Base URL
All REST API endpoints are available under the following path:Access & permissions
Access to the REST API requires a user account that is managed in the admin interface of your shop. The admin interface is divided into so-called services (e.g. Products, Categories, Sitemaps, SEO URLs, Data Feeds, Statistics, etc.). Permissions can be assigned in the admin area for each service — for example Read, Edit, Create, Delete, or Publish. These permissions also apply to the REST API and determine which endpoints you can access and which HTTP methods (GET, POST, PUT, DELETE) you may use. A user with only read permissions for the “Products” service, for example, can only retrieve products via API (GET) but cannot edit them (PUT/POST/DELETE). You can view your assigned permissions in the admin interface under the following path:- URL parameter
subshopId: takes precedence as soon as it is set. - Header
X-SubshopId: applies if the URL parameter is missing or empty. - Fallback: the first subshop configured in the shop.
Authentication
A login is required to access protected REST API endpoints. Authentication is performed either via username/password or via API key. Successfully authenticated requests receive an access token that can be used to call additional endpoints. A refresh token is also provided. The login is performed via the following endpoint:X-Authorization. The value consists of the word Bearer followed by the token:
Filtering, sorting & pagination
Many REST endpoints return lists of data — such as products, orders, or categories. To work efficiently with this data, the API provides various parameters with which results can be narrowed down, sorted, and retrieved page by page. These mechanisms are particularly important for large datasets in order to enable performant and targeted queries. An API call can contain various parameters. A typical GET request might look like this:nextPageToken, the total counter (totalCount), and the endReached flag, which indicates whether further pages are available:
Supported parameters
The following URL parameters are supported to control result lists. The notation is case-sensitive.Count & pagination
The number of data records returned per API request can be controlled via thesize parameter. The value must be an integer between 1 and 300.
If no size parameter is passed, the API uses a default value of 100 entries per page.
If the requested data set is larger than the defined size value (or larger than the default value), the API returns a nextPageToken in the response, with which additional pages can be loaded. The pagination mechanism allows large amounts of data to be retrieved step by step.
Example
Example of a manually set page size.Error codes
The
pageToken parameter enables access to subsequent pages of result lists. The value is automatically returned by the API as nextPageToken and must be passed in base64-url encoded form. If the encoding is faulty or invalid, an error message is returned.
Example
Error codes
Special case: products
Loading products via pageToken can be slow if there are more than 10,000 products in the shop. In addition to the pageToken, asearchAfterToken is also returned for products.
Instead of pageToken, searchAfterToken can be specified in the URL to load products efficiently even with many results.
Example
Sorting
Results are sorted via thesort parameter. It expects a field name and a sort direction (asc for ascending, desc for descending), separated by a colon, as the value.
To combine multiple sort criteria, multiple sort parameters must be passed. Each parameter stands for a single criterion. A comma-separated list within a parameter is not supported.
If no sort parameter is specified, sorting is by internal ID by default. An exception is the product list with the inCategory filter: there, without an explicit sort parameter, the category order maintained in the shop applies – see Products – ordering with inCategory.
Syntax
Sorting by price ascending
Error codes
Filters
Filters allow targeted restriction of result lists. Each filter follows the pattern.Syntax
Supported filter operations
The operations
within, notWithin, and empty are only available for the product list (GET products and the endpoints derived from it), because fields of type list and map only occur there. For all other list endpoints, they result in the error UnknownOperation.Permitted operations per field type
Not every filter operation is permitted on every field. Which operations are valid depends on the data type of the field. So the statement “All product data fields are filterable” does not mean that every field can be combined with every operation. An invalid combination is not ignored but rejected with status code400 Bad Request and type illegalOperation.
Examples:
custom. prefix:
There are no
like or in operations. Instead, use contains (substring search) or multiple filters on the same field, which the API combines with OR:Error codes
Full-text search
Most endpoints support a full-text search via the optional URL parametertextSearch. This allows results to be filtered by a search term without having to specify explicit filter fields. The parameter can be specified multiple times — multiple values are combined with OR. The search is case-sensitive.
Syntax
Example (single search term)
Example (multiple search terms)
Bulk endpoints
For mass operations, the API provides bulk endpoints. They transfer many records in a single request and are significantly more efficient than individual calls.Shared limit: 1000 entries per request
If the limit is exceeded, the API responds with400 Bad Request. In this case, no entries are processed and the request is rejected completely. Therefore, split larger amounts of data client-side into blocks of at most 1,000 entries.
All writing bulk endpoints use POST, even when they update existing records. A
PUT to a bulk path is not answered.