Orders

Use the Orders API to create, retrieve, update, and cancel orders. An order includes order lines, shipping details, documents, and optional metadata. This page describes the models and endpoints to manage the order lifecycle.

Guide: Quick Ship Orders (Sandbox)

UI only – not API

This is a UI guide, not an API flow. Read: Quick Ship Orders (Sandbox).

The order model

Properties

  • Name
    id
    Type
    string
    Readonly
    readonly
    Description
  • Name
    reference
    Type
    string
    Readonly
    readonly
    Description
  • Name
    external_id
    Type
    string
    Description
    A unique identifier for the order, usually coming from the webshop.
  • Name
    external_reference
    Type
    string
    Description
  • Name
    customer
    Type
    uuid
    Description
  • Name
    po_number
    Type
    string
    Description
    If provided, this is printed on the pickup label instead of external_reference.
  • Name
    order_lines
    Type
    array of order lines
    Description
  • Name
    documents
    Type
    array of documents
    Description
  • Name
    requested_delivery_date
    Type
    date
    Description
  • Name
    status
    Type
    string
    Readonly
    readonly
    Description
    Possible statuses: planned | plannable | invalid_address | backorder | cancelled | created | on_hold | partially_shipped | processing | shipped | problem | awaiting_documents | restock | shipment_waiting_for_ewh | invalid
  • Name
    partial_delivery
    Type
    string
    Readonly
    readonly
    Description
  • Name
    business_to_business
    Type
    boolean
    Readonly
    readonly
    Description
  • Name
    shipping_method
    Type
    ShippingMethod
    Description
  • Name
    shipping_email
    Type
    string
    Description
  • Name
    shipping_address
    Type
    ShippingAddress
    Description

Compliance details

  • Name
    incoterms
    Type
    string
    Description
    Options: DAP | DDP
  • Name
    ioss_number
    Type
    string
    Description
    IOSS (Import One-Stop Shop) number of the sender
  • Name
    eori_number
    Type
    string
    Description
    EORI number of the sender
  • Name
    vat_number
    Type
    string
    Description
    VAT number of the sender
  • Name
    inbound_vat_number
    Type
    string
    Description
    GB VAT number — needed for shipments from Europe to GB
  • Name
    inbound_eori_number
    Type
    string
    Description
    GB EORI number — needed for shipments from Europe to GB

Financials

  • Name
    order_amount
    Type
    integer
    Description
    Value of order in cents
  • Name
    assured_amount
    Type
    integer
    Description
  • Name
    currency
    Type
    string
    Description

Notes and language

  • Name
    note
    Type
    string
    Description
  • Name
    customer_note
    Type
    string
    Description
  • Name
    language
    Type
    string
    Description

Meta data

  • Name
    meta_data
    Type
    array
    Description
    An object of key-value pairs. Keys must be lowercase; use _ or - as separators. Empty values are filtered out. See The meta data model below for expand behavior and merging rules.

The order line model

Properties

  • Name
    variant
    Type
    Variant
    Description

    The resolved variant object (matched from the article_code provided in the request)

  • Name
    quantity
    Type
    integer
    Description
  • Name
    processed
    Type
    integer
    Description
  • Name
    packing_slip
    Type
    integer
    Description
  • Name
    meta_data
    Type
    array
    Description

    An object of key-value pairs. Keys must be lowercase; use _ or - as separators. Retrieve all available metadata that are associated with this order line. Metadata is a valuable tool for making your order management more flexible and insightful. Metadata allows you to customize your order data to suit your unique business requirements.

The shipping address model

Properties

  • Name
    addressed_to
    Type
    string
    Description
    Max Length
    Limited to 100 characters
  • Name
    contact_person
    Type
    string
    Description
    Max Length
    Limited to 100 characters
  • Name
    street
    Type
    string
    Description
    Max Length
    Limited to 100 characters
  • Name
    street2
    Type
    string
    Description
    Max Length
    Limited to 100 characters
  • Name
    street_number
    Type
    string
    Description
    Max Length
    Limited to 10 characters
  • Name
    street_number_addition
    Type
    string
    Description
    Max Length
    Limited to 10 characters
  • Name
    zipcode
    Type
    string
    Description
  • Name
    city
    Type
    string
    Description
    Max Length
    Limited to 100 characters
  • Name
    country
    Type
    string
    Description
  • Name
    state
    Type
    string
    Description
    Max Length
    Limited to 100 characters
  • Name
    phone_number
    Type
    string
    Description
  • Name
    mobile_number
    Type
    string
    Description
  • Name
    fax_number
    Type
    string
    Description
  • Name
    email_address
    Type
    string
    Description

