Create Orders/Trackings

The Order API provides a comprehensive, idempotent endpoint for managing order and tracking data in the parcelLab system.

This API allows you to create new orders, update existing orders, add shipment trackings, cancel trackings, and manage partial line item cancellations.

Endpoint Details

• Method: PUT

• Path: /v4/track/orders/

• Full URL: https://product-api.parcellab.com/v4/track/orders/

• Authentication: Header Authorization: Parcellab-API-Token <token>

This endpoint is idempotent, meaning you can safely call it multiple times with the same data without creating duplicate orders. If an order exists, it will be updated; if not, it will be created.

Authentication

Use the Authorization header with this format:

Authorization: Parcellab-API-Token <token>

API tokens can be created at https://app.parcellab.com/service/account/apitoken/. For PUT /v4/track/orders/, the token must include at least the write scope. Make sure to use the API token (non-encoded version, not the encoded token).

Error Handling

The API returns standard HTTP status codes:

• 200 OK - Order successfully updated

• 201 Created - New order created

• 400 Bad Request - Invalid request data

• 401 Unauthorized - Missing or invalid authentication

• 403 Forbidden - Insufficient permissions

• 404 Not Found - Order not found (for GET requests)

Validation Errors

{
  "errors": [
    {
      "detail": "Cannot cancel 3 of item ITEM-001. Only 2 available.",
      "attr": "mutations.0.line_items.0.quantity_to_cancel",
      "code": "invalid"
    }
  ],
  "type": "validation_error"
}

Mutation Results

Each mutation includes a result indicating success or failure:

{
  "mutations": [
    {
      "type": "change_line_item_quantity",
      "result": {
        "success": true,
        "message": "Successfully cancelled items: ITEM-001"
      }
    }
  ]
}

Best Practices

1. Use Idempotent Updates: The PUT endpoint is idempotent. Use it for both creation and updates to avoid duplicates.

2. Partial Updates: Only send the fields you want to update. The API merges changes with existing data.

3. Order Identification: Use either order_number + account or external_id to identify orders. When creating new orders, external_id is generated by parcelLab and returned in the response.

4. Tracking Identification: Trackings require either tracking_number + courier or external_reference.

5. Validate Line Item Quantities: Before cancelling, ensure the requested quantity doesn't exceed available quantity.

6. Use Mutations for Actions: Use mutations for adding trackings or cancelling items rather than direct field updates.

7. Tags: You can set tags on a tracking to identify custom attributes in filters and exports. For example: tags: ["loyalty_customer", "customer_loyalty:gold", "international_order", "dropship"].

Data Models

Order Schema

For upserts, send only the fields you want to set or update.

Recommended fields to send

Field	Type	When to send	Notes
account	integer	Always	Required
order_number	string	Create + most updates	Primary external reference in most integrations.
destination_country_iso3	string	Create	Required on create.
recipient_email	string	Create	Required on create.
recipient_name	string	Recommended	Useful for notifications and lookup UX.
client_key	string	Recommended	Important for multi-brand/multi-shop accounts.
shipping_address	AddressSchema	Recommended	Strongly recommended if available.
billing_address	AddressSchema	Optional	Useful if billing and shipping differ.
language_iso2	string	Recommended	Enables localized communication.
timezone	string	Optional	Helps communication timing.
delivery_method	string	Optional	Must be configured in system.
articles_order	LineItemOrder[]	Recommended	Needed for line-item-level mutations and visibility.
external_reference	string	Optional	Retailer internal order reference.
customer_number	string	Optional	Retailer customer identifier.
invoice_number	string	Optional	Invoice reference.
payment_method	string	Optional	Payment method.
order_currency	string	Optional	ISO 4217
order_total_amount	decimal	Optional	Order total.
order_tax_amount	decimal	Optional	Tax amount.
order_net_amount	decimal	Optional	Net amount.
order_discount_amount	decimal	Optional	Discount amount.
order_date	datetime	Optional	Order creation timestamp.
channel	string	Optional	Sales channel.
announced_delivery_date_min	date	Optional	Earliest expected delivery.
announced_delivery_date_max	date	Optional	Latest expected delivery.
tags	string[]	Optional	For filtering/export.
additional_attributes	AdditionalAttribute[]	Optional	Custom attributes.
mutations	Mutation[]	Optional	Use for tracking and line-item changes.

