Skip to main content
API docs by Redocly

ShopApi - v2 (2.0)

Download OpenAPI specification:Download

IT Support: itsupport@activeants.com URL: https://www.activeants.com/ License: © Active Ants 2023 Terms of Service

Active Ants ShopApi v2

Welcome to the specifications of the Active Ants ShopApi v2. 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.

Note that this API is superceded by the **ShopApi v3** endpoints which will increasingly take over functionality available in this endpoint.

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

Provide the provided username

password
required
string

Prodide your password

Responses

Response Schema: application/json
access_token
string

The actual token to use when making API requests.

token_type
string
Default: "bearer"

A constant indicating the type of the token, provided for reference

expires_in
number <integer>

the number of seconds until the token expires and the user is required to request another

userName
string

The user name echoed back from the request

issued
string

Date the token was issued in RFC1123 format

expires
string

Date the token will expire in RFC1123 format

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
}

settings/get

GET settings/get

When making API calls you will often are required to provide the correct id's when refering to configuration entities such as orderTypes. These id's can be obtained by using the shopapi/v2 GET settings/get method. It is recommended to cache this data locally and refresh daily. Among these settings the id's and names of the following entities are returned

entity description
mainShippingMethods (required for the shopapi/v3)
shippingMethods (deprecated, but still required for shopapi/v2 endpoints)
orderTypes
returnReasons
returnShippingMethods
languages
countries
paymentMethods (obsolete)
Authorizations:
Bearer

Responses

Response Schema: application/json
messageCode
required
string
Enum: "OK" "NOK"
  • OK All went well
  • NOK An error occurred. The message element indicates the issue.
message
required
string

For example status is OK or return label found.

object or null

An object containing the various settings applicable to the client.

Array of objects

Provides a list of the shipping methods available for use through the shopapi/v3 endpoints. The id field of the mainShippingMethod must be used when providing a preferredShippingMethod or can be used as reference when shippingMethods id's are being returned.

Warning

The shopapi/v3 uses different shipping method id's than the shopapi/v2 although both are related there is a significant difference. shopapi/v3 endpoints use the mainShippingMethod id's while the shopapi/v2 endpoints use the shippingMethod id's.

Array
id
integer

The unique identifier for this shippingMethod

name
string

Human readable name for the shippingMethod

code
string

Administrative code for the shippingMethod

Array of objects

An array of warehouse specific shippingMethods

Array
id
integer
warehouse
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
Array of objects

Provides a list of the shipping methods available for use through the shopapi/v2 endpoints.

Warning

The shopapi/v3 uses different shipping method id's than the shopapi/v2 although both are related there is a significant difference. shopapi/v3 endpoints use the mainShippingMethod id's while the shopapi/v2 endpoints use the shippingMethod id's.

Array
id
integer

The id of the shippingMethod (for use with shopapi/v2 endpoints)

name
string

A human readable name for the shipping method

code
string

A code for the shipping method

Array of objects

Provides a list of the available returnShippingMethods.

Array
id
integer

The id of the shippingMethod (for use with shopapi/v2 endpoints)

name
string

A human readable name for the returnShippingMethod

code
string

A code for the returnShippingMethod

Array of objects

Provides a list of all the orderTypes that have been configured for your fulfillment-process. The orderType drives an important part of how orders are being handled and what rules are to be applied on these orders. To understand the prossibilities please contact your acount manager for further information on orderTypes.

Array
id
integer

The unique id of the orderType one of which must be used when submitting an order.

name
string

A human-readable name of the orderType. Note that this is just a name and does not entice behaviour, meaning that an orderType named 'B2B' does not 'magically' implement B2B processes, these have to be configured by your Account Manager.

code
string

Repetition of the name.

Array of objects

An array of all countries and their iso3166-code. Note that some countries are divided into sub-territories such as ES-CE. These countries often require specific customs or tax-regulations to be adhered to.

Array
id
integer

Internally assigned id for the country. Usually this is not needed, but the older shopapi/v2 endpoints require this id to identify a country.

name
string

Name of the country, always in English with the sole exception of The Netherlands

code
string

The iso3166 alpha-2 code associated with this country, or in case of a sub-territory a longer iso3166 code. For more information see ISO-3166:ORG

Array of objects

An array of languages supported by the system. Note that this set is limited to 11 languages.

Array
id
integer

Internally assigned id for the language.

name
string

Name of the language in Dutch.

code
string

Uppercase language code based on the ISO-639 language code (set 1)

Array of objects

Set of reasons used for returned items.

Array
id
integer

Unique id for the reason

name
string

Full name / short description for the reason

code
string

Unique code for the description.

Array of objects
Deprecated

Payment methods are no longer in use.

Array
id
integer
Deprecated

Payment methods are no longer in use.

name
string
Deprecated

Payment methods are no longer in use.

code
string
Deprecated

Payment methods are no longer in use.

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "Settings are ok.",
  • "result": {
    }
}

Orders

order/release

POST order/release

Releases an order which was created with onHold=true.

Authorizations:
Bearer
Request Body schema: application/json
externalOrderNumber
string

Responses

Response Schema: application/json
messageCode
required
string

The value OK indicates the message was accepted by the system.

Value: "OK"
message
required
string

Some response indicating the success

object or string or integer or null
One of
object

Request samples

Content type
application/json
{
  • "externalOrderNumber": "string"
}

Response samples

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

order/add Deprecated

POST order/add

This operation is deprecated, users are encouraged to migrate to the new POST v3/orders end-point instead.
This operation will add new orders to the database. Important to note is that when the Billing Address fields are left empty, all the data in Delivery Address will be used for both Delivery and Billing.
Authorizations:
Bearer
Request Body schema: application/json
externalOrderNumber
required
string

The order number of external system (e.g. Magento)

extraReference
string

Can be used to store an extra reference.

actionCode
string

Can be used to store information about a promotional action in an order.

preferredShippingDate
string <date-time>

When this date is set, the order will not be shipped before this date.

partialDelivery
boolean

When set to false the order will only ship when all products are in stock. When set to true, orders will ship in parts when products become available.

onHold
boolean

When set to true, order gets status 'on hold'. Use the end-point POST order/release to release the order.

email
string

The customer's email.

phoneNumber
string

The customer's phone number.

currency
string
Default: "EUR"

The currency of the order (ISO-3 code, like EUR, USD) EUR is assumed when empty.

bankAccountNumber
string
Deprecated

The customer's IBAN.

bankAccountHolderName
string
Deprecated

The account holder's name.

bankAccountCityName
string
Deprecated

The account holder's city.

paymentMethodId
required
integer