The document model

Properties

  • Name
    file
    Type
    string
    Description

    A base64 encoded string of the document.

  • Name
    title
    Type
    string
    Description
  • Name
    mime_type
    Type
    string
    Readonly
    readonly
    Description
  • Name
    quantity
    Type
    integer
    Description

    Amount of times it will be printed

  • Name
    is_shipping_label
    Type
    boolean
    Description
  • Name
    order_price
    Type
    integer
    Description

The meta data model

Meta data is available for both order and order lines. Make sure you add 'meta_data' within the expand header

Expanding responses

New to the Expand header? See how it works, available groups, and request examples: Expanding responses.

Metadata keys

Keys must be lowercase; use _ or - as separators.

Merging order lines

We will throw an error when identical order lines are being merged and each line consists of meta_data

Properties

  • Name
    {key: value}
    Type
    object
    Description

    An object of key-value pairs.

Example

GET
/wms/orders/
[
    {
        "meta_data": {
            "external_order_id": "5502369235240",
            "foo": "dev"
        }
    }
]
GET/wms/orders/

List all orders

Retrieves a collection of orders

Optional attributes

  • Name
    reference
    Type
    string
    Description

    Search for a specific reference.

  • Name
    external_reference
    Type
    string
    Description

    Search for a specific external reference.

  • Name
    external_id
    Type
    string
    Description

    Search for a specific external id.

  • Name
    status
    Type
    string
    Description

    Search for a specific status.

  • Name
    is_business_to_business
    Type
    boolean
    Description
  • Name
    requested_delivery_date_gte
    Type
    string
    Description

    Accepts date format Y-m-d. IE: 2022-10-22

  • Name
    limit
    Type
    integer
    Description
    Limits the amount of results.
  • Name
    page
    Type
    integer
    Description
    Only works in combination with the limit attribute.
  • Name
    from
    Type
    date
    Description
    Accepts date format %Y-%m-%d. IE: 2022-10-22
  • Name
    to
    Type
    date
    Description
    Accepts date format %Y-%m-%d. IE: 2022-10-22
  • Name
    direction
    Type
    string
    Description
    Sort direction. Options: asc | desc
    Default
    Default: desc
  • Name
    sort
    Type
    string
    Description
    You can sort on the following fields:
    • createdAt
    • status
    • modifiedAt
    • requestedDeliveryDate
    Default
    Default: createdAt

Request

GET
/wms/orders/
curl https://eu-dev.middleware.ewarehousing-solutions.com/wms/orders/

Response

[
{
    "id": "f9c392ac-6335-4828-85e2-fae7f82ff636",
    "created_at": "2021-11-12T14:05:43+00:00",
    "requested_delivery_date": "2018-11-19T00:00:00+00:00",
    "customer": "be62c27e-2aac-4ac1-902e-f770d64f8dce",
    "external_reference": "1636725940",
    "po_number": "841612",
    "reference": "ORD00000000001",
    "status": "backorder",
    "business_to_business": true,
    "applied_business_rules": false,
    "partial_delivery": false,
    "language": null,
    "note": "Testorder",
    "customer_note": "Pleaserushthisorder",
    "order_amount": null,
    "assured_amount": null,
    "inco_terms": null,
    "shipping_method": null,
    "currency": null
}
]
GET/wms/orders/:id/

Retrieve an order

Retrieve a single order.

Request

GET
/wms/orders/:id/
curl https://eu-dev.middleware.ewarehousing-solutions.com/wms/orders/e710389a-5505-49d4-9b99-8314f3543427

Response

