NAV

Architectural overview

General environment

All the Wolfpack services are deployed in a high available environment. To make sure services stay up and can handle high volumes of traffic we are using Microsoft Azure. All the services are deployed in a scalable Service Fabric cluster which can be scaled up on demand.

The database engine used for all Wolfpack services is Microsoft SQL server hosted in an Azure environment. Every client is provided with a private database tailored to his needs. The Azure SQL databases can be scaled up on demand to 100TB and 4000 DTU’s.

For the product API Wolfpack makes use of MongoDB. MongoDB is a document database which is suitable for non relational data. All products are stored as a whole including all dependent data. This makes it very fast to retrieve a complete product.

All Wolfpack software is written in c# using the .Net / .Net Core framework.

Schematic architectural overview Shematic technical overview

General

Authorization

Requesting an access token

    curl https://{host}/idapp/identityserver/connect/token -X POST \
    --basic --user "{client_id}:{client_secret}" \
    -d "grant_type=client_credentials" -d "scope={scope}"
Test the api with the access token

    curl -X GET --header 'Accept: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1…' \
    https://{host}/v1/Health

Your requests to the API need to be authorized. Authorization to the wolfpack API uses the OAuth2.0 protocol.

The first example on the right shows you how to request an access token.

The client_id, client_secret and scope needed to get an authorization token can be requested at your contactperson at wolfpack. Or you can try out the API by using the following test client credentials. The access token must be included in requests by adding a HTTP Authorization header.

The second example on the right shows how to do a health check and verify that your authorization header is valid.

Every request for a single or multiple resources has to define at least two headers:

Scope

The scope of your access is always on customer level. There is no smaller set of permissions available at this time. For every api call that returns one or mulitple resources you have to explicitly define the scopeId parameter. This may change in later versions of the API.

HTTP Methods

The following HTTP request types are used:

GET to retrieve information from the server.

POST to send data to the server to create a new object or to update an existing one.

PUT to update a singular resource. It replaces the current representation of the target resource with the uploaded content.

DELETE to remove all current representations of the target resource given by a URI.

HTTP Response codes

  {
    "description": "Order bestaat al",
    "error": true
  }
  {
    "description": "OK",
    "error": false
  }

200 Kan wel result data error opleveren. OK alleen wat betreft de http connectie

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

Query standards

Common query functionality include paging and filtering. Both are standardized within the API.

Query a single resource

When requesting a single resource you will always get the entire object including it’s relations.

Query multiple resources

Queries requesting mulitple resources always return a paginated result. The paging is based on the limit and the offset parameters.

Here below the parameters required when querying for multiple resources: * offset is the number of elements skipped * limit is the max number of elements retrieved * withTotal a boolean that decides if you get the total resultcount for this query or not * filter a search term to filter the query results on

Shared types

Address

Representation of an Address object. The Address object represents an address and is returned as part of other objects like the Order or Draft Order object. The address object is used for the shipping address and the billing address.

{
  "firstName": string,
  "lastName": string,
  "address1": string,
  "address2": string,
  "address3": string,
  "city": string,
  "postalCode": string,
  "email": string,
  "companyName": string,
  "countryCode": string,
  "phone": string
}
Property name Value Description
firstName string Firstname
lastName string Lastname
address1 string Street
address2 string Housenumber
address3 string Additional address info
city string City
postalCode string Postal code
email string Email for this kind of address (e.g. billing, shipping)
companyName string Name of the company
countryCode string A two-digit country code as per ISO 3166-1 alpha-2
phone string Phonenumber

Payment

Representation of a Payment object. The Payment object is a common type used in other objects like Order or Draft Order objects.

{
  "paymentType": string,
  "processorId": string,
  "name": string,
  "amountPaid": Integer
}
Property name Value Description
paymentType string One of the allowed paymentTypes. The paymentTypes can be retrieved by calling /vX.X/orderpaymenttypes/paymenttypes
processorId string Id as known by the payment provider
name string Name of the payment provider
amountPaid Integer The amount paid in cents

Price Adjustment

[
  {
    "description": string,
    "netAdjustment": Integer,
    "taxAdjustment": Integer,
    "grossAdjustment": Integer
  }
]
Property name Value Description
description string The description of the price adjustment
netAdjustment Integer The net price adjustment
taxAdjustment Integer The tax adjustment
grossAdjustment Integer The gross price adjustment

Currency

Representation of a currency object. The Currency object is a common type used in other objects.

{
  "id": Integer,
  "description": string,
  "isoCode": string
}
Property name Value Description
id Number the amount in cents
description string a description of the currency
isoCode string the currency code compliant to ISO 4217”

Swagger documentation

All the available API versions have swagger documentation available through the following links.

Production

Staging

Orders

Representations

There are different representations of an order. When you request an orderlist for example, the order details returned are fine tuned on what needs to be represented in a list. The fields returned are fixed and can not by choosen by the requester.

All the operations here below can be tried out through the swagger documentation documentation.

Draft Order A Draft Order is an Order that has not been finalized yet. Which means the order can still be modified before it’s made final. In this version of the API a Draft Order contains general order info. A Draft order does NOT contain Payment information, Shipment information or order level price adjustments.

Example usage

A draft order can be created when an In Store sales Assistant (ISA) creates an order. In this case the pricing and promotions are handled outside of the ISA. The ISA creates a Draft Order and the cashregister finalizes the draft order by adding pricing, promotions and delivery information.

DraftOrder

Representation of a Draft Order object. A version of this object is used when creating or retrieving a Draft Order.

{
  "externalId": string,
  "erpChannelId": string,
  "customerName": string,
  "orderNumber": string,
  "orderLines": [
    {
      "orderLinePriceAdjustment": [
        {
          "description": string,
          "netAdjustment": Integer,
          "taxAdjustment": Integer,
          "grossAdjustment": Integer
        }
      ],
      "ean": string,
      "sku": string,
      "externalId": string,
      "quantity": Integer,
      "lineNumber": Integer,
      "online": boolean,
      "name": string,
      "productInformation": string,
      "netPrice": Integer,
      "tax": Integer,
      "taxPercentage": Integer,
      "grossPrice": Integer,
      "originalGrossPrice": Integer,
      "customOrderLineProperties": [
        {
          "key": string,
          "value": string
        }
      ]
    }
  ],
  "currencyCode": string,
  "originalGrossPrice": Integer,
  "netPrice": Integer,
  "grossPrice": Integer,
  "tax": Integer
}
Property name Value Description
externalId string ExternalID of the Order as used in system(s) outside of ORP
erpChannelId string the id of the OrderChannel the Order is coming from
customerName string Name of the customer
orderNumber string Ordernumber, this is the number that can be used to retrieve the order later on
orderLines list of OrderLine object Defines the state of the order in the order lifecycle. Allowed values in OrderState
currencyCode Currency Code of the currency used. Allowed values can be retrieved through /vX/OrderCurrencies
originalGrossPrice Integer the gross price of the order before discounts but including shipping costs in cents
netPrice Integer the net price of the order after discounts, including shipping fees, without tax in cents
grossPrice Integer the gross price of the order after discounts, including shipping fees, including tax in cents
tax Integer the tax amount in cents

FinalDraftOrder