The id of the payment method. Since we do not handle payments ourselves anymore, this should always have value 1 (deprecated)

Value: 1
shippingMethodId
integer

The id of the shipping method. All available shipping methods and the corresponding id's can be found with the GET settings/get operation of the API. When filled in, this will overwrite the default shipping method. So unless your customer uses a shipping method other than the default, this field should be empty.

deliveryAddressFirstName
string

The name of the person of the delivery address.

deliveryAddressInsertion
string

The insertion between first and last name of the delivery address.

deliveryAddressLastName
required
string

The last name of the person of the delivery address.

deliveryAddressExtraName
string

The extra name of the person of the delivery address (e.g. the company name)

deliveryAddressPostalCode
required
string

The postal code of the delivery address. This field is required when shipping within The Netherlands, Germany or Belgium (and most other countries).

deliveryAddressHouseNumber
required
integer

The house number of the delivery address. This field is required when shipping within The Netherlands, Belgium or Germany. If there is no housenumber in there, Maya will try to retrieve it from DeliveryAddressStreet. If DeliveryAddressStreet does not contain a housenumber for these countries mentioned, the order will be marked as Not Valid, and won't be shipped, until a housenumber is added.

deliveryAddressHouseNumberAddition
string

The house number addition of the delivery address.

deliveryAddressStreet
required
string

The streetname of the delivery address

DeliveryAddressCityName
string

The cityname of the delivery address

deliveryAddressRegion
string

The region this address is in. Preferably ISO 2 character code. (ISO 3166-2)

deliveryAddressCountryIso
required
string

The ISO 2 character countrycode (ISO 3166) of the delivery address. All available countries and country codes can be found with the GET settings/get operation of the API.

deliveryAddressExtraAddress
string

Used to store extra information for the delivery address.

billingAddressFirstName
string

The name of the person of the billing address

billingAddressInsertion
string

The insertion between first and last name of the billing address.

billingAddressLastName
string

The last name of the person of the billing address.

billingAddressExtraName
string

The extra name of the person of the billing address (e.g. the company name)

billingAddressPostalCode
string

The postal code of the billing address

billingAddressHouseNumber
integer

The house number of the billing address

billingAddressHouseNumberAddition
string

The house number addition of the billing address

billingAddressStreet
string

The street name of the billing address

billingAddressCityName
string

The city name of the billing address

billingAddressRegion
string

The region this billing address is in. Preferably ISO 2 character code. (ISO 3166-2)

billingAddressCountryIso
string

The ISO 2 character country code (ISO 3166) of the billing address. All available countries and country codes can be found with the GET settings/get operation of the API.

billingAddressExtraAddress
string

Used to store extra information for the billing address.

extra1
string

Can be used to store extra information

extra2
string

Can be used to store extra information

extra3
string

Can be used to store extra information

extra4
string

Can be used to store extra information

extra5
string

Can be used to store extra information

vatNumber
string

BTW (VAT) Number

clientReference
string

Extra reference space for the client.

languageId
required
integer

The id of the Language Code. All available language codes and the corresponding id's can be found with the GET settings/get operation of the API.

orderTypeId
required
integer

Defines the type of Order. All available Order Types can be retrieved using the GET settings/get operation of the Api.

pickUpPointId
string

Pickup spot Service point (f.e. PostNL-Pakje Gemak, DHL - Service point, BPost afhaalpunt, UPS access point) Important to note is the following: The following fields need to be filled appropriately if you want the pickup point shipments to be processed properly! Please ensure that the pickup point address is valid and complete!

pickUpPointName
string

Pickup spot name (usually printed on label)

pickUpPointStreet
string

Pickup spot street name

pickUpPointHouseNumber
integer

The house number of the pickup spot

pickUpPointHouseNumberAddition
string

The house number extension of the pickup spot

pickUpPointPostalCode
string

The Zip code of the pickup spot

pickUpPointCityName
string

City name of the Pickup spot

pickUpPointCountryIso
string

The ISO 2 character country code (ISO 3166) of the pickup spot address. All available countries and country codes can be found with the GET settings/get operation of the API.

pickUpPointRegion
string

The region this billing address is in. Preferably ISO 2 character code. (ISO 3166-2)

pickUpPointExtraAddress
string

Used to store extra information for the pickup spot address.

warehouseId
integer

WarehouseId of the warehouse of the order. If a value is given and not known within Maya, the order will fail.

required
Array of objects
Array
sku
required
string

The product SKU for this order item.

quantity
required
integer

Total number of products in this order item.

name
string

Name of the product.

price
required
number

Price per product.

vat
number

VAT Percentage.

extra6
string

Can be used to store extra information.

extra7
string

Can be used to store extra information.

warehouseId
integer

WarehouseId of the warehouse of the orderitem. If a value is given and not known within Maya, the order will fail

Responses

Response Schema: application/json
messageCode
required
string

The value OK indicates the message was accepted by the system.

Value: "OK"
message
required
string

Some response indicating the success

object or string or integer or null
One of
object

Request samples

Content type
application/json
{
  • "externalOrderNumber": "string",
  • "extraReference": "string",
  • "actionCode": "string",
  • "preferredShippingDate": "2019-08-24T14:15:22Z",
  • "partialDelivery": true,
  • "onHold": true,
  • "email": "string",
  • "phoneNumber": "string",
  • "currency": "EUR",
  • "bankAccountNumber": "string",
  • "bankAccountHolderName": "string",
  • "bankAccountCityName": "string",
  • "paymentMethodId": 1,
  • "shippingMethodId": 0,
  • "deliveryAddressFirstName": "string",
  • "deliveryAddressInsertion": "string",
  • "deliveryAddressLastName": "string",
  • "deliveryAddressExtraName": "string",
  • "deliveryAddressPostalCode": "string",
  • "deliveryAddressHouseNumber": 0,
  • "deliveryAddressHouseNumberAddition": "string",
  • "deliveryAddressStreet": "string",
  • "DeliveryAddressCityName": "string",
  • "deliveryAddressRegion": "string",
  • "deliveryAddressCountryIso": "string",
  • "deliveryAddressExtraAddress": "string",
  • "billingAddressFirstName": "string",
  • "billingAddressInsertion": "string",
  • "billingAddressLastName": "string",
  • "billingAddressExtraName": "string",
  • "billingAddressPostalCode": "string",
  • "billingAddressHouseNumber": 0,
  • "billingAddressHouseNumberAddition": "string",
  • "billingAddressStreet": "string",
  • "billingAddressCityName": "string",
  • "billingAddressRegion": "string",
  • "billingAddressCountryIso": "string",
  • "billingAddressExtraAddress": "string",
  • "extra1": "string",
  • "extra2": "string",
  • "extra3": "string",
  • "extra4": "string",
  • "extra5": "string",
  • "vatNumber": "string",
  • "clientReference": "string",
  • "languageId": 0,
  • "orderTypeId": 0,
  • "pickUpPointId": "string",
  • "pickUpPointName": "string",
  • "pickUpPointStreet": "string",
  • "pickUpPointHouseNumber": 0,
  • "pickUpPointHouseNumberAddition": "string",
  • "pickUpPointPostalCode": "string",
  • "pickUpPointCityName": "string",
  • "pickUpPointCountryIso": "string",
  • "pickUpPointRegion": "string",
  • "pickUpPointExtraAddress": "string",
  • "warehouseId": 0,
  • "orderItems": [
    ]
}

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "Order has been successfully added.",
  • "result": 470345326
}

