Skip to main content
API docs by Redocly

Active Ants ShopApi v3 (3.0)

Download OpenAPI specification:Download

IT Support: itsupport@activeants.com URL: https://www.activeants.com/ License: © Active Ants 2024

This site contains the specifications of the Active Ants ShopApi v3. This api is a rebuild from the earlier released v1 and v2 endpoints which are still online but are in the process of being replaced.

We're working hard to give you the best experience and complete control over your data through our APIs. To make sure that the endpoints follow a certain design pattern we've based the APIs on the JSON:API specifications. For more details about how to make the most of our endpoints see our online developer portal

Common

The "Common" section of the API documentation provides a set of endpoints that are frequently used across different operations. These endpoints handle fundamental tasks, such as authentication and service status checks, which are essential for ensuring smooth communication between your application and the API. Understanding these endpoints is crucial for maintaining an efficient integration process.

One of the key endpoints in this section is POST /token. This operation is responsible for generating an authentication token. To access this endpoint, you must provide valid credentials, including a username and password specific to each shop. The returned token is essential for authenticating further requests. It's important to store the token securely and be prepared to request a new one if it becomes invalid, as unauthorized errors can occur.

Another important endpoint is GET status/get, which serves as a quick way to check the status of the ShopAPI. It requires no authentication and provides a simple confirmation that the API is functioning properly. When the service is available, the response includes a message confirming that the status is OK.

token

POST token

The operations of the shopapi/v3 require a bearer token to access the data. For each client a separate username and password can be requested which in turn can be used to request a bearer token for accessing the endpoints. The same bearer token will grant access to all shopapi/v3 endpoints and older, but only to the information of the client it belongs to. and need to be provided to the Token operation. This operation will return a token string which needs to be provided in the header of each request.

It is not required to request a tokens for each and every API call. It is recommended to store the token until it expires. Be aware that a token can potentially be invalidated before it actually expires in case of intrusion detection. If this happens requests will return a 401 Unauthorized error and a new token must be requested.
Request Body schema: application/x-www-form-urlencoded
grant_type
required
any
Default: "password"
username
required
string
password
required
string

Responses

Response Schema: application/json
access_token
string
token_type
string
Default: "bearer"
expires_in
integer
userName
string
issued
string
expires
string

Request samples

Content type
application/x-www-form-urlencoded
grant_type=password&username=shopapi-user&password=your-secret-is-safe

Response samples

Content type
application/json
{
  • "access_token": "WW91IGNvdWxkIG5vdCByZXNpc3QgdGhlIHVyZ2UgdG8gbG9vayBjb3VsZCB5b3U/,",
  • "token_type": "bearer",
  • "expires_in": 56499,
  • "userName": "shopapi-user",
  • "issued": "Tue, 05 Dec 2024 11:22:52 GMT",
  • "expires": "Wed, 06 Dec 2024 03:22:52 GMT"
}

status/get

GET status/get

This endpoint can be used to verify if the ShopApi is up and running. It requires no authentication and has no input requirements whatsoever.

When the ShopApi is functioning the response is a simple message with the following structure:

{
  "messageCode": "OK",
  "message": "Status is OK.",
  "result": null
}

Responses

Response Schema: application/json
messageCode
string
message
string
result
object or null

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "Status is OK.",
  • "result": null
}

Orders

v3/orders

GET v3/orders

Returns all orders placed.

Pagination

The endpoint supports pagination to split the large collection of resources into smaller, more manageable chunks or pages. This helps to reduce the response size and to improve performance. The endpoint supports only cursor-based technique for pagination.

Filters

The GET v3/orders endpoint supports filtering on the following attributes: orderedOn, externalOrderNumber, reference. Each of these are explained below. Filters can be used in combination with each other and with pagination to allow full access to the desired subset of orders.

Filtering on orderedOn

The results returned by this service can be filtered based on the order date of the order. To do so make use of the filter[orderedOn] parameter in the following manner:

  • GET {host}/v3/orders?filter[orderedOn][lt]={date} will return order that have been ordered before the provided date. Orders that have been ordered on that date are not included in the results.
  • GET {host}/v3/orders?filter[orderedOn][gt]={date} will return order that have been ordered after the provided date. Orders that have been ordered on that date are not included in the results.
  • GET {host}/v3/orders?filter[orderedOn][gt]={date_1}&filter[orderedOn][lt]={date_2} will return orders that have ordered between dates {date_1} and {date_1}. Orders that has been ordered on either date are not included in the results.

Filtering on externalOrderNumber

In order to find orders that have a specific externalOrderNumber it is possible to specify one or more values to search for. Be aware that each entry in the list must be URL-encoded in order to be accepted. This means that the characters !\"#$%&'()*+,\:;=?@[] and white-spaces must be percent-encoded (see also the example below). Make use of the filter[externalOrderNumber][in] filter as follows:

  • GET {host}\v3\orders?filter[externalOrderNumber][in]=%23UK-1003,NL123%2F433 will return all orders that have either #UK-1003 or NL123\433 as externalOrderNumber.

Filtering on reference

In order to find orders that have a specific reference it is possible to specify one or more values to search for. Be aware that each entry in the list must be URL-encoded in order to be accepted. This means that the characters !\"#$%&'()*+,\:;=?@[] and white-spaces must be percent-encoded (see also the example below). Make use of the filter[reference][in] filter as follows:

  • GET{host}\v3\orders?filter[reference][in]=%23UK-1003,NL123%2F433 will return all orders that have either #UK-1003 or NL123\433 as reference.

The endpoint also supports -to some degree- the inclusion of information of related resources. The resources that can be included in the response are limited to the orderItems, the deliveryAddress, the billingAddress and the pickUpPoint. To get the details of related entities the include parameter must be added to the URI in the following way:

  • GET {host}/v3/orders?include=orderItems will return for each order the list of orderItems with their details.
  • GET {host}/v3/orders?include=deliveryAddress,billingAddress,pickUpPoint will return all three types of addresses of each order if applicable. Note that the deliveryAddress and billingAddress are both of type address whereas the pickUpPoint is of type pickUpPoint.
Authorizations:
Bearer Token
query Parameters
page[cursor]
integer >= 0
Default: 0

optional parameter, excludes ?page[number] indicating the value of the cursor. Values too low will be interpreted as if ommitted. The endpoint will use the cursor as the id of the entity that was last returned and will not include it in the response to the request.

page[size]
integer ( 0 .. 100 ]
Default: 100

optional parameter indicating the size of the page, i.e. the maximum number of entities in the response.

include
Array of strings unique
Items Enum: "orderItems" "deliveryAddress" "billingAddress" "pickUpPoint"

Comma-separated list of order related resources to include in the response under the included element

filter[orderedOn][gt]
string <date>

Filters the response to only return items that have a value for the attribute orderedOn after the specified date.

filter[orderedOn][lt]
string <date>

Filters the response to only return items that have a value for the attribute orderedOn before the specified date.

filter[externalOrderNumber][in]
Array of strings (externalOrderNumber) non-empty unique [ items <= 50 characters ]
Examples:
  • filter[externalOrderNumber][in]=ABC -
  • filter[externalOrderNumber][in]=ABC,DEF -
  • filter[externalOrderNumber][in]=DEF -

A comma separated list of externalOrderNumbers to filter the orders by. Note that each id must be URI encoded. For example filter[externalOrderNumber]=ABC,DEF will return orders having ABC or DEF as externalOrderNumber. However filter[externalOrderNumber]=ABC%2CDEF will return orders having ABC,DEF as externalOrderNumber.

filter[reference][in]
Array of strings unique

A comma separated list of reference values to filter by, each of which must be URL encoded and separated by a comma.

Responses

Response Schema: application/vnd.api+json
Array of objects (order)
Array
id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
externalOrderNumber
required
string (externalOrderNumber) <= 50 characters

The externalOrderNumber as specified during creation of the order.

reference
string

Optional field to store an internal reference to the order

orderedOn
string <date>

An optional field to place the date the consumer placed the order, this may be a date in the past. For example when the order was forwarded much later to the shop api.

consumerReference
string

Optional reference provided by the consumer of this order`

promotionCode
string

Any promotion code the consumer used when placing the order.

locale
required
string (localeCode) ^([a-zA-Z]+(?:-[a-zA-Z]+)?)

The locale defines (among other things) the language used in communications, inserts and possibly packaging relating to this order. The locale has to be a full locale like en-GB

email
string <email>

The email address of the consumer. This email address could be used by Active Ants, the carrier o customs in various notification messages regarding the shipments(s) related to this order.

phoneNumber
string (phoneNumber) <= 32 characters ^[\d\s\+\(\)-\.\\\/]+$

The consumer's phone number which might be used by the carrier or customs to contact the consumer regarding the shipment(s) related to this order.

vatNumber
string
fulfillFrom
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

When provided indicates the warehouse from which each orderItem must be fulfilled. When not provided the system will select the warehouse based on the warehouse strategy configuration for your company. Note that this value can also be set at orderItem-level which supercedes the specification at order-level or the warehouse strategy.

preferredShippingDate
string <date>

Allows the specification of a future date at which the order is to be shipped.

allowPartialDelivery
boolean
Default: false

When set to true the order may be split into multiple shipments in case there is insufficient stock to filfill the order in a single shipment or from a single warehouse.

onHold
boolean
Default: false

When set to true prevents the order from being shipped until released.

object

Allows the specification of arbitrary name-value pairs. note currently only the names 'extra1', 'extra2', 'extra3', 'extra4' and 'extra5' are supported and are linked to functionality (contact support for more information).

extra1
string
extra2
string
extra3
string
extra4
string
extra5
string
channelIdentifier
string (channelOrderIdentifier) <= 250 characters

The channelIdentifier is the (technical) id for the order as assigned by the external channel. For example Shopify, Amazon, Bol, Zalando, etc. may assign a unique id for communication and synchronization purposes.

currency
string (currencyCode) = 3 characters [A-Z]{3}
Default: "EUR"

Defines the currency of the order and all its orderItems. If omitted, the value EUR is assumed. The currency is used to convert the price of each orderItem to an acceptable currency when a shipment must be declaring its value to customs agencies.

object
required
object (orderTypeRelation)

Represents a relationship to an orderType resource.

object (orderTypeIdentifier)

Identifies a resource as an orderType.

id
integer
type
stringorderType
Default: "orderType"
object
self
string <uri>
object (orderItemsRelation)

Represents a relationship to multiple orderItem resources.

Array of objects (orderItemIdentification)
Array
id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
self
string <uri>
required
object (addressRelation)

Denotes the address and name where the order must be delivered, unless a pickUpPoint has been specified in which case the order will be delivered to the pick-up point instead

object (addressIdentification)

Identifies a resource as an address.

id
integer
type
required
any
Default: "address"
Value: "address"
object (addressRelation)

Optional address that can be used as billing address. When not provided it is assumed to be the same as the deliveryAddress.

object (addressIdentification)

Identifies a resource as an address.

id
integer
type
required
any
Default: "address"
Value: "address"
object (pickUpPointRelation)

Optional: specify the address of the pick-up point in case the order is to be delivered at a pick-up point. Note that the deliveryAddress is still required.

object (pickUpPointIdentifier)

Identifies a resource as an pickUpPoint.

id
integer
type
required
any
Default: "pickUpPoint"
Value: "pickUpPoint"
object (shippingMethodRelation)

Optional identifier to the shippingMethod preferred for this order. Note that this method is preferred, but not guaranteed since the method might not be available at the warehouse from where the order might be fulfilled, or the shipment may not be compatible with the preferred method. IMPORTANT: the v3 endpoints use the mainShippingMethodId as returned by the GET settings/get endpoints under /MainShippingMethods/id.

object (shippingMethodIdentifier)

Identifies a resource as a shippingMethod.

id
integer
type
any
Value: "shippingMethod"
object
self
string <uri>
Array of orderItemIdentification (object) or addressIdentification (object) or pickUpPointIdentifier (object) or orderAttachmentIdentification (object)

An array of resources included with the order, use the type property to identify the resource's type.

Array
Any of
id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
sku
required
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

channelIdentifier
string (channelOrderItemIdentifier) <= 250 characters

The channelIdentifier is the (technical) id for the orderItem as assigned by the external channel. For example Shopify, Amazon, Bol, Zalando, etc. may assign a unique id for communication and synchronization purposes.

quantity
required
integer
fulfillFrom
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

When specified indicates that the item can only be fulfilled from the indicated warehouse.

price
number decimal places <= 2

Specifies the price of a single unit of the product as sold to the consumer / recipient. Note that all products sold to consumers and shipped internationally must have a price greater than 0.00, as many customs agencies do not accept negative values. Furthermore, some carriers may impose a minimum price—typically around 1.000 in the order’s currency.

vat
number decimal places <= 3 [ 0 .. 1 )
Default: 0

This field represents the VAT percentage that was included in the price. If omitted, the value 0.000 is assumed as the percentage. The value must be between [0.000 and 1.000⟩, with an accuracy of up to three decimal places after the comma.

name
string

The name / description for this product on this orderItem. If no value is provided here, then the name of the product will be used instead whenever a name is required (for example when declaring to customs)

object (metadata)

Allows the specification of arbitrary name-value pairs. note currently only the names 'extra6' and 'extra7' are supported.

extra6
string
extra7
string
object
object (orderRelation)

Represents a relationship to an order resource.

object (orderIdentification)

Identifies a resource as an order.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
self
string <uri>
object (productRelation)

Represents a relationship to a product resource.

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object
self
string <uri>
object

Pagination links that provided for convenience and in compliancy to the json:api specification for pagination.

self
string <uri>
next
string <uri>
first
string <uri>

Response samples

Content type
application/vnd.api+json
{}

v3/orders

POST v3/orders

This endpoint enables a client to create an order with its orderItems and related addresses.

Request

When creating an order the related resources must be included in the request under the included attribute of the order (see the example). For the resources deliveryAddress and billingAddress it is required to provide a provisional id to be able to link the correct address-resource in the appropriate relationship. For orderItems and the pickUpPoint this is not required as these are effectively redundant. Resource orderAttachment is optional and, if provided, has to be set in included array (see the example below).

Attachments

It is possible to submit pdf documents which will be printed-out and placed in the parcel with the products. On order to make use of this print facility contact your account manager to arrange matters.

Response

Upon successfulcreation of the orders and its orderItems the server responds with the complete order resource and related resources in a similar fashion as if invoked by a GET v3/orders/:id?include=orderItems,deliveryAddress,billingAddress,pickUpPoint.

Authorizations:
Bearer Token
Request Body schema: application/vnd.api+json
object (orderIdentification)

Identifies a resource as an order.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
externalOrderNumber
required
string (externalOrderNumber) <= 50 characters

The externalOrderNumber as specified during creation of the order.

reference
string

Optional field to store an internal reference to the order

orderedOn
string <date>

An optional field to place the date the consumer placed the order, this may be a date in the past. For example when the order was forwarded much later to the shop api.

consumerReference
string

Optional reference provided by the consumer of this order`

promotionCode
string

Any promotion code the consumer used when placing the order.

locale
required
string (localeCode) ^([a-zA-Z]+(?:-[a-zA-Z]+)?)

The locale defines (among other things) the language used in communications, inserts and possibly packaging relating to this order. The locale has to be a full locale like en-GB

email
string <email>

The email address of the consumer. This email address could be used by Active Ants, the carrier o customs in various notification messages regarding the shipments(s) related to this order.

phoneNumber
string (phoneNumber) <= 32 characters ^[\d\s\+\(\)-\.\\\/]+$

The consumer's phone number which might be used by the carrier or customs to contact the consumer regarding the shipment(s) related to this order.

vatNumber
string
fulfillFrom
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

When provided indicates the warehouse from which each orderItem must be fulfilled. When not provided the system will select the warehouse based on the warehouse strategy configuration for your company. Note that this value can also be set at orderItem-level which supercedes the specification at order-level or the warehouse strategy.

preferredShippingDate
string <date>

Allows the specification of a future date at which the order is to be shipped.

allowPartialDelivery
boolean
Default: false

When set to true the order may be split into multiple shipments in case there is insufficient stock to filfill the order in a single shipment or from a single warehouse.

onHold
boolean
Default: false

When set to true prevents the order from being shipped until released.

object

Allows the specification of arbitrary name-value pairs. note currently only the names 'extra1', 'extra2', 'extra3', 'extra4' and 'extra5' are supported and are linked to functionality (contact support for more information).

extra1
string
extra2
string
extra3
string
extra4
string
extra5
string
channelIdentifier
string (channelOrderIdentifier) <= 250 characters

The channelIdentifier is the (technical) id for the order as assigned by the external channel. For example Shopify, Amazon, Bol, Zalando, etc. may assign a unique id for communication and synchronization purposes.

currency
string (currencyCode) = 3 characters [A-Z]{3}
Default: "EUR"

Defines the currency of the order and all its orderItems. If omitted, the value EUR is assumed. The currency is used to convert the price of each orderItem to an acceptable currency when a shipment must be declaring its value to customs agencies.

object
required
object (orderTypeRelation)

Represents a relationship to an orderType resource.

object (orderTypeIdentifier)

Identifies a resource as an orderType.

id
integer
type
stringorderType
Default: "orderType"
object
object (orderItemsRelation)

Represents a relationship to multiple orderItem resources.

Array of objects (orderItemIdentification)
Array
id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
required
object (addressRelation)

Denotes the address and name where the order must be delivered, unless a pickUpPoint has been specified in which case the order will be delivered to the pick-up point instead

object (addressIdentification)

Identifies a resource as an address.

id
integer
type
required
any
Default: "address"
Value: "address"
object (addressRelation)

Optional address that can be used as billing address. When not provided it is assumed to be the same as the deliveryAddress.

object (addressIdentification)

Identifies a resource as an address.

id
integer
type
required
any
Default: "address"
Value: "address"
object (pickUpPointRelation)

Optional: specify the address of the pick-up point in case the order is to be delivered at a pick-up point. Note that the deliveryAddress is still required.

object (pickUpPointIdentifier)

Identifies a resource as an pickUpPoint.

id
integer
type
required
any
Default: "pickUpPoint"
Value: "pickUpPoint"
object (shippingMethodRelation)

Optional identifier to the shippingMethod preferred for this order. Note that this method is preferred, but not guaranteed since the method might not be available at the warehouse from where the order might be fulfilled, or the shipment may not be compatible with the preferred method. IMPORTANT: the v3 endpoints use the mainShippingMethodId as returned by the GET settings/get endpoints under /MainShippingMethods/id.

object (shippingMethodIdentifier)

Identifies a resource as a shippingMethod.

id
integer
object
Array of orderItemIdentification (object) or addressIdentification (object) or pickUpPointIdentifier (object) or orderAttachmentIdentification (object)

An array of resources included with the order, use the type property to identify the resource's type.

Array
Any of
id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
sku
required
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

channelIdentifier
string (channelOrderItemIdentifier) <= 250 characters

The channelIdentifier is the (technical) id for the orderItem as assigned by the external channel. For example Shopify, Amazon, Bol, Zalando, etc. may assign a unique id for communication and synchronization purposes.

quantity
required
integer
fulfillFrom
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

When specified indicates that the item can only be fulfilled from the indicated warehouse.

price
number decimal places <= 2

Specifies the price of a single unit of the product as sold to the consumer / recipient. Note that all products sold to consumers and shipped internationally must have a price greater than 0.00, as many customs agencies do not accept negative values. Furthermore, some carriers may impose a minimum price—typically around 1.000 in the order’s currency.

vat
number decimal places <= 3 [ 0 .. 1 )
Default: 0

