# Full Order API Spec

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

{% hint style="info" %}
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.
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

{% hint style="success" %}
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](/docs/developers/data-elements/data-model.md#tags).
{% endhint %}

{% hint style="info" %}
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.
{% endhint %}

## Create or Update Order (recommended)

> 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\
> &#x20; \`mutations\[].result.success=false\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token <encoded-token>`.\n\n`<encoded-token>` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"PatchedOrderRequest":{"type":"object","description":"Create a new order record with shipment and recipient data.","properties":{"account":{"type":"integer","description":"Account to which this order belongs"},"order_number":{"type":"string","minLength":1,"description":"Order number (customer facing)","maxLength":255},"external_reference":{"type":"string","title":"Reference Identifier","description":"Retailer reference (e.g. internal system ID) for this order, unique.","maxLength":255},"client_key":{"type":"string","description":"Name of the technical client / shop (corresponds to the system setup), e.g. 'mybrand-a.com'","maxLength":512},"destination_country_iso3":{"type":"string","minLength":1,"description":"Destination country ISO 3166-1 alpha 3 code","maxLength":3},"language_iso2":{"type":"string","description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3},"shipping_address":{"anyOf":[{"$ref":"#/components/schemas/AddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"delivery_method":{"type":"string","description":"Delivery method (e.g. 'standard shipping'), needs to be set up in the system","maxLength":255},"recipient_email":{"anyOf":[{"format":"email","type":"string"},{"const":"_unset","enum":["_unset"],"type":"string"}],"minLength":1,"description":"Recipient email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead."},"recipient_name":{"type":"string","title":"Recipient name shown on notifications","description":"Recipient name","maxLength":255},"additional_recipients":{"items":{"$ref":"#/components/schemas/AdditionalRecipient"},"type":"array"},"customer_number":{"type":"string","description":"Customer number (e.g. from the retailer)","maxLength":255},"invoice_number":{"type":"string","description":"Invoice number (e.g. from the retailer)","maxLength":255},"payment_method":{"type":"string","description":"Payment method (e.g. 'credit card')","maxLength":255},"order_total_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total amount of the order (usually after tax & discount)"},"order_tax_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Tax amount of the original order"},"order_net_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Net amount of the order (usually before tax)"},"order_discount_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Discount amount of the order"},"order_currency":{"type":"string","description":"Currency of the order, e.g. USD, EUR (ISO 4217)","maxLength":3},"payments":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"order_date":{"type":["string","null"],"format":"date-time","description":"Date and time when the order was placed"},"channel":{"type":"string","description":"Channel through which the order was placed (e.g. 'webshop')","maxLength":255},"announced_delivery_date":{"type":["string","null"],"format":"date","description":"Announced delivery date"},"announced_delivery_date_min":{"type":["string","null"],"format":"date","title":"Announced Delivery Date (min)","description":"Announced delivery date range of order (min)"},"announced_delivery_date_max":{"type":["string","null"],"format":"date","title":"Announced Delivery Date (max)","description":"Announced delivery date range of order (min)"},"articles_order":{"items":{"$ref":"#/components/schemas/LineItemOrder"},"type":"array"},"billing_address":{"anyOf":[{"$ref":"#/components/schemas/AddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"timezone":{"type":"string","description":"Timezone of the recipient, if known, not required, but strongly recommended"},"order_status":{"type":"string","description":"Current status of the order, as setup in the system","maxLength":255},"has_multiple_shipments":{"type":["boolean","null"],"description":"Indicates this order has been split into multiple shipments"},"cancelled_date":{"type":["string","null"],"format":"date-time","title":"Cancelled At","description":"Datetime when the order was cancelled"},"cancelled_reason":{"allOf":[{"$ref":"#/components/schemas/CancelledReasonEnum"}],"description":"Reason for cancellation\n\n* `customer` - Customer\n* `inventory` - Inventory\n* `payment` - Payment-related\n* `other` - Other"},"additional_attributes":{"items":{"$ref":"#/components/schemas/AdditionalAttribute"},"type":"array"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"description":"Tags for the object, format <key>:<value>e.g. 'category:Home Apparel'"},"mutations":{"items":{"anyOf":[{"$ref":"#/components/schemas/AddOrUpdateTrackingMutation"},{"$ref":"#/components/schemas/CancelTrackingMutation"},{"$ref":"#/components/schemas/CancelOrderMutation"},{"$ref":"#/components/schemas/ChangeLineItemQuantityMutation"},{"$ref":"#/components/schemas/AddLineItemMutation"},{"$ref":"#/components/schemas/ReplaceLineItemMutation"}],"title":"Order Mutations"},"type":"array"}}},"AddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"Empty":{"additionalProperties":false,"properties":{},"title":"Empty","type":"object"},"AdditionalRecipient":{"properties":{"role":{"description":"Role of the additional recipient","title":"Role","type":"string"},"email":{"description":"Email address of the additional recipient","title":"Email","type":"string"}},"title":"AdditionalRecipient","type":"object"},"LineItemOrder":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"description":"Line Item ID in the order (preferred when provided)","title":"Order Line Item ID","type":"string"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"},"status":{"allOf":[{"$ref":"#/components/schemas/LineItemOrderStatusEnum"}],"title":"Status"},"original_quantity":{"description":"Original quantity before any adjustments (automatically set by system)","title":"Original Quantity","type":"integer"},"change_reason":{"description":"Reason for the most recent quantity change","title":"Change Reason","type":"string"},"updated_at":{"description":"Timestamp when this line item was last updated","format":"date-time","title":"Updated At","type":"string"}},"required":["line_item_id"],"title":"Line Item Tracking","type":"object"},"LineItemVersionEnum":{"enum":["v1","v2"],"title":"LineItemVersionEnum","type":"string"},"WeightUnitEnum":{"enum":["kg","g","lbs","oz"],"type":"string"},"BundleInfo":{"additionalProperties":true,"properties":{"group_id":{"description":"Bundle group identifier in the retailer's system.","title":"Bundle Group ID","type":"string"},"role":{"$ref":"#/components/schemas/BundleRoleEnum","description":"Whether this line item represents a bundle parent or a bundle component.","title":"Bundle Role"},"return_policy":{"$ref":"#/components/schemas/BundleReturnPolicyEnum","default":"components_only","description":"Which lines in this bundle group are selectable for return.","title":"Bundle Return Policy"},"parent_product_id":{"description":"Parent bundle product identifier in the retailer's system.","title":"Bundle Parent Product ID","type":"string"},"parent_variant_id":{"description":"Parent bundle variant identifier in the retailer's system.","title":"Bundle Parent Variant ID","type":"string"},"parent_sku":{"description":"Parent bundle SKU, if available.","title":"Bundle Parent SKU","type":"string"},"parent_title":{"description":"Display title for the bundle parent, if available.","title":"Bundle Parent Title","type":"string"},"parent_quantity":{"description":"Quantity of the bundle parent purchased in the order.","title":"Bundle Parent Quantity","type":"integer"},"component_quantity_per_parent":{"description":"Component quantity per single bundle parent (if determinable).","title":"Bundle Component Quantity Per Parent","type":"integer"},"allocation_method":{"$ref":"#/components/schemas/BundleAllocationMethodEnum","default":"none","description":"How pricing was allocated to bundle components.","title":"Bundle Allocation Method"},"allocated_unit_price":{"description":"Snapshot of allocated component unit price (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Unit Price","type":"string"},"allocated_amount_invoiced":{"description":"Snapshot of allocated component invoiced amount (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Amount Invoiced","type":"string"}},"required":["group_id","role"],"title":"Bundle Info","type":"object"},"BundleRoleEnum":{"enum":["parent","component"],"title":"BundleRoleEnum","type":"string"},"BundleReturnPolicyEnum":{"enum":["parent_only","components_only","parent_and_components"],"title":"BundleReturnPolicyEnum","type":"string"},"BundleAllocationMethodEnum":{"enum":["none","component_price","msrp_ratio","equal"],"title":"BundleAllocationMethodEnum","type":"string"},"AdditionalAttribute":{"properties":{"key":{"description":"The key of the additional attribute","title":"Key","type":"string"},"value":{"default":null,"description":"The value of the additional attribute","title":"Value"}},"required":["key"],"title":"AdditionalAttribute","type":"object"},"LineItemOrderStatusEnum":{"enum":["shipped","pending","processing","cancelled","returned"],"type":"string"},"CancelledReasonEnum":{"enum":["customer","inventory","payment","other"],"type":"string","description":"* `customer` - Customer\n* `inventory` - Inventory\n* `payment` - Payment-related\n* `other` - Other"},"AddOrUpdateTrackingMutation":{"description":"Add or update tracking data.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"add_tracking","default":"add_tracking","title":"Type","type":"string"},"tracking":{"$ref":"#/components/schemas/TrackingSchema","description":"Tracking data"}},"required":["tracking"],"title":"AddOrUpdateTrackingMutation","type":"object"},"MutationResult":{"description":"The result of a mutation","properties":{"success":{"default":false,"description":"Whether the mutation was successful","title":"Success","type":"boolean"},"message":{"default":"","description":"A message describing the result of the mutation","title":"Message","type":"string"},"errors":{"additionalProperties":{"type":"string"},"description":"A dictionary of errors that occurred during the mutation","title":"Errors","type":"object"},"warnings":{"description":"Non-fatal warnings raised while processing the mutation","items":{"type":"string"},"title":"Warnings","type":"array"}},"title":"MutationResult","type":"object"},"TrackingSchema":{"description":"Tracking model used by v4 API in conjunction with order model","properties":{"tracking_number":{"description":"Tracking number of the shipment, if available. If no tracking number is available, transport number, consignment number or reference number should be used.","title":"Tracking Number","type":"string"},"client_key":{"description":"Name of the client (e.g. brand), as configured in account setup.","title":"Client Key","type":"string"},"courier":{"description":"Key of the courier, if available (required, unless transport number, consignment number or reference number are provided)","title":"Courier","type":"string"},"external_reference":{"description":"Unique retailer-provided reference of the shipment, either this tracking number is required","title":"External Reference","type":"string"},"recipient_postal_code":{"description":"Postal (zip) code of the recipient, frequently required for authentication of carrier data requests, or on the order statsu page. Must be provided if full shipping address is not available.","title":"Postal Code","type":"string"},"recipient_phone":{"description":"Recipient phone number, if known, may be required for communication","title":"Recipient Phone Number","type":"string"},"destination_country_iso3":{"description":"ISO 3166-1 alpha-3 code of the destination country, if different from order destination country","pattern":"^\\w{3}$","title":"Destination Country ISO3","type":"string"},"language_iso2":{"description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3,"title":"Language ISO2","type":"string"},"timezone":{"description":"Timezone of the recipient, if known, required for localized communication","title":"Timezone","type":"string"},"courier_service_level":{"description":"Service level of the courier, if known","title":"Courier Service Level","type":"string"},"delivery_method":{"description":"Delivery method (e.g. 'standard shipping'), needs to be set up in the system","title":"Delivery Method","type":"string"},"shipping_address":{"anyOf":[{"$ref":"#/components/schemas/AddressSchema"},{"$ref":"#/components/schemas/Empty"}],"description":"Recipient address, if different from order","title":"Recipient Address"},"recipient_email":{"description":"Recipient email address, if different from order","title":"Recipient Email","type":"string"},"recipient_name":{"description":"Recipient name used in messages (e.g. 'Max'), if different from order","title":"Recipient Name (for notifications))","type":"string"},"additional_recipients":{"description":"Additional recipients with role and email","items":{"$ref":"#/components/schemas/AdditionalRecipient"},"title":"Additional Recipients","type":"array"},"cancelled_date":{"description":"Date when the tracking was cancelled","format":"date-time","title":"Cancelled Date","type":"string"},"is_return":{"description":"Whether the tracking is return or pre-generated return label","title":"Is Return Label","type":"boolean"},"identifiers_consignment":{"description":"Consignment of the shipment","title":"Consignment","type":"string"},"delivery_number":{"description":"Number of shipment in order","title":"Delivery (Package) Number","type":"string"},"invoice_number":{"description":"Invoice number of the shipment","title":"Invoice Number","type":"string"},"shipping_cost_total":{"description":"Total cost of shipping","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Shipping Cost","type":"string"},"shipping_cost_net":{"description":"Net amount for shipping","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Shipping Cost Net Amount","type":"string"},"shipping_cost_discount":{"description":"Discount amount for shipping","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Shipping Discount","type":"string"},"shipping_weight_total":{"description":"Total weight of the shipment","title":"Shipping Weight Total","type":"number"},"shipping_weight_unit":{"anyOf":[{"$ref":"#/components/schemas/ShippingWeightUnitEnum"},{"type":"null"}],"default":"g","description":"Unit for total shipping weight","title":"Shipping Weight Unit"},"shipping_volume_total":{"description":"Total volume of the shipment","title":"Shipping Volume Total","type":"number"},"shipping_volume_unit":{"description":"Unit for total shipping volume","title":"Shipping Volume Unit","type":"string"},"shipping_height":{"description":"Total height of the shipment","title":"Shipping Height","type":"number"},"shipping_width":{"description":"Total width of the shipment","title":"Shipping Width","type":"number"},"shipping_length":{"description":"Total length of the shipment","title":"Shipping Length","type":"number"},"shipping_dimensions_unit":{"anyOf":[{"enum":["mm","cm","m"],"type":"string"},{"type":"null"}],"default":"mm","description":"Unit for shipping dimensions (height, width, length)","title":"Shipping Dimensions Unit"},"requires_signature":{"description":"Whether the shipment requires a signature","title":"Requires Signature","type":"boolean"},"is_dropshipment":{"description":"Is Dropshipment","title":"Is Dropshipment","type":"boolean"},"transport_number":{"description":"Transport number of the shipment, if available. If no transport number is available, consignment number or reference number must be used.","title":"Transport Number","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of origin country, if known","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"origin_region":{"description":"Origin region code (ISO 3166-2) of the shipment, if known","maxLength":20,"title":"Origin Region","type":"string"},"origin_postal_code":{"description":"Origin postal (zip) code of the shipment, if known","title":"Origin Postal Code","type":"string"},"articles":{"description":"List of articles in the shipment","items":{"$ref":"#/components/schemas/LineItem"},"title":"Articles","type":"array"},"warehouse":{"description":"Warehouse code of originating warehouse, if known, required for EDD calculation","title":"Warehouse","type":"string"},"courier_contact_name":{"description":"Courier Contact Name","title":"Courier Contact Name","type":"string"},"courier_contact_phone":{"description":"Courier contact phone number, if known","title":"Courier Contact Phone","type":"string"},"courier_contact_email":{"description":"Courier contact email address, if known","title":"Courier Contact Email","type":"string"},"review_link":{"description":"Link to review the delivery","title":"Review Link","type":"string"},"status_link":{"description":"Link to track the status of the delivery","title":"Status Link","type":"string"},"collection_code_retailer":{"description":"Collection code of the shipment, if known","title":"Collection Code","type":"string"},"collection_code_carrier":{"description":"Collection code of the shipment, if known","title":"Collection Code","type":"string"},"announced_send_date":{"description":"Announced send date of the shipment","format":"date","title":"Announced Send Date","type":"string"},"announced_delivery_date":{"description":"Announced delivery date","format":"date","title":"Announced Delivery Date","type":"string"},"announced_delivery_date_min":{"description":"Announced delivery date range","format":"date","title":"Announced Delivery Date Range","type":"string"},"announced_delivery_date_max":{"description":"Announced delivery date range","format":"date","title":"Announced Delivery Date Range","type":"string"},"notifications_inactive":{"description":"Notifications are inactive","title":"Notifications Inactive","type":"boolean"},"flags":{"description":"Extra flags for the tracking","items":{"$ref":"#/components/schemas/TrackingFlagEnum"},"title":"Flags","type":"array"},"cash_on_delivery_amount":{"description":"Cash on delivery amount","title":"Cash on Delivery","type":"number"},"tags":{"description":"Tags for the tracking, format <key>:<value>, e.g. 'category:Home Apparel","items":{"type":"string"},"title":"Tags","type":"array"},"checkpoints":{"description":"List of checkpoints for the tracking","items":{"$ref":"#/components/schemas/CheckpointSchema"},"title":"Checkpoints","type":"array"},"additional_fields":{"description":"Additional (customer defined) data-fields for the tracking. Example: {\"seller_organization_code\": \"PL_01\", \"pickupBoxNo\": \"48\"}","title":"Additional Fields"}},"title":"Tracking","type":"object"},"ShippingWeightUnitEnum":{"description":"Weight unit for shipping measurements.","enum":["g","kg","lbs"],"title":"ShippingWeightUnitEnum","type":"string"},"LineItem":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"description":"Line Item ID in the order (preferred when provided)","title":"Order Line Item ID","type":"string"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"}},"required":["line_item_id"],"title":"Line Item","type":"object"},"TrackingFlagEnum":{"enum":["complete","upgrade","cash_on_delivery","branch_delivery","doorstep_delivery"],"title":"TrackingFlagEnum","type":"string"},"CheckpointSchema":{"properties":{"status_code":{"title":"Status Code","type":"string"},"message":{"title":"Message","type":"string"},"courier":{"title":"Courier","type":"string"},"exception":{"items":{"type":"string"},"title":"Exception","type":"array"},"delivery_location":{"title":"Delivery Location","type":"string"},"event_timestamp":{"format":"date-time","title":"Event Timestamp","type":"string"},"courier_status":{"title":"Courier Status","type":"string"}},"required":["status_code","message","event_timestamp","courier_status"],"title":"CheckpointSchema","type":"object"},"CancelTrackingMutation":{"description":"Cancel tracking data.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"cancel_tracking","title":"Type","type":"string"},"tracking":{"$ref":"#/components/schemas/TrackingSchema","description":"The tracking to cancel, only identifiers need to be provided (tracking number + courier or external_reference)"}},"required":["type","tracking"],"title":"CancelTrackingMutation","type":"object"},"CancelOrderMutation":{"description":"Cancel an order.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"cancel_order","default":"cancel_order","title":"Type","type":"string"},"cancelled_reason":{"anyOf":[{"$ref":"#/components/schemas/OrderCancelReason"},{"type":"null"}],"default":null,"description":"Reason for the order cancellation","title":"Cancelled Reason"},"cancelled_date":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"Datetime when the order was cancelled","title":"Cancelled At"}},"title":"CancelOrderMutation","type":"object"},"OrderCancelReason":{"enum":["customer","inventory","payment","other"],"title":"OrderCancelReason","type":"string"},"ChangeLineItemQuantityMutation":{"description":"Set absolute quantity for an existing line item (0 = cancel).","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"change_line_item_quantity","default":"change_line_item_quantity","title":"Type","type":"string"},"line_item_id":{"description":"ID of the line item to update","title":"Line Item ID","type":"string"},"quantity":{"description":"Absolute quantity to set (0 = cancel)","exclusiveMinimum":-1,"title":"New Quantity","type":"integer"},"current_quantity":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"If set, mutation is applied only when stored quantity matches this value","title":"Current Quantity Guard"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Reason for the change","title":"Reason"}},"required":["line_item_id","quantity"],"title":"ChangeLineItemQuantityMutation","type":"object"},"AddLineItemMutation":{"description":"Append a brand-new line item to the order.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"add_line_item","default":"add_line_item","title":"Type","type":"string"},"line_item":{"$ref":"#/components/schemas/LineItemOrder","description":"Line item data to append","title":"Line Item"}},"required":["line_item"],"title":"AddLineItemMutation","type":"object"},"ReplaceLineItemMutation":{"description":"Cancel old line item & add substitute atomically.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"replace_line_item","default":"replace_line_item","title":"Type","type":"string"},"old_line_item_id":{"description":"Line item to be replaced (cancelled)","title":"Old Line Item ID","type":"string"},"new_line_item":{"$ref":"#/components/schemas/LineItemOrder","description":"Replacement line item data","title":"New Line Item"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Reason for replacement","title":"Reason"}},"required":["old_line_item_id","new_line_item"],"title":"ReplaceLineItemMutation","type":"object"},"Order":{"type":"object","description":"Create a new order record with shipment and recipient data.","properties":{"account":{"type":"integer","description":"Account to which this order belongs"},"order_number":{"type":"string","description":"Order number (customer facing)","maxLength":255},"external_id":{"type":"string","readOnly":true,"title":"External Identifier","description":"Unique identifier for this order, generated by parcelLab for this order"},"external_reference":{"type":"string","title":"Reference Identifier","description":"Retailer reference (e.g. internal system ID) for this order, unique.","maxLength":255},"client_key":{"type":"string","description":"Name of the technical client / shop (corresponds to the system setup), e.g. 'mybrand-a.com'","maxLength":512},"destination_country_iso3":{"type":"string","description":"Destination country ISO 3166-1 alpha 3 code","maxLength":3},"language_iso2":{"type":"string","description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3},"shipping_address":{"anyOf":[{"$ref":"#/components/schemas/AddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"delivery_method":{"type":"string","description":"Delivery method (e.g. 'standard shipping'), needs to be set up in the system","maxLength":255},"recipient_email":{"anyOf":[{"format":"email","type":"string"},{"const":"_unset","enum":["_unset"],"type":"string"}],"description":"Recipient email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead."},"recipient_name":{"type":"string","title":"Recipient name shown on notifications","description":"Recipient name","maxLength":255},"additional_recipients":{"items":{"$ref":"#/components/schemas/AdditionalRecipient"},"type":"array"},"customer_number":{"type":"string","description":"Customer number (e.g. from the retailer)","maxLength":255},"invoice_number":{"type":"string","description":"Invoice number (e.g. from the retailer)","maxLength":255},"payment_method":{"type":"string","description":"Payment method (e.g. 'credit card')","maxLength":255},"order_total_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total amount of the order (usually after tax & discount)"},"order_tax_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Tax amount of the original order"},"order_net_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Net amount of the order (usually before tax)"},"order_discount_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Discount amount of the order"},"order_currency":{"type":"string","description":"Currency of the order, e.g. USD, EUR (ISO 4217)","maxLength":3},"payments":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"order_date":{"type":["string","null"],"format":"date-time","description":"Date and time when the order was placed"},"channel":{"type":"string","description":"Channel through which the order was placed (e.g. 'webshop')","maxLength":255},"announced_delivery_date":{"type":["string","null"],"format":"date","description":"Announced delivery date"},"announced_delivery_date_min":{"type":["string","null"],"format":"date","title":"Announced Delivery Date (min)","description":"Announced delivery date range of order (min)"},"announced_delivery_date_max":{"type":["string","null"],"format":"date","title":"Announced Delivery Date (max)","description":"Announced delivery date range of order (min)"},"articles_order":{"items":{"$ref":"#/components/schemas/LineItemOrder"},"type":"array"},"billing_address":{"anyOf":[{"$ref":"#/components/schemas/AddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"timezone":{"type":"string","description":"Timezone of the recipient, if known, not required, but strongly recommended"},"order_status":{"type":"string","description":"Current status of the order, as setup in the system","maxLength":255},"has_multiple_shipments":{"type":["boolean","null"],"description":"Indicates this order has been split into multiple shipments"},"cancelled_date":{"type":["string","null"],"format":"date-time","title":"Cancelled At","description":"Datetime when the order was cancelled"},"cancelled_reason":{"allOf":[{"$ref":"#/components/schemas/CancelledReasonEnum"}],"description":"Reason for cancellation\n\n* `customer` - Customer\n* `inventory` - Inventory\n* `payment` - Payment-related\n* `other` - Other"},"additional_attributes":{"items":{"$ref":"#/components/schemas/AdditionalAttribute"},"type":"array"},"tags":{"type":"array","items":{"type":"string","maxLength":255},"description":"Tags for the object, format <key>:<value>e.g. 'category:Home Apparel'"},"mutations":{"items":{"anyOf":[{"$ref":"#/components/schemas/AddOrUpdateTrackingMutation"},{"$ref":"#/components/schemas/CancelTrackingMutation"},{"$ref":"#/components/schemas/CancelOrderMutation"},{"$ref":"#/components/schemas/ChangeLineItemQuantityMutation"},{"$ref":"#/components/schemas/AddLineItemMutation"},{"$ref":"#/components/schemas/ReplaceLineItemMutation"}],"title":"Order Mutations"},"type":"array"}},"required":["account","destination_country_iso3","external_id","order_number","recipient_email"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}},"paths":{"/v4/track/orders/":{"put":{"operationId":"track_orders_update","description":"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.\n\n\nPayload validation:\n\n- Request-blocking validation failures return HTTP 400 and no order or mutation\n  history is written. Serializer and Pydantic validation errors use the standard\n  `{\"type\": \"client_error\", \"errors\": [...]}` shape. Early order identifier and\n  account authorization failures return `{\"detail\": \"...\"}`.\n- `recipient_email` must be a valid email address or the literal `_unset`.\n- Country, language, currency, timezone, enum, date, datetime, decimal, length,\n  and required-field validations are enforced at the request boundary.\n- `shipping_address` and tracking-level `shipping_address` are strictly\n  validated, including region codes. `billing_address` uses the more permissive\n  address schema and can coerce invalid region codes to `null`.\n- Mutation payloads must use a supported `type`. Tracking mutations require\n  either `tracking_number` plus `courier`, or `external_reference`.\n- Tracking-level `delivery_method` must be configured for the account.\n- `add_tracking` with `tracking_number` plus `courier` performs a best-effort\n  same-account conflict check before enqueueing. The check is eventually\n  consistent and Backend persistence still enforces downstream uniqueness.\n\nSuccessful responses can still contain per-mutation validation information:\n\n- Non-fatal validation warnings are returned in\n  `mutations[].result.warnings`. Today this covers dropped unrecognized\n  `add_tracking.tracking` fields and `articles_order` replacement warnings\n  when mutations are present.\n- Accepted mutation failures do not reject the whole request. The HTTP response\n  remains 200 or 201, while the affected mutation returns\n  `mutations[].result.success=false`.\n","summary":"Create or Update Order (recommended)","tags":["Order"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchedOrderRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/PatchedOrderRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PatchedOrderRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}},"description":"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`."},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}},"description":"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`."},"400":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail","attr"]}}},"required":["type","errors"]},{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}]}}},"description":"Bad request. Payload validation errors use the standard error list shape. Early order identifier and account authorization failures use a direct detail response."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}}}
```

## Create a Tracking/Order

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

{% hint style="info" %}
The same endpoint is used to create and update a tracking and order. For further information, see [how to update an order](#create-or-update-a-tracking-order).
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

## Create Order

> 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\
> &#x20; history is written. Serializer and Pydantic validation errors use the standard\
> &#x20; \`{"type": "client\_error", "errors": \[...]}\` shape. Early order identifier and\
> &#x20; 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,\
> &#x20; and required-field validations are enforced at the request boundary.\
> \- \`shipping\_address\` and tracking-level \`shipping\_address\` are strictly\
> &#x20; validated, including region codes. \`billing\_address\` uses the more permissive\
> &#x20; address schema and can coerce invalid region codes to \`null\`.\
> \- Mutation payloads must use a supported \`type\`. Tracking mutations require\
> &#x20; 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\
> &#x20; same-account conflict check before enqueueing. The check is eventually\
> &#x20; consistent and Backend persistence still enforces downstream uniqueness.\
> \
> Successful responses can still contain per-mutation validation information:\
> \
> \- Non-fatal validation warnings are returned in\
> &#x20; \`mutations\[].result.warnings\`. Today this covers dropped unrecognized\
> &#x20; \`add\_tracking.tracking\` fields and \`articles\_order\` replacement warnings\
> &#x20; when mutations are present.\
> \- Accepted mutation failures do not reject the whole request. The HTTP response\
> &#x20; remains 200 or 201, while the affected mutation returns\
> &#x20; \`mutations\[].result.success=false\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token <encoded-token>`.\n\n`<encoded-token>` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"OrderRequest":{"type":"object","description":"Create a new order record with shipment and recipient data.","properties":{"account":{"type":"integer","description":"Account to which this order belongs"},"order_number":{"type":"string","minLength":1,"description":"Order number (customer facing)","maxLength":255},"external_reference":{"type":"string","title":"Reference Identifier","description":"Retailer reference (e.g. internal system ID) for this order, unique.","maxLength":255},"client_key":{"type":"string","description":"Name of the technical client / shop (corresponds to the system setup), e.g. 'mybrand-a.com'","maxLength":512},"destination_country_iso3":{"type":"string","minLength":1,"description":"Destination country ISO 3166-1 alpha 3 code","maxLength":3},"language_iso2":{"type":"string","description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3},"shipping_address":{"anyOf":[{"$ref":"#/components/schemas/AddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"delivery_method":{"type":"string","description":"Delivery method (e.g. 'standard shipping'), needs to be set up in the system","maxLength":255},"recipient_email":{"anyOf":[{"format":"email","type":"string"},{"const":"_unset","enum":["_unset"],"type":"string"}],"minLength":1,"description":"Recipient email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead."},"recipient_name":{"type":"string","title":"Recipient name shown on notifications","description":"Recipient name","maxLength":255},"additional_recipients":{"items":{"$ref":"#/components/schemas/AdditionalRecipient"},"type":"array"},"customer_number":{"type":"string","description":"Customer number (e.g. from the retailer)","maxLength":255},"invoice_number":{"type":"string","description":"Invoice number (e.g. from the retailer)","maxLength":255},"payment_method":{"type":"string","description":"Payment method (e.g. 'credit card')","maxLength":255},"order_total_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total amount of the order (usually after tax & discount)"},"order_tax_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Tax amount of the original order"},"order_net_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Net amount of the order (usually before tax)"},"order_discount_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Discount amount of the order"},"order_currency":{"type":"string","description":"Currency of the order, e.g. USD, EUR (ISO 4217)","maxLength":3},"payments":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"order_date":{"type":["string","null"],"format":"date-time","description":"Date and time when the order was placed"},"channel":{"type":"string","description":"Channel through which the order was placed (e.g. 'webshop')","maxLength":255},"announced_delivery_date":{"type":["string","null"],"format":"date","description":"Announced delivery date"},"announced_delivery_date_min":{"type":["string","null"],"format":"date","title":"Announced Delivery Date (min)","description":"Announced delivery date range of order (min)"},"announced_delivery_date_max":{"type":["string","null"],"format":"date","title":"Announced Delivery Date (max)","description":"Announced delivery date range of order (min)"},"articles_order":{"items":{"$ref":"#/components/schemas/LineItemOrder"},"type":"array"},"billing_address":{"anyOf":[{"$ref":"#/components/schemas/AddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"timezone":{"type":"string","description":"Timezone of the recipient, if known, not required, but strongly recommended"},"order_status":{"type":"string","description":"Current status of the order, as setup in the system","maxLength":255},"has_multiple_shipments":{"type":["boolean","null"],"description":"Indicates this order has been split into multiple shipments"},"cancelled_date":{"type":["string","null"],"format":"date-time","title":"Cancelled At","description":"Datetime when the order was cancelled"},"cancelled_reason":{"allOf":[{"$ref":"#/components/schemas/CancelledReasonEnum"}],"description":"Reason for cancellation\n\n* `customer` - Customer\n* `inventory` - Inventory\n* `payment` - Payment-related\n* `other` - Other"},"additional_attributes":{"items":{"$ref":"#/components/schemas/AdditionalAttribute"},"type":"array"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"description":"Tags for the object, format <key>:<value>e.g. 'category:Home Apparel'"},"mutations":{"items":{"anyOf":[{"$ref":"#/components/schemas/AddOrUpdateTrackingMutation"},{"$ref":"#/components/schemas/CancelTrackingMutation"},{"$ref":"#/components/schemas/CancelOrderMutation"},{"$ref":"#/components/schemas/ChangeLineItemQuantityMutation"},{"$ref":"#/components/schemas/AddLineItemMutation"},{"$ref":"#/components/schemas/ReplaceLineItemMutation"}],"title":"Order Mutations"},"type":"array"}},"required":["account","destination_country_iso3","order_number","recipient_email"]},"AddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"Empty":{"additionalProperties":false,"properties":{},"title":"Empty","type":"object"},"AdditionalRecipient":{"properties":{"role":{"description":"Role of the additional recipient","title":"Role","type":"string"},"email":{"description":"Email address of the additional recipient","title":"Email","type":"string"}},"title":"AdditionalRecipient","type":"object"},"LineItemOrder":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"description":"Line Item ID in the order (preferred when provided)","title":"Order Line Item ID","type":"string"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"},"status":{"allOf":[{"$ref":"#/components/schemas/LineItemOrderStatusEnum"}],"title":"Status"},"original_quantity":{"description":"Original quantity before any adjustments (automatically set by system)","title":"Original Quantity","type":"integer"},"change_reason":{"description":"Reason for the most recent quantity change","title":"Change Reason","type":"string"},"updated_at":{"description":"Timestamp when this line item was last updated","format":"date-time","title":"Updated At","type":"string"}},"required":["line_item_id"],"title":"Line Item Tracking","type":"object"},"LineItemVersionEnum":{"enum":["v1","v2"],"title":"LineItemVersionEnum","type":"string"},"WeightUnitEnum":{"enum":["kg","g","lbs","oz"],"type":"string"},"BundleInfo":{"additionalProperties":true,"properties":{"group_id":{"description":"Bundle group identifier in the retailer's system.","title":"Bundle Group ID","type":"string"},"role":{"$ref":"#/components/schemas/BundleRoleEnum","description":"Whether this line item represents a bundle parent or a bundle component.","title":"Bundle Role"},"return_policy":{"$ref":"#/components/schemas/BundleReturnPolicyEnum","default":"components_only","description":"Which lines in this bundle group are selectable for return.","title":"Bundle Return Policy"},"parent_product_id":{"description":"Parent bundle product identifier in the retailer's system.","title":"Bundle Parent Product ID","type":"string"},"parent_variant_id":{"description":"Parent bundle variant identifier in the retailer's system.","title":"Bundle Parent Variant ID","type":"string"},"parent_sku":{"description":"Parent bundle SKU, if available.","title":"Bundle Parent SKU","type":"string"},"parent_title":{"description":"Display title for the bundle parent, if available.","title":"Bundle Parent Title","type":"string"},"parent_quantity":{"description":"Quantity of the bundle parent purchased in the order.","title":"Bundle Parent Quantity","type":"integer"},"component_quantity_per_parent":{"description":"Component quantity per single bundle parent (if determinable).","title":"Bundle Component Quantity Per Parent","type":"integer"},"allocation_method":{"$ref":"#/components/schemas/BundleAllocationMethodEnum","default":"none","description":"How pricing was allocated to bundle components.","title":"Bundle Allocation Method"},"allocated_unit_price":{"description":"Snapshot of allocated component unit price (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Unit Price","type":"string"},"allocated_amount_invoiced":{"description":"Snapshot of allocated component invoiced amount (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Amount Invoiced","type":"string"}},"required":["group_id","role"],"title":"Bundle Info","type":"object"},"BundleRoleEnum":{"enum":["parent","component"],"title":"BundleRoleEnum","type":"string"},"BundleReturnPolicyEnum":{"enum":["parent_only","components_only","parent_and_components"],"title":"BundleReturnPolicyEnum","type":"string"},"BundleAllocationMethodEnum":{"enum":["none","component_price","msrp_ratio","equal"],"title":"BundleAllocationMethodEnum","type":"string"},"AdditionalAttribute":{"properties":{"key":{"description":"The key of the additional attribute","title":"Key","type":"string"},"value":{"default":null,"description":"The value of the additional attribute","title":"Value"}},"required":["key"],"title":"AdditionalAttribute","type":"object"},"LineItemOrderStatusEnum":{"enum":["shipped","pending","processing","cancelled","returned"],"type":"string"},"CancelledReasonEnum":{"enum":["customer","inventory","payment","other"],"type":"string","description":"* `customer` - Customer\n* `inventory` - Inventory\n* `payment` - Payment-related\n* `other` - Other"},"AddOrUpdateTrackingMutation":{"description":"Add or update tracking data.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"add_tracking","default":"add_tracking","title":"Type","type":"string"},"tracking":{"$ref":"#/components/schemas/TrackingSchema","description":"Tracking data"}},"required":["tracking"],"title":"AddOrUpdateTrackingMutation","type":"object"},"MutationResult":{"description":"The result of a mutation","properties":{"success":{"default":false,"description":"Whether the mutation was successful","title":"Success","type":"boolean"},"message":{"default":"","description":"A message describing the result of the mutation","title":"Message","type":"string"},"errors":{"additionalProperties":{"type":"string"},"description":"A dictionary of errors that occurred during the mutation","title":"Errors","type":"object"},"warnings":{"description":"Non-fatal warnings raised while processing the mutation","items":{"type":"string"},"title":"Warnings","type":"array"}},"title":"MutationResult","type":"object"},"TrackingSchema":{"description":"Tracking model used by v4 API in conjunction with order model","properties":{"tracking_number":{"description":"Tracking number of the shipment, if available. If no tracking number is available, transport number, consignment number or reference number should be used.","title":"Tracking Number","type":"string"},"client_key":{"description":"Name of the client (e.g. brand), as configured in account setup.","title":"Client Key","type":"string"},"courier":{"description":"Key of the courier, if available (required, unless transport number, consignment number or reference number are provided)","title":"Courier","type":"string"},"external_reference":{"description":"Unique retailer-provided reference of the shipment, either this tracking number is required","title":"External Reference","type":"string"},"recipient_postal_code":{"description":"Postal (zip) code of the recipient, frequently required for authentication of carrier data requests, or on the order statsu page. Must be provided if full shipping address is not available.","title":"Postal Code","type":"string"},"recipient_phone":{"description":"Recipient phone number, if known, may be required for communication","title":"Recipient Phone Number","type":"string"},"destination_country_iso3":{"description":"ISO 3166-1 alpha-3 code of the destination country, if different from order destination country","pattern":"^\\w{3}$","title":"Destination Country ISO3","type":"string"},"language_iso2":{"description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3,"title":"Language ISO2","type":"string"},"timezone":{"description":"Timezone of the recipient, if known, required for localized communication","title":"Timezone","type":"string"},"courier_service_level":{"description":"Service level of the courier, if known","title":"Courier Service Level","type":"string"},"delivery_method":{"description":"Delivery method (e.g. 'standard shipping'), needs to be set up in the system","title":"Delivery Method","type":"string"},"shipping_address":{"anyOf":[{"$ref":"#/components/schemas/AddressSchema"},{"$ref":"#/components/schemas/Empty"}],"description":"Recipient address, if different from order","title":"Recipient Address"},"recipient_email":{"description":"Recipient email address, if different from order","title":"Recipient Email","type":"string"},"recipient_name":{"description":"Recipient name used in messages (e.g. 'Max'), if different from order","title":"Recipient Name (for notifications))","type":"string"},"additional_recipients":{"description":"Additional recipients with role and email","items":{"$ref":"#/components/schemas/AdditionalRecipient"},"title":"Additional Recipients","type":"array"},"cancelled_date":{"description":"Date when the tracking was cancelled","format":"date-time","title":"Cancelled Date","type":"string"},"is_return":{"description":"Whether the tracking is return or pre-generated return label","title":"Is Return Label","type":"boolean"},"identifiers_consignment":{"description":"Consignment of the shipment","title":"Consignment","type":"string"},"delivery_number":{"description":"Number of shipment in order","title":"Delivery (Package) Number","type":"string"},"invoice_number":{"description":"Invoice number of the shipment","title":"Invoice Number","type":"string"},"shipping_cost_total":{"description":"Total cost of shipping","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Shipping Cost","type":"string"},"shipping_cost_net":{"description":"Net amount for shipping","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Shipping Cost Net Amount","type":"string"},"shipping_cost_discount":{"description":"Discount amount for shipping","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Shipping Discount","type":"string"},"shipping_weight_total":{"description":"Total weight of the shipment","title":"Shipping Weight Total","type":"number"},"shipping_weight_unit":{"anyOf":[{"$ref":"#/components/schemas/ShippingWeightUnitEnum"},{"type":"null"}],"default":"g","description":"Unit for total shipping weight","title":"Shipping Weight Unit"},"shipping_volume_total":{"description":"Total volume of the shipment","title":"Shipping Volume Total","type":"number"},"shipping_volume_unit":{"description":"Unit for total shipping volume","title":"Shipping Volume Unit","type":"string"},"shipping_height":{"description":"Total height of the shipment","title":"Shipping Height","type":"number"},"shipping_width":{"description":"Total width of the shipment","title":"Shipping Width","type":"number"},"shipping_length":{"description":"Total length of the shipment","title":"Shipping Length","type":"number"},"shipping_dimensions_unit":{"anyOf":[{"enum":["mm","cm","m"],"type":"string"},{"type":"null"}],"default":"mm","description":"Unit for shipping dimensions (height, width, length)","title":"Shipping Dimensions Unit"},"requires_signature":{"description":"Whether the shipment requires a signature","title":"Requires Signature","type":"boolean"},"is_dropshipment":{"description":"Is Dropshipment","title":"Is Dropshipment","type":"boolean"},"transport_number":{"description":"Transport number of the shipment, if available. If no transport number is available, consignment number or reference number must be used.","title":"Transport Number","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of origin country, if known","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"origin_region":{"description":"Origin region code (ISO 3166-2) of the shipment, if known","maxLength":20,"title":"Origin Region","type":"string"},"origin_postal_code":{"description":"Origin postal (zip) code of the shipment, if known","title":"Origin Postal Code","type":"string"},"articles":{"description":"List of articles in the shipment","items":{"$ref":"#/components/schemas/LineItem"},"title":"Articles","type":"array"},"warehouse":{"description":"Warehouse code of originating warehouse, if known, required for EDD calculation","title":"Warehouse","type":"string"},"courier_contact_name":{"description":"Courier Contact Name","title":"Courier Contact Name","type":"string"},"courier_contact_phone":{"description":"Courier contact phone number, if known","title":"Courier Contact Phone","type":"string"},"courier_contact_email":{"description":"Courier contact email address, if known","title":"Courier Contact Email","type":"string"},"review_link":{"description":"Link to review the delivery","title":"Review Link","type":"string"},"status_link":{"description":"Link to track the status of the delivery","title":"Status Link","type":"string"},"collection_code_retailer":{"description":"Collection code of the shipment, if known","title":"Collection Code","type":"string"},"collection_code_carrier":{"description":"Collection code of the shipment, if known","title":"Collection Code","type":"string"},"announced_send_date":{"description":"Announced send date of the shipment","format":"date","title":"Announced Send Date","type":"string"},"announced_delivery_date":{"description":"Announced delivery date","format":"date","title":"Announced Delivery Date","type":"string"},"announced_delivery_date_min":{"description":"Announced delivery date range","format":"date","title":"Announced Delivery Date Range","type":"string"},"announced_delivery_date_max":{"description":"Announced delivery date range","format":"date","title":"Announced Delivery Date Range","type":"string"},"notifications_inactive":{"description":"Notifications are inactive","title":"Notifications Inactive","type":"boolean"},"flags":{"description":"Extra flags for the tracking","items":{"$ref":"#/components/schemas/TrackingFlagEnum"},"title":"Flags","type":"array"},"cash_on_delivery_amount":{"description":"Cash on delivery amount","title":"Cash on Delivery","type":"number"},"tags":{"description":"Tags for the tracking, format <key>:<value>, e.g. 'category:Home Apparel","items":{"type":"string"},"title":"Tags","type":"array"},"checkpoints":{"description":"List of checkpoints for the tracking","items":{"$ref":"#/components/schemas/CheckpointSchema"},"title":"Checkpoints","type":"array"},"additional_fields":{"description":"Additional (customer defined) data-fields for the tracking. Example: {\"seller_organization_code\": \"PL_01\", \"pickupBoxNo\": \"48\"}","title":"Additional Fields"}},"title":"Tracking","type":"object"},"ShippingWeightUnitEnum":{"description":"Weight unit for shipping measurements.","enum":["g","kg","lbs"],"title":"ShippingWeightUnitEnum","type":"string"},"LineItem":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"description":"Line Item ID in the order (preferred when provided)","title":"Order Line Item ID","type":"string"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"}},"required":["line_item_id"],"title":"Line Item","type":"object"},"TrackingFlagEnum":{"enum":["complete","upgrade","cash_on_delivery","branch_delivery","doorstep_delivery"],"title":"TrackingFlagEnum","type":"string"},"CheckpointSchema":{"properties":{"status_code":{"title":"Status Code","type":"string"},"message":{"title":"Message","type":"string"},"courier":{"title":"Courier","type":"string"},"exception":{"items":{"type":"string"},"title":"Exception","type":"array"},"delivery_location":{"title":"Delivery Location","type":"string"},"event_timestamp":{"format":"date-time","title":"Event Timestamp","type":"string"},"courier_status":{"title":"Courier Status","type":"string"}},"required":["status_code","message","event_timestamp","courier_status"],"title":"CheckpointSchema","type":"object"},"CancelTrackingMutation":{"description":"Cancel tracking data.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"cancel_tracking","title":"Type","type":"string"},"tracking":{"$ref":"#/components/schemas/TrackingSchema","description":"The tracking to cancel, only identifiers need to be provided (tracking number + courier or external_reference)"}},"required":["type","tracking"],"title":"CancelTrackingMutation","type":"object"},"CancelOrderMutation":{"description":"Cancel an order.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"cancel_order","default":"cancel_order","title":"Type","type":"string"},"cancelled_reason":{"anyOf":[{"$ref":"#/components/schemas/OrderCancelReason"},{"type":"null"}],"default":null,"description":"Reason for the order cancellation","title":"Cancelled Reason"},"cancelled_date":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"Datetime when the order was cancelled","title":"Cancelled At"}},"title":"CancelOrderMutation","type":"object"},"OrderCancelReason":{"enum":["customer","inventory","payment","other"],"title":"OrderCancelReason","type":"string"},"ChangeLineItemQuantityMutation":{"description":"Set absolute quantity for an existing line item (0 = cancel).","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"change_line_item_quantity","default":"change_line_item_quantity","title":"Type","type":"string"},"line_item_id":{"description":"ID of the line item to update","title":"Line Item ID","type":"string"},"quantity":{"description":"Absolute quantity to set (0 = cancel)","exclusiveMinimum":-1,"title":"New Quantity","type":"integer"},"current_quantity":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"If set, mutation is applied only when stored quantity matches this value","title":"Current Quantity Guard"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Reason for the change","title":"Reason"}},"required":["line_item_id","quantity"],"title":"ChangeLineItemQuantityMutation","type":"object"},"AddLineItemMutation":{"description":"Append a brand-new line item to the order.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"add_line_item","default":"add_line_item","title":"Type","type":"string"},"line_item":{"$ref":"#/components/schemas/LineItemOrder","description":"Line item data to append","title":"Line Item"}},"required":["line_item"],"title":"AddLineItemMutation","type":"object"},"ReplaceLineItemMutation":{"description":"Cancel old line item & add substitute atomically.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"replace_line_item","default":"replace_line_item","title":"Type","type":"string"},"old_line_item_id":{"description":"Line item to be replaced (cancelled)","title":"Old Line Item ID","type":"string"},"new_line_item":{"$ref":"#/components/schemas/LineItemOrder","description":"Replacement line item data","title":"New Line Item"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Reason for replacement","title":"Reason"}},"required":["old_line_item_id","new_line_item"],"title":"ReplaceLineItemMutation","type":"object"},"Order":{"type":"object","description":"Create a new order record with shipment and recipient data.","properties":{"account":{"type":"integer","description":"Account to which this order belongs"},"order_number":{"type":"string","description":"Order number (customer facing)","maxLength":255},"external_id":{"type":"string","readOnly":true,"title":"External Identifier","description":"Unique identifier for this order, generated by parcelLab for this order"},"external_reference":{"type":"string","title":"Reference Identifier","description":"Retailer reference (e.g. internal system ID) for this order, unique.","maxLength":255},"client_key":{"type":"string","description":"Name of the technical client / shop (corresponds to the system setup), e.g. 'mybrand-a.com'","maxLength":512},"destination_country_iso3":{"type":"string","description":"Destination country ISO 3166-1 alpha 3 code","maxLength":3},"language_iso2":{"type":"string","description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3},"shipping_address":{"anyOf":[{"$ref":"#/components/schemas/AddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"delivery_method":{"type":"string","description":"Delivery method (e.g. 'standard shipping'), needs to be set up in the system","maxLength":255},"recipient_email":{"anyOf":[{"format":"email","type":"string"},{"const":"_unset","enum":["_unset"],"type":"string"}],"description":"Recipient email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead."},"recipient_name":{"type":"string","title":"Recipient name shown on notifications","description":"Recipient name","maxLength":255},"additional_recipients":{"items":{"$ref":"#/components/schemas/AdditionalRecipient"},"type":"array"},"customer_number":{"type":"string","description":"Customer number (e.g. from the retailer)","maxLength":255},"invoice_number":{"type":"string","description":"Invoice number (e.g. from the retailer)","maxLength":255},"payment_method":{"type":"string","description":"Payment method (e.g. 'credit card')","maxLength":255},"order_total_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total amount of the order (usually after tax & discount)"},"order_tax_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Tax amount of the original order"},"order_net_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Net amount of the order (usually before tax)"},"order_discount_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Discount amount of the order"},"order_currency":{"type":"string","description":"Currency of the order, e.g. USD, EUR (ISO 4217)","maxLength":3},"payments":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"order_date":{"type":["string","null"],"format":"date-time","description":"Date and time when the order was placed"},"channel":{"type":"string","description":"Channel through which the order was placed (e.g. 'webshop')","maxLength":255},"announced_delivery_date":{"type":["string","null"],"format":"date","description":"Announced delivery date"},"announced_delivery_date_min":{"type":["string","null"],"format":"date","title":"Announced Delivery Date (min)","description":"Announced delivery date range of order (min)"},"announced_delivery_date_max":{"type":["string","null"],"format":"date","title":"Announced Delivery Date (max)","description":"Announced delivery date range of order (min)"},"articles_order":{"items":{"$ref":"#/components/schemas/LineItemOrder"},"type":"array"},"billing_address":{"anyOf":[{"$ref":"#/components/schemas/AddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"timezone":{"type":"string","description":"Timezone of the recipient, if known, not required, but strongly recommended"},"order_status":{"type":"string","description":"Current status of the order, as setup in the system","maxLength":255},"has_multiple_shipments":{"type":["boolean","null"],"description":"Indicates this order has been split into multiple shipments"},"cancelled_date":{"type":["string","null"],"format":"date-time","title":"Cancelled At","description":"Datetime when the order was cancelled"},"cancelled_reason":{"allOf":[{"$ref":"#/components/schemas/CancelledReasonEnum"}],"description":"Reason for cancellation\n\n* `customer` - Customer\n* `inventory` - Inventory\n* `payment` - Payment-related\n* `other` - Other"},"additional_attributes":{"items":{"$ref":"#/components/schemas/AdditionalAttribute"},"type":"array"},"tags":{"type":"array","items":{"type":"string","maxLength":255},"description":"Tags for the object, format <key>:<value>e.g. 'category:Home Apparel'"},"mutations":{"items":{"anyOf":[{"$ref":"#/components/schemas/AddOrUpdateTrackingMutation"},{"$ref":"#/components/schemas/CancelTrackingMutation"},{"$ref":"#/components/schemas/CancelOrderMutation"},{"$ref":"#/components/schemas/ChangeLineItemQuantityMutation"},{"$ref":"#/components/schemas/AddLineItemMutation"},{"$ref":"#/components/schemas/ReplaceLineItemMutation"}],"title":"Order Mutations"},"type":"array"}},"required":["account","destination_country_iso3","external_id","order_number","recipient_email"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}},"paths":{"/v4/track/orders/":{"post":{"operationId":"track_orders_create","description":"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.\n\n\nPayload validation:\n\n- Request-blocking validation failures return HTTP 400 and no order or mutation\n  history is written. Serializer and Pydantic validation errors use the standard\n  `{\"type\": \"client_error\", \"errors\": [...]}` shape. Early order identifier and\n  account authorization failures return `{\"detail\": \"...\"}`.\n- `recipient_email` must be a valid email address or the literal `_unset`.\n- Country, language, currency, timezone, enum, date, datetime, decimal, length,\n  and required-field validations are enforced at the request boundary.\n- `shipping_address` and tracking-level `shipping_address` are strictly\n  validated, including region codes. `billing_address` uses the more permissive\n  address schema and can coerce invalid region codes to `null`.\n- Mutation payloads must use a supported `type`. Tracking mutations require\n  either `tracking_number` plus `courier`, or `external_reference`.\n- Tracking-level `delivery_method` must be configured for the account.\n- `add_tracking` with `tracking_number` plus `courier` performs a best-effort\n  same-account conflict check before enqueueing. The check is eventually\n  consistent and Backend persistence still enforces downstream uniqueness.\n\nSuccessful responses can still contain per-mutation validation information:\n\n- Non-fatal validation warnings are returned in\n  `mutations[].result.warnings`. Today this covers dropped unrecognized\n  `add_tracking.tracking` fields and `articles_order` replacement warnings\n  when mutations are present.\n- Accepted mutation failures do not reject the whole request. The HTTP response\n  remains 200 or 201, while the affected mutation returns\n  `mutations[].result.success=false`.\n","summary":"Create Order","tags":["Order"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/OrderRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/OrderRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}},"description":"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`."},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail","attr"]}}},"required":["type","errors"]}}},"description":"Bad request. Payload validation errors use the standard error list shape."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}}}
```

## Retrieve All Orders

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

## List Orders

> List all orders

```json
{"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token <encoded-token>`.\n\n`<encoded-token>` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"PaginatedOrderList":{"type":"object","required":["results"],"properties":{"next":{"type":"string","nullable":true,"format":"uri"},"previous":{"type":"string","nullable":true,"format":"uri"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}}},"Order":{"type":"object","description":"Create a new order record with shipment and recipient data.","properties":{"account":{"type":"integer","description":"Account to which this order belongs"},"order_number":{"type":"string","description":"Order number (customer facing)","maxLength":255},"external_id":{"type":"string","readOnly":true,"title":"External Identifier","description":"Unique identifier for this order, generated by parcelLab for this order"},"external_reference":{"type":"string","title":"Reference Identifier","description":"Retailer reference (e.g. internal system ID) for this order, unique.","maxLength":255},"client_key":{"type":"string","description":"Name of the technical client / shop (corresponds to the system setup), e.g. 'mybrand-a.com'","maxLength":512},"destination_country_iso3":{"type":"string","description":"Destination country ISO 3166-1 alpha 3 code","maxLength":3},"language_iso2":{"type":"string","description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3},"shipping_address":{"anyOf":[{"$ref":"#/components/schemas/AddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"delivery_method":{"type":"string","description":"Delivery method (e.g. 'standard shipping'), needs to be set up in the system","maxLength":255},"recipient_email":{"anyOf":[{"format":"email","type":"string"},{"const":"_unset","enum":["_unset"],"type":"string"}],"description":"Recipient email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead."},"recipient_name":{"type":"string","title":"Recipient name shown on notifications","description":"Recipient name","maxLength":255},"additional_recipients":{"items":{"$ref":"#/components/schemas/AdditionalRecipient"},"type":"array"},"customer_number":{"type":"string","description":"Customer number (e.g. from the retailer)","maxLength":255},"invoice_number":{"type":"string","description":"Invoice number (e.g. from the retailer)","maxLength":255},"payment_method":{"type":"string","description":"Payment method (e.g. 'credit card')","maxLength":255},"order_total_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total amount of the order (usually after tax & discount)"},"order_tax_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Tax amount of the original order"},"order_net_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Net amount of the order (usually before tax)"},"order_discount_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Discount amount of the order"},"order_currency":{"type":"string","description":"Currency of the order, e.g. USD, EUR (ISO 4217)","maxLength":3},"payments":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"order_date":{"type":["string","null"],"format":"date-time","description":"Date and time when the order was placed"},"channel":{"type":"string","description":"Channel through which the order was placed (e.g. 'webshop')","maxLength":255},"announced_delivery_date":{"type":["string","null"],"format":"date","description":"Announced delivery date"},"announced_delivery_date_min":{"type":["string","null"],"format":"date","title":"Announced Delivery Date (min)","description":"Announced delivery date range of order (min)"},"announced_delivery_date_max":{"type":["string","null"],"format":"date","title":"Announced Delivery Date (max)","description":"Announced delivery date range of order (min)"},"articles_order":{"items":{"$ref":"#/components/schemas/LineItemOrder"},"type":"array"},"billing_address":{"anyOf":[{"$ref":"#/components/schemas/AddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"timezone":{"type":"string","description":"Timezone of the recipient, if known, not required, but strongly recommended"},"order_status":{"type":"string","description":"Current status of the order, as setup in the system","maxLength":255},"has_multiple_shipments":{"type":["boolean","null"],"description":"Indicates this order has been split into multiple shipments"},"cancelled_date":{"type":["string","null"],"format":"date-time","title":"Cancelled At","description":"Datetime when the order was cancelled"},"cancelled_reason":{"allOf":[{"$ref":"#/components/schemas/CancelledReasonEnum"}],"description":"Reason for cancellation\n\n* `customer` - Customer\n* `inventory` - Inventory\n* `payment` - Payment-related\n* `other` - Other"},"additional_attributes":{"items":{"$ref":"#/components/schemas/AdditionalAttribute"},"type":"array"},"tags":{"type":"array","items":{"type":"string","maxLength":255},"description":"Tags for the object, format <key>:<value>e.g. 'category:Home Apparel'"},"mutations":{"items":{"anyOf":[{"$ref":"#/components/schemas/AddOrUpdateTrackingMutation"},{"$ref":"#/components/schemas/CancelTrackingMutation"},{"$ref":"#/components/schemas/CancelOrderMutation"},{"$ref":"#/components/schemas/ChangeLineItemQuantityMutation"},{"$ref":"#/components/schemas/AddLineItemMutation"},{"$ref":"#/components/schemas/ReplaceLineItemMutation"}],"title":"Order Mutations"},"type":"array"}},"required":["account","destination_country_iso3","external_id","order_number","recipient_email"]},"AddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"Empty":{"additionalProperties":false,"properties":{},"title":"Empty","type":"object"},"AdditionalRecipient":{"properties":{"role":{"description":"Role of the additional recipient","title":"Role","type":"string"},"email":{"description":"Email address of the additional recipient","title":"Email","type":"string"}},"title":"AdditionalRecipient","type":"object"},"LineItemOrder":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"description":"Line Item ID in the order (preferred when provided)","title":"Order Line Item ID","type":"string"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"},"status":{"allOf":[{"$ref":"#/components/schemas/LineItemOrderStatusEnum"}],"title":"Status"},"original_quantity":{"description":"Original quantity before any adjustments (automatically set by system)","title":"Original Quantity","type":"integer"},"change_reason":{"description":"Reason for the most recent quantity change","title":"Change Reason","type":"string"},"updated_at":{"description":"Timestamp when this line item was last updated","format":"date-time","title":"Updated At","type":"string"}},"required":["line_item_id"],"title":"Line Item Tracking","type":"object"},"LineItemVersionEnum":{"enum":["v1","v2"],"title":"LineItemVersionEnum","type":"string"},"WeightUnitEnum":{"enum":["kg","g","lbs","oz"],"type":"string"},"BundleInfo":{"additionalProperties":true,"properties":{"group_id":{"description":"Bundle group identifier in the retailer's system.","title":"Bundle Group ID","type":"string"},"role":{"$ref":"#/components/schemas/BundleRoleEnum","description":"Whether this line item represents a bundle parent or a bundle component.","title":"Bundle Role"},"return_policy":{"$ref":"#/components/schemas/BundleReturnPolicyEnum","default":"components_only","description":"Which lines in this bundle group are selectable for return.","title":"Bundle Return Policy"},"parent_product_id":{"description":"Parent bundle product identifier in the retailer's system.","title":"Bundle Parent Product ID","type":"string"},"parent_variant_id":{"description":"Parent bundle variant identifier in the retailer's system.","title":"Bundle Parent Variant ID","type":"string"},"parent_sku":{"description":"Parent bundle SKU, if available.","title":"Bundle Parent SKU","type":"string"},"parent_title":{"description":"Display title for the bundle parent, if available.","title":"Bundle Parent Title","type":"string"},"parent_quantity":{"description":"Quantity of the bundle parent purchased in the order.","title":"Bundle Parent Quantity","type":"integer"},"component_quantity_per_parent":{"description":"Component quantity per single bundle parent (if determinable).","title":"Bundle Component Quantity Per Parent","type":"integer"},"allocation_method":{"$ref":"#/components/schemas/BundleAllocationMethodEnum","default":"none","description":"How pricing was allocated to bundle components.","title":"Bundle Allocation Method"},"allocated_unit_price":{"description":"Snapshot of allocated component unit price (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Unit Price","type":"string"},"allocated_amount_invoiced":{"description":"Snapshot of allocated component invoiced amount (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Amount Invoiced","type":"string"}},"required":["group_id","role"],"title":"Bundle Info","type":"object"},"BundleRoleEnum":{"enum":["parent","component"],"title":"BundleRoleEnum","type":"string"},"BundleReturnPolicyEnum":{"enum":["parent_only","components_only","parent_and_components"],"title":"BundleReturnPolicyEnum","type":"string"},"BundleAllocationMethodEnum":{"enum":["none","component_price","msrp_ratio","equal"],"title":"BundleAllocationMethodEnum","type":"string"},"AdditionalAttribute":{"properties":{"key":{"description":"The key of the additional attribute","title":"Key","type":"string"},"value":{"default":null,"description":"The value of the additional attribute","title":"Value"}},"required":["key"],"title":"AdditionalAttribute","type":"object"},"LineItemOrderStatusEnum":{"enum":["shipped","pending","processing","cancelled","returned"],"type":"string"},"CancelledReasonEnum":{"enum":["customer","inventory","payment","other"],"type":"string","description":"* `customer` - Customer\n* `inventory` - Inventory\n* `payment` - Payment-related\n* `other` - Other"},"AddOrUpdateTrackingMutation":{"description":"Add or update tracking data.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"add_tracking","default":"add_tracking","title":"Type","type":"string"},"tracking":{"$ref":"#/components/schemas/TrackingSchema","description":"Tracking data"}},"required":["tracking"],"title":"AddOrUpdateTrackingMutation","type":"object"},"MutationResult":{"description":"The result of a mutation","properties":{"success":{"default":false,"description":"Whether the mutation was successful","title":"Success","type":"boolean"},"message":{"default":"","description":"A message describing the result of the mutation","title":"Message","type":"string"},"errors":{"additionalProperties":{"type":"string"},"description":"A dictionary of errors that occurred during the mutation","title":"Errors","type":"object"},"warnings":{"description":"Non-fatal warnings raised while processing the mutation","items":{"type":"string"},"title":"Warnings","type":"array"}},"title":"MutationResult","type":"object"},"TrackingSchema":{"description":"Tracking model used by v4 API in conjunction with order model","properties":{"tracking_number":{"description":"Tracking number of the shipment, if available. If no tracking number is available, transport number, consignment number or reference number should be used.","title":"Tracking Number","type":"string"},"client_key":{"description":"Name of the client (e.g. brand), as configured in account setup.","title":"Client Key","type":"string"},"courier":{"description":"Key of the courier, if available (required, unless transport number, consignment number or reference number are provided)","title":"Courier","type":"string"},"external_reference":{"description":"Unique retailer-provided reference of the shipment, either this tracking number is required","title":"External Reference","type":"string"},"recipient_postal_code":{"description":"Postal (zip) code of the recipient, frequently required for authentication of carrier data requests, or on the order statsu page. Must be provided if full shipping address is not available.","title":"Postal Code","type":"string"},"recipient_phone":{"description":"Recipient phone number, if known, may be required for communication","title":"Recipient Phone Number","type":"string"},"destination_country_iso3":{"description":"ISO 3166-1 alpha-3 code of the destination country, if different from order destination country","pattern":"^\\w{3}$","title":"Destination Country ISO3","type":"string"},"language_iso2":{"description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3,"title":"Language ISO2","type":"string"},"timezone":{"description":"Timezone of the recipient, if known, required for localized communication","title":"Timezone","type":"string"},"courier_service_level":{"description":"Service level of the courier, if known","title":"Courier Service Level","type":"string"},"delivery_method":{"description":"Delivery method (e.g. 'standard shipping'), needs to be set up in the system","title":"Delivery Method","type":"string"},"shipping_address":{"anyOf":[{"$ref":"#/components/schemas/AddressSchema"},{"$ref":"#/components/schemas/Empty"}],"description":"Recipient address, if different from order","title":"Recipient Address"},"recipient_email":{"description":"Recipient email address, if different from order","title":"Recipient Email","type":"string"},"recipient_name":{"description":"Recipient name used in messages (e.g. 'Max'), if different from order","title":"Recipient Name (for notifications))","type":"string"},"additional_recipients":{"description":"Additional recipients with role and email","items":{"$ref":"#/components/schemas/AdditionalRecipient"},"title":"Additional Recipients","type":"array"},"cancelled_date":{"description":"Date when the tracking was cancelled","format":"date-time","title":"Cancelled Date","type":"string"},"is_return":{"description":"Whether the tracking is return or pre-generated return label","title":"Is Return Label","type":"boolean"},"identifiers_consignment":{"description":"Consignment of the shipment","title":"Consignment","type":"string"},"delivery_number":{"description":"Number of shipment in order","title":"Delivery (Package) Number","type":"string"},"invoice_number":{"description":"Invoice number of the shipment","title":"Invoice Number","type":"string"},"shipping_cost_total":{"description":"Total cost of shipping","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Shipping Cost","type":"string"},"shipping_cost_net":{"description":"Net amount for shipping","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Shipping Cost Net Amount","type":"string"},"shipping_cost_discount":{"description":"Discount amount for shipping","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Shipping Discount","type":"string"},"shipping_weight_total":{"description":"Total weight of the shipment","title":"Shipping Weight Total","type":"number"},"shipping_weight_unit":{"anyOf":[{"$ref":"#/components/schemas/ShippingWeightUnitEnum"},{"type":"null"}],"default":"g","description":"Unit for total shipping weight","title":"Shipping Weight Unit"},"shipping_volume_total":{"description":"Total volume of the shipment","title":"Shipping Volume Total","type":"number"},"shipping_volume_unit":{"description":"Unit for total shipping volume","title":"Shipping Volume Unit","type":"string"},"shipping_height":{"description":"Total height of the shipment","title":"Shipping Height","type":"number"},"shipping_width":{"description":"Total width of the shipment","title":"Shipping Width","type":"number"},"shipping_length":{"description":"Total length of the shipment","title":"Shipping Length","type":"number"},"shipping_dimensions_unit":{"anyOf":[{"enum":["mm","cm","m"],"type":"string"},{"type":"null"}],"default":"mm","description":"Unit for shipping dimensions (height, width, length)","title":"Shipping Dimensions Unit"},"requires_signature":{"description":"Whether the shipment requires a signature","title":"Requires Signature","type":"boolean"},"is_dropshipment":{"description":"Is Dropshipment","title":"Is Dropshipment","type":"boolean"},"transport_number":{"description":"Transport number of the shipment, if available. If no transport number is available, consignment number or reference number must be used.","title":"Transport Number","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of origin country, if known","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"origin_region":{"description":"Origin region code (ISO 3166-2) of the shipment, if known","maxLength":20,"title":"Origin Region","type":"string"},"origin_postal_code":{"description":"Origin postal (zip) code of the shipment, if known","title":"Origin Postal Code","type":"string"},"articles":{"description":"List of articles in the shipment","items":{"$ref":"#/components/schemas/LineItem"},"title":"Articles","type":"array"},"warehouse":{"description":"Warehouse code of originating warehouse, if known, required for EDD calculation","title":"Warehouse","type":"string"},"courier_contact_name":{"description":"Courier Contact Name","title":"Courier Contact Name","type":"string"},"courier_contact_phone":{"description":"Courier contact phone number, if known","title":"Courier Contact Phone","type":"string"},"courier_contact_email":{"description":"Courier contact email address, if known","title":"Courier Contact Email","type":"string"},"review_link":{"description":"Link to review the delivery","title":"Review Link","type":"string"},"status_link":{"description":"Link to track the status of the delivery","title":"Status Link","type":"string"},"collection_code_retailer":{"description":"Collection code of the shipment, if known","title":"Collection Code","type":"string"},"collection_code_carrier":{"description":"Collection code of the shipment, if known","title":"Collection Code","type":"string"},"announced_send_date":{"description":"Announced send date of the shipment","format":"date","title":"Announced Send Date","type":"string"},"announced_delivery_date":{"description":"Announced delivery date","format":"date","title":"Announced Delivery Date","type":"string"},"announced_delivery_date_min":{"description":"Announced delivery date range","format":"date","title":"Announced Delivery Date Range","type":"string"},"announced_delivery_date_max":{"description":"Announced delivery date range","format":"date","title":"Announced Delivery Date Range","type":"string"},"notifications_inactive":{"description":"Notifications are inactive","title":"Notifications Inactive","type":"boolean"},"flags":{"description":"Extra flags for the tracking","items":{"$ref":"#/components/schemas/TrackingFlagEnum"},"title":"Flags","type":"array"},"cash_on_delivery_amount":{"description":"Cash on delivery amount","title":"Cash on Delivery","type":"number"},"tags":{"description":"Tags for the tracking, format <key>:<value>, e.g. 'category:Home Apparel","items":{"type":"string"},"title":"Tags","type":"array"},"checkpoints":{"description":"List of checkpoints for the tracking","items":{"$ref":"#/components/schemas/CheckpointSchema"},"title":"Checkpoints","type":"array"},"additional_fields":{"description":"Additional (customer defined) data-fields for the tracking. Example: {\"seller_organization_code\": \"PL_01\", \"pickupBoxNo\": \"48\"}","title":"Additional Fields"}},"title":"Tracking","type":"object"},"ShippingWeightUnitEnum":{"description":"Weight unit for shipping measurements.","enum":["g","kg","lbs"],"title":"ShippingWeightUnitEnum","type":"string"},"LineItem":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"description":"Line Item ID in the order (preferred when provided)","title":"Order Line Item ID","type":"string"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"}},"required":["line_item_id"],"title":"Line Item","type":"object"},"TrackingFlagEnum":{"enum":["complete","upgrade","cash_on_delivery","branch_delivery","doorstep_delivery"],"title":"TrackingFlagEnum","type":"string"},"CheckpointSchema":{"properties":{"status_code":{"title":"Status Code","type":"string"},"message":{"title":"Message","type":"string"},"courier":{"title":"Courier","type":"string"},"exception":{"items":{"type":"string"},"title":"Exception","type":"array"},"delivery_location":{"title":"Delivery Location","type":"string"},"event_timestamp":{"format":"date-time","title":"Event Timestamp","type":"string"},"courier_status":{"title":"Courier Status","type":"string"}},"required":["status_code","message","event_timestamp","courier_status"],"title":"CheckpointSchema","type":"object"},"CancelTrackingMutation":{"description":"Cancel tracking data.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"cancel_tracking","title":"Type","type":"string"},"tracking":{"$ref":"#/components/schemas/TrackingSchema","description":"The tracking to cancel, only identifiers need to be provided (tracking number + courier or external_reference)"}},"required":["type","tracking"],"title":"CancelTrackingMutation","type":"object"},"CancelOrderMutation":{"description":"Cancel an order.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"cancel_order","default":"cancel_order","title":"Type","type":"string"},"cancelled_reason":{"anyOf":[{"$ref":"#/components/schemas/OrderCancelReason"},{"type":"null"}],"default":null,"description":"Reason for the order cancellation","title":"Cancelled Reason"},"cancelled_date":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"Datetime when the order was cancelled","title":"Cancelled At"}},"title":"CancelOrderMutation","type":"object"},"OrderCancelReason":{"enum":["customer","inventory","payment","other"],"title":"OrderCancelReason","type":"string"},"ChangeLineItemQuantityMutation":{"description":"Set absolute quantity for an existing line item (0 = cancel).","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"change_line_item_quantity","default":"change_line_item_quantity","title":"Type","type":"string"},"line_item_id":{"description":"ID of the line item to update","title":"Line Item ID","type":"string"},"quantity":{"description":"Absolute quantity to set (0 = cancel)","exclusiveMinimum":-1,"title":"New Quantity","type":"integer"},"current_quantity":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"If set, mutation is applied only when stored quantity matches this value","title":"Current Quantity Guard"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Reason for the change","title":"Reason"}},"required":["line_item_id","quantity"],"title":"ChangeLineItemQuantityMutation","type":"object"},"AddLineItemMutation":{"description":"Append a brand-new line item to the order.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"add_line_item","default":"add_line_item","title":"Type","type":"string"},"line_item":{"$ref":"#/components/schemas/LineItemOrder","description":"Line item data to append","title":"Line Item"}},"required":["line_item"],"title":"AddLineItemMutation","type":"object"},"ReplaceLineItemMutation":{"description":"Cancel old line item & add substitute atomically.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"replace_line_item","default":"replace_line_item","title":"Type","type":"string"},"old_line_item_id":{"description":"Line item to be replaced (cancelled)","title":"Old Line Item ID","type":"string"},"new_line_item":{"$ref":"#/components/schemas/LineItemOrder","description":"Replacement line item data","title":"New Line Item"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Reason for replacement","title":"Reason"}},"required":["old_line_item_id","new_line_item"],"title":"ReplaceLineItemMutation","type":"object"},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}},"paths":{"/v4/track/orders/":{"get":{"operationId":"track_orders_list","description":"List all orders","summary":"List Orders","parameters":[{"in":"query","name":"account","schema":{"type":"array","items":{"type":"integer"}},"explode":true,"style":"form"},{"name":"cursor","required":false,"in":"query","description":"The pagination cursor value.","schema":{"type":"string"}},{"in":"query","name":"external_reference","schema":{"type":"string"}},{"in":"query","name":"order_number","schema":{"type":"string"}},{"name":"ordering","required":false,"in":"query","description":"Which field to use when ordering the results.","schema":{"type":"string"}}],"tags":["Order"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedOrderList"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}}}
```

## Retrieve Orders by ID

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

## Lookup Order (by identifier)

> Looks up an order by a unique identifier, either order\_number or external\_id. Returns all static order information,and order trackings.

```json
{"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token <encoded-token>`.\n\n`<encoded-token>` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"LookupOrderQueryRequest":{"type":"object","description":"Query parameters for looking up an order or tracking.","properties":{"account":{"type":"integer","description":"Account of order (if lookup by order number)"},"lookup_by":{"allOf":[{"$ref":"#/components/schemas/LookupByEnum"}],"default":"external-id","description":"(Unique) identifier for retrieval of the order\n\n* `external-id` - External ID Field\n* `order-number` - Order Number Field"}}},"LookupByEnum":{"enum":["external-id","order-number"],"type":"string","description":"* `external-id` - External ID Field\n* `order-number` - Order Number Field"},"OrderDetails":{"type":"object","description":"Create a new order record with shipment and recipient data.","properties":{"account":{"type":"integer","description":"Account to which this order belongs"},"order_number":{"type":"string","description":"Order number (customer facing)","maxLength":255},"external_id":{"type":"string","readOnly":true,"title":"External Identifier","description":"Unique identifier for this order, generated by parcelLab for this order"},"external_reference":{"type":"string","title":"Reference Identifier","description":"Retailer reference (e.g. internal system ID) for this order, unique.","maxLength":255},"client_key":{"type":"string","description":"Name of the technical client / shop (corresponds to the system setup), e.g. 'mybrand-a.com'","maxLength":512},"destination_country_iso3":{"type":"string","description":"Destination country ISO 3166-1 alpha 3 code","maxLength":3},"language_iso2":{"type":"string","description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3},"shipping_address":{"anyOf":[{"$ref":"#/components/schemas/AddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"delivery_method":{"type":"string","description":"Delivery method (e.g. 'standard shipping'), needs to be set up in the system","maxLength":255},"recipient_email":{"anyOf":[{"format":"email","type":"string"},{"const":"_unset","enum":["_unset"],"type":"string"}],"description":"Recipient email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead."},"recipient_name":{"type":"string","title":"Recipient name shown on notifications","description":"Recipient name","maxLength":255},"additional_recipients":{"items":{"$ref":"#/components/schemas/AdditionalRecipient"},"type":"array"},"customer_number":{"type":"string","description":"Customer number (e.g. from the retailer)","maxLength":255},"invoice_number":{"type":"string","description":"Invoice number (e.g. from the retailer)","maxLength":255},"payment_method":{"type":"string","description":"Payment method (e.g. 'credit card')","maxLength":255},"order_total_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total amount of the order (usually after tax & discount)"},"order_tax_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Tax amount of the original order"},"order_net_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Net amount of the order (usually before tax)"},"order_discount_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Discount amount of the order"},"order_currency":{"type":"string","description":"Currency of the order, e.g. USD, EUR (ISO 4217)","maxLength":3},"payments":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"order_date":{"type":["string","null"],"format":"date-time","description":"Date and time when the order was placed"},"channel":{"type":"string","description":"Channel through which the order was placed (e.g. 'webshop')","maxLength":255},"announced_delivery_date":{"type":["string","null"],"format":"date","description":"Announced delivery date"},"announced_delivery_date_min":{"type":["string","null"],"format":"date","title":"Announced Delivery Date (min)","description":"Announced delivery date range of order (min)"},"announced_delivery_date_max":{"type":["string","null"],"format":"date","title":"Announced Delivery Date (max)","description":"Announced delivery date range of order (min)"},"articles_order":{"items":{"$ref":"#/components/schemas/LineItemOrder"},"type":"array"},"billing_address":{"anyOf":[{"$ref":"#/components/schemas/AddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"timezone":{"type":"string","description":"Timezone of the recipient, if known, not required, but strongly recommended"},"order_status":{"type":"string","description":"Current status of the order, as setup in the system","maxLength":255},"has_multiple_shipments":{"type":["boolean","null"],"description":"Indicates this order has been split into multiple shipments"},"cancelled_date":{"type":["string","null"],"format":"date-time","title":"Cancelled At","description":"Datetime when the order was cancelled"},"cancelled_reason":{"allOf":[{"$ref":"#/components/schemas/CancelledReasonEnum"}],"description":"Reason for cancellation\n\n* `customer` - Customer\n* `inventory` - Inventory\n* `payment` - Payment-related\n* `other` - Other"},"additional_attributes":{"items":{"$ref":"#/components/schemas/AdditionalAttribute"},"type":"array"},"tags":{"type":"array","items":{"type":"string","maxLength":255},"description":"Tags for the object, format <key>:<value>e.g. 'category:Home Apparel'"},"mutations":{"items":{"anyOf":[{"$ref":"#/components/schemas/AddOrUpdateTrackingMutation"},{"$ref":"#/components/schemas/CancelTrackingMutation"},{"$ref":"#/components/schemas/CancelOrderMutation"},{"$ref":"#/components/schemas/ChangeLineItemQuantityMutation"},{"$ref":"#/components/schemas/AddLineItemMutation"},{"$ref":"#/components/schemas/ReplaceLineItemMutation"}],"title":"Order Mutations"},"type":"array"},"trackings":{"items":{"$ref":"#/components/schemas/TrackingDetailsSchema"},"type":"array"}},"required":["account","destination_country_iso3","external_id","order_number","recipient_email"]},"AddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"Empty":{"additionalProperties":false,"properties":{},"title":"Empty","type":"object"},"AdditionalRecipient":{"properties":{"role":{"description":"Role of the additional recipient","title":"Role","type":"string"},"email":{"description":"Email address of the additional recipient","title":"Email","type":"string"}},"title":"AdditionalRecipient","type":"object"},"LineItemOrder":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"description":"Line Item ID in the order (preferred when provided)","title":"Order Line Item ID","type":"string"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"},"status":{"allOf":[{"$ref":"#/components/schemas/LineItemOrderStatusEnum"}],"title":"Status"},"original_quantity":{"description":"Original quantity before any adjustments (automatically set by system)","title":"Original Quantity","type":"integer"},"change_reason":{"description":"Reason for the most recent quantity change","title":"Change Reason","type":"string"},"updated_at":{"description":"Timestamp when this line item was last updated","format":"date-time","title":"Updated At","type":"string"}},"required":["line_item_id"],"title":"Line Item Tracking","type":"object"},"LineItemVersionEnum":{"enum":["v1","v2"],"title":"LineItemVersionEnum","type":"string"},"WeightUnitEnum":{"enum":["kg","g","lbs","oz"],"type":"string"},"BundleInfo":{"additionalProperties":true,"properties":{"group_id":{"description":"Bundle group identifier in the retailer's system.","title":"Bundle Group ID","type":"string"},"role":{"$ref":"#/components/schemas/BundleRoleEnum","description":"Whether this line item represents a bundle parent or a bundle component.","title":"Bundle Role"},"return_policy":{"$ref":"#/components/schemas/BundleReturnPolicyEnum","default":"components_only","description":"Which lines in this bundle group are selectable for return.","title":"Bundle Return Policy"},"parent_product_id":{"description":"Parent bundle product identifier in the retailer's system.","title":"Bundle Parent Product ID","type":"string"},"parent_variant_id":{"description":"Parent bundle variant identifier in the retailer's system.","title":"Bundle Parent Variant ID","type":"string"},"parent_sku":{"description":"Parent bundle SKU, if available.","title":"Bundle Parent SKU","type":"string"},"parent_title":{"description":"Display title for the bundle parent, if available.","title":"Bundle Parent Title","type":"string"},"parent_quantity":{"description":"Quantity of the bundle parent purchased in the order.","title":"Bundle Parent Quantity","type":"integer"},"component_quantity_per_parent":{"description":"Component quantity per single bundle parent (if determinable).","title":"Bundle Component Quantity Per Parent","type":"integer"},"allocation_method":{"$ref":"#/components/schemas/BundleAllocationMethodEnum","default":"none","description":"How pricing was allocated to bundle components.","title":"Bundle Allocation Method"},"allocated_unit_price":{"description":"Snapshot of allocated component unit price (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Unit Price","type":"string"},"allocated_amount_invoiced":{"description":"Snapshot of allocated component invoiced amount (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Amount Invoiced","type":"string"}},"required":["group_id","role"],"title":"Bundle Info","type":"object"},"BundleRoleEnum":{"enum":["parent","component"],"title":"BundleRoleEnum","type":"string"},"BundleReturnPolicyEnum":{"enum":["parent_only","components_only","parent_and_components"],"title":"BundleReturnPolicyEnum","type":"string"},"BundleAllocationMethodEnum":{"enum":["none","component_price","msrp_ratio","equal"],"title":"BundleAllocationMethodEnum","type":"string"},"AdditionalAttribute":{"properties":{"key":{"description":"The key of the additional attribute","title":"Key","type":"string"},"value":{"default":null,"description":"The value of the additional attribute","title":"Value"}},"required":["key"],"title":"AdditionalAttribute","type":"object"},"LineItemOrderStatusEnum":{"enum":["shipped","pending","processing","cancelled","returned"],"type":"string"},"CancelledReasonEnum":{"enum":["customer","inventory","payment","other"],"type":"string","description":"* `customer` - Customer\n* `inventory` - Inventory\n* `payment` - Payment-related\n* `other` - Other"},"AddOrUpdateTrackingMutation":{"description":"Add or update tracking data.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"add_tracking","default":"add_tracking","title":"Type","type":"string"},"tracking":{"$ref":"#/components/schemas/TrackingSchema","description":"Tracking data"}},"required":["tracking"],"title":"AddOrUpdateTrackingMutation","type":"object"},"MutationResult":{"description":"The result of a mutation","properties":{"success":{"default":false,"description":"Whether the mutation was successful","title":"Success","type":"boolean"},"message":{"default":"","description":"A message describing the result of the mutation","title":"Message","type":"string"},"errors":{"additionalProperties":{"type":"string"},"description":"A dictionary of errors that occurred during the mutation","title":"Errors","type":"object"},"warnings":{"description":"Non-fatal warnings raised while processing the mutation","items":{"type":"string"},"title":"Warnings","type":"array"}},"title":"MutationResult","type":"object"},"TrackingSchema":{"description":"Tracking model used by v4 API in conjunction with order model","properties":{"tracking_number":{"description":"Tracking number of the shipment, if available. If no tracking number is available, transport number, consignment number or reference number should be used.","title":"Tracking Number","type":"string"},"client_key":{"description":"Name of the client (e.g. brand), as configured in account setup.","title":"Client Key","type":"string"},"courier":{"description":"Key of the courier, if available (required, unless transport number, consignment number or reference number are provided)","title":"Courier","type":"string"},"external_reference":{"description":"Unique retailer-provided reference of the shipment, either this tracking number is required","title":"External Reference","type":"string"},"recipient_postal_code":{"description":"Postal (zip) code of the recipient, frequently required for authentication of carrier data requests, or on the order statsu page. Must be provided if full shipping address is not available.","title":"Postal Code","type":"string"},"recipient_phone":{"description":"Recipient phone number, if known, may be required for communication","title":"Recipient Phone Number","type":"string"},"destination_country_iso3":{"description":"ISO 3166-1 alpha-3 code of the destination country, if different from order destination country","pattern":"^\\w{3}$","title":"Destination Country ISO3","type":"string"},"language_iso2":{"description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3,"title":"Language ISO2","type":"string"},"timezone":{"description":"Timezone of the recipient, if known, required for localized communication","title":"Timezone","type":"string"},"courier_service_level":{"description":"Service level of the courier, if known","title":"Courier Service Level","type":"string"},"delivery_method":{"description":"Delivery method (e.g. 'standard shipping'), needs to be set up in the system","title":"Delivery Method","type":"string"},"shipping_address":{"anyOf":[{"$ref":"#/components/schemas/AddressSchema"},{"$ref":"#/components/schemas/Empty"}],"description":"Recipient address, if different from order","title":"Recipient Address"},"recipient_email":{"description":"Recipient email address, if different from order","title":"Recipient Email","type":"string"},"recipient_name":{"description":"Recipient name used in messages (e.g. 'Max'), if different from order","title":"Recipient Name (for notifications))","type":"string"},"additional_recipients":{"description":"Additional recipients with role and email","items":{"$ref":"#/components/schemas/AdditionalRecipient"},"title":"Additional Recipients","type":"array"},"cancelled_date":{"description":"Date when the tracking was cancelled","format":"date-time","title":"Cancelled Date","type":"string"},"is_return":{"description":"Whether the tracking is return or pre-generated return label","title":"Is Return Label","type":"boolean"},"identifiers_consignment":{"description":"Consignment of the shipment","title":"Consignment","type":"string"},"delivery_number":{"description":"Number of shipment in order","title":"Delivery (Package) Number","type":"string"},"invoice_number":{"description":"Invoice number of the shipment","title":"Invoice Number","type":"string"},"shipping_cost_total":{"description":"Total cost of shipping","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Shipping Cost","type":"string"},"shipping_cost_net":{"description":"Net amount for shipping","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Shipping Cost Net Amount","type":"string"},"shipping_cost_discount":{"description":"Discount amount for shipping","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Shipping Discount","type":"string"},"shipping_weight_total":{"description":"Total weight of the shipment","title":"Shipping Weight Total","type":"number"},"shipping_weight_unit":{"anyOf":[{"$ref":"#/components/schemas/ShippingWeightUnitEnum"},{"type":"null"}],"default":"g","description":"Unit for total shipping weight","title":"Shipping Weight Unit"},"shipping_volume_total":{"description":"Total volume of the shipment","title":"Shipping Volume Total","type":"number"},"shipping_volume_unit":{"description":"Unit for total shipping volume","title":"Shipping Volume Unit","type":"string"},"shipping_height":{"description":"Total height of the shipment","title":"Shipping Height","type":"number"},"shipping_width":{"description":"Total width of the shipment","title":"Shipping Width","type":"number"},"shipping_length":{"description":"Total length of the shipment","title":"Shipping Length","type":"number"},"shipping_dimensions_unit":{"anyOf":[{"enum":["mm","cm","m"],"type":"string"},{"type":"null"}],"default":"mm","description":"Unit for shipping dimensions (height, width, length)","title":"Shipping Dimensions Unit"},"requires_signature":{"description":"Whether the shipment requires a signature","title":"Requires Signature","type":"boolean"},"is_dropshipment":{"description":"Is Dropshipment","title":"Is Dropshipment","type":"boolean"},"transport_number":{"description":"Transport number of the shipment, if available. If no transport number is available, consignment number or reference number must be used.","title":"Transport Number","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of origin country, if known","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"origin_region":{"description":"Origin region code (ISO 3166-2) of the shipment, if known","maxLength":20,"title":"Origin Region","type":"string"},"origin_postal_code":{"description":"Origin postal (zip) code of the shipment, if known","title":"Origin Postal Code","type":"string"},"articles":{"description":"List of articles in the shipment","items":{"$ref":"#/components/schemas/LineItem"},"title":"Articles","type":"array"},"warehouse":{"description":"Warehouse code of originating warehouse, if known, required for EDD calculation","title":"Warehouse","type":"string"},"courier_contact_name":{"description":"Courier Contact Name","title":"Courier Contact Name","type":"string"},"courier_contact_phone":{"description":"Courier contact phone number, if known","title":"Courier Contact Phone","type":"string"},"courier_contact_email":{"description":"Courier contact email address, if known","title":"Courier Contact Email","type":"string"},"review_link":{"description":"Link to review the delivery","title":"Review Link","type":"string"},"status_link":{"description":"Link to track the status of the delivery","title":"Status Link","type":"string"},"collection_code_retailer":{"description":"Collection code of the shipment, if known","title":"Collection Code","type":"string"},"collection_code_carrier":{"description":"Collection code of the shipment, if known","title":"Collection Code","type":"string"},"announced_send_date":{"description":"Announced send date of the shipment","format":"date","title":"Announced Send Date","type":"string"},"announced_delivery_date":{"description":"Announced delivery date","format":"date","title":"Announced Delivery Date","type":"string"},"announced_delivery_date_min":{"description":"Announced delivery date range","format":"date","title":"Announced Delivery Date Range","type":"string"},"announced_delivery_date_max":{"description":"Announced delivery date range","format":"date","title":"Announced Delivery Date Range","type":"string"},"notifications_inactive":{"description":"Notifications are inactive","title":"Notifications Inactive","type":"boolean"},"flags":{"description":"Extra flags for the tracking","items":{"$ref":"#/components/schemas/TrackingFlagEnum"},"title":"Flags","type":"array"},"cash_on_delivery_amount":{"description":"Cash on delivery amount","title":"Cash on Delivery","type":"number"},"tags":{"description":"Tags for the tracking, format <key>:<value>, e.g. 'category:Home Apparel","items":{"type":"string"},"title":"Tags","type":"array"},"checkpoints":{"description":"List of checkpoints for the tracking","items":{"$ref":"#/components/schemas/CheckpointSchema"},"title":"Checkpoints","type":"array"},"additional_fields":{"description":"Additional (customer defined) data-fields for the tracking. Example: {\"seller_organization_code\": \"PL_01\", \"pickupBoxNo\": \"48\"}","title":"Additional Fields"}},"title":"Tracking","type":"object"},"ShippingWeightUnitEnum":{"description":"Weight unit for shipping measurements.","enum":["g","kg","lbs"],"title":"ShippingWeightUnitEnum","type":"string"},"LineItem":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"description":"Line Item ID in the order (preferred when provided)","title":"Order Line Item ID","type":"string"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"}},"required":["line_item_id"],"title":"Line Item","type":"object"},"TrackingFlagEnum":{"enum":["complete","upgrade","cash_on_delivery","branch_delivery","doorstep_delivery"],"title":"TrackingFlagEnum","type":"string"},"CheckpointSchema":{"properties":{"status_code":{"title":"Status Code","type":"string"},"message":{"title":"Message","type":"string"},"courier":{"title":"Courier","type":"string"},"exception":{"items":{"type":"string"},"title":"Exception","type":"array"},"delivery_location":{"title":"Delivery Location","type":"string"},"event_timestamp":{"format":"date-time","title":"Event Timestamp","type":"string"},"courier_status":{"title":"Courier Status","type":"string"}},"required":["status_code","message","event_timestamp","courier_status"],"title":"CheckpointSchema","type":"object"},"CancelTrackingMutation":{"description":"Cancel tracking data.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"cancel_tracking","title":"Type","type":"string"},"tracking":{"$ref":"#/components/schemas/TrackingSchema","description":"The tracking to cancel, only identifiers need to be provided (tracking number + courier or external_reference)"}},"required":["type","tracking"],"title":"CancelTrackingMutation","type":"object"},"CancelOrderMutation":{"description":"Cancel an order.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"cancel_order","default":"cancel_order","title":"Type","type":"string"},"cancelled_reason":{"anyOf":[{"$ref":"#/components/schemas/OrderCancelReason"},{"type":"null"}],"default":null,"description":"Reason for the order cancellation","title":"Cancelled Reason"},"cancelled_date":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"Datetime when the order was cancelled","title":"Cancelled At"}},"title":"CancelOrderMutation","type":"object"},"OrderCancelReason":{"enum":["customer","inventory","payment","other"],"title":"OrderCancelReason","type":"string"},"ChangeLineItemQuantityMutation":{"description":"Set absolute quantity for an existing line item (0 = cancel).","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"change_line_item_quantity","default":"change_line_item_quantity","title":"Type","type":"string"},"line_item_id":{"description":"ID of the line item to update","title":"Line Item ID","type":"string"},"quantity":{"description":"Absolute quantity to set (0 = cancel)","exclusiveMinimum":-1,"title":"New Quantity","type":"integer"},"current_quantity":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"If set, mutation is applied only when stored quantity matches this value","title":"Current Quantity Guard"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Reason for the change","title":"Reason"}},"required":["line_item_id","quantity"],"title":"ChangeLineItemQuantityMutation","type":"object"},"AddLineItemMutation":{"description":"Append a brand-new line item to the order.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"add_line_item","default":"add_line_item","title":"Type","type":"string"},"line_item":{"$ref":"#/components/schemas/LineItemOrder","description":"Line item data to append","title":"Line Item"}},"required":["line_item"],"title":"AddLineItemMutation","type":"object"},"ReplaceLineItemMutation":{"description":"Cancel old line item & add substitute atomically.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"replace_line_item","default":"replace_line_item","title":"Type","type":"string"},"old_line_item_id":{"description":"Line item to be replaced (cancelled)","title":"Old Line Item ID","type":"string"},"new_line_item":{"$ref":"#/components/schemas/LineItemOrder","description":"Replacement line item data","title":"New Line Item"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Reason for replacement","title":"Reason"}},"required":["old_line_item_id","new_line_item"],"title":"ReplaceLineItemMutation","type":"object"},"TrackingDetailsSchema":{"properties":{"tracking_number":{"description":"Tracking number of the shipment, if available. If no tracking number is available, transport number, consignment number or reference number should be used.","title":"Tracking Number","type":"string"},"client_key":{"description":"Name of the client (e.g. brand), as configured in account setup.","title":"Client Key","type":"string"},"courier":{"description":"Key of the courier, if available (required, unless transport number, consignment number or reference number are provided)","title":"Courier","type":"string"},"external_reference":{"description":"Unique retailer-provided reference of the shipment, either this tracking number is required","title":"External Reference","type":"string"},"recipient_postal_code":{"description":"Postal (zip) code of the recipient, frequently required for authentication of carrier data requests, or on the order statsu page. Must be provided if full shipping address is not available.","title":"Postal Code","type":"string"},"recipient_phone":{"description":"Recipient phone number, if known, may be required for communication","title":"Recipient Phone Number","type":"string"},"destination_country_iso3":{"description":"ISO 3166-1 alpha-3 code of the destination country, if different from order destination country","pattern":"^\\w{3}$","title":"Destination Country ISO3","type":"string"},"language_iso2":{"description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3,"title":"Language ISO2","type":"string"},"timezone":{"description":"Timezone of the recipient, if known, required for localized communication","title":"Timezone","type":"string"},"courier_service_level":{"description":"Service level of the courier, if known","title":"Courier Service Level","type":"string"},"delivery_method":{"description":"Delivery method (e.g. 'standard shipping'), needs to be set up in the system","title":"Delivery Method","type":"string"},"shipping_address":{"anyOf":[{"$ref":"#/components/schemas/AddressSchema"},{"$ref":"#/components/schemas/Empty"}],"description":"Recipient address, if different from order","title":"Recipient Address"},"recipient_email":{"description":"Recipient email address, if different from order","title":"Recipient Email","type":"string"},"recipient_name":{"description":"Recipient name used in messages (e.g. 'Max'), if different from order","title":"Recipient Name (for notifications))","type":"string"},"additional_recipients":{"description":"Additional recipients with role and email","items":{"$ref":"#/components/schemas/AdditionalRecipient"},"title":"Additional Recipients","type":"array"},"cancelled_date":{"description":"Date when the tracking was cancelled","format":"date-time","title":"Cancelled Date","type":"string"},"is_return":{"description":"Whether the tracking is return or pre-generated return label","title":"Is Return Label","type":"boolean"},"identifiers_consignment":{"description":"Consignment of the shipment","title":"Consignment","type":"string"},"delivery_number":{"description":"Number of shipment in order","title":"Delivery (Package) Number","type":"string"},"invoice_number":{"description":"Invoice number of the shipment","title":"Invoice Number","type":"string"},"shipping_cost_total":{"description":"Total cost of shipping","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Shipping Cost","type":"string"},"shipping_cost_net":{"description":"Net amount for shipping","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Shipping Cost Net Amount","type":"string"},"shipping_cost_discount":{"description":"Discount amount for shipping","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Shipping Discount","type":"string"},"shipping_weight_total":{"description":"Total weight of the shipment","title":"Shipping Weight Total","type":"number"},"shipping_weight_unit":{"anyOf":[{"$ref":"#/components/schemas/ShippingWeightUnitEnum"},{"type":"null"}],"default":"g","description":"Unit for total shipping weight","title":"Shipping Weight Unit"},"shipping_volume_total":{"description":"Total volume of the shipment","title":"Shipping Volume Total","type":"number"},"shipping_volume_unit":{"description":"Unit for total shipping volume","title":"Shipping Volume Unit","type":"string"},"shipping_height":{"description":"Total height of the shipment","title":"Shipping Height","type":"number"},"shipping_width":{"description":"Total width of the shipment","title":"Shipping Width","type":"number"},"shipping_length":{"description":"Total length of the shipment","title":"Shipping Length","type":"number"},"shipping_dimensions_unit":{"anyOf":[{"enum":["mm","cm","m"],"type":"string"},{"type":"null"}],"default":"mm","description":"Unit for shipping dimensions (height, width, length)","title":"Shipping Dimensions Unit"},"requires_signature":{"description":"Whether the shipment requires a signature","title":"Requires Signature","type":"boolean"},"is_dropshipment":{"description":"Is Dropshipment","title":"Is Dropshipment","type":"boolean"},"transport_number":{"description":"Transport number of the shipment, if available. If no transport number is available, consignment number or reference number must be used.","title":"Transport Number","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of origin country, if known","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"origin_region":{"description":"Origin region code (ISO 3166-2) of the shipment, if known","maxLength":20,"title":"Origin Region","type":"string"},"origin_postal_code":{"description":"Origin postal (zip) code of the shipment, if known","title":"Origin Postal Code","type":"string"},"articles":{"description":"List of articles in the shipment","items":{"$ref":"#/components/schemas/LineItem"},"title":"Articles","type":"array"},"warehouse":{"description":"Warehouse code of originating warehouse, if known, required for EDD calculation","title":"Warehouse","type":"string"},"courier_contact_name":{"description":"Courier Contact Name","title":"Courier Contact Name","type":"string"},"courier_contact_phone":{"description":"Courier contact phone number, if known","title":"Courier Contact Phone","type":"string"},"courier_contact_email":{"description":"Courier contact email address, if known","title":"Courier Contact Email","type":"string"},"review_link":{"description":"Link to review the delivery","title":"Review Link","type":"string"},"status_link":{"description":"Link to track the status of the delivery","title":"Status Link","type":"string"},"collection_code_retailer":{"description":"Collection code of the shipment, if known","title":"Collection Code","type":"string"},"collection_code_carrier":{"description":"Collection code of the shipment, if known","title":"Collection Code","type":"string"},"announced_send_date":{"description":"Announced send date of the shipment","format":"date","title":"Announced Send Date","type":"string"},"announced_delivery_date":{"description":"Announced delivery date","format":"date","title":"Announced Delivery Date","type":"string"},"announced_delivery_date_min":{"description":"Announced delivery date range","format":"date","title":"Announced Delivery Date Range","type":"string"},"announced_delivery_date_max":{"description":"Announced delivery date range","format":"date","title":"Announced Delivery Date Range","type":"string"},"notifications_inactive":{"description":"Notifications are inactive","title":"Notifications Inactive","type":"boolean"},"flags":{"description":"Extra flags for the tracking","items":{"$ref":"#/components/schemas/TrackingFlagEnum"},"title":"Flags","type":"array"},"cash_on_delivery_amount":{"description":"Cash on delivery amount","title":"Cash on Delivery","type":"number"},"tags":{"description":"Tags for the tracking, format <key>:<value>, e.g. 'category:Home Apparel","items":{"type":"string"},"title":"Tags","type":"array"},"checkpoints":{"description":"List of checkpoints for the tracking","items":{"$ref":"#/components/schemas/CheckpointSchema"},"title":"Checkpoints","type":"array"},"additional_fields":{"description":"Additional (customer defined) data-fields for the tracking. Example: {\"seller_organization_code\": \"PL_01\", \"pickupBoxNo\": \"48\"}","title":"Additional Fields"},"courier_change_url":{"description":"URL to change courier preferences, if available","title":"Courier Change URL","type":"string"},"is_returns_portal":{"description":"Whether this is a tracking from the parcelLab Returns Portal","title":"Returns Portal","type":"boolean"},"number_of_parcels":{"description":"Number of parcels in this shipment","title":"Number of Parcels","type":"integer"},"pod_date":{"description":"Date of proof of delivery","format":"date","title":"POD Date","type":"string"},"pod_identifier":{"description":"Identifier for proof of delivery","title":"POD Identifier","type":"string"},"pod_signature":{"description":"Signature for proof of delivery","title":"POD Signature","type":"string"},"reporting_courier_dropoff_date":{"description":"Date when delivery was first attempted by courier","format":"date","title":"Courier Dropoff Date","type":"string"},"reporting_delivery_date":{"description":"Date when shipment was delivered","format":"date","title":"Delivery Date","type":"string"},"reporting_in_transit_date":{"description":"Date when shipment was sorted by the carrier in their hub","format":"date","title":"In Transit Date","type":"string"},"reporting_pickup_date":{"description":"Date when shipment was picked up by the carrier","format":"date","title":"Pickup Date","type":"string"},"security_hash":{"description":"Security hash for this tracking","title":"Security Hash","type":"string"},"support_phone":{"description":"Phone number for support","title":"Support Phone","type":"string"}},"title":"Tracking","type":"object"},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}},"paths":{"/v4/track/orders/{unique_id}/":{"get":{"operationId":"track_orders_retrieve","description":"Looks up an order by a unique identifier, either order_number or external_id. Returns all static order information,and order trackings.","summary":"Lookup Order (by identifier)","parameters":[{"in":"path","name":"unique_id","schema":{"type":"string","pattern":"^(?!info)[^/.]+$"},"required":true},{"in":"query","name":"unique_id","schema":{"$ref":"#/components/schemas/LookupOrderQueryRequest"}}],"tags":["Order"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderDetails"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}}}
```

### Retrieve the Security Hash

You can retrieve the security hash as part of the order details response (see [above](#retrieve-orders-by-id)) to securely access the Order Status page.

{% hint style="info" %}
The security hash is generated per tracking, not per order. Orders with multiple trackings will have multiple security hashes.
{% endhint %}

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

```json
{
  "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](/docs/developers/status-updates/order-status-page-configuration.md).

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

{% code title="payload.json" overflow="wrap" %}

```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": "max@mustermann.de",
    "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,
                    }
                ]
            }
        }
    ]
}
```

{% endcode %}

All available keys can be found in the data model.

{% content-ref url="/pages/-LQpTnZA2sICcHRiB8fQ" %}
[Data Model](/docs/developers/data-elements/data-model.md)
{% endcontent-ref %}

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

{% hint style="info" %}
For examples of programming languages, please [fill in our contact form](https://parcellab.com/en/contact) and they will be provided on request.
{% endhint %}

For a simple test, cURL can be used.

{% code title="sample-call-with-curl.sh" %}

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

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.parcellab.com/docs/developers/orders/full-order-api-spec.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.