Full Order API Spec

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.

For partial line cancellations or quantity reductions, use change_line_item_quantity with the new absolute quantity. For full-order cancellation, use the cancel_order mutation — it sets order_status to Cancelled server-side and generates cancelled_date when omitted. Each logical line in articles_order should have a unique line_item_id. If you also send tracking.articles, keep line_item_id or order_item_id aligned with the corresponding item in articles_order so later line-item changes can be reflected correctly on the order status page.

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.

Send shipping_address or billing_address only when you can provide a complete address object. Each address object requires address_line, postal_code, city, and country_iso3; blank strings and null values are not accepted for these fields. If a complete shipping address is not available, omit shipping_address and send order-level fields such as destination_country_iso3, recipient_email, recipient_name, and, when available, recipient_postal_code on the tracking instead.

Create or Update Order (recommended)

put

Create or update an order. If the order already exists, only changed fields or mutation actions such as add_tracking, cancel_tracking, or line-item mutations need to be submitted. This endpoint is idempotent. external_id or order_number is required to identify the order.

Payload validation:

• Request-blocking validation failures return HTTP 400 and no order or mutation history is written. Serializer and Pydantic validation errors use the standard {"type": "client_error", "errors": [...]} shape. Early order identifier and account authorization failures return {"detail": "..."}.

• recipient_email must be a valid email address or the literal _unset.

• Country, language, currency, timezone, enum, date, datetime, decimal, length, and required-field validations are enforced at the request boundary.

• shipping_address and tracking-level shipping_address are strictly validated, including region codes. billing_address uses the more permissive address schema and can coerce invalid region codes to null.

• Mutation payloads must use a supported type. Tracking mutations require either tracking_number plus courier, or external_reference.

• Tracking-level delivery_method must be configured for the account.

• add_tracking with tracking_number plus courier performs a best-effort same-account conflict check before enqueueing. The check is eventually consistent and Backend persistence still enforces downstream uniqueness.

Successful responses can still contain per-mutation validation information:

• Non-fatal validation warnings are returned in mutations[].result.warnings. Today this covers dropped unrecognized add_tracking.tracking fields and articles_order replacement warnings when mutations are present.

• Accepted mutation failures do not reject the whole request. The HTTP response remains 200 or 201, while the affected mutation returns mutations[].result.success=false.

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_reasonstring · 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

Order payload. Mutation actions include mutations[].result. Non-fatal validation warnings are returned in mutations[].result.warnings; accepted mutation failures are returned as mutations[].result.success=false.

application/json

Create a new order record with shipment and recipient data.

accountintegerRequired

Account to which this order belongs

order_numberstring · max: 255Required

Order number (customer facing)

external_idstringRead-onlyRequired

Unique identifier for this order, generated by parcelLab for this order

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 · 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 ofRequired

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_reasonstring · enumOptional

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

Possible values:

tagsstring[]Optional

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

201

Order payload. Mutation actions include mutations[].result. Non-fatal validation warnings are returned in mutations[].result.warnings; accepted mutation failures are returned as mutations[].result.success=false.

application/json

400

Bad request. Payload validation errors use the standard error list shape. Early order identifier and account authorization failures use a direct detail response.

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: 3669

{
  "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",
  "additional_recipients": [
    {
      "role": "text",
      "email": "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": [
    {
      "article_name": "Blue T-Shirt",
      "line_item_id": "ITEM-001",
      "product_id": "PROD-123",
      "quantity": 2,
      "sku": "TSHIRT-BLUE-M"
    }
  ],
  "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"
        },
        "warnings": [
          "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-06-09T15:24:14.015Z",
        "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": [
          {
            "article_name": "Blue T-Shirt",
            "line_item_id": "ITEM-001",
            "product_id": "PROD-123",
            "quantity": 2,
            "sku": "TSHIRT-BLUE-M"
          }
        ],
        "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-06-09",
        "announced_delivery_date": "2026-06-09",
        "announced_delivery_date_min": "2026-06-09",
        "announced_delivery_date_max": "2026-06-09",
        "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-06-09T15:24:14.015Z",
            "courier_status": "text"
          }
        ],
        "additional_fields": null
      }
    }
  ]
}

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