{
  "orderNumber": string,
  "newOrderNumber": string,
  "customerName": string,
  "customerNumber": string,
  "customerEmail": string,
  "orderLines": [
    {
      "orderLinePriceAdjustment": [
        {
          "description": string,
          "netAdjustment": Integer,
          "taxAdjustment": Integer,
          "grossAdjustment": Integer
        }
      ],
      "ean": string,
      "sku": string,
      "externalId": string,
      "quantity": Integer,
      "lineNumber": Integer,
      "online": boolean,
      "name": string,
      "productInformation": string,
      "netPrice": Integer,
      "tax": Integer,
      "taxPercentage": Integer,
      "grossPrice": Integer,
      "originalGrossPrice": Integer,
      "customOrderLineProperties": [
        {
          "key": string,
          "value": string
        }
      ]
    }
  ],
  "payments": [
    {
      "paymentType": string,
      "processorId": string,
      "name": string,
      "amountPaid": Integer
    }
  ],
  "billingAddress": {
    "firstName": string,
    "lastName": string,
    "address1": string,
    "address2": string,
    "address3": string,
    "city": string,
    "postalCode": string,
    "email": string,
    "companyName": string,
    "countryCode": string,
    "phone": string
  },
  "shippingAddress": {
    "firstName": string,
    "lastName": string,
    "address1": string,
    "address2": string,
    "address3": string,
    "city": string,
    "postalCode": string,
    "email": string,
    "companyName": string,
    "countryCode": string,
    "phone": string
  },
  "priceAdjustments": [
    {
      "description": string,
      "netAdjustment": Integer,
      "taxAdjustment": Integer,
      "grossAdjustment": Integer
    }
  ],
  "originalGrossPrice": Integer,
  "netPrice": Integer,
  "grossPrice": Integer,
  "tax": Integer,
  "shippingNetPrice": Integer,
  "shippingGrossPrice": Integer,
  "shippingTax": Integer,
  "customerLocale": string
}
Property name Value Description
orderNumber string Ordernumber, this is the number that can be used to retrieve the order later on
newOrderNumber string New ordernumber, this is the new ordernumber that will be used after finalization of the order
customerName string Name of the customer
customerNumber string Customer number
customerEmail string Emailadress of the customer
orderLines list of OrderLine object the different order lines on the order
payments list of Payment object in shared types Lists how the order has been paid. With one or more payments.
billlingAddress Address object The address used for billing
shippingAddress Address object The address used for shipping
priceAdjustments List of PriceAdjustment object The price adjustments or discounts and there description
originalGrossPrice Integer the gross price of the order before discounts but including shipping costs in cents
netPrice Integer the net price of the order after discounts, including shipping fees, without tax in cents
grossPrice Integer the gross price of the order after discounts, including shipping fees, including tax in cents
tax Integer the tax amount in cents

ListDraftOrder

[
  {
    "externalId": string,
    "erpChannelId": string,
    "orderNumber": string,
    "customerName": string,
    "currencyCode": string,
    "netPrice": Integer,
    "orderDate": string
  },
  {...}
]
Property name Value Description
externalId string The label of the custom property
erpChannelId string the id of the OrderChannel the Order is coming from
orderNumber string Ordernumber, this is the number that can be used to retrieve the order later on
customerName string Name of the customer
currencyCode Currency Code of the currency used. Allowed values can be retrieved through /vX/OrderCurrencies
netPrice Integer the net price of the order after discounts, including shipping fees, without tax in cents
orderDate string The date the order was placed

Order

{
  "id": Integer,
  "externalId": string,
  "orderType": string,
  "orderTypeId": Integer,
  "refundOnline": boolean,
  "currentOrderStatus": string,
  "orderDate": "2018-10-15T12:49:06.847Z",
  "channelDescription": string,
  "channelErpId": string,
  "channelId": Integer,
  "orderInteger": string,
  "customerInteger": string,
  "customerName": string,
  "customerEmail": string,
  "orderLines": [
    OrderLine
  ],
  "payments": [
    Payment
  ],
  "priceAdjustments": [
    {
      "description": string,
      "netAdjustment": Integer,
      "taxAdjustment": Integer,
      "grossAdjustment": Integer
    }
  ],
  "customOrderProperties": [
    CustomProperty
  ],
  "orderCurrencyCode": string,
  "originalGrossPrice": Integer,
  "netPrice": Integer,
  "grossPrice": Integer,
  "tax": Integer,
  "shippingNetPrice": Integer,
  "shippingGrossPrice": Integer,
  "shippingTax": Integer,
  "country": string,
  "shipments": [
    Shipment
  ],
  "customerLocale": string,
  "billingAddress": Address,
  "created": "2018-10-15T12:49:06.847Z",
  "modified": "2018-10-15T12:49:06.847Z"
}
Property name Value Description
id Integer Unique ID of the Order in ORP
externalId string ExternalID of the Order as used in system(s) outside of ORP
orderType String The type of Order as allowed by /vX.X/ordertypes
orderTypeId Integer The id of the OrderType
refundOnline boolean -
currentOrderStatus String The status of the order in the order lifecycle. To get possible statusses call /x.x/orderstatusses
orderDate Date the date the order was placed
channelDescription String The description of the channel the order is coming from.
erpChannelId string the id of the OrderChannel the Order is coming from
channelId Integer the id of the channel the order is coming from. Get the possible channelId’s from /x.x/OrderChannel
orderInteger string Ordernumber, this is the number that can be used to retrieve the order later on
customerName string Name of the customer
customerInteger string Customer number
customerEmail string Email address of the customer
orderLines list of OrderLine object the different order lines on the order
payments list of Payment object in shared types Lists how the order has been paid. With one or more payments.
priceAdjustments List of PriceAdjustment object The price adjustments or discounts and there description
customOrderProperties List of CustomProperty To add any custom property that is not already defined on the Order
orderCurrencyCode String The ISO currency code. . To get possible currencies call the /x.x/ordercurrencies
originalGrossPrice Integer the gross price of the order before discounts but including shipping costs in cents
netPrice Integer the net price of the order after discounts, including shipping fees, without tax in cents
grossPrice Integer the gross price of the order after discounts, including shipping fees, including tax in cents
tax Integer the tax amount in cents
shippingNetPrice Integer
shippingGrossPrice Integer
shippingTax Integer
country String The country where the order is coming from
shipments List of Shipment objects Defines the shipments done for the order
customerLocale String The locale of the customer
billlingAddress Address object The address used for billing
created string The date on which the order has been created
modified Integer Dat of the last modification of the order

OrderLine

{
  "orderLinePriceAdjustment": [
    {
      "description": string,
      "netAdjustment": Integer,
      "taxAdjustment": Integer,
      "grossAdjustment": Integer
    }
  ],
  "ean": string,
  "sku": string,
  "externalId": string,
  "quantity": Integer,
  "quantityShipped": Integer,
  "quantityMispick": Integer,
  "quantityReturned": Integer,
  "online": boolean,
  "lineNumber": Integer,
  "name": string,
  "productInformation": string,
  "netPrice": Integer,
  "tax": Integer,
  "taxPercentage": Integer,
  "grossPrice": Integer,
  "originalGrossPrice": Integer,
  "customOrderLineProperties": [
    CustomProperty
  ]
}
Property name Value Description
orderLinePriceAdjustment List of priceAdjustment object The adjustments to the default product price, like discounts.
ean string Ean code of the product
sku string The SKU of the product
externalId string The ID of the product as it is known in external systems. Like the id in the connected ERP system e.g.
quantity Integer The number of this product bought
lineNumber Integer The order line number
online boolean Is this a product sold online or in store
name string Name of the product
productInformation string Extra information on the product
netPrice Integer Netprice of the product in cents
tax Integer Tax amount in cents
taxPercentage Integer The tax percentage used here
grossPrice Integer The gross price of the orderline in cents
originalGrossPrice Integer The original grossprice of the orderline wihtout discounts in cents
customOrderLineProperties List of customProperties objects To add any custom key/value pairs that are not mentioned above

CustomProperty

{
  "key": string,
  "value": string
}
Property name Value Description
key string The label of the custom property
value string The value of the property

ListOrder

Representation of a ListOrder object. This ListOrder is returned in the response of the list method further down.

{
  "id": Integer,
  "orderInteger": String,
  "orderState": OrderState,
  "state": State,
  "channel": Channel,
  "dateCreated": Date,
  "totalPrice": Money,
  "subTotalPrice": Money,
  "taxedPrice": Money,
  "addresses": [
      Address
  ]
}
Property name Value Description
id Integer Unique ID of the Order
orderInteger String Order number as defined by the originating system
orderState OrderState Defines the state of the order in the order lifecycle. Allowed values in OrderState
state State Optional - this state points to a state in a custom workflow that can be different per customer
totalPrice Money The price of the product after tax with discounts applied multiplied by the quantity
subTotalPrice Money The price of the product after tax without discounts applied multiplied by the quantity
taxedPrice Money The price of the product before tax without discounts applied multiplied by the quantity
addresses Array of Address Optional - list of Address containing a shipping address and a billing address

Shipment

{
  "shipmentLines": [
    {
      "orderLineId": Integer,
      "quantity": Integer,
      "orderLineExternalId": string
    }
  ],
  "shippingAddress": {
    "firstName": string,
    "lastName": string,
    "address1": string,
    "address2": string,
    "address3": string,
    "city": string,
    "postalCode": string,
    "email": string,
    "companyName": string,
    "countryCode": string,
    "phone": string
  },
  "deliveries": [
    {
      "carrier": string,
      "trackNTrace": string,
      "deliveryLines": [
        {
          "sku": string,
          "quantityShipped": Integer,
          "quantity": Integer
        }
      ]
    }
  ]
}
Property name Value Description
shipmentLines.orderLineId Integer The orderLineId this shipment is linked to
shipmentLines.quantity Integer The amount of items of the orderLine that is shipped
orderLineExternalId string The externalId of the orderline as it is know in other systems
ShippingAddress Address object The shipping address for this shipment
deliveries A list of Delivery object Delivery information on orderline level

