Skip to main content
API docs by Redocly

Customer API (experimental) (v1)

Download OpenAPI specification:Download

Warning: This API version is in an experimental state and should not be used for production.
We recommend that all integrations use Customer API v0.

Categories

List categories

Retrieves all top-level categories.

Important: This method will only return results if you performed a category import. Categories contained in a product import will not be returned by this method.

path Parameters
shop_id
required
string

The identifier of the shop.

query Parameters
locale
required
string(^[A-Za-z]{2}$)|(^[a-z]{2}[-_]{1}[A-Za-z]{2}$...

The locale for the products catalog. It should be in format en-US or only en.

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ]
}

List subcategories

Retrieves all subcategories with the given parent category.

path Parameters
parent
required
string

The path of the parent category, connected by the defined path separator for which the list of subcategories should be requested. You can get the path separator with the 'List categories' method, in the 'path_separator' field.

shop_id
required
string

The identifier of the shop.

query Parameters
locale
required
string(^[A-Za-z]{2}$)|(^[a-z]{2}[-_]{1}[A-Za-z]{2}$...

The locale for the products catalog. It should be in format en-US or only en.

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ]
}

Prices

Get prices

Retrieves the price information of a list of products.

path Parameters
shop_id
required
string

The identifier of the shop.

query Parameters
product_id
required
Array of strings

The identifier of the product defined during the master data import phase.

pricebook_id
required
string

The identifier of the price book.

Responses

Response samples

Content type
application/json
{
  • "pricebook_id": "default",
  • "currency": "USD",
  • "traits": [
    ],
  • "elements": [
    ]
}

Products

List products

Retrieves a list of products for the given locale.

path Parameters
shop_id
required
string

The identifier of the shop.

query Parameters
locale
required
string(^[A-Za-z]{2}$)|(^[a-z]{2}[-_]{1}[A-Za-z]{2}$...

The locale for the products catalog. It should be in format en-US or only en.

q
string [ 1 .. 100 ] characters

A search term to restrict products. The search considers the following product properties: title, short_description, description, color and size.

Note: You can configure attributes to be searchable during the product import. See the documentation and the tutorial for more details.

include_variations
boolean
Default: false

Flag to return the siblings of a product.

filter[<field>]
Array of strings

A field=value pair defining the filter applied to the response. The field names you can use in the filter are available in the facets property in the response of this method. Boolean filters like is_preorder are not part of the facet properties in the response of this method.

Note: Using this parameter several times on one field in one query creates an OR operation. The AND operation on the same field is not possible in one query.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "elements": [
    ],
  • "facets": [
    ]
}

Get product details

Returns product detail information including product variant specific information such as prices and quantities.

path Parameters
type
required
string

The type of the external ID. It is the identification system used in your setup. Typical systems are EAN, SKU, GTIN, etc.

Note: To use the NewStore ID of the product (product_id) instead of its external identifier, omit this parameter and only use the id parameter.

id
required
string

The product identifier, either the internal product id (product_id), or an external id such as an SKU number. Both identifiers are provided during the master data import phase:

  • To use an external product ID such as an SKU number, provide the type parameter.
  • To use the internal product ID (product_id), omit the type parameter.

Important: When retrieving a product whose id contains special characters (reserved, unreserved, and escaped characters based on the RFC guidelines, the value of the product ID must be encoded. For more information, see Section 2.1 in the RFC guidelines.

shop_id
required
string

The identifier of the shop.

query Parameters
locale
required
string(^[A-Za-z]{2}$)|(^[a-z]{2}[-_]{1}[A-Za-z]{2}$...

The locale for the products catalog. It should be in format en-US or only en.

include_variations
boolean

Whether to include/populate the product's variations field or not. Variations are included by default.

Responses

Response samples

Content type
application/json
{
  • "product_id": "1200001",
  • "title": "Black Sweater",
  • "short_description": "Perfect for the winter.",
  • "description": "Perfect for the winter. Very cozy and comfortable. A must-have for cold days!",
  • "is_available": true,
  • "serialized_inventory": false,
  • "variable_pricing": false,
  • "inventory_tracked": true,
  • "online_from": "2018-05-17T07:00:00Z",
  • "online_to": "2020-12-31T13:32:16Z",
  • "effective_price": {
    },
  • "images": [],
  • "extended_attributes": [
    ],
  • "variations": [
    ]
}