Gambio REST API v3
Download OpenAPI specification:Download
This documentation reference will provide you analytic guides on how the API works, which resources are available and the proper way to request them efficiently.
We follow a strict deprecation period for breaking changes to our endpoints, so that appropriate time is given to users to update their implementations accordingly.
Thank you for using the Gambio GX3 API!
basicAuth
Every request of the API needs to be authenticated otherwise a 401 Unauthorized response will be returned. The client will need to use the administrator user's credentials through the HTTP Basic Auth header. You can read more about the HTTP authentication header here.
Security Scheme Type | HTTP |
---|---|
HTTP Authorization Scheme | basic |
bearerAuth
The API also supports the usage of JSON web tokens, which can be generated on the Customers
→ Roles and Permissions
page of the Gambio Admin.
Security Scheme Type | HTTP |
---|---|
HTTP Authorization Scheme | bearer |
Bearer format | "JWT" |
Since GX v4.1.1.0 there is a new REST API version available. Similar to the existing v2 API, the new endpoints can be
called via https://www.your-shop-domain.de/path-to-shop/api.php/v3
.
Every error response will contain a valid HTTP Status Code. The response body itself will provided error information
based on the current mode of the application (develop or production). If there is a .dev-environment
file
exists in the base directory of the shop, the develop mode is active and the response body will contain not only
a error message itself, but also a stack trace of the error.
HATEOAS stands for Hypermedia as the Engine of Application State and describes the use of links which point to external resources or actions that are related to a specific resource. The API will provide links inside the response body, if available.
Web caching is not currently supported by any resource but is planned for a future release of the API.
Caching support will be stated in each section explicitly and the API will return an ETag
or Last-Modified
along with an Expires
headers, containing information about the provided response.
Postman is a third party graphical user interface to easily communicate with RESTful APIs. It enables you to directly import the swagger-defined GX4 API v3 specification, which we provide for you (link is at the top of this page).
Importing the specification into Postman automatically provides you with all API-Endpoints available and additionally, most variables are already declared, allowing you to quickly explore the GX4 RESTful API v3.
Defining your API location
Once you downloaded the swagger.json
, it is advised to manually re-define your API's location according to your
hosting. To do so, open the previously downloaded swagger.json
with a text-editor of your choice, and you will
see a JSON document defining all of the API's available communication.
To quickly customize the specification to your needs, change the following values at the beginning of the document
by replacing the string https://www.gambio-shop.de/shop1
according to your setup:
{
//...
"servers": [
{
"url": "https://www.gambio-shop.de/shop1"
}
],
//...
}
Importing into Postman
Once the above stated changes were manually applied, you may proceed to open Postman. Navigate to File -> Import...
in Postman's top menu bar. Once clicked, a dialog will open asking you to specify what to import. Either drag the
edited swagger.json
into the dialog, or click the Choose Files
button and point Postman to the document.
Once the API's swagger.json
was imported into postman, you will have a Postman collection called
Gambio REST API v3
available, allowing you to quickly dive into the Gambio GX4 RESTful API v3.
There are some optional query parameters, that can be used for endpoints that generally return a collection of documents.
Note: The attributes that can be used for the following actions, are the same like the attributes of the
documents in the HTTP response. A dot .
can be used to address attributes in on a deeper level.
Filtering
You can filter the documents of a collection by using the query parameter filter
like:
- GET
/api.php/v3/withdrawals?filter[customer.firstName]=John
will return all withdrawals of customers with first nameJohn
. - GET
/api.php/v3/withdrawals?filter[customer.firstName]=J*
will return all withdrawals of customers whose first name begins withJ
. - GET
/api.php/v3/withdrawals?filter[customer.firstName]=J*&filter[id]=*1
will return all withdrawals of customers whose first name begins withJ
and withdrawal IDs will end with an one. - GET
/api.php/v3/withdrawals?filter[id]=gt|42
will return all withdrawals with an ID that is greater than42
. - GET
/api.php/v3/withdrawals?filter[id]=gte|42
will return all withdrawals with an ID that is equals or greater than42
. - GET
/api.php/v3/withdrawals?filter[id]=lt|42
will return all withdrawals with an ID that is less than42
. - GET
/api.php/v3/withdrawals?filter[id]=lte|42
will return all withdrawals with an ID that is equals or less than42
. - GET
/api.php/v3/withdrawals?filter[id]=neq|42
will return all withdrawals with an ID that is not equal to42
. - GET
/api.php/v3/withdrawals?filter[date]=eq|2020-04-05
or GET/api.php/v3/customers?filter[date]=2020-04-05
will return all withdrawals with a withdrawal date of2020-04-05
. - GET
/api.php/v3/withdrawals?filter[createdByAdmin]=1
will return all withdrawals that have been created by an admin.
Sorting
The sorting order can be modified by using the query parameter sort
. This parameter always expects a comma separated
list of the document attributes. A +
(ascending) or -
(descending) at the beginning of a attribute can be used
modify the order. If no specific order is provided than a ascending order should be used.
Example: /api.php/v3/withdrawals?sort=-customer.firstName,+customer.lastName
Pagination
The query parameters page
and per-page
can be used for pagination.
Example: /api.php/v3/withdrawals?per-page=5&page=3
Trim documents
Endpoint providing a collection of specific documents (like /api.php/v3/withdrawals
), offer the possibility to reduce
the amount of information inside the provided documents. By using the query parameter fields
you are able to provided
a comma separated list of document attributes, which describe the structure of the returned documents.
Example: /api.php/v3/withdrawals?fields=id,customer.firstName,customer.lastName
The following endpoints can be used to manage the image lists of this shop.
The shown paths of the API endpoints are relative paths and references the
<shop-root>/images/product_images/original_images
directory. E.g. the image path tshirds/red.jpg
references the
<shop-root>/images/product_images/original_images/tshirds/red.jpg
file.
Get all available image lists
Returns a collection of image lists.
Authorizations:
query Parameters
fields | string Example: fields=id,customer,orders.id Optional query parameter for trimming the provided documents. Parameter represents a comma separated list of attributes. |
filter | object Example: filter[customer.gender]=o&filter[customer.firstName]=max&filter[customer.lastName]=muster*&filter[customer.age]=gte|18&filter[date]=lt|2020-02-01 Optional query parameter for filtering. Parameter represents an object, which is used to filter the provided documents. |
page | integer >= 1 Default: 1 Example: page=2 Optional query parameter to define current page. |
per-page | integer [ 1 .. 100 ] Default: 25 Example: per-page=25 Optional query parameter to limiting the provided documents. |
sort | string Example: sort=-creationDate,+customer.firstName Optional query parameter for sorting. Parameter represents a comma separated list of attributes. |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
Array of objects (imageLists-imageLists) | |
object (imageLists-collectionMetaData) |
Response samples
- 200
{- "data": [
- {
- "id": "1",
- "name": "image lists #1",
- "images": [
- {
- "relativePath": "subdirectory/image.jpg",
- "titles": [
- {
- "languageCode": "en",
- "text": "text for image"
}
], - "altTitles": [
- {
- "languageCode": "en",
- "text": "text for image"
}
], - "sortOrder": "1"
}
]
}
], - "_meta": {
- "totalItems": 42,
- "perPage": 25,
- "page": 2,
- "links": {
}
}
}
Create a new image list
Creates a single or multiple new image lists based on the request body.
Authorizations:
Request Body schema: application/json
Image lists data for creation.
name required | string non-empty |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
data | Array of integers <int32> (imagelists-imagelistIds) |
object (imageLists-creationMetaData) |
Request samples
- Payload
[- {
- "name": "image lists #1"
}
]
Response samples
- 201
- 400
- 409
- 422
{- "data": [
- 1
],
}
Update an existing image list
Updates a single or multiple image lists based on the request body.
Authorizations:
Request Body schema: application/json
Image list data for update.
id required | integer <int32> >= 1 |
name required | string non-empty |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Request samples
- Payload
[- {
- "id": 1,
- "name": "image lists #1"
}
]
Response samples
- 400
- 409
- 422
{- "errors": [
- [
- "Attribute \"attribute.subAttribute\" is missing."
]
], - "_meta": { }
}
Get a specific image list
Returns a single image list based in the provided ID.
Authorizations:
path Parameters
imageListId required | integer >= 1 Example: 1 ID of an existing image list. |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
object (imageLists-imageList) | |
object (imageLists-documentMetaData) |
Response samples
- 200
{- "data": {
- "id": "1",
- "name": "image lists #1",
- "images": [
- {
- "relativePath": "subdirectory/image.jpg",
- "titles": [
- {
- "languageCode": "en",
- "text": "text for image"
}
], - "altTitles": [
- {
- "languageCode": "en",
- "text": "text for image"
}
], - "sortOrder": "1"
}
]
}, - "_meta": {
- "links": {
}
}
}
Delete multiple image lists
Deletes one or more image lists based on the provided IDs.
Authorizations:
path Parameters
imageListIds required | string Example: 1,2,3 Image list IDs represented as a comma separated list. |
Responses
Response samples
- 409
{- "errors": [
- [
- "<Sample-Business-Entity> already exists."
]
], - "_meta": { }
}
Get all available image list images
Returns a collection of image lists.
Authorizations:
path Parameters
imageListId required | integer >= 1 Example: 1 ID of an existing image list. |
query Parameters
fields | string Example: fields=id,customer,orders.id Optional query parameter for trimming the provided documents. Parameter represents a comma separated list of attributes. |
filter | object Example: filter[customer.gender]=o&filter[customer.firstName]=max&filter[customer.lastName]=muster*&filter[customer.age]=gte|18&filter[date]=lt|2020-02-01 Optional query parameter for filtering. Parameter represents an object, which is used to filter the provided documents. |
page | integer >= 1 Default: 1 Example: page=2 Optional query parameter to define current page. |
per-page | integer [ 1 .. 100 ] Default: 25 Example: per-page=25 Optional query parameter to limiting the provided documents. |
sort | string Example: sort=-creationDate,+customer.firstName Optional query parameter for sorting. Parameter represents a comma separated list of attributes. |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
Array of objects (imageLists-imageListImages) |
Response samples
- 200
{- "data": [
- {
- "relativePath": "subdirectory/image.jpg",
- "titles": [
- {
- "languageCode": "en",
- "text": "text for image"
}
], - "altTitles": [
- {
- "languageCode": "en",
- "text": "text for image"
}
], - "sortOrder": "1"
}
]
}
Add an already uploaded image to an existing image list
Adds a single or multiple existing images to an image lists based on the request body.
Authorizations:
path Parameters
imageListId required | integer >= 1 Example: 1 ID of an existing image list. |
Request Body schema: application/json
Image list images data for update.
relativePath required | string non-empty |
sortOrder | integer <int32> >= 0 |
required | Array of objects |
required | Array of objects |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Request samples
- Payload
[- {
- "relativePath": "subdirectory/image.jpg",
- "sortOrder": 1,
- "titles": [
- {
- "languageCode": "en",
- "text": "text for image"
}
], - "altTitles": [
- {
- "languageCode": "en",
- "text": "text for image"
}
]
}
]
Response samples
- 400
- 409
- 422
{- "errors": [
- [
- "Attribute \"attribute.subAttribute\" is missing."
]
], - "_meta": { }
}
Update sort order of an existing image list images
Updates the sort order(s) of a single or multiple image list images based on the request body.
Authorizations:
path Parameters
imageListId required | integer >= 1 Example: 1 ID of an existing image list. |
Request Body schema: application/json
Image list images data to update sort orders.
relativePath required | string non-empty |
sortOrder required | integer <int32> >= 0 |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Request samples
- Payload
[- {
- "relativePath": "subdirectory/image.jpg",
- "sortOrder": "1"
}
]
Response samples
- 400
- 409
- 422
{- "errors": [
- [
- "Attribute \"attribute.subAttribute\" is missing."
]
], - "_meta": { }
}
Update an existing image list image
Updates a single or multiple image list images based on the request body.
Authorizations:
path Parameters
imageListId required | integer >= 1 Example: 1 ID of an existing image list. |
Request Body schema: application/json
Image list images data for update.
relativePath required | string non-empty |
sortOrder | integer <int32> >= 0 |
required | Array of objects |
required | Array of objects |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Request samples
- Payload
[- {
- "relativePath": "subdirectory/image.jpg",
- "sortOrder": 1,
- "titles": [
- {
- "languageCode": "en",
- "text": "text for image"
}
], - "altTitles": [
- {
- "languageCode": "en",
- "text": "text for image"
}
]
}
]
Response samples
- 400
- 409
- 422
{- "errors": [
- [
- "Attribute \"attribute.subAttribute\" is missing."
]
], - "_meta": { }
}
Delete single image list image
Deletes a single image list image based on the provided image path.
Authorizations:
path Parameters
imageListId required | integer >= 1 Example: 1 ID of an existing image list. |
relativePath required | string Example: subdirectory/image.jpg Relative path of an image list image. |
Responses
Upload and add an image to an existing image list
Adds a new image to an existing image list.
Authorizations:
path Parameters
imageListId required | integer >= 1 Example: 1 ID of an existing image list. |
relativePath required | string Example: subdirectory/image.jpg Relative path of an image list image. |
Request Body schema: image/pngimage/pngimage/gifimage/jpg
Image list image for addition.
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
data | Array of strings (imagelists-imagelistPaths) |
Response samples
- 201
- 400
- 409
- 422
{- "data": [
- "subdirectory/image.jpg"
]
}
The following endpoints can be used to manage the options of this shop.
Currently, the shop does no support all fields inside the documents completly. The following fields aren't
supported yet: details.description
, values.details.description
, values.weightType
, values.priceType
,
values.stock
, values.stockCentrallyManaged
Get all available options
Returns a collection of options.
Authorizations:
query Parameters
fields | string Example: fields=id,customer,orders.id Optional query parameter for trimming the provided documents. Parameter represents a comma separated list of attributes. |
filter | object Example: filter[customer.gender]=o&filter[customer.firstName]=max&filter[customer.lastName]=muster*&filter[customer.age]=gte|18&filter[date]=lt|2020-02-01 Optional query parameter for filtering. Parameter represents an object, which is used to filter the provided documents. |
page | integer >= 1 Default: 1 Example: page=2 Optional query parameter to define current page. |
per-page | integer [ 1 .. 100 ] Default: 25 Example: per-page=25 Optional query parameter to limiting the provided documents. |
sort | string Example: sort=-creationDate,+customer.firstName Optional query parameter for sorting. Parameter represents a comma separated list of attributes. |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
Array of objects (options-options) | |
object (options-collectionMetaData) |
Response samples
- 200
{- "data": [
- {
- "id": "1",
- "type": "Dropdown",
- "sortOrder": 1,
- "details": [
- {
- "languageCode": "en",
- "label": "Size",
- "adminLabel": "Size (T-Shirts)",
- "description": "An additional description ..."
}
], - "values": [
- {
- "id": "1",
- "sortOrder": 1,
- "details": [
- {
- "languageCode": "en",
- "label": "XXL",
- "description": "A sample description"
}
], - "image": "xxl.jpg",
- "modelNumber": "xxl",
- "weight": 13.37,
- "price": 13.37,
- "stockType": "only-positive",
- "stock": 13.37,
- "stockCentrallyManaged": true
}
]
}
], - "_meta": {
- "totalItems": 42,
- "perPage": 25,
- "page": 2,
- "links": {
}
}
}
Create a new option
Creates a single or multiple new option based on the request body.
Authorizations:
Request Body schema: application/json
Option data for creation.
type required | string Enum: "Dropdown" "Image" "Radio" "Text" "BoxedText" Determines how this option will be shown on the product details page. For more information take a look into the developers' documentation of the option domain. |
sortOrder required | integer <int32> >= 0 Default: 1 |
required | Array of objects |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
data | Array of integers <int32> (options-optionIds) |
object (options-creationMetaData) |
Request samples
- Payload
[- {
- "type": "Dropdown",
- "sortOrder": 1,
- "details": [
- {
- "languageCode": "en",
- "label": "Size",
- "adminLabel": "Size (T-Shirts)",
- "description": "An additional description ..."
}
]
}
]
Response samples
- 201
- 400
- 409
- 422
{- "data": [
- "1"
],
}
Update the sort order of an existing option
Updates the sort order of a single or multiple options based on the request body.
Authorizations:
Request Body schema: application/json
Options data for updating sort orders.
id required | integer <int32> >= 1 |
sortOrder required | integer <int32> >= 0 |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Request samples
- Payload
[- {
- "id": "1",
- "sortOrder": "1"
}
]
Response samples
- 400
- 409
- 422
{- "errors": [
- [
- "Attribute \"attribute.subAttribute\" is missing."
]
], - "_meta": { }
}
Update an existing option
Updates a single or multiple options based on the request body.
NOTE: all the languages, in the "details" array, are required.
Authorizations:
Request Body schema: application/json
Options data for update.
id required | integer <int32> >= 1 |
type required | string Enum: "Dropdown" "Image" "Radio" "Text" "BoxedText" Determines how this option will be shown on the product details page. For more information take a look into the developers' documentation of the option domain. |
sortOrder required | integer <int32> >= 0 Default: 1 |
required | Array of objects |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Request samples
- Payload
[- {
- "id": 1,
- "type": "Dropdown",
- "sortOrder": 1,
- "details": [
- {
- "languageCode": "en",
- "label": "Size",
- "adminLabel": "Size (T-Shirts)",
- "description": "An additional description ..."
}
]
}
]
Response samples
- 400
- 409
- 422
{- "errors": [
- [
- "Attribute \"attribute.subAttribute\" is missing."
]
], - "_meta": { }
}
Get a specific option
Returns a single option based in the provided ID.
Authorizations:
path Parameters
optionId required | integer >= 1 Example: 1 ID of an existing option. |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
object (options-option) | |
object (options-documentMetaData) |
Response samples
- 200
{- "data": {
- "id": "1",
- "type": "Dropdown",
- "sortOrder": 1,
- "details": [
- {
- "languageCode": "en",
- "label": "Size",
- "adminLabel": "Size (T-Shirts)",
- "description": "An additional description ..."
}
], - "values": [
- {
- "id": "1",
- "sortOrder": 1,
- "details": [
- {
- "languageCode": "en",
- "label": "XXL",
- "description": "A sample description"
}
], - "image": "xxl.jpg",
- "modelNumber": "xxl",
- "weight": 13.37,
- "price": 13.37,
- "stockType": "only-positive",
- "stock": 13.37,
- "stockCentrallyManaged": true
}
]
}, - "_meta": {
- "links": {
}
}
}
Delete multiple options
Deletes one or more options based on the provided IDs.
Authorizations:
path Parameters
optionIds required | string Example: 1,2,3 Option IDs represented as a comma separated list. |
Responses
Response samples
- 409
{- "errors": [
- [
- "<Sample-Business-Entity> already exists."
]
], - "_meta": { }
}
Get all available option values for a given option
Returns a collection of option values for a given option.
Authorizations:
path Parameters
optionId required | integer >= 1 Example: 1 ID of an existing option. |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
Array of objects (options-option-values) | |
object (options-collectionMetaData) |
Response samples
- 200
{- "data": [
- {
- "id": "1",
- "sortOrder": 1,
- "details": [
- {
- "languageCode": "en",
- "label": "XXL",
- "description": "A sample description"
}
], - "image": "xxl.jpg",
- "modelNumber": "xxl",
- "weight": 13.37,
- "price": 13.37,
- "stockType": "only-positive",
- "stock": 13.37,
- "stockCentrallyManaged": true
}
], - "_meta": {
- "totalItems": 42,
- "perPage": 25,
- "page": 2,
- "links": {
}
}
}
Create a new option value
Creates a single or multiple new option values based on the request body.
Authorizations:
path Parameters
optionId required | integer >= 1 Example: 1 ID of an existing option. |
Request Body schema: application/json
Option values data for creation.
sortOrder required | integer <int32> >= 0 Default: 1 |
required | Array of objects |
image required | string |
modelNumber required | string |
weight required | number <double> |
price required | number <double> |
stockType required | string non-empty Enum: "only-positive" "all-numbers" "not-managed" Determines the behavior for the stock management. |
stock required | number <double> |
stockCentrallyManaged required | boolean |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
data | Array of integers <int32> (options-optionValueIds) |
object (options-creationMetaData) |
Request samples
- Payload
[- {
- "sortOrder": 1,
- "details": [
- {
- "languageCode": "en",
- "label": "XXL",
- "description": "A sample description"
}
], - "image": "xxl.jpg",
- "modelNumber": "xxl",
- "weight": 13.37,
- "price": 13.37,
- "stockType": "only-positive",
- "stock": 13.37,
- "stockCentrallyManaged": true
}
]
Response samples
- 201
- 400
- 409
- 422
{- "data": [
- "1"
],
}
Update an existing option value
Updates a single or multiple option values based on the request body.
Authorizations:
path Parameters
optionId required | integer >= 1 Example: 1 ID of an existing option. |
Request Body schema: application/json
Option values data for update.
id required | integer <int32> >= 1 |
sortOrder required | integer <int32> >= 0 Default: 1 |
required | Array of objects |
image required | string |
modelNumber required | string |
weight required | number <double> |
price required | number <double> |
stockType required | string non-empty Enum: "only-positive" "all-numbers" "not-managed" Determines the behavior for the stock management. |
stock required | number <double> |
stockCentrallyManaged required | boolean |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Request samples
- Payload
[- {
- "id": "1",
- "sortOrder": 1,
- "details": [
- {
- "languageCode": "en",
- "label": "XXL",
- "description": "A sample description"
}
], - "image": "xxl.jpg",
- "modelNumber": "xxl",
- "weight": 13.37,
- "price": 13.37,
- "stockType": "only-positive",
- "stock": 13.37,
- "stockCentrallyManaged": true
}
]
Response samples
- 400
- 409
- 422
{- "errors": [
- [
- "Attribute \"attribute.subAttribute\" is missing."
]
], - "_meta": { }
}
Update sort order of an existing option value
Updates the sort order(s) of a single or multiple option values based on the request body.
Authorizations:
path Parameters
optionId required | integer >= 1 Example: 1 ID of an existing option. |
Request Body schema: application/json
Option values data to update sort orders.
id required | integer <int32> >= 1 |
sortOrder required | integer <int32> >= 0 |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Request samples
- Payload
[- {
- "id": "1",
- "sortOrder": "1"
}
]
Response samples
- 400
- 409
- 422
{- "errors": [
- [
- "Attribute \"attribute.subAttribute\" is missing."
]
], - "_meta": { }
}
Delete multiple option values
Deletes one or more option values based on the provided IDs.
Authorizations:
path Parameters
optionId required | integer >= 1 Example: 1 ID of an existing option. |
optionValueIds required | string Example: 1,2,3 Option value IDs represented as a comma separated list. |
Responses
Response samples
- 409
{- "errors": [
- [
- "<Sample-Business-Entity> already exists."
]
], - "_meta": { }
}
Upload and add an image to an existing option value
Adds a new image to an existing option value.
Authorizations:
path Parameters
optionId required | integer >= 1 Example: 1 ID of an existing option. |
optionValueId required | integer >= 1 Example: 1 ID of an existing option value. |
relativePath required | string Example: subdirectory/image.jpg Relative path of the option value image. |
Request Body schema: image/pngimage/pngimage/gifimage/jpg
option value image for addition.
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response samples
- 400
- 409
- 422
{- "errors": [
- [
- "Attribute \"attribute.subAttribute\" is missing."
]
], - "_meta": { }
}
Get all available parcel services
Returns a collection of parcel services.
Authorizations:
query Parameters
fields | string Example: fields=id,customer,orders.id Optional query parameter for trimming the provided documents. Parameter represents a comma separated list of attributes. |
filter | object Example: filter[customer.gender]=o&filter[customer.firstName]=max&filter[customer.lastName]=muster*&filter[customer.age]=gte|18&filter[date]=lt|2020-02-01 Optional query parameter for filtering. Parameter represents an object, which is used to filter the provided documents. |
page | integer >= 1 Default: 1 Example: page=2 Optional query parameter to define current page. |
per-page | integer [ 1 .. 100 ] Default: 25 Example: per-page=25 Optional query parameter to limiting the provided documents. |
sort | string Example: sort=-creationDate,+customer.firstName Optional query parameter for sorting. Parameter represents a comma separated list of attributes. |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
Array of objects (parcelServices-parcelServices) | |
object (parcelServices-collectionMetaData) |
Response samples
- 200
{- "data": [
- {
- "id": "1",
- "name": "DHL",
- "isDefault": true,
- "descriptions": [
- {
- "languageCode": "en",
- "url": "http:\\/\\/nolp.dhl.de\\/nextt-online-public\\/set_identcodes.do?lang=en&idc={TRACKING_NUMBER}&rfn=&extendedSearch=true",
- "comment": "You can access the shipment tracking for your order by visiting the link above."
}
], - "shipmentType": "shipment type"
}
], - "_meta": {
- "totalItems": 42,
- "perPage": 25,
- "page": 2,
- "links": {
}
}
}
Create a new parcel service
Creates a single or multiple new parcel services based on the request body.
Authorizations:
Request Body schema: application/json
Parcel services data for creation.
id required | integer <int32> >= 1 |
name required | string |
isDefault required | boolean |
required | Array of objects |
shipmentType required | string |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
data | Array of integers <int32> (parcelServices-parcelServiceIds) |
object (parcelServices-creationMetaData) |
Request samples
- Payload
[- {
- "id": "1",
- "name": "DHL",
- "isDefault": true,
- "descriptions": [
- {
- "languageCode": "en",
- "url": "http:\\/\\/nolp.dhl.de\\/nextt-online-public\\/set_identcodes.do?lang=en&idc={TRACKING_NUMBER}&rfn=&extendedSearch=true",
- "comment": "You can access the shipment tracking for your order by visiting the link above."
}
], - "shipmentType": "shipment type"
}
]
Response samples
- 201
- 400
- 409
- 422
{- "data": [
- "1"
],
}
Update an existing parcel service
Updates a single or multiple parcel services based on the request body.
Authorizations:
Request Body schema: application/json
Parcel services data for update.
id required | integer <int32> >= 1 |
name required | string |
isDefault required | boolean |
required | Array of objects |
shipmentType required | string |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Request samples
- Payload
[- {
- "id": "1",
- "name": "DHL",
- "isDefault": true,
- "descriptions": [
- {
- "languageCode": "en",
- "url": "http:\\/\\/nolp.dhl.de\\/nextt-online-public\\/set_identcodes.do?lang=en&idc={TRACKING_NUMBER}&rfn=&extendedSearch=true",
- "comment": "You can access the shipment tracking for your order by visiting the link above."
}
], - "shipmentType": "shipment type"
}
]
Response samples
- 400
- 409
- 422
{- "errors": [
- [
- "Attribute \"attribute.subAttribute\" is missing."
]
], - "_meta": { }
}
Get a specific parcel service
Returns a single parcel service based in the provided ID.
Authorizations:
path Parameters
id required | integer >= 1 Example: 1 ID of an existing parcel service. |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
object (parcelServices-parcelService) | |
object (parcelServices-documentMetaData) |
Response samples
- 200
{- "data": {
- "id": "1",
- "name": "DHL",
- "isDefault": true,
- "descriptions": [
- {
- "languageCode": "en",
- "url": "http:\\/\\/nolp.dhl.de\\/nextt-online-public\\/set_identcodes.do?lang=en&idc={TRACKING_NUMBER}&rfn=&extendedSearch=true",
- "comment": "You can access the shipment tracking for your order by visiting the link above."
}
], - "shipmentType": "shipment type"
}, - "_meta": {
- "links": {
}
}
}
The following endpoints can be used to manage the product options of this shop.
Currently, the shop does no support all fields inside the documents completly. The following fields aren't
supported yet: stockType
Get all available product options
Returns a collection of product options.
Authorizations:
path Parameters
productId required | integer >= 1 Example: 1 ID of a product. |
query Parameters
fields | string Example: fields=id,customer,orders.id Optional query parameter for trimming the provided documents. Parameter represents a comma separated list of attributes. |
filter | object Example: filter[customer.gender]=o&filter[customer.firstName]=max&filter[customer.lastName]=muster*&filter[customer.age]=gte|18&filter[date]=lt|2020-02-01 Optional query parameter for filtering. Parameter represents an object, which is used to filter the provided documents. |
page | integer >= 1 Default: 1 Example: page=2 Optional query parameter to define current page. |
per-page | integer [ 1 .. 100 ] Default: 25 Example: per-page=25 Optional query parameter to limiting the provided documents. |
sort | string Example: sort=-creationDate,+customer.firstName Optional query parameter for sorting. Parameter represents a comma separated list of attributes. |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
Array of objects (productOptions-productOptions) | |
object (productOptions-collectionMetaData) |
Response samples
- 200
{- "data": [
- {
- "id": 1,
- "optionId": 1,
- "optionValueId": 1,
- "imageListId": 1,
- "modelNumber": "abcdef-12345",
- "weight": 13.37,
- "price": 13.37,
- "stockType": "only-positive",
- "stock": 13.37,
- "sortOrder": 1
}
], - "_meta": {
- "totalItems": 42,
- "perPage": 25,
- "page": 2,
- "links": {
}
}
}
Create a new product option
Creates a single or multiple new product options based on the request body.
Authorizations:
path Parameters
productId required | integer >= 1 Example: 1 ID of a product. |
Request Body schema: application/json
Product options data for creation.
optionId required | integer <int32> >= 1 |
optionValueId required | integer <int32> >= 1 |
imageListId required | integer <int32> >= 1 Nullable |
modelNumber required | string |
weight required | number <double> |
price required | number <double> |
stockType required | string non-empty Enum: "only-positive" "all-numbers" "not-managed" Determines the behavior for the stock management. |
stock required | number <double> |
sortOrder required | integer <int32> >= 0 |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
data | Array of integers <int32> (productOptions-OptionsCreated) |
object (productVariants-creationMetaData) |
Request samples
- Payload
[- {
- "optionId": 1,
- "optionValueId": 1,
- "imageListId": 1,
- "modelNumber": "abcdef-12345",
- "weight": 13.37,
- "price": 13.37,
- "stockType": "only-positive",
- "stock": 13.37,
- "sortOrder": 1
}
]
Response samples
- 200
- 400
- 409
- 422
{- "data": [
- 1
],
}
Update an existing product option
Updates a single or multiple product options based on the request body.
Authorizations:
path Parameters
productId required | integer >= 1 Example: 1 ID of a product. |
Request Body schema: application/json
Product options data for update.
id required | integer <int32> >= 1 |
optionId required | integer <int32> >= 1 |
optionValueId required | integer <int32> >= 1 |
imageListId required | integer <int32> >= 1 Nullable |
modelNumber required | string |
weight required | number <double> |
price required | number <double> |
stockType required | string non-empty Enum: "only-positive" "all-numbers" "not-managed" Determines the behavior for the stock management. |
stock required | number <double> |
sortOrder required | integer <int32> >= 0 |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Request samples
- Payload
[- {
- "id": 1,
- "optionId": 1,
- "optionValueId": 1,
- "imageListId": 1,
- "modelNumber": "abcdef-12345",
- "weight": 13.37,
- "price": 13.37,
- "stockType": "only-positive",
- "stock": 13.37,
- "sortOrder": 1
}
]
Response samples
- 400
- 409
- 422
{- "errors": [
- [
- "Attribute \"attribute.subAttribute\" is missing."
]
], - "_meta": { }
}
Update sort order of an existing product option
Updates the sort order(s) of a single or multiple product options based on the request body.
Authorizations:
path Parameters
productId required | integer >= 1 Example: 1 ID of a product. |
Request Body schema: application/json
Product options data to update sort orders.
id required | integer <int32> >= 1 |
sortOrder required | integer <int32> >= 0 |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Request samples
- Payload
[- {
- "id": "1",
- "sortOrder": "1"
}
]
Response samples
- 400
- 409
- 422
{- "errors": [
- [
- "Attribute \"attribute.subAttribute\" is missing."
]
], - "_meta": { }
}
Get a specific product option
Returns a single product option based in the provided ID.
Authorizations:
path Parameters
productId required | integer >= 1 Example: 1 ID of a product. |
optionId required | integer >= 1 Example: 1 ID of a product variant. |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
object (productOptions-productOption) | |
object (productOptions-documentMetaData) |
Response samples
- 200
{- "data": {
- "id": 1,
- "optionId": 1,
- "optionValueId": 1,
- "imageListId": 1,
- "modelNumber": "abcdef-12345",
- "weight": 13.37,
- "price": 13.37,
- "stockType": "only-positive",
- "stock": 13.37,
- "sortOrder": 1
}, - "_meta": {
- "links": {
}
}
}
The following endpoints can be used to manage the product variants of this shop.
Currently, the shop does no support all fields inside the documents completly. The following fields aren't
supported yet: GTIN
, ASIN
Get all available product variants
Returns a collection of product variants.
Authorizations:
path Parameters
productId required | integer >= 1 Example: 1 ID of a product. |
query Parameters
fields | string Example: fields=id,customer,orders.id Optional query parameter for trimming the provided documents. Parameter represents a comma separated list of attributes. |
filter | object Example: filter[customer.gender]=o&filter[customer.firstName]=max&filter[customer.lastName]=muster*&filter[customer.age]=gte|18&filter[date]=lt|2020-02-01 Optional query parameter for filtering. Parameter represents an object, which is used to filter the provided documents. |
page | integer >= 1 Default: 1 Example: page=2 Optional query parameter to define current page. |
per-page | integer [ 1 .. 100 ] Default: 25 Example: per-page=25 Optional query parameter to limiting the provided documents. |
sort | string Example: sort=-creationDate,+customer.firstName Optional query parameter for sorting. Parameter represents a comma separated list of attributes. |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
Array of objects (productVariants-variants) | |
object (productVariants-collectionMetaData) |
Response samples
- 200
{- "data": [
- {
- "id": 1,
- "combination": [
- {
- "optionId": 1,
- "optionValueId": 1
}
], - "sortOrder": 1,
- "modelNumber": "abcdef-12345",
- "GTIN": "00012345678905",
- "ASIN": "B0006GQ8RW",
- "EAN": "401234567890",
- "stockType": "only-positive",
- "stock": 13.37,
- "weightType": "replacing",
- "weight": 13.37,
- "priceType": "replacing",
- "price": 13.37,
- "vpeScalarValue": 13.37,
- "vpeUnitId": 1,
- "deliveryTimeId": 1,
- "imageListId": 1
}
], - "_meta": {
- "totalItems": 42,
- "perPage": 25,
- "page": 2,
- "links": {
}
}
}
Create a new product variant
Creates a single or multiple new product variants based on the request body.
Authorizations:
path Parameters
productId required | integer >= 1 Example: 1 ID of a product. |
Request Body schema: application/json
Product variants data for creation.
required | Array of objects |
sortOrder | integer <int32> >= 0 Default: 1 |
modelNumber required | string |
GTIN required | string |
ASIN required | string |
EAN required | string |
stockType required | string non-empty Enum: "only-positive" "all-numbers" "not-managed" Determines the behavior for the stock management. |
stock required | number <double> Default: 0 |
weightType required | string non-empty Enum: "addition" "replacing" Determines if the set variant weight should be added to the product weight or if it replaces the product weight. |
weight required | number <double> |
priceType required | string non-empty Enum: "addition" "replacing" Determines if the set variant price should be added to the product price or if it replaces the product price. |
price required | number <double> |
vpeScalarValue required | number <double> |
vpeUnitId required | integer <int32> >= 1 Nullable |
deliveryTimeId required | integer <int32> >= 1 |
imageListId | integer <int32> >= 1 Nullable Default: null |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
data | Array of integers (productVariants-variants-created) |
object (productVariants-creationMetaData) |
Request samples
- Payload
[- {
- "combination": [
- {
- "optionId": 1,
- "optionValueId": 1
}, - {
- "optionId": 2,
- "optionValueId": 4
}
], - "sortOrder": 1,
- "modelNumber": "abcdef-12345",
- "GTIN": "00012345678905",
- "ASIN": "B0006GQ8RW",
- "EAN": "401234567890",
- "stockType": "only-positive",
- "stock": 13.37,
- "weightType": "replacing",
- "weight": 13.37,
- "priceType": "replacing",
- "price": 13.37,
- "vpeScalarValue": 13.37,
- "vpeUnitId": 1,
- "deliveryTimeId": 1,
- "imageListId": 1
}
]
Response samples
- 200
- 400
- 409
- 422
{- "data": [
- 1
],
}
Update an existing product variant
Updates a single or multiple product variants based on the request body.
Authorizations:
path Parameters
productId required | integer >= 1 Example: 1 ID of a product. |
Request Body schema: application/json
Product variants data for update.
id required | integer <int32> >= 1 |
required | Array of objects |
sortOrder required | integer <int32> >= 0 |
modelNumber required | string |
GTIN required | string |
ASIN required | string |
EAN required | string |
stockType required | string non-empty Enum: "only-positive" "all-numbers" "not-managed" Determines the behavior for the stock management. |
stock required | number <double> |
weightType required | string non-empty Enum: "addition" "replacing" Determines if the set variant weight should be added to the product weight or if it replaces the product weight. |
weight required | number <double> |
priceType required | string non-empty Enum: "addition" "replacing" Determines if the set variant price should be added to the product price or if it replaces the product price. |
price required | number <double> |
vpeScalarValue required | number <double> |
vpeUnitId required | integer <int32> >= 1 Nullable |
deliveryTimeId required | integer <int32> >= 1 |
imageListId required | integer <int32> >= 1 Nullable |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Request samples
- Payload
[- {
- "id": 1,
- "combination": [
- {
- "optionId": 1,
- "optionValueId": 1
}
], - "sortOrder": 1,
- "modelNumber": "abcdef-12345",
- "GTIN": "00012345678905",
- "ASIN": "B0006GQ8RW",
- "EAN": "401234567890",
- "stockType": "only-positive",
- "stock": 13.37,
- "weightType": "replacing",
- "weight": 13.37,
- "priceType": "replacing",
- "price": 13.37,
- "vpeScalarValue": 13.37,
- "vpeUnitId": 1,
- "deliveryTimeId": 1,
- "imageListId": 1
}
]
Response samples
- 400
- 409
- 422
{- "errors": [
- [
- "Attribute \"attribute.subAttribute\" is missing."
]
], - "_meta": { }
}
Update sort order of an existing product variant
Updates the sort order(s) of a single or multiple product variants based on the request body.
Authorizations:
path Parameters
productId required | integer >= 1 Example: 1 ID of a product. |
Request Body schema: application/json
Product variants data to update sort orders.
id required | integer <int32> >= 1 |
sortOrder required | integer <int32> >= 0 |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Request samples
- Payload
[- {
- "id": "1",
- "sortOrder": "1"
}
]
Response samples
- 400
- 409
- 422
{- "errors": [
- [
- "Attribute \"attribute.subAttribute\" is missing."
]
], - "_meta": { }
}
Get a specific product variant
Returns a single product variant based in the provided ID.
Authorizations:
path Parameters
productId required | integer >= 1 Example: 1 ID of a product. |
variantId required | int >= 1 Example: 1 ID of a product variant. |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
object (productVariants-variant) | |
object (productVariants-documentMetaData) |
Response samples
- 200
{- "data": {
- "id": 1,
- "combination": [
- {
- "optionId": 1,
- "optionValueId": 1
}
], - "sortOrder": 1,
- "modelNumber": "abcdef-12345",
- "GTIN": "00012345678905",
- "ASIN": "B0006GQ8RW",
- "EAN": "401234567890",
- "stockType": "only-positive",
- "stock": 13.37,
- "weightType": "replacing",
- "weight": 13.37,
- "priceType": "replacing",
- "price": 13.37,
- "vpeScalarValue": 13.37,
- "vpeUnitId": 1,
- "deliveryTimeId": 1,
- "imageListId": 1
}, - "_meta": {
- "links": {
}
}
}
Generate new product variants
Generates a single or multiple product variants based on the request body.
Authorizations:
path Parameters
productId required | integer >= 1 Example: 1 ID of a product. |
query Parameters
limit | integer >= 1 Default: 100 Example: limit=100 Optional query parameter to limit how many product variants can be generated per request. |
offset | integer >= 1 Default: 0 Example: offset=0 Optional query parameter offset is used to specify which product variants should be processed. |
Request Body schema: application/json
Option IDs and option value IDs for generation of product variant combinations.
optionId required | integer <int32> >= 1 |
optionValueId required | integer <int32> >= 1 |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
data | Array of integers (productVariants-variants-created) |
object (productVariants-creationMetaData) |
Request samples
- Payload
[- {
- "optionId": 1,
- "optionValueId": 1
}, - {
- "optionId": 1,
- "optionValueId": 2
}, - {
- "optionId": 2,
- "optionValueId": 1
}, - {
- "optionId": 2,
- "optionValueId": 2
}
]
Response samples
- 200
{- "data": [
- 1
],
}
Add new options to the existing product variant combinations
Adds a single or multiple options (with option values) to the existing product variant combinations based on the request body.
Authorizations:
path Parameters
productId required | integer >= 1 Example: 1 ID of a product. |
Request Body schema: application/json
Option IDs and option value IDs for adding them to the existing product variant combinations.
optionId required | integer <int32> >= 1 |
optionValueId required | integer <int32> >= 1 |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
data | Array of integers (productVariants-variants-created) |
object (productVariants-creationMetaData) |
Request samples
- Payload
[- {
- "optionId": 1,
- "optionValueId": 1
}, - {
- "optionId": 2,
- "optionValueId": 2
}
]
Response samples
- 200
- 400
- 409
- 422
{- "data": [
- 1
],
}
Remove options from the existing product variant combinations
Removes a single or multiple options from the existing product variants based on the request body.
Authorizations:
path Parameters
productId required | integer >= 1 Example: 1 ID of a product. |
Request Body schema: application/json
Option IDs that should be removed, as well as their option value IDs that are used to determine which combinations should be kept.
optionId required | integer <int32> >= 1 |
retainableOptionValueId required | integer <int32> >= 1 Variant's that had this option value will be modified, while variants with other option values of that option will be removed |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Request samples
- Payload
[- {
- "optionId": 1,
- "retainableOptionValueId": 3
}
]
Response samples
- 400
- 409
- 422
{- "errors": [
- [
- "Attribute \"attribute.subAttribute\" is missing."
]
], - "_meta": { }
}
Get all available tracking codes
Returns a collection of tracking codes.
Authorizations:
query Parameters
fields | string Example: fields=id,customer,orders.id Optional query parameter for trimming the provided documents. Parameter represents a comma separated list of attributes. |
filter | object Example: filter[customer.gender]=o&filter[customer.firstName]=max&filter[customer.lastName]=muster*&filter[customer.age]=gte|18&filter[date]=lt|2020-02-01 Optional query parameter for filtering. Parameter represents an object, which is used to filter the provided documents. |
page | integer >= 1 Default: 1 Example: page=2 Optional query parameter to define current page. |
per-page | integer [ 1 .. 100 ] Default: 25 Example: per-page=25 Optional query parameter to limiting the provided documents. |
sort | string Example: sort=-creationDate,+customer.firstName Optional query parameter for sorting. Parameter represents a comma separated list of attributes. |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
Array of objects (trackingCodes-trackingCodes) | |
object (trackingCodes-collectionMetaData) |
Response samples
- 200
{- "data": [
- {
- "id": "1",
- "orderId": "1",
- "code": "123456789",
- "isReturnDelivery": true,
- "parcelService": {
- "id": "1",
- "languageCode": "en",
- "name": "DHL",
- "url": "http:\\/\\/nolp.dhl.de\\/nextt-online-public\\/set_identcodes.do?lang=en&idc=123456789&rfn=&extendedSearch=true",
- "comment": "You can access the shipment tracking for your order by visiting the link above.",
- "shipmentType": "Sample Shipment Type"
}, - "createdOn": "2020-04-15 14:30:35"
}
], - "_meta": {
- "totalItems": 42,
- "perPage": 25,
- "page": 2,
- "links": {
}
}
}
Create a new tracking code
Creates a single or multiple new tracking codes based on the request body. Parcel service information like name, comment, and so on must be determined manually but default values are defined for each parcel service and could, for example, be fetched via the dedicated REST API endpoint.
Authorizations:
Request Body schema: application/json
Tracking Codes data for creation.
orderId required | integer <int32> >= 1 |
code required | string |
isReturnDelivery required | boolean |
required | object |
createdOn required | string <datetime> ^\d{4}-\d{2}-\d{2}(\s\d{2}:\d{2}:\d{2})?$ |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
data | Array of integers <int32> (trackingCodes-trackingCodeIds) |
object (trackingCodes-creationMetaData) |
Request samples
- Payload
[- {
- "orderId": "1",
- "code": "123456789",
- "isReturnDelivery": true,
- "parcelService": {
- "id": "1",
- "languageCode": "en",
- "name": "DHL",
- "url": "http:\\/\\/nolp.dhl.de\\/nextt-online-public\\/set_identcodes.do?lang=en&idc=123456789&rfn=&extendedSearch=true",
- "comment": "You can access the shipment tracking for your order by visiting the link above.",
- "shipmentType": "Sample Shipment Type"
}, - "createdOn": "2020-04-15 14:30:35"
}
]
Response samples
- 201
- 400
- 409
- 422
{- "data": [
- "1"
],
}
Get a specific tracking code
Returns a single tracking code based in the provided ID.
Authorizations:
path Parameters
id required | integer >= 1 Example: 1 ID of an existing tracking code. |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
object (trackingCodes-trackingCode) | |
object (trackingCodes-documentMetaData) |
Response samples
- 200
{- "data": {
- "id": "1",
- "orderId": "1",
- "code": "123456789",
- "isReturnDelivery": true,
- "parcelService": {
- "id": "1",
- "languageCode": "en",
- "name": "DHL",
- "url": "http:\\/\\/nolp.dhl.de\\/nextt-online-public\\/set_identcodes.do?lang=en&idc=123456789&rfn=&extendedSearch=true",
- "comment": "You can access the shipment tracking for your order by visiting the link above.",
- "shipmentType": "Sample Shipment Type"
}, - "createdOn": "2020-04-15 14:30:35"
},
}
Get all available withdrawals
Returns a collection of withdrawals.
Authorizations:
query Parameters
fields | string Example: fields=id,customer,orders.id Optional query parameter for trimming the provided documents. Parameter represents a comma separated list of attributes. |
filter | object Example: filter[customer.gender]=o&filter[customer.firstName]=max&filter[customer.lastName]=muster*&filter[customer.age]=gte|18&filter[date]=lt|2020-02-01 Optional query parameter for filtering. Parameter represents an object, which is used to filter the provided documents. |
page | integer >= 1 Default: 1 Example: page=2 Optional query parameter to define current page. |
per-page | integer [ 1 .. 100 ] Default: 25 Example: per-page=25 Optional query parameter to limiting the provided documents. |
sort | string Example: sort=-creationDate,+customer.firstName Optional query parameter for sorting. Parameter represents a comma separated list of attributes. |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
Array of objects (withdrawals-withdrawals) | |
object (withdrawals-collectionMetaData) |
Response samples
- 200
{- "data": [
- {
- "id": "1",
- "order": {
- "id": "1",
- "creationDate": "2020-04-15 14:30:35",
- "deliveryDate": "2020-04-15 14:30:35"
}, - "customer": {
- "id": "1",
- "gender": "o",
- "firstName": "John",
- "lastName": "Doe",
- "address": {
- "street": "Parallelweg 30",
- "postcode": "28219",
- "city": "Bremen",
- "country": "Deutschland"
}, - "email": "admin@example.org"
}, - "date": "2020-04-15 14:30:35",
- "content": "Hiermit widerrufe ich ...",
- "createdByAdmin": true,
- "createdOn": "2020-04-15 14:30:35"
}
], - "_meta": {
- "totalItems": 42,
- "perPage": 25,
- "page": 2,
- "links": {
}
}
}
Create a new withdrawal
Creates a single or multiple new withdrawals based on the request body.
Authorizations:
Request Body schema: application/json
Withdrawals data for creation.
required | object |
required | object |
date required | string <datetime> ^\d{4}-\d{2}-\d{2}(\s\d{2}:\d{2}:\d{2})?$ |
content required | string |
createdByAdmin required | boolean |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
data | Array of integers <int32> (withdrawals-withdrawalIds) |
object (withdrawals-creationMetaData) |
Request samples
- Payload
[- {
- "order": {
- "id": "1",
- "creationDate": "2020-04-15 14:30:35",
- "deliveryDate": "2020-04-15 14:30:35"
}, - "customer": {
- "id": "1",
- "gender": "o",
- "firstName": "John",
- "lastName": "Doe",
- "address": {
- "street": "Parallelweg 30",
- "postcode": "28219",
- "city": "Bremen",
- "country": "Deutschland"
}, - "email": "admin@example.org"
}, - "date": "2020-04-15 14:30:35",
- "content": "Hiermit widerrufe ich ...",
- "createdByAdmin": true
}
]
Response samples
- 201
- 400
- 409
- 422
{- "data": [
- "1"
],
}
Update sort order of an existing withdrawal
Updates the sort order(s) of a single or multiple withdrawals based on the request body.
Authorizations:
Request Body schema: application/json
Withdrawals data to update sort orders.
id required | integer <int32> >= 1 |
required | object |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Request samples
- Payload
[- {
- "id": "1",
- "order": {
- "date": "2020-04-15 14:30:35"
}
}
]
Response samples
- 400
- 409
- 422
{- "errors": [
- [
- "Attribute \"attribute.subAttribute\" is missing."
]
], - "_meta": { }
}
Get a specific withdrawal
Returns a single withdrawal based in the provided ID.
Authorizations:
path Parameters
id required | integer >= 1 Example: 1 ID of an existing withdrawal. |
Responses
X-Shop-Version | string Example: "4.1.0.0" Current shop version. |
X-API-Version | string Example: "3.0.0" Current API version. |
X-Rate-Limit-Limit | integer Example: 5000 Request limit per time frame. |
X-Rate-Limit-Remaining | integer Example: 4242 Number of requests left for current time frame. |
X-Rate-Limit-Reset | integer Example: 3500 Seconds til the current rate limit resets. |
Response Schema: application/json
object (withdrawals-withdrawal) | |
object (withdrawals-documentMetaData) |
Response samples
- 200
{- "data": {
- "id": "1",
- "order": {
- "id": "1",
- "creationDate": "2020-04-15 14:30:35",
- "deliveryDate": "2020-04-15 14:30:35"
}, - "customer": {
- "id": "1",
- "gender": "o",
- "firstName": "John",
- "lastName": "Doe",
- "address": {
- "street": "Parallelweg 30",
- "postcode": "28219",
- "city": "Bremen",
- "country": "Deutschland"
}, - "email": "admin@example.org"
}, - "date": "2020-04-15 14:30:35",
- "content": "Hiermit widerrufe ich ...",
- "createdByAdmin": true,
- "createdOn": "2020-04-15 14:30:35"
}, - "_meta": {
- "links": {
}
}
}