Delivery

{
  "carrier": string,
  "trackNTrace": string,
  "deliveryLines": [
    {
      "sku": string,
      "quantityShipped": Integer,
      "quantity": Integer
    }
  ]
}
Property name Value Description
carrier string The name of the carrier that shipped the products
trackNTrace string The trackNTrace URL where the shipment can be tracked
sku string The sku of the product in the shipment
quantityShipped Integer The number of items with sku shipped
quantity Integer The total number of items of the same sku

getdraft

Get one order by ordernumber

Request

GET /vX.X/draftorders/{ordernumber}

Parameters

Parameter name Value Description
orderNumber string required - the OrderNumber of the order
scopeId Number required - the scope for which the order will be created
authorization string required - the bearer token for authorization

Request Body

No request body for this operation

Response

If successful this operation returns a Draft Order in the response body

listdraft

Call these methods to get a list of orders. The result will be a PagedQueryResult with a List Draft Order in the resultset.

Request

GET /vX.X/draftorders/list

Parameters

Property name Value Description
erpChannelId string required - the channelId for which you like to retrieve orders
offset Number number of elements that where skipped
limit Number page size or maximum number of elements in the result set
withTotal string required - the total amount of objects matching the query
filter string optional - a value to filter on. Could be part of the name or ordernumber
scopeId Number required - the scope for which the order will be created
authorization string required - the bearer token for authorization

Request Body

No request body for this operation

Response

If successful the operation returns a PagedQueryResult

{
  "offset": Number,
  "limit": Number,
  "count": Number,
  "total": Number,
  "results": [
    ListDraftOrder
  ]
}
Property name Value Description
offset Number number of elements that where skipped
limit Number page size or maximum number of elements in the result set
count Number the total of results returned
total Number the total amount of objects matching the query
results Array a list of ListDraftOrder objects

insertdraft

Request

POST /vX.X/draftorders/draft

Parameters

Property name Value Description
scopeId Number required - the scope for which the order will be created
authorization string required - the bearer token for authorization

Request Body

Supply a Draft Order resource in the request body with at least the required properties. All the properties not specified will be set to their default.

Response

OK if the order could have been inserted correctly.

finalizedraft

When finalizing an order it is still possible to change the OrderNumber of the draft order. If this is needed, you can enter the original ordernumber in orderNumber and the new ordernumber in newOrderNumber.

Request

PUT /vX.X/draftorders/draft/finalize

Parameters

Property name Value Description
scopeId Number required - the scope for which the order will be finalized
authorization string required - the bearer token for authorization

Request Body

The request body of the finalize call needs to contain a Final Draft Order object including shipping address, billing address and payment information.

Response

OK if the order could have been finalized correctly

get

Get one order by ordernumber

Request

GET /vX.X/orders/{ordernumber}

Parameters

Parameter name Value Description
orderInteger string the OrderInteger of the order

Request Body

No request body

Response

If successful this operation returns an Order resource in the response body

list

Call these methods to get a list of orders. The result will be a PagedQueryResult with ListOrder in the resultset

Request

GET /vX.X/orders/list

Parameters

Property name Value Description
offset Integer number of elements that where skipped
limit Integer page size or maximum number of elements in the result set
withTotal string required - the total amount of objects matching the query
filter string optional - a value to filter on. Could be part of the name or ordernumber
scopeId Integer required - the scope for which the order will be created
authorization string required - the bearer token for authorization

Request Body

No request body for this operation

Response

If successful the operation returns a PagedQueryResult

{
  "offset": Integer,
  "limit": Integer,
  "count": Integer,
  "total": Integer,
  "results": [
    ListOrder
  ]
}
Property name Value Description
offset Integer number of elements to be skipped
limit Integer page size or maximum number of elements in the result set
count Integer the total of results returned
total Integer the total amount of objects matching the query
results Array a list of ListOrder objects

getorderbystatus

Request

GET /vX.X/orders/status/{currentorderstatus}

Parameters

Property name Value Description
currentOrderStatus string The status for which you would like to get orders
offset Integer number of elements that where skipped
limit Integer page size or maximum number of elements in the result set
withTotal string required - the total amount of objects matching the query
filter string optional - a value to filter on. Could be part of the name or ordernumber
scopeId Integer required - the scope for which the order will be created
authorization string required - the bearer token for authorization

Request Body

No request body for this operation

Response

If successful the operation returns a PagedQueryResult

{
  "offset": Integer,
  "limit": Integer,
  "count": Integer,
  "total": Integer,
  "results": [
    Order
  ]
}
Property name Value Description
offset Integer number of elements to be skipped
limit Integer page size or maximum number of elements in the result set
count Integer the total of results returned
total Integer the total amount of objects matching the query
results Array a list of Order objects

getorderbystatusandtype

Request

GET /vX.X/orders/status/{currentorderstatus}/{ordertype}

Parameters

Property name Value Description
currentOrderStatus string The status for which you would like to get orders
orderType string The type of order you would like to see in the resultset
offset Integer number of elements that where skipped
limit Integer page size or maximum number of elements in the result set
withTotal string required - the total amount of objects matching the query
filter string optional - a value to filter on. Could be part of the name or ordernumber
scopeId Integer required - the scope for which the order will be created
authorization string required - the bearer token for authorization

Request Body

No request body for this operation

Response

If successfull the method returns a PagedQueryResult

{
  "offset": Integer,
  "limit": Integer,
  "count": Integer,
  "total": Integer,
  "results": [
    Order
  ]
}
Property name Value Description
offset Integer number of elements to be skipped
limit Integer page size or maximum number of elements in the result set
count Integer the total of results returned
total Integer the total amount of objects matching the query
results Array a list of Order objects

getdelivery

Request

GET /vX.X/deliveries/{orderNumber}

Parameters

Property name Value Description
orderNumber string The number of the order to get delivery information for
scopeId Integer required - the scope for which the order will be created
authorization string required - the bearer token for authorization

Request Body

No request body for this operation

Response

If successful the method returns an Order resource.

getorderchannel

Request

GET /vX.X/orderchannel

Parameters

Property name Value Description
scopeId Integer required - the scope for which the order will be created
authorization string required - the bearer token for authorization

Request Body

No request body for this operation

Response

If succesfull the method returns a list of OrderChannel resources:

[
  {
    "erpId": string,
    "description": string
  },
  {...}
]
Property name Value Description Example
erpId string The id of the channel the order is coming from w1
description string The description of the channel the order is coming from Amsterdam Store

getordercurrencies

Request

GET /vX.X/ordercurrencies

Parameters

Property name Value Description
authorization string required - the bearer token for authorization

Request Body

No request body for this operation

Response

If successful the method returns a list of Currency resources like described in Shared Types.

getorderpaymenttypes

Request

GET /vX.X/orderpaymenttypes/paymenttypes

Parameters

Property name Value Description
authorization string required - the bearer token for authorization

Request Body

No request body for this operation

Response

If successful the method returns a list of PaymentType resources:

[
  {
    "id": Integer,
    "description": string
  }
]
Property name Value Description Example
id Integer The payment type id 1
description string The description of the paymenttype ideal

getorderstatusses

Request

GET /vX.X/orderstatusses

Parameters

Property name Value Description
authorization string required - the bearer token for authorization

Request Body

No request body for this operation

Response

If successful the method returns a list of OrderStatus resources:

[
  {
    "id": Integer,
    "description": string
  }
]
Property name Value Description Example
id Integer The orderstatus id 100
description string The description of the orderstatus NEW

getordertypes

Request

GET /vX.X/ordertypes

Parameters

Property name Value Description
authorization string required - the bearer token for authorization

Request Body

No request body for this operation

Response

If succesfull the method returns a list of OrderType resources:

[
  {
    "id": Integer,
    "description": string
  }
]
Property name Value Description Example
id Integer The ordertype id 1
description string The description of the ordertype Web

insert

Request

POST /vX.X/orders

Parameters

Property name Value Description
scopeId Integer required - the scope for which the order will be created
authorization string required - the bearer token for authorization

Request Body

Supply an Order resource in the request body. All the properties not specified will be set to their default.

Response

OK, if the order could be created.

insertAsync

The asynchronous creation of an order will put the order on a queue. The order will not be created in ORP immediately. The time between this call and the order creation is to be discussed.

