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.
For line-item cancellations or quantity reductions, use change_line_item_quantity with the new absolute quantity. Use quantity: 0 to cancel an existing line. Use replace_line_item only when the cancelled line is substituted by a replacement line. 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.
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_emailmust 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_addressand tracking-levelshipping_addressare strictly validated, including region codes.billing_addressuses the more permissive address schema and can coerce invalid region codes tonull.Mutation payloads must use a supported
type. Tracking mutations require eithertracking_numberpluscourier, orexternal_reference.Tracking-level
delivery_methodmust be configured for the account.add_trackingwithtracking_numberpluscourierperforms 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 unrecognizedadd_tracking.trackingfields andarticles_orderreplacement 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.
Send Authorization: Parcellab-API-Token <encoded-token>.
<encoded-token> = base64(account_id:token) as provided in the portal.
Create a new order record with shipment and recipient data.
Account to which this order belongs
Order number (customer facing)
Retailer reference (e.g. internal system ID) for this order, unique.
Name of the technical client / shop (corresponds to the system setup), e.g. 'mybrand-a.com'
Destination country ISO 3166-1 alpha 3 code
ISO 639-1 language code of the recipient, if known, required for localized communication
Delivery method (e.g. 'standard shipping'), needs to be set up in the system
Recipient email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead.
Recipient name
Customer number (e.g. from the retailer)
Invoice number (e.g. from the retailer)
Payment method (e.g. 'credit card')
Total amount of the order (usually after tax & discount)
^-?\d{0,8}(?:\.\d{0,2})?$Tax amount of the original order
^-?\d{0,8}(?:\.\d{0,2})?$Net amount of the order (usually before tax)
^-?\d{0,8}(?:\.\d{0,2})?$Discount amount of the order
^-?\d{0,8}(?:\.\d{0,2})?$Currency of the order, e.g. USD, EUR (ISO 4217)
Date and time when the order was placed
Channel through which the order was placed (e.g. 'webshop')
Announced delivery date
Announced delivery date range of order (min)
Announced delivery date range of order (min)
Timezone of the recipient, if known, not required, but strongly recommended
Current status of the order, as setup in the system
Indicates this order has been split into multiple shipments
Datetime when the order was cancelled
customer- Customerinventory- Inventorypayment- Payment-relatedother- Other
Tags for the object, format :e.g. 'category:Home Apparel'
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.
Create a new order record with shipment and recipient data.
Account to which this order belongs
Order number (customer facing)
Unique identifier for this order, generated by parcelLab for this order
Retailer reference (e.g. internal system ID) for this order, unique.
Name of the technical client / shop (corresponds to the system setup), e.g. 'mybrand-a.com'
Destination country ISO 3166-1 alpha 3 code
ISO 639-1 language code of the recipient, if known, required for localized communication
Delivery method (e.g. 'standard shipping'), needs to be set up in the system
Recipient email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead.
Recipient name
Customer number (e.g. from the retailer)
Invoice number (e.g. from the retailer)
Payment method (e.g. 'credit card')
Total amount of the order (usually after tax & discount)
^-?\d{0,8}(?:\.\d{0,2})?$Tax amount of the original order
^-?\d{0,8}(?:\.\d{0,2})?$Net amount of the order (usually before tax)
^-?\d{0,8}(?:\.\d{0,2})?$Discount amount of the order
^-?\d{0,8}(?:\.\d{0,2})?$Currency of the order, e.g. USD, EUR (ISO 4217)
Date and time when the order was placed
Channel through which the order was placed (e.g. 'webshop')
Announced delivery date
Announced delivery date range of order (min)
Announced delivery date range of order (min)
Timezone of the recipient, if known, not required, but strongly recommended
Current status of the order, as setup in the system
Indicates this order has been split into multiple shipments
Datetime when the order was cancelled
customer- Customerinventory- Inventorypayment- Payment-relatedother- Other
Tags for the object, format :e.g. 'category:Home Apparel'
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.
Bad request. Payload validation errors use the standard error list shape. Early order identifier and account authorization failures use a direct detail response.
PUT /v4/track/orders/ HTTP/1.1
Authorization: Parcellab-API-Token YOUR_BASE64_ENCODED_API_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 3737
{
"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": "name@gmail.com",
"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",
"order_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-01-01T00:00:00.000Z",
"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",
"courier_reference_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-01-01",
"announced_delivery_date": "2026-01-01",
"announced_delivery_date_min": "2026-01-01",
"announced_delivery_date_max": "2026-01-01",
"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-01-01T00:00:00.000Z",
"courier_status": "text"
}
],
"additional_fields": null
}
}
]
}{
"account": 1234,
"order_number": "ORD-100045",
"external_id": "6f89b5ac-8af2-4c42-8d38-36f0f6c8532d",
"destination_country_iso3": "USA",
"recipient_email": "customer@example.com",
"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.
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 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_emailmust 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_addressand tracking-levelshipping_addressare strictly validated, including region codes.billing_addressuses the more permissive address schema and can coerce invalid region codes tonull.Mutation payloads must use a supported
type. Tracking mutations require eithertracking_numberpluscourier, orexternal_reference.Tracking-level
delivery_methodmust be configured for the account.add_trackingwithtracking_numberpluscourierperforms 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 unrecognizedadd_tracking.trackingfields andarticles_orderreplacement 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.
Send Authorization: Parcellab-API-Token <encoded-token>.
<encoded-token> = base64(account_id:token) as provided in the portal.
Create a new order record with shipment and recipient data.
Account to which this order belongs
Order number (customer facing)
Retailer reference (e.g. internal system ID) for this order, unique.
Name of the technical client / shop (corresponds to the system setup), e.g. 'mybrand-a.com'
Destination country ISO 3166-1 alpha 3 code
ISO 639-1 language code of the recipient, if known, required for localized communication
Delivery method (e.g. 'standard shipping'), needs to be set up in the system
Recipient email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead.
Recipient name
Customer number (e.g. from the retailer)
Invoice number (e.g. from the retailer)
Payment method (e.g. 'credit card')
Total amount of the order (usually after tax & discount)
^-?\d{0,8}(?:\.\d{0,2})?$Tax amount of the original order
^-?\d{0,8}(?:\.\d{0,2})?$Net amount of the order (usually before tax)
^-?\d{0,8}(?:\.\d{0,2})?$Discount amount of the order
^-?\d{0,8}(?:\.\d{0,2})?$Currency of the order, e.g. USD, EUR (ISO 4217)
Date and time when the order was placed
Channel through which the order was placed (e.g. 'webshop')
Announced delivery date
Announced delivery date range of order (min)
Announced delivery date range of order (min)
Timezone of the recipient, if known, not required, but strongly recommended
Current status of the order, as setup in the system
Indicates this order has been split into multiple shipments
Datetime when the order was cancelled
customer- Customerinventory- Inventorypayment- Payment-relatedother- Other
Tags for the object, format :e.g. 'category:Home Apparel'
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.
Create a new order record with shipment and recipient data.
Account to which this order belongs
Order number (customer facing)
Unique identifier for this order, generated by parcelLab for this order
Retailer reference (e.g. internal system ID) for this order, unique.
Name of the technical client / shop (corresponds to the system setup), e.g. 'mybrand-a.com'
Destination country ISO 3166-1 alpha 3 code
ISO 639-1 language code of the recipient, if known, required for localized communication
Delivery method (e.g. 'standard shipping'), needs to be set up in the system
Recipient email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead.
Recipient name
Customer number (e.g. from the retailer)
Invoice number (e.g. from the retailer)
Payment method (e.g. 'credit card')
Total amount of the order (usually after tax & discount)
^-?\d{0,8}(?:\.\d{0,2})?$Tax amount of the original order
^-?\d{0,8}(?:\.\d{0,2})?$Net amount of the order (usually before tax)
^-?\d{0,8}(?:\.\d{0,2})?$Discount amount of the order
^-?\d{0,8}(?:\.\d{0,2})?$Currency of the order, e.g. USD, EUR (ISO 4217)
Date and time when the order was placed
Channel through which the order was placed (e.g. 'webshop')
Announced delivery date
Announced delivery date range of order (min)
Announced delivery date range of order (min)
Timezone of the recipient, if known, not required, but strongly recommended
Current status of the order, as setup in the system
Indicates this order has been split into multiple shipments
Datetime when the order was cancelled
customer- Customerinventory- Inventorypayment- Payment-relatedother- Other
Tags for the object, format :e.g. 'category:Home Apparel'
Bad request. Payload validation errors use the standard error list shape.
POST /v4/track/orders/ HTTP/1.1
Authorization: Parcellab-API-Token YOUR_BASE64_ENCODED_API_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": "max.mustermann@example.com",
"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"
}
}
}
]
}{
"account": 1234,
"order_number": "ORD-100045",
"external_id": "6f89b5ac-8af2-4c42-8d38-36f0f6c8532d",
"destination_country_iso3": "USA",
"recipient_email": "customer@example.com",
"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 all orders
Send Authorization: Parcellab-API-Token <encoded-token>.
<encoded-token> = base64(account_id:token) as provided in the portal.
The pagination cursor value.
Order results by any response field. Prefix with - for descending (e.g. -id).
http://api.example.org/accounts/?cursor=cD00ODY%3D"http://api.example.org/accounts/?cursor=cj0xJnA9NDg3GET /v4/track/orders/ HTTP/1.1
Authorization: Parcellab-API-Token YOUR_BASE64_ENCODED_API_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.
Looks up an order by a unique identifier, either order_number or external_id. Returns all static order information,and order trackings.
Send Authorization: Parcellab-API-Token <encoded-token>.
<encoded-token> = base64(account_id:token) as provided in the portal.
^(?!info)[^/.]+$Create a new order record with shipment and recipient data.
Account to which this order belongs
Order number (customer facing)
Unique identifier for this order, generated by parcelLab for this order
Retailer reference (e.g. internal system ID) for this order, unique.
Name of the technical client / shop (corresponds to the system setup), e.g. 'mybrand-a.com'
Destination country ISO 3166-1 alpha 3 code
ISO 639-1 language code of the recipient, if known, required for localized communication
Delivery method (e.g. 'standard shipping'), needs to be set up in the system
Recipient email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead.
Recipient name
Customer number (e.g. from the retailer)
Invoice number (e.g. from the retailer)
Payment method (e.g. 'credit card')
Total amount of the order (usually after tax & discount)
^-?\d{0,8}(?:\.\d{0,2})?$Tax amount of the original order
^-?\d{0,8}(?:\.\d{0,2})?$Net amount of the order (usually before tax)
^-?\d{0,8}(?:\.\d{0,2})?$Discount amount of the order
^-?\d{0,8}(?:\.\d{0,2})?$Currency of the order, e.g. USD, EUR (ISO 4217)
Date and time when the order was placed
Channel through which the order was placed (e.g. 'webshop')
Announced delivery date
Announced delivery date range of order (min)
Announced delivery date range of order (min)
Timezone of the recipient, if known, not required, but strongly recommended
Current status of the order, as setup in the system
Indicates this order has been split into multiple shipments
Datetime when the order was cancelled
customer- Customerinventory- Inventorypayment- Payment-relatedother- Other
Tags for the object, format :e.g. 'category:Home Apparel'
GET /v4/track/orders/{unique_id}/ HTTP/1.1
Authorization: Parcellab-API-Token YOUR_BASE64_ENCODED_API_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": "name@gmail.com",
"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",
"order_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-01-01T00:00:00.000Z",
"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",
"courier_reference_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-01-01",
"announced_delivery_date": "2026-01-01",
"announced_delivery_date_min": "2026-01-01",
"announced_delivery_date_max": "2026-01-01",
"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-01-01T00:00:00.000Z",
"courier_status": "text"
}
],
"additional_fields": null
}
}
],
"trackings": [
{
"tracking_number": "text",
"client_key": "text",
"courier": "text",
"external_reference": "text",
"order_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-01-01T00:00:00.000Z",
"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",
"courier_reference_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-01-01",
"announced_delivery_date": "2026-01-01",
"announced_delivery_date_min": "2026-01-01",
"announced_delivery_date_max": "2026-01-01",
"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-01-01T00:00:00.000Z",
"courier_status": "text"
}
],
"additional_fields": null,
"courier_change_url": "text",
"is_returns_portal": true,
"number_of_parcels": 1,
"pod_date": "2026-01-01",
"pod_identifier": "text",
"pod_signature": "text",
"reporting_courier_dropoff_date": "2026-01-01",
"reporting_delivery_date": "2026-01-01",
"reporting_in_transit_date": "2026-01-01",
"reporting_pickup_date": "2026-01-01",
"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.
To retrieve the security hash:
Call the
v4/track/ordersendpoint using one of the following identifiers:order_numberGET /v4/track/orders/{order_number}/?lookup_by=order-number&account={account_id}external_idGET /v4/track/orders/{external_id}/
Authenticate the request using your API token.
In the response, locate the
trackingsarray and retrieve thesecurity_hashvalue.If multiple trackings exist, identify the correct one using:
tracking_number+courierexternal_reference
Example response:
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.
All available keys can be found in the data model.
Additional Notification Recipients
Use additional_recipients when selected parcelLab notifications should go to role-based contacts that are different from the main recipient_email. Provide a role and an email for each contact that should be selectable by a Journey trigger; the role is selected in the Journey trigger configuration for the relevant message. Carrier-generated notifications may use separate carrier-specific recipient fields.
For details and tracking-level examples, see Dynamic Recipients and Additional Recipients for Notifications.
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 a simple test, cURL can be used.
Last updated
Was this helpful?