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!

Authentication

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 CustomersRoles and Permissions page of the Gambio Admin.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

General Information

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.

Error Handling

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 Support

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.

HTTP Caching Support

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.

Usage with Postman

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.

Optional Query Parameters

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 name John.
  • GET /api.php/v3/withdrawals?filter[customer.firstName]=J* will return all withdrawals of customers whose first name begins with J.
  • GET /api.php/v3/withdrawals?filter[customer.firstName]=J*&filter[id]=*1 will return all withdrawals of customers whose first name begins with J 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 than 42.
  • GET /api.php/v3/withdrawals?filter[id]=gte|42 will return all withdrawals with an ID that is equals or greater than 42.
  • GET /api.php/v3/withdrawals?filter[id]=lt|42 will return all withdrawals with an ID that is less than 42.
  • GET /api.php/v3/withdrawals?filter[id]=lte|42 will return all withdrawals with an ID that is equals or less than 42.
  • GET /api.php/v3/withdrawals?filter[id]=neq|42 will return all withdrawals with an ID that is not equal to 42.
  • 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 of 2020-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

ImageLists

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

Response Headers
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

Content type
application/json
{}

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.

Array ()
name
required
string non-empty

Responses

Response Headers
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

Content type
application/json
[
  • {
    • "name": "image lists #1"
    }
]

Response samples

Content type
application/json
{}

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.

Array ()
id
required
integer <int32> >= 1
name
required
string non-empty

Responses

Response Headers
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

Content type
application/json
[
  • {
    • "id": 1,
    • "name": "image lists #1"
    }
]

Response samples