Shipments

v2/shipment/tracktracestatus

GET v2/shipment/tracktracestatus

Returns current tracking data of shipments that are in trackable delivery. Trackable delivery means the shipment is tracked by a carrier from which we receive tracking information and hasn’t been delivered* yet. (*Delivered is meant in the broad sense of the word: arrived at a pick-up point, returned to sender, delivered at addressee.)

PLEASE NOTE : We rely on external companies for this data (like the carriers). This endpoint is only to be used as extra additional information about the shipments, we cannot guarantee each and every shipment will have (correct) tracking data! Also not all carriers have tracking available

This endpoint should be consumed sparingly. It’s strongly advised to limit the use to once per hour. If violated we cannot guarantee responsiveness of our services.

CurrentTrackTraceStatus codes:

  • 1 - Labeled
  • 2 - Accepted by carrier
  • 3 - Sorted
  • 4 - In delivery
  • 5 - At pickup point
  • 7 - Delivered
  • 8 - Delivery started
  • 10 - Delivery started (1st attempt)
  • 18 - Tracked Externally
  • 19 - Returned (at warehouse)
  • 20 - At customs (only for shipments that have to go through customs)
  • 21 - In transit (only for shipments that have to go through customs)

CurrentTrackTraceExceptionLevel Codes:

  • 1 - ok
  • 2 - warning
  • 3 - error
Authorizations:
Bearer

Responses

Response Schema: application/json
messageCode
string
message
string
Array of objects
Array
shipmentId
integer

Id of the Shipment

externalOrderNumber
string

The external Order number this shipment belongs to

packageNumber
string

Parcelnumber with the carrier

shipmentMethod
string

Name of the shipping method

currentTrackTraceStatus
integer

Available tracking status at time of shipment search request as described

currentTrackTraceStatusDateTime
string <date-time>

Time of occurrence of the tracking status. Nullable in case of old entries.

currentTrackTraceExceptionLevel
integer

Available exception status if available as described.

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "Found track trace status data",
  • "result": [
    ]
}

v2/shipment/get Deprecated

GET v2/shipment/get

This operation is deprecated, users are encouraged to migrate to the new GET v3/shipments end-point instead.
Only the shipments that are marked as 'needs to be synced' will be processed. Per request a max. of 100 shipments are returned. When processed the shipments is finished they should be marked as 'synced' with the UpdateSyncedShipments operation.
Authorizations:
Bearer

Responses

Response Schema: application/json
messageCode
string
Value: "OK"
message
string
Array of objects
Array
id
integer

Id of the shipment

orderNumber
integer

Id of the order this shipment belongs to

orderType
integer

Id of the order type this shipment belongs to

externalOrderNumber
string

The external order number this shipment belongs to

shippingDate
string

The date this shipment is going to be/has been sent off on

numberOfColli
integer

Number of packages for this shipment

totalNumberOfProducts
integer

Total amount of products being shipped in this shipment

shippingMethodId
integer

Id of the shipping method

returnPackageNumber
string or null

The number of the return label

Array of objects
Array
colloNr
string

Number of the collo

packageNumber
string

Parcelnumber with the carrier

trackTraceUrl
string

Track & trace url

Array of objects
Array
sku
string

The product SKU

quantity
integer

Quantity shipped of this product

serialNrs
Array of strings

A list of serial numbers, if this is relevant for this product

weight
number

Product Weight, 0 if unknown

tht
string or null <date-time>

Best Before Date, if product has one

extra6
string or null
extra7
string or null
lotNumber
string or null
Array of objects
Array
sku
string

The product SKU

quantity
integer

Quantity shipped of this product

serialNrs
Array of strings

A list of serial numbers, if this is relevant for this product

weight
number

Product Weight, 0 if unknown

tht
string <date-time>

Best Before Date, if product has one

extra6
string
extra7
string
lotNumber
string
basketPicURL
string

Contains an URL pointing to the basketpic.

extra1
string or null
extra2
string or null
extra3
string or null
extra4
string or null
extra5
string or null
currentTrackTraceStatus
string

Available trackingstatus at time of shipment search request

currentTrackTraceExceptionLevel
string or null

Available exception status if available

warehouseAbbrevation
string

Showed Warehouse Abbreviation

mainShippingMethodId
integer

Showed MainShipingMethodId from core shipping methods

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "Found 100 shipments that match your criteria.",
  • "result": [
    ]
}

v2/shipment/byordertype Deprecated

POST v2/shipment/byordertype

This operation is deprecated, users are encouraged to migrate to the new GET v3/shipments?filter[orderType][in]=5,6,7 end-point instead.
Only the shipments that are marked as 'needs to be synced' will be processed. Per request a max. of 100 shipments are returned. When processed the shipments is finished they should be marked as 'synced' with the UpdateSyncedShipments operation.
Authorizations:
Bearer
Request Body schema: application/json
orderTypes
Array of integers

Used to indicate a subset of shipments to sync by order type. This allows you to only retrieve & sync shipments for specific order types.

Responses

Response Schema: application/json
messageCode
string
Value: "OK"
message
string
Array of objects
Array
id
integer

Id of the shipment

orderNumber
integer

Id of the order this shipment belongs to

orderType
integer

Id of the order type this shipment belongs to

externalOrderNumber
string

The external order number this shipment belongs to

shippingDate
string

The date this shipment is going to be/has been sent off on

numberOfColli
integer

Number of packages for this shipment

totalNumberOfProducts
integer

Total amount of products being shipped in this shipment

shippingMethodId
integer

Id of the shipping method

returnPackageNumber
string or null

The number of the return label

Array of objects
Array
colloNr
string

Number of the collo

packageNumber
string

Parcelnumber with the carrier

trackTraceUrl
string

