# Order

The order represents a customer purchase from an external shop system that needs to be fulfilled by the logistics process. The order contains line items of articles with a quantity that need to be shipped to a customer. With this API, you can first create a draft order. The order can be updated as long as it is in draft mode. The fulfillment process starts after the order is approved.

# The order resource

# JSON object

{
  "id": 13032291,
  "customerId": 1000050,
  "status": "draft",
  "statusOutbound": "new",
  "number": "AN011738",
  "numberExternal": null,
  "date": "2024-05-13T12:15:00Z",
  "priority": "normal",
  "tags": [ ],
  "shipping": {
    "mode": "100",
    "dispatchDate": "2024-05-13T13:15:00Z",
    "address": {
      "line1": "Max Mustermann",
      "line2": null,
      "line3": null,
      "street": "Musterstr. 1",
      "zipCode": "1234",
      "city": "Musterstadt",
      "countryCode": "CH",
      "phone": "+41 123 456 789",
      "email": "example@mail.de"
    },
    "routingCode": "H789",
    "options": {
      "DHL_RETNOPRINT": null
    }
  },
  "note": "Please ship ASAP.",
  "attributes": {
    "type": "standard",
    "areaId": "1000176",
    "placeId": "1145048"
  },
  "lineItems": [
    {
      "id": 81740567,
      "status": "new",
      "type": "article",
      "articleId": 71035893,
      "articleNumber": "A1000-BLUE",
      "articleUnit": "ST",
      "quantity": 10,
      "note": null,
      "createdAt": "2024-05-13T12:11:09Z",
      "updatedAt": "2024-05-13T12:11:09Z"
    }
  ],
  "createdAt": "2024-05-13T12:11:09Z",
  "updatedAt": "2024-05-13T12:11:09Z"
}

# Properties

id int32 - read-only
The id of the order to identify the order in the API.
customerId int32 - read-only
The id of the customer the order belongs to.
status string - read-only
The status of the order. Valid values: unknown, error, cancelled, draft, approved, inFulfillment or completed.
statusOutbound string - read-only
The outbound status of the order. Valid values: unknown, error, onHold, cancelled, new, approved, planned, supply, inSupply, outOfStock, partiallyAssigned, assigned, inStaging, staged, packed or shipped.
number string (length <= 50) - required
The unique order number to identify from the shop or third party.
numberExternal string (length <= 50)
The external order number to identify from the shop or third party.
date date (ISO 8601) - required
The order date.
priority string (default: normal)
Value to display the importance of the order. Valid values: low, normal or high.
tags - string[]
Tags can be used to filter and search orders.

Currently only one tag is supported at the moment.

shipping object
The shipping object.
- mode string
  Specify the shipping mode. The exact value is provided by your contact.
- dispatchDate date (ISO 8601)
  The requested dispatch date.
- address object
  The address object.
  - line1 string (length <= 255) - required
    The shipping line 1. Make sure to match the length requirements of the shipping systems.
  - line2 string (length <= 255)
    The shipping line 2. Make sure to match the length requirements of the shipping systems.
  - line3 string (length <= 255)
    The shipping line 3. Make sure to match the length requirements of the shipping systems.
  - street string (length <= 255) - required
    The shipping street with the house number. Make sure to match the length requirements of the shipping systems.
  - zipCode string (length <= 20) - required
    The shipping zip code.
  - city string (length <= 50) - required
    The city. Make sure to match the length requirements of the shipping systems.
  - countryCode string (ISO3166-2) - required
    The country code. E.g.: CH, DE, FR, ...
  - phone string (length <= 25)
    The contact telephone number. This is required by some shipment carriers.
  - email string (length <= 50)
    The contact email. This is required by some shipment carriers.
- routingCode string - read-only
  Some shipping carriers provide routing codes. The value can be used to cluster orders and improve shipping. The routing code is calculated based on the shipping address and mode automatically.
- options object
  The options can be used to provide additional information to the shipping. Values are:
  - DHL_RET null
    Requests an additional return label from DHL. If the chosen carrier system is not DHL this will be ignored. To use this option you need an active configured DHL account and DHL return account.
  - DHL_RETNOPRINT null
    Requests an additional return label from DHL but only keeps the return number. If the chosen carrier system is not DHL this will be ignored. To use this option you need an active configured DHL account and DHL return account.
  - DPD_RET null
    Requests an additional return label from DPD. If the chosen carrier system is not DPD this will be ignored. To use this option you need an active configured DPD account.
  - DPD_RETNOPRINT null
    Requests an additional return label from DPD but only keeps the return number. If the chosen carrier system is not DPD this will be ignored. To use this option you need an active configured DPD account.
  - HERMES_HSS null
    This option prevents the parcel from being left with a neighbor. If the chosen carrier system is not Hermes this will be ignored. To use this option you need an active configured Hermes account.
  - HERMES_PSHDS null
    The option prohibits parcel pick-up from a ParcelShop with power of attorney. If the chosen carrier system is not Hermes this will be ignored. To use this option you need an active configured Hermes account.