Request

POST /vX.X/orders/async

Parameters

Property name Value Description
scopeId Integer required - the scope for which the order will be created
authorization string required - the bearer token for authorization

Request Body

Supply an Order resource in the request body. All the properties not specified will be set to their default.

Response

OK, if the order could be added to the queue.

remove

Request

DELETE /vX.X/orders/{ordernumber}

Parameters

Property name Value Description
orderNumber string required - the number of the order
scopeId Integer required - the scope for which the order will be created
authorization string required - the bearer token for authorization

Request Body

No request body for this operation

Response

200 OK if the order can be deleted

insertDelivery

Request

POST /vX.X/deliveries

Parameters

Property name Value Description
scopeId Integer required - the scope for which the order will be created
authorization string required - the bearer token for authorization

Request Body

Supply a Delivery resource in the request body as shown here below.

{
  "orderNumber": string,
  "deliveryShipments": [
    {
      "trackAndTrace": string,
      "carrier": string,
      "shippedItems": [
        {
          "sku": string,
          "quantity": Integer
        }
      ]
    }
  ],
  "returnedItems": [
    {
      "sku": string,
      "quantity": Integer
    }
  ],
  "mispickedItems": [
    {
      "sku": string,
      "quantity": Integer
    }
  ]
}
Property name Value Description
orderNumber string The number of the order for which the delivery is done
trackNTrace string The trackNTrace URL where the shipment can be tracked
carrier string The name of the carrier that shipped the products
sku string The sku of the product in the shipment
quantityShipped Integer The number of items with sku shipped
returnedItems.sku string The sku of the product returned
returnedItems.quantity Integer The total number of items of the sku that is returned
mispickedItems.sku string The sku of the product mispicked
mispickedItems.quantity Integer The number of items of this sku mispicked

Response

200 OK if the delivery can be inserted

updateStatus

Request

PUT /vX.X/status

Parameters

Property name Value Description
scopeId Integer required - the scope for which the order will be created
authorization string required - the bearer token for authorization

Request Body

Supply a orderStatusUpdate resource in the request body as shown here below.

{
  "ordernumber": string,
  "orderStatusTypeId": Integer
}
Property name Value Description
orderNumber string The number of the order for which the delivery is done
orderStatusTypeId Integer The id of an allowed order status that can be found through /vX.X/orderstatusses

Response

200 OK if the order status can be updated

Products

The product api is divided into two parts: the read api and the write api. To retrieve product data you use the GET operations from the product read swagger documentation. To update product data you use the POST and PUT operations from the product write swagger documentation. The productwrite api also offers a few GET operations to retrieve values that are needed to complete POST and PUT operations. Like id’s for referenced objects.

Here below the description of the read and write API starting with the operations from the read api followed by the operations of the write api.

Representations

The read and write operations all use the entire or partial Product resource either in the response body or in the request body.

Product

Representation of a Product object as used in the response of GET operations

{
  "id": string,
  "scopeId": string,
  "erpId": string,
  "eanCode": string,
  "status": string,
  "masterVariantType": Number,
  "parentId": string,
  "children": [
    string
  ],
  "attributes": [
    {
      "locale": string,
      "name": string,
      "value": string
    }
  ],
  "names": [
    {
      "locale": string,
      "value": string
    }
  ],
  "descriptions": [
    {
      "locale": string,
      "type": string,
      "value": string
    }
  ],
  "prices": [
    Price
  ],
  "images": [
    {
      "url": string
    }
  ],
  "salesChannelAvailabilities": [
    SalesChannelAvailability
  ],
  "modified": Date
}
Property name Value Description Example
id Number Unique ID BA20118899-5000 or BA20118899-5000-S
scopeId string Id of the scope this product belongs to WP
erpId string The id of the channel the order is coming from BA20118899-blue or BA20118899-blue-S
eanCode string EAN code of the product 871234567788
status string Product status -
masterVariantType Number Value 1 if it is a master product, value 2 if it is a product variant 1
parentId string The id of the master product if this concerns a product variant. If this product is a master product this field is null BA20118899-5000 or null
children list of string List of id’s of children BA20118899-5000-S, BA20118899-5000-M etc or empty list
attributes list List of Locale, name and value for the attribute “nl-NL”, “Material”, “Cotton”
names list List of locale and value for the name of the product “nl-NL”, “Stoere capuchon trui”
descriptions list List of Locale, type and value for the description “nl-NL”, “Short description”, “Korte omschrijving voor de stoere capuchon trui”
prices list of Price object - -
images list of image urls this list is part of the product when doing a GET operation. To update images a different operation is available -
salesChannelAvailabilities list of SalesChannelAvailability object defines on which sales channels the product can be available -
modified Date the last modified date of the product “2018-08-23T05:32:14”

Price

{
    "priceType": string,
    "currencyISOCode": string,
    "price": Number,
    "dateFrom": Date,
    "dateTo": Date
}
Property name Value Description Example
priceType string description of the type of price Normal price or Sale price
currencyISOCode string the currency code compliant to ISO 4217” EUR
price Number the price in cents 1595
dateFrom Date the date from which this price is valid “2018-08-16T09:32:14”
dateTo Date the date until which this price is valid “2018-08-23T05:32:14”

SalesChannelAvailability

{
  "salesChannel": string,
  "salesChannelId": Number,
  "available": boolean,
  "availableFrom": Date,
  "availableTo": Date
}
Property name Value Description Example
salesChannel string name of the sales channel Webshop
salesChannelId Number id of the sales channel 1
available boolean true if the product is available true
availableFrom Date date from which the product is available in the sales channel “2018-08-16T09:32:14”
availableTo Date date until which the product is available in the sales channel “2018-08-23T05:32:14”

ProductVariant

The representation of a ProductVariant resource is the same as a Product resource.

health

To do a health check on the product read api.

Request

GET /vX.X/health

Parameters

Parameter name Value Description
authorization string required - the bearer token for authorization

Request body

No request body for this operation

Response

200 OK if the health check succeeded

get

This operation can be used to retrieve a product by id.

Request

GET /vX.X/products/id

Parameters

Parameter name Value Description
id string required - the product id
scopeId Number required - the scope for which the operation will be done
authorization string required - the bearer token for authorization

Request body

No request body for this operation

Response

If successful the operation returns a Product resource that represents either a master of a variant depending on the id parameter.

list

This operation can be used to retrieve all products, masters or variants, for a specific scope.

Request

GET /vX.X/products

Parameters

Property name Value Description
offset Number required - number of elements that where skipped
limit Number required - page size or maximum number of elements in the result set
withTotal string required - the total amount of objects matching the query
filter string optional - a value to filter on. Could be part of the name or productnumber
scopeId Number required - the scope for which the operation will be done
authorization string required - the bearer token for authorization

Request body

No request body for this operation

Response

If successful the operation returns a PagedQueryResult

  {
    "offset": Number,
    "limit": Number,
    "count": Number,
    "total": Number,
    "results": [
      Product
    ]
  }
Property name Value Description
offset Number number of elements that where skipped
limit Number page size or maximum number of elements in the result set
count Number the total of results returned
total Number the total amount of objects matching the query
results Array a list of Product objects

listproductmaster

This operation can be used to retrieve all product masters for a specific scope.

Request

GET /vX.X/productmaster

Parameters

Property name Value Description
offset Number number of elements that where skipped
limit Number page size or maximum number of elements in the result set
withTotal string required - the total amount of objects matching the query
filter string optional - a value to filter on. Could be part of the name or productnumber
scopeId Number required - the scope for which the operation will be done
authorization string required - the bearer token for authorization

Request body

No request body for this operation

Response

If successful the operation returns a PagedQueryResult

{
  "offset": Number,
  "limit": Number,
  "count": Number,
  "total": Number,
  "results": [
    Product
  ]
}
Property name Value Description
offset Number number of elements that where skipped
limit Number page size or maximum number of elements in the result set
count Number the total of results returned
total Number the total amount of objects matching the query
results Array a list of Product objects

listcomplete

This operation retrieves all the products with the status complete.

Request

GET /vX.X/products/complete

Parameters

Property name Value Description
offset Number required - number of elements that where skipped
limit Number required - page size or maximum number of elements in the result set
withTotal string required - the total amount of objects matching the query
filter string optional - a value to filter on. Could be part of the name or productnumber
scopeId Number required - the scope for which the operation will be done
authorization string required - the bearer token for authorization

Request body

No request body for this operation

Response

If successful the operation returns a PagedQueryResult