{
  "account": 1234,
  "order_number": "ORD-100045",
  "external_id": "6f89b5ac-8af2-4c42-8d38-36f0f6c8532d",
  "destination_country_iso3": "USA",
  "recipient_email": "[email protected]",
  "mutations": [
    {
      "type": "add_tracking",
      "operation_id": "a097f450-0f55-4388-bf3c-817d99198978",
      "tracking": {
        "tracking_number": "794600000001",
        "courier": "fedex"
      },
      "result": {
        "success": true,
        "message": "",
        "errors": {},
        "warnings": [
          "Dropped unrecognized fields from tracking payload: enterprise_code"
        ]
      }
    }
  ]
}

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 already exist. Duplicate orders return a validation error. For idempotent create-or-update behavior, use the PUT endpoint.

Payload validation:

• Request-blocking validation failures return HTTP 400 and no order or mutation history is written. Serializer and Pydantic validation errors use the standard {"type": "client_error", "errors": [...]} shape. Early order identifier and account authorization failures return {"detail": "..."}.

• recipient_email must be a valid email address or the literal _unset.

• Country, language, currency, timezone, enum, date, datetime, decimal, length, and required-field validations are enforced at the request boundary.

• shipping_address and tracking-level shipping_address are strictly validated, including region codes. billing_address uses the more permissive address schema and can coerce invalid region codes to null.

• Mutation payloads must use a supported type. Tracking mutations require either tracking_number plus courier, or external_reference.

• Tracking-level delivery_method must be configured for the account.

• add_tracking with tracking_number plus courier performs a best-effort same-account conflict check before enqueueing. The check is eventually consistent and Backend persistence still enforces downstream uniqueness.

Successful responses can still contain per-mutation validation information:

• Non-fatal validation warnings are returned in mutations[].result.warnings. Today this covers dropped unrecognized add_tracking.tracking fields and articles_order replacement warnings when mutations are present.

• Accepted mutation failures do not reject the whole request. The HTTP response remains 200 or 201, while the affected mutation returns mutations[].result.success=false.

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_reasonstring · 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

201

Order payload. Mutation actions include mutations[].result. Non-fatal validation warnings are returned in mutations[].result.warnings; accepted mutation failures are returned as mutations[].result.success=false.

application/json

400

Bad request. Payload validation errors use the standard error list shape.

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: 1363

{
  "account": 1612197,
  "order_number": "ORD-US-2024-001",
  "external_reference": "WEB-1612197-10001",
  "client_key": "us-webshop",
  "destination_country_iso3": "USA",
  "language_iso2": "en",
  "recipient_email": "[email protected]",
  "recipient_name": "Max Mustermann",
  "order_total_amount": "129.99",
  "order_currency": "USD",
  "order_date": "2024-01-15T10:30:00Z",
  "delivery_method": "ground_shipping",
  "channel": "webshop",
  "shipping_address": {
    "first_name": "Max",
    "last_name": "Mustermann",
    "address_line": "75 State St",
    "city": "Boston",
    "postal_code": 2109,
    "country_iso3": "USA",
    "region_code": "MA"
  },
  "articles_order": [
    {
      "line_item_id": "ITEM-001",
      "product_id": "PROD-100",
      "sku": "JACKET-NAVY-M",
      "article_name": "Navy Utility Jacket",
      "quantity": 1,
      "unit_price": "79.99"
    },
    {
      "line_item_id": "ITEM-002",
      "product_id": "PROD-200",
      "sku": "MUG-GRANITE",
      "article_name": "Stoneware Travel Mug",
      "quantity": 1,
      "unit_price": "50.00"
    }
  ],
  "mutations": [
    {
      "type": "add_tracking",
      "tracking": {
        "tracking_number": "T10000001",
        "courier": "fedex",
        "delivery_number": "D-12345_1",
        "warehouse": "US-WEST",
        "articles": [
          {
            "line_item_id": "ITEM-001",
            "product_id": "PROD-100",
            "sku": "JACKET-NAVY-M",
            "article_name": "Navy Utility Jacket",
            "quantity": 1
          },
          {
            "line_item_id": "ITEM-002",
            "product_id": "PROD-200",
            "sku": "MUG-GRANITE",
            "article_name": "Stoneware Travel Mug",
            "quantity": 1
          }
        ],
        "additional_fields": {
          "seller_organization_code": "PL_01",
          "pickupBoxNo": "48"
        }
      }
    }
  ]
}

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