note string (length <= 500)
Add additional information to the order that is displayed in the logistic processes. Like instructions, ...
attributes object
The attributes object.
- type string
  This value is provided by your contact. Valid values are: standard, vendor, fbm, fba, b2b or b2c.
- areaId string
  This value is provided by your contact.
- placeId string
  This value is provided by your contact.
lineItems object[]
The line items represents one or more ordered items.
- id int32 - read-only
  The id used to identify the line item in the API.
- status string - read-only
  The status of the line item. Valid values: unknown, error, onHold, cancelled, new, approved, planned, supply, inSupply, outOfStock, partiallyAssigned, assigned, inStaging, staged, packed or shipped
- articleId int32
  The id of the article the line item belongs to.
- articleNumber string - read-only
  The number of the article the line item belongs to.
- articleUnit string - read-only
  The quantity unit of the article the line item belongs to.
- quantity int32
  The quantity of the ordered articles.
- note string (length <= 250)
  Add additional information to the order that is displayed in the logistic processes. Like instructions, ...
- createdAt date (ISO 8601) - read-only
  The date the order was created in logistic.cloud.
- updatedAt date (ISO 8601) - read-only
  The date some data has changed like status, ...
createdAt date (ISO 8601) - read-only
The date the order was created in logistic.cloud.
updatedAt date (ISO 8601) - read-only
The date some data has changed like status, ...

# POST - Create an Order

Requires scope Order.Write

Use this operation to create an order draft. Make sure to specify all required parameters.

curl -X POST \
  'https://{domain}.logistic.cloud/api/{version}/orders' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
        "customerId": 1000050,
        "number": "AN011738",
        "numberExternal": null,
        "date": "2024-05-13T12:15:00Z",
        "priority": "normal",
        "tags": [ ],
        "shipping": {
          "mode": "100",
          "dispatchDate": "2024-05-13T13:15:00Z",
          "address": {
            "line1": "Max Mustermann",
            "line2": null,
            "line3": null,
            "street": "Musterstr. 1",
            "zipCode": "1234",
            "city": "Musterstadt",
            "countryCode": "CH",
            "phone": "+41 123 456 789",
            "email": "example@mail.de"
          },
          "options": {
            "DHL_RETNOPRINT": null
          }
        },
        "note": "Please ship ASAP.",
        "attributes": {
          "type": "standard",
          "areaId": "1000176",
          "placeId": "1145048"
        },
        "lineItems": [
          {
            "type": "article",
            "articleId": 71035893,
            "quantity": 10,
            "note": null
          }
        ]
      }'

Responses

201 - Created The order was created successfully. Returns the created order resource.
400 - Bad Request
Returns a problem details JSON object. More info can be found here.

# Examples

Create an order with the minimum required information. See the Properties section for more details.

curl -X POST \
  'https://{domain}.logistic.cloud/api/{version}/orders' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
        "customerId": 1000050,
        "number": "AN011738",
        "date": "2024-05-13T12:15:00Z",
        "attributes": {
          "type": "standard",
          "areaId": "1000176",
          "placeId": "1145048"
        },
        "lineItems": [
          {
            "type": "article",
            "articleId": 71035893,
            "quantity": 10
          }
        ]
      }'

# GET - Retrieve a list of orders

Requires scope Order.Read or Order.Write

Use this operation to retrieve a list of orders that meet the specified criteria. This endpoint implements pagination. Click here to learn more.

curl -X GET \
  'https://{domain}.logistic.cloud/api/orders' \
  -H 'X-API-KEY: YOUR_API_KEY'

Parameters

ids string
Retrieve only orders specified by a comma-separated list of order ids.
status string
Filter orders by their status. Allowed values are: unknown, error, cancelled, draft, approved, inFulfillment or completed.
statusOutbound string
Filter orders by their outbound status. Allowed values are: unknown, error, onHold, cancelled, new, approved, planned, supply, inSupply, outOfStock, partiallyAssigned, assigned, inStaging, staged, packed or shipped.
number string
Filter orders by their exact number.
numberExternal string
Filter orders by their exact external number.
tags string
Filter orders by tags. Multiple tags should be separated by commas e.g. 'TAG1,TAG2'
priority string
Filter orders by their priority. Allowed values are: low, normal or high.
createdAtMin date (ISO 8601)
Show orders last created after a specific date.
createdAtMax date (ISO 8601)
Show orders last created before a specific date.
updatedAtMin date (ISO 8601)
Show orders last updated after a specific date.
updatedAtMax date (ISO 8601)
Show orders last updated before a specific date.
page int32 (default: 0)
The page number that contains the results. If not specified the first page will be returned.
pageSize int32 (default: 50)
The maximum number of results returned per page. Value must be between 1 and 250.

Responses

200 - OK
Returns a list of order resources.

# Examples

List all orders with the status draft.

curl -X GET \
  'https://{domain}.logistic.cloud/api/{version}/orders?status=draft' \
  -H 'X-API-KEY: YOUR_API_KEY'