{
    "id": "c9165f93-8301-4aaa-9f64-27f191c0c778",
    "created_at": "2022-02-11T09:32:12+00:00",
    "customer": "be62c27e-2aac-4ac1-902e-f770d64f8dce",
    "external_reference": "1644571933",
    "po_number": "841612",
    "reference": "ORD00000003029",
    "status": "created",
    "business_to_business": true,
    "applied_business_rules": null,
    "partial_delivery": false,
    "language": null,
    "note": "Testorder",
    "customer_note": "Pleaserushthisorder",
    "shipping_method": null,
    "shipping_address": {
        "addressed_to": "eWarehousing Solutions",
        "contact_person": null,
        "street": "Nijverheidsweg",
        "street2": null,
        "street_number": "27",
        "street_number_addition": null,
        "zipcode": "3331MB",
        "city": "Zwijndrecht",
        "country": "NL",
        "state": "ZH",
        "phone_number": "0102202863",
        "mobile_number": null,
        "fax_number": null,
        "email_address": null
    },
    "order_lines": [
        {
            "variant": {
                "id": "87557e7a-4f4d-44eb-bbf1-c9d83df90099",
                "article_code": "default_variant_b_id",
                "name": "default_variant_b_id",
                "description": null,
                "ean": "default_variant_b_id",
                "sku": "default_variant_b_id",
                "hs_tariff_code": null,
                "height": null,
                "depth": null,
                "width": null,
                "weight": null,
                "expirable": false,
                "country_of_origin": null,
                "using_serial_numbers": false,
                "value": 0
            },
            "quantity": 7,
            "description": "Voorbeeldproduct-B"
        },
        {
            "variant": {
                "id": "1e19da60-4d2b-4c15-8f4e-8978f6113c00",
                "article_code": "default_variant_a_id",
                "name": "default_variant_a_id",
                "description": null,
                "ean": "default_variant_a_id",
                "sku": "default_variant_a_id",
                "hs_tariff_code": null,
                "height": null,
                "depth": null,
                "width": null,
                "weight": null,
                "expirable": false,
                "country_of_origin": null,
                "using_serial_numbers": false,
                "value": 0
            },
            "quantity": 15,
            "description": "Voorbeeldproduct-A"
        }
    ]
}
POST/wms/orders/

Create an order

This endpoint allows you to add a new order

Required attributes

  • Name
    customer
    Type
    uuid
    Description
  • Name
    order_lines
    Type
    array of order lines
    Description
  • Name
    requested_delivery_date
    Type
    date
    Description
  • Name
    external_reference
    Type
    string
    Description
  • Name
    shipping_method
    Type
    uuid
    Description
  • Name
    shipping_address
    Type
    ShippingAddress
    Description

Order line attributes (request)

  • Name
    article_code
    Type
    string
    Description

    Universal identifier that matches against variant article_code, EAN, or SKU to identify the variant. The API will resolve this to a variant object in the response.

  • Name
    quantity
    Type
    integer
    Description
  • Name
    description
    Type
    string
    Description
  • Name
    meta_data
    Type
    array
    Description

Request vs response

You send article_code in order line requests, but the API returns resolved variant objects in the response. The article_code is used to match and identify the appropriate variant.

Optional attributes

  • Name
    external_id
    Type
    string
    Description

    A unique identifier for the order, usually coming from the webshop.

  • Name
    po_number
    Type
    string
    Description
  • Name
    shipping_email
    Type
    string
    Description
  • Name
    documents
    Type
    array of documents
    Description
  • Name
    ioss_number
    Type
    string
    Description

    IOSS(Import One-Stop Shop) number of the sender

  • Name
    eori_number
    Type
    string
    Description

    EORI number of the sender

  • Name
    vat_number
    Type
    string
    Description

    VAT number of the sender

  • Name
    inbound_vat_number
    Type
    string
    Description

    GB VAT number - needed for shipments from Europe to GB

  • Name
    inbound_eori_number
    Type
    string
    Description

    GB EORI number - needed for shipments from Europe to GB

  • Name
    meta_data
    Type
    array
    Description
  • Name
    language
    Type
    string
    Description
  • Name
    note
    Type
    string
    Description
  • Name
    customer_note
    Type
    string
    Description
  • Name
    order_amount
    Type
    integer
    Description

    Value of order in cents

  • Name
    assured_amount
    Type
    integer
    Description
  • Name
    incoterms
    Type
    string
    Description

    Options: DAP | DDP

  • Name
    currency
    Type
    string
    Description

Request

POST
/wms/orders/
curl -X POST 'https://eu-dev.middleware.ewarehousing-solutions.com/wms/orders/' \
-H 'Content-Type: application/json' \
--data-raw '{
    "external_reference": "1560520952",
    "po_number": "841612",
    "note": "Note for this order",
    "requested_delivery_date": "2018-11-14",
    "order_lines": [
        {
            "quantity": 30,
            "article_code": "VBP_C",
            "description": "Order line A"
        },
        {
            "quantity": 20,
            "article_code": "VBP_B",
            "description": "Order line B"
        }
    ],
    "shipping_address": {
        "city": "Heinenoord",
        "state": null,
        "street": "Nijverheidsweg",
        "country": "NL",
        "street2": null,
        "zipcode": "3274 KJ",
        "fax_number": null,
        "addressed_to": "John",
        "phone_number": "+31 (0)18 – 66 12 267",
        "mobile_number": null,
        "street_number": 27,
        "street_number_addition": null
    }
}'

Response

