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:subshopId. This applies, among other things, to methods for products, categories, SEO data, and similar context-dependent content.
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.| Parameter | Description |
|---|---|
size | Number of returned entries per page (1 to maximum 300) |
pageToken | Optional pagination marker for retrieving the next page |
sort | Result sorting by one or more fields |
filter_... | Filter conditions to restrict the results |
subshopId | Optional parameter to restrict to a specific subshop. Required for some endpoints (e.g. Products, Categories, SEO). |
textSearch | Optional parameter for full-text search. |
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
| Error code | Type | Description |
|---|---|---|
| 400 | InvalidCharacter | Invalid characters in parameter value |
| 400 | InvalidValue | Value less than 1 or greater than 300 |
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
| Error code | Type | Description |
|---|---|---|
| 400 | Token cannot be decoded, or is negative or invalid |
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.
Syntax
Sorting by price ascending
Error codes
| Error code | Type | Description |
|---|---|---|
| 400 | SyntaxError | Missing or multiple colons. |
| 400 | InvalidValue | Invalid sort direction (not asc or desc) |
| 400 | UnknownField | The specified sort field is unknown |
Filters
Filters allow targeted restriction of result lists. Each filter follows the pattern.Syntax
Supported filter operations
| Operation | Meaning |
|---|---|
eq | Equality (=) |
neq | Inequality (!=) |
lt | Less than (<) |
lte | Less than or equal (≤) |
gt | Greater than (>) |
gte | Greater than or equal (≥) |
beginsWith | Begins with |
endsWith | Ends with |
contains | Contains |
notContains | Does not contain |
filter_within | Applies to user-defined fields of type list |
filter_notWithin | Applies to user-defined fields of type list |
Error codes
| Error code | Type | Description |
|---|---|---|
| 400 | UnknownOperation | The filter operation is not known |
| 400 | UnknownField | The specified field is invalid |
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.