Track & trace url

Array of objects
Array
sku
string

The product SKU

quantity
integer

Quantity shipped of this product

serialNrs
Array of strings

A list of serial numbers, if this is relevant for this product

weight
number

Product Weight, 0 if unknown

tht
string or null <date-time>

Best Before Date, if product has one

extra6
string or null
extra7
string or null
lotNumber
string or null
Array of objects
Array
sku
string

The product SKU

quantity
integer

Quantity shipped of this product

serialNrs
Array of strings

A list of serial numbers, if this is relevant for this product

weight
number

Product Weight, 0 if unknown

tht
string <date-time>

Best Before Date, if product has one

extra6
string or null
extra7
string or null
lotNumber
string or null
basketPicURL
string

Contains an URL pointing to the basketpic.

extra1
string or null
extra2
string or null
extra3
string or null
extra4
string or null
extra5
string or null
currentTrackTraceStatus
string

Available trackingstatus at time of shipment search request

currentTrackTraceExceptionLevel
string or null

Available exception status if available

warehouseAbbrevation
string

Showed Warehouse Abbreviation

mainShippingMethodId
integer

Showed MainShipingMethodId from core shipping methods

Request samples

Content type
application/json
{
  • "orderTypes": [
    ]
}

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "Found 100 shipments that match your criteria.",
  • "result": [
    ]
}

v2/shipment/byordertype/labeled Deprecated

POST v2/shipment/byordertype/labeled

This operation is deprecated, users are encouraged to migrate to the new GET v3/shipments?filter[orderType][in]=5,6,7&filter[status][in]=SOME_STATUS end-point instead.
Only the shipments that are marked as 'needs to be synced' will be processed. Per request a max. of 100 shipments are returned. When processed the shipments is finished they should be marked as 'synced' with the UpdateSyncedShipments operation.
Authorizations:
Bearer
Request Body schema: application/json
orderTypes
Array of integers

Used to indicate a subset of shipments to sync by order type. This allows you to only retrieve & sync shipments for specific order types.

Responses

Response Schema: application/json
messageCode
string
Value: "OK"
message
string
Array of objects
Array
id
integer

Id of the shipment

orderNumber
integer

Id of the order this shipment belongs to

orderType
integer

Id of the order type this shipment belongs to

externalOrderNumber
string

The external order number this shipment belongs to

shippingDate
string

The date this shipment is going to be/has been sent off on

numberOfColli
integer

Number of packages for this shipment

totalNumberOfProducts
integer

Total amount of products being shipped in this shipment

shippingMethodId
integer

Id of the shipping method

returnPackageNumber
string or null

The number of the return label

Array of objects
Array
colloNr
string

Number of the collo

packageNumber
string

Parcelnumber with the carrier

trackTraceUrl
string

Track & trace url

Array of objects
Array
sku
string

The product SKU

quantity
integer

Quantity shipped of this product

serialNrs
Array of strings

A list of serial numbers, if this is relevant for this product

weight
number

Product Weight, 0 if unknown

tht
string or null <date-time>

Best Before Date, if product has one

extra6
string or null
extra7
string or null
lotNumber
string or null
Array of objects
Array
sku
string

The product SKU

quantity
integer

Quantity shipped of this product

serialNrs
Array of strings

A list of serial numbers, if this is relevant for this product

weight
number

Product Weight, 0 if unknown

tht
string <date-time>

Best Before Date, if product has one

extra6
string
extra7
string
lotNumber
string
basketPicURL
string

Contains an URL pointing to the basketpic.

extra1
string
extra2
string
extra3
string
extra4
string
extra5
string
currentTrackTraceStatus
string

Available trackingstatus at time of shipment search request

currentTrackTraceExceptionLevel
string

Available exception status if available

warehouseAbbrevation
string

Showed Warehouse Abbreviation

mainShippingMethodId
integer

Showed MainShipingMethodId from core shipping methods

Request samples

Content type
application/json
{
  • "orderTypes": [
    ]
}

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "Found 100 shipments that match your criteria.",
  • "result": [
    ]
}

v2/shipment/get/labeled Deprecated

GET v2/shipment/get/labeled

This operation is deprecated, users are encouraged to migrate to the new GET v3/shipments?filter[status][in]=SOME_STATUS end-point instead.
Only the shipments that are marked as ‘have labeled state’ will be processed. When processed the shipments can be marked 'synced' with the UpdateLabeledSyncedShipments operation.
Authorizations:
Bearer

Responses

Response Schema: application/json
messageCode
string
Value: "OK"
message
string
Array of objects
Array
id
integer

Id of the shipment

orderNumber
integer

Id of the order this shipment belongs to

orderType
integer

Id of the order type this shipment belongs to

externalOrderNumber
string

The external order number this shipment belongs to

shippingDate
string

The date this shipment is going to be/has been sent off on

numberOfColli
integer

Number of packages for this shipment

totalNumberOfProducts
integer

Total amount of products being shipped in this shipment

shippingMethodId
integer

Id of the shipping method

returnPackageNumber
string

The number of the return label

Array of objects
Array
colloNr
string

Number of the collo

packageNumber
string

Parcelnumber with the carrier

trackTraceUrl
string

Track & trace url

Array of objects
Array
sku
string

The product SKU

quantity
integer

Quantity shipped of this product

serialNrs
Array of strings

A list of serial numbers, if this is relevant for this product

weight
number

Product Weight, 0 if unknown

tht
string <date-time>

Best Before Date, if product has one

extra6
string
extra7
string
lotNumber
string
Array of objects
Array
sku
string

The product SKU

quantity
integer

Quantity shipped of this product

serialNrs
Array of strings

A list of serial numbers, if this is relevant for this product

weight
number

Product Weight, 0 if unknown

tht
string <date-time>

Best Before Date, if product has one

extra6
string
extra7
string
lotNumber
string
basketPicURL
string

Contains an URL pointing to the basketpic.

extra1
string
extra2
string
extra3
string
extra4
string
extra5
string
currentTrackTraceStatus
string

Available trackingstatus at time of shipment search request

currentTrackTraceExceptionLevel
string

Available exception status if available

warehouseAbbrevation
string

Showed Warehouse Abbreviation

mainShippingMethodId
integer

Showed MainShipingMethodId from core shipping methods

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "Found 100 shipments that match your criteria.",
  • "result": [
    ]
}

v2/shipment/sync Deprecated

POST v2/shipment/sync

This operation is deprecated, users are encouraged to make use of the v3 end-points which do not require syncing.
If an invalid collection of Ids is provided, the return message will contain a list of Ids that were not found or do not belong to your company. Any Ids that were correct will NOT be processed.
Authorizations:
Bearer
Request Body schema: application/json
ids
Array of integers

