Orders (GET/POST/PATCH)

Besides sending orders to the API, you can also lookup placed orders to check its current status.

• GET api/orders
• PATCH api/orders
• POST api/orders

Parameters

NAME	TYPE	DESCRIPTION
externalOrderNumber	string / array of strings	Mandatory - the ordernumber(s) from your system
itemsPerPage	integer	Optional - allows the restriction of results per page
page	integer	Optional - number of page (useful for paginated responses)
status	string	Optional - allows searching for orders having a specific status

Hint

Please note that externalOrderNumber can only be an array of strings if you want to do a GET-request.

Payload

To place an order, it has to be linked to your account. This can be achieved by adding the field partner with the value v2/api/partners/XX where XX represents the id of your API-account.
The id of your account will be included in the response of create-token.

Static account-id

Since your account-id is static and will never change, the field partner can be "hard-coded" to increase performance.

Besides the partner-id and the usual address-material there are two additional values that are mandatory for each order:

• The sku is necessary to identify the ordered item on our end.
• The netCost are important because we need to import the price, we calculated for you.
  • If you are unable to provide the netCost, you can set it to null (not 0 or 0.0) and our system will add the price automatically.

{
    "partner": "v2/api/partners/17",
    "externalOrderNumber": "ABC::123",
    "externalUserNumber": "TestUser_001",
    "externalProgrammeNumber": "TestProgramme",
    "externalCampaignCode": "Summer Sale '19",
    "externalCatalogueCode": "S_2019",
    "externalCatalogueName": "Summer 2019",
    "recipientCompany": "Example Ltd.",
    "recipientName": "Doe",
    "recipientFirstName": "Jane",
    "recipientStreet": "Some street 1",
    "recipientHouseNumber": "",
    "recipientAnnex": "3rd floor",
    "recipientZip": "12345",
    "recipientCity": "Hometown",
    "recipientCountry": "Germany",
    "recipientEmail": "jane.doe@example.de",
    "recipientPhone": "+49 1234 5678 90",
    "recipientMobilePhone": "+49 132 456 78 90",
    "items": [
        {
            "sku": 3543,
            "externalItemNumber": "3543_Multicutter",
            "quantity": 3,
            "itemName": "Multicutter",
            "netCost": 40.3
        },
        {
            "sku": 5367,
            "externalItemNumber": "5367_Adenogen",
            "quantity": 1,
            "itemName": "Adenogen",
            "netCost": 20.85
        }
    ]
}

Response

The returned response will show the posted order with two additional fields:

• The list trackings will contain links to tracking-resources.
• The field status that will show the current status of an order. Please note that status can only have one of the following values:
  • pending
  • processing
  • shipped
  • complete

{
    "@context": "/v2/api/contexts/Order",
    "@id": "/v2/api/orders",
    "@type": "hydra:Collection",
    "hydra:member": [
        {
            "@id": "/v2/api/orders/22",
            "@type": "Order",
            "id": 22,
            "trackings": [],
            "partner": "/v2/api/partners/17",
            "items": [
                {
                    "@id": "/v2/api/order_items/3",
                    "@type": "OrderItem",
                    "id": 3,
                    "sku": "3543",
                    "quantity": 3,
                    "itemName": "Multicutter",
                    "netCost": 40.3,
                    "order": "/v2/api/orders/22",
                    "externalItemNumber": "3543_Multicutter"
                },
                {
                    "@id": "/v2/api/order_items/4",
                    "@type": "OrderItem",
                    "id": 4,
                    "sku": "5367",
                    "quantity": 1,
                    "itemName": "Adenogen",
                    "netCost": 20.85,
                    "order": "/v2/api/orders/22",
                    "externalItemNumber": "5367_Adenogen"
                }
            ],
            "externalOrderNumber": "ABC::123",
            "externalUserNumber": "TestUser_001",
            "externalProgrammeNumber": "TestProgramme",
            "externalCampaignCode": "Summer Sale '19",
            "externalCatalogueCode": "S_2019",
            "externalCatalogueName": "Summer 2019",
            "recipientCompany": "Example Ltd.",
            "recipientName": "Doe",
            "recipientFirstName": "Jane",
            "recipientStreet": "Some street 1",
            "recipientHouseNumber": "",
            "recipientAnnex": "3rd floor",
            "recipientZip": "12345",
            "recipientCity": "Hometown",
            "recipientCountry": "Germany",
            "recipientEmail": "jane.doe@example.de",
            "recipientPhone": "+49 1234 5678 90",
            "recipientMobilePhone": "+49 132 456 78 90",
            "isExported": true, // deprecated, please use `status` instead
            "status": "processing"
        }
    ],
    "hydra:totalItems": 1,
    "hydra:view": {
        "@id": "/v2/api/orders?externalOrderNumber=ABC%3A%3A123",
        "@type": "hydra:PartialCollectionView"
    },
    "hydra:search": {
        "@type": "hydra:IriTemplate",
        "hydra:template": "/v2/api/orders{?externalOrderNumber,externalOrderNumber[]}",
        "hydra:variableRepresentation": "BasicRepresentation",
        "hydra:mapping": [
            {
                "@type": "IriTemplateMapping",
                "variable": "externalOrderNumber",
                "property": "externalOrderNumber",
                "required": false
            },
            {
                "@type": "IriTemplateMapping",
                "variable": "externalOrderNumber[]",
                "property": "externalOrderNumber",
                "required": false
            }
        ]
    }
}