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.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.
Syntax
Sorting by price ascending
Error codes
Filters
Filters allow targeted restriction of result lists. Each filter follows the pattern.Syntax
Supported filter operations
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.