# 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.

  • 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.

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.

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.

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.