{
    "id": "8faf6cd6-28e7-4e44-a258-4e927d8e680c",
    "created_at": "2023-05-01T13:25:42+00:00",
    "requested_delivery_date": "2018-11-14T00:00:00+00:00",
    "customer": "7239a373-ac8c-4c9e-9b78-994ace312227",
    "external_reference": "1560520952",
    "po_number": "841612",
    "external_id": null,
    "reference": "ORD00000005939",
    "status": "created",
    "business_to_business": false,
    "applied_business_rules": false,
    "partial_delivery": false,
    "language": null,
    "note": "Note for this order",
    "customer_note": null,
    "order_amount": null,
    "assured_amount": null,
    "inco_terms": null,
    "shipping_method": "a299249a-b2cd-4666-a6e5-77d3e1156a22",
    "currency": null
}
PATCH/wms/orders/:id/

Update an order

This endpoint allows you to perform an update on an order.

Updating lines overwrites

Updating the order_lines will delete the previous order lines.

Order line attributes (request)

When updating order lines, use the same format as creating orders:

  • Name
    article_code
    Type
    string
    Description

    Universal identifier that matches against variant article_code, EAN, or SKU to identify the variant.

  • Name
    quantity
    Type
    integer
    Description
  • Name
    description
    Type
    string
    Description
  • Name
    meta_data
    Type
    array
    Description

Optional attributes

  • Name
    order_lines
    Type
    array of order lines
    Description
  • Name
    shipping_email
    Type
    string
    Description
  • Name
    requested_delivery_date
    Type
    date
    Description
  • Name
    shipping_method
    Type
    ShippingMethod
    Description
  • Name
    shipping_address
    Type
    ShippingAddress
    Description
  • Name
    documents
    Type
    array of documents
    Description
  • Name
    meta_data
    Type
    array
    Description
  • Name
    language
    Type
    string
    Description
  • Name
    note
    Type
    string
    Description
  • Name
    customer_note
    Type
    string
    Description
  • Name
    order_amount
    Type
    integer
    Description

    Value of order in cents

  • Name
    assured_amount
    Type
    integer
    Description
  • Name
    incoterms
    Type
    string
    Description

    Options: DAP | DDP

  • Name
    currency
    Type
    string
    Description

Request

PATCH
/wms/orders/:id/
curl -X PATCH https://eu-dev.middleware.ewarehousing-solutions.com/wms/orders/774bf6ee-90cf-11e9-b36d-0242ac120005/ \
--data-raw '{
"note": "updated order --123---",
"order_lines": [
    {
        "article_code": "papier123",
        "description": "updated all orderlines, only this is the required item",
        "quantity": 1337
    }
]
}'

Response

{
    "id": "4fdb3055-4b1d-4352-96d5-2a89f9f50680",
    "customer": "be62c27e-2aac-4ac1-902e-f770d64f8dce",
    "created_at": "2022-10-27T13:14:45+00:00",
    "reference": "INB00000000272",
    "external_reference": "PO-1569",
    "po_number": "841612",
    "status": "announced",
    "order_date": "2022-12-30T00:00:00+00:00",
    "note": "Update Note",
    "order_lines": [
        {
            "variant": {
                "id": "5060691c-2812-48e2-bd07-82ff3fd19382"
            },
            "quantity": 30,
            "processed": null,
            "packing_slip": 30
        },
        {
            "variant": {
                "id": "b04f5233-9980-4307-bb20-bc7460b49933"
            },
            "quantity": 20,
            "processed": null,
            "packing_slip": 20
        }
    ]
}
PATCH/wms/orders/:id/cancel/

Cancel an order

This endpoint allows you to perform cancel an order.

The order can only be canceled while the order's status is one of:

  • created
  • planned
  • invalid_address
  • backorder
  • on_hold
  • restock
  • planned
  • processing
  • invalid

Request

PATCH
/wms/orders/:id/cancel/
curl -X PATCH https://eu-dev.middleware.ewarehousing-solutions.com/wms/orders/774bf6ee-90cf-11e9-b36d-0242ac120005/cancel/
GET/wms/orders/:id/documents/

List all order documents

List all order documents.

Also see

Use the generic Documents resource to retrieve documents by ID.

Request

GET
/wms/orders/:id/documents/
curl https://eu-dev.middleware.ewarehousing-solutions.com/wms/orders/184c47d4-d3ee-4412-b156-ce5a4518d641/documents/

Response

