Trackings/Orders

Our powerful API integration allows you to submit each individual parcel and order, get instant feedback, and have the most flexible data structures.

Create or Update a Tracking/Order

You can create a new tracking and order in the parcelLab system using the v4/track/orders endpoint. This allows you to submit tracking information (that is: courier and tracking_number) for one or multiple parcels with a corresponding order number and can also be used to inform parcelLab to expect tracking information for a specified order.

If submitting the order details before the tracking information, the relevant tracking details that follow should be sent via the v4/track/orders endpoint as well when you receive it.

You can set tags on a tracking that allow you to easily identify custom attributes in filters and exports (for example: tags: ["category:womens fashion", "brand:Parkers", "season:W24", "category:sweater", "material:cashmere"]). For further information, see our data model documentation.

Create or Update Order (recommended)

put

Create or update an order. If the order already exists, it will be updated. Order data does not need to be providedin full with every call. If the order already exists only changed fields or mutation actions (add tracking, cancel tracking, etc.) need to be submitted.This endpoint is idempotent.

Authorizations

OAuth2 AuthenticationHeaderToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

Create a new order record with shipment and recipient data.

accountintegerOptional

Account to which this order belongs

order_numberstring · min: 1 · max: 255Optional

Order number (customer facing)

external_referencestring · max: 255Optional

Retailer reference (e.g. internal system ID) for this order, unique.

client_keystring · max: 512Optional

Name of the technical client / shop (corresponds to the system setup), e.g. 'mybrand-a.com'

destination_country_iso3string · min: 1 · max: 3Optional

Destination country ISO 3166-1 alpha 3 code

language_iso2string · max: 3Optional

ISO 639-1 language code of the recipient, if known, required for localized communication

shipping_addressany ofOptional

or

object · EmptyOptional

delivery_methodstring · max: 255Optional

Delivery method (e.g. 'standard shipping'), needs to be set up in the system

recipient_emailany of · min: 1Optional

Recipient email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead.

string · emailOptional

or

const: _unsetOptionalPossible values:

recipient_namestring · max: 255Optional

Recipient name

customer_numberstring · max: 255Optional

Customer number (e.g. from the retailer)

invoice_numberstring · max: 255Optional

Invoice number (e.g. from the retailer)

payment_methodstring · max: 255Optional

Payment method (e.g. 'credit card')

order_total_amountstring · nullableOptional

Total amount of the order (usually after tax & discount)

Pattern: ^-?\d{0,8}(?:\.\d{0,2})?$

order_tax_amountstring · nullableOptional

Tax amount of the original order

Pattern: ^-?\d{0,8}(?:\.\d{0,2})?$

order_net_amountstring · nullableOptional

Net amount of the order (usually before tax)

Pattern: ^-?\d{0,8}(?:\.\d{0,2})?$

order_discount_amountstring · nullableOptional

Discount amount of the order

Pattern: ^-?\d{0,8}(?:\.\d{0,2})?$

order_currencystring · max: 3Optional

Currency of the order, e.g. USD, EUR (ISO 4217)

order_datestring · nullableOptional

Date and time when the order was placed

channelstring · max: 255Optional

Channel through which the order was placed (e.g. 'webshop')

announced_delivery_datestring · nullableOptional

Announced delivery date

announced_delivery_date_minstring · nullableOptional

Announced delivery date range of order (min)

announced_delivery_date_maxstring · nullableOptional

Announced delivery date range of order (min)

billing_addressany ofOptional

or

object · EmptyOptional

timezonestringOptional

Timezone of the recipient, if known, not required, but strongly recommended

order_statusstring · max: 255Optional

Current status of the order, as setup in the system

has_multiple_shipmentsboolean · nullableOptional

Indicates this order has been split into multiple shipments

cancelled_datestring · nullableOptional

Datetime when the order was cancelled

cancelled_reasonall ofOptional

Reason for cancellation

• customer - Customer
• inventory - Inventory
• payment - Payment-related
• other - Other

string · enumOptional

• customer - Customer
• inventory - Inventory
• payment - Payment-related
• other - Other

Possible values:

tagsstring[]Optional

Tags for the object, format :e.g. 'category:Home Apparel'

Responses

200

No response body

No content

400Error

application/json

403Error

application/json

404Error

application/json

put

/v4/track/orders/

HTTPcURLJavaScriptPython

PUT /v4/track/orders/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 4765