Array of shipment ids

Responses

Response Schema: application/json
messageCode
required
string

The value OK indicates the message was accepted by the system.

Value: "OK"
message
required
string

Some response indicating the success

object or string or integer or null
One of
object

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "Request processed successfully.",
  • "result": null
}

v2/shipment/sync/labeled Deprecated

POST v2/shipment/sync/labeled

This operation is deprecated, users are encouraged to make use of the v3 end-points which do not require syncing.
If an invalid collection of Ids is provided, the return message will contain a list of Ids that were not found or do not belong to your company. Any Ids that were correct will NOT be processed.
Authorizations:
Bearer
Request Body schema: application/json
ids
Array of integers

Array of shipment ids

Responses

Response Schema: application/json
messageCode
required
string

The value OK indicates the message was accepted by the system.

Value: "OK"
message
required
string

Some response indicating the success

object or string or integer or null
One of
object

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "Request processed successfully.",
  • "result": null
}

RMA

v2/rma/add

POST v2/rma/add

Authorizations:
Bearer
Request Body schema: application/json
shipmentId
required
integer

The ID of the Shipment

remark
string

Optional remark.

externalReference
string

Optional: external reference that can be used freely by the API user

object
shipmentItemId
required
integer

The id of the shipmentItem

quantity
required
integer

Total number of products in the shipment item order

returnReasonId
required
integer

Id of the return reason.

externalReference
string

Optional external reference that can be used freely by the API user.

object

Optional list of key/value pairs that can be used freely by the API user.

property name*
additional property
string

Responses

Response Schema: application/x-www-form-urlencoded
messageCode
string
message
string
result
integer

Request samples

Content type
application/json
{
  • "shipmentId": 0,
  • "remark": "string",
  • "externalReference": "string",
  • "rmaItems": {
    }
}

Response samples

Content type
application/x-www-form-urlencoded
messageCode=OK&message=RMA%20created.&result=133

Returns

The "Returns" section of the API documentation provides a set of endpoints that are related to the returns processes

v2/returnlabel/get/:id

GET v2/returnlabel/get/:shipmentId

This endpoint returns a return-label for a shipment resource. The request requires a path parameter which is the id of the shipment to fetch the return label for. It returns only a label if the shipment can be be found and the return-label could be created successfully.

Paperless Returns

Return labels for specific (return)shipping methods

Authorizations:
Bearer
path Parameters
shipmentId
required
integer

Id of the shipment as issued by Active Ants.

Responses

Response Schema: application/json
messageCode
required
string
Enum: "OK" "NOK"
  • OK All went well
  • NOK An error occurred. The message element indicates the issue.
message
required
string

For example status is OK or return label found.

object or null
data
string
mimeType
string
fileName
string
shipmentItemId
string
packageNumber
string
isPaperlessReturnShippingMethod
boolean

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "Return label found.",
  • "result": {
    }
}

v2/returnlabel/get/:id/:id

GET v2/returnlabel/get/:shipmentId/:shippingMethodId

This endpoint returns a return-label for a shipment resource. The request requires a path parameter which is the id of the shipment to fetch the return label for and also the id of the shipping method to be used for the return in the path parameter sm. It returns only a label if the shipment can be be found and the return-label could be created successfully.

Paperless Returns

Return labels for any (return)shipping method

See GET v2/returnlabel/get/:id.

Authorizations:
Bearer
path Parameters
shipmentId
required
integer

Id of the shipment as issued by Active Ants.

shippingMethodId
required
integer

Id of the shipping method as issued by Active Ants.

Responses

Response Schema: application/json
messageCode
required
string
Enum: "OK" "NOK"
  • OK All went well
  • NOK An error occurred. The message element indicates the issue.
message
required
string

For example status is OK or return label found.

object or null
data
string
mimeType
string
fileName
string
shipmentItemId
string
packageNumber
string
isPaperlessReturnShippingMethod
boolean

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "Return label found.",
  • "result": {
    }
}

v2/returnitem/get Deprecated

POST v2/returnitem/get

This operation is deprecated, users are encouraged to migrate to the new POST v3/returnItems end-point instead.
The request must be done by either posting an external ordernumber or a time path. The response will have a maximum of 1000 returnitems per post.
Authorizations:
Bearer
Request Body schema: application/x-www-form-urlencoded
ExternalOrderNumber
integer

Optional, to get data from a specific external ordernumber

Starttime
string <date-time>

Optional, date time returnitems from

Endtime
string <date-time>

Optional, date time returnitems to

Responses

Response Schema: application/x-www-form-urlencoded
messageCode
string
message
string
Array of objects
Array
id
integer
returnDate
string

Date time of the returned item

externalOrderNumber
string

The external order number this returnitem belongs to

sku
string

The product SKU

quantity
integer

Quantity shipped of this product

type
string

Defines the condition

returnReasonId
integer

The ID of the ReturnReason

returnReason
string

Description of the Return Reason

comment
string

Comment related to the returnitem

afterCare
string
porti
null

Description of the used Porti

returnShippingMethod
string

Description of the used return shipping method

returnShippingMethodId
integer
reDeliver
boolean

Default false

orderType
string

Ordertype of the ExternalOrderNumber

warehouseAbbreviation
string
processedByWarehouseAbbreviation
string
rma
null

ExternalReference (String): reference of the Rma that was supplied when the Rma was added.

rmaItem
null

ExternalReference (String): reference of the RmaItem that was supplied when the Rma was added. Metadata (JSON object): metadata of the RmaItem that was supplied when the Rma was added.

Response samples

Content type
application/x-www-form-urlencoded
messageCode=OK&message=Found%201%20return%20items%20that%20match%20your%20criteria.&result=%5Bobject%20Object%5D

Products

WARNING!

All of the product related endpoints in the v2 specification have been deprecated and replaced by the new v3/products endpoints. At any point these legacy end points may be terminated. Please upgrade your implementation as soon as possible. For documentaiton on the new end-points go the the v3/products section of our new API specification

product/add Deprecated

POST product/add

This operation is deprecated, users are encouraged to migrate to the new POST v3/products end-point instead.
This operation will insert a new product into the Maya database.
Authorizations:
Bearer
Request Body schema: application/json
sku
required
string

The product's SKU. Should be a unique value in the database.

name
required
string

The product name

barcode
string

The product barcode.

description
string

The product description.

harmonisationCode
string

HS-code to be used for customs.

countryOfOriginIso
string

Alpha-2 ISO code of the Country of Origin.

encodedImage
string