curl -X GET \
  'https://{domain}.logistic.cloud/api/{version}/orders?number=AN011738' \
  -H 'X-API-KEY: YOUR_API_KEY'

All dates are handled in UTC. To get the orders you need to pass in the updatedAtMin and updatedAtMax with the correct timezone. The values must also be url encoded. Please be aware that all dates in the results will be returned in UTC.

curl -X GET \
  'https://{domain}.logistic.cloud/api/{version}/orders?updatedAtMin=2024-06-20T12:48:48%2B02:00&updatedAtMax=2024-06-30T23:59:59%2B02:00' \
  -H 'X-API-KEY: YOUR_API_KEY'

# GET - Retrieve a specific order

Requires scope Order.Read or Order.Write

Use this operation to retrieve an order by specifying the id.

curl -X GET \
  'https://{domain}.logistic.cloud/api/{version}/orders/{id}' \
  -H 'X-API-KEY: YOUR_API_KEY'

Parameters

id int32 - required
The order id.

Responses

200 - OK
Returns the specific order resource.
404 - Not Found
The given order id to update hasn't been found.

# PUT - Update an order

Requires scope Order.Write

Use this operation to replace properties of an order and its line items if the order is in status 'draft'. After approving an order the order line items cannot be updated anymore. All properties within the order head can still be updated until the order is completed.

Updating order head when order is not in status 'draft'

To update the order the line item values must be specified as 'null'. If the line items are not 'null' the operation returns a 400 Bad Request.

curl -X PUT \
  'https://{domain}.logistic.cloud/api/{version}/orders/{id}' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
        "customerId": 1000050,
        "number": "AN011738",
        "numberExternal": "EXT011738",
        "date": "2024-05-13T12:15:00Z",
        "priority": "high",
        "tags": [ "PRIME" ],
        "shipping": {
          "mode": "100",
          "dispatchDate": "2024-05-13T13:15:00Z",
          "address": {
            "line1": "Max Mustermann",
            "line2": "c/o Moritz Mustermann",
            "line3": null,
            "street": "Musterstr. 1",
            "zipCode": "1234",
            "city": "Musterstadt",
            "countryCode": "CH",
            "phone": "+41 123 456 789",
            "email": "example@mail.de"
          },
          "options": {
            "DHL_RETNOPRINT": null
          }
        },
        "note": "Please ship ASAP.",
        "attributes": {
          "type": "standard",
          "areaId": "1000176",
          "placeId": "1145048"
        },
        "lineItems": [
          {
            "type": "article",
            "articleId": 71035893,
            "quantity": 15,
            "note": null
          }
        ]
      }'

Parameters

id int32 - required
The order id.

Responses

200 - OK
The order was approved successfully. Returns the updated order.
400 - Bad Request
Returns a problem details JSON object. More info can be found here.
404 - Not Found
The given order id to update hasn't been found.

# Examples

Replace the line items of an order with three new line items.

Make sure to specify any other properties that should not be removed, as the resource will be replaced by your data. See how we recommend updating a resource here.

curl -X PUT \
  'https://{domain}.logistic.cloud/api/{version}/orders/{id}' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
        "customerId": 1000050,
        "number": "AN011738",
        "date": "2024-05-13T12:15:00Z",
        "attributes": {
          "type": "standard",
          "areaId": "1000176",
          "placeId": "1145048"
        },
        "lineItems": [
          {
            "type": "article",
            "articleId": 71035893,
            "quantity": 5500
          },
          {
            "type": "article",
            "articleId": 71035893,
            "quantity": 5500
          }
        ]
      }'

If the order has status approved the line items cannot be updated any more. To update the order address data, the line items must be set to null.

Make sure to specify any other properties that should not be removed, as the resource will be replaced by your data. See how we recommend updating a resource here.

curl -X PUT \
  'https://{domain}.logistic.cloud/api/{version}/orders/{id}' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
        "customerId": 1000050,
        "number": "AN011738",
        "date": "2024-05-13T12:15:00Z",
        "shipping": {
          "address": {
            "line1": "Max Mustermann",
            "line2": null,
            "line3": null,
            "street": "Musterstr. 1",
            "zipCode": "1234",
            "city": "Musterstadt",
            "countryCode": "CH",
            "phone": "+41 123 456 789",
            "email": "example@mail.de"
          }
        },
        "attributes": {
          "type": "standard",
          "areaId": "1000176",
          "placeId": "1145048"
        },
        "lineItems": null
      }'

# POST - Approve an order

Requires scope Order.Write

Use this operation to approve an order. Approving an order marks it as ready to be fulfilled. After approving an order the order line items cannot be updated anymore.

curl -X POST \
  'https://{domain}.logistic.cloud/api/{version}/orders/{id}/approve' \
  -H 'X-API-KEY: YOUR_API_KEY'
  

Parameters

id int32 - required
The order id.

Responses

204 - No Content
The order was approved successfully.
400 - Bad Request
Returns a problem details JSON object. More info can be found here.