{
  "offset": Number,
  "limit": Number,
  "count": Number,
  "total": Number,
  "results": [
    Product
  ]
}
Property name Value Description
offset Number number of elements that where skipped
limit Number page size or maximum number of elements in the result set
count Number the total of results returned
total Number the total amount of objects matching the query
results Array a list of Product objects

getvariants

This operation retrieves all product variants for the specified scope.

Request

GET /vX.X/productvariant

Parameters

Property name Value Description
offset Number required - number of elements that where skipped
limit Number required - page size or maximum number of elements in the result set
withTotal string required - the total amount of objects matching the query
filter string optional - a value to filter on. Could be part of the name or productnumber
scopeId Number required - the scope for which the operation will be done
authorization string required - the bearer token for authorization

Request body

No request body for this operation

Response

If successful the operation returns a PagedQueryResult

{
  "offset": Number,
  "limit": Number,
  "count": Number,
  "total": Number,
  "results": [
    Product
  ]
}
Property name Value Description
offset Number number of elements that where skipped
limit Number page size or maximum number of elements in the result set
count Number the total of results returned
total Number the total amount of objects matching the query
results Array a list of Product objects

getvariantsformaster

This operation retrieves all the variants for a specified master.

Request

GET /vX.X/productvariant/{masterid}

Parameters

Property name Value Description
masterId string required - the id of the master for which to retrieve variants
offset Number required - number of elements that where skipped
limit Number required - page size or maximum number of elements in the result set
withTotal string required - the total amount of objects matching the query
filter string optional - a value to filter on. Could be part of the name or productnumber
scopeId Number required - the scope for which the operation will be done
authorization string required - the bearer token for authorization

Request body

No request body for this operation

Response

If successful the operation returns a PagedQueryResult

{
  "offset": Number,
  "limit": Number,
  "count": Number,
  "total": Number,
  "results": [
    Product
  ]
}
Property name Value Description
offset Number number of elements that where skipped
limit Number page size or maximum number of elements in the result set
count Number the total of results returned
total Number the total amount of objects matching the query
results Array a list of Product objects

getimages

This operation retrieves the images for the specified productVariantIds.

Request

GET /vX.X/productvariant/images

Parameters

Parameter name Value Description
productVariantIds string required - a comma separated list of productVariantIds
scopeId Number required - the scope for which the operation will be done
authorization string required - the bearer token for authorization

Request body

No request body for this operation

Response

insertproductmaster

This operation creates a productmaster.

Request

POST /vX.X/productmasters

Parameters

Parameter name Value Description
scopeId Number required - the scope for which the operation will be done
authorization string required - the bearer token for authorization

Request body

Supply a partial Product resource in the request body as shown here below. For the description of the attributes checkout the Product resource description.

{
  "productCode": string,
  "erpId": string,
  "status": string,
  "names": [
    {
      "locale": string,
      "value": string
    }
  ],
  "descriptions": [
    {
      "descriptionType": Number,
      "locale": string,
      "value": string
    }
  ],
  "attributeValues": [
    {
      "attributeId": Number,
      "attributeListValueId": Number,
      "value": string,
      "localizedValues": [
        {
          "locale": string,
          "value": string
        }
      ]
    }
  ],
  "imageGroups": [
    {
      "description": string,
      "images": [
        {
          "url": string
        }
      ]
    }
  ],
  "productVariations": [
    {
      "productCode": string,
      "erpId": string,
      "eanCode": string,
      "attributeValues": [
        {
          "attributeId": Number,
          "attributeListValueId": Number,
          "value": string,
          "localizedValues": [
            {
              "locale": string,
              "value": string
            }
          ]
        }
      ],
      "prices": [
        Price
      ]
    }
  ]
}

Response

200 OK if the product master could be created.

updateproductmaster

This operation updates a productmaster.

Request

PUT /vX.X/productmasters/{productcode}

Parameters

Parameter name Value Description
productCode string required - the id of the productmaster to update
scopeId Number required - the scope for which the operation will be done
authorization string required - the bearer token for authorization

Request body

Supply a partial Product resource in the request body as shown here below. For the description of the attributes checkout the Product resource description.

{
  "status": string,
  "names": [
    {
      "locale": string,
      "value": string
    }
  ],
  "descriptions": [
    {
      "descriptionType": Number,
      "locale": string,
      "value": string
    }
  ],
  "attributeValues": [
    {
      "attributeId": Number,
      "attributeListValueId": Number,
      "value": string,
      "localizedValues": [
        {
          "locale": string,
          "value": string
        }
      ]
    }
  ],
  "imageGroups": [
    {
      "description": string,
      "images": [
        {
          "url": string
        }
      ]
    }
  ]
}

Response

200 OK if the product master could be updated.

insertproductvariant

This operation creates a new product variant.

Request

POST /vX.X/productmasters/{productmastercode}/productvariations

Parameters

Parameter name Value Description
productMasterCode string required - the product master id for which to create the variant
scopeId Number required - the scope for which the operation will be done
authorization string required - the bearer token for authorization

Request body

Supply a partial Product resource in the request body as shown here below. For the description of the attributes checkout the Product resource description.

{
  "productCode": string,
  "erpId": string,
  "eanCode": string,
  "attributeValues": [
    {
      "attributeId": Number,
      "attributeListValueId": Number,
      "value": string,
      "localizedValues": [
        {
          "locale": string,
          "value": string
        }
      ]
    }
  ],
  "prices": [
    {
      "id": 0,
      "priceTypeId": 0,
      "currencyCode": string,
      "price": 0,
      "dateFrom": Date,
      "dateTo": Date
    }
  ]
}

Response

200 OK if the product variant could be created.

updateproductvariant

This operation updates a productvariant.

Request

PUT /vX.X/productmasters/{productmastercode}/productvariations/{productcode}

Parameters

Parameter name Value Description
productMasterCode string required - the product master id for which the variant will be updated
productCode string required - the product variant id that will be updated
scopeId Number required - the scope for which the operation will be done
authorization string required - the bearer token for authorization

Request body

Supply a partial Product resource in the request body as shown here below. For the description of the attributes checkout the Product resource description.

{
  "attributeValues": [
    {
      "attributeId": Number,
      "attributeListValueId": Number,
      "value": string,
      "localizedValues": [
        {
          "locale": string,
          "value": string
        }
      ]
    }
  ],
  "prices": [
    {
      "id": Number,
      "priceTypeId": Number,
      "currencyCode": string,
      "price": Number,
      "dateFrom": Date,
      "dateTo": Date
    }
  ]
}

Response

200 OK if the product variant could be updated.

insertattributedefinitions

This operation creates attribute definitions that are used to define the different types of attributes when adding attributes to products.

Request

POST /vX.X/attributedefinitions

Parameters

Parameter name Value Description
scopeId Number required - the scope for which the operation will be done
authorization string required - the bearer token for authorization

Request body

Supply an AttributeDefinition resource in the request body as shown here below:

{
  "name": string,
  "description": string,
  "localizable": boolean,
  "required": boolean,
  "attributeTypeId": Number,
  "attributeRestrictions": [
    {
      "description": string,
      "restriction": string
    }
  ],
  "attributeListValues": [
    {
      "value": string,
      "localizedValues": [
        {
          "locale": string,
          "value": string
        }
      ]
    }
  ]
}
Property name Value Description Example
name string the name of the attribute Color
description string the description of the attribute Color
localizable boolean wether the attribute is localizable or not false
required boolean wether the attribute is required or not true
attributeTypeId Number the id of the type of attribute as can be found by calling /vX.X/attributetypes 1
attributeRestrictions Object the description of a restriction and the restriction itself. Can be a regular expression -
attributeListValues List of Object a list of possible values and there localized value if it exists (see example below)

Example attributeListValues as shown here on the right.

{
  "id": 9,
  "value": "Mannen",
  "localizedValues": [
    {
      "locale": "nl-NL",
      "value": "Mannen"
    },
    {
      "locale": "en-GB",
      "value": "Men"
    },
    {
      "locale": "de-DE",
      "value": "Herren"
    }
  ]
}

Response

200 OK if the attributeDefinition has been created correctly and in the response body the created attributeDefinition.

insertprices

This operation creates a price object for the product with the erpId given in the request body.

Request

POST /vX.X/prices

Parameters

Parameter name Value Description
scopeId Number required - the scope for which operation will be done
authorization string required - the bearer token for authorization

Request body

Supply a Price resource in the request body.

Response

200 OK if the price has been created and the created Price object in the response body.