{
  "account": 1,
  "order_number": "text",
  "external_reference": "text",
  "client_key": "text",
  "destination_country_iso3": "text",
  "language_iso2": "text",
  "shipping_address": {
    "first_name": "text",
    "last_name": "text",
    "company_name": "text",
    "address_line": "text",
    "address_line_extra": "text",
    "postal_code": "text",
    "city": "text",
    "country_iso3": "text",
    "region_code": "text",
    "phone": "text"
  },
  "delivery_method": "text",
  "recipient_email": "[email protected]",
  "recipient_name": "text",
  "customer_number": "text",
  "invoice_number": "text",
  "payment_method": "text",
  "order_total_amount": null,
  "order_tax_amount": null,
  "order_net_amount": null,
  "order_discount_amount": null,
  "order_currency": "text",
  "payments": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "order_date": null,
  "channel": "text",
  "announced_delivery_date": null,
  "announced_delivery_date_min": null,
  "announced_delivery_date_max": null,
  "articles_order": [
    {
      "version": "v1",
      "line_item_id": "text",
      "product_id": "text",
      "variant_id": "text",
      "sku": "text",
      "order_item_id": "text",
      "article_name": "text",
      "article_category": "text",
      "article_store_url": "text",
      "article_image_url": "text",
      "article_brand": "text",
      "size": "text",
      "color": "text",
      "width": 1,
      "height": 1,
      "length": 1,
      "length_unit": "cm",
      "weight": 1,
      "weight_unit": "g",
      "unit_price": "text",
      "unit_price_original": "text",
      "quantity": 1,
      "amount_invoiced": "text",
      "tax_amount": "text",
      "harmonized_system_code": "text",
      "origin_country_iso3": "text",
      "is_bulky": false,
      "tags": [
        "text"
      ],
      "additional_attributes": [
        {
          "key": "text",
          "value": null
        }
      ],
      "status": "shipped",
      "shipped_quantity": 1,
      "original_quantity": 1,
      "change_reason": "text",
      "updated_at": "2026-02-14T14:21:45.964Z",
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "billing_address": {
    "first_name": "text",
    "last_name": "text",
    "company_name": "text",
    "address_line": "text",
    "address_line_extra": "text",
    "postal_code": "text",
    "city": "text",
    "country_iso3": "text",
    "region_code": "text",
    "phone": "text"
  },
  "timezone": "text",
  "order_status": "text",
  "has_multiple_shipments": null,
  "cancelled_date": null,
  "cancelled_reason": "customer",
  "additional_attributes": [
    {
      "key": "text",
      "value": null
    }
  ],
  "tags": [
    "text"
  ],
  "mutations": [
    {
      "operation_id": "123e4567-e89b-12d3-a456-426614174000",
      "result": {
        "success": false,
        "message": "",
        "errors": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "type": "add_tracking",
      "tracking": {
        "tracking_number": "text",
        "client_key": "text",
        "courier": "text",
        "external_reference": "text",
        "recipient_postal_code": "text",
        "recipient_phone": "text",
        "destination_country_iso3": "text",
        "language_iso2": "text",
        "timezone": "text",
        "courier_service_level": "text",
        "delivery_method": "text",
        "shipping_address": {
          "first_name": "text",
          "last_name": "text",
          "company_name": "text",
          "address_line": "text",
          "address_line_extra": "text",
          "postal_code": "text",
          "city": "text",
          "country_iso3": "text",
          "region_code": "text",
          "phone": "text"
        },
        "recipient_email": "text",
        "recipient_name": "text",
        "additional_recipients": [
          {
            "role": "text",
            "email": "text"
          }
        ],
        "cancelled_date": "2026-02-14T14:21:45.964Z",
        "is_return": true,
        "identifiers_consignment": "text",
        "delivery_number": "text",
        "invoice_number": "text",
        "shipping_cost_total": "text",
        "shipping_cost_net": "text",
        "shipping_cost_discount": "text",
        "shipping_weight_total": 1,
        "shipping_weight_unit": "g",
        "shipping_volume_total": 1,
        "shipping_volume_unit": "text",
        "shipping_height": 1,
        "shipping_width": 1,
        "shipping_length": 1,
        "shipping_dimensions_unit": "mm",
        "requires_signature": true,
        "is_dropshipment": true,
        "transport_number": "text",
        "origin_country_iso3": "text",
        "origin_region": "text",
        "origin_postal_code": "text",
        "articles": [
          {
            "version": "v1",
            "line_item_id": "text",
            "product_id": "text",
            "variant_id": "text",
            "sku": "text",
            "order_item_id": "text",
            "article_name": "text",
            "article_category": "text",
            "article_store_url": "text",
            "article_image_url": "text",
            "article_brand": "text",
            "size": "text",
            "color": "text",
            "width": 1,
            "height": 1,
            "length": 1,
            "length_unit": "cm",
            "weight": 1,
            "weight_unit": "g",
            "unit_price": "text",
            "unit_price_original": "text",
            "quantity": 1,
            "amount_invoiced": "text",
            "tax_amount": "text",
            "harmonized_system_code": "text",
            "origin_country_iso3": "text",
            "is_bulky": false,
            "tags": [
              "text"
            ],
            "additional_attributes": [
              {
                "key": "text",
                "value": null
              }
            ],
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        ],
        "warehouse": "text",
        "courier_contact_name": "text",
        "courier_contact_phone": "text",
        "courier_contact_email": "text",
        "review_link": "text",
        "status_link": "text",
        "collection_code_retailer": "text",
        "collection_code_carrier": "text",
        "announced_send_date": "2026-02-14",
        "announced_delivery_date": "2026-02-14",
        "announced_delivery_date_min": "2026-02-14",
        "announced_delivery_date_max": "2026-02-14",
        "notifications_inactive": true,
        "flags": [
          "complete"
        ],
        "cash_on_delivery_amount": 1,
        "tags": [
          "text"
        ],
        "checkpoints": [
          {
            "status_code": "text",
            "message": "text",
            "courier": "text",
            "exception": [
              "text"
            ],
            "delivery_location": "text",
            "event_timestamp": "2026-02-14T14:21:45.964Z",
            "courier_status": "text"
          }
        ],
        "additional_fields": null
      }
    }
  ]
}

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

No content

Create a Tracking/Order

You can create trackings and orders in the parcelLab system using the v4/track/orders endpoint.

The same endpoint is used to create and update a tracking and order. For further information, see how to update an order.

When you receive tracking information (that is: courier and tracking_number) for an order, you should send this data to parcelLab using this endpoint to update the record.

Create Order

post

Create a new order, if it does not exist. If the order already exists, this will result in an error. If you need to perform an (idem-potent) create or update, please use this endpoint. This endpoint will validate the payload. If the payload is invalid, it will return a 400 Bad Request.

Authorizations

OAuth2 AuthenticationHeaderToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

Create a new order record with shipment and recipient data.

accountintegerRequired

Account to which this order belongs

order_numberstring · min: 1 · max: 255Required

Order number (customer facing)

external_referencestring · max: 255Optional

Retailer reference (e.g. internal system ID) for this order, unique.

client_keystring · max: 512Optional

Name of the technical client / shop (corresponds to the system setup), e.g. 'mybrand-a.com'

destination_country_iso3string · min: 1 · max: 3Required

Destination country ISO 3166-1 alpha 3 code

language_iso2string · max: 3Optional

ISO 639-1 language code of the recipient, if known, required for localized communication

shipping_addressany ofOptional

or

object · EmptyOptional

delivery_methodstring · max: 255Optional

Delivery method (e.g. 'standard shipping'), needs to be set up in the system

recipient_emailany of · min: 1Required

Recipient email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead.

string · emailOptional

or

const: _unsetOptionalPossible values:

recipient_namestring · max: 255Optional

Recipient name

customer_numberstring · max: 255Optional

Customer number (e.g. from the retailer)

invoice_numberstring · max: 255Optional

Invoice number (e.g. from the retailer)

payment_methodstring · max: 255Optional

Payment method (e.g. 'credit card')

order_total_amountstring · nullableOptional

Total amount of the order (usually after tax & discount)

Pattern: ^-?\d{0,8}(?:\.\d{0,2})?$

order_tax_amountstring · nullableOptional

Tax amount of the original order

Pattern: ^-?\d{0,8}(?:\.\d{0,2})?$

order_net_amountstring · nullableOptional

Net amount of the order (usually before tax)

Pattern: ^-?\d{0,8}(?:\.\d{0,2})?$

order_discount_amountstring · nullableOptional

Discount amount of the order

Pattern: ^-?\d{0,8}(?:\.\d{0,2})?$

order_currencystring · max: 3Optional

Currency of the order, e.g. USD, EUR (ISO 4217)

order_datestring · nullableOptional

Date and time when the order was placed

channelstring · max: 255Optional

Channel through which the order was placed (e.g. 'webshop')

announced_delivery_datestring · nullableOptional

Announced delivery date

announced_delivery_date_minstring · nullableOptional

Announced delivery date range of order (min)

announced_delivery_date_maxstring · nullableOptional

Announced delivery date range of order (min)

billing_addressany ofOptional

or

object · EmptyOptional

timezonestringOptional

Timezone of the recipient, if known, not required, but strongly recommended

order_statusstring · max: 255Optional

Current status of the order, as setup in the system

has_multiple_shipmentsboolean · nullableOptional

Indicates this order has been split into multiple shipments

cancelled_datestring · nullableOptional

Datetime when the order was cancelled

cancelled_reasonall ofOptional

Reason for cancellation

• customer - Customer
• inventory - Inventory
• payment - Payment-related
• other - Other

string · enumOptional

• customer - Customer
• inventory - Inventory
• payment - Payment-related
• other - Other

Possible values:

tagsstring[]Optional

Tags for the object, format :e.g. 'category:Home Apparel'

Responses

201Success

application/json

400Error

application/json

403Error

application/json

404Error

application/json

post

/v4/track/orders/

HTTPcURLJavaScriptPython

POST /v4/track/orders/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 4765

{
  "account": 1,
  "order_number": "text",
  "external_reference": "text",
  "client_key": "text",
  "destination_country_iso3": "text",
  "language_iso2": "text",
  "shipping_address": {
    "first_name": "text",
    "last_name": "text",
    "company_name": "text",
    "address_line": "text",
    "address_line_extra": "text",
    "postal_code": "text",
    "city": "text",
    "country_iso3": "text",
    "region_code": "text",
    "phone": "text"
  },
  "delivery_method": "text",
  "recipient_email": "[email protected]",
  "recipient_name": "text",
  "customer_number": "text",
  "invoice_number": "text",
  "payment_method": "text",
  "order_total_amount": null,
  "order_tax_amount": null,
  "order_net_amount": null,
  "order_discount_amount": null,
  "order_currency": "text",
  "payments": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "order_date": null,
  "channel": "text",
  "announced_delivery_date": null,
  "announced_delivery_date_min": null,
  "announced_delivery_date_max": null,
  "articles_order": [
    {
      "version": "v1",
      "line_item_id": "text",
      "product_id": "text",
      "variant_id": "text",
      "sku": "text",
      "order_item_id": "text",
      "article_name": "text",
      "article_category": "text",
      "article_store_url": "text",
      "article_image_url": "text",
      "article_brand": "text",
      "size": "text",
      "color": "text",
      "width": 1,
      "height": 1,
      "length": 1,
      "length_unit": "cm",
      "weight": 1,
      "weight_unit": "g",
      "unit_price": "text",
      "unit_price_original": "text",
      "quantity": 1,
      "amount_invoiced": "text",
      "tax_amount": "text",
      "harmonized_system_code": "text",
      "origin_country_iso3": "text",
      "is_bulky": false,
      "tags": [
        "text"
      ],
      "additional_attributes": [
        {
          "key": "text",
          "value": null
        }
      ],
      "status": "shipped",
      "shipped_quantity": 1,
      "original_quantity": 1,
      "change_reason": "text",
      "updated_at": "2026-02-14T14:21:45.964Z",
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "billing_address": {
    "first_name": "text",
    "last_name": "text",
    "company_name": "text",
    "address_line": "text",
    "address_line_extra": "text",
    "postal_code": "text",
    "city": "text",
    "country_iso3": "text",
    "region_code": "text",
    "phone": "text"
  },
  "timezone": "text",
  "order_status": "text",
  "has_multiple_shipments": null,
  "cancelled_date": null,
  "cancelled_reason": "customer",
  "additional_attributes": [
    {
      "key": "text",
      "value": null
    }
  ],
  "tags": [
    "text"
  ],
  "mutations": [
    {
      "operation_id": "123e4567-e89b-12d3-a456-426614174000",
      "result": {
        "success": false,
        "message": "",
        "errors": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "type": "add_tracking",
      "tracking": {
        "tracking_number": "text",
        "client_key": "text",
        "courier": "text",
        "external_reference": "text",
        "recipient_postal_code": "text",
        "recipient_phone": "text",
        "destination_country_iso3": "text",
        "language_iso2": "text",
        "timezone": "text",
        "courier_service_level": "text",
        "delivery_method": "text",
        "shipping_address": {
          "first_name": "text",
          "last_name": "text",
          "company_name": "text",
          "address_line": "text",
          "address_line_extra": "text",
          "postal_code": "text",
          "city": "text",
          "country_iso3": "text",
          "region_code": "text",
          "phone": "text"
        },
        "recipient_email": "text",
        "recipient_name": "text",
        "additional_recipients": [
          {
            "role": "text",
            "email": "text"
          }
        ],
        "cancelled_date": "2026-02-14T14:21:45.964Z",
        "is_return": true,
        "identifiers_consignment": "text",
        "delivery_number": "text",
        "invoice_number": "text",
        "shipping_cost_total": "text",
        "shipping_cost_net": "text",
        "shipping_cost_discount": "text",
        "shipping_weight_total": 1,
        "shipping_weight_unit": "g",
        "shipping_volume_total": 1,
        "shipping_volume_unit": "text",
        "shipping_height": 1,
        "shipping_width": 1,
        "shipping_length": 1,
        "shipping_dimensions_unit": "mm",
        "requires_signature": true,
        "is_dropshipment": true,
        "transport_number": "text",
        "origin_country_iso3": "text",
        "origin_region": "text",
        "origin_postal_code": "text",
        "articles": [
          {
            "version": "v1",
            "line_item_id": "text",
            "product_id": "text",
            "variant_id": "text",
            "sku": "text",
            "order_item_id": "text",
            "article_name": "text",
            "article_category": "text",
            "article_store_url": "text",
            "article_image_url": "text",
            "article_brand": "text",
            "size": "text",
            "color": "text",
            "width": 1,
            "height": 1,
            "length": 1,
            "length_unit": "cm",
            "weight": 1,
            "weight_unit": "g",
            "unit_price": "text",
            "unit_price_original": "text",
            "quantity": 1,
            "amount_invoiced": "text",
            "tax_amount": "text",
            "harmonized_system_code": "text",
            "origin_country_iso3": "text",
            "is_bulky": false,
            "tags": [
              "text"
            ],
            "additional_attributes": [
              {
                "key": "text",
                "value": null
              }
            ],
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        ],
        "warehouse": "text",
        "courier_contact_name": "text",
        "courier_contact_phone": "text",
        "courier_contact_email": "text",
        "review_link": "text",
        "status_link": "text",
        "collection_code_retailer": "text",
        "collection_code_carrier": "text",
        "announced_send_date": "2026-02-14",
        "announced_delivery_date": "2026-02-14",
        "announced_delivery_date_min": "2026-02-14",
        "announced_delivery_date_max": "2026-02-14",
        "notifications_inactive": true,
        "flags": [
          "complete"
        ],
        "cash_on_delivery_amount": 1,
        "tags": [
          "text"
        ],
        "checkpoints": [
          {
            "status_code": "text",
            "message": "text",
            "courier": "text",
            "exception": [
              "text"
            ],
            "delivery_location": "text",
            "event_timestamp": "2026-02-14T14:21:45.964Z",
            "courier_status": "text"
          }
        ],
        "additional_fields": null
      }
    }
  ]
}

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

{
  "account": 1,
  "order_number": "text",
  "external_id": "text",
  "external_reference": "text",
  "client_key": "text",
  "destination_country_iso3": "text",
  "language_iso2": "text",
  "shipping_address": {
    "first_name": "text",
    "last_name": "text",
    "company_name": "text",
    "address_line": "text",
    "address_line_extra": "text",
    "postal_code": "text",
    "city": "text",
    "country_iso3": "text",
    "region_code": "text",
    "phone": "text"
  },
  "delivery_method": "text",
  "recipient_email": "[email protected]",
  "recipient_name": "text",
  "customer_number": "text",
  "invoice_number": "text",
  "payment_method": "text",
  "order_total_amount": null,
  "order_tax_amount": null,
  "order_net_amount": null,
  "order_discount_amount": null,
  "order_currency": "text",
  "payments": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "order_date": null,
  "channel": "text",
  "announced_delivery_date": null,
  "announced_delivery_date_min": null,
  "announced_delivery_date_max": null,
  "articles_order": [
    {
      "version": "v1",
      "line_item_id": "text",
      "product_id": "text",
      "variant_id": "text",
      "sku": "text",
      "order_item_id": "text",
      "article_name": "text",
      "article_category": "text",
      "article_store_url": "text",
      "article_image_url": "text",
      "article_brand": "text",
      "size": "text",
      "color": "text",
      "width": 1,
      "height": 1,
      "length": 1,
      "length_unit": "cm",
      "weight": 1,
      "weight_unit": "g",
      "unit_price": "text",
      "unit_price_original": "text",
      "quantity": 1,
      "amount_invoiced": "text",
      "tax_amount": "text",
      "harmonized_system_code": "text",
      "origin_country_iso3": "text",
      "is_bulky": false,
      "tags": [
        "text"
      ],
      "additional_attributes": [
        {
          "key": "text",
          "value": null
        }
      ],
      "status": "shipped",
      "shipped_quantity": 1,
      "original_quantity": 1,
      "change_reason": "text",
      "updated_at": "2026-02-14T14:21:45.964Z",
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "billing_address": {
    "first_name": "text",
    "last_name": "text",
    "company_name": "text",
    "address_line": "text",
    "address_line_extra": "text",
    "postal_code": "text",
    "city": "text",
    "country_iso3": "text",
    "region_code": "text",
    "phone": "text"
  },
  "timezone": "text",
  "order_status": "text",
  "has_multiple_shipments": null,
  "cancelled_date": null,
  "cancelled_reason": "customer",
  "additional_attributes": [
    {
      "key": "text",
      "value": null
    }
  ],
  "tags": [
    "text"
  ],
  "mutations": [
    {
      "operation_id": "123e4567-e89b-12d3-a456-426614174000",
      "result": {
        "success": false,
        "message": "",
        "errors": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "type": "add_tracking",
      "tracking": {
        "tracking_number": "text",
        "client_key": "text",
        "courier": "text",
        "external_reference": "text",
        "recipient_postal_code": "text",
        "recipient_phone": "text",
        "destination_country_iso3": "text",
        "language_iso2": "text",
        "timezone": "text",
        "courier_service_level": "text",
        "delivery_method": "text",
        "shipping_address": {
          "first_name": "text",
          "last_name": "text",
          "company_name": "text",
          "address_line": "text",
          "address_line_extra": "text",
          "postal_code": "text",
          "city": "text",
          "country_iso3": "text",
          "region_code": "text",
          "phone": "text"
        },
        "recipient_email": "text",
        "recipient_name": "text",
        "additional_recipients": [
          {
            "role": "text",
            "email": "text"
          }
        ],
        "cancelled_date": "2026-02-14T14:21:45.964Z",
        "is_return": true,
        "identifiers_consignment": "text",
        "delivery_number": "text",
        "invoice_number": "text",
        "shipping_cost_total": "text",
        "shipping_cost_net": "text",
        "shipping_cost_discount": "text",
        "shipping_weight_total": 1,
        "shipping_weight_unit": "g",
        "shipping_volume_total": 1,
        "shipping_volume_unit": "text",
        "shipping_height": 1,
        "shipping_width": 1,
        "shipping_length": 1,
        "shipping_dimensions_unit": "mm",
        "requires_signature": true,
        "is_dropshipment": true,
        "transport_number": "text",
        "origin_country_iso3": "text",
        "origin_region": "text",
        "origin_postal_code": "text",
        "articles": [
          {
            "version": "v1",
            "line_item_id": "text",
            "product_id": "text",
            "variant_id": "text",
            "sku": "text",
            "order_item_id": "text",
            "article_name": "text",
            "article_category": "text",
            "article_store_url": "text",
            "article_image_url": "text",
            "article_brand": "text",
            "size": "text",
            "color": "text",
            "width": 1,
            "height": 1,
            "length": 1,
            "length_unit": "cm",
            "weight": 1,
            "weight_unit": "g",
            "unit_price": "text",
            "unit_price_original": "text",
            "quantity": 1,
            "amount_invoiced": "text",
            "tax_amount": "text",
            "harmonized_system_code": "text",
            "origin_country_iso3": "text",
            "is_bulky": false,
            "tags": [
              "text"
            ],
            "additional_attributes": [
              {
                "key": "text",
                "value": null
              }
            ],
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        ],
        "warehouse": "text",
        "courier_contact_name": "text",
        "courier_contact_phone": "text",
        "courier_contact_email": "text",
        "review_link": "text",
        "status_link": "text",
        "collection_code_retailer": "text",
        "collection_code_carrier": "text",
        "announced_send_date": "2026-02-14",
        "announced_delivery_date": "2026-02-14",
        "announced_delivery_date_min": "2026-02-14",
        "announced_delivery_date_max": "2026-02-14",
        "notifications_inactive": true,
        "flags": [
          "complete"
        ],
        "cash_on_delivery_amount": 1,
        "tags": [
          "text"
        ],
        "checkpoints": [
          {
            "status_code": "text",
            "message": "text",
            "courier": "text",
            "exception": [
              "text"
            ],
            "delivery_location": "text",
            "event_timestamp": "2026-02-14T14:21:45.964Z",
            "courier_status": "text"
          }
        ],
        "additional_fields": null
      }
    }
  ]
}

Retrieve All Orders

You can retrieve a list of all orders for your account using the v4/track/orders endpoint.

List Orders

get

List all orders

Authorizations

OAuth2 AuthenticationHeaderToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

accountinteger[]Optional

cursorstringOptional

The pagination cursor value.

external_referencestringOptional

order_numberstringOptional

orderingstringOptional

Which field to use when ordering the results.

Responses

200Success

application/json

400Error

application/json

403Error

application/json

404Error

application/json

get

/v4/track/orders/

HTTPcURLJavaScriptPython

GET /v4/track/orders/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "next": "http://api.example.org/accounts/?cursor=cD00ODY%3D\"",
  "previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
  "results": [
    {
      "order_number": "O-1233",
      "tracking_number": "D12345678"
    }
  ]
}

Retrieve Orders by ID

You can retrieve a specific order using the v4/track/orders endpoint.

Lookup Order (by identifier)

get

Looks up an order by a unique identifier, either order_number or external_id. Returns all static order information,and order trackings.

Authorizations

OAuth2 AuthenticationHeaderToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

unique_idstringRequiredPattern: ^(?!info)[^/.]+$

Query parameters

Responses

200Success

application/json

400Error

application/json

403Error

application/json

404Error

application/json

get

/v4/track/orders/{unique_id}/

HTTPcURLJavaScriptPython

GET /v4/track/orders/{unique_id}/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "account": 1,
  "order_number": "text",
  "external_id": "text",
  "external_reference": "text",
  "client_key": "text",
  "destination_country_iso3": "text",
  "language_iso2": "text",
  "shipping_address": {
    "first_name": "text",
    "last_name": "text",
    "company_name": "text",
    "address_line": "text",
    "address_line_extra": "text",
    "postal_code": "text",
    "city": "text",
    "country_iso3": "text",
    "region_code": "text",
    "phone": "text"
  },
  "delivery_method": "text",
  "recipient_email": "[email protected]",
  "recipient_name": "text",
  "customer_number": "text",
  "invoice_number": "text",
  "payment_method": "text",
  "order_total_amount": null,
  "order_tax_amount": null,
  "order_net_amount": null,
  "order_discount_amount": null,
  "order_currency": "text",
  "payments": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "order_date": null,
  "channel": "text",
  "announced_delivery_date": null,
  "announced_delivery_date_min": null,
  "announced_delivery_date_max": null,
  "articles_order": [
    {
      "version": "v1",
      "line_item_id": "text",
      "product_id": "text",
      "variant_id": "text",
      "sku": "text",
      "order_item_id": "text",
      "article_name": "text",
      "article_category": "text",
      "article_store_url": "text",
      "article_image_url": "text",
      "article_brand": "text",
      "size": "text",
      "color": "text",
      "width": 1,
      "height": 1,
      "length": 1,
      "length_unit": "cm",
      "weight": 1,
      "weight_unit": "g",
      "unit_price": "text",
      "unit_price_original": "text",
      "quantity": 1,
      "amount_invoiced": "text",
      "tax_amount": "text",
      "harmonized_system_code": "text",
      "origin_country_iso3": "text",
      "is_bulky": false,
      "tags": [
        "text"
      ],
      "additional_attributes": [
        {
          "key": "text",
          "value": null
        }
      ],
      "status": "shipped",
      "shipped_quantity": 1,
      "original_quantity": 1,
      "change_reason": "text",
      "updated_at": "2026-02-14T14:21:45.964Z",
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "billing_address": {
    "first_name": "text",
    "last_name": "text",
    "company_name": "text",
    "address_line": "text",
    "address_line_extra": "text",
    "postal_code": "text",
    "city": "text",
    "country_iso3": "text",
    "region_code": "text",
    "phone": "text"
  },
  "timezone": "text",
  "order_status": "text",
  "has_multiple_shipments": null,
  "cancelled_date": null,
  "cancelled_reason": "customer",
  "additional_attributes": [
    {
      "key": "text",
      "value": null
    }
  ],
  "tags": [
    "text"
  ],
  "mutations": [
    {
      "operation_id": "123e4567-e89b-12d3-a456-426614174000",
      "result": {
        "success": false,
        "message": "",
        "errors": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "type": "add_tracking",
      "tracking": {
        "tracking_number": "text",
        "client_key": "text",
        "courier": "text",
        "external_reference": "text",
        "recipient_postal_code": "text",
        "recipient_phone": "text",
        "destination_country_iso3": "text",
        "language_iso2": "text",
        "timezone": "text",
        "courier_service_level": "text",
        "delivery_method": "text",
        "shipping_address": {
          "first_name": "text",
          "last_name": "text",
          "company_name": "text",
          "address_line": "text",
          "address_line_extra": "text",
          "postal_code": "text",
          "city": "text",
          "country_iso3": "text",
          "region_code": "text",
          "phone": "text"
        },
        "recipient_email": "text",
        "recipient_name": "text",
        "additional_recipients": [
          {
            "role": "text",
            "email": "text"
          }
        ],
        "cancelled_date": "2026-02-14T14:21:45.964Z",
        "is_return": true,
        "identifiers_consignment": "text",
        "delivery_number": "text",
        "invoice_number": "text",
        "shipping_cost_total": "text",
        "shipping_cost_net": "text",
        "shipping_cost_discount": "text",
        "shipping_weight_total": 1,
        "shipping_weight_unit": "g",
        "shipping_volume_total": 1,
        "shipping_volume_unit": "text",
        "shipping_height": 1,
        "shipping_width": 1,
        "shipping_length": 1,
        "shipping_dimensions_unit": "mm",
        "requires_signature": true,
        "is_dropshipment": true,
        "transport_number": "text",
        "origin_country_iso3": "text",
        "origin_region": "text",
        "origin_postal_code": "text",
        "articles": [
          {
            "version": "v1",
            "line_item_id": "text",
            "product_id": "text",
            "variant_id": "text",
            "sku": "text",
            "order_item_id": "text",
            "article_name": "text",
            "article_category": "text",
            "article_store_url": "text",
            "article_image_url": "text",
            "article_brand": "text",
            "size": "text",
            "color": "text",
            "width": 1,
            "height": 1,
            "length": 1,
            "length_unit": "cm",
            "weight": 1,
            "weight_unit": "g",
            "unit_price": "text",
            "unit_price_original": "text",
            "quantity": 1,
            "amount_invoiced": "text",
            "tax_amount": "text",
            "harmonized_system_code": "text",
            "origin_country_iso3": "text",
            "is_bulky": false,
            "tags": [
              "text"
            ],
            "additional_attributes": [
              {
                "key": "text",
                "value": null
              }
            ],
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        ],
        "warehouse": "text",
        "courier_contact_name": "text",
        "courier_contact_phone": "text",
        "courier_contact_email": "text",
        "review_link": "text",
        "status_link": "text",
        "collection_code_retailer": "text",
        "collection_code_carrier": "text",
        "announced_send_date": "2026-02-14",
        "announced_delivery_date": "2026-02-14",
        "announced_delivery_date_min": "2026-02-14",
        "announced_delivery_date_max": "2026-02-14",
        "notifications_inactive": true,
        "flags": [
          "complete"
        ],
        "cash_on_delivery_amount": 1,
        "tags": [
          "text"
        ],
        "checkpoints": [
          {
            "status_code": "text",
            "message": "text",
            "courier": "text",
            "exception": [
              "text"
            ],
            "delivery_location": "text",
            "event_timestamp": "2026-02-14T14:21:45.964Z",
            "courier_status": "text"
          }
        ],
        "additional_fields": null
      }
    }
  ],
  "trackings": [
    {
      "tracking_number": "text",
      "client_key": "text",
      "courier": "text",
      "external_reference": "text",
      "recipient_postal_code": "text",
      "recipient_phone": "text",
      "destination_country_iso3": "text",
      "language_iso2": "text",
      "timezone": "text",
      "courier_service_level": "text",
      "delivery_method": "text",
      "shipping_address": {
        "first_name": "text",
        "last_name": "text",
        "company_name": "text",
        "address_line": "text",
        "address_line_extra": "text",
        "postal_code": "text",
        "city": "text",
        "country_iso3": "text",
        "region_code": "text",
        "phone": "text"
      },
      "recipient_email": "text",
      "recipient_name": "text",
      "additional_recipients": [
        {
          "role": "text",
          "email": "text"
        }
      ],
      "cancelled_date": "2026-02-14T14:21:45.964Z",
      "is_return": true,
      "identifiers_consignment": "text",
      "delivery_number": "text",
      "invoice_number": "text",
      "shipping_cost_total": "text",
      "shipping_cost_net": "text",
      "shipping_cost_discount": "text",
      "shipping_weight_total": 1,
      "shipping_weight_unit": "g",
      "shipping_volume_total": 1,
      "shipping_volume_unit": "text",
      "shipping_height": 1,
      "shipping_width": 1,
      "shipping_length": 1,
      "shipping_dimensions_unit": "mm",
      "requires_signature": true,
      "is_dropshipment": true,
      "transport_number": "text",
      "origin_country_iso3": "text",
      "origin_region": "text",
      "origin_postal_code": "text",
      "articles": [
        {
          "version": "v1",
          "line_item_id": "text",
          "product_id": "text",
          "variant_id": "text",
          "sku": "text",
          "order_item_id": "text",
          "article_name": "text",
          "article_category": "text",
          "article_store_url": "text",
          "article_image_url": "text",
          "article_brand": "text",
          "size": "text",
          "color": "text",
          "width": 1,
          "height": 1,
          "length": 1,
          "length_unit": "cm",
          "weight": 1,
          "weight_unit": "g",
          "unit_price": "text",
          "unit_price_original": "text",
          "quantity": 1,
          "amount_invoiced": "text",
          "tax_amount": "text",
          "harmonized_system_code": "text",
          "origin_country_iso3": "text",
          "is_bulky": false,
          "tags": [
            "text"
          ],
          "additional_attributes": [
            {
              "key": "text",
              "value": null
            }
          ],
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "warehouse": "text",
      "courier_contact_name": "text",
      "courier_contact_phone": "text",
      "courier_contact_email": "text",
      "review_link": "text",
      "status_link": "text",
      "collection_code_retailer": "text",
      "collection_code_carrier": "text",
      "announced_send_date": "2026-02-14",
      "announced_delivery_date": "2026-02-14",
      "announced_delivery_date_min": "2026-02-14",
      "announced_delivery_date_max": "2026-02-14",
      "notifications_inactive": true,
      "flags": [
        "complete"
      ],
      "cash_on_delivery_amount": 1,
      "tags": [
        "text"
      ],
      "checkpoints": [
        {
          "status_code": "text",
          "message": "text",
          "courier": "text",
          "exception": [
            "text"
          ],
          "delivery_location": "text",
          "event_timestamp": "2026-02-14T14:21:45.964Z",
          "courier_status": "text"
        }
      ],
      "additional_fields": null,
      "courier_change_url": "text",
      "is_returns_portal": true,
      "number_of_parcels": 1,
      "pod_date": "2026-02-14",
      "pod_identifier": "text",
      "pod_signature": "text",
      "reporting_courier_dropoff_date": "2026-02-14",
      "reporting_delivery_date": "2026-02-14",
      "reporting_in_transit_date": "2026-02-14",
      "reporting_pickup_date": "2026-02-14",
      "security_hash": "text",
      "support_phone": "text"
    }
  ]
}

Payload

The payload holds the order-specific information as specified in the data model. All attributes are named key-value pairs in a flat JSON formatted object.

payload.json

{
    "account": 1234567,
    "order_number": "PCL-1235",
    "reference": "REF-1234",
    "client_key": "1234",
    "destination_country_iso3": "DEU",
    "shipping_address": {
        "first_name": "Max",
        "last_name": "Mustermann",
        "address_line": "Kapellenweg 2"
        "postal_code": "12345",
        "city": "Berlin",
        "country_iso3": "DEU",
        "region_code": "BY",
    },
    "delivery_method": "Standard",
    "recipient_email": "[email protected]",
    "recipient_name": "Max Mustermann",
    "articles_order": [
        {
                       "line_item_id": "57",
                       "sku": "AP-SH-TWC-2315"
                       "article_name": "Trendy White Cotton Sneakers",
                       "article_store_url": "https://weareparkers.com/products/trendy-white-cotton-sneakers",
                       "article_iamge_url":          "https://weareparkers.com/cdn/shop/products/trendy-white-cotton-sneakers-01.png?v=1704374674&width=1100",
                       "size": "9",
                       "color": "White",
                       "quantity": 1,
        }
    ],
    "mutations": [
        {
            "type": "add_tracking",
            "tracking": {
                "tracking_number": "PCLX-123123",
                "courier": "pclx",
                "articles": [
                    {
                        "line_item_id": "57",
                        "sku": "AP-SH-TWC-2315"
                        "article_name": "Trendy White Cotton Sneakers",
                        "article_store_url": "https://weareparkers.com/products/trendy-white-cotton-sneakers",
                        "article_iamge_url":          "https://weareparkers.com/cdn/shop/products/trendy-white-cotton-sneakers-01.png?v=1704374674&width=1100",
                        "size": "9",
                        "color": "White",
                        "quantity": 1,
                    }
                ]
            }
        }
    ]
}

All available keys can be found in the data model.

Data Model

Credentials

Credentials are assigned by our Support team as required for the services used. Overall, there are different pairs of credentials for different services to assure security.

Code Samples

You can use our API with jQuery, Node, Ruby, Python, PHP, and other programming languages.

For examples of programming languages, please fill in our contact form and they will be provided on request.

For a simple test, cURL can be used.

sample-call-with-curl.sh

curl -L \
  -request PUT \
  -url ‘/v4/track/orders/’ \
  -header ‘Authorization: Parcellab-API-Token <your-token>’ \
  -header ‘Content-Type: application/json’ \
  -data ‘{
   "account": 1612197.
   "order_number: PK1004",
   "...",
   }