Request Parameters

🔗 path · unmarked parameters are query params

Example Request

curl 'https://www.locally.com/api/v2/brand/{{COMPANY_ID}}/upc/{{UPC}}/stores' \
--header 'Locally-Api-Token: {{API_TOKEN}}'

const response = await fetch(
  'https://www.locally.com/api/v2/brand/{{COMPANY_ID}}/upc/{{UPC}}/stores',
  {
    headers: {
      'Locally-Api-Token': '{{API_TOKEN}}'
    }
  }
);
const data = await response.json();

import requests

url = "https://www.locally.com/api/v2/brand/{{COMPANY_ID}}/upc/{{UPC}}/stores"
headers = {"Locally-Api-Token": "{{API_TOKEN}}"}

response = requests.get(url, headers=headers)
data = response.json()

upc_code accepts a single 12-digit UPC or multiple codes pipe-delimited (for example 000000000000|000000000001). Each store's in_stock_upcs array lists which of the requested UPCs that store currently has in stock.

Location-aware filtering

Pass the location query param to restrict results to stores near a place. Three formats are accepted:

• city,state — for example location=atlanta,ga
• zip — for example location=60647
• raw comma-separated lat,lng — for example location=37.44,-122.16

Labeled formats such as location=lat:37.44,lng:-122.16 are not supported.

Pagination

Results are paginated with the offset and limit query parameters. By default the endpoint returns all matching stores, paginated 10 per page (limit defaults to 10 and is capped at 100). Use offset to page through the full result set; total reports the full count across every page.

📘

Location filtering and pagination now return results for brands that previously returned no data from these endpoints.

Example Response

{
  "total": 2,
  "offset": 0,
  "results": [
    {
      "name": "ACME Outfitters Chicago",
      "address": "15 ACME Ave",
      "zip": "60647",
      "phone": "(312) 555-0142",
      "lat": 41.8756719,
      "lng": -87.6243469,
      "company_id": 999,
      "is_hold_capable": "Enabled",
      "is_chat_capable": 0,
      "is_charge_capable": "Enabled",
      "is_delivery_capable": "",
      "is_dropship_capable": "",
      "country": "US",
      "city": "Chicago",
      "state": "IL",
      "has_inventory_data": "Live",
      "company_name": "ACME Outfitters",
      "bw_logo": "",
      "logo": "",
      "is_claimed": 1,
      "categories": "Outdoor Gear",
      "rating": "",
      "store_id": "37175",
      "brand_slug": "acme-outfitters",
      "brand_bw_logo": "acme-outfitters-bw_2024-01-15-09-30-00.png",
      "vendor_id": "",
      "in_stock_upcs": [
        {
          "upc": "000000000000",
          "product_id": 1381059,
          "product_url": "https://www.locally.com/sapi/p/999/37175/1381059"
        }
      ],
      "slug": "acme-outfitters-chicago",
      "store_url": "https://www.locally.com/sapi/s/999/37175"
    },
    {
      "name": "ACME Outfitters Evanston",
      "address": "812 Sherman Ave",
      "zip": "60201",
      "phone": "(847) 555-0182",
      "lat": 42.0450722,
      "lng": -87.6876969,
      "company_id": 999,
      "is_hold_capable": "Enabled",
      "is_chat_capable": 0,
      "is_charge_capable": "",
      "is_delivery_capable": "",
      "is_dropship_capable": "",
      "country": "US",
      "city": "Evanston",
      "state": "IL",
      "has_inventory_data": "Live",
      "company_name": "ACME Outfitters",
      "bw_logo": "",
      "logo": "",
      "is_claimed": 1,
      "categories": "Outdoor Gear",
      "rating": "",
      "store_id": "37176",
      "brand_slug": "acme-outfitters",
      "brand_bw_logo": "acme-outfitters-bw_2024-01-15-09-30-00.png",
      "vendor_id": "",
      "in_stock_upcs": [
        {
          "upc": "000000000000",
          "product_id": 1381059,
          "product_url": "https://www.locally.com/sapi/p/999/37176/1381059"
        }
      ],
      "slug": "acme-outfitters-evanston",
      "store_url": "https://www.locally.com/sapi/s/999/37176"
    }
  ]
}

Response Explanation

• total — Count of all matching stores across every page — results is just the current window. Page with the offset and limit query parameters (10 per page by default, limit capped at 100).
• results[].store_id — Locally's canonical ID for the physical store, returned as a string. The same store ID is used across Locally APIs (it matches data.markers[].id in the Headless API).
• results[].company_id — Always the brand company ID from the request path — every store repeats it. The retailer company operating the store is named by company_name.
• results[].is_hold_capable — Capability flags (is_hold_capable, is_charge_capable, is_delivery_capable, is_dropship_capable) are "Enabled" or "" strings, not booleans — reserve-for-pickup, pay-online-for-pickup, local delivery, and ship-to-store respectively. is_chat_capable alone is an integer.
• results[].has_inventory_data — "Live" when the store shares live inventory data with Locally (and it isn't muted); empty string otherwise — never a boolean.
• results[].is_claimed — Integer flag: 1 when the retailer has claimed and manages this store's Locally profile, 0 for unclaimed listings.
• results[].vendor_id — The brand's own identifier for this store, taken from the brand's dealer records; empty string when the brand hasn't assigned one.
• results[].in_stock_upcs[] — Stores without at least one matching UPC in stock (quantity above zero) are omitted from results entirely; each entry pairs an in-stock upc with its Locally product_id.
• results[].in_stock_upcs[].product_url — Tracked locally.com redirect (/sapi/p/…) that forwards to the product's page scoped to this store — same mechanism as store_url.
• results[].store_url — Tracked locally.com redirect (/sapi/s/…) that forwards to the store's Locally page with UTM tagging applied; slug is that page's URL slug.