updateimagegroups

This operation updates the imagegroups of a productmaster.

Request

PUT /vX.X/productmasters/{productmastercode}/imagegroups

Parameters

Parameter name Value Description
productMasterCode string required - the id of the product master that needs to be updated
scopeId Number required - the scope for which the operation will be done
authorization string required - the bearer token for authorization

Request body

Supply the request body with one or more image groups as shown here on the right.

[
  {
    "id": Number,
    "description": string,
    "images": [
      {
        "id": Number,
        "url": string
      }
    ]
  }
]

Response

200 OK if the image groups have been updated.

updatestatus

This operation updates the status of a productmaster.

Request

PUT /vX.X/productmasters/{productmastercode}/status

Parameters

Parameter name Value Description
productMasterCode string required - the id of the product master that needs to be updated
scopeId Number required - the scope for which the operation will be done
authorization string required - the bearer token for authorization

Request body

Supply the id of the status to which the master needs to be set. The allowed values can be retrieved through /vX.X/productmasterstatuses.

Response

200 OK if the status could be updated.

updateproductvariantavailability

This operation updates the availability of a productvariant on all its sales channels.

Request

PUT /vX.X/saleschannels

Parameters

Parameter name Value Description
sku string required - the sku of the product for which to update the availability
scopeId Number required - the scope for which the operation will be done
isAvailable boolean required - the new availability of the variant
authorization string required - the bearer token for authorization

Request body

No request body for this operation

Response

200 OK if the update has been successful.

Stock

The stock API can be used to query and manipulate stock. The stock API is divided into three logical building blocks.

  1. The first building block is a stock entity. A stock entity is a location that stores stock. For example: a warehouse or a store.
  2. The second building block is a stock channel. A stock channel is a logical grouping of stock entities, for example: the web channel which contains all the warehouses or the stores channel that contains all the stores.
  3. The last building block are the stocks. Stock is stored at a stock entity.

Schematic overview of the stock api Shematic technical overview

The stock api is divided into two parts: the read api and the write api. To retrieve stock data you use the GET operations from the stock read swagger documentation. To update stock data you use the POST operation from the stock write swagger documentation.

Representations

StockEntity

Representation of a StockEntity object. This object represents a warehouse for example.

  {
    "stockEntityId": string,
    "stockEntityDescription": string
  }
Property name Value Description Example
stockEntityId string the id of the stock entity warehouseAmsterdam
stockEntityDescription string the description of the stock entity the default warehouse for online orders

StockChannel

Representation of a StockChannel object. This object groups a set of stock entities for a specific sales channel.

  {
    "stockChannelId": string,
    "stockEntities": [
      StockEntity
    ]
  }
Property name Value Description Example
stockChannelId string the id of the stock channel onlineStock
stockEntities list of StockEntity resource the stock entities that can be used for this stock channel see StockEntity for examples

StockEntry

Representation of a StockEntry object

{
  "sku": string,
  "stockEntityId": string,
  "amount": Number
}
Property name Value Description Example
sku string the sku belonging to this stock entry B2060100883
stockEntityId string id of the stock entity warehouseAmsterdam
amount Number the amount of the sku in stock in this stock entity 14

StockChannelEntry

Representation of a StockChannelEntry object

{
  "stockChannelId": string,
  "stocks": [
      Stocks
    ]
}
Property name Value Description Example
stockChannelId string the id of the stock channel warehouse1
stocks string the list of stocks see Stocks for examples

Stocks

Representation of a Stocks object

{
  "stockEntityId": string,
  "amount": int,
  "modified": string
  
}
Property name Value Description Example
stockEntityId string the id of the stock entity warehouse1
amount string the amount of stock 56
modified string the date the record was modified “2019-01-04T12:09:04.3476494”

SkuStock

Representation of a SkuStock object

{
  "sku": string,
  "stockEntityId": string,
  "amount": int
  
}
Property name Value Description Example
sku string the sku belonging to this stock entry B2060100883
stockEntityId string id of the stock entity warehouseAmsterdam
amount int the amount of stock 56

get

Request

GET /vX.X/stock/channels/{channel}

Parameters

Property name Value Description Example
channel string required - the id of the stock channel onlineStock
sku string required - the sku of the product B2060100883
scopeId Number required - the scope for which the operation will be done -
authorization string required - the bearer token for authorization -

Request body

No request body for this operation

Response

{
   "stockChannelId":"onlineStock",
   "stocks":[
      {
         "label":"Warehouse",
         "value":130,
         "modified":"2018-08-03T15:09:04.3476494"
      }
   ]
}

If successful the operation returns a StockChannelEntry resource. On the right an example response for the given request properties.

getmultiplestocks

Request

GET /vX.X/stock/channels/{channel}/multi

Parameters

Property name Value Description Example
channel string required - the id of the stock channel onlineStock
skus string required - the skus of products for which you want to retrieve the stock B2060100883, B2060100886
scopeId Number required - the scope for which the operation will be done -
authorization string required - the bearer token for authorization -

Request body

No request body for this operation

Response

{
   "1":{
      "stockChannelId":"onlineStock",
      "stocks":[
         {
            "label":"Warehouse",
            "value":130,
            "modified":"2018-08-03T15:09:04.3476494"
         }
      ]
   },
   "2":{
      "stockChannelId":"onlineStock",
      "stocks":[
         {
            "label":"Warehouse",
            "value":10,
            "modified":"2018-08-03T15:09:04.3476494"
         }
      ]
   }
}

If successful the operation returns a list of StockChannelEntry resources for every sku parameter. On the right an example response for the given request properties.

getchannel

Request

GET /vX.X/stockchannel

Parameters

Property name Value Description Example
authorization string required - the bearer token for authorization -

Request body

No request body for this operation

Response

If successful the operation returns a resultset as shown on the right

[
  {
    "stockChannelId": "Web",
    "stockEntities": [
      {
        "stockEntityId": "Warehouse",
        "stockEntityDescription": "The warehouse"
      }
    ]
  },
  {
    "stockChannelId": "Store",
    "stockEntities": [
      {
        "stockEntityId": "Store1",
        "stockEntityDescription": "The Amsterdam store"
      },
      {
        "stockEntityId": "Store2",
        "stockEntityDescription": "The Rotterdam store"
      }
    ]
  }
]

getentity

Request

GET /vX.X/stockentity

Parameters

Property name Value Description Example
authorization string required - the bearer token for authorization -

Request body

No request body for this operation

Response

If successful the operation returns a list of StockEntity resources as shown on the right.

[
  {
    "stockEntityId": "Warehouse",
    "stockEntityDescription": "The warehouse"
  },
  {
    "stockEntityId": "Store1",
    "stockEntityDescription": "The Amsterdam store"
  },
  {
    "stockEntityId": "Store2",
    "stockEntityDescription": "The Rotterdam store"
  }
]

getstockbychannel

Request

GET /vX.X/stockChannel/{channel}/stock

Parameters

Property name Value Description Example
channel string required - the id of the stock channel onlineStock
offset Number number of elements that where skipped
limit Number page size or maximum number of elements in the result set
withTotal string required - the total amount of objects matching the query
filter string optional - a value to filter on. Could be part of the name or ordernumber
scopeId Number required - the scope for which the order will be created
authorization string required - the bearer token for authorization -

Request body

No request body for this operation

Response

If successful the operation returns a PagedQueryResult with a List SkuStock in the resultset.

{
  "offset": 0,
  "limit": 2,
  "count": 2,
  "total": 26494,
  "results": [
    {
      "sku": "1",
      "stockEntityId": "Warehouse",
      "amount": 130
    },
    {
      "sku": "1000000",
      "stockEntityId": "Warehouse",
      "amount": 54
    }
  ]
}

reset

Request

POST /vX.X/stocks/reset

Parameters

Property name Value Description Example
sku string required - the sku of the product B2060100886
authorization string required - the bearer token for authorization -

Request body

Example 1:
Value of stock record: 20
Quantity in request body: 10
Value of stock record after call: 10

Example 2:
Value of stock record: 20
Quantity in request body: -10
Value of stock record after call: -10

The request body should contain the object on the right. This call resets the current value of the stock to the value specified in the body. This call does not take the old value of the stock record into account.

  {
    "quantity": int,
    "stockEntityId": string
  }

Response

200 OK if the reset is successful

update

Request

POST /vX.X/stocks/update

Parameters

Property name Value Description Example
sku string required - the sku of the product B2060100886
authorization string required - the bearer token for authorization -

Request body

