---
title: "Create or Update Order (recommended)"
method: PUT
path: "/v4/track/orders/"
tags: ["Order"]
---

# Create or Update Order (recommended)

`PUT /v4/track/orders/`

## Request

- The document declares no server URL.
- Auth: one of:
  - API key in header `Authorization`
  - HTTP bearer

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


Payload validation:

- Request-blocking validation failures return HTTP 400 and no order or mutation
  history is written. Serializer and Pydantic validation errors use the standard
  `{"type": "client_error", "errors": [...]}` shape. Early order identifier and
  account authorization failures return `{"detail": "..."}`.
- `recipient_email` must be a valid email address or the literal `_unset`.
- Country, language, currency, timezone, enum, date, datetime, decimal, length,
  and required-field validations are enforced at the request boundary.
- `shipping_address` and tracking-level `shipping_address` are strictly
  validated, including region codes. `billing_address` uses the more permissive
  address schema and can coerce invalid region codes to `null`.
- Mutation payloads must use a supported `type`. Tracking mutations require
  either `tracking_number` plus `courier`, or `external_reference`.
- Tracking-level `delivery_method` must be configured for the account.
- `add_tracking` with `tracking_number` plus `courier` performs a best-effort
  same-account conflict check before enqueueing. The check is eventually
  consistent and Backend persistence still enforces downstream uniqueness.

Successful responses can still contain per-mutation validation information:

- Non-fatal validation warnings are returned in
  `mutations[].result.warnings`. Today this covers dropped unrecognized
  `add_tracking.tracking` fields and `articles_order` replacement warnings
  when mutations are present.
- Accepted mutation failures do not reject the whole request. The HTTP response
  remains 200 or 201, while the affected mutation returns
  `mutations[].result.success=false`.

## Request body