[
    {
        "id": "8067cdfb-cb22-4490-902d-a9863f38f76f",
        "title": "customs_file_en.pdf",
        "mime_type": "application/pdf",
        "created_at": "2022-10-27T14:16:57+00:00",
        "quantity": 1,
        "url": "https://storage.googleapis.com/storage/documents/order/1e57a747-46e4-4c4f-89d9-80b82e7c9f27/64c7c9d35a13b.pdf?GoogleAccessId=test-780%40wms-development-355515.iam.gserviceaccount.com&Expires=1690818531&Signature=aB30S0PfR3Qf2TtFAAt8AxHUCt%2FXfUXaQoYl7F3y%2BPVrG70O3FkYpomAKhs0dYMG%2FCBylveCw3FtqJImbvcKhOn7gvAMa4zPLKywvXYpjmuxnTqvwz2ZSe%2BfS6BL%2B9Bwy4ayZgEmxA7c6L3MkjPilhP%2BR0P61YPZRuhYMBeOlFbjiTNK6HzIXw6tT6vkx%2BkKss4%2BOctV%2BnaN%2FYn93f4LVUrnHyXSgI1nYVp7jondrg26%2FvACgKZdBj6fVJSXTtvoj%2FQYhc6tFrKAdG9dkCB2lcjiZSiYxdeI4r5D6jZ8pYC5f6ZXRDKXnJrq9SHzD3Td%2FR2ojEen%2FqbAJheG3sNVBg%3D%3D",
        "is_shipping_label": false,
        "order_price": null
    },
    {
        "id": "af7c1fe6-d669-414e-b066-e9733f0de7a8",
        "title": "customs_file_nl.pdf",
        "mime_type": "application/pdf",
        "created_at": "2022-10-27T14:16:58+00:00",
        "quantity": 1,
        "url": "https://storage.googleapis.com/storage/documents/order/1e57a747-46e4-4c4f-89d9-80b82e7c9f27/64c7c9d35a13b.pdf?GoogleAccessId=test-780%40wms-development-355515.iam.gserviceaccount.com&Expires=1690818531&Signature=aB30S0PfR3Qf2TtFAAt8AxHUCt%2FXfUXaQoYl7F3y%2BPVrG70O3FkYpomAKhs0dYMG%2FCBylveCw3FtqJImbvcKhOn7gvAMa4zPLKywvXYpjmuxnTqvwz2ZSe%2BfS6BL%2B9Bwy4ayZgEmxA7c6L3MkjPilhP%2BR0P61YPZRuhYMBeOlFbjiTNK6HzIXw6tT6vkx%2BkKss4%2BOctV%2BnaN%2FYn93f4LVUrnHyXSgI1nYVp7jondrg26%2FvACgKZdBj6fVJSXTtvoj%2FQYhc6tFrKAdG9dkCB2lcjiZSiYxdeI4r5D6jZ8pYC5f6ZXRDKXnJrq9SHzD3Td%2FR2ojEen%2FqbAJheG3sNVBg%3D%3D",
        "is_shipping_label": false,
        "order_price": null
    }
]
GET/wms/orders/:id/documents/:documentId/

Retrieve an order document

[deprecated] Use the /wms/documents/:id endpoint instead

Retrieve an order document.

Request

GET
/wms/orders/:id/documents/:documentId/
curl https://eu-dev.middleware.ewarehousing-solutions.com/wms/orders/184c47d4-d3ee-4412-b156-ce5a4518d641/documents/af7c1fe6-d669-414e-b066-e9733f0de7a8/

Response

{
    "id": "8067cdfb-cb22-4490-902d-a9863f38f76f",
    "title": "customs_file.pdf",
    "mime_type": "application/pdf",
    "created_at": "2022-10-27T14:16:57+00:00",
    "quantity": 1,
    "is_shipping_label": false,
    "order_price": null
}
POST/wms/orders/:id/documents/

Add a document to an order

This endpoint allows you to add a document to an existing order.

Request

POST
/wms/orders/:id/documents/
curl -X POST 'https://eu-dev.middleware.ewarehousing-solutions.com/wms/orders/3f2a00b4-ce1d-473b-bacb-e6e12303244b/documents/' \
-H 'Content-Type: application/json' \
--data-raw '{
    "file": "base64 encoded string",
    "title": "my_label",
    "quantity": 1,
    "order_price": 115,
    "shipping_label": false
}'

Response

{
    "id": "8067cdfb-cb22-4490-902d-a9863f38f76f",
    "title": "customs_file.pdf",
    "mime_type": "application/pdf",
    "created_at": "2022-10-27T14:16:57+00:00",
    "quantity": 1,
    "is_shipping_label": false,
    "order_price": null
}