Generated/returned by parcelLab

• external_id (UUID): generated by parcelLab on create.

• mutations[].operation_id (UUID): generated if not provided.

• mutations[].result: populated in responses with per-mutation processing status.

Line Item Order Schema

Represents individual products in articles_order.

Recommended fields to send

Field	Type	Notes
line_item_id	string	Required identifier for mutations.
quantity	integer	Ordered/open quantity.
sku	string	Recommended
product_id	string	Recommended
variant_id	string	Recommended when variants exist.
article_name	string	Recommended for portal display.
article_category	string	Optional
article_store_url	string	Optional
article_image_url	string	Optional
unit_price	decimal	Optional
tags	string[]	Optional
additional_attributes	AdditionalAttribute[]	Optional

Generated/managed by parcelLab

• shipped_quantity

• original_quantity

• status

• change_reason

• updated_at

Tracking Schema

Represent an individual shipment, package or parcel used to fulfill (parts of) an order.

Recommended fields to send

Field	Type	Notes
tracking_number + courier	string + string	Primary tracking identifier pair.
external_reference	string	Alternative identifier where applicable.
articles	LineItem[]	Recommended for shipment-level line-item mapping.
destination_country_iso3	string	Recommended
recipient_postal_code	string	Recommended when full address is not sent.
shipping_address	AddressSchema	Recommended if tracking-level address differs.
courier_service_level	string	Optional
warehouse	string	Optional
origin_country_iso3	string	Optional
origin_postal_code	string	Optional
announced_delivery_date	date	Optional ETA communication.
announced_send_date	date	Optional
delivery_method	string	Optional
shipping_cost_total	decimal	Optional
shipping_weight_total	float	Optional
shipping_weight_unit	string	Optional
requires_signature	boolean	Optional
is_return	boolean	Optional
flags	string[]	Optional
tags	string[]	Optional
additional_fields	object	Optional custom payload.

Generated/managed by parcelLab

• cancelled_date can be set by parcelLab when a cancel_tracking mutation is processed.

Example tracking payload as JSON

{
  "tracking_number": "1234567890",
  "courier": "dhl",
  "external_reference": "SHIP-2024-001",
  "recipient_postal_code": "10001",
  "destination_country_iso3": "USA",
  "language_iso2": "en",
  "timezone": "America/New_York",
  "courier_service_level": "express",
  "warehouse": "WH-US-EAST",
  "origin_country_iso3": "USA",
  "origin_postal_code": "07001",
  "announced_delivery_date": "2024-01-18",
  "announced_send_date": "2024-01-16",
  "shipping_weight_total": 1500,
  "shipping_weight_unit": "g",
  "requires_signature": true,
  "articles": [
    {
      "line_item_id": "ITEM-001",
      "product_id": "PROD-123",
      "article_name": "Blue T-Shirt",
      "quantity": 2,
      "sku": "TSHIRT-BLUE-M"
    }
  ],
  "tags": ["express-delivery", "high-value"],
  "additional_fields": {
    "special_instructions": "Handle with care"
  }
}

Additional Data

parcelLab in general allows you to send additional attributes with custom data. For full data-element definitions, refer to the following page.

Data Model

Mutations

Mutations allow you to perform actions on orders.

AddOrUpdateTrackingMutation

Adds or updates a tracking of an order. Update an existing tracking by running this mutation and using the same values for keys courier and tracking_number, as the combined value of those fields are idempotent.

{
  "type": "add_tracking",
  "tracking": {
    // TrackingSchema fields
  }
}

CancelTrackingMutation

Cancel a tracking by identifying it by its courier and tracking_number.

{
  "type": "cancel_tracking",
  "tracking": {
    "tracking_number": "1234567890",
    "courier": "dhl"
    // Only identifiers needed
  }
}

ChangeLineItemQuantityMutation

Cancel individual quantity of an order line item. Quantities already assigned to a tracking are considered fulfilled and cannot be cancelled anymore.

{
  "type": "change_line_item_quantity",
  "line_item_id": "ITEM-001",
  "quantity": 0,
  "current_quantity": 1,
  "reason": "customer_changed_mind"
}

AddLineItemMutation

Adds a line item to an order.

{
  "type": "add_line_item",
  "line_item": {
    "line_item_id": "ITEM-NEW",
    "product_id": "PROD-999",
    "article_name": "Green Hat",
    "quantity": 1,
    "unit_price": "19.99"
  }
}