- PatchedOrderRequest: Create a new order record with shipment and recipient data.
  - `account` integer: Account to which this order belongs
  - `order_number` string: Order number (customer facing)
  - `external_reference` string: Retailer reference (e.g. internal system ID) for this order, unique.
  - `client_key` string: Name of the technical client / shop (corresponds to the system setup), e.g. 'mybrand-a.com'
  - `destination_country_iso3` string: Destination country ISO 3166-1 alpha 3 code
  - `language_iso2` string: ISO 639-1 language code of the recipient, if known, required for localized communication
  - `shipping_address` union
    - AddressSchema
      - `first_name` string
      - `last_name` string
      - `company_name` string
      - `address_line` string, required: Address line, e.g. street and house number, or PO Box
      - `address_line_extra` string: Additional address line, e.g. apartment number or company name
      - `postal_code` string, required
      - `city` string, required: City name (min-length of 1 due to logographic languages)
      - `country_iso3` string, required: ISO 3166-1 alpha-3 code of country
      - `region_code` string: Region code, e.g. state or province code (ISO 3166-2), if available
      - `phone` string: Phone number related to this address, if any
    - Empty
  - `delivery_method` string: Delivery method (e.g. 'standard shipping'), needs to be set up in the system
  - `recipient_email` union: Recipient email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead.
    - string, email
    - '_unset'
  - `recipient_name` string: Recipient name
  - `additional_recipients` AdditionalRecipient[]
    - `role` string: Role of the additional recipient
    - `email` string: Email address of the additional recipient
  - `customer_number` string: Customer number (e.g. from the retailer)
  - `invoice_number` string: Invoice number (e.g. from the retailer)
  - `payment_method` string: Payment method (e.g. 'credit card')
  - `order_total_amount` string, decimal, nullable: Total amount of the order (usually after tax & discount)
  - `order_tax_amount` string, decimal, nullable: Tax amount of the original order
  - `order_net_amount` string, decimal, nullable: Net amount of the order (usually before tax)
  - `order_discount_amount` string, decimal, nullable: Discount amount of the order
  - `order_currency` string: Currency of the order, e.g. USD, EUR (ISO 4217)
  - `payments` object[]
  - `order_date` string, date-time, nullable: Date and time when the order was placed
  - `channel` string: Channel through which the order was placed (e.g. 'webshop')
  - `announced_delivery_date` string, date, nullable: Announced delivery date
  - `announced_delivery_date_min` string, date, nullable: Announced delivery date range of order (min)
  - `announced_delivery_date_max` string, date, nullable: Announced delivery date range of order (min)
  - `articles_order` LineItemOrder[]
    - `version` 'v1' | 'v2'
    - `line_item_id` string, required: Retailer ID of the line item
    - `product_id` string: Parent product identifier in the retailer's system (shared across variants).
    - `variant_id` string: SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.
    - `sku` string: Stock Keeping Unit of the line item
    - `barcode` string: Barcode associated with the line item variant or product
    - `order_item_id` string: Line Item ID in the order (preferred when provided)
    - `article_name` string: Name of the article
    - `article_description` string: Description of the article
    - `article_category` string: Category of the article
    - `article_store_url` string: URL to the article in the store
    - `article_image_url` string: URL to the image of the article
    - `article_brand` string: Brand of the article (reference only)
    - `size` string: Size of the article (reference only)
    - `color` string: Color of the article (reference only)
    - `width` number: Width of the article (in millimeters)
    - `height` number: Height of the article (in millimeters)
    - `length` number: Length of the article (in millimeters)
    - `length_unit` 'cm'
    - `weight` number: Weight of the article (in grams, kg, lbs, or oz)
    - `weight_unit` 'kg' | 'g' | 'lbs' | 'oz'
    - `unit_price` string: Paid unit price of the article (post-discount)
    - `unit_price_original` string: Original unit price of the article (pre-discount)
    - `quantity` integer: Unit quantity of the article
    - `amount_invoiced` string: Paid line total amount for this line item (post-discount)
    - `tax_amount` string: Total tax amount for this line item (regardless of taxesIncluded)
    - `harmonized_system_code` string: HS/HTS code for customs classification
    - `origin_country_iso3` string: ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations
    - `is_bulky` boolean: If the article is bulky
    - `tags` string[]: Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'
    - `bundle` BundleInfo
      - `group_id` string, required: Bundle group identifier in the retailer's system.
      - `role` 'parent' | 'component', required
      - `return_policy` 'parent_only' | 'components_only' | 'parent_and_components'
      - `parent_product_id` string: Parent bundle product identifier in the retailer's system.
      - `parent_variant_id` string: Parent bundle variant identifier in the retailer's system.
      - `parent_sku` string: Parent bundle SKU, if available.
      - `parent_title` string: Display title for the bundle parent, if available.
      - `parent_quantity` integer: Quantity of the bundle parent purchased in the order.
      - `component_quantity_per_parent` integer: Component quantity per single bundle parent (if determinable).
      - `selection_mode` 'individual' | 'group_on_first_pick'
      - `allocation_method` 'none' | 'component_price' | 'msrp_ratio' | 'equal'
      - `allocated_unit_price` string: Snapshot of allocated component unit price (if derived from bundle totals).
      - `allocated_amount_invoiced` string: Snapshot of allocated component invoiced amount (if derived from bundle totals).
    - `additional_attributes` AdditionalAttribute[]: Additional attributes for this line item
      - `key` string, required: The key of the additional attribute
      - `value` unknown
    - `status` 'shipped' | 'pending' | 'processing' | 'cancelled' | 'returned'
    - `original_quantity` integer: Original quantity before any adjustments (automatically set by system)
    - `change_reason` string: Reason for the most recent quantity change
    - `updated_at` string, date-time: Timestamp when this line item was last updated
  - `billing_address` union
    - AddressSchema
      - `first_name` string
      - `last_name` string
      - `company_name` string
      - `address_line` string, required: Address line, e.g. street and house number, or PO Box
      - `address_line_extra` string: Additional address line, e.g. apartment number or company name
      - `postal_code` string, required
      - `city` string, required: City name (min-length of 1 due to logographic languages)
      - `country_iso3` string, required: ISO 3166-1 alpha-3 code of country
      - `region_code` string: Region code, e.g. state or province code (ISO 3166-2), if available
      - `phone` string: Phone number related to this address, if any
    - Empty
  - `timezone` string: Timezone of the recipient, if known, not required, but strongly recommended
  - `order_status` string: Current status of the order, as setup in the system
  - `has_multiple_shipments` boolean, nullable: Indicates this order has been split into multiple shipments
  - `cancelled_date` string, date-time, nullable: Datetime when the order was cancelled
  - `cancelled_reason` 'customer' | 'inventory' | 'payment' | 'other': * `customer` - Customer * `inventory` - Inventory * `payment` - Payment-related * `other` - Other
  - `additional_attributes` AdditionalAttribute[]
    - `key` string, required: The key of the additional attribute
    - `value` unknown
  - `tags` string[]: Tags for the object, format <key>:<value>e.g. 'category:Home Apparel'
  - `mutations` union[]
    - union
      - AddOrUpdateTrackingMutation: Add or update tracking data.
        - `operation_id` string, uuid: The unique ID of the operation, generated by parcelLab, if not provided
        - `result` MutationResult: The result of a mutation
          - `success` boolean: Whether the mutation was successful
          - `message` string: A message describing the result of the mutation
          - `errors` object: A dictionary of errors that occurred during the mutation
          - `warnings` string[]: Non-fatal warnings raised while processing the mutation
        - `type` 'add_tracking'
        - `tracking` TrackingSchema, required: Tracking model used by v4 API in conjunction with order model
          - `tracking_number` string: Tracking number of the shipment, if available. If no tracking number is available, transport number, consignment number or reference number should be used.
          - `client_key` string: Name of the client (e.g. brand), as configured in account setup.
          - `courier` string: Key of the courier, if available (required, unless transport number, consignment number or reference number are provided)
          - `external_reference` string: Unique retailer-provided reference of the shipment, either this tracking number is required
          - `order_external_reference` string: External order identifier from the source platform (e.g. the Shopify order id)
          - `recipient_postal_code` string: 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.
          - `recipient_phone` string: Recipient phone number, if known, may be required for communication
          - `destination_country_iso3` string: ISO 3166-1 alpha-3 code of the destination country, if different from order destination country
          - `language_iso2` string: ISO 639-1 language code of the recipient, if known, required for localized communication
          - `timezone` string: Timezone of the recipient, if known, required for localized communication
          - `courier_service_level` string: Service level of the courier, if known
          - `delivery_method` string: Delivery method (e.g. 'standard shipping'), needs to be set up in the system
          - `shipping_address` union: Recipient address, if different from order
            - AddressSchema
              - …
            - Empty
          - `recipient_email` string: Recipient email address, if different from order
          - `recipient_name` string: Recipient name used in messages (e.g. 'Max'), if different from order
          - `additional_recipients` AdditionalRecipient[]: Additional recipients with role and email
            - `role` string: Role of the additional recipient
            - `email` string: Email address of the additional recipient
          - `cancelled_date` string, date-time: Date when the tracking was cancelled
          - `is_return` boolean: Whether the tracking is return or pre-generated return label
          - `identifiers_consignment` string: Consignment of the shipment
          - `delivery_number` string: Number of shipment in order
          - `invoice_number` string: Invoice number of the shipment
          - `shipping_cost_total` string: Total cost of shipping
          - `shipping_cost_net` string: Net amount for shipping
          - `shipping_cost_discount` string: Discount amount for shipping
          - `shipping_weight_total` number: Total weight of the shipment
          - `shipping_weight_unit` 'g' | 'kg' | 'lbs': Weight unit for shipping measurements.
          - `shipping_volume_total` number: Total volume of the shipment
          - `shipping_volume_unit` string: Unit for total shipping volume
          - `shipping_height` number: Total height of the shipment
          - `shipping_width` number: Total width of the shipment
          - `shipping_length` number: Total length of the shipment
          - `shipping_dimensions_unit` 'mm' | 'cm' | 'm', nullable: Unit for shipping dimensions (height, width, length)
          - `requires_signature` boolean: Whether the shipment requires a signature
          - `is_dropshipment` boolean: Is Dropshipment
          - `transport_number` string: Transport number of the shipment, if available. If no transport number is available, consignment number or reference number must be used.
          - `courier_reference_number` string: Courier reference number of the shipment, if available.
          - `origin_country_iso3` string: ISO 3166-1 alpha-3 code of origin country, if known
          - `origin_region` string: Origin region code (ISO 3166-2) of the shipment, if known
          - `origin_postal_code` string: Origin postal (zip) code of the shipment, if known
          - `articles` LineItem[]: List of articles in the shipment
            - `version` 'v1' | 'v2'
            - `line_item_id` string, required: Retailer ID of the line item
            - `product_id` string: Parent product identifier in the retailer's system (shared across variants).
            - `variant_id` string: SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.
            - `sku` string: Stock Keeping Unit of the line item
            - `barcode` string: Barcode associated with the line item variant or product
            - `order_item_id` string: Line Item ID in the order (preferred when provided)
            - `article_name` string: Name of the article
            - `article_description` string: Description of the article
            - `article_category` string: Category of the article
            - `article_store_url` string: URL to the article in the store
            - `article_image_url` string: URL to the image of the article
            - `article_brand` string: Brand of the article (reference only)
            - `size` string: Size of the article (reference only)
            - `color` string: Color of the article (reference only)
            - `width` number: Width of the article (in millimeters)
            - `height` number: Height of the article (in millimeters)
            - `length` number: Length of the article (in millimeters)
            - `length_unit` 'cm'
            - `weight` number: Weight of the article (in grams, kg, lbs, or oz)
            - `weight_unit` 'kg' | 'g' | 'lbs' | 'oz'
            - `unit_price` string: Paid unit price of the article (post-discount)
            - `unit_price_original` string: Original unit price of the article (pre-discount)
            - `quantity` integer: Unit quantity of the article
            - `amount_invoiced` string: Paid line total amount for this line item (post-discount)
            - `tax_amount` string: Total tax amount for this line item (regardless of taxesIncluded)
            - `harmonized_system_code` string: HS/HTS code for customs classification
            - `origin_country_iso3` string: ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations
            - `is_bulky` boolean: If the article is bulky
            - `tags` string[]: Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'
            - `bundle` BundleInfo
              - …
            - `additional_attributes` AdditionalAttribute[]: Additional attributes for this line item
              - …
          - `warehouse` string: Warehouse code of originating warehouse, if known, required for EDD calculation
          - `courier_contact_name` string: Courier Contact Name
          - `courier_contact_phone` string: Courier contact phone number, if known
          - `courier_contact_email` string: Courier contact email address, if known
          - `review_link` string: Link to review the delivery
          - `status_link` string: Link to track the status of the delivery
          - `collection_code_retailer` string: Collection code of the shipment, if known
          - `collection_code_carrier` string: Collection code of the shipment, if known
          - `announced_send_date` string, date: Announced send date of the shipment
          - `announced_delivery_date` string, date: Announced delivery date
          - `announced_delivery_date_min` string, date: Announced delivery date range
          - `announced_delivery_date_max` string, date: Announced delivery date range
          - `notifications_inactive` boolean: Notifications are inactive
          - `flags` TrackingFlagEnum[]: Extra flags for the tracking
          - `cash_on_delivery_amount` number: Cash on delivery amount
          - `tags` string[]: Tags for the tracking, format <key>:<value>, e.g. 'category:Home Apparel
          - `checkpoints` CheckpointSchema[]: List of checkpoints for the tracking
            - `status_code` string
            - `message` string
            - `courier` string
            - `exception` string[]
            - `delivery_location` string
            - `event_timestamp` string, date-time, required
            - `courier_status` string, required
          - `additional_fields` unknown
      - CancelTrackingMutation: Cancel tracking data.
        - `operation_id` string, uuid: The unique ID of the operation, generated by parcelLab, if not provided
        - `result` MutationResult: The result of a mutation
          - `success` boolean: Whether the mutation was successful
          - `message` string: A message describing the result of the mutation
          - `errors` object: A dictionary of errors that occurred during the mutation
          - `warnings` string[]: Non-fatal warnings raised while processing the mutation
        - `type` 'cancel_tracking', required
        - `tracking` TrackingSchema, required: Tracking model used by v4 API in conjunction with order model
          - `tracking_number` string: Tracking number of the shipment, if available. If no tracking number is available, transport number, consignment number or reference number should be used.
          - `client_key` string: Name of the client (e.g. brand), as configured in account setup.
          - `courier` string: Key of the courier, if available (required, unless transport number, consignment number or reference number are provided)
          - `external_reference` string: Unique retailer-provided reference of the shipment, either this tracking number is required
          - `order_external_reference` string: External order identifier from the source platform (e.g. the Shopify order id)
          - `recipient_postal_code` string: 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.
          - `recipient_phone` string: Recipient phone number, if known, may be required for communication
          - `destination_country_iso3` string: ISO 3166-1 alpha-3 code of the destination country, if different from order destination country
          - `language_iso2` string: ISO 639-1 language code of the recipient, if known, required for localized communication
          - `timezone` string: Timezone of the recipient, if known, required for localized communication
          - `courier_service_level` string: Service level of the courier, if known
          - `delivery_method` string: Delivery method (e.g. 'standard shipping'), needs to be set up in the system
          - `shipping_address` union: Recipient address, if different from order
            - AddressSchema
              - …
            - Empty
          - `recipient_email` string: Recipient email address, if different from order
          - `recipient_name` string: Recipient name used in messages (e.g. 'Max'), if different from order
          - `additional_recipients` AdditionalRecipient[]: Additional recipients with role and email
            - `role` string: Role of the additional recipient
            - `email` string: Email address of the additional recipient
          - `cancelled_date` string, date-time: Date when the tracking was cancelled
          - `is_return` boolean: Whether the tracking is return or pre-generated return label
          - `identifiers_consignment` string: Consignment of the shipment
          - `delivery_number` string: Number of shipment in order
          - `invoice_number` string: Invoice number of the shipment
          - `shipping_cost_total` string: Total cost of shipping
          - `shipping_cost_net` string: Net amount for shipping
          - `shipping_cost_discount` string: Discount amount for shipping
          - `shipping_weight_total` number: Total weight of the shipment
          - `shipping_weight_unit` 'g' | 'kg' | 'lbs': Weight unit for shipping measurements.
          - `shipping_volume_total` number: Total volume of the shipment
          - `shipping_volume_unit` string: Unit for total shipping volume
          - `shipping_height` number: Total height of the shipment
          - `shipping_width` number: Total width of the shipment
          - `shipping_length` number: Total length of the shipment
          - `shipping_dimensions_unit` 'mm' | 'cm' | 'm', nullable: Unit for shipping dimensions (height, width, length)
          - `requires_signature` boolean: Whether the shipment requires a signature
          - `is_dropshipment` boolean: Is Dropshipment
          - `transport_number` string: Transport number of the shipment, if available. If no transport number is available, consignment number or reference number must be used.
          - `courier_reference_number` string: Courier reference number of the shipment, if available.
          - `origin_country_iso3` string: ISO 3166-1 alpha-3 code of origin country, if known
          - `origin_region` string: Origin region code (ISO 3166-2) of the shipment, if known
          - `origin_postal_code` string: Origin postal (zip) code of the shipment, if known
          - `articles` LineItem[]: List of articles in the shipment
            - `version` 'v1' | 'v2'
            - `line_item_id` string, required: Retailer ID of the line item
            - `product_id` string: Parent product identifier in the retailer's system (shared across variants).
            - `variant_id` string: SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.
            - `sku` string: Stock Keeping Unit of the line item
            - `barcode` string: Barcode associated with the line item variant or product
            - `order_item_id` string: Line Item ID in the order (preferred when provided)
            - `article_name` string: Name of the article
            - `article_description` string: Description of the article
            - `article_category` string: Category of the article
            - `article_store_url` string: URL to the article in the store
            - `article_image_url` string: URL to the image of the article
            - `article_brand` string: Brand of the article (reference only)
            - `size` string: Size of the article (reference only)
            - `color` string: Color of the article (reference only)
            - `width` number: Width of the article (in millimeters)
            - `height` number: Height of the article (in millimeters)
            - `length` number: Length of the article (in millimeters)
            - `length_unit` 'cm'
            - `weight` number: Weight of the article (in grams, kg, lbs, or oz)
            - `weight_unit` 'kg' | 'g' | 'lbs' | 'oz'
            - `unit_price` string: Paid unit price of the article (post-discount)
            - `unit_price_original` string: Original unit price of the article (pre-discount)
            - `quantity` integer: Unit quantity of the article
            - `amount_invoiced` string: Paid line total amount for this line item (post-discount)
            - `tax_amount` string: Total tax amount for this line item (regardless of taxesIncluded)
            - `harmonized_system_code` string: HS/HTS code for customs classification
            - `origin_country_iso3` string: ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations
            - `is_bulky` boolean: If the article is bulky
            - `tags` string[]: Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'
            - `bundle` BundleInfo
              - …
            - `additional_attributes` AdditionalAttribute[]: Additional attributes for this line item
              - …
          - `warehouse` string: Warehouse code of originating warehouse, if known, required for EDD calculation
          - `courier_contact_name` string: Courier Contact Name
          - `courier_contact_phone` string: Courier contact phone number, if known
          - `courier_contact_email` string: Courier contact email address, if known
          - `review_link` string: Link to review the delivery
          - `status_link` string: Link to track the status of the delivery
          - `collection_code_retailer` string: Collection code of the shipment, if known
          - `collection_code_carrier` string: Collection code of the shipment, if known
          - `announced_send_date` string, date: Announced send date of the shipment
          - `announced_delivery_date` string, date: Announced delivery date
          - `announced_delivery_date_min` string, date: Announced delivery date range
          - `announced_delivery_date_max` string, date: Announced delivery date range
          - `notifications_inactive` boolean: Notifications are inactive
          - `flags` TrackingFlagEnum[]: Extra flags for the tracking
          - `cash_on_delivery_amount` number: Cash on delivery amount
          - `tags` string[]: Tags for the tracking, format <key>:<value>, e.g. 'category:Home Apparel
          - `checkpoints` CheckpointSchema[]: List of checkpoints for the tracking
            - `status_code` string
            - `message` string
            - `courier` string
            - `exception` string[]
            - `delivery_location` string
            - `event_timestamp` string, date-time, required
            - `courier_status` string, required
          - `additional_fields` unknown
      - CancelOrderMutation: Cancel an order.
        - `operation_id` string, uuid: The unique ID of the operation, generated by parcelLab, if not provided
        - `result` MutationResult: The result of a mutation
          - `success` boolean: Whether the mutation was successful
          - `message` string: A message describing the result of the mutation
          - `errors` object: A dictionary of errors that occurred during the mutation
          - `warnings` string[]: Non-fatal warnings raised while processing the mutation
        - `type` 'cancel_order'
        - `cancelled_reason` 'customer' | 'inventory' | 'payment' | 'other'
        - `cancelled_date` string, date-time, nullable: Datetime when the order was cancelled
      - ChangeLineItemQuantityMutation: Set absolute quantity for an existing line item (0 = cancel).
        - `operation_id` string, uuid: The unique ID of the operation, generated by parcelLab, if not provided
        - `result` MutationResult: The result of a mutation
          - `success` boolean: Whether the mutation was successful
          - `message` string: A message describing the result of the mutation
          - `errors` object: A dictionary of errors that occurred during the mutation
          - `warnings` string[]: Non-fatal warnings raised while processing the mutation
        - `type` 'change_line_item_quantity'
        - `line_item_id` string, required: ID of the line item to update
        - `quantity` integer, required: Absolute quantity to set (0 = cancel)
        - `current_quantity` integer, nullable: If set, mutation is applied only when stored quantity matches this value
        - `reason` string, nullable: Reason for the change
      - AddLineItemMutation: Append a brand-new line item to the order.
        - `operation_id` string, uuid: The unique ID of the operation, generated by parcelLab, if not provided
        - `result` MutationResult: The result of a mutation
          - `success` boolean: Whether the mutation was successful
          - `message` string: A message describing the result of the mutation
          - `errors` object: A dictionary of errors that occurred during the mutation
          - `warnings` string[]: Non-fatal warnings raised while processing the mutation
        - `type` 'add_line_item'
        - `line_item` LineItemOrder, required
          - `version` 'v1' | 'v2'
          - `line_item_id` string, required: Retailer ID of the line item
          - `product_id` string: Parent product identifier in the retailer's system (shared across variants).
          - `variant_id` string: SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.
          - `sku` string: Stock Keeping Unit of the line item
          - `barcode` string: Barcode associated with the line item variant or product
          - `order_item_id` string: Line Item ID in the order (preferred when provided)
          - `article_name` string: Name of the article
          - `article_description` string: Description of the article
          - `article_category` string: Category of the article
          - `article_store_url` string: URL to the article in the store
          - `article_image_url` string: URL to the image of the article
          - `article_brand` string: Brand of the article (reference only)
          - `size` string: Size of the article (reference only)
          - `color` string: Color of the article (reference only)
          - `width` number: Width of the article (in millimeters)
          - `height` number: Height of the article (in millimeters)
          - `length` number: Length of the article (in millimeters)
          - `length_unit` 'cm'
          - `weight` number: Weight of the article (in grams, kg, lbs, or oz)
          - `weight_unit` 'kg' | 'g' | 'lbs' | 'oz'
          - `unit_price` string: Paid unit price of the article (post-discount)
          - `unit_price_original` string: Original unit price of the article (pre-discount)
          - `quantity` integer: Unit quantity of the article
          - `amount_invoiced` string: Paid line total amount for this line item (post-discount)
          - `tax_amount` string: Total tax amount for this line item (regardless of taxesIncluded)
          - `harmonized_system_code` string: HS/HTS code for customs classification
          - `origin_country_iso3` string: ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations
          - `is_bulky` boolean: If the article is bulky
          - `tags` string[]: Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'
          - `bundle` BundleInfo
            - `group_id` string, required: Bundle group identifier in the retailer's system.
            - `role` 'parent' | 'component', required
            - `return_policy` 'parent_only' | 'components_only' | 'parent_and_components'
            - `parent_product_id` string: Parent bundle product identifier in the retailer's system.
            - `parent_variant_id` string: Parent bundle variant identifier in the retailer's system.
            - `parent_sku` string: Parent bundle SKU, if available.
            - `parent_title` string: Display title for the bundle parent, if available.
            - `parent_quantity` integer: Quantity of the bundle parent purchased in the order.
            - `component_quantity_per_parent` integer: Component quantity per single bundle parent (if determinable).
            - `selection_mode` 'individual' | 'group_on_first_pick'
            - `allocation_method` 'none' | 'component_price' | 'msrp_ratio' | 'equal'
            - `allocated_unit_price` string: Snapshot of allocated component unit price (if derived from bundle totals).
            - `allocated_amount_invoiced` string: Snapshot of allocated component invoiced amount (if derived from bundle totals).
          - `additional_attributes` AdditionalAttribute[]: Additional attributes for this line item
            - `key` string, required: The key of the additional attribute
            - `value` unknown
          - `status` 'shipped' | 'pending' | 'processing' | 'cancelled' | 'returned'
          - `original_quantity` integer: Original quantity before any adjustments (automatically set by system)
          - `change_reason` string: Reason for the most recent quantity change
          - `updated_at` string, date-time: Timestamp when this line item was last updated
      - ReplaceLineItemMutation: Cancel old line item & add substitute atomically.
        - `operation_id` string, uuid: The unique ID of the operation, generated by parcelLab, if not provided
        - `result` MutationResult: The result of a mutation
          - `success` boolean: Whether the mutation was successful
          - `message` string: A message describing the result of the mutation
          - `errors` object: A dictionary of errors that occurred during the mutation
          - `warnings` string[]: Non-fatal warnings raised while processing the mutation
        - `type` 'replace_line_item'
        - `old_line_item_id` string, required: Line item to be replaced (cancelled)
        - `new_line_item` LineItemOrder, required
          - `version` 'v1' | 'v2'
          - `line_item_id` string, required: Retailer ID of the line item
          - `product_id` string: Parent product identifier in the retailer's system (shared across variants).
          - `variant_id` string: SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.
          - `sku` string: Stock Keeping Unit of the line item
          - `barcode` string: Barcode associated with the line item variant or product
          - `order_item_id` string: Line Item ID in the order (preferred when provided)
          - `article_name` string: Name of the article
          - `article_description` string: Description of the article
          - `article_category` string: Category of the article
          - `article_store_url` string: URL to the article in the store
          - `article_image_url` string: URL to the image of the article
          - `article_brand` string: Brand of the article (reference only)
          - `size` string: Size of the article (reference only)
          - `color` string: Color of the article (reference only)
          - `width` number: Width of the article (in millimeters)
          - `height` number: Height of the article (in millimeters)
          - `length` number: Length of the article (in millimeters)
          - `length_unit` 'cm'
          - `weight` number: Weight of the article (in grams, kg, lbs, or oz)
          - `weight_unit` 'kg' | 'g' | 'lbs' | 'oz'
          - `unit_price` string: Paid unit price of the article (post-discount)
          - `unit_price_original` string: Original unit price of the article (pre-discount)
          - `quantity` integer: Unit quantity of the article
          - `amount_invoiced` string: Paid line total amount for this line item (post-discount)
          - `tax_amount` string: Total tax amount for this line item (regardless of taxesIncluded)
          - `harmonized_system_code` string: HS/HTS code for customs classification
          - `origin_country_iso3` string: ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations
          - `is_bulky` boolean: If the article is bulky
          - `tags` string[]: Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'
          - `bundle` BundleInfo
            - `group_id` string, required: Bundle group identifier in the retailer's system.
            - `role` 'parent' | 'component', required
            - `return_policy` 'parent_only' | 'components_only' | 'parent_and_components'
            - `parent_product_id` string: Parent bundle product identifier in the retailer's system.
            - `parent_variant_id` string: Parent bundle variant identifier in the retailer's system.
            - `parent_sku` string: Parent bundle SKU, if available.
            - `parent_title` string: Display title for the bundle parent, if available.
            - `parent_quantity` integer: Quantity of the bundle parent purchased in the order.
            - `component_quantity_per_parent` integer: Component quantity per single bundle parent (if determinable).
            - `selection_mode` 'individual' | 'group_on_first_pick'
            - `allocation_method` 'none' | 'component_price' | 'msrp_ratio' | 'equal'
            - `allocated_unit_price` string: Snapshot of allocated component unit price (if derived from bundle totals).
            - `allocated_amount_invoiced` string: Snapshot of allocated component invoiced amount (if derived from bundle totals).
          - `additional_attributes` AdditionalAttribute[]: Additional attributes for this line item
            - `key` string, required: The key of the additional attribute
            - `value` unknown
          - `status` 'shipped' | 'pending' | 'processing' | 'cancelled' | 'returned'
          - `original_quantity` integer: Original quantity before any adjustments (automatically set by system)
          - `change_reason` string: Reason for the most recent quantity change
          - `updated_at` string, date-time: Timestamp when this line item was last updated
        - `reason` string, nullable: Reason for replacement