Content type
application/json
{
  • "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

Response Headers
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

Content type
application/json
{}

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

Content type
application/json
{
  • "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

Response Headers
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

Content type
application/json
{}

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.

Array ()
relativePath
required
string non-empty
sortOrder
integer <int32> >= 0
required
Array of objects
required
Array of objects

Responses

Response Headers
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

Content type
application/json
[
  • {
    • "relativePath": "subdirectory/image.jpg",
    • "sortOrder": 1,
    • "titles": [
      • {
        • "languageCode": "en",
        • "text": "text for image"
        }
      ],
    • "altTitles": [
      • {
        • "languageCode": "en",
        • "text": "text for image"
        }
      ]
    }
]

Response samples

Content type
application/json
{
  • "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.

Array ()
relativePath
required
string non-empty
sortOrder
required
integer <int32> >= 0

Responses

Response Headers
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

Content type
application/json
[
  • {
    • "relativePath": "subdirectory/image.jpg",
    • "sortOrder": "1"
    }
]

Response samples

Content type
application/json
{
  • "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.

Array ()
relativePath
required
string non-empty
sortOrder
integer <int32> >= 0
required
Array of objects
required
Array of objects

Responses

Response Headers
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

Content type
application/json
[
  • {
    • "relativePath": "subdirectory/image.jpg",
    • "sortOrder": 1,
    • "titles": [
      • {
        • "languageCode": "en",
        • "text": "text for image"
        }
      ],
    • "altTitles": [
      • {
        • "languageCode": "en",
        • "text": "text for image"
        }
      ]
    }
]

Response samples

Content type
application/json
{
  • "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 list image for addition.

string <binary>

Responses

Response Headers
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

Content type
application/json
{
  • "data": [
    • "subdirectory/image.jpg"
    ]
}

Options

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

Response Headers
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

Content type
application/json
{
  • "data": [
    • {
      • "id": "1",
      • "type": "Dropdown",
      • "sortOrder": 1,
      • "details": [
        • {
          }
        ],
      • "values": [
        • {
          }
        ]
      }
    ],
  • "_meta": {}
}

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.

Array ()
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

Response Headers
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

Content type
application/json
[
  • {
    • "type": "Dropdown",
    • "sortOrder": 1,
    • "details": [
      • {
        • "languageCode": "en",
        • "label": "Size",
        • "adminLabel": "Size (T-Shirts)",
        • "description": "An additional description ..."
        }
      ]
    }
]

Response samples

Content type
application/json
{}

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.

Array ()
id
required
integer <int32> >= 1
sortOrder
required
integer <int32> >= 0

Responses

Response Headers
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

Content type
application/json
[
  • {
    • "id": "1",
    • "sortOrder": "1"
    }
]

Response samples

Content type
application/json
{
  • "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.

Array ()
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

Response Headers
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

Content type
application/json
[
  • {
    • "id": 1,
    • "type": "Dropdown",
    • "sortOrder": 1,
    • "details": [
      • {
        • "languageCode": "en",
        • "label": "Size",
        • "adminLabel": "Size (T-Shirts)",
        • "description": "An additional description ..."
        }
      ]
    }
]

Response samples

Content type
application/json
{
  • "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

Response Headers
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

Content type
application/json
{
  • "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": [
          ],
        • "image": "xxl.jpg",
        • "modelNumber": "xxl",
        • "weight": 13.37,
        • "price": 13.37,
        • "stockType": "only-positive",
        • "stock": 13.37,
        • "stockCentrallyManaged": true
        }
      ]
    },
  • "_meta": {}
}

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

Content type
application/json
{
  • "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

Response Headers
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

Content type
application/json
{}

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.

Array ()
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. only-positive allows only positive stock values (including zero), all-numbers allows all numeric stock values, and not-managed means that this value is not considered for the stock management.

stock
required
number <double>
stockCentrallyManaged
required
boolean

Responses

Response Headers
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

Content type
application/json
[
  • {
    • "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

Content type
application/json
{}

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.

Array ()
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. only-positive allows only positive stock values (including zero), all-numbers allows all numeric stock values, and not-managed means that this value is not considered for the stock management.

stock
required
number <double>
stockCentrallyManaged
required
boolean

Responses

Response Headers
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

Content type
application/json
[
  • {
    • "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

Content type
application/json
{
  • "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.

Array ()
id
required
integer <int32> >= 1
sortOrder
required
integer <int32> >= 0

Responses

Response Headers
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

Content type
application/json
[
  • {
    • "id": "1",
    • "sortOrder": "1"
    }
]

Response samples

Content type
application/json
{
  • "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

Content type
application/json
{
  • "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:

option value image for addition.

string <binary>

Responses

Response Headers
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

Content type
application/json
{
  • "errors": [
    • [
      • "Attribute \"attribute.subAttribute\" is missing."
      ]
    ],
  • "_meta": { }
}

Parcel Services

The following endpoints can be used to manage the parcel services of this shop.

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

Response Headers
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

Content type
application/json
{}

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.

Array ()
id
required
integer <int32> >= 1
name
required
string
isDefault
required
boolean
required
Array of objects
shipmentType
required
string

Responses

Response Headers
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

Content type
application/json
[
  • {
    • "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

Content type
application/json
{}

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.

Array ()
id
required
integer <int32> >= 1
name
required
string
isDefault
required
boolean
required
Array of objects
shipmentType
required
string

Responses

Response Headers
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

Content type
application/json
[
  • {
    • "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

Content type
application/json
{
  • "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

Response Headers
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

Content type
application/json
{
  • "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": {}
}

Delete multiple parcel services

Deletes one or more parcel services based on the provided IDs.

Authorizations:
path Parameters
ids
required
string
Example: 1,2,3

Parcel service IDs represented as a comma separated list.

Responses

Product Options

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

Response Headers
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

Content type
application/json
{}

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.

Array ()
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. only-positive allows only positive stock values (including zero), all-numbers allows all numeric stock values, and not-managed means that this value is not considered for the stock management.

stock
required
number <double>
sortOrder
required
integer <int32> >= 0

Responses

Response Headers
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

Content type
application/json
[
  • {
    • "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

Content type
application/json
{}

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.

Array ()
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. only-positive allows only positive stock values (including zero), all-numbers allows all numeric stock values, and not-managed means that this value is not considered for the stock management.

stock
required
number <double>
sortOrder
required
integer <int32> >= 0

Responses

Response Headers
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

Content type
application/json
[
  • {
    • "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

Content type
application/json
{
  • "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.

Array ()
id
required
integer <int32> >= 1
sortOrder
required
integer <int32> >= 0

Responses

Response Headers
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

Content type
application/json
[
  • {
    • "id": "1",
    • "sortOrder": "1"
    }
]

Response samples

Content type
application/json
{
  • "errors": [
    • [
      • "Attribute \"attribute.subAttribute\" is missing."
      ]
    ],
  • "_meta": { }
}

Delete all product options

Deletes all product options.

Authorizations:
path Parameters
productId
required
integer >= 1
Example: 1

ID of a product.

Responses

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

Response Headers
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

Content type
application/json
{}

Delete multiple product options

Deletes one or more product options based on the provided IDs.

Authorizations:
path Parameters
productId
required
integer >= 1
Example: 1

ID of a product.

ids
required
string
Example: 1,2,3,4,5

Product variant IDs represented as a comma separated list.

Responses

Product Variants

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

Response Headers
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

Content type
application/json
{}

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.

Array ()
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. only-positive allows only positive stock values (including zero), all-numbers allows all numeric stock values, and not-managed means that this value is not considered 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

Response Headers
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

Content type
application/json
[
  • {
    • "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

Content type
application/json
{}

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.

Array ()
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. only-positive allows only positive stock values (including zero), all-numbers allows all numeric stock values, and not-managed means that this value is not considered 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

Response Headers
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

Content type
application/json
[
  • {
    • "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

Content type
application/json
{
  • "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.

Array ()
id
required
integer <int32> >= 1
sortOrder
required
integer <int32> >= 0

Responses

Response Headers
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

Content type
application/json
[
  • {
    • "id": "1",
    • "sortOrder": "1"
    }
]

Response samples

Content type
application/json
{
  • "errors": [
    • [
      • "Attribute \"attribute.subAttribute\" is missing."
      ]
    ],
  • "_meta": { }
}

Delete all product variants

Deletes all product variants.

Authorizations:
path Parameters
productId
required
integer >= 1
Example: 1

ID of a product.

Responses

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

Response Headers
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

Content type
application/json
{
  • "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": {}
}

Delete multiple product variants

Deletes one or more product variants based on the provided IDs.

Authorizations:
path Parameters
productId
required
integer >= 1
Example: 1

ID of a product.

ids
required
int >= 1
Example: 1

Product variant IDs represented as a comma separated list.

Responses

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.

Array ()
optionId
required
integer <int32> >= 1
optionValueId
required
integer <int32> >= 1

Responses

Response Headers
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

Content type
application/json
[
  • {
    • "optionId": 1,
    • "optionValueId": 1
    },
  • {
    • "optionId": 1,
    • "optionValueId": 2
    },
  • {
    • "optionId": 2,
    • "optionValueId": 1
    },
  • {
    • "optionId": 2,
    • "optionValueId": 2
    }
]

Response samples

Content type
application/json
{}

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.

Array ()
optionId
required
integer <int32> >= 1
optionValueId
required
integer <int32> >= 1

Responses

Response Headers
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

Content type
application/json
[
  • {
    • "optionId": 1,
    • "optionValueId": 1
    },
  • {
    • "optionId": 2,
    • "optionValueId": 2
    }
]

Response samples

Content type
application/json
{}

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.

Array ()
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

Response Headers
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

Content type
application/json
[
  • {
    • "optionId": 1,
    • "retainableOptionValueId": 3
    }
]

Response samples

Content type
application/json
{
  • "errors": [
    • [
      • "Attribute \"attribute.subAttribute\" is missing."
      ]
    ],
  • "_meta": { }
}

Tracking Codes

The following endpoints can be used to manage the tracking codes of this shop.

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

Response Headers
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

Content type
application/json
{
  • "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": {}
}

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.

Array ()
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

Response Headers
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

Content type
application/json
[
  • {
    • "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

Content type
application/json
{}

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

Response Headers
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

Content type
application/json
{
  • "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": {}
}

Delete multiple tracking codes

Deletes one or more tracking codes based on the provided IDs.

Authorizations:
path Parameters
ids
required
string
Example: 1,2,3

Tracking Code IDs represented as a comma separated list.

Responses

Withdrawals

The following endpoints can be used to manage the withdrawals of this shop.

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

Response Headers
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

Content type
application/json
{
  • "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": {
          },
        • "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": {}
}

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.

Array ()
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

Response Headers
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

Content type
application/json
[
  • {
    • "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

Content type
application/json
{}

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.

Array ()
id
required
integer <int32> >= 1
required
object

Responses

Response Headers
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

Content type
application/json
[
  • {
    • "id": "1",
    • "order": {
      • "date": "2020-04-15 14:30:35"
      }
    }
]

Response samples

Content type
application/json
{
  • "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

Response Headers
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

Content type
application/json
{
  • "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": {}
}

Delete multiple withdrawals

Deletes one or more withdrawals based on the provided IDs.

Authorizations:
path Parameters
ids
required
string
Example: 1,2,3

Withdrawal IDs represented as a comma separated list.

Responses