Base64 string of the product image. Max file size is 100Kb.

costPrice
number

The product's purchasing price.

supplierCode
string

Company code belonging to the supplier company (must be the same as configured in MaYa)

supplierProductCode
string

Product code used by the Supplier of this product

stockMinimum
integer

Used to define a minimum stock

stockMaximum
integer

Used to define a maximum stock

priceA
string

Product sale price (used in reports)

priceB
string

Product sale price (used in reports)

priceC
string

Product sale price (used in reports)

priceD
string

Product sale price (used in reports)

vatLevel
string
Deprecated

0 = No VAT, 1 = Low VAT, 2 = High VAT

orderQuantity
string

The quantity used in the order reports.

extra1
string

Additional product info

extra2
string

Additional product info

extra3
string

Additional product info

extra4
string

Additional product info

extra5
string

Additional product info

hasThtDate
boolean

Product has an expiration date if true

warningDaysTillThtDate
integer

Number of days for warning of THT

maxDaysTillThtDate
integer

Max number of days of THT

hasLotNumber
boolean

Product has a lot number if true

hasSerial
boolean

Product has a serial number if true

useEconomicStock
boolean

Use economic stock for product if true

Responses

Response Schema: application/json
messageCode
string
message
string
result
integer

Request samples

Content type
application/json
{
  • "sku": "string",
  • "name": "string",
  • "barcode": "string",
  • "description": "string",
  • "harmonisationCode": "string",
  • "countryOfOriginIso": "string",
  • "encodedImage": "string",
  • "costPrice": 0,
  • "supplierCode": "Sup001",
  • "supplierProductCode": "string",
  • "stockMinimum": 0,
  • "stockMaximum": 0,
  • "priceA": "string",
  • "priceB": "string",
  • "priceC": "string",
  • "priceD": "string",
  • "vatLevel": "string",
  • "orderQuantity": "string",
  • "extra1": "string",
  • "extra2": "string",
  • "extra3": "string",
  • "extra4": "string",
  • "extra5": "string",
  • "hasThtDate": true,
  • "warningDaysTillThtDate": 0,
  • "maxDaysTillThtDate": 0,
  • "hasLotNumber": true,
  • "hasSerial": true,
  • "useEconomicStock": true
}

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "Product has been successfully added",
  • "result": 1326169
}

product/edit Deprecated

POST product/edit

This operation is deprecated, users are encouraged to migrate to the new PUT v3/products/:id end-point instead.
This operation will update a product.
Authorizations:
Bearer
Request Body schema: application/json
sku
required
string

The Product SKU.

CostPrice
string

Purchasing cost of the product.

Description
string

The product description. Truncated after 200 characters

HarmonisationCode
string

HS-code to be used for customs.

CountryOfOriginIso
string

Alpha-2 ISO code of the Country of Origin.

EncodedImage
string

A Base64 encoded image. Max file size is 100Kb.

Name
string

The product name. Cannot be empty

Barcode
string

The product barcode. Can only be changed as long as the product is not in stock!

StockMinimum
integer

Used to define a minimum stock

StockMaximum
integer

Used to define a maximum stock

PriceA
number

Product sale price (used in reports)

PriceB
number

Product sale price (used in reports)

PriceC
number

Product sale price (used in reports)

PriceD
number

Product sale price (used in reports)

VatLevel
integer
Deprecated

0 = No VAT, 1 = Low VAT, 2 = High VAT

OrderQuantity
integer

The quantity used in the order reports.

Extra1
string

Additional product info

Extra2
string

Additional product info

Extra3
string

Additional product info

Extra4
string

Additional product info

Extra5
string

Additional product info

HasThtDate
boolean

Set to true if the product has an expiration date to keep track of

WarningDaysTillThtDate
integer

Number of days before the expiration date to warning of iminent expiration

MaxDaysTillThtDate
integer

Number of days before the expiration date the product can be sold at

HasLotNumber
boolean

Product has a lot number if true

HasSerial
boolean

Product has a serial number if true

UseEconomicStock
boolean

Use economic stock for product if true

Responses

Response Schema: application/json
messageCode
string
message
string
result

Request samples

Content type
application/json
{
  • "sku": "string",
  • "name": "string",
  • "barcode": "string",
  • "description": "string",
  • "harmonisationCode": "string",
  • "countryOfOriginIso": "string",
  • "encodedImage": "string",
  • "costPrice": 0,
  • "supplierCode": "Sup001",
  • "supplierProductCode": "string",
  • "stockMinimum": 0,
  • "stockMaximum": 0,
  • "priceA": "string",
  • "priceB": "string",
  • "priceC": "string",
  • "priceD": "string",
  • "vatLevel": "string",
  • "orderQuantity": "string",
  • "extra1": "string",
  • "extra2": "string",
  • "extra3": "string",
  • "extra4": "string",
  • "extra5": "string",
  • "hasThtDate": true,
  • "warningDaysTillThtDate": 0,
  • "maxDaysTillThtDate": 0,
  • "hasLotNumber": true,
  • "hasSerial": true,
  • "useEconomicStock": true
}

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "Edit of product (testsku125145) completed successfully.",
  • "result": null
}

Stock

WARNING!

All of the stock related endpoints in the v2 specification have been deprecated and replaced by the new v3/stock endpoints. At any point these legacy end points may be terminated. Please upgrade your implementation as soon as possible. For documentaiton on the new end-points go the the v3/stock section of our new API specification.

stock/get/:sku Deprecated

GET stock/get/:sku

This operation is deprecated, users are encouraged to migrate to the new GET v3/stock?filter[sku][in]={sku} end-point instead.
Either returns Economic stock or Free stock, based on the UseEconomicStock value in Product, set in Maya.
Authorizations:
Bearer
path Parameters
sku
required
string

the sku to retreive the stock level for

Responses

Response Schema: application/json
messageCode
string
message
string
result
integer

the stock level. Either economic or available, depending on the product's settings

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "Found stock for the provided information.",
  • "result": 15
}

stock/bulk/:all Deprecated

GET stock/bulk/:all

This operation is deprecated, users are encouraged to migrate to the new GET v3/stock end-point instead.
allProducts needs to be either true or false. Under normal operation false needs to be specified. true is only needed when performing the initial stock synchronization to force all products to be retrieved. This is an intensive operation which should only be used sparingly. When false is specified only the products that are marked as ‘needs to be synched’ will be processed.
Authorizations:
Bearer
path Parameters
all
required
bool

Responses

Response Schema: application/json
messageCode
string
message
string
Array of objects
Array
sku
string

The product SKU.

name
string

The product name.