## Response `200`

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

- Order: Create a new order record with shipment and recipient data.
  - `account` integer, required: Account to which this order belongs
  - `order_number` string, required: Order number (customer facing)
  - `external_id` string, required: Unique identifier for this order, generated by parcelLab for this order
  - `external_reference` string: Retailer reference (e.g. internal system ID) for this order, unique.
  - `client_key` string: Name of the technical client / shop (corresponds to the system setup), e.g. 'mybrand-a.com'
  - `destination_country_iso3` string, required: Destination country ISO 3166-1 alpha 3 code
  - `language_iso2` string: ISO 639-1 language code of the recipient, if known, required for localized communication
  - `shipping_address` union
    - AddressSchema
      - `first_name` string
      - `last_name` string
      - `company_name` string
      - `address_line` string, required: Address line, e.g. street and house number, or PO Box
      - `address_line_extra` string: Additional address line, e.g. apartment number or company name
      - `postal_code` string, required
      - `city` string, required: City name (min-length of 1 due to logographic languages)
      - `country_iso3` string, required: ISO 3166-1 alpha-3 code of country
      - `region_code` string: Region code, e.g. state or province code (ISO 3166-2), if available
      - `phone` string: Phone number related to this address, if any
    - Empty
  - `delivery_method` string: Delivery method (e.g. 'standard shipping'), needs to be set up in the system
  - `recipient_email` union, required: Recipient email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead.
    - string, email
    - '_unset'
  - `recipient_name` string: Recipient name
  - `additional_recipients` AdditionalRecipient[]
    - `role` string: Role of the additional recipient
    - `email` string: Email address of the additional recipient
  - `customer_number` string: Customer number (e.g. from the retailer)
  - `invoice_number` string: Invoice number (e.g. from the retailer)
  - `payment_method` string: Payment method (e.g. 'credit card')
  - `order_total_amount` string, decimal, nullable: Total amount of the order (usually after tax & discount)
  - `order_tax_amount` string, decimal, nullable: Tax amount of the original order
  - `order_net_amount` string, decimal, nullable: Net amount of the order (usually before tax)
  - `order_discount_amount` string, decimal, nullable: Discount amount of the order
  - `order_currency` string: Currency of the order, e.g. USD, EUR (ISO 4217)
  - `payments` object[]
  - `order_date` string, date-time, nullable: Date and time when the order was placed
  - `channel` string: Channel through which the order was placed (e.g. 'webshop')
  - `announced_delivery_date` string, date, nullable: Announced delivery date
  - `announced_delivery_date_min` string, date, nullable: Announced delivery date range of order (min)
  - `announced_delivery_date_max` string, date, nullable: Announced delivery date range of order (min)
  - `articles_order` LineItemOrder[]
    - `version` 'v1' | 'v2'
    - `line_item_id` string, required: Retailer ID of the line item
    - `product_id` string: Parent product identifier in the retailer's system (shared across variants).
    - `variant_id` string: SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.
    - `sku` string: Stock Keeping Unit of the line item
    - `barcode` string: Barcode associated with the line item variant or product
    - `order_item_id` string: Line Item ID in the order (preferred when provided)
    - `article_name` string: Name of the article
    - `article_description` string: Description of the article
    - `article_category` string: Category of the article
    - `article_store_url` string: URL to the article in the store
    - `article_image_url` string: URL to the image of the article
    - `article_brand` string: Brand of the article (reference only)
    - `size` string: Size of the article (reference only)
    - `color` string: Color of the article (reference only)
    - `width` number: Width of the article (in millimeters)
    - `height` number: Height of the article (in millimeters)
    - `length` number: Length of the article (in millimeters)
    - `length_unit` 'cm'
    - `weight` number: Weight of the article (in grams, kg, lbs, or oz)
    - `weight_unit` 'kg' | 'g' | 'lbs' | 'oz'
    - `unit_price` string: Paid unit price of the article (post-discount)
    - `unit_price_original` string: Original unit price of the article (pre-discount)
    - `quantity` integer: Unit quantity of the article
    - `amount_invoiced` string: Paid line total amount for this line item (post-discount)
    - `tax_amount` string: Total tax amount for this line item (regardless of taxesIncluded)
    - `harmonized_system_code` string: HS/HTS code for customs classification
    - `origin_country_iso3` string: ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations
    - `is_bulky` boolean: If the article is bulky
    - `tags` string[]: Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'
    - `bundle` BundleInfo
      - `group_id` string, required: Bundle group identifier in the retailer's system.
      - `role` 'parent' | 'component', required
      - `return_policy` 'parent_only' | 'components_only' | 'parent_and_components'
      - `parent_product_id` string: Parent bundle product identifier in the retailer's system.
      - `parent_variant_id` string: Parent bundle variant identifier in the retailer's system.
      - `parent_sku` string: Parent bundle SKU, if available.
      - `parent_title` string: Display title for the bundle parent, if available.
      - `parent_quantity` integer: Quantity of the bundle parent purchased in the order.
      - `component_quantity_per_parent` integer: Component quantity per single bundle parent (if determinable).
      - `selection_mode` 'individual' | 'group_on_first_pick'
      - `allocation_method` 'none' | 'component_price' | 'msrp_ratio' | 'equal'
      - `allocated_unit_price` string: Snapshot of allocated component unit price (if derived from bundle totals).
      - `allocated_amount_invoiced` string: Snapshot of allocated component invoiced amount (if derived from bundle totals).
    - `additional_attributes` AdditionalAttribute[]: Additional attributes for this line item
      - `key` string, required: The key of the additional attribute
      - `value` unknown
    - `status` 'shipped' | 'pending' | 'processing' | 'cancelled' | 'returned'
    - `original_quantity` integer: Original quantity before any adjustments (automatically set by system)
    - `change_reason` string: Reason for the most recent quantity change
    - `updated_at` string, date-time: Timestamp when this line item was last updated
  - `billing_address` union
    - AddressSchema
      - `first_name` string
      - `last_name` string
      - `company_name` string
      - `address_line` string, required: Address line, e.g. street and house number, or PO Box
      - `address_line_extra` string: Additional address line, e.g. apartment number or company name
      - `postal_code` string, required
      - `city` string, required: City name (min-length of 1 due to logographic languages)
      - `country_iso3` string, required: ISO 3166-1 alpha-3 code of country
      - `region_code` string: Region code, e.g. state or province code (ISO 3166-2), if available
      - `phone` string: Phone number related to this address, if any
    - Empty
  - `timezone` string: Timezone of the recipient, if known, not required, but strongly recommended
  - `order_status` string: Current status of the order, as setup in the system
  - `has_multiple_shipments` boolean, nullable: Indicates this order has been split into multiple shipments
  - `cancelled_date` string, date-time, nullable: Datetime when the order was cancelled
  - `cancelled_reason` 'customer' | 'inventory' | 'payment' | 'other': * `customer` - Customer * `inventory` - Inventory * `payment` - Payment-related * `other` - Other
  - `additional_attributes` AdditionalAttribute[]
    - `key` string, required: The key of the additional attribute
    - `value` unknown
  - `tags` string[]: Tags for the object, format <key>:<value>e.g. 'category:Home Apparel'
  - `mutations` union[]
    - union
      - AddOrUpdateTrackingMutation: Add or update tracking data.
        - `operation_id` string, uuid: The unique ID of the operation, generated by parcelLab, if not provided
        - `result` MutationResult: The result of a mutation
          - `success` boolean: Whether the mutation was successful
          - `message` string: A message describing the result of the mutation
          - `errors` object: A dictionary of errors that occurred during the mutation
          - `warnings` string[]: Non-fatal warnings raised while processing the mutation
        - `type` 'add_tracking'
        - `tracking` TrackingSchema, required: Tracking model used by v4 API in conjunction with order model
          - `tracking_number` string: Tracking number of the shipment, if available. If no tracking number is available, transport number, consignment number or reference number should be used.
          - `client_key` string: Name of the client (e.g. brand), as configured in account setup.
          - `courier` string: Key of the courier, if available (required, unless transport number, consignment number or reference number are provided)
          - `external_reference` string: Unique retailer-provided reference of the shipment, either this tracking number is required
          - `order_external_reference` string: External order identifier from the source platform (e.g. the Shopify order id)
          - `recipient_postal_code` string: 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.
          - `recipient_phone` string: Recipient phone number, if known, may be required for communication
          - `destination_country_iso3` string: ISO 3166-1 alpha-3 code of the destination country, if different from order destination country
          - `language_iso2` string: ISO 639-1 language code of the recipient, if known, required for localized communication
          - `timezone` string: Timezone of the recipient, if known, required for localized communication
          - `courier_service_level` string: Service level of the courier, if known
          - `delivery_method` string: Delivery method (e.g. 'standard shipping'), needs to be set up in the system
          - `shipping_address` union: Recipient address, if different from order
            - AddressSchema
              - …
            - Empty
          - `recipient_email` string: Recipient email address, if different from order
          - `recipient_name` string: Recipient name used in messages (e.g. 'Max'), if different from order
          - `additional_recipients` AdditionalRecipient[]: Additional recipients with role and email
            - `role` string: Role of the additional recipient
            - `email` string: Email address of the additional recipient
          - `cancelled_date` string, date-time: Date when the tracking was cancelled
          - `is_return` boolean: Whether the tracking is return or pre-generated return label
          - `identifiers_consignment` string: Consignment of the shipment
          - `delivery_number` string: Number of shipment in order
          - `invoice_number` string: Invoice number of the shipment
          - `shipping_cost_total` string: Total cost of shipping
          - `shipping_cost_net` string: Net amount for shipping
          - `shipping_cost_discount` string: Discount amount for shipping
          - `shipping_weight_total` number: Total weight of the shipment
          - `shipping_weight_unit` 'g' | 'kg' | 'lbs': Weight unit for shipping measurements.
          - `shipping_volume_total` number: Total volume of the shipment
          - `shipping_volume_unit` string: Unit for total shipping volume
          - `shipping_height` number: Total height of the shipment
          - `shipping_width` number: Total width of the shipment
          - `shipping_length` number: Total length of the shipment
          - `shipping_dimensions_unit` 'mm' | 'cm' | 'm', nullable: Unit for shipping dimensions (height, width, length)
          - `requires_signature` boolean: Whether the shipment requires a signature
          - `is_dropshipment` boolean: Is Dropshipment
          - `transport_number` string: Transport number of the shipment, if available. If no transport number is available, consignment number or reference number must be used.
          - `courier_reference_number` string: Courier reference number of the shipment, if available.
          - `origin_country_iso3` string: ISO 3166-1 alpha-3 code of origin country, if known
          - `origin_region` string: Origin region code (ISO 3166-2) of the shipment, if known
          - `origin_postal_code` string: Origin postal (zip) code of the shipment, if known
          - `articles` LineItem[]: List of articles in the shipment
            - `version` 'v1' | 'v2'
            - `line_item_id` string, required: Retailer ID of the line item
            - `product_id` string: Parent product identifier in the retailer's system (shared across variants).
            - `variant_id` string: SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.
            - `sku` string: Stock Keeping Unit of the line item
            - `barcode` string: Barcode associated with the line item variant or product
            - `order_item_id` string: Line Item ID in the order (preferred when provided)
            - `article_name` string: Name of the article
            - `article_description` string: Description of the article
            - `article_category` string: Category of the article
            - `article_store_url` string: URL to the article in the store
            - `article_image_url` string: URL to the image of the article
            - `article_brand` string: Brand of the article (reference only)
            - `size` string: Size of the article (reference only)
            - `color` string: Color of the article (reference only)
            - `width` number: Width of the article (in millimeters)
            - `height` number: Height of the article (in millimeters)
            - `length` number: Length of the article (in millimeters)
            - `length_unit` 'cm'
            - `weight` number: Weight of the article (in grams, kg, lbs, or oz)
            - `weight_unit` 'kg' | 'g' | 'lbs' | 'oz'
            - `unit_price` string: Paid unit price of the article (post-discount)
            - `unit_price_original` string: Original unit price of the article (pre-discount)
            - `quantity` integer: Unit quantity of the article
            - `amount_invoiced` string: Paid line total amount for this line item (post-discount)
            - `tax_amount` string: Total tax amount for this line item (regardless of taxesIncluded)
            - `harmonized_system_code` string: HS/HTS code for customs classification
            - `origin_country_iso3` string: ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations
            - `is_bulky` boolean: If the article is bulky
            - `tags` string[]: Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'
            - `bundle` BundleInfo
              - …
            - `additional_attributes` AdditionalAttribute[]: Additional attributes for this line item
              - …
          - `warehouse` string: Warehouse code of originating warehouse, if known, required for EDD calculation
          - `courier_contact_name` string: Courier Contact Name
          - `courier_contact_phone` string: Courier contact phone number, if known
          - `courier_contact_email` string: Courier contact email address, if known
          - `review_link` string: Link to review the delivery
          - `status_link` string: Link to track the status of the delivery
          - `collection_code_retailer` string: Collection code of the shipment, if known
          - `collection_code_carrier` string: Collection code of the shipment, if known
          - `announced_send_date` string, date: Announced send date of the shipment
          - `announced_delivery_date` string, date: Announced delivery date
          - `announced_delivery_date_min` string, date: Announced delivery date range
          - `announced_delivery_date_max` string, date: Announced delivery date range
          - `notifications_inactive` boolean: Notifications are inactive
          - `flags` TrackingFlagEnum[]: Extra flags for the tracking
          - `cash_on_delivery_amount` number: Cash on delivery amount
          - `tags` string[]: Tags for the tracking, format <key>:<value>, e.g. 'category:Home Apparel
          - `checkpoints` CheckpointSchema[]: List of checkpoints for the tracking
            - `status_code` string
            - `message` string
            - `courier` string
            - `exception` string[]
            - `delivery_location` string
            - `event_timestamp` string, date-time, required
            - `courier_status` string, required
          - `additional_fields` unknown
      - CancelTrackingMutation: Cancel tracking data.
        - `operation_id` string, uuid: The unique ID of the operation, generated by parcelLab, if not provided
        - `result` MutationResult: The result of a mutation
          - `success` boolean: Whether the mutation was successful
          - `message` string: A message describing the result of the mutation
          - `errors` object: A dictionary of errors that occurred during the mutation
          - `warnings` string[]: Non-fatal warnings raised while processing the mutation
        - `type` 'cancel_tracking', required
        - `tracking` TrackingSchema, required: Tracking model used by v4 API in conjunction with order model
          - `tracking_number` string: Tracking number of the shipment, if available. If no tracking number is available, transport number, consignment number or reference number should be used.
          - `client_key` string: Name of the client (e.g. brand), as configured in account setup.
          - `courier` string: Key of the courier, if available (required, unless transport number, consignment number or reference number are provided)
          - `external_reference` string: Unique retailer-provided reference of the shipment, either this tracking number is required
          - `order_external_reference` string: External order identifier from the source platform (e.g. the Shopify order id)
          - `recipient_postal_code` string: 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.
          - `recipient_phone` string: Recipient phone number, if known, may be required for communication
          - `destination_country_iso3` string: ISO 3166-1 alpha-3 code of the destination country, if different from order destination country
          - `language_iso2` string: ISO 639-1 language code of the recipient, if known, required for localized communication
          - `timezone` string: Timezone of the recipient, if known, required for localized communication
          - `courier_service_level` string: Service level of the courier, if known
          - `delivery_method` string: Delivery method (e.g. 'standard shipping'), needs to be set up in the system
          - `shipping_address` union: Recipient address, if different from order
            - AddressSchema
              - …
            - Empty
          - `recipient_email` string: Recipient email address, if different from order
          - `recipient_name` string: Recipient name used in messages (e.g. 'Max'), if different from order
          - `additional_recipients` AdditionalRecipient[]: Additional recipients with role and email
            - `role` string: Role of the additional recipient
            - `email` string: Email address of the additional recipient
          - `cancelled_date` string, date-time: Date when the tracking was cancelled
          - `is_return` boolean: Whether the tracking is return or pre-generated return label
          - `identifiers_consignment` string: Consignment of the shipment
          - `delivery_number` string: Number of shipment in order
          - `invoice_number` string: Invoice number of the shipment
          - `shipping_cost_total` string: Total cost of shipping
          - `shipping_cost_net` string: Net amount for shipping
          - `shipping_cost_discount` string: Discount amount for shipping
          - `shipping_weight_total` number: Total weight of the shipment
          - `shipping_weight_unit` 'g' | 'kg' | 'lbs': Weight unit for shipping measurements.
          - `shipping_volume_total` number: Total volume of the shipment
          - `shipping_volume_unit` string: Unit for total shipping volume
          - `shipping_height` number: Total height of the shipment
          - `shipping_width` number: Total width of the shipment
          - `shipping_length` number: Total length of the shipment
          - `shipping_dimensions_unit` 'mm' | 'cm' | 'm', nullable: Unit for shipping dimensions (height, width, length)
          - `requires_signature` boolean: Whether the shipment requires a signature
          - `is_dropshipment` boolean: Is Dropshipment
          - `transport_number` string: Transport number of the shipment, if available. If no transport number is available, consignment number or reference number must be used.
          - `courier_reference_number` string: Courier reference number of the shipment, if available.
          - `origin_country_iso3` string: ISO 3166-1 alpha-3 code of origin country, if known
          - `origin_region` string: Origin region code (ISO 3166-2) of the shipment, if known
          - `origin_postal_code` string: Origin postal (zip) code of the shipment, if known
          - `articles` LineItem[]: List of articles in the shipment
            - `version` 'v1' | 'v2'
            - `line_item_id` string, required: Retailer ID of the line item
            - `product_id` string: Parent product identifier in the retailer's system (shared across variants).
            - `variant_id` string: SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.
            - `sku` string: Stock Keeping Unit of the line item
            - `barcode` string: Barcode associated with the line item variant or product
            - `order_item_id` string: Line Item ID in the order (preferred when provided)
            - `article_name` string: Name of the article
            - `article_description` string: Description of the article
            - `article_category` string: Category of the article
            - `article_store_url` string: URL to the article in the store
            - `article_image_url` string: URL to the image of the article
            - `article_brand` string: Brand of the article (reference only)
            - `size` string: Size of the article (reference only)
            - `color` string: Color of the article (reference only)
            - `width` number: Width of the article (in millimeters)
            - `height` number: Height of the article (in millimeters)
            - `length` number: Length of the article (in millimeters)
            - `length_unit` 'cm'
            - `weight` number: Weight of the article (in grams, kg, lbs, or oz)
            - `weight_unit` 'kg' | 'g' | 'lbs' | 'oz'
            - `unit_price` string: Paid unit price of the article (post-discount)
            - `unit_price_original` string: Original unit price of the article (pre-discount)
            - `quantity` integer: Unit quantity of the article
            - `amount_invoiced` string: Paid line total amount for this line item (post-discount)
            - `tax_amount` string: Total tax amount for this line item (regardless of taxesIncluded)
            - `harmonized_system_code` string: HS/HTS code for customs classification
            - `origin_country_iso3` string: ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations
            - `is_bulky` boolean: If the article is bulky
            - `tags` string[]: Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'
            - `bundle` BundleInfo
              - …
            - `additional_attributes` AdditionalAttribute[]: Additional attributes for this line item
              - …
          - `warehouse` string: Warehouse code of originating warehouse, if known, required for EDD calculation
          - `courier_contact_name` string: Courier Contact Name
          - `courier_contact_phone` string: Courier contact phone number, if known
          - `courier_contact_email` string: Courier contact email address, if known
          - `review_link` string: Link to review the delivery
          - `status_link` string: Link to track the status of the delivery
          - `collection_code_retailer` string: Collection code of the shipment, if known
          - `collection_code_carrier` string: Collection code of the shipment, if known
          - `announced_send_date` string, date: Announced send date of the shipment
          - `announced_delivery_date` string, date: Announced delivery date
          - `announced_delivery_date_min` string, date: Announced delivery date range
          - `announced_delivery_date_max` string, date: Announced delivery date range
          - `notifications_inactive` boolean: Notifications are inactive
          - `flags` TrackingFlagEnum[]: Extra flags for the tracking
          - `cash_on_delivery_amount` number: Cash on delivery amount
          - `tags` string[]: Tags for the tracking, format <key>:<value>, e.g. 'category:Home Apparel
          - `checkpoints` CheckpointSchema[]: List of checkpoints for the tracking
            - `status_code` string
            - `message` string
            - `courier` string
            - `exception` string[]
            - `delivery_location` string
            - `event_timestamp` string, date-time, required
            - `courier_status` string, required
          - `additional_fields` unknown
      - CancelOrderMutation: Cancel an order.
        - `operation_id` string, uuid: The unique ID of the operation, generated by parcelLab, if not provided
        - `result` MutationResult: The result of a mutation
          - `success` boolean: Whether the mutation was successful
          - `message` string: A message describing the result of the mutation
          - `errors` object: A dictionary of errors that occurred during the mutation
          - `warnings` string[]: Non-fatal warnings raised while processing the mutation
        - `type` 'cancel_order'
        - `cancelled_reason` 'customer' | 'inventory' | 'payment' | 'other'
        - `cancelled_date` string, date-time, nullable: Datetime when the order was cancelled
      - ChangeLineItemQuantityMutation: Set absolute quantity for an existing line item (0 = cancel).
        - `operation_id` string, uuid: The unique ID of the operation, generated by parcelLab, if not provided
        - `result` MutationResult: The result of a mutation
          - `success` boolean: Whether the mutation was successful
          - `message` string: A message describing the result of the mutation
          - `errors` object: A dictionary of errors that occurred during the mutation
          - `warnings` string[]: Non-fatal warnings raised while processing the mutation
        - `type` 'change_line_item_quantity'
        - `line_item_id` string, required: ID of the line item to update
        - `quantity` integer, required: Absolute quantity to set (0 = cancel)
        - `current_quantity` integer, nullable: If set, mutation is applied only when stored quantity matches this value
        - `reason` string, nullable: Reason for the change
      - AddLineItemMutation: Append a brand-new line item to the order.
        - `operation_id` string, uuid: The unique ID of the operation, generated by parcelLab, if not provided
        - `result` MutationResult: The result of a mutation
          - `success` boolean: Whether the mutation was successful
          - `message` string: A message describing the result of the mutation
          - `errors` object: A dictionary of errors that occurred during the mutation
          - `warnings` string[]: Non-fatal warnings raised while processing the mutation
        - `type` 'add_line_item'
        - `line_item` LineItemOrder, required
          - `version` 'v1' | 'v2'
          - `line_item_id` string, required: Retailer ID of the line item
          - `product_id` string: Parent product identifier in the retailer's system (shared across variants).
          - `variant_id` string: SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.
          - `sku` string: Stock Keeping Unit of the line item
          - `barcode` string: Barcode associated with the line item variant or product
          - `order_item_id` string: Line Item ID in the order (preferred when provided)
          - `article_name` string: Name of the article
          - `article_description` string: Description of the article
          - `article_category` string: Category of the article
          - `article_store_url` string: URL to the article in the store
          - `article_image_url` string: URL to the image of the article
          - `article_brand` string: Brand of the article (reference only)
          - `size` string: Size of the article (reference only)
          - `color` string: Color of the article (reference only)
          - `width` number: Width of the article (in millimeters)
          - `height` number: Height of the article (in millimeters)
          - `length` number: Length of the article (in millimeters)
          - `length_unit` 'cm'
          - `weight` number: Weight of the article (in grams, kg, lbs, or oz)
          - `weight_unit` 'kg' | 'g' | 'lbs' | 'oz'
          - `unit_price` string: Paid unit price of the article (post-discount)
          - `unit_price_original` string: Original unit price of the article (pre-discount)
          - `quantity` integer: Unit quantity of the article
          - `amount_invoiced` string: Paid line total amount for this line item (post-discount)
          - `tax_amount` string: Total tax amount for this line item (regardless of taxesIncluded)
          - `harmonized_system_code` string: HS/HTS code for customs classification
          - `origin_country_iso3` string: ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations
          - `is_bulky` boolean: If the article is bulky
          - `tags` string[]: Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'
          - `bundle` BundleInfo
            - `group_id` string, required: Bundle group identifier in the retailer's system.
            - `role` 'parent' | 'component', required
            - `return_policy` 'parent_only' | 'components_only' | 'parent_and_components'
            - `parent_product_id` string: Parent bundle product identifier in the retailer's system.
            - `parent_variant_id` string: Parent bundle variant identifier in the retailer's system.
            - `parent_sku` string: Parent bundle SKU, if available.
            - `parent_title` string: Display title for the bundle parent, if available.
            - `parent_quantity` integer: Quantity of the bundle parent purchased in the order.
            - `component_quantity_per_parent` integer: Component quantity per single bundle parent (if determinable).
            - `selection_mode` 'individual' | 'group_on_first_pick'
            - `allocation_method` 'none' | 'component_price' | 'msrp_ratio' | 'equal'
            - `allocated_unit_price` string: Snapshot of allocated component unit price (if derived from bundle totals).
            - `allocated_amount_invoiced` string: Snapshot of allocated component invoiced amount (if derived from bundle totals).
          - `additional_attributes` AdditionalAttribute[]: Additional attributes for this line item
            - `key` string, required: The key of the additional attribute
            - `value` unknown
          - `status` 'shipped' | 'pending' | 'processing' | 'cancelled' | 'returned'
          - `original_quantity` integer: Original quantity before any adjustments (automatically set by system)
          - `change_reason` string: Reason for the most recent quantity change
          - `updated_at` string, date-time: Timestamp when this line item was last updated
      - ReplaceLineItemMutation: Cancel old line item & add substitute atomically.
        - `operation_id` string, uuid: The unique ID of the operation, generated by parcelLab, if not provided
        - `result` MutationResult: The result of a mutation
          - `success` boolean: Whether the mutation was successful
          - `message` string: A message describing the result of the mutation
          - `errors` object: A dictionary of errors that occurred during the mutation
          - `warnings` string[]: Non-fatal warnings raised while processing the mutation
        - `type` 'replace_line_item'
        - `old_line_item_id` string, required: Line item to be replaced (cancelled)
        - `new_line_item` LineItemOrder, required
          - `version` 'v1' | 'v2'
          - `line_item_id` string, required: Retailer ID of the line item
          - `product_id` string: Parent product identifier in the retailer's system (shared across variants).
          - `variant_id` string: SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.
          - `sku` string: Stock Keeping Unit of the line item
          - `barcode` string: Barcode associated with the line item variant or product
          - `order_item_id` string: Line Item ID in the order (preferred when provided)
          - `article_name` string: Name of the article
          - `article_description` string: Description of the article
          - `article_category` string: Category of the article
          - `article_store_url` string: URL to the article in the store
          - `article_image_url` string: URL to the image of the article
          - `article_brand` string: Brand of the article (reference only)
          - `size` string: Size of the article (reference only)
          - `color` string: Color of the article (reference only)
          - `width` number: Width of the article (in millimeters)
          - `height` number: Height of the article (in millimeters)
          - `length` number: Length of the article (in millimeters)
          - `length_unit` 'cm'
          - `weight` number: Weight of the article (in grams, kg, lbs, or oz)
          - `weight_unit` 'kg' | 'g' | 'lbs' | 'oz'
          - `unit_price` string: Paid unit price of the article (post-discount)
          - `unit_price_original` string: Original unit price of the article (pre-discount)
          - `quantity` integer: Unit quantity of the article
          - `amount_invoiced` string: Paid line total amount for this line item (post-discount)
          - `tax_amount` string: Total tax amount for this line item (regardless of taxesIncluded)
          - `harmonized_system_code` string: HS/HTS code for customs classification
          - `origin_country_iso3` string: ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations
          - `is_bulky` boolean: If the article is bulky
          - `tags` string[]: Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'
          - `bundle` BundleInfo
            - `group_id` string, required: Bundle group identifier in the retailer's system.
            - `role` 'parent' | 'component', required
            - `return_policy` 'parent_only' | 'components_only' | 'parent_and_components'
            - `parent_product_id` string: Parent bundle product identifier in the retailer's system.
            - `parent_variant_id` string: Parent bundle variant identifier in the retailer's system.
            - `parent_sku` string: Parent bundle SKU, if available.
            - `parent_title` string: Display title for the bundle parent, if available.
            - `parent_quantity` integer: Quantity of the bundle parent purchased in the order.
            - `component_quantity_per_parent` integer: Component quantity per single bundle parent (if determinable).
            - `selection_mode` 'individual' | 'group_on_first_pick'
            - `allocation_method` 'none' | 'component_price' | 'msrp_ratio' | 'equal'
            - `allocated_unit_price` string: Snapshot of allocated component unit price (if derived from bundle totals).
            - `allocated_amount_invoiced` string: Snapshot of allocated component invoiced amount (if derived from bundle totals).
          - `additional_attributes` AdditionalAttribute[]: Additional attributes for this line item
            - `key` string, required: The key of the additional attribute
            - `value` unknown
          - `status` 'shipped' | 'pending' | 'processing' | 'cancelled' | 'returned'
          - `original_quantity` integer: Original quantity before any adjustments (automatically set by system)
          - `change_reason` string: Reason for the most recent quantity change
          - `updated_at` string, date-time: Timestamp when this line item was last updated
        - `reason` string, nullable: Reason for replacement

## Other responses

- `201`: Order payload. Mutation actions include `mutations[].result`. Non-fatal validation warnings are returned in `mutations[].result.warnings`; accepted mutation failures are returned as `mutations[].result.success=false`.
- `400`: Bad request. Payload validation errors use the standard error list shape. Early order identifier and account authorization failures use a direct detail response.
- `403`
- `404`

## Changes

- **2026-11-03** `84524f38b6c9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/parcellab/apis/parcellab-api/changes/v4/track/orders/put.md)

---

[API](https://skmtc.dev/parcellab/apis/parcellab-api.md) - [All operations](https://skmtc.dev/parcellab/apis/parcellab-api/llms.txt) - [OpenAPI document](https://skmtc.dev/parcellab/apis/parcellab-api/revisions/84524f38b6c9?raw)