The request body should contain the object on the right. This call adds the value in the body to the current stock record. See the examples below on how to use this call.

Example 1:
Value of stock record: 20
Quantity in request body: 10
Value of stock record after call: 30

Example 2:
Value of stock record: 20
Quantity in request body: -10
Value of stock record after call: 10

  {
    "quantity": int,
    "stockEntityId": string
  }

Response

200 OK if the update is successful

Shipping labels

The shipping API is used to request shipping labels for parcels. Currently three carriers are fully supported: DHL 4 you, DHL Parcel and PostNL. More carriers will be added in the future. The carriers on the backlog are:

  1. DPD
  2. DHL Express
  3. DHL Deutschland
  4. Fedex
  5. UPS
  6. Bpost
  7. van Spreul

Most carriers have a 3 step process regarding shipping labels.

  1. Print the shipping label.
  2. Sent a prenotification to the carrier so the carrier knows a package is ready for shipment.
  3. Get status updates for the parcels sent. (parcel at distribution hub, parcel received by receiver, etc)

Representations

The shipping labels returned are PDF files which can be printed out with a printer. The PDF files are represented as base64 encoded strings. The fields returned fields are fixed and can not by choosen by the requester.

The API is split up per Vendor. All vendors have their own pecularities regarding data so the DTO’s per vendor may differ. Per request method the request body, parameters and response object are described in the swagger documentation.

PostNL

PostNLLabelDTO

{
    "barcode": string,
    "label": string,
    "labelType": string
}
Property name Value Description
barcode String The unique barcode for the label
label String The label in base64 format
labelType String The label type

PostNLAddressDTO

{
    "area": string,
    "buildingName": string,
    "city": string,
    "companyName": string,
    "countryCode": string
    "department": string,
    "doorCode": string,
    "houseNr": string,
    "houseNrExt": string,
    "lastName": string,
    "region": string,
    "street": string,
    "streetHouseNrExt": string,
    "zipCode": string
}
Property name Value Description Example
area String Optional The area Beukenhorst
buildingName String Optional The building name AA
city String The City Amsterdam
companyName String The Company name Wolfpack
countryCode String The ISO2 country codes NL
department String Optional The specific department of a company IT
doorCode String Optional Door code 123
firstName String The receivers firstname Ron
floor String Optional The specific floor for a company 4
houseNr String The housenumber 4
houseNrExt String Optional House number extension A
lastName String The receivers last name de Ridder
region String Optional The region Noord-Holland
street String The street Asterweg
streetHouseNrExt String Optional Combination of Street, HouseNr and HouseNrExt.
The field StreetHouseNrExt is only usable for locations in NL, BE and DE.
Asterweg 9B
zipCode String Zipcode of the address. Mandatory for shipments to Benelux.
Max length (NL) 6 characters, (BE;LU) 4 numeric characters.
1031HL

PostNLNotificationDTO

{
    "email": string,
    "phoneNumber": string
}
Property name Value Description Example
email String The notification receivers email info@wolfpack-dcs.com
phoneNumber String The notification receivers phoneNumber 0612345678

PickupLocationDTO

{
        "locationCode": string,
        "name": string,
        "phoneNumber": string,
        "latitude": float,
        "longitude": float,
        "address": AddressDTO,
        "openingHours": OpeningHoursDTO,
        "deliveryOptions": [
            string
        ]
}
Property name Value Description Example
locationCode String The pickup point location code 176227
name String The name of the pickup point Primera Sanders
phoneNumber String The pickup point’s phoneNumber 023-123456
latitude String The pickup point’s latitude 52.3032951
longitude String The pickup point’s longitude 4.694762
address AddressDTO The pickup point’s address See the AddressDTO description
openingHours OpeningHoursDTO pickup point’s opening hours See the OpeningHoursDTO description
deliveryOptions String The pickup points delivery options DO, PG

AddressDTO

{
        "countryCode": string,
        "zipCode": string,
        "houseNr": string,
        "street": string,
        "city": string,
        "remark": string
}
Property name Value Description Example
countryCode String The ISO2 country code NL
zipCode String The postal code 1031HL
houseNr String The house nr 9
street String The Street Asterweg
city String The city Amsterdam
remark String A remark about the pickup point Dit is een Business Point. Post en pakketten die u op werkdagen vóór de lichtingstijd afgeeft, bezorgen we binnen Nederland de volgende dag.

OpeningHoursDTO

{
        "monday": [
            string
        ],
        "tuesday": [
            string
        ],
        "wednesday": [
            string
        ],
        "thursday": [
            string
        ],
        "friday": [
            string
        ],
        "saturday": [
            string
        ],
        "sunday": [
            string
        ]
}
Property name Value Description Example
monday Array The opening hours on monday 09:00-18:30
tuesday Array The opening hours on tuesday 09:00-18:30
wednesday Array The opening hours on wednesday 09:00-18:30
thursday Array The opening hours on thursday 09:00-21:00
friday Array The opening hours on friday 09:00-18:30
saturday Array The opening hours on saturday 09:00-17:00
sunday Array The opening hours on sunday null

DHL Parcel

SubmitParcelLabelModelResponseDTO

{
    "barcode": string,
    "labelPDF": string
}
Property name Value Description
barcode String The unique barcode for the label
labelPDF String The label in base64 format

DimensionDTO

{
    "weightInGrams": int,
    "lengthInCms": int,
    "widthInCms": int,
    "heightInCms": int,
    "volumeInCm3": int
}

At least on property needs to be set

Property name Value Description Example
weightInGrams Int The weight of the parcel in grams 10
lengthInCms Int The length of the parcel in cm 10
widthInCms Int The width of the parcel in cm 10
heightInCms Int The height of the parcel in cm 10
volumeInCm3 Int The volume of the parcel in cm3 1000

LabelAddressDTO

{
    "name": string,
    "street": string,
    "number": int,
    "numberAddition": string,
    "postCode": string,
    "city": string
}
Property name Value Description Example
name String Name of the receiver Wolfpack
street String The street Asterweg
number String The house number 19
numberAddition String Optional The house number addition B
postCode String The postcode 1031HL
city String The city Amsterdam

ServicePointDTO

{
    "id": string,
    "harmonisedId": string,
    "psfKey": string,
    "shopType": string,
    "name": string,
    "keyword": string,
    "address": ServicePointAddressDTO,
    "geoLocation": GeoLocationDTO,
    "distance": 1024,
    "openingTimes": [
      OpeningTimeDTO
    ]
}
Property name Value Description Example
id String The full service point id 8004-NL-201301
harmonisedId String The harmonised service point id, this id is used for service point labels NL-201301
psfKey String The PSF key NL-201301
shopType String The shop type parcelShop
name String The service point name TelefoonWereld
keyword String The keyword DHL ParcelShop
address ServicePointAddressDTO The service point address See the ServicePointAddressDTO description
geoLocation GeoLocationDTO The lat/long for the service point See the GeoLocationDTO description
distance String The distance to the service point in meters 1024
openingTimes Array The list of opening times See the OpeningTimeDTO description

ServicePointAddressDTO

{
      "countryCode": string,
      "zipCode": string,
      "postalCode": string,
      "city": string,
      "street": string,
      "number": string,
      "isBusiness": boolean
}
Property name Value Description Example
countryCode String The ISO2 country code NL
zipCode String The service point zip code 1031HL
postalCode String The service point postal code 1031HL
city String The service point city Amsterdam
street String The service point street Asterweg
number String The service point number 9
isBusiness Boolean Is this a business service point true

GeoLocationDTO

{
      "latitude": double,
      "longitude": double
}
Property name Value Description Example
latitude Double The latitude 52.3838763
longitude Double The longitude 4.6279324

DHL 4 you

LabelDTO

{
    "labelId": string
    "labelType": string
    "trackerCode": string
    "routingCode": string
    "orderReference": string
    "pdf": string
}
Property name Value Description
labelId String The unique id for the label
labelType String The label type
trackerCode String The track & trace code for the shipment
routingCode String Unique combination of the route and the handler
orderReference String The reference for the order printed on the label
pdf String The label in base64 format

ShipperDTO

{
    "name": NameDTO,
    "address": AddressDTO,
    "email": string,
    "phoneNumber": string,
    "vatNumber": string
  }
Property name Value Description
name String The name of the shipper
address String The address of the shipper
email String The email address for the shipper
phoneNumber String The phone number for the shipper
vatNumber String The vat number for the shipper

NameDTO