stock
integer

Either Economic stock or Available stock, based on the UseEconomicStock value in Product, set in Maya.

Array of objects

List of the best before dates, lotnumbers and quantities per product (based on PhyscalStock)

Array
quantity
integer
string or null
One of
string <date>
string or null
One of
string
freeStock
integer

Number of free stock for this Sku

economicStock
integer

Number of economic stock for this Sku

availableStock
integer

Number of free stock minus stock stored on locations which are excluded from fulfilment

physicalStock
integer

Number of physical stock

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "Found 1 products suitable for stock synchronization.",
  • "result": [
    ]
}

v2/stock/get/:sku Deprecated

GET v2/stock/get/:sku

This operation is deprecated, users are encouraged to migrate to the new GET v3/stock?filter[sku][in]={sku} end-point instead.
Either returns various stock levels for the sku.
Authorizations:
Bearer
path Parameters
sku
required
string

Responses

Response Schema: application/json
messageCode
string
message
string
object
name
string

The product name

sku
string

The product's SKU

productId
integer

Id of the product

useEconomicStock

Either Economic stock or Available stock, based on the UseEconomicStock value in Product, set in Maya.

physicalStock
integer

Number of physical stock

expectedStock
integer

Number of expected stock

orderedStock
integer

Number of ordered stock

unavailableStock
integer

Number of unavailable stock

freeStock
integer

Number of free stock for this Sku

economicStock
integer

Number of economic stock for this Sku

availableStock
integer

Number of free stock minus stock stored on locations which are excluded from fulfilment

thts
Array of objects

List of the best before dates, lotnumbers and quantities per product (based on PhyscalStock)

Response samples

Content type
application/json
{
  • "messageCode": "string",
  • "message": "string",
  • "result": {
    }
}

v2/stock/bulk Deprecated

GET v2/stock/bulk

This operation is deprecated, users are encouraged to migrate to the new GET v3/stock end-point instead.
Both query parameters are optional, but if `all_products` is set to `true` it will take priority over `from`. When no parameters are specified stock information for all products with stock mutation date equal or greater than the default day (currently one day in the past) will be returned.

Url examples::

Authorizations:
Bearer
query Parameters
all_products
required
boolean

When true returns product stock information for all products. When false returns product stock information for products with stock mutation date equal or greater than the default day (currently one day in the past).

from
required
string <date-time>

ISO-8601 date and time format (time of day and time zone offset are optional). Value should be URLencoded. When specified, only the product stock information of products with a stock mutation date equal or greater than that date are returned.

Responses

Response Schema: application/json
messageCode
string
message
string
object
object
from
string

The date time that is lesser or equal to the stock mutation time of the products. This is the date time supplied in the request.

to
string

The date time that is greater than the stock mutation time of the products. This date time should be used as from value in the successive request.

Array of objects
Array
sku
string

The product's SKU.

name
string

The product name.

stock
integer

Either Economic stock or Free stock, based on the UseEconomicStock value in Product, set in Maya.

Array of objects

List of the best before dates, lotnumbers and quantities per product (based on PhyscalStock)

Array
quantity
integer
tht
string <date-time>
lotNumber
string
freeStock
integer

Number of free stock for this Sku

economicStock
integer

Number of economic stock for this Sku

availableStock
integer

Number of free stock minus stock stored on locations which are excluded from fulfilment

physicalStock
integer

Number of physical stock

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "Found 4 products suitable for stock synchronization.",
  • "result": {
    }
}

Stockmutations

WARNING!

All of the stock mutation related endpoints in the v2 specification have been deprecated and replaced by the new v3/stockmutations endpoints. At any point these legacy end points may be terminated. Please upgrade your implementation as soon as possible. For documentaiton on the new end-points go the the v3/stockmutations section of our new API specification.

v2/stockmutation/get Deprecated

GET v2/stockmutation/get

This operation is deprecated, users are encouraged to migrate to the new GET v3/stockmutations end-point instead.
Only the stockmutations that are marked as ‘need to be synced’ will be processed. Only mutations of the last 7 days are shown. Shipments are excluded, they should be obtained with the GetShipments operation. When processed the stockmutations can be marked ‘synced’ with the UpdateSyncedStockMutations operation. Keep in mind that returns of damaged goods cannot be retrieved through this function, as they are not added to stock but discarded. This means there won’t be a StockMutation associated with this return.
Authorizations:
Bearer

Responses

Response Schema: application/json
messageCode
string
message
string
Array of objects
Array
id
integer

Id of the Stock Mutation

sku
string
quantity
integer
type
integer

Type of mutation:

  • 1 = Received goods
  • 3 = Returned goods
  • 4 = Correction
  • 5 = Composed products
createdAt
string
thtDate

THT Date (if applicable)

warehouseCode
string

The code for the warehouse where the item was moved to

locationType
string
Enum: "AUTOSTORE" "SPECIAL" "PALLET" "PICKABLE" "COOLED" "OUTBOUND" "INBOUND" "RETURN" "TRANSFER" "SECURED" "INSERTS"

Only filled if it corresponds with a type of location, otherwise null.

correctionReason
string

Only filled with type 'correction'. Reason of correction

remark
string

Only filled with type 'correction' or 'returned goods'

supplierId

Only filled with type 'received goods'

shippingId
integer

Only filled with type 'returned goods'

orderNumber
integer

Only filled with type 'returned goods'

externalOrderNumber

Only filled with type 'returned goods'

returnReason

Only filled with type 'returned goods'

lotNumber

Lot number (if applicable)

Array of objects

Only filled with type 'received goods'

Array
purchaseOrderId
integer

Contains the purchase order Id

purchaseOrderReference
string

Contains the purchase order reference

purchaseOrderRemark
string

Any comments entered for this purchase order will be listed here.

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "Found 3 stock Mutations that match your criteria.",
  • "result": [
    ]
}

v2/stockmutation/sync Deprecated

POST v2/stockmutation/sync

This operation is deprecated, users are encouraged to migrate to the new GET v3/stockmutations end-point instead.
If an invalid collection of Ids is provided, the return message will contain a list of Ids that were not found or do not belong to your company. Any Ids that were correct will NOT be processed in this event.
Authorizations:
Bearer
Request Body schema: application/json
ids
Array of integers

Array of stockmutation id's

Responses

Response Schema: application/json
messageCode
string
message
string
result

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "Request processed successfully.",
  • "result": null
}

Purchase Orders

purchaseorder/add

POST purchaseorder/add

This operation will insert a new purchase order into our database.

Authorizations:
Bearer
Request Body schema: application/json
reference
required
string

