API Reference

The Product object

List active storefront products. Titles are localized from the Accept-Language header and prices are converted to the X-Currency header, both falling back to the store's defaults.

Attributes

idstring
handlestring
URL slug.
titlestring
Localized product name.
featuredMediastringnullable
The product's lead asset: URL of the first media item, of any type (image, video, or 3D model). Null only when the product has no media. Check featuredMediaType before rendering.
featuredMediaTypestringnullable
MIME type of featuredMedia (e.g. image/webp, video/mp4). Null when the product has no media.
featuredImagestringnullable
URL of the first image in the gallery, skipping any non-image media, or null if the product has only videos or 3D models. This is not always the first gallery item. If the gallery opens with a video and then an image, for example a .mp4 at position 1 and a .png at position 2, featuredImage returns the .png, not the .mp4. Always safe to render directly in an image tag.
priceobject
Price range in the resolved display currency. Null on the product when it has no purchasable variant. Every amount below is an object with minor (integer minor units, e.g. cents, for exact math) and formatted (a ready-to-display string in the currency's scale).
availableboolean
True when a live variant is in stock or untracked.
API Reference

List products

Returns active products for the store, paginated with a cursor. Prices use the X-Currency header (default: the store currency) and titles use Accept-Language (default: the store language).

GET/ products

Authorizations

Authorizationstringheaderrequired
The Authorization header expects a Bearer token. Use a publishable API key (prefixed with pk_). It is scoped to a single store, so there is no store ID to pass in requests, and is safe to use from client code: it covers your public storefront data and shopper actions such as cart creation, but never private data or administrative operations. Generate one on the API keys page in your dashboard.

Header Parameters

Accept-Languagestring
Preferred language, narrowed to the store's enabled languages. Falls back to the store's default language.
X-Currencystring
ISO 4217 display currency. Falls back to the store default.

Query Parameters

limitintegerdefault:10
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
Required range: 1 <= x <= 100
starting_afterstring
A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with prod_foo, your subsequent call can include starting_after=prod_foo in order to fetch the next page of the list.
ending_beforestring
A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with prod_bar, your subsequent call can include ending_before=prod_bar in order to fetch the previous page of the list.
sortenum<string>default:created_at
The field used to order the returned products.
orderenum<string>default:desc
The direction in which the returned products are sorted.
collectionstring
Only return products that belong to the collection with this ID.
tagstring
Only return products labeled with this tag name.
qstring
Restricts the results to products matching the query. The name is matched loosely, tolerating typos and partial words, while the handle is matched as a substring. A product is returned if either matches. This filters the result set but does not change its order, which is still controlled by sort and order.

Response

application/json

Returns a paginated list of products matching the supplied filters. The data array holds up to limit product objects ordered by sort and order, has_more is true when further pages remain, and total_count is the number of products across all pages. The array is empty when no products match.

dataobject[]
The page of products, up to limit items, ordered by sort and order. Empty when no products match.
has_moreboolean
True when more products remain beyond this page. Pass the last product's id as starting_after to fetch the next page.
total_countinteger
The total number of products matching the filters across all pages, not just this one.