Menu

Products API Routes

Customers browse products for their purchase.

A product has variants for different option values. The customer chooses from these variants before adding it to the cart.

These API routes allow customers to browse products.

GET /store/products#

List Products

Retrieve a list of products. The products can be filtered by fields such as id. The products can also be sorted or paginated.

You can retrieve the content of the products translated to a specific locale either by passing the locale query parameter or by setting the x-medusa-locale header to the desired locale code in BCP 47 format. If you don't pass a locale, and your store has a default locale, the default locale will be used.

With localization, the products' content like title and description will be in the specified locale if a translation is available, and fallback to the original content otherwise. Learn more in the Localization section.

Authentication: none.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
qstringOptional
Search term to filter the product's searchable properties.
idstring | string[]Optional
Filter by a product ID.
titlestring | string[]Optional
Filter by product titles.
handlestring | string[]Optional
Filter by product handles.
is_giftcardbooleanOptional
Whether the product is a gift card.
collection_idanyOptional
Filter by a collection's ID to retrieve the products in it.
tag_idstring | string[]Optional
Filter by a tag's ID to retrieve the products in it.
type_idstring | string[]Optional
Filter by a type's ID to retrieve the products in it.
created_atobjectOptional
Filter by the product's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by the product's update date. Accepts the filter operators.
region_idstringOptional
The ID of the region the products are being viewed from. This is required if you're retrieving product variant prices with taxes.
provincestringOptional
The lower-case ISO 3166-2 province code the products are being viewed from. This is useful to narrow down the tax context when calculating product variant prices with taxes.
Example: us-ca
sales_channel_idstring | string[]Optional
The ID of a sales channel to retrieve products in it.
category_idstring | string[]Optional
The ID of a product category to retrieve products in it.
variantsobjectOptional
Filter the products' variants.
country_codestringOptional
The product's country code.
cart_idstringOptional
The product's cart id.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US
external_idstring | string[]Optional
Filter by a product's external ID.
option_value_idstring | string[]Optional
Filter by a product option value ID to retrieve products that have variants with that option value.
option_idstring | string[]Optional
Filter by a product option ID to retrieve products that have variants with that option.

Request examples

Responses

200 OK

limitnumber
The maximum number of items returned.
offsetnumber
The number of items skipped before retrieving the returned items.
countnumber
The total count of items.
estimate_countnumberOptional
The estimated count retrieved from the PostgreSQL query planner, which may be inaccurate.
productsobject[]
The list of products.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /store/products/{id}#

Get a Product

Retrieve a product by its ID. You can expand the product's relations or select the fields that should be returned.

You can retrieve the content of the product translated to a specific locale either by passing the locale query parameter or by setting the x-medusa-locale header to the desired locale code in BCP 47 format. If you don't pass a locale, and your store has a default locale, the default locale will be used.

With localization, the product's content like title and description will be in the specified locale if a translation is available, and fallback to the original content otherwise. Learn more in the Localization section.

Authentication: none.

Path parameters

idstring
The product's ID.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
region_idstringOptional
The ID of the region the product is being viewed from. This is required if you're retrieving product variant prices with taxes.
country_codestringOptional
The country code the product is being viewed from. This is required if you're retrieving product variant prices with taxes.
provincestringOptional
The lower-case ISO 3166-2 province code the product is being viewed from. This is useful to narrow down the tax context when calculating product variant prices with taxes.
Example: us-ca
cart_idstringOptional
The ID of the customer's cart. If set, the cart's region and shipping address's country code and province are used instead of the region_id, country_code, and province properties.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request examples

Responses

200 OK

productobject
The product's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Found a problem with this page?Report Issue
Edited Nov 14·Edit this page