ReplaceLineItemMutation

Replaces a line item with another line item. To cancel a line item, replace it with a quantity: 0 line item.

{
  "type": "replace_line_item",
  "old_line_item_id": "ITEM-001",
  "new_line_item": {
    "line_item_id": "ITEM-NEW2",
    "product_id": "PROD-888",
    "article_name": "Red Hat",
    "quantity": 1,
    "unit_price": "19.99"
  },
  "reason": "size_exchange"
}

Typical Use Cases for OMS and WMS Integration

You can use the Order API to update parcelLab about all updates on the order from placement to cancellation or fulfillment.

Integration Flow

1. Order Placement: Create the order with all known information

2. Cancellations: Handle partial or full cancellations as needed

3. Fulfillment: Add trackings as items ship

4. Delivery: System automatically updates based on carrier events (outside of this API)

Sample Mutations

Create a New Order

Request:

PUT /v4/track/orders/

{
  "account": 1234,
  "order_number": "ORD-2024-001",
  "recipient_email": "[email protected]",
  "recipient_name": "John Doe",
  "destination_country_iso3": "USA",
  "language_iso2": "en",
  "order_total_amount": "129.99",
  "order_currency": "USD",
  "order_date": "2024-01-15T10:30:00Z",
  "shipping_address": {
    "first_name": "John",
    "last_name": "Doe",
    "address_line": "123 Main St",
    "city": "New York",
    "postal_code": "10001",
    "country_iso3": "USA",
    "region_code": "NY"
  },
  "articles_order": [
    {
      "line_item_id": "ITEM-001",
      "product_id": "PROD-123",
      "article_name": "Blue T-Shirt",
      "quantity": 2,
      "unit_price": "29.99"
    },
    {
      "line_item_id": "ITEM-002",
      "product_id": "PROD-456",
      "article_name": "Black Jeans",
      "quantity": 1,
      "unit_price": "69.99"
    }
  ]
}

Response:

{
  "external_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "order_number": "ORD-2024-001"
  // ... all order fields ...
}

Update an Existing Order

Only send the fields you want to update:

Request:

PUT /v4/track/orders/

{
  "order_number": "ORD-2024-001",
  "account": 1234,
  "customer_number": "CUST-98765",
  "payment_method": "credit_card"
}

Add Tracking to an Order

Request:

PUT /v4/track/orders/

{
  "order_number": "ORD-2024-001",
  "account": 1234,
  "mutations": [
    {
      "type": "add_tracking",
      "tracking": {
        "tracking_number": "1234567890",
        "courier": "dhl",
        "warehouse": "WH-01",
        "announced_delivery_date": "2024-01-18",
        "articles": [
          {
            "line_item_id": "ITEM-001",
            "quantity": 2
          }
        ]
      }
    }
  ]
}

Cancel a Tracking

Request:

PUT /v4/track/orders/

{
  "order_number": "ORD-2024-001",
  "account": 1234,
  "mutations": [
    {
      "type": "cancel_tracking",
      "tracking": {
        "tracking_number": "1234567890",
        "courier": "dhl"
      }
    }
  ]
}

Cancel Line Items (Partial Cancellation)

This allows cancelling specific quantities of line items at the order level:

Request:

PUT /v4/track/orders/

{
  "order_number": "ORD-2024-001",
  "account": 1234,
  "mutations": [
    {
      "type": "change_line_item_quantity",
      "line_item_id": "ITEM-001",
      "quantity": 0,
      "current_quantity": 1,
      "reason": "customer_changed_mind"
    }
  ]
}

Notes on Line Item Cancellation:

• Cancellations are tracked at the order level in articles_order

• The system validates quantity constraints (including shipped quantity guards)

• When line items are cancelled, updates are sent to all trackings in the order

• Line item mutation metadata is stored on the item (for example status, original_quantity, change_reason, updated_at)

Complex Multi-Operation Update

You can combine multiple operations in a single request:

Request:

PUT /v4/track/orders/

{
  "order_number": "ORD-2024-001",
  "account": 1234,
  "customer_number": "CUST-UPDATE",  // Update order field
  "mutations": [
    {
      "type": "add_tracking",
      "tracking": {
        "tracking_number": "9876543210",
        "courier": "ups",
        "articles": [
          {
            "line_item_id": "ITEM-002",
            "quantity": 1
          }
        ]
      }
    },
    {
      "type": "change_line_item_quantity",
      "line_item_id": "ITEM-001",
      "quantity": 0,
      "current_quantity": 1,
      "reason": "customer_changed_mind"
    }
  ]
}

