API Reference

The Product object

Products are the goods or services your store sells, the items shoppers browse and buy in your storefront. A product groups one or more variants, which determine its price range and availability, and can carry media, belong to collections, and be labeled with tags. This is the public, read-only view of a product: only active products are returned, titles are localized to the requested language, and prices are resolved into the requested display currency. Use it to render storefront listing and product pages.

Attributes

idstring
Unique identifier for the product.
handlestring
URL slug.
titlestring
Localized product name.
featured_mediastringnullable
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 featured_media_type before rendering.
featured_media_typestringnullable
MIME type of featured_media (e.g. image/webp, video/mp4). Null when the product has no media.
featured_imagestringnullable
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, featured_image returns the .png, not the .mp4. Always safe to render directly in an image tag.
priceobjectnullable
Price range in the resolved display currency, or null when the product has no purchasable variant.
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/ v1/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. Note that q only filters, it does not rank: results are not ordered by how closely they match, and the closest match is not surfaced first. Ordering is always controlled by sort and order (default created_at).

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.