{
  "account": 1234,
  "order_number": "ORD-100045",
  "external_id": "6f89b5ac-8af2-4c42-8d38-36f0f6c8532d",
  "destination_country_iso3": "USA",
  "recipient_email": "[email protected]",
  "mutations": [
    {
      "type": "add_tracking",
      "operation_id": "a097f450-0f55-4388-bf3c-817d99198978",
      "tracking": {
        "tracking_number": "794600000001",
        "courier": "fedex"
      },
      "result": {
        "success": true,
        "message": "",
        "errors": {},
        "warnings": [
          "Dropped unrecognized fields from tracking payload: enterprise_code"
        ]
      }
    }
  ]
}

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

Order results by any response field. Prefix with - for descending (e.g. -id).

Responses

200Success

application/json

nextstring · uri · nullableOptionalExample: http://api.example.org/accounts/?cursor=cD00ODY%3D"

previousstring · uri · nullableOptionalExample: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3

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

Create a new order record with shipment and recipient data.

accountintegerRequired

Account to which this order belongs

order_numberstring · max: 255Required

Order number (customer facing)

external_idstringRead-onlyRequired

Unique identifier for this order, generated by parcelLab for this order

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 · 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 ofRequired

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_reasonstring · enumOptional

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

Possible values:

tagsstring[]Optional

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

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",
  "additional_recipients": [
    {
      "role": "text",
      "email": "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": [
    {
      "article_name": "Blue T-Shirt",
      "line_item_id": "ITEM-001",
      "product_id": "PROD-123",
      "quantity": 2,
      "sku": "TSHIRT-BLUE-M"
    }
  ],
  "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"
        },
        "warnings": [
          "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-06-09T15:24:14.015Z",
        "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": [
          {
            "article_name": "Blue T-Shirt",
            "line_item_id": "ITEM-001",
            "product_id": "PROD-123",
            "quantity": 2,
            "sku": "TSHIRT-BLUE-M"
          }
        ],
        "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-06-09",
        "announced_delivery_date": "2026-06-09",
        "announced_delivery_date_min": "2026-06-09",
        "announced_delivery_date_max": "2026-06-09",
        "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-06-09T15:24:14.015Z",
            "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-06-09T15:24:14.015Z",
      "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": [
        {
          "article_name": "Blue T-Shirt",
          "line_item_id": "ITEM-001",
          "product_id": "PROD-123",
          "quantity": 2,
          "sku": "TSHIRT-BLUE-M"
        }
      ],
      "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-06-09",
      "announced_delivery_date": "2026-06-09",
      "announced_delivery_date_min": "2026-06-09",
      "announced_delivery_date_max": "2026-06-09",
      "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-06-09T15:24:14.015Z",
          "courier_status": "text"
        }
      ],
      "additional_fields": null,
      "courier_change_url": "text",
      "is_returns_portal": true,
      "number_of_parcels": 1,
      "pod_date": "2026-06-09",
      "pod_identifier": "text",
      "pod_signature": "text",
      "reporting_courier_dropoff_date": "2026-06-09",
      "reporting_delivery_date": "2026-06-09",
      "reporting_in_transit_date": "2026-06-09",
      "reporting_pickup_date": "2026-06-09",
      "security_hash": "text",
      "support_phone": "text"
    }
  ]
}

Retrieve the Security Hash

You can retrieve the security hash as part of the order details response (see above) to securely access the Order Status page.

The security hash is generated per tracking, not per order. Orders with multiple trackings will have multiple security hashes.

To retrieve the security hash:

1. Call the v4/track/orders endpoint using one of the following identifiers:

   • order_number GET /v4/track/orders/{order_number}/?lookup_by=order-number&account={account_id}

   • external_id GET /v4/track/orders/{external_id}/

2. Authenticate the request using your API token.

3. In the response, locate the trackings array and retrieve the security_hash value.

4. If multiple trackings exist, identify the correct one using:

   • tracking_number + courier

   • external_reference

Example response:

{
  "account": "1619884",
  "order_number": "ORDER-123",
  "external_id": "8d57c8b2-3c38-4bd4-9b6e-9b6dc9ce52d9",
  "trackings": [
    {
      "tracking_number": "1Z999AA10123456784",
      "courier": "ups",
      "external_reference": "SHIPMENT-1",
      "security_hash": "FPrvZY6CkE"
    }
  ]
}

To use the security hash, append it to the URL of any website running our tracking plugin as &s=<securityHash>. For more information, see our Order Status page setup documentation.

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",
   "...",
   }