Start conversion

Request Parameters

🏷️ header · unmarked parameters are query params

Parameter	Type	Required	Description
`Locally-Api-Token` 🏷️	string	Yes	Locally API token must be passed in the header to authenticate the API consumer.
`company_id`	integer	Yes	The ID of the company that owns the store.
`style`	string	No	The brand's style identifier as stored in Locally (typically the `style_number` from the brand's product feed). Resolves to a product within the `company_id` scope — for cross-brand lookups, the company_id must belong to the product owner. Use `upc` if the owner is unknown. Default value is null.
`product_id`	integer	No	The ID of the product.
`upc`	string	No	The UPC of the product.

Example Request

curl --get 'https://www.locally.com/headless/api/1.0/conversion/start' \
--header 'Locally-Api-Token: {{API_TOKEN}}' \
--data-urlencode 'company_id={{COMPANY_ID}}' \
--data-urlencode 'upc={{UPC}}'

const response = await fetch(
  'https://www.locally.com/headless/api/1.0/conversion/start?company_id={{COMPANY_ID}}&upc={{UPC}}',
  {
    headers: {
      'Locally-Api-Token': '{{API_TOKEN}}'
    }
  }
);
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    'https://www.locally.com/headless/api/1.0/conversion/start',
    params={
        'company_id': '{{COMPANY_ID}}',
        'upc': '{{UPC}}'
    },
    headers={'Locally-Api-Token': '{{API_TOKEN}}'}
)
print(response.json())

company_id is required. Identify the product with either upc or style — if only style is provided, the upc returned in the response is the most common locally available variant of the product. product_id is optional and may be passed alongside either identifier.

Example Response

{
  "success": true,
  "data": {
    "style": "999",
    "company_id": 999,
    "upc": "000000000000",
    "company_name": "ACME Outfitters",
    "initial_store_id": 37175,
    "company_logo": "image.jpg",
    "user_geo": {
      "lat": "41.8756719",
      "lng": "-87.6243469",
      "city_label": "Chicago, IL",
      "country": "US",
      "distance_unit": "mi"
    }
  }
}

Response Explanation

success — Boolean outcome of the call. When false, the response also carries a top-level error_code and explanatory msg — always check success, not just the HTTP status.
data.upc — The validated UPC — may differ from the one you sent: out-of-stock UPCs are swapped for the closest in-stock variant, and style-only requests return the most common locally available variant.
data.style — The resolved product's style_number as stored in Locally — the canonical value to reuse in later style queries.
data.company_name — Name of the brand that owns the resolved product. For cross-brand lookups this is the product owner, not the requesting partner.
data.initial_store_id — Present when the conversion is tied to a specific store (a store_id was passed with the request); the ID matches markers[].id in Get inventory data.
data.company_logo — Filename of the brand's black-and-white logo variant (bw_logo), not its primary logo; empty string when the brand has not uploaded one.
data.user_geo — The shopper's session location — geolocated automatically on first request, persisted on the session, changeable via Switch session location. Its lat/lng seed the map center for inventory calls.
data.user_geo.distance_unit — mi for shoppers located in the US or GB, km everywhere else, derived from user_geo.country. Pass it as map_distance_unit in follow-up inventory calls.