This field represents the VAT percentage that was included in the price. If omitted, the value 0.000 is assumed as the percentage. The value must be between [0.000 and 1.000⟩, with an accuracy of up to three decimal places after the comma.

name
string

The name / description for this product on this orderItem. If no value is provided here, then the name of the product will be used instead whenever a name is required (for example when declaring to customs)

object (metadata)

Allows the specification of arbitrary name-value pairs. note currently only the names 'extra6' and 'extra7' are supported.

extra6
string
extra7
string
object
object (orderRelation)

Represents a relationship to an order resource.

object (orderIdentification)

Identifies a resource as an order.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
object (productRelation)

Represents a relationship to a product resource.

object (productIdentifier)

Identifies a resource as a product.

type
any
Default: "product"
Value: "product"
object

Responses

Response Schema: application/vnd.api+json
object (order)

An order is a single request for fulfillment that is submitted to Active Ants. An order will be 'converted' into one or more shipments that together consist of the same quantity of products delivered at the consumer.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
externalOrderNumber
required
string (externalOrderNumber) <= 50 characters

The externalOrderNumber as specified during creation of the order.

reference
string

Optional field to store an internal reference to the order

orderedOn
string <date>

An optional field to place the date the consumer placed the order, this may be a date in the past. For example when the order was forwarded much later to the shop api.

consumerReference
string

Optional reference provided by the consumer of this order`

promotionCode
string

Any promotion code the consumer used when placing the order.

locale
required
string (localeCode) ^([a-zA-Z]+(?:-[a-zA-Z]+)?)

The locale defines (among other things) the language used in communications, inserts and possibly packaging relating to this order. The locale has to be a full locale like en-GB

email
string <email>

The email address of the consumer. This email address could be used by Active Ants, the carrier o customs in various notification messages regarding the shipments(s) related to this order.

phoneNumber
string (phoneNumber) <= 32 characters ^[\d\s\+\(\)-\.\\\/]+$

The consumer's phone number which might be used by the carrier or customs to contact the consumer regarding the shipment(s) related to this order.

vatNumber
string
fulfillFrom
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

When provided indicates the warehouse from which each orderItem must be fulfilled. When not provided the system will select the warehouse based on the warehouse strategy configuration for your company. Note that this value can also be set at orderItem-level which supercedes the specification at order-level or the warehouse strategy.

preferredShippingDate
string <date>

Allows the specification of a future date at which the order is to be shipped.

allowPartialDelivery
boolean
Default: false

When set to true the order may be split into multiple shipments in case there is insufficient stock to filfill the order in a single shipment or from a single warehouse.

onHold
boolean
Default: false

When set to true prevents the order from being shipped until released.

object

Allows the specification of arbitrary name-value pairs. note currently only the names 'extra1', 'extra2', 'extra3', 'extra4' and 'extra5' are supported and are linked to functionality (contact support for more information).

extra1
string
extra2
string
extra3
string
extra4
string
extra5
string
channelIdentifier
string (channelOrderIdentifier) <= 250 characters

The channelIdentifier is the (technical) id for the order as assigned by the external channel. For example Shopify, Amazon, Bol, Zalando, etc. may assign a unique id for communication and synchronization purposes.

currency
string (currencyCode) = 3 characters [A-Z]{3}
Default: "EUR"

Defines the currency of the order and all its orderItems. If omitted, the value EUR is assumed. The currency is used to convert the price of each orderItem to an acceptable currency when a shipment must be declaring its value to customs agencies.

object
required
object (orderTypeRelation)

Represents a relationship to an orderType resource.

object (orderTypeIdentifier)

Identifies a resource as an orderType.

id
integer
type
stringorderType
Default: "orderType"
object
self
string <uri>
object (orderItemsRelation)

Represents a relationship to multiple orderItem resources.

Array of objects (orderItemIdentification)
Array
id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
self
string <uri>
required
object (addressRelation)

Denotes the address and name where the order must be delivered, unless a pickUpPoint has been specified in which case the order will be delivered to the pick-up point instead

object (addressIdentification)

Identifies a resource as an address.

id
integer
type
required
any
Default: "address"
Value: "address"
object (addressRelation)

Optional address that can be used as billing address. When not provided it is assumed to be the same as the deliveryAddress.

object (addressIdentification)

Identifies a resource as an address.

id
integer
type
required
any
Default: "address"
Value: "address"
object (pickUpPointRelation)

Optional: specify the address of the pick-up point in case the order is to be delivered at a pick-up point. Note that the deliveryAddress is still required.

object (pickUpPointIdentifier)

Identifies a resource as an pickUpPoint.

id
integer
type
required
any
Default: "pickUpPoint"
Value: "pickUpPoint"
object (shippingMethodRelation)

Optional identifier to the shippingMethod preferred for this order. Note that this method is preferred, but not guaranteed since the method might not be available at the warehouse from where the order might be fulfilled, or the shipment may not be compatible with the preferred method. IMPORTANT: the v3 endpoints use the mainShippingMethodId as returned by the GET settings/get endpoints under /MainShippingMethods/id.

object (shippingMethodIdentifier)

Identifies a resource as a shippingMethod.

id
integer
type
any
Value: "shippingMethod"
object
self
string <uri>
Array of orderItemIdentification (object) or addressIdentification (object) or pickUpPointIdentifier (object) or orderAttachmentIdentification (object)

An array of resources included with the order, use the type property to identify the resource's type.

Array
Any of
id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
sku
required
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

channelIdentifier
string (channelOrderItemIdentifier) <= 250 characters

The channelIdentifier is the (technical) id for the orderItem as assigned by the external channel. For example Shopify, Amazon, Bol, Zalando, etc. may assign a unique id for communication and synchronization purposes.

quantity
required
integer
fulfillFrom
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

When specified indicates that the item can only be fulfilled from the indicated warehouse.

price
number decimal places <= 2

Specifies the price of a single unit of the product as sold to the consumer / recipient. Note that all products sold to consumers and shipped internationally must have a price greater than 0.00, as many customs agencies do not accept negative values. Furthermore, some carriers may impose a minimum price—typically around 1.000 in the order’s currency.

vat
number decimal places <= 3 [ 0 .. 1 )
Default: 0

This field represents the VAT percentage that was included in the price. If omitted, the value 0.000 is assumed as the percentage. The value must be between [0.000 and 1.000⟩, with an accuracy of up to three decimal places after the comma.

name
string

The name / description for this product on this orderItem. If no value is provided here, then the name of the product will be used instead whenever a name is required (for example when declaring to customs)

object (metadata)

Allows the specification of arbitrary name-value pairs. note currently only the names 'extra6' and 'extra7' are supported.

extra6
string
extra7
string
object
object (orderRelation)

Represents a relationship to an order resource.

object (orderIdentification)

Identifies a resource as an order.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
self
string <uri>
object (productRelation)

Represents a relationship to a product resource.

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object
self
string <uri>
object
self
string <uri>

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

v3/orders/:id

GET v3/orders/:id

Returns a specific order by the id assigned by Active Ants.

The endpoint also supports -to some degree- the inclusion of information of related resources. The resources that can be included in the response are limited to the orderItems, the deliveryAddress, the billingAddress and the pickUpPoint. To get the details of related entities the include parameter must be added to the URI in the following way:

  • GET {host}/v3/orders?include=orderItems will return for each order the list of orderItems with their details.
  • GET {host}/v3/orders?include=deliveryAddress,billingAddress,pickUpPoint will return all three types of addresses of each order if applicable. Note that the deliveryAddress and billingAddress are both of type address whereas the pickUpPoint is of type pickUpPoint.
Authorizations:
Bearer Token
path Parameters
id
required
string

The unique id (integer) of the order to retrieve.

Responses

Response Schema: application/vnd.api+json
object (order)

An order is a single request for fulfillment that is submitted to Active Ants. An order will be 'converted' into one or more shipments that together consist of the same quantity of products delivered at the consumer.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
externalOrderNumber
required
string (externalOrderNumber) <= 50 characters

The externalOrderNumber as specified during creation of the order.

reference
string

Optional field to store an internal reference to the order

orderedOn
string <date>

An optional field to place the date the consumer placed the order, this may be a date in the past. For example when the order was forwarded much later to the shop api.

consumerReference
string

Optional reference provided by the consumer of this order`

promotionCode
string

Any promotion code the consumer used when placing the order.

locale
required
string (localeCode) ^([a-zA-Z]+(?:-[a-zA-Z]+)?)

The locale defines (among other things) the language used in communications, inserts and possibly packaging relating to this order. The locale has to be a full locale like en-GB

email
string <email>

The email address of the consumer. This email address could be used by Active Ants, the carrier o customs in various notification messages regarding the shipments(s) related to this order.

phoneNumber
string (phoneNumber) <= 32 characters ^[\d\s\+\(\)-\.\\\/]+$

The consumer's phone number which might be used by the carrier or customs to contact the consumer regarding the shipment(s) related to this order.

vatNumber
string
fulfillFrom
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

When provided indicates the warehouse from which each orderItem must be fulfilled. When not provided the system will select the warehouse based on the warehouse strategy configuration for your company. Note that this value can also be set at orderItem-level which supercedes the specification at order-level or the warehouse strategy.

preferredShippingDate
string <date>

Allows the specification of a future date at which the order is to be shipped.

allowPartialDelivery
boolean
Default: false

When set to true the order may be split into multiple shipments in case there is insufficient stock to filfill the order in a single shipment or from a single warehouse.

onHold
boolean
Default: false

When set to true prevents the order from being shipped until released.

object

Allows the specification of arbitrary name-value pairs. note currently only the names 'extra1', 'extra2', 'extra3', 'extra4' and 'extra5' are supported and are linked to functionality (contact support for more information).

extra1
string
extra2
string
extra3
string
extra4
string
extra5
string
channelIdentifier
string (channelOrderIdentifier) <= 250 characters

The channelIdentifier is the (technical) id for the order as assigned by the external channel. For example Shopify, Amazon, Bol, Zalando, etc. may assign a unique id for communication and synchronization purposes.

currency
string (currencyCode) = 3 characters [A-Z]{3}
Default: "EUR"

Defines the currency of the order and all its orderItems. If omitted, the value EUR is assumed. The currency is used to convert the price of each orderItem to an acceptable currency when a shipment must be declaring its value to customs agencies.

object
required
object (orderTypeRelation)

Represents a relationship to an orderType resource.

object (orderTypeIdentifier)

Identifies a resource as an orderType.

id
integer
type
stringorderType
Default: "orderType"
object
self
string <uri>
object (orderItemsRelation)

Represents a relationship to multiple orderItem resources.

Array of objects (orderItemIdentification)
Array
id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
self
string <uri>
required
object (addressRelation)

Denotes the address and name where the order must be delivered, unless a pickUpPoint has been specified in which case the order will be delivered to the pick-up point instead

object (addressIdentification)

Identifies a resource as an address.

id
integer
type
required
any
Default: "address"
Value: "address"
object (addressRelation)

Optional address that can be used as billing address. When not provided it is assumed to be the same as the deliveryAddress.

object (addressIdentification)

Identifies a resource as an address.

id
integer
type
required
any
Default: "address"
Value: "address"
object (pickUpPointRelation)

Optional: specify the address of the pick-up point in case the order is to be delivered at a pick-up point. Note that the deliveryAddress is still required.

object (pickUpPointIdentifier)

Identifies a resource as an pickUpPoint.

id
integer
type
required
any
Default: "pickUpPoint"
Value: "pickUpPoint"
object (shippingMethodRelation)

Optional identifier to the shippingMethod preferred for this order. Note that this method is preferred, but not guaranteed since the method might not be available at the warehouse from where the order might be fulfilled, or the shipment may not be compatible with the preferred method. IMPORTANT: the v3 endpoints use the mainShippingMethodId as returned by the GET settings/get endpoints under /MainShippingMethods/id.

object (shippingMethodIdentifier)

Identifies a resource as a shippingMethod.

id
integer
type
any
Value: "shippingMethod"
object
self
string <uri>
Array of orderItemIdentification (object) or addressIdentification (object) or pickUpPointIdentifier (object) or orderAttachmentIdentification (object)

An array of resources included with the order, use the type property to identify the resource's type.

Array
Any of
id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
sku
required
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

channelIdentifier
string (channelOrderItemIdentifier) <= 250 characters

The channelIdentifier is the (technical) id for the orderItem as assigned by the external channel. For example Shopify, Amazon, Bol, Zalando, etc. may assign a unique id for communication and synchronization purposes.

quantity
required
integer
fulfillFrom
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

When specified indicates that the item can only be fulfilled from the indicated warehouse.

price
number decimal places <= 2

Specifies the price of a single unit of the product as sold to the consumer / recipient. Note that all products sold to consumers and shipped internationally must have a price greater than 0.00, as many customs agencies do not accept negative values. Furthermore, some carriers may impose a minimum price—typically around 1.000 in the order’s currency.

vat
number decimal places <= 3 [ 0 .. 1 )
Default: 0

This field represents the VAT percentage that was included in the price. If omitted, the value 0.000 is assumed as the percentage. The value must be between [0.000 and 1.000⟩, with an accuracy of up to three decimal places after the comma.

name
string

The name / description for this product on this orderItem. If no value is provided here, then the name of the product will be used instead whenever a name is required (for example when declaring to customs)

object (metadata)

Allows the specification of arbitrary name-value pairs. note currently only the names 'extra6' and 'extra7' are supported.

extra6
string
extra7
string
object
object (orderRelation)

Represents a relationship to an order resource.

object (orderIdentification)

Identifies a resource as an order.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
self
string <uri>
object (productRelation)

Represents a relationship to a product resource.

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object
self
string <uri>
object
self
string <uri>

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

v3/orders/:id

DELETE v3/orders/:id

Invoking this endpoint will cause the server to make an effort to cancel an order by cancelling each of its orderItems. This may succeed when there is no shipment fulfilling any of the orderItems yet. Otherwise the cancellation will be at best partially successfull. Depending on the result the server response will be slightly different. (See below and the examples)

The endpoint also supports -to some degree- the inclusion of information of related resources. The resources that can be included in the response are limited to the orderItems, the deliveryAddress, the billingAddress and the pickUpPoint. To get the details of related entities the include parameter must be added to the URI in the following way:

  • DELETE {host}/v3/orders?include=orderItems will attempt to cancel the order and return the order and all its orderItems in their new state.

Responses

Partial or Complete Cancellation

If the order was partially or completely cancelled (for example, if it was already partially fulfilled), the server will respond with a field meta.modified attribute set to true. This indicates that the order was modified. To determine which orderItems were modified as a result of this request, the server response will include an array of ids of orderItems in the element meta.modifiedItems. To determine the completeness of the cancellation, refer to the quantities on the orderItems.

No Change

If none of the orderItems of the order could be cancelled because they were already completely fulfilled, the server will still respond with a 200: OK. However, the attribute meta.modified will be set to false, indicating that the order was not modified as a result of this request.

Authorizations:
Bearer Token
path Parameters
id
required
string

The unique id (integer) of the order to (partially) cancel.

query Parameters
include
Array of strings unique
Items Enum: "orderItems" "deliveryAddress" "billingAddress" "pickUpPoint"

Comma-separated list of order related resources to include in the response under the included element

Responses

Response Schema: application/vnd.api+json
object (order)

An order is a single request for fulfillment that is submitted to Active Ants. An order will be 'converted' into one or more shipments that together consist of the same quantity of products delivered at the consumer.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
externalOrderNumber
required
string (externalOrderNumber) <= 50 characters

The externalOrderNumber as specified during creation of the order.

reference
string

Optional field to store an internal reference to the order

orderedOn
string <date>

An optional field to place the date the consumer placed the order, this may be a date in the past. For example when the order was forwarded much later to the shop api.

consumerReference
string

Optional reference provided by the consumer of this order`

promotionCode
string

Any promotion code the consumer used when placing the order.

locale
required
string (localeCode) ^([a-zA-Z]+(?:-[a-zA-Z]+)?)

The locale defines (among other things) the language used in communications, inserts and possibly packaging relating to this order. The locale has to be a full locale like en-GB

email
string <email>

The email address of the consumer. This email address could be used by Active Ants, the carrier o customs in various notification messages regarding the shipments(s) related to this order.

phoneNumber
string (phoneNumber) <= 32 characters ^[\d\s\+\(\)-\.\\\/]+$

The consumer's phone number which might be used by the carrier or customs to contact the consumer regarding the shipment(s) related to this order.

vatNumber
string
fulfillFrom
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

When provided indicates the warehouse from which each orderItem must be fulfilled. When not provided the system will select the warehouse based on the warehouse strategy configuration for your company. Note that this value can also be set at orderItem-level which supercedes the specification at order-level or the warehouse strategy.

preferredShippingDate
string <date>

Allows the specification of a future date at which the order is to be shipped.

allowPartialDelivery
boolean
Default: false

When set to true the order may be split into multiple shipments in case there is insufficient stock to filfill the order in a single shipment or from a single warehouse.

onHold
boolean
Default: false

When set to true prevents the order from being shipped until released.

object

Allows the specification of arbitrary name-value pairs. note currently only the names 'extra1', 'extra2', 'extra3', 'extra4' and 'extra5' are supported and are linked to functionality (contact support for more information).

extra1
string
extra2
string
extra3
string
extra4
string
extra5
string
channelIdentifier
string (channelOrderIdentifier) <= 250 characters

The channelIdentifier is the (technical) id for the order as assigned by the external channel. For example Shopify, Amazon, Bol, Zalando, etc. may assign a unique id for communication and synchronization purposes.

currency
string (currencyCode) = 3 characters [A-Z]{3}
Default: "EUR"

Defines the currency of the order and all its orderItems. If omitted, the value EUR is assumed. The currency is used to convert the price of each orderItem to an acceptable currency when a shipment must be declaring its value to customs agencies.

object
required
object (orderTypeRelation)

Represents a relationship to an orderType resource.

object (orderTypeIdentifier)

Identifies a resource as an orderType.

id
integer
type
stringorderType
Default: "orderType"
object
self
string <uri>
object (orderItemsRelation)

Represents a relationship to multiple orderItem resources.

Array of objects (orderItemIdentification)
Array
id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
self
string <uri>
required
object (addressRelation)

Denotes the address and name where the order must be delivered, unless a pickUpPoint has been specified in which case the order will be delivered to the pick-up point instead

object (addressIdentification)

Identifies a resource as an address.

id
integer
type
required
any
Default: "address"
Value: "address"
object (addressRelation)

Optional address that can be used as billing address. When not provided it is assumed to be the same as the deliveryAddress.

object (addressIdentification)

Identifies a resource as an address.

id
integer
type
required
any
Default: "address"
Value: "address"
object (pickUpPointRelation)

Optional: specify the address of the pick-up point in case the order is to be delivered at a pick-up point. Note that the deliveryAddress is still required.

object (pickUpPointIdentifier)

Identifies a resource as an pickUpPoint.

id
integer
type
required
any
Default: "pickUpPoint"
Value: "pickUpPoint"
object (shippingMethodRelation)

Optional identifier to the shippingMethod preferred for this order. Note that this method is preferred, but not guaranteed since the method might not be available at the warehouse from where the order might be fulfilled, or the shipment may not be compatible with the preferred method. IMPORTANT: the v3 endpoints use the mainShippingMethodId as returned by the GET settings/get endpoints under /MainShippingMethods/id.

object (shippingMethodIdentifier)

Identifies a resource as a shippingMethod.

id
integer
type
any
Value: "shippingMethod"
object
self
string <uri>
Array of orderItemIdentification (object) or addressIdentification (object) or pickUpPointIdentifier (object) or orderAttachmentIdentification (object)

An array of resources included with the order, use the type property to identify the resource's type.

Array
Any of
id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
sku
required
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

channelIdentifier
string (channelOrderItemIdentifier) <= 250 characters

The channelIdentifier is the (technical) id for the orderItem as assigned by the external channel. For example Shopify, Amazon, Bol, Zalando, etc. may assign a unique id for communication and synchronization purposes.

quantity
required
integer
fulfillFrom
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

When specified indicates that the item can only be fulfilled from the indicated warehouse.

price
number decimal places <= 2

Specifies the price of a single unit of the product as sold to the consumer / recipient. Note that all products sold to consumers and shipped internationally must have a price greater than 0.00, as many customs agencies do not accept negative values. Furthermore, some carriers may impose a minimum price—typically around 1.000 in the order’s currency.

vat
number decimal places <= 3 [ 0 .. 1 )
Default: 0

This field represents the VAT percentage that was included in the price. If omitted, the value 0.000 is assumed as the percentage. The value must be between [0.000 and 1.000⟩, with an accuracy of up to three decimal places after the comma.

name
string

The name / description for this product on this orderItem. If no value is provided here, then the name of the product will be used instead whenever a name is required (for example when declaring to customs)

object (metadata)

Allows the specification of arbitrary name-value pairs. note currently only the names 'extra6' and 'extra7' are supported.

extra6
string
extra7
string
object
object (orderRelation)

Represents a relationship to an order resource.

object (orderIdentification)

Identifies a resource as an order.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
self
string <uri>
object (productRelation)

Represents a relationship to a product resource.

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object
self
string <uri>
object
modified
boolean

Indicates if the order was modified in any way. When true the modified orderItems are listed in the modifiedItems.

object (orderItemsRelation)

Represents a relationship to multiple orderItem resources.

Array of objects (orderItemIdentification)
Array
id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
self
string <uri>

Response samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    },
  • "meta": {
    }
}

v3/orders/:id

PUT /v3/orders/:id

This endpoint enables a client to make some changes to an existing order within certain limits. The order cannot be modified after it is fulfilled in its entirety (i.e. there is nothing left to ship). The mutability of the attributes is indicated in the tables below.

Request

When submitting changes for an order, the entire order in its desired state must be submitted; otherwise, the omitted fields may be erased.

Mutable attributes on order level

attribute nullable remarks
externalOrderNumber no The new value must also be unique.
reference yes Use an empty string to erase current value.
consumerReference yes Use an empty string to erase current value.
promotionCode yes Use an empty string to erase current value.
email yes When null or omitted, noreply@activeants.nl default will be used.
locale no
phoneNumber yes
vatNumber yes
fulfillFrom yes New warehouseCode must be part of the fulfillment strategy.
preferredShippingDate yes New date must be today or later.
allowPartialDelivery yes When null or omitted, the default for the orderType will take effect.
onHold no
metadata/* yes Note that not providing the full set will erase previous data.

Immutable attributes on order level

attribute remarks
currency
channelIdentifier

Response

Upon successful modification of the order, the server responds with the complete order resource and related resources in a similar fashion as if invoked by a GET v3/orders/:id?include=orderItems,deliveryAddress,billingAddress,pickUpPoint. It is the responsibility of the caller to validate that the changes made to the order are having the expected results.

Limitations of PUT /v3/orders/:id

When using this endpoint, the following limitations apply:

  • Invoking the endpoint requires the use of the order's resource id. If not known, this can be obtained by invoking the GET v3/orders?filter[externalOrderNumber]={YOUR_ORDER_NUMBER}.
  • It is not possible to modify the orderItems.
  • It is not possible to modify the deliveryAddress, billingAddress, or pickUpPoint.
  • It is not possible to modify the related preferredShippingMethod.
  • It is not possible to modify the related orderType.
Authorizations:
Bearer Token
path Parameters
id
required
string

The unique id (integer) of the order to put.

query Parameters
include
Array of strings unique
Items Enum: "orderItems" "deliveryAddress" "billingAddress" "pickUpPoint"

Comma-separated list of order related resources to include in the response under the included element

Request Body schema: application/vnd.api+json
object (orderIdentification)

Identifies a resource as an order.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
externalOrderNumber
required
string (externalOrderNumber) <= 50 characters

The externalOrderNumber as specified during creation of the order.

reference
string

Optional field to store an internal reference to the order

orderedOn
string <date>

An optional field to place the date the consumer placed the order, this may be a date in the past. For example when the order was forwarded much later to the shop api.

consumerReference
string

Optional reference provided by the consumer of this order`

promotionCode
string

Any promotion code the consumer used when placing the order.

locale
required
string (localeCode) ^([a-zA-Z]+(?:-[a-zA-Z]+)?)

The locale defines (among other things) the language used in communications, inserts and possibly packaging relating to this order. The locale has to be a full locale like en-GB

email
string <email>

The email address of the consumer. This email address could be used by Active Ants, the carrier o customs in various notification messages regarding the shipments(s) related to this order.

phoneNumber
string (phoneNumber) <= 32 characters ^[\d\s\+\(\)-\.\\\/]+$

The consumer's phone number which might be used by the carrier or customs to contact the consumer regarding the shipment(s) related to this order.

vatNumber
string
fulfillFrom
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

When provided indicates the warehouse from which each orderItem must be fulfilled. When not provided the system will select the warehouse based on the warehouse strategy configuration for your company. Note that this value can also be set at orderItem-level which supercedes the specification at order-level or the warehouse strategy.

preferredShippingDate
string <date>

Allows the specification of a future date at which the order is to be shipped.

allowPartialDelivery
boolean
Default: false

When set to true the order may be split into multiple shipments in case there is insufficient stock to filfill the order in a single shipment or from a single warehouse.

onHold
boolean
Default: false

When set to true prevents the order from being shipped until released.

object

Allows the specification of arbitrary name-value pairs. note currently only the names 'extra1', 'extra2', 'extra3', 'extra4' and 'extra5' are supported and are linked to functionality (contact support for more information).

extra1
string
extra2
string
extra3
string
extra4
string
extra5
string

Responses

Response Schema: application/vnd.api+json
object (order)

An order is a single request for fulfillment that is submitted to Active Ants. An order will be 'converted' into one or more shipments that together consist of the same quantity of products delivered at the consumer.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
externalOrderNumber
required
string (externalOrderNumber) <= 50 characters

The externalOrderNumber as specified during creation of the order.

reference
string

Optional field to store an internal reference to the order

orderedOn
string <date>

An optional field to place the date the consumer placed the order, this may be a date in the past. For example when the order was forwarded much later to the shop api.

consumerReference
string

Optional reference provided by the consumer of this order`

promotionCode
string

Any promotion code the consumer used when placing the order.

locale
required
string (localeCode) ^([a-zA-Z]+(?:-[a-zA-Z]+)?)

The locale defines (among other things) the language used in communications, inserts and possibly packaging relating to this order. The locale has to be a full locale like en-GB

email
string <email>

The email address of the consumer. This email address could be used by Active Ants, the carrier o customs in various notification messages regarding the shipments(s) related to this order.

phoneNumber
string (phoneNumber) <= 32 characters ^[\d\s\+\(\)-\.\\\/]+$

The consumer's phone number which might be used by the carrier or customs to contact the consumer regarding the shipment(s) related to this order.

vatNumber
string
fulfillFrom
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

When provided indicates the warehouse from which each orderItem must be fulfilled. When not provided the system will select the warehouse based on the warehouse strategy configuration for your company. Note that this value can also be set at orderItem-level which supercedes the specification at order-level or the warehouse strategy.

preferredShippingDate
string <date>

Allows the specification of a future date at which the order is to be shipped.

allowPartialDelivery
boolean
Default: false

When set to true the order may be split into multiple shipments in case there is insufficient stock to filfill the order in a single shipment or from a single warehouse.

onHold
boolean
Default: false

When set to true prevents the order from being shipped until released.

object

Allows the specification of arbitrary name-value pairs. note currently only the names 'extra1', 'extra2', 'extra3', 'extra4' and 'extra5' are supported and are linked to functionality (contact support for more information).

extra1
string
extra2
string
extra3
string
extra4
string
extra5
string
channelIdentifier
string (channelOrderIdentifier) <= 250 characters

The channelIdentifier is the (technical) id for the order as assigned by the external channel. For example Shopify, Amazon, Bol, Zalando, etc. may assign a unique id for communication and synchronization purposes.

currency
string (currencyCode) = 3 characters [A-Z]{3}
Default: "EUR"

Defines the currency of the order and all its orderItems. If omitted, the value EUR is assumed. The currency is used to convert the price of each orderItem to an acceptable currency when a shipment must be declaring its value to customs agencies.

object
required
object (orderTypeRelation)

Represents a relationship to an orderType resource.

object (orderTypeIdentifier)

Identifies a resource as an orderType.

id
integer
type
stringorderType
Default: "orderType"
object
self
string <uri>
object (orderItemsRelation)

Represents a relationship to multiple orderItem resources.

Array of objects (orderItemIdentification)
Array
id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
self
string <uri>
required
object (addressRelation)

Denotes the address and name where the order must be delivered, unless a pickUpPoint has been specified in which case the order will be delivered to the pick-up point instead

object (addressIdentification)

Identifies a resource as an address.

id
integer
type
required
any
Default: "address"
Value: "address"
object (addressRelation)

Optional address that can be used as billing address. When not provided it is assumed to be the same as the deliveryAddress.

object (addressIdentification)

Identifies a resource as an address.

id
integer
type
required
any
Default: "address"
Value: "address"
object (pickUpPointRelation)

Optional: specify the address of the pick-up point in case the order is to be delivered at a pick-up point. Note that the deliveryAddress is still required.

object (pickUpPointIdentifier)

Identifies a resource as an pickUpPoint.

id
integer
type
required
any
Default: "pickUpPoint"
Value: "pickUpPoint"
object (shippingMethodRelation)

Optional identifier to the shippingMethod preferred for this order. Note that this method is preferred, but not guaranteed since the method might not be available at the warehouse from where the order might be fulfilled, or the shipment may not be compatible with the preferred method. IMPORTANT: the v3 endpoints use the mainShippingMethodId as returned by the GET settings/get endpoints under /MainShippingMethods/id.

object (shippingMethodIdentifier)

Identifies a resource as a shippingMethod.

id
integer
type
any
Value: "shippingMethod"
object
self
string <uri>
Array of orderItemIdentification (object) or addressIdentification (object) or pickUpPointIdentifier (object) or orderAttachmentIdentification (object)

An array of resources included with the order, use the type property to identify the resource's type.

Array
Any of
id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
sku
required
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

channelIdentifier
string (channelOrderItemIdentifier) <= 250 characters

The channelIdentifier is the (technical) id for the orderItem as assigned by the external channel. For example Shopify, Amazon, Bol, Zalando, etc. may assign a unique id for communication and synchronization purposes.

quantity
required
integer
fulfillFrom
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

When specified indicates that the item can only be fulfilled from the indicated warehouse.

price
number decimal places <= 2

Specifies the price of a single unit of the product as sold to the consumer / recipient. Note that all products sold to consumers and shipped internationally must have a price greater than 0.00, as many customs agencies do not accept negative values. Furthermore, some carriers may impose a minimum price—typically around 1.000 in the order’s currency.

vat
number decimal places <= 3 [ 0 .. 1 )
Default: 0

This field represents the VAT percentage that was included in the price. If omitted, the value 0.000 is assumed as the percentage. The value must be between [0.000 and 1.000⟩, with an accuracy of up to three decimal places after the comma.

name
string

The name / description for this product on this orderItem. If no value is provided here, then the name of the product will be used instead whenever a name is required (for example when declaring to customs)

object (metadata)

Allows the specification of arbitrary name-value pairs. note currently only the names 'extra6' and 'extra7' are supported.

extra6
string
extra7
string
object
object (orderRelation)

Represents a relationship to an order resource.

object (orderIdentification)

Identifies a resource as an order.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
self
string <uri>
object (productRelation)

Represents a relationship to a product resource.

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object
self
string <uri>
object
self
string <uri>

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "links": {}
}

v3/orderItems/:id

GET v3/orderItem/:id

Returns a specific orderItem by it's id.

The does not support inclusion of related resources.

Authorizations:
Bearer Token

Responses

Response Schema: application/vnd.api+json
object (orderItem)

An orderItem refers to a specific product has been purchased and must be shipped to the consumer. It is a line item that details the quantity, description, price, and other relevant information about the product.

id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
sku
required
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

channelIdentifier
string (channelOrderItemIdentifier) <= 250 characters

The channelIdentifier is the (technical) id for the orderItem as assigned by the external channel. For example Shopify, Amazon, Bol, Zalando, etc. may assign a unique id for communication and synchronization purposes.

quantity
required
integer
fulfillFrom
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

When specified indicates that the item can only be fulfilled from the indicated warehouse.

price
number decimal places <= 2

Specifies the price of a single unit of the product as sold to the consumer / recipient. Note that all products sold to consumers and shipped internationally must have a price greater than 0.00, as many customs agencies do not accept negative values. Furthermore, some carriers may impose a minimum price—typically around 1.000 in the order’s currency.

vat
number decimal places <= 3 [ 0 .. 1 )
Default: 0

This field represents the VAT percentage that was included in the price. If omitted, the value 0.000 is assumed as the percentage. The value must be between [0.000 and 1.000⟩, with an accuracy of up to three decimal places after the comma.

name
string

The name / description for this product on this orderItem. If no value is provided here, then the name of the product will be used instead whenever a name is required (for example when declaring to customs)

object (metadata)

Allows the specification of arbitrary name-value pairs. note currently only the names 'extra6' and 'extra7' are supported.

extra6
string
extra7
string
object
object (orderRelation)

Represents a relationship to an order resource.

object (orderIdentification)

Identifies a resource as an order.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
self
string <uri>
object (productRelation)

Represents a relationship to a product resource.

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object
self
string <uri>
object
self
string <uri>

Response samples

Content type
application/vnd.api+json
{}

v3/orderItems/:id

DELETE v3/orderItems/:id

Invoking this endpoint will cause the server to make an effort to cancel an orderItem. This may succeed when there are no shipments fulfilling the orderItem yet. Otherwise the cancellation will be at best partially successfull. Depending on the outcome the server response will be (sligtly) different as outlined below

Responses

Partial or Complete Cancellation

If the orderItem was partially or completely cancelled (for example, if it was already partially fulfilled), the server will respond with a field meta.modified attribute set to true. This indicates that the orderItem was modified. If the value of the quantity attribute equals zero then the orderItem was successfully cancelled. Otherwise, when the value is larger than zero, the orderItem was partially cancelled.

No Change

If the orderItem could not be cancelled, because it has already been fulfilled, the server will still respond also with a 200: OK. However, the attribute meta.modified will be set to false, indicating that the orderItem was not modified as a result of this request.

Authorizations:
Bearer Token

Responses

Response Schema: application/vnd.api+json
required
object (orderItemIdentification)

Identifies a resource as an orderItem.

id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
sku
required
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

channelIdentifier
string (channelOrderItemIdentifier) <= 250 characters

The channelIdentifier is the (technical) id for the orderItem as assigned by the external channel. For example Shopify, Amazon, Bol, Zalando, etc. may assign a unique id for communication and synchronization purposes.

quantity
required
integer
fulfillFrom
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

When specified indicates that the item can only be fulfilled from the indicated warehouse.

price
number decimal places <= 2

Specifies the price of a single unit of the product as sold to the consumer / recipient. Note that all products sold to consumers and shipped internationally must have a price greater than 0.00, as many customs agencies do not accept negative values. Furthermore, some carriers may impose a minimum price—typically around 1.000 in the order’s currency.

vat
number decimal places <= 3 [ 0 .. 1 )
Default: 0

This field represents the VAT percentage that was included in the price. If omitted, the value 0.000 is assumed as the percentage. The value must be between [0.000 and 1.000⟩, with an accuracy of up to three decimal places after the comma.

name
string

The name / description for this product on this orderItem. If no value is provided here, then the name of the product will be used instead whenever a name is required (for example when declaring to customs)

object (metadata)

Allows the specification of arbitrary name-value pairs. note currently only the names 'extra6' and 'extra7' are supported.

extra6
string
extra7
string
object
self
string <uri>
object
modified
boolean

Flag indicating if the operation affected the orderItem or if it ultimately was not able to delete any of it.

Response samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    },
  • "meta": {
    }
}

v3/orderAttachments

POST v3/orderAttachments

The POST /v3/orderAttachments endpoint allows linking an attachment to an order for printing during the picking process.

⚠ orderAttachments is part of the POST /v3/orders.

⚠ See endpoint POST /v3/orders.

Request

When submitting an orderAttachment, the order to which it will be attached must be created prior to attaching, but before the order is fulfilled.

Response

Upon successfulcreation of the orderAttachment the response will contain the created orderAttachment resource and the relation to the order. The contents of the attachment is suppressed from the response..

Limitations to POST v3/orderAttachments

There are limitations to what and when orderAttachments can be attached to orders:

  • As long as the order is not completely fulfilled and some items remain to be shipped, an orderAttachment can be added to the order. Attempting to add an orderAttachment afterwards will result in an error.
  • Only valid pdf documents can be submitted as orderAttachment.
  • Only document with a single page sizes in A4 or A5 are supported. So mixing of A4 with A5 formats is not possible in a single orderAttachment.
  • There is a file sizelimit and page limit to each orderAttachment.
Authorizations:
Bearer Token
Request Body schema: multipart/form-data
object (orderAttachmentIdentification)

Identifies a resource as an orderAttachment.

id
integer

The id is an internally assigned id of an orderAttachment. Only during and POST v3/orders or POST v3/orderAttachments is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderAttachment"
Value: "orderAttachment"
object
filename
required
string
contentType
required
string
Default: "application/pdf"
Value: "application/pdf"

MIME content type of a content property. This parameter is important because will define the manner in which contents are processed, note however that at the moment only one value is supported: application/pdf

printStrategy
string (orderAttachmentPrintStrategy)
Enum: "REQUIRED" "BEST_EFFORT"

Defines the strategy to employ when printing the orderAttachement. Defaults to REQUIRED.

value description
REQUIRED (default) Makes the printing of the orderAttachment a required step in the fulfilment of each shipment of the order.
BEST_EFFORT Makes the printing of the orderAttahment optional, meaning that when printing fails for what ever reasons the shipment will not be blocked.
externalOrderNumber
string (externalOrderNumber) <= 50 characters

To attach the orderAttachment to the correct order it is possible to provide the id of the order as one of the related items (see data.relationships.order.data.id) or provide the externalOrderNumber of the order using this attribute.

object
object (orderRelation)

Represents a relationship to an order resource.

object (orderIdentification)

Identifies a resource as an order.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object

Responses

Response Schema: application/vnd.api+json
object
object (orderAttachment)

Identifies a resource as an orderAttachment.

id
integer

The id is an internally assigned id of an orderAttachment. Only during and POST v3/orders or POST v3/orderAttachments is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderAttachment"
Value: "orderAttachment"
object
filename
required
string
contentType
required
string
Default: "application/pdf"
Value: "application/pdf"

MIME content type of a content property. This parameter is important because will define the manner in which contents are processed, note however that at the moment only one value is supported: application/pdf

printStrategy
string (orderAttachmentPrintStrategy)
Enum: "REQUIRED" "BEST_EFFORT"

Defines the strategy to employ when printing the orderAttachement. Defaults to REQUIRED.

value description
REQUIRED (default) Makes the printing of the orderAttachment a required step in the fulfilment of each shipment of the order.
BEST_EFFORT Makes the printing of the orderAttahment optional, meaning that when printing fails for what ever reasons the shipment will not be blocked.
object
object (orderRelation)

Represents a relationship to an order resource.

object (orderIdentification)

Identifies a resource as an order.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
self
string <uri>
object
self
string <uri>

Request samples

Content type
multipart/form-data
{
  "data": {
    "id": 52005678,
    "type": "orderAttachment",
    "attributes": {
      "externalOrderNumber": "#1003-UK",
      "filename": "string",
      "contentType": "application/pdf",
      "printStrategy": "REQUIRED"
    },
    "relationships": {
      "order": {
        "data": {
          "id": 24006341,
          "type": "order",
          "links": {
            "self": "https://shopapi.activeants.nl/v3/orders/24006341"
          }
        }
      }
    }
  }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {}
}

Shipments

Endpoints related to managing shipments for near-realtime notification of changes.

Note that Active Ants attempts to make a shipment for each order as quickly and as early as possible. This may lead to situations where a planned shipment cannot be completed as expected and must be adjusted. Be aware that, up until the shipment reaches the status SHIPPED, all details in the shipment are subject to change.

v3/shipments

GET v3/shipments

Returns a collection of up to 100 shipment resources, non older than 90 days, that match the provided filerting criteria and allows for iterating over pages of more shipment resources if there are more available. The endpoint supports pagination and filtering as described in the chapters below.

Pagination

The endpoint supports pagination to split the large collection of resources into smaller, more manageable chunks or pages. This helps to reduce the response size and to improve performance. The endpoint supports only cursor-based technique for pagination.

Filters

The GET v3/shipments endpoint supports filtering on the following attributes: shippedOn, orderType, status, orderId, externalOrderNumber. Each of these are explained below. Filters can be used in combination with eachother and with pagination as to allow full access to the desired subset of shipments.

Filtering on shippedOn

The results returned by this service can be filtered based on the shipping date of the shipments. To do so make use of the filter[shippedOn] parameter in the following manner:

  • GET {host}/v3/shipments?filter[shippedOn][lt]={date} will return shipments that have shipped before the provided date. Shipments that shipped on that date are not included in the results.
  • GET {host}/v3/shipments?filter[shippedOn][gt]={date} will return shipments that have shipped after the provided date. Shipments that shipped on that date are not included in the results.
  • GET {host}/v3/shipments?filter[shippedOn][gt]={date_1}&filter[shippedOn][lt]={date_2} will return shipments that have shipped between dates {date_1} and {date_1}. Shipments that shipped on either date are not included in the results.

Filtering on status

The results returned by this service can be filtered based on the status of the shipments. To do so make use of the filter[status][in] parameter in the following manner:

  • GET {host}/v3/shipments?filter[status][in]=READY_TO_SHIP,SHIPPED will return shipments that have been picked and packed and are awaiting pickup by the carrier or have been picked up by the carrier.
  • GET {host}/v3/shipments?filter[status][in]=READY_TO_PICK will return shipments that are waiting for physical processing in the warehouse.

Filtering on orderType

The endpoint allows filtering on one or more orderType values of the order(s) that form the bases of the shipments. An orderType is a required paramter on the order and determines various asects of how the order should be processed. To filter on orderType use the filter[orderType][in] query parameter as follows:

  • GET {host}/v3/shipments?filter[orderType][in]=1 will return all shipments that belong to an order with the orderType set to 1.
  • GET {host}/v3/shipments?filter[orderType][in]=5,6,7 will return all shipments that belong to an order with the orderType set to 5, 6 or 7.

Filtering on orderId, externalOrderNumber and reference

The endpoint allows filtering on both orderId, externalOrderNumber and reference of the order(s) that the shipments are created for. To filter using one or more of these filters follow the examples below:

  • GET {host}/v3/shipments?filter[orderId][in]=123 will return all shipments are created for an order with id equal to 123. To filter on externalOrderNumber use the filter[externalOrderNumber][in] query parameter as follows:
  • GET {host}/v3/shipments?filter[externalOrderNumber][in]=abc,123,1a2b will return all shipments that are created for orders with external order numbers set to corresponding values.
  • GET {host}/v3/shipments?filter[orderId][in]=123&filter[externalOrderNumber][in]=abc will return all shipments that are created for orders with orderId = 123 and externalOrderNumber=abc.
  • GET {host}/v3/shipments?filter[reference][in]=cust1,cust2,cust3 will return all shipments that are created for orders with reference set to corresponding values.

The endpoint also supports -to some degree- the inclusion of information of related resources. To get the details of related entities the include parameter must be added to the URI in the following way:

  • GET {host}/v3/shipments?include=shipmentItems will return the shipment with all shipmentItems details.

Limitations of GET v3/shipments

When using this endpoint, expect the following limits on the result set:

  • Shipments older than 90 days are not returned using this method.
  • At most 100 shipments will be returned regardless of the page[size] settings provided in the request.
  • Ordering is based on the id of the shipment in ascending order.
  • Some shipment statusses are suppressed from the results when retreiving shipments in bulk using the GET v3/shipments.
Authorizations:
Bearer Token
query Parameters
page[size]
integer ( 0 .. 100 ]
Default: 100

optional parameter indicating the size of the page, i.e. the maximum number of entities in the response.

page[cursor]
integer >= 0
Default: 0

optional parameter, excludes ?page[number] indicating the value of the cursor. Values too low will be interpreted as if ommitted. The endpoint will use the cursor as the id of the entity that was last returned and will not include it in the response to the request.

filter[status][in]
Array of strings (shipmentStatus) non-empty unique
Items Enum: "READY_TO_PICK" "READY_TO_SORT" "READY_TO_SHIP" "SHIPPED" "ERROR"
Examples:
  • filter[status][in]=READY_TO_PICK - Filter by `shipments` that are awaiting physical processing in the warehouse.
  • filter[status][in]=READY_TO_SHIP,SHIPPED - Filter by `shipments` that are either waiting to be shipped or have shipped.

A comma separated list of shipmentStatus values to filter by such as COMPLETED, CHECKING, etc.

filter[shippedOn][lt]
string <date>

Filters the response to only return items that have a value for the attribute shippedOn before the specified date.

filter[shippedOn][gt]
string <date>

Filters the response to only return items that have a value for the attribute shippedOn after the specified date.

filter[orderType][in]
Array of integers unique

A comma separated list of orderType values to filter by

filter[reference][in]
Array of strings unique

A comma separated list of reference values to filter by, each of which must be URL encoded and separated by a comma.

include
Array of strings unique
Items Value: "shipmentItems"

Comma-separated list of related resources to include into the response.

filter[orderId]
string

A comma-separated list of order id's to filter by

filter[externalOrderNumber]
string

A comma-separated list of external order numbers to filter by

Responses

Response Schema: application/vnd.api+json
Array of objects (shipment) [ 0 .. 100 ] items
Array ([ 0 .. 100 ] items)
id
integer
type
any
Value: "shipment"
object
status
string (shipmentStatus)
Enum: "READY_TO_PICK" "READY_TO_SORT" "READY_TO_SHIP" "SHIPPED" "ERROR"

The shipmentStatus provides insight into the step in the process of fulfilling a shipment within a warehouse.

status Description
READY_TO_PICK The shipment has been fully planned and awaits the picking by an operator.
READY_TO_SORT The shipment has been picked and packed and awaits sorting for the carrier.
READY_TO_SHIP The shipment has been sorted and awaits pick-up by the carrier.
SHIPPED The shipment has been handed over to the carrier and has dispatched from the warehouse.
ERROR An issue with the shipment has occurred, for example some labelling issue. The shipments is awaiting intervention from an operator.
readyToPickOn
string <date>

Indicates the date the shipment was fully planned and ready to be picked in a warehouse of Active Ants.

readyToShipOn
string <date>

Indicates the date the shipment was fully picked and packed in a warehouse of Active Ants, awaiting dispatch.

shippedOn
string <date>

Indicates the date the shipment has shipped from the warehouse of Active Ants.

warehouseCode
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

The code for the warehouse used to uniquely refer to an Active Ants warehouse.

The following warehouses are currently defined:

code country city customs region
BW Belgium Willebroek EU - Common Customs Tariff
DD Germany Dorsten EU - Common Customs Tariff
GN Great Brittain Northampton GB - UK Global Tariff
NN The Netherlands Nieuwegein EU - Common Customs Tariff
NR The Netherlands Roosendaal EU - Common Customs Tariff
FP France Pantin EU - Common Customs Tariff
weight
integer

The (actual) weight of the shipment in grams. This weight includes the products, packing materials and inserts.

invoicingWeight
integer

The weight used to calculate the tariff for this shipment. For some carriers this deviates from the (actual) weight as these carriers apply a 'volumetric' or 'dimensional' weight which is the largest of the actual weight and the dimensional weight of the shipment.

basketPicture
string <uri>
object
carrier
string

SOON Provides insight into which carrier is providing the transport of the shipment to the deliveryAddress or pickUpPointAddress. For example FEDEX, POSTNL, BPOST, DHL, CORREOS, POSTE ITALIANE, BRING, ROYAL MAIL, and many more.

number
integer
stage
string (shipmentTrackingStage)
Enum: "LABELLED" "ACCEPTED" "SORTED" "IN_DELIVERY" "AT_PUP" "DELIVERED" "1ST_ATTEMPT"

The shipmentTrackingStage provide a generalized set of tracking well-defined stages for shipments.

The shipmentTrackingStage are generalized over all carriers. Each carrier can and has defined their own set of stages for tracking their consignments. To accommodate the main stages that are supported by most carriers the shipmentTrackingStages generalizes the carrier-specific stages. This could mean that some details of a particular carrier are not reflected by this enumeration.

stage id Description
NEW 0 The shipment is newly created and has not been assigned to a carrier yet.
LABELED 1 A label has created for the shipment.
ACCEPTED 2 The shipment has been accepted, received and scanned by the carrier.
SORTED 3 The shipment is been sorted before delivery.
IN_TRANSIT 4 The shipment is being delivered, but has not been delivered yet.
ATTEMPTED 8 or 10 An unsuccessful attempt to deliver the shipment has been made.
AVAILABLE_FOR_PICKUP 5 The shipment has been delivered to the pick up point for the recipient to collect.
DELIVERED 7 The shipment has been delivered.
RETURNED 19 The shipment has been returned to the sender after a failing be delivered.
TRACKED_EXTERNALLY 18 There is no tracking information being shared with Active Ants for this shipment.

Note the id column corresponds to the v2 endpoint values for the stage

status
string
Enum: "OK" "ERROR" "WARNING"
url
string <uri>
Array of objects
Array
number
string
parcelNumber
string

The parcel number as assigned by the carrier

trackingUrl
string <uri>

A tracking url specific to this collo

returnLabel
string
object

Repeats the metadata as specified on the order.

extra1
string
extra2
string
extra3
string
extra4
string
extra5
string
object
object (orderRelation)

Represents a relationship to an order resource.

object (orderIdentification)

Identifies a resource as an order.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
self
string <uri>
object (orderTypeRelation)

Represents a relationship to an orderType resource.

object (orderTypeIdentifier)

Identifies a resource as an orderType.

id
integer
type
stringorderType
Default: "orderType"
object
self
string <uri>
object (shipmentItemsRelation)

Represents a relationship to multiple shipmentItem resources.

Array of objects (shipmentItemIdentifier)
Array
id
integer
type
any
Value: "shipmentItem"
object
self
string <uri>
object (shippingMethodRelation)

Represents a relationship to a shippingMethod resource.

object (shippingMethodIdentifier)

Identifies a resource as a shippingMethod.

id
integer
type
any
Value: "shippingMethod"
object
self
string <uri>
Array of shipmentItemIdentifier (object)
Array
Any of
id
integer
type
any
Value: "shipmentItem"
object
sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

quantity
integer >= 0
lotNumber
string (lotNumber) ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

A lot number is a unique identification number assigned to a specific batch or lot of a product during the manufacturing process. It is used to track and trace the product's manufacturing and distribution history, including when and where it was produced, which raw materials were used, and to which customers it was shipped.

Lot numbers can be alphanumeric and may include information such as the date and time of production, the location of production, and the machine or equipment used. They are often printed on the product's packaging or label, as well as on associated documentation such as batch records and certificates of analysis.

expirationDate
string <date>
serialNumbers
Array of strings[ items non-empty ]
object
object (orderItemRelation)

Represents a relationship to an orderItem resource.

object (orderItemIdentification)

Identifies a resource as an orderItem.

id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
self
string <uri>
object (productRelation)

Represents a relationship to a product resource.

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object (shipmentRelation)

Represents a relationship to a shipment resource.

object (shipmentIdentifier)

Identifies a resource as a shipment.

id
integer
type
any
Value: "shipment"
object
self
string <uri>
object
self
string <uri>
object

Pagination links that provided for convenience and in compliancy to the json:api specification for pagination.

self
string <uri>
next
string <uri>
first
string <uri>

Response samples

Content type
application/vnd.api+json
{}

v3/shipments/:id

GET v3/shipments/:id

This endpoint returns a single shipment resource. The request requires a path parameter which is the id of the shipment to fetch. It returns only a shipment if it can be be found and the associated id belongs to a shipment that was generated as a result of an order.

The endpoint also supports -to some degree- the inclusion of information of related resources. To get the details of related entities the include parameter must be added to the URI in the following way:

  • GET {host}/v3/shipments?include=shipmentItems will return the shipment with all shipmentItems details.

Limitations of GET v3/shipments/:id

When using this endpoint, expect the following limits on the result set

  • Shipments older than 90 days are not returned using this method.
  • Some shipment statusses are blocked when retreiving shipments in bulk using the GET v3/shipments but when requesting the shipment through GET v3/shipments/:id direcly may yield results.
Authorizations:
Bearer Token
path Parameters
id
required
string

The unique id (integer) of the shipment to retrieve.

query Parameters
include
Array of strings unique
Items Value: "shipmentItems"

Comma-separated list of related resources to include into the response.

Responses

Response Schema: application/vnd.api+json
object (shipment)

Represents a single shipment from a single warehouse that was generated for an order.

id
integer
type
any
Value: "shipment"
object
status
string (shipmentStatus)
Enum: "READY_TO_PICK" "READY_TO_SORT" "READY_TO_SHIP" "SHIPPED" "ERROR"

The shipmentStatus provides insight into the step in the process of fulfilling a shipment within a warehouse.

status Description
READY_TO_PICK The shipment has been fully planned and awaits the picking by an operator.
READY_TO_SORT The shipment has been picked and packed and awaits sorting for the carrier.
READY_TO_SHIP The shipment has been sorted and awaits pick-up by the carrier.
SHIPPED The shipment has been handed over to the carrier and has dispatched from the warehouse.
ERROR An issue with the shipment has occurred, for example some labelling issue. The shipments is awaiting intervention from an operator.
readyToPickOn
string <date>

Indicates the date the shipment was fully planned and ready to be picked in a warehouse of Active Ants.

readyToShipOn
string <date>

Indicates the date the shipment was fully picked and packed in a warehouse of Active Ants, awaiting dispatch.

shippedOn
string <date>

Indicates the date the shipment has shipped from the warehouse of Active Ants.

warehouseCode
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

The code for the warehouse used to uniquely refer to an Active Ants warehouse.

The following warehouses are currently defined:

code country city customs region
BW Belgium Willebroek EU - Common Customs Tariff
DD Germany Dorsten EU - Common Customs Tariff
GN Great Brittain Northampton GB - UK Global Tariff
NN The Netherlands Nieuwegein EU - Common Customs Tariff
NR The Netherlands Roosendaal EU - Common Customs Tariff
FP France Pantin EU - Common Customs Tariff
weight
integer

The (actual) weight of the shipment in grams. This weight includes the products, packing materials and inserts.

invoicingWeight
integer

The weight used to calculate the tariff for this shipment. For some carriers this deviates from the (actual) weight as these carriers apply a 'volumetric' or 'dimensional' weight which is the largest of the actual weight and the dimensional weight of the shipment.

basketPicture
string <uri>
object
carrier
string

SOON Provides insight into which carrier is providing the transport of the shipment to the deliveryAddress or pickUpPointAddress. For example FEDEX, POSTNL, BPOST, DHL, CORREOS, POSTE ITALIANE, BRING, ROYAL MAIL, and many more.

number
integer
stage
string (shipmentTrackingStage)
Enum: "LABELLED" "ACCEPTED" "SORTED" "IN_DELIVERY" "AT_PUP" "DELIVERED" "1ST_ATTEMPT"

The shipmentTrackingStage provide a generalized set of tracking well-defined stages for shipments.

The shipmentTrackingStage are generalized over all carriers. Each carrier can and has defined their own set of stages for tracking their consignments. To accommodate the main stages that are supported by most carriers the shipmentTrackingStages generalizes the carrier-specific stages. This could mean that some details of a particular carrier are not reflected by this enumeration.

stage id Description
NEW 0 The shipment is newly created and has not been assigned to a carrier yet.
LABELED 1 A label has created for the shipment.
ACCEPTED 2 The shipment has been accepted, received and scanned by the carrier.
SORTED 3 The shipment is been sorted before delivery.
IN_TRANSIT 4 The shipment is being delivered, but has not been delivered yet.
ATTEMPTED 8 or 10 An unsuccessful attempt to deliver the shipment has been made.
AVAILABLE_FOR_PICKUP 5 The shipment has been delivered to the pick up point for the recipient to collect.
DELIVERED 7 The shipment has been delivered.
RETURNED 19 The shipment has been returned to the sender after a failing be delivered.
TRACKED_EXTERNALLY 18 There is no tracking information being shared with Active Ants for this shipment.

Note the id column corresponds to the v2 endpoint values for the stage

status
string
Enum: "OK" "ERROR" "WARNING"
url
string <uri>
Array of objects
Array
number
string
parcelNumber
string

The parcel number as assigned by the carrier

trackingUrl
string <uri>

A tracking url specific to this collo

returnLabel
string
object

Repeats the metadata as specified on the order.

extra1
string
extra2
string
extra3
string
extra4
string
extra5
string
object
object (orderRelation)

Represents a relationship to an order resource.

object (orderIdentification)

Identifies a resource as an order.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
self
string <uri>
object (orderTypeRelation)

Represents a relationship to an orderType resource.

object (orderTypeIdentifier)

Identifies a resource as an orderType.

id
integer
type
stringorderType
Default: "orderType"
object
self
string <uri>
object (shipmentItemsRelation)

Represents a relationship to multiple shipmentItem resources.

Array of objects (shipmentItemIdentifier)
Array
id
integer
type
any
Value: "shipmentItem"
object
self
string <uri>
object (shippingMethodRelation)

Represents a relationship to a shippingMethod resource.

object (shippingMethodIdentifier)

Identifies a resource as a shippingMethod.

id
integer
type
any
Value: "shippingMethod"
object
self
string <uri>
Array of shipmentItemIdentifier (object)
Array
Any of
id
integer
type
any
Value: "shipmentItem"
object
sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

quantity
integer >= 0
lotNumber
string (lotNumber) ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

A lot number is a unique identification number assigned to a specific batch or lot of a product during the manufacturing process. It is used to track and trace the product's manufacturing and distribution history, including when and where it was produced, which raw materials were used, and to which customers it was shipped.

Lot numbers can be alphanumeric and may include information such as the date and time of production, the location of production, and the machine or equipment used. They are often printed on the product's packaging or label, as well as on associated documentation such as batch records and certificates of analysis.

expirationDate
string <date>
serialNumbers
Array of strings[ items non-empty ]
object
object (orderItemRelation)

Represents a relationship to an orderItem resource.

object (orderItemIdentification)

Identifies a resource as an orderItem.

id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
self
string <uri>
object (productRelation)

Represents a relationship to a product resource.

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object (shipmentRelation)

Represents a relationship to a shipment resource.

object (shipmentIdentifier)

Identifies a resource as a shipment.

id
integer
type
any
Value: "shipment"
object
self
string <uri>
object
self
string <uri>
object
self
string <uri>

Response samples

Content type
application/vnd.api+json
{}

Returns

v3/returnItems

GET v3/returnItems

The GET v3/returnItems endpoint returns all returns that have been processed by one of the warehouses of Active Ants. Returns that have been delivered to, but not processed by, Active Ants are not returned by this endpoint yet until these returns are processed.

Pagination

The endpoint supports pagination to split the large collection of resources into smaller, more manageable chunks or pages. This helps to reduce the response size and to improve performance. The endpoint supports only cursor-based technique for pagination

Filters

The GET v3/returnItem endpoint supports filtering on processedOn. Each of these are explained below. Filters can be used in combination with eachother and with pagination to allow full access to the desired subset of returnItems.

Attribute restockOn and the filters filter[restockOn][before] and filter[restockOn][after] are under development.

Filtering on processedOn

The results returned by this service can be filtered based on the date the returnItem was processed in the warehouse. To do so make use of the filter[processedOn] parameter in the following manner:

  • GET {host}/v3/returnItems?filter[processedOn][lt]={date} will return returned items that have been created before the provided date. Returned items that has been processed on that date are not included in the results.
  • GET {host}/v3/returnItems?filter[processedOn][gt]={date} will return returned items that have been created after the provided date. Returned items that have been processed on that date are not included in the results.
  • GET {host}/v3/returnItems?filter[processedOn][gt]={date_1}&filter[processedOn][lt]={date_2} will return returned itemsthat have created between dates {date_1} and {date_1}. Returned items that have been processed on either date are not included in the results.

There are currently no resources to include in the response.

Limitations of GET v3/returnItems

  • At most 100 returnItems resources are returned regardless of the value provided by the page[size] query parameter.
  • Ordering is by id and in ascending order.
Authorizations:
Bearer Token
query Parameters
filter[processedOn][gt]
string <date>
Example: filter[processedOn][gt]=2023-01-01

Filters the response to only return items that have been processed after the specified date.

filter[processedOn][lt]
string <date>
Example: filter[processedOn][lt]=2023-01-01

Filters the response to only return items that have been processed before the specified date.

Responses

Response Schema: application/vnd.api+json
Array of objects (returnItem)
Array
id
integer
type
any
Value: "returnItem"
object
sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

quantity
integer
condition
string (returnItemCondition)
Enum: "RETURN" "DAMAGED"

Defines the condition the returnItem arrived in at the warehouse. The following values are supported:

value description
RETURN The item was returned and will be added to the pickable stock as soon as possible
DAMAGED The item was returned and damaged, meaning that the item cannot be added to the pickable stock
UNKNOWN The condition could not be provided or is irrellevant.
processedOn
string <date-time>

Specifies the date the returnItem was processed and registered in the warehouse. Note that the item might have been delivered to that warehouse prior to this date.

processedIn
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

Specifies the warehouseCode where the returnItem has been processed.

restockIn
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

Specifies the warehouseCode where the returnItem will be restocked in. For damaged and scrapped returns this will be the warehouse were the item will remain until collected.

restockOn
string <date-time>

Specifies the date the returnItem was put back on stock.

comment
string
redeliver
boolean
externalOrderNumber
string (externalOrderNumber) <= 50 characters

The externalOrderNumber as specified during creation of the order.

object
object (orderRelation)

Represents a relationship to an order resource.

object (orderIdentification)

Identifies a resource as an order.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
self
string <uri>
object (orderItemRelation)

Represents a relationship to an orderItem resource.

object (orderItemIdentification)

Identifies a resource as an orderItem.

id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
self
string <uri>
object (productRelation)

Represents a relationship to a product resource.

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object (returnRelation)

Link to the 'parent' return resource which provides insights into the other returnItems that were processed together.

object (returnIdentifier)

Identifies a resource as a return.

id
integer
type
any
Default: "return"
Value: "return"
object
self
string <uri>
object (returnAuthorizationItemRelation)

(optionally) refers to a returnAuthorizationItem that was linked to this returnItem during the processing of the return.

object (returnAuthorizationIdentifier)

Identifies a resource as a returnAuthorizationItem.

id
integer
type
any
Default: "returnAuthorizationItem"
Value: "returnAuthorizationItem"
object
self
string <uri>
object (returnReasonRelation)

Indicates the reason for the return

object (returnReasonIdentifier)

Identifies a resource as a returnReason.

id
integer
type
any
Default: "returnReason"
Value: "returnReason"
object
self
string <uri>
object (shipmentItemRelation)

Links to the shipmentItem that initially shipped out the returned item(s).

object (shipmentItemIdentifier)

Identifies a resource as a shipmentItem.

id
integer
type
any
Value: "shipmentItem"
object
self
string <uri>
object
self
string <uri>
object

Pagination links that provided for convenience and in compliancy to the json:api specification for pagination.

self
string <uri>
next
string <uri>
first
string <uri>

Response samples

Content type
application/vnd.api+json
{}

Inbounds

v3/inbounds/:id

GET v3/inbounds/:id

Allows the retreival of a specific inbound and its related details.

The endpoint also supports the inclusion of information of its related inboundItems negating the need to access these directly.

  • GET {host}/v3/inbounds?include=inboundItems will return for each inbound the list of inboundItems with their details.
Authorizations:
Bearer Token
path Parameters
id
required
string

The unique id (integer) of the inbound to retrieve.

query Parameters
include
Array of strings unique
Items Value: "inboundItems"
Examples:
  • include=inboundItems - Include `inboundItems`

Comma-separated list of inbound related resources to include in the response under the inbound element. Possible values are inboundItems.

Responses

Response Schema: application/vnd.api+json
object (inbound)

In the context of Active Ants, an inbound, is a consignment of goods received by or in the process of being received by a warehouse.

id
integer
type
any
Value: "inbound"
object
reference
string

Shorthand reference of the inbound.

status
string (inboundStatus)
Enum: "PROCESSING" "CHECKING" "CHECKED" "COMPLETED"

The states of an inbound are

State Description
PROCESSING The initial stage of the inbound in which SKUs are being counted and moved from the pallets to warehouse locations. At this moment SKUs are not counted as stock.
CHECKING All SKUs have been counted and placed on warehouse locations. When th quantities on the inbound match those on the inboundPackingSlip the locations contianint that SKU are released and counted towards available stock levels. All SKUs with differences must first be checked.
CHECKED All totals of the SKUs have checked and any differences between the inbound and inboundPackingSlip have been confirmed or corrected. Some misplaced SKUs might still be added to the inbound until it is CLOSED.
COMPLETED The inbound is completed and no more changes can be made to the data."
receivedIn
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

Indicates the warehouse where the inbound is received.

createdOn
string <date-time>

Timestamp of when the inbound was created which typically coincides with the PROCESSING status.

checkingOn
string <date-time>

Timestamp of when the inbound reached the CHECKING status.

completedOn
string <date-time>

Timestamp of when the inbound reached the COMPLETED status

object
object (inboundPackingSlipRelations)

An inbound can only be linked to at most one inboundPackingSlip which is used to determine the completeness of the inbound. If no inboundPackingSlip was linked, then the completeness of the inbound can not be verified and is assumed to be correct.

object (inboundPackingSlipIdentification)

Identifies a resource as a inboundPackingSlip.

id
integer

The id is an internally assigned id of a inboundPackingSlip. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "inboundPackingSlip"
Value: "inboundPackingSlip"
object
self
string <uri>
Array of inboundItemIdentification (object)
Array
Any of
id
integer
type
any
Value: "inboundItem"
object
quantity
integer > 0

The quantity of the sku received. Note that the same sku could appear multiple times on the inbound depending on how the items have been unpacked and counted.

sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

lotNumber
string (lotNumber) ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

A lot number is a unique identification number assigned to a specific batch or lot of a product during the manufacturing process. It is used to track and trace the product's manufacturing and distribution history, including when and where it was produced, which raw materials were used, and to which customers it was shipped.

Lot numbers can be alphanumeric and may include information such as the date and time of production, the location of production, and the machine or equipment used. They are often printed on the product's packaging or label, as well as on associated documentation such as batch records and certificates of analysis.

expirationDate
string <date>

If applicable, the

object
object (productRelation)

Links to the product that was recieved as part of this inboundItem

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object (inboundPackingSlipItemRelation)

Links to the inboundPackingSlipItem that was expecting this inboundItem.

object (inboundPackingSlipItemIdentifier)

Identifies a resource as a inboundPackingSlipItem.

id
integer

The id is an internally assigned id of a inboundPackingSlipItem. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Value: "inboundPackingSlipItem"
object
self
string <uri>
object
self
string <uri>
object
self
string <uri>

Response samples

Content type
application/vnd.api+json
{}

v3/inbounds

GET v3/inbounds

Allows the retreival of multiple inbounds and their related details. This endpoint support pagination and various filters as indicated below.

Pagination

The endpoint supports pagination to split the large collection of resources into smaller, more manageable chunks or pages. This helps to reduce the response size and to improve performance. The endpoint supports only cursor-based technique for pagination.

Filters

The GET v3/inbounds endpoint supports filtering on the following attributes: status.

Filtering on status

The end point allows to set a filter on the status of the inbounds. The filter accepts multiple status values, each of which must be URL encoded and separated by a comma. Be aware that the status values must be URL encoded to avoid being interpreted incorrecly.

  • GET {host}/v3/inbounds?filter[status][in]=ABC,DEF will return the inbounds with status ABC and DEF.
  • GET {host}/v3/inbounds?filter[status][in]=ABC%2CDEF will return the inbounds with the status ABC,DEF.

The endpoint also supports the inclusion of information of its related inboundItems negating the need to access these directly. GET {host}/v3/inbounds?include=inboundItems will return for each inbound the list of inboundItems with their details.

Limitations of GET v3/inbounds

When using this endpoint, expect the following limits on the result set

  • At most 100 inbounds will be returned regardless of the page[size] settings provided in the request.
  • Ordering is based on the id of the inbound in ascending order.
Authorizations:
Bearer Token
query Parameters
filter[status][in]
Array of strings (inboundStatus) non-empty unique
Items Enum: "PROCESSING" "CHECKING" "CHECKED" "COMPLETED"
Examples:
  • filter[status][in]=COMPLETED - Filter by `inbounds` that have completed and have `COMPLETED`
  • filter[status][in]=PROCESING,CHECKING,CHECKED - Filter by `inbounds` not yet complete with statuses `PROCESSING`, `CHECKING` or `CHECKED`

A comma separated list of inboundStatus values to filter by such as COMPLETED, CHECKING, etc.

include
Array of strings unique
Items Value: "inboundItems"
Examples:
  • include=inboundItems - Include `inboundItems`

Comma-separated list of inbound related resources to include in the response under the inbound element. Possible values are inboundItems.

Responses

Response Schema: application/vnd.api+json
Array of objects (inbound)
Array
id
integer
type
any
Value: "inbound"
object
reference
string

Shorthand reference of the inbound.

status
string (inboundStatus)
Enum: "PROCESSING" "CHECKING" "CHECKED" "COMPLETED"

The states of an inbound are

State Description
PROCESSING The initial stage of the inbound in which SKUs are being counted and moved from the pallets to warehouse locations. At this moment SKUs are not counted as stock.
CHECKING All SKUs have been counted and placed on warehouse locations. When th quantities on the inbound match those on the inboundPackingSlip the locations contianint that SKU are released and counted towards available stock levels. All SKUs with differences must first be checked.
CHECKED All totals of the SKUs have checked and any differences between the inbound and inboundPackingSlip have been confirmed or corrected. Some misplaced SKUs might still be added to the inbound until it is CLOSED.
COMPLETED The inbound is completed and no more changes can be made to the data."
receivedIn
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

Indicates the warehouse where the inbound is received.

createdOn
string <date-time>

Timestamp of when the inbound was created which typically coincides with the PROCESSING status.

checkingOn
string <date-time>

Timestamp of when the inbound reached the CHECKING status.

completedOn
string <date-time>

Timestamp of when the inbound reached the COMPLETED status

object
object (inboundPackingSlipRelations)

An inbound can only be linked to at most one inboundPackingSlip which is used to determine the completeness of the inbound. If no inboundPackingSlip was linked, then the completeness of the inbound can not be verified and is assumed to be correct.

object (inboundPackingSlipIdentification)

Identifies a resource as a inboundPackingSlip.

id
integer

The id is an internally assigned id of a inboundPackingSlip. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "inboundPackingSlip"
Value: "inboundPackingSlip"
object
self
string <uri>
Array of inboundItemIdentification (object)
Array
Any of
id
integer
type
any
Value: "inboundItem"
object
quantity
integer > 0

The quantity of the sku received. Note that the same sku could appear multiple times on the inbound depending on how the items have been unpacked and counted.

sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

lotNumber
string (lotNumber) ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

A lot number is a unique identification number assigned to a specific batch or lot of a product during the manufacturing process. It is used to track and trace the product's manufacturing and distribution history, including when and where it was produced, which raw materials were used, and to which customers it was shipped.

Lot numbers can be alphanumeric and may include information such as the date and time of production, the location of production, and the machine or equipment used. They are often printed on the product's packaging or label, as well as on associated documentation such as batch records and certificates of analysis.

expirationDate
string <date>

If applicable, the

object
object (productRelation)

Links to the product that was recieved as part of this inboundItem

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object (inboundPackingSlipItemRelation)

Links to the inboundPackingSlipItem that was expecting this inboundItem.

object (inboundPackingSlipItemIdentifier)

Identifies a resource as a inboundPackingSlipItem.

id
integer

The id is an internally assigned id of a inboundPackingSlipItem. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Value: "inboundPackingSlipItem"
object
self
string <uri>
object
self
string <uri>
object

Pagination links that provided for convenience and in compliancy to the json:api specification for pagination.

self
string <uri>
next
string <uri>
first
string <uri>

Response samples

Content type
application/vnd.api+json
{}

v3/inboundItems/:id

GET v3/inboundItems/:id

Authorizations:
Bearer Token
path Parameters
id
required
string

The unique id (integer) of the inboundItem to retrieve.

Responses

Response Schema: application/vnd.api+json
id
integer
type
any
Value: "inboundItem"
object
quantity
integer > 0

The quantity of the sku received. Note that the same sku could appear multiple times on the inbound depending on how the items have been unpacked and counted.

sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

lotNumber
string (lotNumber) ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

A lot number is a unique identification number assigned to a specific batch or lot of a product during the manufacturing process. It is used to track and trace the product's manufacturing and distribution history, including when and where it was produced, which raw materials were used, and to which customers it was shipped.

Lot numbers can be alphanumeric and may include information such as the date and time of production, the location of production, and the machine or equipment used. They are often printed on the product's packaging or label, as well as on associated documentation such as batch records and certificates of analysis.

expirationDate
string <date>

If applicable, the

object
object (productRelation)

Links to the product that was recieved as part of this inboundItem

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object (inboundPackingSlipItemRelation)

Links to the inboundPackingSlipItem that was expecting this inboundItem.

object (inboundPackingSlipItemIdentifier)

Identifies a resource as a inboundPackingSlipItem.

id
integer

The id is an internally assigned id of a inboundPackingSlipItem. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Value: "inboundPackingSlipItem"
object
self
string <uri>
object
self
string <uri>

Response samples

Content type
application/vnd.api+json
{}

InboundPackingSlips

v3/inboundPackingSlips

GET v3/inboundPackingSlips

Allows the retrieval of inboundPackingSlips and their current status. This endpoint support pagination and various filters as indicated below.

Pagination

The endpoint supports pagination to split the large collection of resources into smaller, more manageable chunks or pages. This helps to reduce the response size and to improve performance. The endpoint supports only the cursor-based technique for pagination.

Filters

The GET v3/inboundPackingSlips endpoint supports filtering on the following attributes: status, receivedOn and completedOn. Each of these are explained below. Filters can be used in combination with each other and with pagination to allow full access to the desired subset of inboundPackingSlip resources.

Filtering on status

The end point allows to set a filter on the current status of inboundPackingSlips. For more details on the various statusses see inboundPackingSlipStatus.

  • GET {host}/v3/inboundPackingSlips?filter[status][in]=EXPECTED,COMPLETED will return all inboundPackingSlips that have either the status EXPECTED or COMPLETED.

Filtering on receivedOn

To filter inboundPackingSlips for which the inbound has been received before or after a particular date it is possible to specify the filter[receivedOn][lt] and filter[receivedOn][lt]. The received on date represents the date at which the inbound has started.

Filtering on completedOn

To filter inboundPackingSlips for which the inbound has been completely processed and completed before or after a particular date it is possible to specify the filter[completedOn][lt] and filter[completedOn][lt]. The value of the completedOn attribute represents the date at which the inbound was completed and no further items are expected.

The endpoint also supports -to some degree- the inclusion of information of related resources. The resources that can be included in the response are limited to inboundPackingSlipItems. To get the details of related entities included in the response make use of the include query-parameter in the following way:

  • GET {host}/v3/inboundPackingSlips?include=inboundPackingSlipItems will return for each inboundPackingSlip the list of inboundPackingSlipItems with their details.

Limitations of GET v3/inboundPackingSlips

When using this endpoint, expect the following limits on the result set

  • inboundPackingSlips older than 90 days are not returned using this method.
  • At most 100 inboundPackingSlips will be returned regardless of the page[size] settings provided in the request.
  • Ordering is based on the id of the inboundPackingSlip in ascending order.
Authorizations:
Bearer Token
query Parameters
include
Array of strings unique
Items Value: "inboundPackingSlipItems"
Examples:
  • include=inboundPackingSlipItems - Include `inboundPackingSlipItems`

Comma-separated list of inboundPackingSlip related resources to include in the response under the included element

page[cursor]
integer >= 0
Default: 0

optional parameter, excludes ?page[number] indicating the value of the cursor. Values too low will be interpreted as if ommitted. The endpoint will use the cursor as the id of the entity that was last returned and will not include it in the response to the request.

page[size]
integer ( 0 .. 100 ]
Default: 100

optional parameter indicating the size of the page, i.e. the maximum number of entities in the response.

filter[receivedOn][gt]
string <date>
Examples:
  • filter[receivedOn][gt]=2024-05-01 - Received after `2024-05-01`

Filters the response to only return items that have a value for the attribute receivedOn after the specified date. Note that both filter[receivedOn][after] and filter[receivedOn][gt] constitute same filter.

filter[receivedOn][lt]
string <date>
Examples:
  • filter[receivedOn][lt]=2024-11-12 - Received before `2024-11-12`

Filters the response to only return items that have a value for the attribute receivedOn before the specified date. Note that both filter[receivedOn][before] and filter[receivedOn][lt] constitute same filter.

filter[completedOn][gt]
string <date>
Examples:
  • filter[completedOn][gt]=2024-05-01 - Completed after `2024-05-01`

Filters the response to only return items that have a value for the attribute completedOn after the specified date. Note that filter[completedOn][after] and filter[completedOn][gt] are synonymous.

filter[completedOn][lt]
string <date>
Examples:
  • filter[completedOn][lt]=2024-11-12 - Completed before `2024-11-12`

Filters the response to only return items that have a value for the attribute completedOn before the specified date. Note that both filter[completedOn][before] and filter[completedOn][lt] constitute same filter.

filter[status][in]
Array of strings (inboundPackingSlipStatus) non-empty unique
Items Enum: "EXPECTED" "IN_PROGRESS" "CHECKING" "COMPLETED"
Examples:
  • filter[status][in]=COMPLETED - Filter by `inboundPackingSlips` with status `COMPLETED`
  • filter[status][in]=IN_PROGRESS,CHECKING,CHECKED - Filter by `inboundPackingSlips` with statuses `IN_PROGRESS`, `CHECKING` or `CHECKED`

A comma separated list of inboundPackingSlips statuses.

Responses

Response Schema: application/vnd.api+json
Array of objects (inboundPackingSlip)
Array
id
integer

The id is an internally assigned id of a inboundPackingSlip. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "inboundPackingSlip"
Value: "inboundPackingSlip"
object
expectedIn
required
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

Indicates the warehouse the products are expected in. This is a required field and must match the warehouse where the inbound will be processed as this warehouse is only able to see the packingSlips matching their warehouse.

expectedOn
string <date>

Allows specifying the date at which the inbound shipment related to this packing slip is expected to arrive at the warehouse. This date helps with apactiy planning

receivedOn
string <date-time>

Indicates the moment the packing slip was coupled to an inbound shipment.

completedOn
string <date-time>

Indicates the moment the inbound shipment was completed and verified, signalling tha tthe packing slip is also marked as COMPLETED.

reference
string

A unique reference for the packingSlip.

status
string (inboundPackingSlipStatus)
Enum: "EXPECTED" "IN_PROGRESS" "CHECKING" "COMPLETED"

The inboundPackingSlipStatus describes the life-cycle of packing slip.

All locations have been classified to the one of the following types:

value description
EXPECTED This status indicates that the inbound shipment is not (yet) being processed. It is still possible to make amendments to the inboundPackingSlip.
IN_PROGRESS The items of the inboundPackingSlip are being processed. The inbound has not been completed yet therefor the quantities on the inboundPackingSlip are not final.
CHECKING All the goods of the inbound have been registered, but before the packingslip is COMPLETED it is being checked. Checking occurs when differences between the inboundPackingSlip and the inbound have been identified. Products that are correctly received are released for ordering.
CHECKED The ibound related to this inboundPackingSlip has been checked meaning that all locations containing sku for which a different quantity was received than expected have been recounted. Since the moment of the last check there is a timewindow of 2 hours before the inbound is automatically COMPLETED making the inboundPackinSlip also COMPLETED.
COMPLETED The inbound related to this inboundPackingSlip has been completed and deviations have been checked and verified. There are no validation steps to follow and all products that have been received have been released for picking.
comments
string

Allows for arbitrary comments to be added to the packing slip.

metadata
object (metadata)

The metadata object is a flexible mechanism that allows clients to include arbitrary key-value pairs in the resource. It can be used to include additional information about the resource that has no meaning within Active Ants, but provides additional context to the client. The server will ignore the keys that it does not recognize, allowing clients to include custom metadata without affecting the behavior of the API. Note that only name-value pairs of type string-string are allowed!

object
object (inboundPackingSlipItemsRelation)

Represents a relationship to multiple inboundPackingSlipItem resources.

Array of objects (inboundPackingSlipItemIdentifier)
Array
id
integer

The id is an internally assigned id of a inboundPackingSlipItem. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Value: "inboundPackingSlipItem"
object
self
string <uri>
object (inboundRelation)

Points to a related inbound resource

object (inboundIdentification)

Identifies a resource as an inbound also referred to as receipt.

id
integer
type
any
Value: "inbound"
object
self
string <uri>
Array of inboundPackingSlipItemIdentifier (object)
Array
Any of
id
integer

The id is an internally assigned id of a inboundPackingSlipItem. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Value: "inboundPackingSlipItem"
object
sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

quantity
integer > 0

Indicates the 'expected' or 'declared' quantity of the sku.

received
integer >= 0

Indicates the quantity of the sku that was received. Note that this value can change as long as the packingSlip has a status other than EXPECTED or COMPLETED

object
self
string <uri>
object

Pagination links that provided for convenience and in compliancy to the json:api specification for pagination.

self
string <uri>
next
string <uri>
first
string <uri>

Response samples

Content type
application/vnd.api+json
{}

v3/inboundPackingSlips

POST v3/inboundPackingSlips

Using this endpoint it is possible to create a new inboundPackingSlip for an inbound that is to be expected in one of the warehouses of Active Ants. Note that an inboundPackingSlip and its related inboundPackingSlipItems can be created in one invocation by making use of the included relationship as shown in the example request body.

Limitations of POST /v3/inboundPackingSlips

  • Each inboundPackingSlip must have a unique reference not used before.
  • Each sku must be of a product that exists prior to creating the inboundPackingSlip.
  • Each sku can occur only once on an inboundPackingSlip, adding multiple inboundPackingSlipItems for the same sku will result in a single inboundPackingSlipItem with the sum of the quantities.
  • The quantity must be 1 or larger.
  • The warehouseCode provided in the expectedIn must exist and must be a valid warehouse to receive goods in. (For more information contact your account manager).
Authorizations:
Bearer Token
Request Body schema: application/vnd.api+json
object (inboundPackingSlipIdentification)

Identifies a resource as a inboundPackingSlip.

id
integer

The id is an internally assigned id of a inboundPackingSlip. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "inboundPackingSlip"
Value: "inboundPackingSlip"
object
expectedIn
required
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

Indicates the warehouse the products are expected in. This is a required field and must match the warehouse where the inbound will be processed as this warehouse is only able to see the packingSlips matching their warehouse.

expectedOn
string <date>

Allows specifying the date at which the inbound shipment related to this packing slip is expected to arrive at the warehouse. This date helps with apactiy planning

reference
string

A unique reference for the packingSlip.

comments
string

Allows for arbitrary comments to be added to the packing slip.

metadata
object (metadata)

The metadata object is a flexible mechanism that allows clients to include arbitrary key-value pairs in the resource. It can be used to include additional information about the resource that has no meaning within Active Ants, but provides additional context to the client. The server will ignore the keys that it does not recognize, allowing clients to include custom metadata without affecting the behavior of the API. Note that only name-value pairs of type string-string are allowed!

Array of inboundPackingSlipItemIdentifier (object)
Array
Any of
id
integer

The id is an internally assigned id of a inboundPackingSlipItem. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Value: "inboundPackingSlipItem"
object
sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

quantity
integer > 0

Indicates the 'expected' or 'declared' quantity of the sku.

Responses

Response Schema: application/vnd.api+json
object (inboundPackingSlip)

In the context of Active Ants, an inboundPackingSlip, which is also referred to as an advanced shipping notice or ASN, is a document that is included with an inbound shipment and provides important information about its contents. By merging the packing slip and ASN, it is possible to declare an inbound shipments and track its results.

id
integer

The id is an internally assigned id of a inboundPackingSlip. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "inboundPackingSlip"
Value: "inboundPackingSlip"
object
expectedIn
required
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

Indicates the warehouse the products are expected in. This is a required field and must match the warehouse where the inbound will be processed as this warehouse is only able to see the packingSlips matching their warehouse.

expectedOn
string <date>

Allows specifying the date at which the inbound shipment related to this packing slip is expected to arrive at the warehouse. This date helps with apactiy planning

receivedOn
string <date-time>

Indicates the moment the packing slip was coupled to an inbound shipment.

completedOn
string <date-time>

Indicates the moment the inbound shipment was completed and verified, signalling tha tthe packing slip is also marked as COMPLETED.

reference
string

A unique reference for the packingSlip.

status
string (inboundPackingSlipStatus)
Enum: "EXPECTED" "IN_PROGRESS" "CHECKING" "COMPLETED"

The inboundPackingSlipStatus describes the life-cycle of packing slip.

All locations have been classified to the one of the following types:

value description
EXPECTED This status indicates that the inbound shipment is not (yet) being processed. It is still possible to make amendments to the inboundPackingSlip.
IN_PROGRESS The items of the inboundPackingSlip are being processed. The inbound has not been completed yet therefor the quantities on the inboundPackingSlip are not final.
CHECKING All the goods of the inbound have been registered, but before the packingslip is COMPLETED it is being checked. Checking occurs when differences between the inboundPackingSlip and the inbound have been identified. Products that are correctly received are released for ordering.
CHECKED The ibound related to this inboundPackingSlip has been checked meaning that all locations containing sku for which a different quantity was received than expected have been recounted. Since the moment of the last check there is a timewindow of 2 hours before the inbound is automatically COMPLETED making the inboundPackinSlip also COMPLETED.
COMPLETED The inbound related to this inboundPackingSlip has been completed and deviations have been checked and verified. There are no validation steps to follow and all products that have been received have been released for picking.
comments
string

Allows for arbitrary comments to be added to the packing slip.

metadata
object (metadata)

The metadata object is a flexible mechanism that allows clients to include arbitrary key-value pairs in the resource. It can be used to include additional information about the resource that has no meaning within Active Ants, but provides additional context to the client. The server will ignore the keys that it does not recognize, allowing clients to include custom metadata without affecting the behavior of the API. Note that only name-value pairs of type string-string are allowed!

object
object (inboundPackingSlipItemsRelation)

Represents a relationship to multiple inboundPackingSlipItem resources.

Array of objects (inboundPackingSlipItemIdentifier)
Array
id
integer

The id is an internally assigned id of a inboundPackingSlipItem. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Value: "inboundPackingSlipItem"
object
self
string <uri>
object (inboundRelation)

Points to a related inbound resource

object (inboundIdentification)

Identifies a resource as an inbound also referred to as receipt.

id
integer
type
any
Value: "inbound"
object
self
string <uri>
Array of inboundPackingSlipItemIdentifier (object)
Array
Any of
id
integer

The id is an internally assigned id of a inboundPackingSlipItem. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Value: "inboundPackingSlipItem"
object
sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

quantity
integer > 0

Indicates the 'expected' or 'declared' quantity of the sku.

received
integer >= 0

Indicates the quantity of the sku that was received. Note that this value can change as long as the packingSlip has a status other than EXPECTED or COMPLETED

object
self
string <uri>

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

v3/inboundPackingSlips/:id

GET v3/inboundPackingSlips/:id

Allows the retreival of a inboundPackingSlip by its id along with its current status and optionally all inboundPackingSlipItems that are part of the inboundPackingSlip.

The endpoint also supports -to some degree- the inclusion of information of related resources. The resources that can be included in the response are limited to inboundPackingSlipItems. To get the details of related entities included in the response make use of the include query-parameter in the following way:

  • GET {host}/v3/inboundPackingSlips?include=inboundPackingSlipItems will return for each inboundPackingSlip the list of inboundPackingSlipItems with their details.
Authorizations:
Bearer Token
path Parameters
id
required
string

The unique id (integer) of the inboundPackingSlip to retrieve.

query Parameters
include
Array of strings unique
Items Value: "inboundPackingSlipItems"
Examples:
  • include=inboundPackingSlipItems - Include `inboundPackingSlipItems`

Comma-separated list of inboundPackingSlip related resources to include in the response under the included element

Responses

Response Schema: application/vnd.api+json
object (inboundPackingSlip)

In the context of Active Ants, an inboundPackingSlip, which is also referred to as an advanced shipping notice or ASN, is a document that is included with an inbound shipment and provides important information about its contents. By merging the packing slip and ASN, it is possible to declare an inbound shipments and track its results.

id
integer

The id is an internally assigned id of a inboundPackingSlip. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "inboundPackingSlip"
Value: "inboundPackingSlip"
object
expectedIn
required
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

Indicates the warehouse the products are expected in. This is a required field and must match the warehouse where the inbound will be processed as this warehouse is only able to see the packingSlips matching their warehouse.

expectedOn
string <date>

Allows specifying the date at which the inbound shipment related to this packing slip is expected to arrive at the warehouse. This date helps with apactiy planning

receivedOn
string <date-time>

Indicates the moment the packing slip was coupled to an inbound shipment.

completedOn
string <date-time>

Indicates the moment the inbound shipment was completed and verified, signalling tha tthe packing slip is also marked as COMPLETED.

reference
string

A unique reference for the packingSlip.

status
string (inboundPackingSlipStatus)
Enum: "EXPECTED" "IN_PROGRESS" "CHECKING" "COMPLETED"

The inboundPackingSlipStatus describes the life-cycle of packing slip.

All locations have been classified to the one of the following types:

value description
EXPECTED This status indicates that the inbound shipment is not (yet) being processed. It is still possible to make amendments to the inboundPackingSlip.
IN_PROGRESS The items of the inboundPackingSlip are being processed. The inbound has not been completed yet therefor the quantities on the inboundPackingSlip are not final.
CHECKING All the goods of the inbound have been registered, but before the packingslip is COMPLETED it is being checked. Checking occurs when differences between the inboundPackingSlip and the inbound have been identified. Products that are correctly received are released for ordering.
CHECKED The ibound related to this inboundPackingSlip has been checked meaning that all locations containing sku for which a different quantity was received than expected have been recounted. Since the moment of the last check there is a timewindow of 2 hours before the inbound is automatically COMPLETED making the inboundPackinSlip also COMPLETED.
COMPLETED The inbound related to this inboundPackingSlip has been completed and deviations have been checked and verified. There are no validation steps to follow and all products that have been received have been released for picking.
comments
string

Allows for arbitrary comments to be added to the packing slip.

metadata
object (metadata)

The metadata object is a flexible mechanism that allows clients to include arbitrary key-value pairs in the resource. It can be used to include additional information about the resource that has no meaning within Active Ants, but provides additional context to the client. The server will ignore the keys that it does not recognize, allowing clients to include custom metadata without affecting the behavior of the API. Note that only name-value pairs of type string-string are allowed!

object
object (inboundPackingSlipItemsRelation)

Represents a relationship to multiple inboundPackingSlipItem resources.

Array of objects (inboundPackingSlipItemIdentifier)
Array
id
integer

The id is an internally assigned id of a inboundPackingSlipItem. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Value: "inboundPackingSlipItem"
object
self
string <uri>
object (inboundRelation)

Points to a related inbound resource

object (inboundIdentification)

Identifies a resource as an inbound also referred to as receipt.

id
integer
type
any
Value: "inbound"
object
self
string <uri>
Array of inboundPackingSlipItemIdentifier (object)
Array
Any of
id
integer

The id is an internally assigned id of a inboundPackingSlipItem. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Value: "inboundPackingSlipItem"
object
sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

quantity
integer > 0

Indicates the 'expected' or 'declared' quantity of the sku.

received
integer >= 0

Indicates the quantity of the sku that was received. Note that this value can change as long as the packingSlip has a status other than EXPECTED or COMPLETED

object
self
string <uri>
object
self
string <uri>

Response samples

Content type
application/vnd.api+json
{}

Products

To avoid abuse, all v3/products/* endpoints are rate limited to 500 requests per hour per user. When exceeding this limit the server will respond with a 429 Too Many Requests error.

v3/products

GET v3/products

Allows the retrieval of multiple products and their related details. This endpoint supports pagination and various filters as indicated below.

Pagination

The endpoint supports pagination to split the large collection of resources into smaller, more manageable chunks or pages. This helps to reduce the response size and to improve performance. The endpoint supports only cursor-based pagination.

Filters

The GET v3/products endpoint supports filtering on the following attributes: sku and barcode. Each of these is explained below. Filters can be used in combination with each other and with pagination to allow full access to the desired subset of product resources.

Filtering on sku

The endpoint allows setting a filter on the sku of products. The filter accepts multiple sku values, each of which must be URL encoded and separated by a comma. Each sku returns at most one product resource but could also return none. Be aware that the SKUs must be URL encoded to avoid being interpreted incorrectly.

  • GET {host}/v3/products?filter[sku][in]=ABC,DEF will return the products with sku ABC and DEF.
  • GET {host}/v3/products?filter[sku][in]=ABC%2CDEF will return the product with the sku ABC,DEF.

Filtering on barcode

The endpoint allows setting a filter on the barcode of products. The filter accepts multiple barcode values, each of which must be URL encoded and separated by a comma. Each barcode returns at most one product resource but could also return none. Be aware that the barcodes must be URL encoded to avoid being interpreted incorrectly.

  • GET {host}/v3/products?filter[barcode][in]=848017,748222 will return the products with barcodes 848017 and 748222.
  • GET {host}/v3/products?filter[barcode][in]=848017%2C748222 will return the product with the barcode 848017,748222.

This endpoint does not support inclusion of other resources.

Limitations of GET v3/products

When using this endpoint, expect the following limits on the result set:

  • At most 100 products will be returned regardless of the page[size] settings provided in the request.
  • Ordering is based on the id of the product in ascending order.
  • When providing multiple filters they will all be applied (so both filter[sku][in] and filter[barcode][in], will result in products having both these values).
  • Users are rate-limited to 500 requests per hour on this service.
Authorizations:
Bearer Token
query Parameters
filter[sku][in]
Array of strings (productSku) non-empty unique [ items [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$ ]
Examples:
  • filter[sku][in]=TSH-000-S -
  • filter[sku][in]=8720874770299,HK-HNTSSTNG 6X -
  • filter[sku][in]=TRRE-PSU6*003;2023-10:special,THE_ULTIMATE_SKU -

A comma separated list of productSku values to filter by.

filter[barcode][in]
Array of strings (productBarcode) non-empty unique [ items [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$ ]
Examples:
  • filter[barcode][in]=7020813370299 -
  • filter[barcode][in]=8720874770299 -

A comma separated list of productBarcode values to filter by.

Responses

Response Schema: application/vnd.api+json
Array of objects (products)
Array
id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
sku
required
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

status
string (productStatus)
Enum: "DISCONTINUED" "AVAILABLE" "END_OF_LIFE"

The productStatus indicates the availability of the product. The possible values are AVAILABLE, DISCONTINUED and END_OF_LIFE. See the table below for more details.

status description
AVAILABLE The product is available and active. It is actively being sold and new stock can be received
DISCONTINUED The product is still available, but new stock will no longer be expected.
END_OF_LIFE The product is no longer active and will no longer show in the reports.
stockLevelType
string (stockLevelType)
Enum: "ECONOMIC" "AVAILABLE"

Specifies which type of stockLevel is to be used for stock synchronization for this particular product.

type
string (productType)
Enum: "DEFAULT" "COMPOSITE" "PART" "DEFAULT_IN_PACKAGING" "BUNDLE" "GREETING_CARD" "SERVICE"

The productType indicates the type of the product .

status description
DEFAULT The product a regular product which can be sold and shipped.
DEFAULT_IN_PACKAGING Same as DEFAULT, but when ordered individually the product will be shipped without packaging.
COMPOSITE Used for products that are composed out of other products of type PART. Composite products are stocked, picked and shipped as a single SKU and cannot be split into their consituent parts. This is important as consumers will notbe able to return these parts individually. Also note that composite products can also run out of stock eventhough the parts may still be in stock. This is because new stock of composite products is created through special work orders.
BUNDLE The product is a bundled product which means that the product itself is not kept on stock, but when ordered, its parts are picked and shipped instead. When ordering a bundled product the system will automatically add the parts to the order as separate orderItems. Bundled products can be partially returned as each item is a separate product, they can also be split across shipments if packaging constraints prevent them from being shipped together.
PART The product is a part of one or more COMPOSITE products.
GREETING_CARD A special type of product used to add a personalized greeing card to the order. This requires the greeting to be added to the metadata field on the orderItem with the name extra6.
SERVICE A special type of product used in very specific situations.
weight
integer

This field indicates the weight of the product, measured in grams. It is important to note that the weight is determined when the product is first processed in an inbound shipment and can only be set or modified on request.

length
integer

The length of the product in millimeters, notice that this value can not be specified. It will be measured once the product is received for the first time.

width
integer

The width of the product in millimeters, notice that this value can not be specified. It will be measured once the product is received for the first time.

height
integer

The height of the product in millimeters, notice that this value can not be specified. It will be measured once the product is received for the first time.

name
required
string [ 1 .. 250 ] characters

Short name for the product used on packing slips if required. Note that this name is used mostly internally and when the orderItem.name is not provided.

description
string <= 10000 characters

A more complete description of the product.

hasBarcode
boolean
Default: false

Specifies if the product has a barCode or not. When set to true a barcode will be scanned during the first inbound or when already known the barcode can be specified in the barcode field.

barcode
string (productBarcode) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

The barcode of the product, when set will ensure that the hasBarcode is true as well.

hasLotNumber
boolean
Default: false

Specifies if the product has a lotNumber or not. Defaults to false.

hasSerialNumber
boolean
Default: false

Specifies if the product has a serialNumber or not. Defaults to false.

hasExpirationDate
boolean
Default: false

Specifies if the product has an expirationDate or not. Defaults to false.

expirationDateMargin
integer

The expirationDateMargin is the number of days used to determine whether particular stock can still be sold or if it has expired. Stock of a product is expired when the difference of the current date with and expirationDate of the stock is more than the expirationDateMargin speficied on the product. This field is optional when expirationDate is NONE.

expirationDateWarning
integer

The expirationDateWarning is the number of days used to determine is a product nearing its expiration date. This field is optional when expirationDate is NONE.

countryOfOrigin
string (countryCode) ^[A-Z]{2,2}(-[A-Z0-9]{2,3})?$

A valid ISO:3166-1 alpha-2 country code denoting the country of origin for the product. This value is required for international shipments.

Array of objects

An array of hsCodes (or more specific equivalents thereof) for this product. To set a default/fallback hsCode for the product use country code XX. It is not mandatory to specify hsCodes, but when provigind the element the array should contain at least one entry.

Array
country
required
string (countryCode) ^[A-Z]{2,2}(-[A-Z0-9]{2,3})?$

A valid ISO:3166-1 alpha-2 country code denoting the country or region the hsCode is applicable for. Use XX to denote the default/fallback hsCode for the product.

hsCode
required
string (hsCode) [ 6 .. 12 ] characters \d{6,12}

The hsCode stands for Harmonized System code, which is a standardized numerical method of classifying traded products. It is used by customs authorities around the world to identify and track goods as they cross borders. The Harmonized System is maintained by the World Customs Organization (WCO) and is recognized as the global standard for product classification. It consists of a six-digit code that can be further detailed with additional digits. Standard hsCodes are six digits long, but more specific variants such as TARIC can use more.

Array of objects (monetaryAmountEUR) <= 1 items

Specifies the purchase price of the product. At the moment only a single price in EUR is supported. Any currency code provided will be ignored.

Array (<= 1 items)
currency
required
stringEUR
Default: "EUR"

The currency symbol for this amount must always be set to EUR.

amount
required
number
object
extra1
string <= 250 characters
extra2
string <= 250 characters
extra3
string <= 250 characters
extra4
string <= 250 characters
extra5
string <= 250 characters
object
object (stockLevelRelation)

Convenience relationship to the stockLevel of the product.

object (stockLevelIdentifier)

Identifies a resource as a stockLevel.

id
integer
type
any
Default: "stockLevel"
Value: "stockLevel"
object
self
string <uri>
object

Provided when the product is of type BUNDLE or COMPOSITE. The array contains references to the constituent products and the quantity they appear in in this bundle.

Array of objects (productIdentifier)
Array
id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
quantity
integer > 0
object
self
string <uri>
object
self
string <uri>
object

Pagination links that provided for convenience and in compliancy to the json:api specification for pagination.

self
string <uri>
next
string <uri>
first
string <uri>

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "included": null,
  • "links": {}
}

v3/products

POST v3/products

Limitations of POST /v3/products

When using this endpoint, expect the following limitations are applicable

  • The sku must be unique and never used before in the context of the user.
  • The barcode must be unique and never used before in the context of the user.
  • The name is used both internally and towards consumer communication, however it is possible to specify a different name during ordering on the orderItem which will be used within that order and related shipment(s)
  • hsCode limitations:
    • To specify the 'default' or'fallback' hsCodes make use of country XX to denote the default hsCode to use in most scenarios.
    • When at least one hsCode is provided, but none have country XX, the system will copy EU, NL or the first entry as the default/fallback hsCode.
    • hsCodes are not formatted and consist of digits only. Other characters will be stripped from the code.
  • Products that are perishable and for which the expiration date must be registered during processing of inbound must have:
    • expirationDate set to SCAN_AT_INBOUND.
    • expirationDateMargin to a positive number.
    • expirationDateWarning to be number equal or larger than expirationDateMargin.
Authorizations:
Bearer Token
Request Body schema: application/vnd.api+json
object (productIdentifier)

Identifies a resource as a product.

type
any
Default: "product"
Value: "product"
object
sku
required
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

status
string (productStatus)
Enum: "DISCONTINUED" "AVAILABLE" "END_OF_LIFE"

The productStatus indicates the availability of the product. The possible values are AVAILABLE, DISCONTINUED and END_OF_LIFE. See the table below for more details.

status description
AVAILABLE The product is available and active. It is actively being sold and new stock can be received
DISCONTINUED The product is still available, but new stock will no longer be expected.
END_OF_LIFE The product is no longer active and will no longer show in the reports.
stockLevelType
string (stockLevelType)
Enum: "ECONOMIC" "AVAILABLE"

Specifies which type of stockLevel is to be used for stock synchronization for this particular product.

name
required
string [ 1 .. 250 ] characters

Short name for the product used on packing slips if required. Note that this name is used mostly internally and when the orderItem.name is not provided.

description
string <= 10000 characters

A more complete description of the product.

hasBarcode
boolean
Default: false

Specifies if the product has a barCode or not. When set to true a barcode will be scanned during the first inbound or when already known the barcode can be specified in the barcode field.

barcode
string (productBarcode) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

The barcode of the product, when set will ensure that the hasBarcode is true as well.

hasLotNumber
boolean
Default: false

Specifies if the product has a lotNumber or not. Defaults to false.

hasSerialNumber
boolean
Default: false

Specifies if the product has a serialNumber or not. Defaults to false.

hasExpirationDate
boolean
Default: false

Specifies if the product has an expirationDate or not. Defaults to false.

expirationDateMargin
integer

The expirationDateMargin is the number of days used to determine whether particular stock can still be sold or if it has expired. Stock of a product is expired when the difference of the current date with and expirationDate of the stock is more than the expirationDateMargin speficied on the product. This field is optional when expirationDate is NONE.

expirationDateWarning
integer

The expirationDateWarning is the number of days used to determine is a product nearing its expiration date. This field is optional when expirationDate is NONE.

countryOfOrigin
string (countryCode) ^[A-Z]{2,2}(-[A-Z0-9]{2,3})?$

A valid ISO:3166-1 alpha-2 country code denoting the country of origin for the product. This value is required for international shipments.

Array of objects

An array of hsCodes (or more specific equivalents thereof) for this product. To set a default/fallback hsCode for the product use country code XX. It is not mandatory to specify hsCodes, but when provigind the element the array should contain at least one entry.

Array
country
required
string (countryCode) ^[A-Z]{2,2}(-[A-Z0-9]{2,3})?$

A valid ISO:3166-1 alpha-2 country code denoting the country or region the hsCode is applicable for. Use XX to denote the default/fallback hsCode for the product.

hsCode
required
string (hsCode) [ 6 .. 12 ] characters \d{6,12}

The hsCode stands for Harmonized System code, which is a standardized numerical method of classifying traded products. It is used by customs authorities around the world to identify and track goods as they cross borders. The Harmonized System is maintained by the World Customs Organization (WCO) and is recognized as the global standard for product classification. It consists of a six-digit code that can be further detailed with additional digits. Standard hsCodes are six digits long, but more specific variants such as TARIC can use more.

Array of objects (monetaryAmountEUR) <= 1 items

Specifies the purchase price of the product. At the moment only a single price in EUR is supported. Any currency code provided will be ignored.

Array (<= 1 items)
currency
required
stringEUR
Default: "EUR"

The currency symbol for this amount must always be set to EUR.

amount
required
number
object
extra1
string <= 250 characters
extra2
string <= 250 characters
extra3
string <= 250 characters
extra4
string <= 250 characters
extra5
string <= 250 characters

Responses

Response Schema: application/vnd.api+json
object (product)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
sku
required
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

status
string (productStatus)
Enum: "DISCONTINUED" "AVAILABLE" "END_OF_LIFE"

The productStatus indicates the availability of the product. The possible values are AVAILABLE, DISCONTINUED and END_OF_LIFE. See the table below for more details.

status description
AVAILABLE The product is available and active. It is actively being sold and new stock can be received
DISCONTINUED The product is still available, but new stock will no longer be expected.
END_OF_LIFE The product is no longer active and will no longer show in the reports.
stockLevelType
string (stockLevelType)
Enum: "ECONOMIC" "AVAILABLE"

Specifies which type of stockLevel is to be used for stock synchronization for this particular product.

type
string (productType)
Enum: "DEFAULT" "COMPOSITE" "PART" "DEFAULT_IN_PACKAGING" "BUNDLE" "GREETING_CARD" "SERVICE"

The productType indicates the type of the product .

status description
DEFAULT The product a regular product which can be sold and shipped.
DEFAULT_IN_PACKAGING Same as DEFAULT, but when ordered individually the product will be shipped without packaging.
COMPOSITE Used for products that are composed out of other products of type PART. Composite products are stocked, picked and shipped as a single SKU and cannot be split into their consituent parts. This is important as consumers will notbe able to return these parts individually. Also note that composite products can also run out of stock eventhough the parts may still be in stock. This is because new stock of composite products is created through special work orders.
BUNDLE The product is a bundled product which means that the product itself is not kept on stock, but when ordered, its parts are picked and shipped instead. When ordering a bundled product the system will automatically add the parts to the order as separate orderItems. Bundled products can be partially returned as each item is a separate product, they can also be split across shipments if packaging constraints prevent them from being shipped together.
PART The product is a part of one or more COMPOSITE products.
GREETING_CARD A special type of product used to add a personalized greeing card to the order. This requires the greeting to be added to the metadata field on the orderItem with the name extra6.
SERVICE A special type of product used in very specific situations.
weight
integer

This field indicates the weight of the product, measured in grams. It is important to note that the weight is determined when the product is first processed in an inbound shipment and can only be set or modified on request.

length
integer

The length of the product in millimeters, notice that this value can not be specified. It will be measured once the product is received for the first time.

width
integer

The width of the product in millimeters, notice that this value can not be specified. It will be measured once the product is received for the first time.

height
integer

The height of the product in millimeters, notice that this value can not be specified. It will be measured once the product is received for the first time.

name
required
string [ 1 .. 250 ] characters

Short name for the product used on packing slips if required. Note that this name is used mostly internally and when the orderItem.name is not provided.

description
string <= 10000 characters

A more complete description of the product.

hasBarcode
boolean
Default: false

Specifies if the product has a barCode or not. When set to true a barcode will be scanned during the first inbound or when already known the barcode can be specified in the barcode field.

barcode
string (productBarcode) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

The barcode of the product, when set will ensure that the hasBarcode is true as well.

hasLotNumber
boolean
Default: false

Specifies if the product has a lotNumber or not. Defaults to false.

hasSerialNumber
boolean
Default: false

Specifies if the product has a serialNumber or not. Defaults to false.

hasExpirationDate
boolean
Default: false

Specifies if the product has an expirationDate or not. Defaults to false.

expirationDateMargin
integer

The expirationDateMargin is the number of days used to determine whether particular stock can still be sold or if it has expired. Stock of a product is expired when the difference of the current date with and expirationDate of the stock is more than the expirationDateMargin speficied on the product. This field is optional when expirationDate is NONE.

expirationDateWarning
integer

The expirationDateWarning is the number of days used to determine is a product nearing its expiration date. This field is optional when expirationDate is NONE.

countryOfOrigin
string (countryCode) ^[A-Z]{2,2}(-[A-Z0-9]{2,3})?$

A valid ISO:3166-1 alpha-2 country code denoting the country of origin for the product. This value is required for international shipments.

Array of objects

An array of hsCodes (or more specific equivalents thereof) for this product. To set a default/fallback hsCode for the product use country code XX. It is not mandatory to specify hsCodes, but when provigind the element the array should contain at least one entry.

Array
country
required
string (countryCode) ^[A-Z]{2,2}(-[A-Z0-9]{2,3})?$

A valid ISO:3166-1 alpha-2 country code denoting the country or region the hsCode is applicable for. Use XX to denote the default/fallback hsCode for the product.

hsCode
required
string (hsCode) [ 6 .. 12 ] characters \d{6,12}

The hsCode stands for Harmonized System code, which is a standardized numerical method of classifying traded products. It is used by customs authorities around the world to identify and track goods as they cross borders. The Harmonized System is maintained by the World Customs Organization (WCO) and is recognized as the global standard for product classification. It consists of a six-digit code that can be further detailed with additional digits. Standard hsCodes are six digits long, but more specific variants such as TARIC can use more.

Array of objects (monetaryAmountEUR) <= 1 items

Specifies the purchase price of the product. At the moment only a single price in EUR is supported. Any currency code provided will be ignored.

Array (<= 1 items)
currency
required
stringEUR
Default: "EUR"

The currency symbol for this amount must always be set to EUR.

amount
required
number
object
extra1
string <= 250 characters
extra2
string <= 250 characters
extra3
string <= 250 characters
extra4
string <= 250 characters
extra5
string <= 250 characters
object
object (stockLevelRelation)

Convenience relationship to the stockLevel of the product.

object (stockLevelIdentifier)

Identifies a resource as a stockLevel.

id
integer
type
any
Default: "stockLevel"
Value: "stockLevel"
object
self
string <uri>
object

Provided when the product is of type BUNDLE or COMPOSITE. The array contains references to the constituent products and the quantity they appear in in this bundle.

Array of objects (productIdentifier)
Array
id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
quantity
integer > 0
object
self
string <uri>
object
self
string <uri>
object
self
string <uri>

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "links": {}
}

v3/products/:id

GET v3/products/:id

Allows the retreival of a specific product and its related details by its id.

This endpoint does not support inclusion of other resources.

Authorizations:
Bearer Token
path Parameters
id
required
string

The unique id (integer) of the product to retrieve.

Responses

Response Schema: application/vnd.api+json
object (product)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
sku
required
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

status
string (productStatus)
Enum: "DISCONTINUED" "AVAILABLE" "END_OF_LIFE"

The productStatus indicates the availability of the product. The possible values are AVAILABLE, DISCONTINUED and END_OF_LIFE. See the table below for more details.

status description
AVAILABLE The product is available and active. It is actively being sold and new stock can be received
DISCONTINUED The product is still available, but new stock will no longer be expected.
END_OF_LIFE The product is no longer active and will no longer show in the reports.
stockLevelType
string (stockLevelType)
Enum: "ECONOMIC" "AVAILABLE"

Specifies which type of stockLevel is to be used for stock synchronization for this particular product.

type
string (productType)
Enum: "DEFAULT" "COMPOSITE" "PART" "DEFAULT_IN_PACKAGING" "BUNDLE" "GREETING_CARD" "SERVICE"

The productType indicates the type of the product .

status description
DEFAULT The product a regular product which can be sold and shipped.
DEFAULT_IN_PACKAGING Same as DEFAULT, but when ordered individually the product will be shipped without packaging.
COMPOSITE Used for products that are composed out of other products of type PART. Composite products are stocked, picked and shipped as a single SKU and cannot be split into their consituent parts. This is important as consumers will notbe able to return these parts individually. Also note that composite products can also run out of stock eventhough the parts may still be in stock. This is because new stock of composite products is created through special work orders.
BUNDLE The product is a bundled product which means that the product itself is not kept on stock, but when ordered, its parts are picked and shipped instead. When ordering a bundled product the system will automatically add the parts to the order as separate orderItems. Bundled products can be partially returned as each item is a separate product, they can also be split across shipments if packaging constraints prevent them from being shipped together.
PART The product is a part of one or more COMPOSITE products.
GREETING_CARD A special type of product used to add a personalized greeing card to the order. This requires the greeting to be added to the metadata field on the orderItem with the name extra6.
SERVICE A special type of product used in very specific situations.
weight
integer

This field indicates the weight of the product, measured in grams. It is important to note that the weight is determined when the product is first processed in an inbound shipment and can only be set or modified on request.

length
integer

The length of the product in millimeters, notice that this value can not be specified. It will be measured once the product is received for the first time.

width
integer

The width of the product in millimeters, notice that this value can not be specified. It will be measured once the product is received for the first time.

height
integer

The height of the product in millimeters, notice that this value can not be specified. It will be measured once the product is received for the first time.

name
required
string [ 1 .. 250 ] characters

Short name for the product used on packing slips if required. Note that this name is used mostly internally and when the orderItem.name is not provided.

description
string <= 10000 characters

A more complete description of the product.

hasBarcode
boolean
Default: false

Specifies if the product has a barCode or not. When set to true a barcode will be scanned during the first inbound or when already known the barcode can be specified in the barcode field.

barcode
string (productBarcode) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

The barcode of the product, when set will ensure that the hasBarcode is true as well.

hasLotNumber
boolean
Default: false

Specifies if the product has a lotNumber or not. Defaults to false.

hasSerialNumber
boolean
Default: false

Specifies if the product has a serialNumber or not. Defaults to false.

hasExpirationDate
boolean
Default: false

Specifies if the product has an expirationDate or not. Defaults to false.

expirationDateMargin
integer

The expirationDateMargin is the number of days used to determine whether particular stock can still be sold or if it has expired. Stock of a product is expired when the difference of the current date with and expirationDate of the stock is more than the expirationDateMargin speficied on the product. This field is optional when expirationDate is NONE.

expirationDateWarning
integer

The expirationDateWarning is the number of days used to determine is a product nearing its expiration date. This field is optional when expirationDate is NONE.

countryOfOrigin
string (countryCode) ^[A-Z]{2,2}(-[A-Z0-9]{2,3})?$

A valid ISO:3166-1 alpha-2 country code denoting the country of origin for the product. This value is required for international shipments.

Array of objects

An array of hsCodes (or more specific equivalents thereof) for this product. To set a default/fallback hsCode for the product use country code XX. It is not mandatory to specify hsCodes, but when provigind the element the array should contain at least one entry.

Array
country
required
string (countryCode) ^[A-Z]{2,2}(-[A-Z0-9]{2,3})?$

A valid ISO:3166-1 alpha-2 country code denoting the country or region the hsCode is applicable for. Use XX to denote the default/fallback hsCode for the product.

hsCode
required
string (hsCode) [ 6 .. 12 ] characters \d{6,12}

The hsCode stands for Harmonized System code, which is a standardized numerical method of classifying traded products. It is used by customs authorities around the world to identify and track goods as they cross borders. The Harmonized System is maintained by the World Customs Organization (WCO) and is recognized as the global standard for product classification. It consists of a six-digit code that can be further detailed with additional digits. Standard hsCodes are six digits long, but more specific variants such as TARIC can use more.

Array of objects (monetaryAmountEUR) <= 1 items

Specifies the purchase price of the product. At the moment only a single price in EUR is supported. Any currency code provided will be ignored.

Array (<= 1 items)
currency
required
stringEUR
Default: "EUR"

The currency symbol for this amount must always be set to EUR.

amount
required
number
object
extra1
string <= 250 characters
extra2
string <= 250 characters
extra3
string <= 250 characters
extra4
string <= 250 characters
extra5
string <= 250 characters
object
object (stockLevelRelation)

Convenience relationship to the stockLevel of the product.

object (stockLevelIdentifier)

Identifies a resource as a stockLevel.

id
integer
type
any
Default: "stockLevel"
Value: "stockLevel"
object
self
string <uri>
object

Provided when the product is of type BUNDLE or COMPOSITE. The array contains references to the constituent products and the quantity they appear in in this bundle.

Array of objects (productIdentifier)
Array
id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
quantity
integer > 0
object
self
string <uri>
object
self
string <uri>
object
self
string <uri>

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": null,
  • "links": {}
}

v3/products/:id

GET v3/products/:id

Enables updating and modifying product information related details by its id. Note that not all attributes can be modified once the product is created and others are not mutable through the API.

This endpoint does not support inclusion of other resources.

Limitations of PUT /v3/products/:id

When using this endpoint, expect the following limitations

  • The following attributes of a product can not be modified, or only under certain conditions and result in a 409 Conflict:
    • sku sku changes are not supported.
    • barcode can be changed as long as there is no stock for that product.
    • weight this attribute is determined during the first inbound.
    • length, width and height these attributes are determined during the first inbound.
Authorizations:
Bearer Token
path Parameters
id
required
string

The unique id (integer) of the product to retrieve.

Request Body schema: application/vnd.api+json
object (product)

Identifies a resource as a product.

type
any
Default: "product"
Value: "product"
object
sku
required
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

status
string (productStatus)
Enum: "DISCONTINUED" "AVAILABLE" "END_OF_LIFE"

The productStatus indicates the availability of the product. The possible values are AVAILABLE, DISCONTINUED and END_OF_LIFE. See the table below for more details.

status description
AVAILABLE The product is available and active. It is actively being sold and new stock can be received
DISCONTINUED The product is still available, but new stock will no longer be expected.
END_OF_LIFE The product is no longer active and will no longer show in the reports.
stockLevelType
string (stockLevelType)
Enum: "ECONOMIC" "AVAILABLE"

Specifies which type of stockLevel is to be used for stock synchronization for this particular product.

name
required
string [ 1 .. 250 ] characters

Short name for the product used on packing slips if required. Note that this name is used mostly internally and when the orderItem.name is not provided.

description
string <= 10000 characters

A more complete description of the product.

hasBarcode
boolean
Default: false

Specifies if the product has a barCode or not. When set to true a barcode will be scanned during the first inbound or when already known the barcode can be specified in the barcode field.

barcode
string (productBarcode) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

The barcode of the product, when set will ensure that the hasBarcode is true as well.

hasLotNumber
boolean
Default: false

Specifies if the product has a lotNumber or not. Defaults to false.

hasSerialNumber
boolean
Default: false

Specifies if the product has a serialNumber or not. Defaults to false.

hasExpirationDate
boolean
Default: false

Specifies if the product has an expirationDate or not. Defaults to false.

expirationDateMargin
integer

The expirationDateMargin is the number of days used to determine whether particular stock can still be sold or if it has expired. Stock of a product is expired when the difference of the current date with and expirationDate of the stock is more than the expirationDateMargin speficied on the product. This field is optional when expirationDate is NONE.

expirationDateWarning
integer

The expirationDateWarning is the number of days used to determine is a product nearing its expiration date. This field is optional when expirationDate is NONE.

countryOfOrigin
string (countryCode) ^[A-Z]{2,2}(-[A-Z0-9]{2,3})?$

A valid ISO:3166-1 alpha-2 country code denoting the country of origin for the product. This value is required for international shipments.

Array of objects

An array of hsCodes (or more specific equivalents thereof) for this product. To set a default/fallback hsCode for the product use country code XX. It is not mandatory to specify hsCodes, but when provigind the element the array should contain at least one entry.

Array
country
required
string (countryCode) ^[A-Z]{2,2}(-[A-Z0-9]{2,3})?$

A valid ISO:3166-1 alpha-2 country code denoting the country or region the hsCode is applicable for. Use XX to denote the default/fallback hsCode for the product.

hsCode
required
string (hsCode) [ 6 .. 12 ] characters \d{6,12}

The hsCode stands for Harmonized System code, which is a standardized numerical method of classifying traded products. It is used by customs authorities around the world to identify and track goods as they cross borders. The Harmonized System is maintained by the World Customs Organization (WCO) and is recognized as the global standard for product classification. It consists of a six-digit code that can be further detailed with additional digits. Standard hsCodes are six digits long, but more specific variants such as TARIC can use more.

Array of objects (monetaryAmountEUR) <= 1 items

Specifies the purchase price of the product. At the moment only a single price in EUR is supported. Any currency code provided will be ignored.

Array (<= 1 items)
currency
required
stringEUR
Default: "EUR"

The currency symbol for this amount must always be set to EUR.

amount
required
number
object
extra1
string <= 250 characters
extra2
string <= 250 characters
extra3
string <= 250 characters
extra4
string <= 250 characters
extra5
string <= 250 characters
object
object (stockLevelRelation)

Convenience relationship to the stockLevel of the product.

object (stockLevelIdentifier)

Identifies a resource as a stockLevel.

id
integer
type
any
Default: "stockLevel"
Value: "stockLevel"
object
self
string <uri>
object

Provided when the product is of type BUNDLE or COMPOSITE. The array contains references to the constituent products and the quantity they appear in in this bundle.

Array of objects (productIdentifier)
Array
type
any
Default: "product"
Value: "product"
quantity
integer > 0
object
object

Responses

Response Schema: application/vnd.api+json
object (product)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
sku
required
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

status
string (productStatus)
Enum: "DISCONTINUED" "AVAILABLE" "END_OF_LIFE"

The productStatus indicates the availability of the product. The possible values are AVAILABLE, DISCONTINUED and END_OF_LIFE. See the table below for more details.

status description
AVAILABLE The product is available and active. It is actively being sold and new stock can be received
DISCONTINUED The product is still available, but new stock will no longer be expected.
END_OF_LIFE The product is no longer active and will no longer show in the reports.
stockLevelType
string (stockLevelType)
Enum: "ECONOMIC" "AVAILABLE"

Specifies which type of stockLevel is to be used for stock synchronization for this particular product.

type
string (productType)
Enum: "DEFAULT" "COMPOSITE" "PART" "DEFAULT_IN_PACKAGING" "BUNDLE" "GREETING_CARD" "SERVICE"

The productType indicates the type of the product .

status description
DEFAULT The product a regular product which can be sold and shipped.
DEFAULT_IN_PACKAGING Same as DEFAULT, but when ordered individually the product will be shipped without packaging.
COMPOSITE Used for products that are composed out of other products of type PART. Composite products are stocked, picked and shipped as a single SKU and cannot be split into their consituent parts. This is important as consumers will notbe able to return these parts individually. Also note that composite products can also run out of stock eventhough the parts may still be in stock. This is because new stock of composite products is created through special work orders.
BUNDLE The product is a bundled product which means that the product itself is not kept on stock, but when ordered, its parts are picked and shipped instead. When ordering a bundled product the system will automatically add the parts to the order as separate orderItems. Bundled products can be partially returned as each item is a separate product, they can also be split across shipments if packaging constraints prevent them from being shipped together.
PART The product is a part of one or more COMPOSITE products.
GREETING_CARD A special type of product used to add a personalized greeing card to the order. This requires the greeting to be added to the metadata field on the orderItem with the name extra6.
SERVICE A special type of product used in very specific situations.
weight
integer

This field indicates the weight of the product, measured in grams. It is important to note that the weight is determined when the product is first processed in an inbound shipment and can only be set or modified on request.

length
integer

The length of the product in millimeters, notice that this value can not be specified. It will be measured once the product is received for the first time.

width
integer

The width of the product in millimeters, notice that this value can not be specified. It will be measured once the product is received for the first time.

height
integer

The height of the product in millimeters, notice that this value can not be specified. It will be measured once the product is received for the first time.

name
required
string [ 1 .. 250 ] characters

Short name for the product used on packing slips if required. Note that this name is used mostly internally and when the orderItem.name is not provided.

description
string <= 10000 characters

A more complete description of the product.

hasBarcode
boolean
Default: false

Specifies if the product has a barCode or not. When set to true a barcode will be scanned during the first inbound or when already known the barcode can be specified in the barcode field.

barcode
string (productBarcode) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

The barcode of the product, when set will ensure that the hasBarcode is true as well.

hasLotNumber
boolean
Default: false

Specifies if the product has a lotNumber or not. Defaults to false.

hasSerialNumber
boolean
Default: false

Specifies if the product has a serialNumber or not. Defaults to false.

hasExpirationDate
boolean
Default: false

Specifies if the product has an expirationDate or not. Defaults to false.

expirationDateMargin
integer

The expirationDateMargin is the number of days used to determine whether particular stock can still be sold or if it has expired. Stock of a product is expired when the difference of the current date with and expirationDate of the stock is more than the expirationDateMargin speficied on the product. This field is optional when expirationDate is NONE.

expirationDateWarning
integer

The expirationDateWarning is the number of days used to determine is a product nearing its expiration date. This field is optional when expirationDate is NONE.

countryOfOrigin
string (countryCode) ^[A-Z]{2,2}(-[A-Z0-9]{2,3})?$

A valid ISO:3166-1 alpha-2 country code denoting the country of origin for the product. This value is required for international shipments.

Array of objects

An array of hsCodes (or more specific equivalents thereof) for this product. To set a default/fallback hsCode for the product use country code XX. It is not mandatory to specify hsCodes, but when provigind the element the array should contain at least one entry.

Array
country
required
string (countryCode) ^[A-Z]{2,2}(-[A-Z0-9]{2,3})?$

A valid ISO:3166-1 alpha-2 country code denoting the country or region the hsCode is applicable for. Use XX to denote the default/fallback hsCode for the product.

hsCode
required
string (hsCode) [ 6 .. 12 ] characters \d{6,12}

The hsCode stands for Harmonized System code, which is a standardized numerical method of classifying traded products. It is used by customs authorities around the world to identify and track goods as they cross borders. The Harmonized System is maintained by the World Customs Organization (WCO) and is recognized as the global standard for product classification. It consists of a six-digit code that can be further detailed with additional digits. Standard hsCodes are six digits long, but more specific variants such as TARIC can use more.

Array of objects (monetaryAmountEUR) <= 1 items

Specifies the purchase price of the product. At the moment only a single price in EUR is supported. Any currency code provided will be ignored.

Array (<= 1 items)
currency
required
stringEUR
Default: "EUR"

The currency symbol for this amount must always be set to EUR.

amount
required
number
object
extra1
string <= 250 characters
extra2
string <= 250 characters
extra3
string <= 250 characters
extra4
string <= 250 characters
extra5
string <= 250 characters
object
object (stockLevelRelation)

Convenience relationship to the stockLevel of the product.

object (stockLevelIdentifier)

Identifies a resource as a stockLevel.

id
integer
type
any
Default: "stockLevel"
Value: "stockLevel"
object
self
string <uri>
object

Provided when the product is of type BUNDLE or COMPOSITE. The array contains references to the constituent products and the quantity they appear in in this bundle.

Array of objects (productIdentifier)
Array
id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
quantity
integer > 0
object
self
string <uri>
object
self
string <uri>
object
self
string <uri>

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "links": {}
}

v3/products/:id/image

POST v3/products/:id/image

Allows the user to add or update the commercial image of a single products. The commercial image is used as reference image in when searching products in Maya and has no functional implications. Internally different images of the product are used for recognition and processing, however the commercial image may be relevant when dealing with consumer related issues about the product.

Limitations of POST /v3/propducts/:id/image

  • Each product can have only one commercially assigned image
  • The size of the file must be less than 10MiB
  • Only the following file types are supported:
    • image/png
    • image/x-png
    • image/apng
    • image/jpg
    • image/jpeg
    • image/pjpeg
    • image/gif (not recommended)
    • image/bmp (not recommended)
    • image/webp (partially, may cause issues)
    • application/x-photoshop (can't be rendered properly, but is accepted)
Authorizations:
Bearer Token
path Parameters
id
required
integer
Examples: 1267733

The id of the product for which the image is to be set. Note that the id must be the internally assigned id and not the user-assigned id

Request Body schema: application/octet-stream
required
string <binary>

The (commercial) product image to attach to the product for reference.

Responses

Response Schema: application/vnd.api+json
object
object (product)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
sku
required
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

status
string (productStatus)
Enum: "DISCONTINUED" "AVAILABLE" "END_OF_LIFE"

The productStatus indicates the availability of the product. The possible values are AVAILABLE, DISCONTINUED and END_OF_LIFE. See the table below for more details.

status description
AVAILABLE The product is available and active. It is actively being sold and new stock can be received
DISCONTINUED The product is still available, but new stock will no longer be expected.
END_OF_LIFE The product is no longer active and will no longer show in the reports.
stockLevelType
string (stockLevelType)
Enum: "ECONOMIC" "AVAILABLE"

Specifies which type of stockLevel is to be used for stock synchronization for this particular product.

type
string (productType)
Enum: "DEFAULT" "COMPOSITE" "PART" "DEFAULT_IN_PACKAGING" "BUNDLE" "GREETING_CARD" "SERVICE"

The productType indicates the type of the product .

status description
DEFAULT The product a regular product which can be sold and shipped.
DEFAULT_IN_PACKAGING Same as DEFAULT, but when ordered individually the product will be shipped without packaging.
COMPOSITE Used for products that are composed out of other products of type PART. Composite products are stocked, picked and shipped as a single SKU and cannot be split into their consituent parts. This is important as consumers will notbe able to return these parts individually. Also note that composite products can also run out of stock eventhough the parts may still be in stock. This is because new stock of composite products is created through special work orders.
BUNDLE The product is a bundled product which means that the product itself is not kept on stock, but when ordered, its parts are picked and shipped instead. When ordering a bundled product the system will automatically add the parts to the order as separate orderItems. Bundled products can be partially returned as each item is a separate product, they can also be split across shipments if packaging constraints prevent them from being shipped together.
PART The product is a part of one or more COMPOSITE products.
GREETING_CARD A special type of product used to add a personalized greeing card to the order. This requires the greeting to be added to the metadata field on the orderItem with the name extra6.
SERVICE A special type of product used in very specific situations.
weight
integer

This field indicates the weight of the product, measured in grams. It is important to note that the weight is determined when the product is first processed in an inbound shipment and can only be set or modified on request.

length
integer

The length of the product in millimeters, notice that this value can not be specified. It will be measured once the product is received for the first time.

width
integer

The width of the product in millimeters, notice that this value can not be specified. It will be measured once the product is received for the first time.

height
integer

The height of the product in millimeters, notice that this value can not be specified. It will be measured once the product is received for the first time.

name
required
string [ 1 .. 250 ] characters

Short name for the product used on packing slips if required. Note that this name is used mostly internally and when the orderItem.name is not provided.

description
string <= 10000 characters

A more complete description of the product.

hasBarcode
boolean
Default: false

Specifies if the product has a barCode or not. When set to true a barcode will be scanned during the first inbound or when already known the barcode can be specified in the barcode field.

barcode
string (productBarcode) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

The barcode of the product, when set will ensure that the hasBarcode is true as well.

hasLotNumber
boolean
Default: false

Specifies if the product has a lotNumber or not. Defaults to false.

hasSerialNumber
boolean
Default: false

Specifies if the product has a serialNumber or not. Defaults to false.

hasExpirationDate
boolean
Default: false

Specifies if the product has an expirationDate or not. Defaults to false.

expirationDateMargin
integer

The expirationDateMargin is the number of days used to determine whether particular stock can still be sold or if it has expired. Stock of a product is expired when the difference of the current date with and expirationDate of the stock is more than the expirationDateMargin speficied on the product. This field is optional when expirationDate is NONE.

expirationDateWarning
integer

The expirationDateWarning is the number of days used to determine is a product nearing its expiration date. This field is optional when expirationDate is NONE.

countryOfOrigin
string (countryCode) ^[A-Z]{2,2}(-[A-Z0-9]{2,3})?$

A valid ISO:3166-1 alpha-2 country code denoting the country of origin for the product. This value is required for international shipments.

Array of objects

An array of hsCodes (or more specific equivalents thereof) for this product. To set a default/fallback hsCode for the product use country code XX. It is not mandatory to specify hsCodes, but when provigind the element the array should contain at least one entry.

Array
country
required
string (countryCode) ^[A-Z]{2,2}(-[A-Z0-9]{2,3})?$

A valid ISO:3166-1 alpha-2 country code denoting the country or region the hsCode is applicable for. Use XX to denote the default/fallback hsCode for the product.

hsCode
required
string (hsCode) [ 6 .. 12 ] characters \d{6,12}

The hsCode stands for Harmonized System code, which is a standardized numerical method of classifying traded products. It is used by customs authorities around the world to identify and track goods as they cross borders. The Harmonized System is maintained by the World Customs Organization (WCO) and is recognized as the global standard for product classification. It consists of a six-digit code that can be further detailed with additional digits. Standard hsCodes are six digits long, but more specific variants such as TARIC can use more.

Array of objects (monetaryAmountEUR) <= 1 items

Specifies the purchase price of the product. At the moment only a single price in EUR is supported. Any currency code provided will be ignored.

Array (<= 1 items)
currency
required
stringEUR
Default: "EUR"

The currency symbol for this amount must always be set to EUR.

amount
required
number
object
extra1
string <= 250 characters
extra2
string <= 250 characters
extra3
string <= 250 characters
extra4
string <= 250 characters
extra5
string <= 250 characters
object
object (stockLevelRelation)

Convenience relationship to the stockLevel of the product.

object (stockLevelIdentifier)

Identifies a resource as a stockLevel.

id
integer
type
any
Default: "stockLevel"
Value: "stockLevel"
object
self
string <uri>
object

Provided when the product is of type BUNDLE or COMPOSITE. The array contains references to the constituent products and the quantity they appear in in this bundle.

Array of objects (productIdentifier)
Array
id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
quantity
integer > 0
object
self
string <uri>
object
self
string <uri>

Response samples

Content type
application/vnd.api+json
null

Stock

Endpoints related to managing webhooks for near-realtime notification of changes.

v3/stock

GET v3/stock

The GET v3/stock endpoint will return up to 100 stock records at a time. The definition of stock is products at a stockLocation with shared characteristics. This means that whenever two identical products are located at the same stockLocation, that both share all related attributes such as lotNumber, expirationDate, etc.

Pagination

The endpoint supports pagination to split the large collection of resources into smaller, more manageable chunks or pages. This helps to reduce the response size and to improve performance. The endpoint supports only cursor-based technique for pagination.

Filters

The GET v3/stock endpoint supports filtering on the attributes sku, locationType and modifiedOn. Each of these are explained below. Filters can be used in combination with eachother and with pagination to allow full access to the desired subset of stock.

Filtering on modifiedOn

The results returned by this service can be filtered based on the modification date of the stock. To do so make use of the filter[modifiedOn] parameter in the following manner:

  • GET {host}/v3/stock?filter[modifiedOn][lt]={date} will return stock that have been created before the provided date. Stock that has been created on that date are not included in the results.
  • GET {host}/v3/stock?filter[createdOn][gt]={date} will return stock that have been created after the provided date. Stock that has been created on that date are not included in the results.
  • GET {host}/v3/stock?filter[createdOn][gt]={date_1}&filter[createdOn][lt]={date_2} will return stock that have created between dates {date_1} and {date_1}. Stock that has been created on either date are not included in the results.

Filtering on locationType

By specifying one or more locationType values the stock returned will be filtered on that type. See the documentation of locationType for more details on the options.

  • GET {host}/v3/stock?filter[locationType][in]=INBOUND,PALLET will return all stock on either location.

Filtering on sku

By specifying the product sku it is possible to look for stock of that product specifically. Be aware that the SKU's must be URL encoded to avoid being interpreted incorrecly.

  • GET {host}/v3/stock?filter[sku][in]=09238532,TRS-001-1 will return the stock for the specified sku.

Filtering on expirationStatus

By specifying one or more expirationStatus values the stock returned will be filtered on that status. See the documentation of expirationStatus for more details on the options.

The endpoint also supports -to some degree- the inclusion of information of related resources. This option is provided to allow clients used to the v2 version of the stock endpoint to be able to use the v3 version more seemlessly. To get the details of related entities the include parameter must be added to the URI in the following way:

  • GET {host}/v3/stock?include=stockLocation will return the stock with some stockLocation related details

Note: inclusion of product has been deprecated

Limitations of GET v3/stock

  • At most 100 stock resources are returned regardles of the value provided by the page[size] query parameter.
  • Ordering is by id and in ascending order.
Authorizations:
Bearer Token
query Parameters
page[cursor]
integer >= 0
Default: 0

optional parameter, excludes ?page[number] indicating the value of the cursor. Values too low will be interpreted as if ommitted. The endpoint will use the cursor as the id of the entity that was last returned and will not include it in the response to the request.

page[size]
integer ( 0 .. 100 ]
Default: 100

optional parameter indicating the size of the page, i.e. the maximum number of entities in the response.

filter[locationType][in]
Array of strings (locationType) non-empty unique
Items Enum: "PALLET" "SPECIAL" "PICKABLE" "COOLED" "INBOUND" "OUTBOUND" "RETURN" "TRANSFER" "SECURED" "AUTOSTORE" "DAMAGED" "TO_SCRAP" "INSERTS"
Examples:
  • filter[locationType][in]=AUTOSTORE -
  • filter[locationType][in]=INBOUND -
  • filter[locationType][in]=AUTOSTORE&filter[locationType][in]=TRANSFER -

A comma separated list of locationType values to filter by such as AUTOSTORE, INBOUND, etc.

filter[sku][in]
Array of strings (productSku) non-empty unique [ items [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$ ]
Examples:
  • filter[sku][in]=TSH-000-S -
  • filter[sku][in]=8720874770299,HK-HNTSSTNG 6X -
  • filter[sku][in]=TRRE-PSU6*003;2023-10:special,THE_ULTIMATE_SKU -

A comma separated list of productSku values to filter by.

filter[modifiedOn][gt]
string <date>
Example: filter[modifiedOn][gt]=2023-01-01

Filters the response to only return items that have been modified after the specified date.

filter[modifiedOn][lt]
string <date>
Example: filter[modifiedOn][lt]=2022-01-01

Filters the response to only return items that have been modified before the specified date.

filter[expirationStatus][in]
Array of arrays

A comma separated list of expirationStatus values to filter by such as OK, EXPIRED, etc.

include
Array of strings unique
Items Value: "stockLocation"

Comma-separated list of stock related resources to include in the response under the included element

Responses

Response Schema: application/vnd.api+json
Array of objects (stock) [ 0 .. 100 ] items
Array ([ 0 .. 100 ] items)
id
integer
type
string
object
sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

quantity
integer > 0
locationType
string (stockLocationType)
Enum: "PALLET" "SPECIAL" "PICKABLE" "COOLED" "INBOUND" "OUTBOUND" "RETURN" "TRANSFER" "SECURED" "AUTOSTORE" "DAMAGED" "TO_SCRAP" "INSERTS"

The locationType indicates the (general) usage of the location of physical stock.

All locations have been classified to the one of the following types:

value description
AUTOSTORE An autostore location, which is a special type of PICKABLE location
PICKABLE A location from which stock can be picked, but different than AUTOSTORE
PALLET A storage location, not directly used for picking
INBOUND A temporary location used for new SKUs
RETURN A temporary location for returned SKUs
TRANSFER A temporary location used to transfer stock in or between warehouses
SECURED Special secured storage
COOLED Special cooled storage
OUTBOUND Location used in case of outbounds other than regular shipments
SPECIAL Special purpose locations
INSERTS Special purpose location for inserts (e.g. flyers)
DAMAGED Special purpose location for damaged goods that need to be shipped to a refurbishment party
TO_SCRAP Special purpose location for scrapped goods that remain in the warehouse until a destruction order is received.
locationCode
string (stockLocationCode)

The stockLocationCode defines a location uniquely within a warehouse. This means that the code may appear in other warehouses as well with the exception of the locations of type TRANSFER which operate between warehouses.

quality
string (stockQuality)
Enum: "OK" "DAMAGED" "TO_SCRAP" "OVERDUE" "EXPIRED"

An enumerated value indicating the quality of stock.

The following qualities exists:

quality description
OK The SKU of this stock is not damaged in any form and could be sold.
DAMAGED The SKU of this stock is damaged and requires refurbishment. Typical occurs when returned items are stained or otherwise damaged.
TO_SCRAP The SKU of this stock is damaged beyond repair and can no longer be sold.
OVERDUE The SKU of this stock is past its sell-by date and may no longer be sold.
EXPIRED The SKU of this stock is expired and can no longer be sold.
status
string (stockStatus)
Enum: "OK" "NOL_CHECK" "INBOUND" "INBOUND_RECOUNT" "RECOUNT_REQUEST" "BARCODE_NOT_SCANNABLE"

An enumerated value indicating the status of stock.

The following qualities exists:

status description
OK The stock is ok and can be sold/moved or used.
NOL_CHECK A deviation in quantity has been detected and the stock must be recounted before it can be used.
INBOUND The stock is involved in an inbound which is not complete yet.
INBOUND_RECOUNT The stock is involved in an inbound and a difference between the inboundPackingSlip and the inbound causes the stock to be recounted.
RECOUNT_REQUESTED The stock is to be recounted on request.
BARCODE_NOT_SCANNABLE The stock could not be picked due to barcode issues and must be investigated.
expirationDate
string <date>

When the products at this locatoin have the same expiration date then this is reflected by this field. As a rule, products with different expiration dates cannot be kept in the same location.

expirationStatus
string (expirationStatus)
Enum: "OK" "WARNING" "OVERDUE" "EXPIRED"

The expirationStatus shows if the expirationDate of the stock is within certain limits or has expired. The following statuses exists:

status description
OK The stock is well before the sell-by date or does not expire.
WARNING The stock is within the margin before it reaches the sell-by date, but has not crossed the sell-by date. The margin for this warning is set by the field expirationDateWarning on the product.
OVERDUE The stock has technically not expired, but can no longer be sold to consumers. It is now excluded from being shipped. The margin for this date is set by the field expirationDateMargin on the product.
EXPIRED The stock has actually expired, i.e. the expirationDate of this stock lies in the past.
lotNumber
string (lotNumber) ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

Specifies the lot number of the SKU at this location. This value is only provided if all items at this location share the same lot number. It is not possible to keep sku having different lot numbers at the same location.

quarantined
boolean
Default: false

Indicates that this particular stock is in quarantine. Stock that i placed in quarantine is excluded from many regular processes to prevent it from being shipped.

modifiedOn
string <date-time>
receivedOn
string <date>

Specifies when the items in this stock were first received.

object
object (stockLocationRelation)

Represents a relationship to a stockLocation resource.

object (stockLocationIdentifier)

Identifies a resource as stockLocation.

id
integer
type
any
Default: "stockLocation"
Value: "stockLocation"
object (productRelation)

Represents a relationship to a product resource.

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object (inboundItemRelation)

Points to the last inboundItem resource that increased the quantity of this stock.

object (inboundItemIdentification)

Identifies a resource as an inboundItem.

id
integer
type
any
Value: "inboundItem"
object
self
string <uri>
Array of stockLocationIdentifier (object)
Array
Any of
id
integer
type
any
Default: "stockLocation"
Value: "stockLocation"
object
warehouseCode
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

The code for the warehouse used to uniquely refer to an Active Ants warehouse.

The following warehouses are currently defined:

code country city customs region
BW Belgium Willebroek EU - Common Customs Tariff
DD Germany Dorsten EU - Common Customs Tariff
GN Great Brittain Northampton GB - UK Global Tariff
NN The Netherlands Nieuwegein EU - Common Customs Tariff
NR The Netherlands Roosendaal EU - Common Customs Tariff
FP France Pantin EU - Common Customs Tariff
locationType
string (stockLocationType)
Enum: "PALLET" "SPECIAL" "PICKABLE" "COOLED" "INBOUND" "OUTBOUND" "RETURN" "TRANSFER" "SECURED" "AUTOSTORE" "DAMAGED" "TO_SCRAP" "INSERTS"

The locationType indicates the (general) usage of the location of physical stock.

All locations have been classified to the one of the following types:

value description
AUTOSTORE An autostore location, which is a special type of PICKABLE location
PICKABLE A location from which stock can be picked, but different than AUTOSTORE
PALLET A storage location, not directly used for picking
INBOUND A temporary location used for new SKUs
RETURN A temporary location for returned SKUs
TRANSFER A temporary location used to transfer stock in or between warehouses
SECURED Special secured storage
COOLED Special cooled storage
OUTBOUND Location used in case of outbounds other than regular shipments
SPECIAL Special purpose locations
INSERTS Special purpose location for inserts (e.g. flyers)
DAMAGED Special purpose location for damaged goods that need to be shipped to a refurbishment party
TO_SCRAP Special purpose location for scrapped goods that remain in the warehouse until a destruction order is received.
locationCode
string (stockLocationCode)

The stockLocationCode defines a location uniquely within a warehouse. This means that the code may appear in other warehouses as well with the exception of the locations of type TRANSFER which operate between warehouses.

object
self
string
object

Pagination links that provided for convenience and in compliancy to the json:api specification for pagination.

self
string <uri>
next
string <uri>
first
string <uri>

Response samples

Content type
application/vnd.api+json
Example
{}

v3/stock/:id

GET v3/stock/:id

The GET v3/stock/:id endpoint will return a specific stock record. Note that the endpoint returns information about a single stock record which will no longer exist once all products have been moved away from it. Stock is transient and may be moved around at any time. It is therefor recommended not to persist stock and id in your systems.

The endpoint also supports -to some degree- the inclusion of information of related resources. This option is provided to allow clients used to the v2 version of the stock endpoint to be able to use the v3 version more seemlessly. To get the details of related entities the include parameter must be added to the URI in the following way:

  • GET {host}/v3/stock?include=stockLocation will return the stock with some stockLocation related details.

Note: inclusion of product has been deprecated.

Authorizations:
Bearer Token
path Parameters
id
required
string

The unique id (integer) of the stock to retrieve.

query Parameters
include
Array of strings unique
Items Value: "stockLocation"

Comma-separated list of stock related resources to include in the response under the included element

Responses

Response Schema: application/vnd.api+json
object (stock)

The stock resource represents a quantity of a product (SKU) at a stockLocation. The stock itself may carry some properties.

id
integer
type
string
object
sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

quantity
integer > 0
locationType
string (stockLocationType)
Enum: "PALLET" "SPECIAL" "PICKABLE" "COOLED" "INBOUND" "OUTBOUND" "RETURN" "TRANSFER" "SECURED" "AUTOSTORE" "DAMAGED" "TO_SCRAP" "INSERTS"

The locationType indicates the (general) usage of the location of physical stock.

All locations have been classified to the one of the following types:

value description
AUTOSTORE An autostore location, which is a special type of PICKABLE location
PICKABLE A location from which stock can be picked, but different than AUTOSTORE
PALLET A storage location, not directly used for picking
INBOUND A temporary location used for new SKUs
RETURN A temporary location for returned SKUs
TRANSFER A temporary location used to transfer stock in or between warehouses
SECURED Special secured storage
COOLED Special cooled storage
OUTBOUND Location used in case of outbounds other than regular shipments
SPECIAL Special purpose locations
INSERTS Special purpose location for inserts (e.g. flyers)
DAMAGED Special purpose location for damaged goods that need to be shipped to a refurbishment party
TO_SCRAP Special purpose location for scrapped goods that remain in the warehouse until a destruction order is received.
locationCode
string (stockLocationCode)

The stockLocationCode defines a location uniquely within a warehouse. This means that the code may appear in other warehouses as well with the exception of the locations of type TRANSFER which operate between warehouses.

quality
string (stockQuality)
Enum: "OK" "DAMAGED" "TO_SCRAP" "OVERDUE" "EXPIRED"

An enumerated value indicating the quality of stock.

The following qualities exists:

quality description
OK The SKU of this stock is not damaged in any form and could be sold.
DAMAGED The SKU of this stock is damaged and requires refurbishment. Typical occurs when returned items are stained or otherwise damaged.
TO_SCRAP The SKU of this stock is damaged beyond repair and can no longer be sold.
OVERDUE The SKU of this stock is past its sell-by date and may no longer be sold.
EXPIRED The SKU of this stock is expired and can no longer be sold.
status
string (stockStatus)
Enum: "OK" "NOL_CHECK" "INBOUND" "INBOUND_RECOUNT" "RECOUNT_REQUEST" "BARCODE_NOT_SCANNABLE"

An enumerated value indicating the status of stock.

The following qualities exists:

status description
OK The stock is ok and can be sold/moved or used.
NOL_CHECK A deviation in quantity has been detected and the stock must be recounted before it can be used.
INBOUND The stock is involved in an inbound which is not complete yet.
INBOUND_RECOUNT The stock is involved in an inbound and a difference between the inboundPackingSlip and the inbound causes the stock to be recounted.
RECOUNT_REQUESTED The stock is to be recounted on request.
BARCODE_NOT_SCANNABLE The stock could not be picked due to barcode issues and must be investigated.
expirationDate
string <date>

When the products at this locatoin have the same expiration date then this is reflected by this field. As a rule, products with different expiration dates cannot be kept in the same location.

expirationStatus
string (expirationStatus)
Enum: "OK" "WARNING" "OVERDUE" "EXPIRED"

The expirationStatus shows if the expirationDate of the stock is within certain limits or has expired. The following statuses exists:

status description
OK The stock is well before the sell-by date or does not expire.
WARNING The stock is within the margin before it reaches the sell-by date, but has not crossed the sell-by date. The margin for this warning is set by the field expirationDateWarning on the product.
OVERDUE The stock has technically not expired, but can no longer be sold to consumers. It is now excluded from being shipped. The margin for this date is set by the field expirationDateMargin on the product.
EXPIRED The stock has actually expired, i.e. the expirationDate of this stock lies in the past.
lotNumber
string (lotNumber) ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

Specifies the lot number of the SKU at this location. This value is only provided if all items at this location share the same lot number. It is not possible to keep sku having different lot numbers at the same location.

quarantined
boolean
Default: false

Indicates that this particular stock is in quarantine. Stock that i placed in quarantine is excluded from many regular processes to prevent it from being shipped.

modifiedOn
string <date-time>
receivedOn
string <date>

Specifies when the items in this stock were first received.

object
object (stockLocationRelation)

Represents a relationship to a stockLocation resource.

object (stockLocationIdentifier)

Identifies a resource as stockLocation.

id
integer
type
any
Default: "stockLocation"
Value: "stockLocation"
object (productRelation)

Represents a relationship to a product resource.

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object (inboundItemRelation)

Points to the last inboundItem resource that increased the quantity of this stock.

object (inboundItemIdentification)

Identifies a resource as an inboundItem.

id
integer
type
any
Value: "inboundItem"
object
self
string <uri>
Array of stockLocationIdentifier (object)
Array
Any of
id
integer
type
any
Default: "stockLocation"
Value: "stockLocation"
object
warehouseCode
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

The code for the warehouse used to uniquely refer to an Active Ants warehouse.

The following warehouses are currently defined:

code country city customs region
BW Belgium Willebroek EU - Common Customs Tariff
DD Germany Dorsten EU - Common Customs Tariff
GN Great Brittain Northampton GB - UK Global Tariff
NN The Netherlands Nieuwegein EU - Common Customs Tariff
NR The Netherlands Roosendaal EU - Common Customs Tariff
FP France Pantin EU - Common Customs Tariff
locationType
string (stockLocationType)
Enum: "PALLET" "SPECIAL" "PICKABLE" "COOLED" "INBOUND" "OUTBOUND" "RETURN" "TRANSFER" "SECURED" "AUTOSTORE" "DAMAGED" "TO_SCRAP" "INSERTS"

The locationType indicates the (general) usage of the location of physical stock.

All locations have been classified to the one of the following types:

value description
AUTOSTORE An autostore location, which is a special type of PICKABLE location
PICKABLE A location from which stock can be picked, but different than AUTOSTORE
PALLET A storage location, not directly used for picking
INBOUND A temporary location used for new SKUs
RETURN A temporary location for returned SKUs
TRANSFER A temporary location used to transfer stock in or between warehouses
SECURED Special secured storage
COOLED Special cooled storage
OUTBOUND Location used in case of outbounds other than regular shipments
SPECIAL Special purpose locations
INSERTS Special purpose location for inserts (e.g. flyers)
DAMAGED Special purpose location for damaged goods that need to be shipped to a refurbishment party
TO_SCRAP Special purpose location for scrapped goods that remain in the warehouse until a destruction order is received.
locationCode
string (stockLocationCode)

The stockLocationCode defines a location uniquely within a warehouse. This means that the code may appear in other warehouses as well with the exception of the locations of type TRANSFER which operate between warehouses.

object
self
string
object
self
string

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "links": {}
}

v3/stockLevels

GET v3/stockLevels

Returns the various stockLevels of the product indicated by the id in the url. The GET v3/stockLevels endpoint will return up to 100 stockLevel resource at a time. Each stockLevel is related to a single product by its id and may contain multiple levels for each warehouse the product is located in.

Pagination

The endpoint supports pagination to split the large collection of resources into smaller, more manageable chunks or pages. This helps to reduce the response size and to improve performance. The endpoint supports two forms of cursor-based pagination, both are explained below.

Iterating over all stock levels of all products

By default the end-point will enable the user to iterate over all stock levels of all products in ascending order of id (product-id). To begin iterating start by making the following request: GET v3/stockLevels. It is possible to specify a page[size] to reduce the number of items returned from 100. To iterate, invoke the URL provided in the next parameter of the response. Each response will contain another next parameter pointing to the next 'page'. This process can be continued until the response either contains fewer stockLevel resources than requested using the page[size] parameter or there is no next paramter in the response to invoke.

Iterating over stock levels that changed on or after a certain point in time

The end-point also supports iteration over the stock levels of products that have changed on or since a certain point in time. To start this iteration, invoke the endpoint using the filter filter[mutatedOn][gte]={timestamp}. The parameter page[size] can also be used in this case. For example GET v3/stockLevels?filter[mutatedOn][gte]=2023-07-28T11:25:00 will return the stockLevels of the first 100 skus that have changed since 11:25 on 2023-07-28. The response will also have a next parameter that will point to the next 'page' and by repeatedly invoking the next of each response will guarnatee that all stock levels changed since the prodivded timestamp are returned. The final response will contain fewer stockLevel resources than requested using the page[size] parameter or will have no next paramter to invoke at which point the product whose stock level was mutated latest has been returned. Note however that during this process, stock mutations may have occurred on products whose stock level was already returned in a previous response. The server will return these updated stock levels for those products again on more recent 'pages' (i.e. more towards the end of the iteration process) because these products now have a more recent mutatedOn value.

Filters

The GET v3/stockLevels endpoint supports filtering on the following attributes: sku;\

Filtering on sku

By specifying the product sku it is possible to look for stock of that product specifically. Be aware that the SKU's must be URL encoded to avoid being interpreted incorrecly. stockLevels for:

  • GET {host}/v3/stockLevels?filter[sku][in]=ABC,DEF will return the stockLevels for the products with sku ABC and DEF.
  • GET {host}/v3/stockLevels?filter[sku][in]=ABC%2CDEF will return the stockLevels for the product with sku ABC,DEF.

Filtering on mutatedOn

By specifying a timestamp to the filter filter[mutatedOn][gte] it becomes possible to iterate over all stockLevels that have changed since that timestamp. (See the section above for a more detailed explanation of this process.) The filter on mutatedOn supports only the 'greater than or equal' comparitor: filter[mutatedOn][gte]={timestamp} and will cause the sorting of the response to adhere to sort=mutadedOn,id regardless what was provided or requested. The sort query paramter is implicitly set to mutatedOn,id when using this filter.

Note that the timestamp is considered to be in UTC

Ordering

The endpoint has two orderings of the result sets, however this ordering cannot be specified by the user.

Limitations of GET v3/stockLevels

  • At most 100 stockLevel resources are returned regardles of the value provided by the page[size] query parameter.
  • The id of the stockLevel is the same as the product.
  • Ordering of results:
    • By default or when using page[cursor], the ordering is set to sort=id. This is by id of the sku\\product and in ascending order to guarantee that each sku appears exactly once.
  • When using filter[mutatedOn][gte] the ordering is set to sort=mutatedOn,id. This ordering is fixed for this filter to guarantee that no stockLevels are omitted from the results when iterating over the set of stockLevels that changed since the provided timestamp.
  • filter[mutatedOn][gte] expectes a timestamp in UTC.
  • Users are rate-limited to 500 requests per hour on this service.
Authorizations:
Bearer Token
query Parameters
page[cursor]
integer >= 0
Default: 0

optional parameter, excludes ?page[number] indicating the value of the cursor. Values too low will be interpreted as if ommitted. The endpoint will use the cursor as the id of the entity that was last returned and will not include it in the response to the request.

page[size]
integer ( 0 .. 100 ]
Default: 100

optional parameter indicating the size of the page, i.e. the maximum number of entities in the response.

filter[sku][in]
Array of strings (productSku) non-empty unique [ items [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$ ]
Examples:
  • filter[sku][in]=TSH-000-S -
  • filter[sku][in]=8720874770299,HK-HNTSSTNG 6X -
  • filter[sku][in]=TRRE-PSU6*003;2023-10:special,THE_ULTIMATE_SKU -

A comma separated list of productSku values to filter by.

filter[mutatedOn][gte]
string <date-time>
Example: filter[mutatedOn][gte]=2023-07-12T17:10:20.000321

Filters the response to only return items that have mutated on or after the specified timestamp.

sort
string
Default: "id"
Enum: "id" "mutatedOn,id"
Example: sort=mutatedOn,id

Specifies the sorting to be used on the result set, note that this parameter is silently overwritten/set depending on the use-case. See documentation for more details.

Responses

Response Schema: application/vnd.api+json
Array of objects (stockLevel)
Array
id
integer
type
any
Default: "stockLevel"
Value: "stockLevel"
object

An array of stock levels of the indicated sku and warehouse combination.

sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

Array of objects
Array
warehouse
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

Provides the warehouseCode of the warehouse the stock is located in.

stock
integer

Depending on the product specific setting, the value of stock is assigned the value of economic or available.

free
integer
economic
integer
available
integer
physical
integer

Physical stock represents the total number of items of the sku at any of the locations at Active Ants.

quarantined
integer
unavailable
integer
expected
integer
damaged
integer
toScrap
integer
overdue
integer
expired
integer
outbound
integer
object
object (productRelation)

Represents a relationship to a product resource.

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object
self
string <uri>
object

Pagination links that provided for convenience and in compliancy to the json:api specification for pagination.

self
string <uri>
next
string <uri>
first
string <uri>

Response samples

Content type
application/vnd.api+json
{}

v3/stockLevels/:id

GET v3/stockLevels/:id

Returns the various stockLevels of the product indicated by the id in the url.

Limitations of GET v3/stockLevels/:id

  • Users are rate-limited to 500 requests per hour on this service.
Authorizations:
Bearer Token
path Parameters
id
required
string

The unique id (integer) of the stockLevel to retrieve.

Responses

Response Schema: application/vnd.api+json
object (stockLevel)

Identifies a resource as a stockLevel.

id
integer
type
any
Default: "stockLevel"
Value: "stockLevel"
object

An array of stock levels of the indicated sku and warehouse combination.

sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

Array of objects
Array
warehouse
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

Provides the warehouseCode of the warehouse the stock is located in.

stock
integer

Depending on the product specific setting, the value of stock is assigned the value of economic or available.

free
integer
economic
integer
available
integer
physical
integer

Physical stock represents the total number of items of the sku at any of the locations at Active Ants.

quarantined
integer
unavailable
integer
expected
integer
damaged
integer
toScrap
integer
overdue
integer
expired
integer
outbound
integer
object
object (productRelation)

Represents a relationship to a product resource.

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object
self
string <uri>
object
self
string <uri>

Response samples

Content type
application/vnd.api+json
{}

v3/stockmutations

GET v3/stockMutations

This endpoint allows you to retrieve a list of up to 100 stock mutations at a time, sorted in ascending order by the createdOn attribute. However, this endpoint will only return stock mutations that are less than 7 days old¹. Note that any stock mutations related to shipments or damaged eturns cannot be accessed through this endpoint. Instead, mutations related to shipments must be inferred from the GET v3/shipments endpoint.

Pagination

The endpoint supports pagination to split the large collection of resources into smaller, more manageable chunks or pages. This helps to reduce the response size and to improve performance. The endpoint supports both cursor-based and number-based techniques for pagination, but it is recommended to use cursor-based as this is more performant and reliable due to page-shifting.

Filters

The GET v3/stockmutations endpoint supports filtering on the following attributes: createdOn, type and synced. Each of these are explained below. Filters can be used in combination with eachother and with pagination as to allow full access to the desired subset of stockmutations.

Filtering on createdOn

The results returned by this service can be filtered based on the creation date of the stockmutation. To do so make use of the filter[createdOn] parameter in the following manner:

  • GET {host}/v3/stockmutations?filter[createdOn][lt]={date} will return stockmutations that have been created before the provided date. Stockmutations that have been created on that date are not included in the results.
  • GET {host}/v3/stockmutations?filter[createdOn][gt]={date} will return stockmutations that have been created after the provided date. Stockmutations that were created on that date are not included in the results.
  • GET {host}/v3/stockmutations?filter[createdOn][gt]={date_1}&filter[createdOn][lt]={date_2} will return stockmutations that have created between dates {date_1} and {date_1}. Stockmutations that were created on either date are not included in the results.

Filtering on type

The endpoint allows filtering on one or more stockmutationType values. To filter on stockmutationType use the filter[type] query parameter as follows:

  • GET {host}/v3/stockmutations?filter[type][in]=RETURN will return all stockmutations that relate to a RETURN.
  • GET {host}/v3/stockmutations?filter[type][in]=RETURN,PRODUCTION will return all stockmutations that belong to RETURN or PRODUCTION.

Filtering on synced (obsolete)

To support legacy stockmutation synchronization, the endpoint allows users to request unsynced or synced stockmutations. Internally a stockmutation is marked as unsynced whenever it is created. To fetch the stockmutations that require synchronization invoke the endpoint as follows:

  • GET {host}/v3/stockmutations?filter[synced]=false will return all stockmutations that have changed since last time these were 'synchronized'. To mark them as synced use the old v2 endpoint.

Example invokations

  • GET {host}/v3/stockmutations Returns the 100 oldest stockmutations up to 7 days back. Note that the service has a limit of 7 days. This invokation is equivalent to GET {host}/v3/stockmutations?page[size]=100&page[cursor]=0 and GET {host}/v3/stockmutations?page[size]=100&page[number]=1
  • GET {host}/v3/stockmutations?filter[createdOn][gt]=2023-01-01 Returns up to 100 stockmutations that were created after 2023-01-01. The stockmutations returned are never older than 7 days, regardless of the date provided in the request.
  • GET {host}/v3/stockmutation?filter[type][in]=INBOUND,PRODUCTION Returns only stockmutations that are related to inbounds or productions
  • GET {host}/v3/stockmutations?filter[synced]=false Returns all stockmutations that haven't been synchronized. This corresponds to the old way of synchronizing information. Note that this feature will be removed when stockmutation WebHooks become available.

Limitations of the GET v3/stockmutations

  • No stockmutation older than 7 days¹ are returned.
  • At most 100 stockmutation resources are returned per request, regardless of the value provided in the page[size] query parameter.
  • Ordering is by id of the stockmutation in ascending order. ¹ Note this limit may change over time without notice!
Authorizations:
Bearer Token
query Parameters
page[cursor]
integer >= 0
Default: 0

optional parameter, excludes ?page[number] indicating the value of the cursor. Values too low will be interpreted as if ommitted. The endpoint will use the cursor as the id of the entity that was last returned and will not include it in the response to the request.

page[number]
integer > 0
Default: 1

optional parameter, excludes ?page[number] indicating the value of the cursor. Values too low will be interpreted as if omitted. The endpoint will use the cursor as the id of the entity that was last returned and will not include it in the response to the request.

page[size]
integer ( 0 .. 100 ]
Default: 100

optional parameter indicating the size of the page, i.e. the maximum number of entities in the response.

filter[synced]
boolean
Deprecated
Example: filter[synced]=false

Legacy filter to only retreive unsynchronized records of an entity. Set to 'false' to fetch all items that have not been synchronized yet. To mark items synchronized, make use of a corresponding POST operation. This filter will become obsolete when webhooks are realized for the respective resource(s). The query parameter looks like filter[synced]=false when used.

filter[createdOn][lt]
string <date>
Example: filter[createdOn][lt]=2022-01-01

Filters the response to only return items that have been created before the specified date.

filter[createdOn][gt]
string <date>
Example: filter[createdOn][gt]=2023-01-01

Filters the response to only return items that have been created after the specified date.

filter[type][in]
Array of strings (stockmutationType)
Items Enum: "INBOUND" "MOVE" "SHIPMENT" "RETURN" "CORRECTION" "COMPOSITION" "STATUS" "QUALITY" "EXPIRATION_DATE" "REVEICE_DATE" "LOT_NUMBER"

allows the specification of one or more stockmutation types to be returned

Responses

Response Schema: application/vnd.api+json
Array of objects (stockmutation) [ 0 .. 100 ] items
Array ([ 0 .. 100 ] items)
id
integer

Unique identifier of the stockmutation.

type
any

Resource Type which is a constant value stockmutation for stockmutations.

Value: "stockmutation"
object
type
string (stockmutationType)
Enum: "INBOUND" "MOVE" "SHIPMENT" "RETURN" "CORRECTION" "COMPOSITION" "STATUS" "QUALITY" "EXPIRATION_DATE" "REVEICE_DATE" "LOT_NUMBER"

The stockmutationType describes the type of mutation that occurred in a stock management system.

It can assume one following values:

type description
COMPOSITION This value indicates that two or more products have been combined to create a new product.
CORRECTION This value indicates that a correction has been made to the inventory. This could happen, for example, when an error is discovered in the stock count.
EXPIRATION_DATE Indicates the mutation affected the expirationDate of the stock
INBOUND This value indicates that a new stock has been added to the inventory. This could happen, for example, when a new product is received from a supplier.
LOT_NUMBER Indicates the mutation affected the lotNumber of the stock
MOVE This value indicates that items have moved from one location to another.
RECEIVE_DATE Indicates the mutation affected the received date of the stock
RETURN This value indicates that a previously shipped product has been returned to the inventory. This could happen, for example, when a consumer returned a product.
SHIPMENT This value indicates that an item has been assigned to a shipment. Note that the process plans each shipment ahead of time and that this stock mutation may reflect the plan prior to the actual pick.
QUALITY Indicates the mutation affected the quality of the stock
QUARANTINE Indicates the mutation affected the quarantine flag of the stock
STATUS Indicates the mutation affected the status of the stock
createdOn
string <date-time>

The date-time of when the stock mutation was created in UTC

warehouseCode
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

The code for the warehouse used to uniquely refer to an Active Ants warehouse.

The following warehouses are currently defined:

code country city customs region
BW Belgium Willebroek EU - Common Customs Tariff
DD Germany Dorsten EU - Common Customs Tariff
GN Great Brittain Northampton GB - UK Global Tariff
NN The Netherlands Nieuwegein EU - Common Customs Tariff
NR The Netherlands Roosendaal EU - Common Customs Tariff
FP France Pantin EU - Common Customs Tariff
locationType
string (stockLocationType)
Enum: "PALLET" "SPECIAL" "PICKABLE" "COOLED" "INBOUND" "OUTBOUND" "RETURN" "TRANSFER" "SECURED" "AUTOSTORE" "DAMAGED" "TO_SCRAP" "INSERTS"

Defines the type of the location, note that of all location types possible, not all are returned using this end-point

locationCode
string (stockLocationCode)

The stockLocationCode defines a location uniquely within a warehouse. This means that the code may appear in other warehouses as well with the exception of the locations of type TRANSFER which operate between warehouses.

sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

The SKU of the product whose quantity was increased or decreased

quantity
integer

The number of items added (positive) or removed (negative) a location of type locationType to the stock.

quality
string (stockQuality)
Enum: "OK" "DAMAGED" "TO_SCRAP" "OVERDUE" "EXPIRED"

An enumerated value indicating the quality of stock.

The following qualities exists:

quality description
OK The SKU of this stock is not damaged in any form and could be sold.
DAMAGED The SKU of this stock is damaged and requires refurbishment. Typical occurs when returned items are stained or otherwise damaged.
TO_SCRAP The SKU of this stock is damaged beyond repair and can no longer be sold.
OVERDUE The SKU of this stock is past its sell-by date and may no longer be sold.
EXPIRED The SKU of this stock is expired and can no longer be sold.
status
string (stockStatus)
Enum: "OK" "NOL_CHECK" "INBOUND" "INBOUND_RECOUNT" "RECOUNT_REQUEST" "BARCODE_NOT_SCANNABLE"

An enumerated value indicating the status of stock.

The following qualities exists:

status description
OK The stock is ok and can be sold/moved or used.
NOL_CHECK A deviation in quantity has been detected and the stock must be recounted before it can be used.
INBOUND The stock is involved in an inbound which is not complete yet.
INBOUND_RECOUNT The stock is involved in an inbound and a difference between the inboundPackingSlip and the inbound causes the stock to be recounted.
RECOUNT_REQUESTED The stock is to be recounted on request.
BARCODE_NOT_SCANNABLE The stock could not be picked due to barcode issues and must be investigated.
expirationDate
string <date>

(only if applicable) If the product has an expiration date.

lotNumber
string (lotNumber) ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

If the stock of the product has a lot number that is known during 'stocktime,' then this attribute will reflect that lot number. Note that for some products the lot number will not be known during stock-time, but will be scanned at during order picking.

correctionCode
string (stockCorrectionCode)
Enum: "DAMAGED" "SCRAPPED" "ADJUSTMENT" "USED" "RETURN" "DIFF_QTY_IN_BOX" "WRONG_SKU" "WRONG_QUANTITY" "LEFT_BEHIND" "INTERCOMPANY" "TO_REFURBISH" "RECOUNT" "OTHER"

In case a stockmutation pertains to a correction the stockCorrectionCode indicates the (general) reason for the correction of stock.

value description
RECOUNT The stock was corrected after it was recounted due to a recount request or a NOL
DAMAGED The stock was damaged
SCRAPPED The stock was scrapped
ADJUSTMENT A stock adjustment for other reasons like misplacements or removal on request
USED The stock is 'used'. This is typically used for flyers and inserts which are not picked like regular products
OTHER Other reason for corrections, see comments
RETURN Returned stock
DIFF_QTY_IN_BOX The bulk packaging contained a different quantity than expected
WRONG_SKU The SKU was incorrectly entered
WRONG_QUANTITY The quantity was incorrectly entered, can occur during an inbound
LEFT_BEHIND Items should have been shipped, but were left behind
INTERCOMPANY Stock moves between warehouses and companies
TO_REFURBISH Stock moved from warehouses to be shipped to refurbishment parties
remarks
string

An (optional) remark added to the stockmutation by the employee or the system.

object
object (productRelation)

Provides a link to the product which is the subject of this stockmutation. This relation is always available. Note that the attributes SKU, expirationDate and lotNumber are also provided as attributes of the stockmutation itself.

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object (returnItemRelation)

When the attribute type has the value RETURN then this relation is available.

object (returnItemIdentifier)

Identifies a resource as a returnItem.

id
integer
type
any
Value: "returnItem"
object
self
string <uri>
object (inboundItemRelation)

When the attribute type has the value INBOUND then this relation is available.

object (inboundItemIdentification)

Identifies a resource as an inboundItem.

id
integer
type
any
Value: "inboundItem"
object
self
string <uri>
object (shipmentItemRelation)

Represents a relationship to a shipmentItem resource.

object (shipmentItemIdentifier)

Identifies a resource as a shipmentItem.

id
integer
type
any
Value: "shipmentItem"
object
self
string <uri>
object
self
string <uri>
object

Pagination links that provided for convenience and in compliancy to the json:api specification for pagination.

self
string <uri>
next
string <uri>
first
string <uri>

Response samples

Content type
application/vnd.api+json
{}

WebHooks

Endpoints related to managing webhooks for near-realtime notification of changes.

v3/webhooks

GET v3/webhooks

The GET v3/webhooks endpoint returns all webhooks that have been registered.

Pagination

The endpoint supports pagination to split the large collection of resources into smaller, more manageable chunks or pages. This helps to reduce the response size and to improve performance. The endpoint supports only cursor-based technique for pagination

Filters

There are currently no filters applicable to this endpoint.

There are currently no resources to include in the response.

Limitations of GET v3/webhooks

  • At most 100 webhook resources are returned regardless of the value provided by the page[size] query parameter.
  • Ordering is by id and in ascending order.
Authorizations:
Bearer Token

Responses

Response Schema: application/vnd.api+json
Array of objects (webhook)
Array
id
integer

Unique identifier for the webhook.

type
any
Default: "webhook"
Value: "webhook"
object
event
string (webhookEvent)

Enumerates the events for which webhooks can be registered. The format of the name is {entity} '.' {action} '.' {version}. The possible values for event are predetermined and listed here:

event description
shipment.created.3 Triggered whenever a shipment has been created, stock is assigned, but no label has been requested yet.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
shipment.readyToPick.3 Triggered whenever a shipment is ready to be picked and packed.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
shipment.readyToShip.3 Triggered whenever a shipment has been picked and packed and is ready for pick-up by the carrier.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
shipment.shipped.3 Triggered whenever a shipment has been handed over tot he carrier.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
inbound.processing Happens when an inbound is created.
inbound.checking Happens after the operator clicks 'complete entire inbound', happens once per inbound and regardless if there are differences with the packing slip.
inbound.checkingUpdate Happens every time an inbound changes state from 'DIFFERENCE_GOODS_RECEIVING' (aka 'INBOUND RECOUNT') to either 'OK' or 'INBOUND CHECKED'.
inbound.checked Happens when all locations of the inbound have been checked. Note: changes to the inbound are still possible!
inbound.processed Happens when the inbound is closed. No more changes are possible and this is the final state.
isActive
boolean

Indicates if the webhook is active (true) or inactive (false).

targetUrl
string <uri>

The URL that will be invoked whenever an event of the provided type occurs.

object
self
string <uri>
object

Pagination links that provided for convenience and in compliancy to the json:api specification for pagination.

self
string <uri>
next
string <uri>
first
string <uri>

Response samples

Content type
application/vnd.api+json
{}

v3/webhooks

POST v3/webhooks

The POST v3/webhooks endpoint allows for registering a new webhook to an specific eventType of a specific entityType.

There are currently no resources to be included in the request or response.

Limitations of POST v3/webhooks

  • Only valid entity and event pairs are supported, see the definition of webhookEvent.
Authorizations:
Bearer Token
Request Body schema: application/vnd.api+json
object (webhook)

Represents a single webhook instance registered in the system. Note that webhooks may be activated and deactivated at will, but could also be deactivated automatically in case of technical issues with the targetUrl

type
any
Default: "webhook"
Value: "webhook"
object
event
string (webhookEvent)

Enumerates the events for which webhooks can be registered. The format of the name is {entity} '.' {action} '.' {version}. The possible values for event are predetermined and listed here:

event description
shipment.created.3 Triggered whenever a shipment has been created, stock is assigned, but no label has been requested yet.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
shipment.readyToPick.3 Triggered whenever a shipment is ready to be picked and packed.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
shipment.readyToShip.3 Triggered whenever a shipment has been picked and packed and is ready for pick-up by the carrier.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
shipment.shipped.3 Triggered whenever a shipment has been handed over tot he carrier.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
inbound.processing Happens when an inbound is created.
inbound.checking Happens after the operator clicks 'complete entire inbound', happens once per inbound and regardless if there are differences with the packing slip.
inbound.checkingUpdate Happens every time an inbound changes state from 'DIFFERENCE_GOODS_RECEIVING' (aka 'INBOUND RECOUNT') to either 'OK' or 'INBOUND CHECKED'.
inbound.checked Happens when all locations of the inbound have been checked. Note: changes to the inbound are still possible!
inbound.processed Happens when the inbound is closed. No more changes are possible and this is the final state.
isActive
boolean

Indicates if the webhook is active (true) or inactive (false).

targetUrl
string <uri>

The URL that will be invoked whenever an event of the provided type occurs.

object

Responses

Response Schema: application/vnd.api+json
object (webhook)

Represents a single webhook instance registered in the system. Note that webhooks may be activated and deactivated at will, but could also be deactivated automatically in case of technical issues with the targetUrl

id
integer

Unique identifier for the webhook.

type
any
Default: "webhook"
Value: "webhook"
object
event
string (webhookEvent)

Enumerates the events for which webhooks can be registered. The format of the name is {entity} '.' {action} '.' {version}. The possible values for event are predetermined and listed here:

event description
shipment.created.3 Triggered whenever a shipment has been created, stock is assigned, but no label has been requested yet.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
shipment.readyToPick.3 Triggered whenever a shipment is ready to be picked and packed.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
shipment.readyToShip.3 Triggered whenever a shipment has been picked and packed and is ready for pick-up by the carrier.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
shipment.shipped.3 Triggered whenever a shipment has been handed over tot he carrier.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
inbound.processing Happens when an inbound is created.
inbound.checking Happens after the operator clicks 'complete entire inbound', happens once per inbound and regardless if there are differences with the packing slip.
inbound.checkingUpdate Happens every time an inbound changes state from 'DIFFERENCE_GOODS_RECEIVING' (aka 'INBOUND RECOUNT') to either 'OK' or 'INBOUND CHECKED'.
inbound.checked Happens when all locations of the inbound have been checked. Note: changes to the inbound are still possible!
inbound.processed Happens when the inbound is closed. No more changes are possible and this is the final state.
isActive
boolean

Indicates if the webhook is active (true) or inactive (false).

targetUrl
string <uri>

The URL that will be invoked whenever an event of the provided type occurs.

object
self
string <uri>
object
self
string <uri>

Request samples

Content type
application/vnd.api+json
{}

Response samples

Content type
application/vnd.api+json
{}

v3/webhooks/:id

GET v3/webhooks/:id

The GET v3/webhooks/:id endpoint allows the retrieval of one specific webhooks that has been registered.

There are currently no resources to include in the response.

Limitations of GET v3/webhooks/:id

None

Authorizations:
Bearer Token
path Parameters
id
required
string

The unique id (integer) of the webhook to retrieve.

Responses

Response Schema: application/vnd.api+json
Array of objects (webhook)
Array
id
integer

Unique identifier for the webhook.

type
any
Default: "webhook"
Value: "webhook"
object
event
string (webhookEvent)

Enumerates the events for which webhooks can be registered. The format of the name is {entity} '.' {action} '.' {version}. The possible values for event are predetermined and listed here:

event description
shipment.created.3 Triggered whenever a shipment has been created, stock is assigned, but no label has been requested yet.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
shipment.readyToPick.3 Triggered whenever a shipment is ready to be picked and packed.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
shipment.readyToShip.3 Triggered whenever a shipment has been picked and packed and is ready for pick-up by the carrier.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
shipment.shipped.3 Triggered whenever a shipment has been handed over tot he carrier.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
inbound.processing Happens when an inbound is created.
inbound.checking Happens after the operator clicks 'complete entire inbound', happens once per inbound and regardless if there are differences with the packing slip.
inbound.checkingUpdate Happens every time an inbound changes state from 'DIFFERENCE_GOODS_RECEIVING' (aka 'INBOUND RECOUNT') to either 'OK' or 'INBOUND CHECKED'.
inbound.checked Happens when all locations of the inbound have been checked. Note: changes to the inbound are still possible!
inbound.processed Happens when the inbound is closed. No more changes are possible and this is the final state.
isActive
boolean

Indicates if the webhook is active (true) or inactive (false).

targetUrl
string <uri>

The URL that will be invoked whenever an event of the provided type occurs.

object
self
string <uri>
object

Pagination links that provided for convenience and in compliancy to the json:api specification for pagination.

self
string <uri>
next
string <uri>
first
string <uri>

Response samples

Content type
application/vnd.api+json
{}

v3/webhooks/:id

PUT v3/webhooks/:id

The PUT /v3/webhooks/:id endpoint allows for modifying the targetUrl and enabled state (isActive) of an existing webhook.

There are currently no resources to be included in the request or response.

Limitations of PUT v3/webhooks/:id

  • Attributes entity and event can not be modified using this operation, change these create a new webhook using POST /v3/webhooks and delete this one using DELETE /v3/webhooks/:id instead.
Authorizations:
Bearer Token
path Parameters
id
required
string

The unique id (integer) of the webhook to retrieve.

Request Body schema: application/vnd.api+json
object (webhook)

Represents a single webhook instance registered in the system. Note that webhooks may be activated and deactivated at will, but could also be deactivated automatically in case of technical issues with the targetUrl

type
any
Default: "webhook"
Value: "webhook"
object
event
string (webhookEvent)

Enumerates the events for which webhooks can be registered. The format of the name is {entity} '.' {action} '.' {version}. The possible values for event are predetermined and listed here:

event description
shipment.created.3 Triggered whenever a shipment has been created, stock is assigned, but no label has been requested yet.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
shipment.readyToPick.3 Triggered whenever a shipment is ready to be picked and packed.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
shipment.readyToShip.3 Triggered whenever a shipment has been picked and packed and is ready for pick-up by the carrier.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
shipment.shipped.3 Triggered whenever a shipment has been handed over tot he carrier.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
inbound.processing Happens when an inbound is created.
inbound.checking Happens after the operator clicks 'complete entire inbound', happens once per inbound and regardless if there are differences with the packing slip.
inbound.checkingUpdate Happens every time an inbound changes state from 'DIFFERENCE_GOODS_RECEIVING' (aka 'INBOUND RECOUNT') to either 'OK' or 'INBOUND CHECKED'.
inbound.checked Happens when all locations of the inbound have been checked. Note: changes to the inbound are still possible!
inbound.processed Happens when the inbound is closed. No more changes are possible and this is the final state.
isActive
boolean

Indicates if the webhook is active (true) or inactive (false).

targetUrl
string <uri>

The URL that will be invoked whenever an event of the provided type occurs.

object

Responses

Response Schema: application/vnd.api+json
object (webhook)

Represents a single webhook instance registered in the system. Note that webhooks may be activated and deactivated at will, but could also be deactivated automatically in case of technical issues with the targetUrl

id
integer

Unique identifier for the webhook.

type
any
Default: "webhook"
Value: "webhook"
object
event
string (webhookEvent)

Enumerates the events for which webhooks can be registered. The format of the name is {entity} '.' {action} '.' {version}. The possible values for event are predetermined and listed here:

event description
shipment.created.3 Triggered whenever a shipment has been created, stock is assigned, but no label has been requested yet.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
shipment.readyToPick.3 Triggered whenever a shipment is ready to be picked and packed.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
shipment.readyToShip.3 Triggered whenever a shipment has been picked and packed and is ready for pick-up by the carrier.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
shipment.shipped.3 Triggered whenever a shipment has been handed over tot he carrier.
The message model of the webhook will follow the GET v3/shipments/{id}?include=shipmentItems endpoint.
inbound.processing Happens when an inbound is created.
inbound.checking Happens after the operator clicks 'complete entire inbound', happens once per inbound and regardless if there are differences with the packing slip.
inbound.checkingUpdate Happens every time an inbound changes state from 'DIFFERENCE_GOODS_RECEIVING' (aka 'INBOUND RECOUNT') to either 'OK' or 'INBOUND CHECKED'.
inbound.checked Happens when all locations of the inbound have been checked. Note: changes to the inbound are still possible!
inbound.processed Happens when the inbound is closed. No more changes are possible and this is the final state.
isActive
boolean

Indicates if the webhook is active (true) or inactive (false).

targetUrl
string <uri>

The URL that will be invoked whenever an event of the provided type occurs.

object
self
string <uri>
object
self
string <uri>

Request samples

Content type
application/vnd.api+json
{}

Response samples

Content type
application/vnd.api+json
{}

v3/webhooks/:id

DELETE v3/webhooks/:id

The DELETE v3/webhooks/:id endpoint allows for complete removal of an existing webhook.

Authorizations:
Bearer Token
path Parameters
id
required
string

The unique id (integer) of the webhook to delete.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ]
}

WebHook Events

The Events section of the API documentation provides an overview of the various events that customers can subscribe to in order to receive real-time updates about key activities and changes within the system. To subscribe to these events make use of the webhook endpoints. Each event follows the same message layout as the data that would be returned by the corresponding GET operation, providing consistency to the processing of data.

shipment.readyToShip.3 Webhook

Triggered whenever a shipment has been picked, packed and sorted, ready for pick-up by the carrier The message model of the webhook will follow the GET v3/shipments/:id?include=shipmentItems endpoint.

Authorizations:
Bearer Token
Request Body schema: application/vnd.api+json

This is the message we send you whenever a new shipment has been picked, packed and sorted

id
integer
type
any
Value: "shipment"
object
status
string (shipmentStatus)
Enum: "READY_TO_PICK" "READY_TO_SORT" "READY_TO_SHIP" "SHIPPED" "ERROR"

The shipmentStatus provides insight into the step in the process of fulfilling a shipment within a warehouse.

status Description
READY_TO_PICK The shipment has been fully planned and awaits the picking by an operator.
READY_TO_SORT The shipment has been picked and packed and awaits sorting for the carrier.
READY_TO_SHIP The shipment has been sorted and awaits pick-up by the carrier.
SHIPPED The shipment has been handed over to the carrier and has dispatched from the warehouse.
ERROR An issue with the shipment has occurred, for example some labelling issue. The shipments is awaiting intervention from an operator.
readyToPickOn
string <date>

Indicates the date the shipment was fully planned and ready to be picked in a warehouse of Active Ants.

readyToShipOn
string <date>

Indicates the date the shipment was fully picked and packed in a warehouse of Active Ants, awaiting dispatch.

shippedOn
string <date>

Indicates the date the shipment has shipped from the warehouse of Active Ants.

warehouseCode
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

The code for the warehouse used to uniquely refer to an Active Ants warehouse.

The following warehouses are currently defined:

code country city customs region
BW Belgium Willebroek EU - Common Customs Tariff
DD Germany Dorsten EU - Common Customs Tariff
GN Great Brittain Northampton GB - UK Global Tariff
NN The Netherlands Nieuwegein EU - Common Customs Tariff
NR The Netherlands Roosendaal EU - Common Customs Tariff
FP France Pantin EU - Common Customs Tariff
weight
integer

The (actual) weight of the shipment in grams. This weight includes the products, packing materials and inserts.

invoicingWeight
integer

The weight used to calculate the tariff for this shipment. For some carriers this deviates from the (actual) weight as these carriers apply a 'volumetric' or 'dimensional' weight which is the largest of the actual weight and the dimensional weight of the shipment.

basketPicture
string <uri>
object
carrier
string

SOON Provides insight into which carrier is providing the transport of the shipment to the deliveryAddress or pickUpPointAddress. For example FEDEX, POSTNL, BPOST, DHL, CORREOS, POSTE ITALIANE, BRING, ROYAL MAIL, and many more.

number
integer
stage
string (shipmentTrackingStage)
Enum: "LABELLED" "ACCEPTED" "SORTED" "IN_DELIVERY" "AT_PUP" "DELIVERED" "1ST_ATTEMPT"

The shipmentTrackingStage provide a generalized set of tracking well-defined stages for shipments.

The shipmentTrackingStage are generalized over all carriers. Each carrier can and has defined their own set of stages for tracking their consignments. To accommodate the main stages that are supported by most carriers the shipmentTrackingStages generalizes the carrier-specific stages. This could mean that some details of a particular carrier are not reflected by this enumeration.

stage id Description
NEW 0 The shipment is newly created and has not been assigned to a carrier yet.
LABELED 1 A label has created for the shipment.
ACCEPTED 2 The shipment has been accepted, received and scanned by the carrier.
SORTED 3 The shipment is been sorted before delivery.
IN_TRANSIT 4 The shipment is being delivered, but has not been delivered yet.
ATTEMPTED 8 or 10 An unsuccessful attempt to deliver the shipment has been made.
AVAILABLE_FOR_PICKUP 5 The shipment has been delivered to the pick up point for the recipient to collect.
DELIVERED 7 The shipment has been delivered.
RETURNED 19 The shipment has been returned to the sender after a failing be delivered.
TRACKED_EXTERNALLY 18 There is no tracking information being shared with Active Ants for this shipment.

Note the id column corresponds to the v2 endpoint values for the stage

status
string
Enum: "OK" "ERROR" "WARNING"
url
string <uri>
Array of objects
Array
number
string
parcelNumber
string

The parcel number as assigned by the carrier

trackingUrl
string <uri>

A tracking url specific to this collo

returnLabel
string
object

Repeats the metadata as specified on the order.

extra1
string
extra2
string
extra3
string
extra4
string
extra5
string
object
object (orderRelation)

Represents a relationship to an order resource.

object (orderIdentification)

Identifies a resource as an order.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
self
string <uri>
object (orderTypeRelation)

Represents a relationship to an orderType resource.

object (orderTypeIdentifier)

Identifies a resource as an orderType.

id
integer
type
stringorderType
Default: "orderType"
object
self
string <uri>
object (shipmentItemsRelation)

Represents a relationship to multiple shipmentItem resources.

Array of objects (shipmentItemIdentifier)
Array
id
integer
type
any
Value: "shipmentItem"
object
self
string <uri>
object (shippingMethodRelation)

Represents a relationship to a shippingMethod resource.

object (shippingMethodIdentifier)

Identifies a resource as a shippingMethod.

id
integer
type
any
Value: "shippingMethod"
object
self
string <uri>
Array of shipmentItemIdentifier (object)
Array
Any of
id
integer
type
any
Value: "shipmentItem"
object
sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

quantity
integer >= 0
lotNumber
string (lotNumber) ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

A lot number is a unique identification number assigned to a specific batch or lot of a product during the manufacturing process. It is used to track and trace the product's manufacturing and distribution history, including when and where it was produced, which raw materials were used, and to which customers it was shipped.

Lot numbers can be alphanumeric and may include information such as the date and time of production, the location of production, and the machine or equipment used. They are often printed on the product's packaging or label, as well as on associated documentation such as batch records and certificates of analysis.

expirationDate
string <date>
serialNumbers
Array of strings[ items non-empty ]
object
object (orderItemRelation)

Represents a relationship to an orderItem resource.

object (orderItemIdentification)

Identifies a resource as an orderItem.

id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
self
string <uri>
object (productRelation)

Represents a relationship to a product resource.

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object (shipmentRelation)

Represents a relationship to a shipment resource.

object (shipmentIdentifier)

Identifies a resource as a shipment.

id
integer
type
any
Value: "shipment"
object
self
string <uri>
object
self
string <uri>

Responses

Request samples

Content type
application/vnd.api+json
{}

shipment.shipped.3 Webhook

Triggered whenever a shipment has been handed over to the carrier. The message model of the webhook will follow the GET v3/shipments/:id?include=shipmentItems endpoint.

Authorizations:
Bearer Token
Request Body schema: application/vnd.api+json

This is the message we send you whenever a new shipment has been handed over to the carrier

id
integer
type
any
Value: "shipment"
object
status
string (shipmentStatus)
Enum: "READY_TO_PICK" "READY_TO_SORT" "READY_TO_SHIP" "SHIPPED" "ERROR"

The shipmentStatus provides insight into the step in the process of fulfilling a shipment within a warehouse.

status Description
READY_TO_PICK The shipment has been fully planned and awaits the picking by an operator.
READY_TO_SORT The shipment has been picked and packed and awaits sorting for the carrier.
READY_TO_SHIP The shipment has been sorted and awaits pick-up by the carrier.
SHIPPED The shipment has been handed over to the carrier and has dispatched from the warehouse.
ERROR An issue with the shipment has occurred, for example some labelling issue. The shipments is awaiting intervention from an operator.
readyToPickOn
string <date>

Indicates the date the shipment was fully planned and ready to be picked in a warehouse of Active Ants.

readyToShipOn
string <date>

Indicates the date the shipment was fully picked and packed in a warehouse of Active Ants, awaiting dispatch.

shippedOn
string <date>

Indicates the date the shipment has shipped from the warehouse of Active Ants.

warehouseCode
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

The code for the warehouse used to uniquely refer to an Active Ants warehouse.

The following warehouses are currently defined:

code country city customs region
BW Belgium Willebroek EU - Common Customs Tariff
DD Germany Dorsten EU - Common Customs Tariff
GN Great Brittain Northampton GB - UK Global Tariff
NN The Netherlands Nieuwegein EU - Common Customs Tariff
NR The Netherlands Roosendaal EU - Common Customs Tariff
FP France Pantin EU - Common Customs Tariff
weight
integer

The (actual) weight of the shipment in grams. This weight includes the products, packing materials and inserts.

invoicingWeight
integer

The weight used to calculate the tariff for this shipment. For some carriers this deviates from the (actual) weight as these carriers apply a 'volumetric' or 'dimensional' weight which is the largest of the actual weight and the dimensional weight of the shipment.

basketPicture
string <uri>
object
carrier
string

SOON Provides insight into which carrier is providing the transport of the shipment to the deliveryAddress or pickUpPointAddress. For example FEDEX, POSTNL, BPOST, DHL, CORREOS, POSTE ITALIANE, BRING, ROYAL MAIL, and many more.

number
integer
stage
string (shipmentTrackingStage)
Enum: "LABELLED" "ACCEPTED" "SORTED" "IN_DELIVERY" "AT_PUP" "DELIVERED" "1ST_ATTEMPT"

The shipmentTrackingStage provide a generalized set of tracking well-defined stages for shipments.

The shipmentTrackingStage are generalized over all carriers. Each carrier can and has defined their own set of stages for tracking their consignments. To accommodate the main stages that are supported by most carriers the shipmentTrackingStages generalizes the carrier-specific stages. This could mean that some details of a particular carrier are not reflected by this enumeration.

stage id Description
NEW 0 The shipment is newly created and has not been assigned to a carrier yet.
LABELED 1 A label has created for the shipment.
ACCEPTED 2 The shipment has been accepted, received and scanned by the carrier.
SORTED 3 The shipment is been sorted before delivery.
IN_TRANSIT 4 The shipment is being delivered, but has not been delivered yet.
ATTEMPTED 8 or 10 An unsuccessful attempt to deliver the shipment has been made.
AVAILABLE_FOR_PICKUP 5 The shipment has been delivered to the pick up point for the recipient to collect.
DELIVERED 7 The shipment has been delivered.
RETURNED 19 The shipment has been returned to the sender after a failing be delivered.
TRACKED_EXTERNALLY 18 There is no tracking information being shared with Active Ants for this shipment.

Note the id column corresponds to the v2 endpoint values for the stage

status
string
Enum: "OK" "ERROR" "WARNING"
url
string <uri>
Array of objects
Array
number
string
parcelNumber
string

The parcel number as assigned by the carrier

trackingUrl
string <uri>

A tracking url specific to this collo

returnLabel
string
object

Repeats the metadata as specified on the order.

extra1
string
extra2
string
extra3
string
extra4
string
extra5
string
object
object (orderRelation)

Represents a relationship to an order resource.

object (orderIdentification)

Identifies a resource as an order.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
self
string <uri>
object (orderTypeRelation)

Represents a relationship to an orderType resource.

object (orderTypeIdentifier)

Identifies a resource as an orderType.

id
integer
type
stringorderType
Default: "orderType"
object
self
string <uri>
object (shipmentItemsRelation)

Represents a relationship to multiple shipmentItem resources.

Array of objects (shipmentItemIdentifier)
Array
id
integer
type
any
Value: "shipmentItem"
object
self
string <uri>
object (shippingMethodRelation)

Represents a relationship to a shippingMethod resource.

object (shippingMethodIdentifier)

Identifies a resource as a shippingMethod.

id
integer
type
any
Value: "shippingMethod"
object
self
string <uri>
Array of shipmentItemIdentifier (object)
Array
Any of
id
integer
type
any
Value: "shipmentItem"
object
sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

quantity
integer >= 0
lotNumber
string (lotNumber) ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

A lot number is a unique identification number assigned to a specific batch or lot of a product during the manufacturing process. It is used to track and trace the product's manufacturing and distribution history, including when and where it was produced, which raw materials were used, and to which customers it was shipped.

Lot numbers can be alphanumeric and may include information such as the date and time of production, the location of production, and the machine or equipment used. They are often printed on the product's packaging or label, as well as on associated documentation such as batch records and certificates of analysis.

expirationDate
string <date>
serialNumbers
Array of strings[ items non-empty ]
object
object (orderItemRelation)

Represents a relationship to an orderItem resource.

object (orderItemIdentification)

Identifies a resource as an orderItem.

id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
self
string <uri>
object (productRelation)

Represents a relationship to a product resource.

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object (shipmentRelation)

Represents a relationship to a shipment resource.

object (shipmentIdentifier)

Identifies a resource as a shipment.

id
integer
type
any
Value: "shipment"
object
self
string <uri>
object
self
string <uri>

Responses

Request samples

Content type
application/vnd.api+json
{}

inbound.processing Webhook

Happens when an inbound is created.

Authorizations:
Bearer Token
Request Body schema: application/vnd.api+json

This is the message we send you whenever an inbound has been created

id
integer
type
any
Value: "inbound"
object
reference
string

Shorthand reference of the inbound.

status
string (inboundStatus)
Enum: "PROCESSING" "CHECKING" "CHECKED" "COMPLETED"

The states of an inbound are

State Description
PROCESSING The initial stage of the inbound in which SKUs are being counted and moved from the pallets to warehouse locations. At this moment SKUs are not counted as stock.
CHECKING All SKUs have been counted and placed on warehouse locations. When th quantities on the inbound match those on the inboundPackingSlip the locations contianint that SKU are released and counted towards available stock levels. All SKUs with differences must first be checked.
CHECKED All totals of the SKUs have checked and any differences between the inbound and inboundPackingSlip have been confirmed or corrected. Some misplaced SKUs might still be added to the inbound until it is CLOSED.
COMPLETED The inbound is completed and no more changes can be made to the data."
receivedIn
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

Indicates the warehouse where the inbound is received.

createdOn
string <date-time>

Timestamp of when the inbound was created which typically coincides with the PROCESSING status.

checkingOn
string <date-time>

Timestamp of when the inbound reached the CHECKING status.

completedOn
string <date-time>

Timestamp of when the inbound reached the COMPLETED status

object
object (inboundPackingSlipRelations)

An inbound can only be linked to at most one inboundPackingSlip which is used to determine the completeness of the inbound. If no inboundPackingSlip was linked, then the completeness of the inbound can not be verified and is assumed to be correct.

object (inboundPackingSlipIdentification)

Identifies a resource as a inboundPackingSlip.

id
integer

The id is an internally assigned id of a inboundPackingSlip. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "inboundPackingSlip"
Value: "inboundPackingSlip"
object
self
string <uri>
Array of inboundItemIdentification (object)
Array
Any of
id
integer
type
any
Value: "inboundItem"
object
quantity
integer > 0

The quantity of the sku received. Note that the same sku could appear multiple times on the inbound depending on how the items have been unpacked and counted.

sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

lotNumber
string (lotNumber) ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

A lot number is a unique identification number assigned to a specific batch or lot of a product during the manufacturing process. It is used to track and trace the product's manufacturing and distribution history, including when and where it was produced, which raw materials were used, and to which customers it was shipped.

Lot numbers can be alphanumeric and may include information such as the date and time of production, the location of production, and the machine or equipment used. They are often printed on the product's packaging or label, as well as on associated documentation such as batch records and certificates of analysis.

expirationDate
string <date>

If applicable, the

object
object (productRelation)

Links to the product that was recieved as part of this inboundItem

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object (inboundPackingSlipItemRelation)

Links to the inboundPackingSlipItem that was expecting this inboundItem.

object (inboundPackingSlipItemIdentifier)

Identifies a resource as a inboundPackingSlipItem.

id
integer

The id is an internally assigned id of a inboundPackingSlipItem. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Value: "inboundPackingSlipItem"
object
self
string <uri>
object
self
string <uri>

Responses

Request samples

Content type
application/vnd.api+json
{}

inbound.checking Webhook

Happens after the operator clicks 'complete entire inbound', happens once per inbound and regardless if there are differences with the packing slip.

Authorizations:
Bearer Token
Request Body schema: application/vnd.api+json

This is the message we send you whenever an inbound has been completed

id
integer
type
any
Value: "inbound"
object
reference
string

Shorthand reference of the inbound.

status
string (inboundStatus)
Enum: "PROCESSING" "CHECKING" "CHECKED" "COMPLETED"

The states of an inbound are

State Description
PROCESSING The initial stage of the inbound in which SKUs are being counted and moved from the pallets to warehouse locations. At this moment SKUs are not counted as stock.
CHECKING All SKUs have been counted and placed on warehouse locations. When th quantities on the inbound match those on the inboundPackingSlip the locations contianint that SKU are released and counted towards available stock levels. All SKUs with differences must first be checked.
CHECKED All totals of the SKUs have checked and any differences between the inbound and inboundPackingSlip have been confirmed or corrected. Some misplaced SKUs might still be added to the inbound until it is CLOSED.
COMPLETED The inbound is completed and no more changes can be made to the data."
receivedIn
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

Indicates the warehouse where the inbound is received.

createdOn
string <date-time>

Timestamp of when the inbound was created which typically coincides with the PROCESSING status.

checkingOn
string <date-time>

Timestamp of when the inbound reached the CHECKING status.

completedOn
string <date-time>

Timestamp of when the inbound reached the COMPLETED status

object
object (inboundPackingSlipRelations)

An inbound can only be linked to at most one inboundPackingSlip which is used to determine the completeness of the inbound. If no inboundPackingSlip was linked, then the completeness of the inbound can not be verified and is assumed to be correct.

object (inboundPackingSlipIdentification)

Identifies a resource as a inboundPackingSlip.

id
integer

The id is an internally assigned id of a inboundPackingSlip. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "inboundPackingSlip"
Value: "inboundPackingSlip"
object
self
string <uri>
Array of inboundItemIdentification (object)
Array
Any of
id
integer
type
any
Value: "inboundItem"
object
quantity
integer > 0

The quantity of the sku received. Note that the same sku could appear multiple times on the inbound depending on how the items have been unpacked and counted.

sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

lotNumber
string (lotNumber) ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

A lot number is a unique identification number assigned to a specific batch or lot of a product during the manufacturing process. It is used to track and trace the product's manufacturing and distribution history, including when and where it was produced, which raw materials were used, and to which customers it was shipped.

Lot numbers can be alphanumeric and may include information such as the date and time of production, the location of production, and the machine or equipment used. They are often printed on the product's packaging or label, as well as on associated documentation such as batch records and certificates of analysis.

expirationDate
string <date>

If applicable, the

object
object (productRelation)

Links to the product that was recieved as part of this inboundItem

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object (inboundPackingSlipItemRelation)

Links to the inboundPackingSlipItem that was expecting this inboundItem.

object (inboundPackingSlipItemIdentifier)

Identifies a resource as a inboundPackingSlipItem.

id
integer

The id is an internally assigned id of a inboundPackingSlipItem. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Value: "inboundPackingSlipItem"
object
self
string <uri>
object
self
string <uri>

Responses

Request samples

Content type
application/vnd.api+json
{}

inbound.checkingUpdate Webhook

Happens every time an inbound changes state from 'DIFFERENCE_GOODS_RECEIVING' (aka 'INBOUND RECOUNT') to either 'OK' or 'INBOUND CHECKED'.

Authorizations:
Bearer Token
Request Body schema: application/vnd.api+json

This is the message we send you whenever an inbound changes state from 'DIFFERENCE_GOODS_RECEIVING' (aka 'INBOUND RECOUNT') to either 'OK' or 'INBOUND CHECKED'

id
integer
type
any
Value: "inbound"
object
reference
string

Shorthand reference of the inbound.

status
string (inboundStatus)
Enum: "PROCESSING" "CHECKING" "CHECKED" "COMPLETED"

The states of an inbound are

State Description
PROCESSING The initial stage of the inbound in which SKUs are being counted and moved from the pallets to warehouse locations. At this moment SKUs are not counted as stock.
CHECKING All SKUs have been counted and placed on warehouse locations. When th quantities on the inbound match those on the inboundPackingSlip the locations contianint that SKU are released and counted towards available stock levels. All SKUs with differences must first be checked.
CHECKED All totals of the SKUs have checked and any differences between the inbound and inboundPackingSlip have been confirmed or corrected. Some misplaced SKUs might still be added to the inbound until it is CLOSED.
COMPLETED The inbound is completed and no more changes can be made to the data."
receivedIn
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

Indicates the warehouse where the inbound is received.

createdOn
string <date-time>

Timestamp of when the inbound was created which typically coincides with the PROCESSING status.

checkingOn
string <date-time>

Timestamp of when the inbound reached the CHECKING status.

completedOn
string <date-time>

Timestamp of when the inbound reached the COMPLETED status

object
object (inboundPackingSlipRelations)

An inbound can only be linked to at most one inboundPackingSlip which is used to determine the completeness of the inbound. If no inboundPackingSlip was linked, then the completeness of the inbound can not be verified and is assumed to be correct.

object (inboundPackingSlipIdentification)

Identifies a resource as a inboundPackingSlip.

id
integer

The id is an internally assigned id of a inboundPackingSlip. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "inboundPackingSlip"
Value: "inboundPackingSlip"
object
self
string <uri>
Array of inboundItemIdentification (object)
Array
Any of
id
integer
type
any
Value: "inboundItem"
object
quantity
integer > 0

The quantity of the sku received. Note that the same sku could appear multiple times on the inbound depending on how the items have been unpacked and counted.

sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

lotNumber
string (lotNumber) ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

A lot number is a unique identification number assigned to a specific batch or lot of a product during the manufacturing process. It is used to track and trace the product's manufacturing and distribution history, including when and where it was produced, which raw materials were used, and to which customers it was shipped.

Lot numbers can be alphanumeric and may include information such as the date and time of production, the location of production, and the machine or equipment used. They are often printed on the product's packaging or label, as well as on associated documentation such as batch records and certificates of analysis.

expirationDate
string <date>

If applicable, the

object
object (productRelation)

Links to the product that was recieved as part of this inboundItem

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object (inboundPackingSlipItemRelation)

Links to the inboundPackingSlipItem that was expecting this inboundItem.

object (inboundPackingSlipItemIdentifier)

Identifies a resource as a inboundPackingSlipItem.

id
integer

The id is an internally assigned id of a inboundPackingSlipItem. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Value: "inboundPackingSlipItem"
object
self
string <uri>
object
self
string <uri>

Responses

Request samples

Content type
application/vnd.api+json
{}

inbound.checked Webhook

Happens when all locations of the inbound have been checked. Note: changes to the inbound are still possible!

Authorizations:
Bearer Token
Request Body schema: application/vnd.api+json

This is the message we send you when all locations of an inbound have been checked

id
integer
type
any
Value: "inbound"
object
reference
string

Shorthand reference of the inbound.

status
string (inboundStatus)
Enum: "PROCESSING" "CHECKING" "CHECKED" "COMPLETED"

The states of an inbound are

State Description
PROCESSING The initial stage of the inbound in which SKUs are being counted and moved from the pallets to warehouse locations. At this moment SKUs are not counted as stock.
CHECKING All SKUs have been counted and placed on warehouse locations. When th quantities on the inbound match those on the inboundPackingSlip the locations contianint that SKU are released and counted towards available stock levels. All SKUs with differences must first be checked.
CHECKED All totals of the SKUs have checked and any differences between the inbound and inboundPackingSlip have been confirmed or corrected. Some misplaced SKUs might still be added to the inbound until it is CLOSED.
COMPLETED The inbound is completed and no more changes can be made to the data."
receivedIn
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

Indicates the warehouse where the inbound is received.

createdOn
string <date-time>

Timestamp of when the inbound was created which typically coincides with the PROCESSING status.

checkingOn
string <date-time>

Timestamp of when the inbound reached the CHECKING status.

completedOn
string <date-time>

Timestamp of when the inbound reached the COMPLETED status

object
object (inboundPackingSlipRelations)

An inbound can only be linked to at most one inboundPackingSlip which is used to determine the completeness of the inbound. If no inboundPackingSlip was linked, then the completeness of the inbound can not be verified and is assumed to be correct.

object (inboundPackingSlipIdentification)

Identifies a resource as a inboundPackingSlip.

id
integer

The id is an internally assigned id of a inboundPackingSlip. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "inboundPackingSlip"
Value: "inboundPackingSlip"
object
self
string <uri>
Array of inboundItemIdentification (object)
Array
Any of
id
integer
type
any
Value: "inboundItem"
object
quantity
integer > 0

The quantity of the sku received. Note that the same sku could appear multiple times on the inbound depending on how the items have been unpacked and counted.

sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

lotNumber
string (lotNumber) ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

A lot number is a unique identification number assigned to a specific batch or lot of a product during the manufacturing process. It is used to track and trace the product's manufacturing and distribution history, including when and where it was produced, which raw materials were used, and to which customers it was shipped.

Lot numbers can be alphanumeric and may include information such as the date and time of production, the location of production, and the machine or equipment used. They are often printed on the product's packaging or label, as well as on associated documentation such as batch records and certificates of analysis.

expirationDate
string <date>

If applicable, the

object
object (productRelation)

Links to the product that was recieved as part of this inboundItem

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object (inboundPackingSlipItemRelation)

Links to the inboundPackingSlipItem that was expecting this inboundItem.

object (inboundPackingSlipItemIdentifier)

Identifies a resource as a inboundPackingSlipItem.

id
integer

The id is an internally assigned id of a inboundPackingSlipItem. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Value: "inboundPackingSlipItem"
object
self
string <uri>
object
self
string <uri>

Responses

Request samples

Content type
application/vnd.api+json
{}

inbound.processed Webhook

Happens when the inbound is closed. No more changes are possible and this is the final state.

Authorizations:
Bearer Token
Request Body schema: application/vnd.api+json

This is the message we send you whenever an inbound has been closed

id
integer
type
any
Value: "inbound"
object
reference
string

Shorthand reference of the inbound.

status
string (inboundStatus)
Enum: "PROCESSING" "CHECKING" "CHECKED" "COMPLETED"

The states of an inbound are

State Description
PROCESSING The initial stage of the inbound in which SKUs are being counted and moved from the pallets to warehouse locations. At this moment SKUs are not counted as stock.
CHECKING All SKUs have been counted and placed on warehouse locations. When th quantities on the inbound match those on the inboundPackingSlip the locations contianint that SKU are released and counted towards available stock levels. All SKUs with differences must first be checked.
CHECKED All totals of the SKUs have checked and any differences between the inbound and inboundPackingSlip have been confirmed or corrected. Some misplaced SKUs might still be added to the inbound until it is CLOSED.
COMPLETED The inbound is completed and no more changes can be made to the data."
receivedIn
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

Indicates the warehouse where the inbound is received.

createdOn
string <date-time>

Timestamp of when the inbound was created which typically coincides with the PROCESSING status.

checkingOn
string <date-time>

Timestamp of when the inbound reached the CHECKING status.

completedOn
string <date-time>

Timestamp of when the inbound reached the COMPLETED status

object
object (inboundPackingSlipRelations)

An inbound can only be linked to at most one inboundPackingSlip which is used to determine the completeness of the inbound. If no inboundPackingSlip was linked, then the completeness of the inbound can not be verified and is assumed to be correct.

object (inboundPackingSlipIdentification)

Identifies a resource as a inboundPackingSlip.

id
integer

The id is an internally assigned id of a inboundPackingSlip. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "inboundPackingSlip"
Value: "inboundPackingSlip"
object
self
string <uri>
Array of inboundItemIdentification (object)
Array
Any of
id
integer
type
any
Value: "inboundItem"
object
quantity
integer > 0

The quantity of the sku received. Note that the same sku could appear multiple times on the inbound depending on how the items have been unpacked and counted.

sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

lotNumber
string (lotNumber) ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

A lot number is a unique identification number assigned to a specific batch or lot of a product during the manufacturing process. It is used to track and trace the product's manufacturing and distribution history, including when and where it was produced, which raw materials were used, and to which customers it was shipped.

Lot numbers can be alphanumeric and may include information such as the date and time of production, the location of production, and the machine or equipment used. They are often printed on the product's packaging or label, as well as on associated documentation such as batch records and certificates of analysis.

expirationDate
string <date>

If applicable, the

object
object (productRelation)

Links to the product that was recieved as part of this inboundItem

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object (inboundPackingSlipItemRelation)

Links to the inboundPackingSlipItem that was expecting this inboundItem.

object (inboundPackingSlipItemIdentifier)

Identifies a resource as a inboundPackingSlipItem.

id
integer

The id is an internally assigned id of a inboundPackingSlipItem. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Value: "inboundPackingSlipItem"
object
self
string <uri>
object
self
string <uri>

Responses

Request samples

Content type
application/vnd.api+json
{}

Models

order

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
externalOrderNumber
required
string (externalOrderNumber) <= 50 characters

The externalOrderNumber as specified during creation of the order.

reference
string

Optional field to store an internal reference to the order

orderedOn
string <date>

An optional field to place the date the consumer placed the order, this may be a date in the past. For example when the order was forwarded much later to the shop api.

consumerReference
string

Optional reference provided by the consumer of this order`

promotionCode
string

Any promotion code the consumer used when placing the order.

locale
required
string (localeCode) ^([a-zA-Z]+(?:-[a-zA-Z]+)?)

The locale defines (among other things) the language used in communications, inserts and possibly packaging relating to this order. The locale has to be a full locale like en-GB

email
string <email>

The email address of the consumer. This email address could be used by Active Ants, the carrier o customs in various notification messages regarding the shipments(s) related to this order.

phoneNumber
string (phoneNumber) <= 32 characters ^[\d\s\+\(\)-\.\\\/]+$

The consumer's phone number which might be used by the carrier or customs to contact the consumer regarding the shipment(s) related to this order.

vatNumber
string
fulfillFrom
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

When provided indicates the warehouse from which each orderItem must be fulfilled. When not provided the system will select the warehouse based on the warehouse strategy configuration for your company. Note that this value can also be set at orderItem-level which supercedes the specification at order-level or the warehouse strategy.

preferredShippingDate
string <date>

Allows the specification of a future date at which the order is to be shipped.

allowPartialDelivery
boolean
Default: false

When set to true the order may be split into multiple shipments in case there is insufficient stock to filfill the order in a single shipment or from a single warehouse.

onHold
boolean
Default: false

When set to true prevents the order from being shipped until released.

object

Allows the specification of arbitrary name-value pairs. note currently only the names 'extra1', 'extra2', 'extra3', 'extra4' and 'extra5' are supported and are linked to functionality (contact support for more information).

extra1
string
extra2
string
extra3
string
extra4
string
extra5
string
channelIdentifier
string (channelOrderIdentifier) <= 250 characters

The channelIdentifier is the (technical) id for the order as assigned by the external channel. For example Shopify, Amazon, Bol, Zalando, etc. may assign a unique id for communication and synchronization purposes.

currency
string (currencyCode) = 3 characters [A-Z]{3}
Default: "EUR"

Defines the currency of the order and all its orderItems. If omitted, the value EUR is assumed. The currency is used to convert the price of each orderItem to an acceptable currency when a shipment must be declaring its value to customs agencies.

object
required
object (orderTypeRelation)

Represents a relationship to an orderType resource.

object (orderTypeIdentifier)

Identifies a resource as an orderType.

id
integer
type
stringorderType
Default: "orderType"
object
self
string <uri>
object (orderItemsRelation)

Represents a relationship to multiple orderItem resources.

Array of objects (orderItemIdentification)
Array
id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
self
string <uri>
required
object (addressRelation)

Denotes the address and name where the order must be delivered, unless a pickUpPoint has been specified in which case the order will be delivered to the pick-up point instead

object (addressIdentification)

Identifies a resource as an address.

id
integer
type
required
any
Default: "address"
Value: "address"
object (addressRelation)

Optional address that can be used as billing address. When not provided it is assumed to be the same as the deliveryAddress.

object (addressIdentification)

Identifies a resource as an address.

id
integer
type
required
any
Default: "address"
Value: "address"
object (pickUpPointRelation)

Optional: specify the address of the pick-up point in case the order is to be delivered at a pick-up point. Note that the deliveryAddress is still required.

object (pickUpPointIdentifier)

Identifies a resource as an pickUpPoint.

id
integer
type
required
any
Default: "pickUpPoint"
Value: "pickUpPoint"
object (shippingMethodRelation)

Optional identifier to the shippingMethod preferred for this order. Note that this method is preferred, but not guaranteed since the method might not be available at the warehouse from where the order might be fulfilled, or the shipment may not be compatible with the preferred method. IMPORTANT: the v3 endpoints use the mainShippingMethodId as returned by the GET settings/get endpoints under /MainShippingMethods/id.

object (shippingMethodIdentifier)

Identifies a resource as a shippingMethod.

id
integer
type
any
Value: "shippingMethod"
object
self
string <uri>
Array of orderItemIdentification (object) or addressIdentification (object) or pickUpPointIdentifier (object) or orderAttachmentIdentification (object)

An array of resources included with the order, use the type property to identify the resource's type.

Array
Any of
id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
sku
required
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

channelIdentifier
string (channelOrderItemIdentifier) <= 250 characters

The channelIdentifier is the (technical) id for the orderItem as assigned by the external channel. For example Shopify, Amazon, Bol, Zalando, etc. may assign a unique id for communication and synchronization purposes.

quantity
required
integer
fulfillFrom
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

When specified indicates that the item can only be fulfilled from the indicated warehouse.

price
number decimal places <= 2

Specifies the price of a single unit of the product as sold to the consumer / recipient. Note that all products sold to consumers and shipped internationally must have a price greater than 0.00, as many customs agencies do not accept negative values. Furthermore, some carriers may impose a minimum price—typically around 1.000 in the order’s currency.

vat
number decimal places <= 3 [ 0 .. 1 )
Default: 0

This field represents the VAT percentage that was included in the price. If omitted, the value 0.000 is assumed as the percentage. The value must be between [0.000 and 1.000⟩, with an accuracy of up to three decimal places after the comma.

name
string

The name / description for this product on this orderItem. If no value is provided here, then the name of the product will be used instead whenever a name is required (for example when declaring to customs)

object (metadata)

Allows the specification of arbitrary name-value pairs. note currently only the names 'extra6' and 'extra7' are supported.

extra6
string
extra7
string
object
object (orderRelation)

Represents a relationship to an order resource.

object (orderIdentification)

Identifies a resource as an order.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
self
string <uri>
object (productRelation)

Represents a relationship to a product resource.

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object
self
string <uri>
{
  • "id": 24006341,
  • "type": "order",
  • "attributes": {
    },
  • "relationships": {},
  • "included": [
    ],
  • "links": {}
}

orderItem

id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
sku
required
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

channelIdentifier
string (channelOrderItemIdentifier) <= 250 characters

The channelIdentifier is the (technical) id for the orderItem as assigned by the external channel. For example Shopify, Amazon, Bol, Zalando, etc. may assign a unique id for communication and synchronization purposes.

quantity
required
integer
fulfillFrom
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

When specified indicates that the item can only be fulfilled from the indicated warehouse.

price
number decimal places <= 2

Specifies the price of a single unit of the product as sold to the consumer / recipient. Note that all products sold to consumers and shipped internationally must have a price greater than 0.00, as many customs agencies do not accept negative values. Furthermore, some carriers may impose a minimum price—typically around 1.000 in the order’s currency.

vat
number decimal places <= 3 [ 0 .. 1 )
Default: 0

This field represents the VAT percentage that was included in the price. If omitted, the value 0.000 is assumed as the percentage. The value must be between [0.000 and 1.000⟩, with an accuracy of up to three decimal places after the comma.

name
string

The name / description for this product on this orderItem. If no value is provided here, then the name of the product will be used instead whenever a name is required (for example when declaring to customs)

object (metadata)

Allows the specification of arbitrary name-value pairs. note currently only the names 'extra6' and 'extra7' are supported.

extra6
string
extra7
string
object
object (orderRelation)

Represents a relationship to an order resource.

object (orderIdentification)

Identifies a resource as an order.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
self
string <uri>
object (productRelation)

Represents a relationship to a product resource.

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object
self
string <uri>
{}

orderAttachment

id
integer

The id is an internally assigned id of an orderAttachment. Only during and POST v3/orders or POST v3/orderAttachments is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderAttachment"
Value: "orderAttachment"
object
filename
required
string
contentType
required
string
Default: "application/pdf"
Value: "application/pdf"

MIME content type of a content property. This parameter is important because will define the manner in which contents are processed, note however that at the moment only one value is supported: application/pdf

printStrategy
string (orderAttachmentPrintStrategy)
Enum: "REQUIRED" "BEST_EFFORT"

Defines the strategy to employ when printing the orderAttachement. Defaults to REQUIRED.

value description
REQUIRED (default) Makes the printing of the orderAttachment a required step in the fulfilment of each shipment of the order.
BEST_EFFORT Makes the printing of the orderAttahment optional, meaning that when printing fails for what ever reasons the shipment will not be blocked.
object
object (orderRelation)

Represents a relationship to an order resource.

object (orderIdentification)

Identifies a resource as an order.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
self
string <uri>
object
self
string <uri>
{}

shipment

id
integer
type
any
Value: "shipment"
object
status
string (shipmentStatus)
Enum: "READY_TO_PICK" "READY_TO_SORT" "READY_TO_SHIP" "SHIPPED" "ERROR"

The shipmentStatus provides insight into the step in the process of fulfilling a shipment within a warehouse.

status Description
READY_TO_PICK The shipment has been fully planned and awaits the picking by an operator.
READY_TO_SORT The shipment has been picked and packed and awaits sorting for the carrier.
READY_TO_SHIP The shipment has been sorted and awaits pick-up by the carrier.
SHIPPED The shipment has been handed over to the carrier and has dispatched from the warehouse.
ERROR An issue with the shipment has occurred, for example some labelling issue. The shipments is awaiting intervention from an operator.
readyToPickOn
string <date>

Indicates the date the shipment was fully planned and ready to be picked in a warehouse of Active Ants.

readyToShipOn
string <date>

Indicates the date the shipment was fully picked and packed in a warehouse of Active Ants, awaiting dispatch.

shippedOn
string <date>

Indicates the date the shipment has shipped from the warehouse of Active Ants.

warehouseCode
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

The code for the warehouse used to uniquely refer to an Active Ants warehouse.

The following warehouses are currently defined:

code country city customs region
BW Belgium Willebroek EU - Common Customs Tariff
DD Germany Dorsten EU - Common Customs Tariff
GN Great Brittain Northampton GB - UK Global Tariff
NN The Netherlands Nieuwegein EU - Common Customs Tariff
NR The Netherlands Roosendaal EU - Common Customs Tariff
FP France Pantin EU - Common Customs Tariff
weight
integer

The (actual) weight of the shipment in grams. This weight includes the products, packing materials and inserts.

invoicingWeight
integer

The weight used to calculate the tariff for this shipment. For some carriers this deviates from the (actual) weight as these carriers apply a 'volumetric' or 'dimensional' weight which is the largest of the actual weight and the dimensional weight of the shipment.

basketPicture
string <uri>
object
carrier
string

SOON Provides insight into which carrier is providing the transport of the shipment to the deliveryAddress or pickUpPointAddress. For example FEDEX, POSTNL, BPOST, DHL, CORREOS, POSTE ITALIANE, BRING, ROYAL MAIL, and many more.

number
integer
stage
string (shipmentTrackingStage)
Enum: "LABELLED" "ACCEPTED" "SORTED" "IN_DELIVERY" "AT_PUP" "DELIVERED" "1ST_ATTEMPT"

The shipmentTrackingStage provide a generalized set of tracking well-defined stages for shipments.

The shipmentTrackingStage are generalized over all carriers. Each carrier can and has defined their own set of stages for tracking their consignments. To accommodate the main stages that are supported by most carriers the shipmentTrackingStages generalizes the carrier-specific stages. This could mean that some details of a particular carrier are not reflected by this enumeration.

stage id Description
NEW 0 The shipment is newly created and has not been assigned to a carrier yet.
LABELED 1 A label has created for the shipment.
ACCEPTED 2 The shipment has been accepted, received and scanned by the carrier.
SORTED 3 The shipment is been sorted before delivery.
IN_TRANSIT 4 The shipment is being delivered, but has not been delivered yet.
ATTEMPTED 8 or 10 An unsuccessful attempt to deliver the shipment has been made.
AVAILABLE_FOR_PICKUP 5 The shipment has been delivered to the pick up point for the recipient to collect.
DELIVERED 7 The shipment has been delivered.
RETURNED 19 The shipment has been returned to the sender after a failing be delivered.
TRACKED_EXTERNALLY 18 There is no tracking information being shared with Active Ants for this shipment.

Note the id column corresponds to the v2 endpoint values for the stage

status
string
Enum: "OK" "ERROR" "WARNING"
url
string <uri>
Array of objects
Array
number
string
parcelNumber
string

The parcel number as assigned by the carrier

trackingUrl
string <uri>

A tracking url specific to this collo

returnLabel
string
object

Repeats the metadata as specified on the order.

extra1
string
extra2
string
extra3
string
extra4
string
extra5
string
object
object (orderRelation)

Represents a relationship to an order resource.

object (orderIdentification)

Identifies a resource as an order.

id
integer

The id is an internally assigned id of an order. Only during and POST v3/orders is it possible to use arbitrary integer value which might be used to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "order"
Value: "order"
object
self
string <uri>
object (orderTypeRelation)

Represents a relationship to an orderType resource.

object (orderTypeIdentifier)

Identifies a resource as an orderType.

id
integer
type
stringorderType
Default: "orderType"
object
self
string <uri>
object (shipmentItemsRelation)

Represents a relationship to multiple shipmentItem resources.

Array of objects (shipmentItemIdentifier)
Array
id
integer
type
any
Value: "shipmentItem"
object
self
string <uri>
object (shippingMethodRelation)

Represents a relationship to a shippingMethod resource.

object (shippingMethodIdentifier)

Identifies a resource as a shippingMethod.

id
integer
type
any
Value: "shippingMethod"
object
self
string <uri>
Array of shipmentItemIdentifier (object)
Array
Any of
id
integer
type
any
Value: "shipmentItem"
object
sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

quantity
integer >= 0
lotNumber
string (lotNumber) ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

A lot number is a unique identification number assigned to a specific batch or lot of a product during the manufacturing process. It is used to track and trace the product's manufacturing and distribution history, including when and where it was produced, which raw materials were used, and to which customers it was shipped.

Lot numbers can be alphanumeric and may include information such as the date and time of production, the location of production, and the machine or equipment used. They are often printed on the product's packaging or label, as well as on associated documentation such as batch records and certificates of analysis.

expirationDate
string <date>
serialNumbers
Array of strings[ items non-empty ]
object
object (orderItemRelation)

Represents a relationship to an orderItem resource.

object (orderItemIdentification)

Identifies a resource as an orderItem.

id
integer

The id is the internally assigned id of an orderItem. Only during and POST v3/orders is it possible to use arbitrary integer values to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
required
any
Default: "orderItem"
Value: "orderItem"
object
self
string <uri>
object (productRelation)

Represents a relationship to a product resource.

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object (shipmentRelation)

Represents a relationship to a shipment resource.

object (shipmentIdentifier)

Identifies a resource as a shipment.

id
integer
type
any
Value: "shipment"
object
self
string <uri>
object
self
string <uri>
{}

stock

id
integer
type
string
object
sku
string (productSku) [ 2 .. 80 ] characters ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

SKU (stock keeping unit) of a product used to identify products.

quantity
integer > 0
locationType
string (stockLocationType)
Enum: "PALLET" "SPECIAL" "PICKABLE" "COOLED" "INBOUND" "OUTBOUND" "RETURN" "TRANSFER" "SECURED" "AUTOSTORE" "DAMAGED" "TO_SCRAP" "INSERTS"

The locationType indicates the (general) usage of the location of physical stock.

All locations have been classified to the one of the following types:

value description
AUTOSTORE An autostore location, which is a special type of PICKABLE location
PICKABLE A location from which stock can be picked, but different than AUTOSTORE
PALLET A storage location, not directly used for picking
INBOUND A temporary location used for new SKUs
RETURN A temporary location for returned SKUs
TRANSFER A temporary location used to transfer stock in or between warehouses
SECURED Special secured storage
COOLED Special cooled storage
OUTBOUND Location used in case of outbounds other than regular shipments
SPECIAL Special purpose locations
INSERTS Special purpose location for inserts (e.g. flyers)
DAMAGED Special purpose location for damaged goods that need to be shipped to a refurbishment party
TO_SCRAP Special purpose location for scrapped goods that remain in the warehouse until a destruction order is received.
locationCode
string (stockLocationCode)

The stockLocationCode defines a location uniquely within a warehouse. This means that the code may appear in other warehouses as well with the exception of the locations of type TRANSFER which operate between warehouses.

quality
string (stockQuality)
Enum: "OK" "DAMAGED" "TO_SCRAP" "OVERDUE" "EXPIRED"

An enumerated value indicating the quality of stock.

The following qualities exists:

quality description
OK The SKU of this stock is not damaged in any form and could be sold.
DAMAGED The SKU of this stock is damaged and requires refurbishment. Typical occurs when returned items are stained or otherwise damaged.
TO_SCRAP The SKU of this stock is damaged beyond repair and can no longer be sold.
OVERDUE The SKU of this stock is past its sell-by date and may no longer be sold.
EXPIRED The SKU of this stock is expired and can no longer be sold.
status
string (stockStatus)
Enum: "OK" "NOL_CHECK" "INBOUND" "INBOUND_RECOUNT" "RECOUNT_REQUEST" "BARCODE_NOT_SCANNABLE"

An enumerated value indicating the status of stock.

The following qualities exists:

status description
OK The stock is ok and can be sold/moved or used.
NOL_CHECK A deviation in quantity has been detected and the stock must be recounted before it can be used.
INBOUND The stock is involved in an inbound which is not complete yet.
INBOUND_RECOUNT The stock is involved in an inbound and a difference between the inboundPackingSlip and the inbound causes the stock to be recounted.
RECOUNT_REQUESTED The stock is to be recounted on request.
BARCODE_NOT_SCANNABLE The stock could not be picked due to barcode issues and must be investigated.
expirationDate
string <date>

When the products at this locatoin have the same expiration date then this is reflected by this field. As a rule, products with different expiration dates cannot be kept in the same location.

expirationStatus
string (expirationStatus)
Enum: "OK" "WARNING" "OVERDUE" "EXPIRED"

The expirationStatus shows if the expirationDate of the stock is within certain limits or has expired. The following statuses exists:

status description
OK The stock is well before the sell-by date or does not expire.
WARNING The stock is within the margin before it reaches the sell-by date, but has not crossed the sell-by date. The margin for this warning is set by the field expirationDateWarning on the product.
OVERDUE The stock has technically not expired, but can no longer be sold to consumers. It is now excluded from being shipped. The margin for this date is set by the field expirationDateMargin on the product.
EXPIRED The stock has actually expired, i.e. the expirationDate of this stock lies in the past.
lotNumber
string (lotNumber) ^[\x21-\x7E][\x20-\x7E]*[\x21-\x7E]$

Specifies the lot number of the SKU at this location. This value is only provided if all items at this location share the same lot number. It is not possible to keep sku having different lot numbers at the same location.

quarantined
boolean
Default: false

Indicates that this particular stock is in quarantine. Stock that i placed in quarantine is excluded from many regular processes to prevent it from being shipped.

modifiedOn
string <date-time>
receivedOn
string <date>

Specifies when the items in this stock were first received.

object
object (stockLocationRelation)

Represents a relationship to a stockLocation resource.

object (stockLocationIdentifier)

Identifies a resource as stockLocation.

id
integer
type
any
Default: "stockLocation"
Value: "stockLocation"
object (productRelation)

Represents a relationship to a product resource.

object (productIdentifier)

Identifies a resource as a product.

id
integer

The id is an internally assigned id of a product. It is possible to assign an arbitrary value in a POST request to cross-reference within the message itself. However the system will not honour any value assigned by external systems.

type
any
Default: "product"
Value: "product"
object
self
string <uri>
object (inboundItemRelation)

Points to the last inboundItem resource that increased the quantity of this stock.

object (inboundItemIdentification)

Identifies a resource as an inboundItem.

id
integer
type
any
Value: "inboundItem"
object
self
string <uri>
Array of stockLocationIdentifier (object)
Array
Any of
id
integer
type
any
Default: "stockLocation"
Value: "stockLocation"
object
warehouseCode
string (warehouseCode)
Enum: "NR" "NN" "GN" "BW" "DD" "FP"

The code for the warehouse used to uniquely refer to an Active Ants warehouse.

The following warehouses are currently defined:

code country city customs region
BW Belgium Willebroek EU - Common Customs Tariff
DD Germany Dorsten EU - Common Customs Tariff
GN Great Brittain Northampton GB - UK Global Tariff
NN The Netherlands Nieuwegein EU - Common Customs Tariff
NR The Netherlands Roosendaal EU - Common Customs Tariff
FP France Pantin EU - Common Customs Tariff
locationType
string (stockLocationType)
Enum: "PALLET" "SPECIAL" "PICKABLE" "COOLED" "INBOUND" "OUTBOUND" "RETURN" "TRANSFER" "SECURED" "AUTOSTORE" "DAMAGED" "TO_SCRAP" "INSERTS"

The locationType indicates the (general) usage of the location of physical stock.

All locations have been classified to the one of the following types:

value description
AUTOSTORE An autostore location, which is a special type of PICKABLE location
PICKABLE A location from which stock can be picked, but different than AUTOSTORE
PALLET A storage location, not directly used for picking
INBOUND A temporary location used for new SKUs
RETURN A temporary location for returned SKUs
TRANSFER A temporary location used to transfer stock in or between warehouses
SECURED Special secured storage
COOLED Special cooled storage
OUTBOUND Location used in case of outbounds other than regular shipments
SPECIAL Special purpose locations
INSERTS Special purpose location for inserts (e.g. flyers)
DAMAGED Special purpose location for damaged goods that need to be shipped to a refurbishment party
TO_SCRAP Special purpose location for scrapped goods that remain in the warehouse until a destruction order is received.
locationCode
string (stockLocationCode)

The stockLocationCode defines a location uniquely within a warehouse. This means that the code may appear in other warehouses as well with the exception of the locations of type TRANSFER which operate between warehouses.

object
self
string
{
  • "id": 654322,
  • "type": "stock",
  • "attributes": {
    },
  • "relationships": {},
  • "included": [
    ],
  • "links": {}
}