{
      "firstName": string,
      "lastName": string,
      "companyName": string,
      "additionalName": string
}
Property name Value Description Example
firstName String The first name Ron
lastName String The last name de Ridder
companyName String Optional The company name Wolfpack
additionalName String Optional Additional name Lucas

AddressDTO

{
      "countryCode": string,
      "postalCode": string,
      "city": string,
      "street": string,
      "number": string,
      "isBusiness": boolean,
      "addition": string
}
Property name Value Description Example
countryCode String The ISO2 country code NL
postalCode String The postal code 1031WL
city String The city Amsterdam
street String The street Asterweg
number String The number 19
isBusiness Boolean Is this a business addres true
addition String The house number addition B

OptionDTO

{
      "key": string
}
Property name Value Description Example
key String The option key, shipping options can be requested from: /vX.X/DHL4YouShippingOptions EXP

ReceiverDTO

{
    "name": NameDTO,
    "address": AddressDTO,
    "email": string,
    "phoneNumber": string
  }
Property name Value Description
name String The name of the receiver
address String The address of the receiver
email String The email address for the receiver
phoneNumber String The phone number for the receiver
{
    "name": NameDTO,
    "address": AddressDTO,
    "email": "string",
    "phoneNumber": "string"
}

PostNLLabels

Create a label for a PostNL shipment

Request

POST /vX.X/PostNLLabels

Parameters

There are no additional parameters to be given

Request Body

Supply a PostNLCreateLabelDTO resource in the request body with at least the following properties.

{
  "productCode": string,
  "printerType": string,
  "weight": int,
  "insuranceAmount": int,
  "pickupPointLocationCode": string,
  "pickupPointCountryCode": string,
  "from": PostNLAddressDTO,
  "to": PostNLAddressDTO,
  "return": PostNLAddressDTO,
  "notification": PostNLNotificationDTO
  }
}
Property name Value Description Example
productCode String The productcode for the service, productcodes can be requested from: /vX.X/PostNLLabels/productCodes 3085
printerType String The printer type for the label, printertypes can be requested from: /vX.X/PostNLLabels/printerTypes Zebra
weight Integer Net weight of goods in gram 2600
insuranceAmount Integer The total insured amount in Euro’s 500
pickupPointLocationCode String Optional The pickup point location code, the location code can be requested from: /vX.X/PostNLLabels/PostNLPickupPoints 176227
pickupPointCountryCode String Optional The pickup point ISO2 country code NL
from PostNLAddressDTO The from address see the PostNLAddressDTO description
to PostNLAddressDTO The to address see the PostNLAddressDTO description
return PostNLAddressDTO The return address see the PostNLAddressDTO description
notification PostNLNotificationDTO The detail to which notifications are sent see the PostNLNotificationDTO description

Response

If successfull this method returns an PostNLLabelDTO resource in the response body

PostNLPickupPoints

Get the pickup point details

Request

GET /vX.X/PostNLPickupPoints

Parameters

Parameter name Value Description Example
countryCode String The ISO2 country code, can only be NL or BE NL
postalCode String The postal code from which to get the nearest pickup points 1031HL
deliveryOptions Array The delivery options for the pickup point, delivery options can be requested from: /vX.X/PostNLPickupPoints/deliveryOptions PG

Request Body

No request body for this operation

Response

If successfull this method returns an PickupLocationDTO resource in the response body

DHLParcelLabel/parcel

Get a shipping label for use with DHL parcel, this label is used to ship to an address directly. There is a separate call for shipments to service points.

Request

POST /vX.X/DHLParcelLabel/parcel

Parameters

There are no additional parameters to be given

Request Body

Supply a SubmitParcelLabelModelDTO resource in the request body with at least the following properties.

{
  "consignorNumber": int,
  "from": LabelAddressDTO,
  "to": LabelAddressDTO,
  "return": LabelAddressDTO,
  "referenceNumber": int,
  "reference": string,
  "deviatingShipperName": string,
  "timeFrameNotificationPerEmail": boolean,
  "mobilePhoneConsignee": string,
  "emailAddressConsignee": string,
  "dimensions": DimensionDTO
  "dpi": int
}
Property name Value Description Example
consignorNumber Int The DHL consignor number used for this shipment 12345678
from LabelAddressDTO The from address from the sender See the LabelAddressDTO description
to LabelAddressDTO The unique barcode for the label See the LabelAddressDTO description
return LabelAddressDTO The label in base64 format See the LabelAddressDTO description
referenceNumber String A reference number for this shipment 123456
reference String The label in base64 format The reference for this shipment, this reference is printed on the label
deviatingShipperName String Afwijkende afzender Wolfpack
timeFrameNotificationPerEmail Boolean Does the receiver want to be notified when the parcel gets shipped ? If timeFrameNotificationPerEmail is true, emailAddress is mandatory. true
mobilePhoneConsignee String The mobile phone number of the receiver 0031622477999
emailAddressConsignee String The email address of the receiver info@wolfpack-dcs.com
dimensions String Optional The Dimensions for the parcel See the DimensionDTO description
dpi int The dots per inch of the returned PDF 72

Response

If successfull this method returns an SubmitParcelLabelModelResponseDTO resource in the response body

DHLParcelLabel/servicepoint

Get a shipping label for use with DHL parcel, this label is used to ship to an address directly. There is a separate call for shipments to service points.

Request

POST /vX.X/DHDHLParcelLabel/servicepoint

Parameters

There are no additional parameters to be given

Request Body

Supply a SubmitServicePointLabelModelDTO resource in the request body with at least the following properties.

{
  "servicePointId": string,
  "consignorNumber": int,
  "from": LabelAddressDTO,
  "to": LabelAddressDTO,
  "return": LabelAddressDTO,
  "referenceNumber": int,
  "reference": string,
  "deviatingShipperName": string,
  "timeFrameNotificationPerEmail": boolean,
  "mobilePhoneConsignee": string,
  "emailAddressConsignee": string,
  "dimensions": DimensionDTO
  "dpi": int
}
Property name Value Description Example
servicePointId String The service point id, service point ids can be requested from: /vX.X/DHLServicePoints/byCity. The harmonisedId needs to be used. NL-201301
consignorNumber Int The DHL consignor number used for this shipment 12345678
from LabelAddressDTO The from address from the sender See the LabelAddressDTO description
to LabelAddressDTO The unique barcode for the label See the LabelAddressDTO description
return LabelAddressDTO The label in base64 format See the LabelAddressDTO description
referenceNumber String A reference number for this shipment 123456
reference String The label in base64 format The reference for this shipment, this reference is printed on the label
deviatingShipperName String Afwijkende afzender Wolfpack
timeFrameNotificationPerEmail Boolean Does the receiver want to be notified when the parcel gets shipped ? If timeFrameNotificationPerEmail is true, emailAddress is mandatory. true
mobilePhoneConsignee String The mobile phone number of the receiver 0031622477999
emailAddressConsignee String The email address of the receiver info@wolfpack-dcs.com
dimensions String Optional The Dimensions for the parcel See the DimensionDTO description
dpi int The dots per inch of the returned PDF 72

Response

If successfull this method returns an SubmitParcelLabelModelResponseDTO resource in the response body

DHLServicePoints/byCity

Get a shipping label for use with DHL parcel, this label is used to ship to an address directly. There is a separate call for shipments to service points.

Request

GET /vX.X/DHLServicePoints/byCity

Parameters

Parameter name Value Description Example
countryCode String The ISO2 country code NL
city String The city for which to get the nearest pickup points Amsterdam

Request Body

No request body for this operation

Response

If successfull this method returns a list of ServicePointDTO resource in the response body

DHL4YouLabels

Create a label for a PostNL shipment

Request

POST /vX.X/DHL4YouLabels/{parcelType}

Parameters

There are no additional parameters to be given

Request Body

Supply a CreateLabelDTO resource in the request body with at least the following properties.

{
  "orderReference": string,
  "receiver": ReceiverDTO,
  "shipper": ShipperDTO,
  "options": [
    OptionDTO
  ],
  "returnLabel": boolean,
  "pieceNumber": int,
  "quantity": int
}
Property name Value Description Example
orderReference String The order reference ref-123aa
receiver ReceiverDTO The parcel receiver See the ReceiverDTO description
shipper ShipperDTO The parcel shipper See the ShipperDTO description
options Array The shipping options See the OptionDTO description
returnLabel Boolean Is a return label needed ? true
pieceNumber Int The number of pieces in the shipment, used for multi collo 1
quantity Int The parcel quantity, used for multi collo 1

Response

If successfull this method returns an LabelDTO resource in the response body