Used to store a reference number or other text used to identify the purchase order.

comment
string

Can contain any extra information regarding the purchase order.

expectedDate
string <date-time>

The date on which the purchase order is expected to arrive

warehouseId
integer

It is an optional field, used to store id of warehouse. WarehouseId could be user input or default warehouse.

required
Array of objects
Array
sku
required
string

The product SKU for this purchase order item.

quantity
required
integer

Total number of products in this purchase order item.

expectedDate
string <date-time>

The date on which this product is expected to arrive

Responses

Response Schema: application/json
messageCode
required
string

The value OK indicates the message was accepted by the system.

Value: "OK"
message
required
string

Some response indicating the success

object or string or integer or null
One of
object

Request samples

Content type
application/json
{
  • "reference": "string",
  • "comment": "string",
  • "expectedDate": "2019-08-24T14:15:22Z",
  • "warehouseId": 0,
  • "purchaseOrderItems": [
    ]
}

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "PurchaseOrder added successfully.",
  • "result": 23056
}

purchaseorder/edit

POST purchaseorder/edit

Rules for editing and deleting purchase orders (colours will be displayed in Maya)

Green rules This purchase-order matches completely with all received goods. Each and every purchase-order-item is matched completely to incoming goods. There are no actions open for this purchase-order.

  • Edit of purchase-order allowed: NO
  • Delete of purchase-order allowed: NO
  • Edit of purchase-order-item allowed: NO
  • Delete of purchase-order-item allowed: NO
  • Adding purchase-order-item allowed: NO

Yellow rules This purchase-order is not complete: not all expected goods have been delivered, but there is at least one purchase-order-item that has goods (partially) delivered.

  • Edit of purchase-order allowed: YES (only comment and reference, not expected date)
  • Delete of purchase-order allowed: NO
  • Edit of purchase-order-item allowed: YES (if new expected quantity for this purchase-order-item >= already booked)
  • Delete of purchase-order-item allowed: YES (if no goods booked on this purchase-order-item, otherwise set to booked value)
  • Adding purchase-order-item allowed: YES

Red rules This purchase-order is new: no goods have been received for this purchase-order.

  • Edit of purchase-order allowed: YES (reference, comment and expected date)
  • Delete of purchase-order allowed: YES
  • Edit of purchase-order-item allowed: YES
  • Delete of purchase-order-item allowed: YES
  • Adding purchase-order-item allowed: YES

Notes:

  1. Edit purchase-order: edit purchase-order, only provide purchase-order-level information. Existing purchase-order-items remain untouched.
  2. Edit purchase-order-item(s): edit purchase-order, provide array of SKUs and quantities. If SKU exists: overwrite quantity. Other existing purchase-order-items remain untouched. Red/ yellow rules apply
  3. Add purchase-order-item(s): edit purchase-order, provide array of SKUs and quantities to add. Existing purchase-order-items remain untouched.
  4. Delete purchase-order-item(s): edit purchase-order, provide array of SKUs with quantities set to 0. Any unbooked purchase-order-items will be deleted, or set to currently booked quantity
Authorizations:
Bearer
Request Body schema: application/json
purchaseOrderId
required
integer

Used to look up, via Purchase Order ID of the original PO, the purchase order to be modified.

reference
string

Used to store the (modified) reference number or other text used to identify the purchase order. Overwrites the "old" reference when provided.

comment
string

Can contain any extra information regarding the purchase order. Overwrites the "old" comment when provided.

expectedDate
string <date-time>

The (modified) date on which the purchase order is expected to arrive. Overwrites original when provided.

Array of objects

All Purchase Order Items that are affected will be put into this array in your request. Any PurchaseOrderItem / SKU not listed will not be modified.

Array
sku
required
string

The product SKU for this purchase order item.

quantity
required
integer

Total number of products in this purchase order item.

Responses

Response Schema: application/json
messageCode
string
message
string
result
integer

Request samples

Content type
application/json
{
  • "purchaseOrderId": 12345,
  • "reference": "ThisIsAReference",
  • "comment": "ThisIsAComment",
  • "expectedDate": "2019-08-24T14:15:22Z",
  • "purchaseOrderItems": [
    ]
}

Response samples

Content type
application/json
{
  • "messageCode": "OK",
  • "message": "PurchaseOrder(Items) processed successfully.",
  • "result": 23056
}

purchaseorder/delete

POST purchaseorder/delete

Important Note: Calling Delete on a partially completed (Yellow) PurchaseOrder will result in the PurchaseOrder being adjusted to match any booked stock and set to Completed (Green).

To delete a purchase-order provide only purchase-order id, if red/yellow will do a full/partial delete respectively.

To delete purchase-order-item(s) provide purchase-order id and array of SKUs to be deleted. Red/yellow rules apply.

Green rules This purchase-order matches completely with all received goods. Each and every purchase-order-item is matched completely to incoming goods. There are no actions open for this purchase-order.

  • Edit of purchase-order allowed: NO
  • Delete of purchase-order allowed: NO
  • Edit of purchase-order-item allowed: NO
  • Delete of purchase-order-item allowed: NO
  • Adding purchase-order-item allowed: NO

Yellow rules This purchase-order is not complete: not all expected goods have been delivered, but there is at least one purchase-order-item that has goods (partially) delivered.

  • Edit of purchase-order allowed: YES (only comment and reference, not expected date)
  • Delete of purchase-order allowed: NO
  • Edit of purchase-order-item allowed: YES (if new expected quantity for this purchase-order-item >= already booked)
  • Delete of purchase-order-item allowed: YES (if no goods booked on this purchase-order-item, otherwise set to booked value)
  • Adding purchase-order-item allowed: YES

Red rules This purchase-order is new: no goods have been received for this purchase-order.

  • Edit of purchase-order allowed: YES (reference, comment and expected date)
  • Delete of purchase-order allowed: YES
  • Edit of purchase-order-item allowed: YES
  • Delete of purchase-order-item allowed: YES
  • Adding purchase-order-item allowed: YES
Authorizations:
Bearer
Request Body schema: application/json
purchaseOrderId
required
integer

Used to look up, via Purchase Order ID of the original purchase-order, the purchase order to be modified.

Array of objects

All purchase-order-items that are affected will be put into this array in your request. Any purchase-order-item / SKU not listed will not be modified. See below for description of valid contents.

Array
sku
required
string

The product SKU for this purchase order item.

Responses

Response Schema: application/json
messageCode
string
message
string
result
integer

Request samples

Content type
application/json
{
  • "purchaseOrderId": 1234,
  • "purchaseOrderItems": {
    }
}

Response samples

Content type
application/json
Example
null