OMS Mixed Status Example (2 Cancelled, 3 Shipped, 1 Remaining)

Scenario:

• order_number: OMS-100045

• Line LINE-1 was ordered with quantity 6

• OMS then cancels 2

• FedEx ships 3

• 1 remains open/backordered for later shipment

Step 1: Create the order (minimal but valid create payload):

PUT /v4/track/orders/

{
  "account": 1234,
  "order_number": "OMS-100045",
  "destination_country_iso3": "USA",
  "recipient_email": "[email protected]",
  "articles_order": [
    {
      "line_item_id": "LINE-1",
      "sku": "SKU-RED-42",
      "quantity": 6
    },
    {
      "line_item_id": "LINE-2",
      "sku": "SKU-BLUE-10",
      "quantity": 1
    },
    {
      "line_item_id": "LINE-3",
      "sku": "SKU-GREEN-7",
      "quantity": 1
    }
  ]
}

Step 2: OMS partial cancellation (6→4) using change_line_item_quantity:

PUT /v4/track/orders/

{
  "account": 1234,
  "order_number": "OMS-100045",
  "mutations": [
    {
      "type": "change_line_item_quantity",
      "line_item_id": "LINE-1",
      "quantity": 4,
      "current_quantity": 6,
      "reason": "oms_partial_cancel"
    }
  ]
}

Step 3: First FedEx shipment (3 units) using add_tracking:

PUT /v4/track/orders/

{
  "account": 1234,
  "order_number": "OMS-100045",
  "mutations": [
    {
      "type": "add_tracking",
      "tracking": {
        "tracking_number": "794600000001",
        "courier": "fedex",
        "articles": [
          {
            "line_item_id": "LINE-1",
            "quantity": 3
          }
        ]
      }
    }
  ]
}

Step 4: Remaining quantity (1) is implicit.

No additional mutation is required to represent "not yet shipped/backordered". At this point:

• Ordered/open quantity for LINE-1 is 4

• Shipped quantity recorded across trackings is 3

• Remaining not-yet-shipped quantity is 1

Step 5a (later): If the remaining 1 ships, send another add_tracking:

PUT /v4/track/orders/

{
  "account": 1234,
  "order_number": "OMS-100045",
  "mutations": [
    {
      "type": "add_tracking",
      "tracking": {
        "tracking_number": "794600000002",
        "courier": "fedex",
        "articles": [
          {
            "line_item_id": "LINE-1",
            "quantity": 1
          }
        ]
      }
    }
  ]
}

Step 5b (alternative): If the remaining 1 is cancelled instead of shipped:

PUT /v4/track/orders/
{
  "account": 1234,
  "order_number": "OMS-100045",
  "mutations": [
    {
      "type": "change_line_item_quantity",
      "line_item_id": "LINE-1",
      "quantity": 3,
      "current_quantity": 4,
      "reason": "oms_cancel_remaining"
    }
  ]
}

Other Minimal Mutation Payloads (Same order_number Pattern)

Add a line item:

PUT /v4/track/orders/

{
  "account": 1234,
  "order_number": "OMS-100045",
  "mutations": [
    {
      "type": "add_line_item",
      "line_item": {
        "line_item_id": "LINE-4",
        "sku": "SKU-BLACK-9",
        "quantity": 1
      }
    }
  ]
}

Replace a line item (substitution):

PUT /v4/track/orders/

{
  "account": 1234,
  "order_number": "OMS-100045",
  "mutations": [
    {
      "type": "replace_line_item",
      "old_line_item_id": "LINE-2",
      "new_line_item": {
        "line_item_id": "LINE-2B",
        "sku": "SKU-BLUE-10-V2",
        "quantity": 1
      },
      "reason": "substitution"
    }
  ]
}

Cancel an existing tracking (e.g., label voided):

PUT /v4/track/orders/

{
  "account": 1234,
  "order_number": "OMS-100045",
  "mutations": [
    {
      "type": "cancel_tracking",
      "tracking": {
        "tracking_number": "794600000001",
        "courier": "fedex"
      }
    }
  ]
}