Quickstart

This guide walks you through creating your first shipping label, retrieving the label document, and tracking the shipment.

Prerequisites

An API key and API token (see Authentication for how to obtain them)
curl or any HTTP client
The development base URL: https://sandbox.flexforwardship.com

Use the development environment for testing. It connects to courier sandbox services and does not create live shipments.

Step 1: Authenticate

Include both headers on every request:

x-rr-apikey: YOUR_API_KEY
x-rr-apitoken: YOUR_API_TOKEN

See the Authentication page for credential best practices and error responses.

Step 2: Create a label

Send a POST /labels request with your shipment details. The idempotencyKey ensures that retrying the same request does not create a duplicate label.

Replace idempotencyKey (unique-key-per-request) and order.customerOrderNumber (N-2026-05-27-TEST-03) with values that are unique to each run. Order numbers accept 1–40 ASCII letters, digits, -, and _. Re-sending the sample unchanged returns the stored result from the first run (HTTP 200); changing the body while reusing the key returns 409 IDEMPOTENCY_CONFLICT. See Idempotency and Retries for the legacy-record exception.

Minimum required fields: idempotencyKey, courier, service.productCode, shipment.shipTo (contact with firstName, address with countryCode, city, postalCode, streetLines), and at least one parcel with weight and one item (descriptionEn, quantity, unitPrice, unitWeight). The shipment.shipFrom field is required for certain couriers and shipping lanes — confirm requirements with the Flex Forward team during onboarding.

Use a courier code returned by GET /couriers. The examples below use yunexpress, but your valid values depend on the couriers enabled for your account.

curl -X POST https://sandbox.flexforwardship.com/labels \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "idempotencyKey": "unique-key-per-request",
      "courier": "yunexpress",
      "service": {
        "productCode": "HKMUZXR"
      },
      "label": {
        "format": "PDF"
      },
      "units": {
        "weight": "KG",
        "dimension": "CM"
      },
      "order": {
        "customerOrderNumber": "N-2026-05-27-TEST-03",
        "orderNumbers": {
          "platformOrderNumber": "platform-order-number",
          "referenceNumbers": [
            "ref-number-1",
            "ref-number-2"
          ]
        }
      },
      "shipment": {
        "shipTo": {
          "contact": {
            "firstName": "Alex",
            "lastName": "Smith",
            "phone": "8554377467",
            "email": "[email protected]"
          },
          "address": {
            "streetLines": [
              "18 Distribution Blvd"
            ],
            "city": "Edison",
            "state": "NJ",
            "postalCode": "08817",
            "countryCode": "US"
          }
        },
        "shipFrom": {
          "contact": {
            "firstName": "John",
            "lastName": "Doe",
            "phone": "886900676877",
            "email": "[email protected]"
          },
          "address": {
            "streetLines": [
              "Habucho"
            ],
            "city": "Kishiwada-Shi",
            "state": "Osaka",
            "postalCode": "596-0825",
            "countryCode": "JP"
          }
        },
        "parcels": [
          {
            "weight": 0.5,
            "dimension": {
              "length": 30,
              "width": 20,
              "height": 10
            },
            "items": [
              {
                "descriptionEn": "Muji Ink pen",
                "descriptionLocal": "文具",
                "quantity": 1,
                "unitPrice": {
                  "amount": 29.99,
                  "currency": "USD"
                },
                "unitWeight": 0.5
              }
            ]
          }
        ]
      },
      "serviceOptions": [
        {
          "code": "V1",
          "value": "云途预缴"
        }
      ],
      "courierOptions": {
        "yunexpress": {
          "sourceCode": "YT",
          "sensitiveType": "D"
        }
      }
  }'

const response = await fetch('https://sandbox.flexforwardship.com/labels', {
  method: 'POST',
  headers: {
    'x-rr-apikey': 'YOUR_API_KEY',
    'x-rr-apitoken': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(
    {
      idempotencyKey: 'unique-key-per-request',
      courier: 'yunexpress',
      service: {
        productCode: 'HKMUZXR'
      },
      label: {
        format: 'PDF'
      },
      units: {
        weight: 'KG',
        dimension: 'CM'
      },
      order: {
        customerOrderNumber: 'N-2026-05-27-TEST-03',
        orderNumbers: {
          platformOrderNumber: 'platform-order-number',
          referenceNumbers: [
            'ref-number-1',
            'ref-number-2'
          ]
        }
      },
      shipment: {
        shipTo: {
          contact: {
            firstName: 'Alex',
            lastName: 'Smith',
            phone: '8554377467',
            email: '[email protected]'
          },
          address: {
            streetLines: [
              '18 Distribution Blvd'
            ],
            city: 'Edison',
            state: 'NJ',
            postalCode: '08817',
            countryCode: 'US'
          }
        },
        shipFrom: {
          contact: {
            firstName: 'John',
            lastName: 'Doe',
            phone: '886900676877',
            email: '[email protected]'
          },
          address: {
            streetLines: [
              'Habucho'
            ],
            city: 'Kishiwada-Shi',
            state: 'Osaka',
            postalCode: '596-0825',
            countryCode: 'JP'
          }
        },
        parcels: [
          {
            weight: 0.5,
            dimension: {
              length: 30,
              width: 20,
              height: 10
            },
            items: [
              {
                descriptionEn: 'Muji Ink pen',
                descriptionLocal: '文具',
                quantity: 1,
                unitPrice: {
                  amount: 29.99,
                  currency: 'USD'
                },
                unitWeight: 0.5
              }
            ]
          }
        ]
      },
      serviceOptions: [
        {
          code: 'V1',
          value: '云途预缴'
        }
      ],
      courierOptions: {
        yunexpress: {
          sourceCode: 'YT',
          sensitiveType: 'D'
        }
      }
    }
  )
});
const label = await response.json();
console.log(label.id); // Use this ID for document retrieval and tracking

import requests

response = requests.post(
    'https://sandbox.flexforwardship.com/labels',
    headers={
        'x-rr-apikey': 'YOUR_API_KEY',
        'x-rr-apitoken': 'YOUR_API_TOKEN',
    },
    json={
        'idempotencyKey': 'unique-key-per-request',
        'courier': 'yunexpress',
        'service': {
            'productCode': 'HKMUZXR'
        },
        'label': {
            'format': 'PDF'
        },
        'units': {
            'weight': 'KG',
            'dimension': 'CM'
        },
        'order': {
            'customerOrderNumber': 'N-2026-05-27-TEST-03',
            'orderNumbers': {
                'platformOrderNumber': 'platform-order-number',
                'referenceNumbers': [
                    'ref-number-1',
                    'ref-number-2'
                ]
            }
        },
        'shipment': {
            'shipTo': {
                'contact': {
                    'firstName': 'Alex',
                    'lastName': 'Smith',
                    'phone': '8554377467',
                    'email': '[email protected]'
                },
                'address': {
                    'streetLines': [
                        '18 Distribution Blvd'
                    ],
                    'city': 'Edison',
                    'state': 'NJ',
                    'postalCode': '08817',
                    'countryCode': 'US'
                }
            },
            'shipFrom': {
                'contact': {
                    'firstName': 'John',
                    'lastName': 'Doe',
                    'phone': '886900676877',
                    'email': '[email protected]'
                },
                'address': {
                    'streetLines': [
                        'Habucho'
                    ],
                    'city': 'Kishiwada-Shi',
                    'state': 'Osaka',
                    'postalCode': '596-0825',
                    'countryCode': 'JP'
                }
            },
            'parcels': [
                {
                    'weight': 0.5,
                    'dimension': {
                        'length': 30,
                        'width': 20,
                        'height': 10
                    },
                    'items': [
                        {
                            'descriptionEn': 'Muji Ink pen',
                            'descriptionLocal': '文具',
                            'quantity': 1,
                            'unitPrice': {
                                'amount': 29.99,
                                'currency': 'USD'
                            },
                            'unitWeight': 0.5
                        }
                    ]
                }
            ]
        },
        'serviceOptions': [
            {
                'code': 'V1',
                'value': '云途预缴'
            }
        ],
        'courierOptions': {
            'yunexpress': {
                'sourceCode': 'YT',
                'sensitiveType': 'D'
            }
        }
    }
)
label = response.json()
print(label['id'])  # Use this ID for document retrieval and tracking

A successful response returns HTTP 201 with the label details:

201 Created

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customerOrderNumber": "N-2026-05-27-TEST-03",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": null,
  "error": null
}

Key fields in the response:

Field	Description
`id`	The label UUID. Use this to retrieve documents and tracking.
`customerOrderNumber`	Your supplied order number, or a system-generated value if omitted. Store this value; it can also retrieve documents and tracking. See Customer order numbers.
`status`	`created` on success, `failed` if the courier rejected the request.
`courierOrderNumber`	The order number assigned by the courier.
`courierTrackingNumber`	The last-mile carrier’s tracking number. Usually `null` at creation and filled in once the carrier assigns one — poll tracking to pick it up.
`error`	`null` on success. Contains `code` and `message` on failure.

If you retry the same request with the same idempotencyKey, the API returns HTTP 200 with the original result instead of creating a duplicate label. That stored result may have status: failed if the first attempt was rejected by the courier, so always check the status field rather than relying on the HTTP status code alone. See Idempotency and Retries and Error Handling for details.

Step 3: Retrieve the label document

Use the label id from the previous response to retrieve the airway bill document:

curl https://sandbox.flexforwardship.com/labels/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN"

200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customerOrderNumber": "N-2026-05-27-TEST-03",
  "url": "https://label-documents.example.com/labels/a1b2c3d4.pdf",
  "labelFormat": "pdf"
}

Download the PDF from the returned url to print the shipping label. This sample requests label.format: "PDF". You can also request "PNG" at creation; the document response then reports labelFormat: "png".

Step 4: Track the shipment

Use the same label id to retrieve tracking information:

curl https://sandbox.flexforwardship.com/tracking/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN"

200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "trackingNumber": "YT2503010001TN",
  "tag": "InfoReceived",
  "subtag": "InfoReceived_001",
  "subtagMessage": "Shipment information received",
  "slug": "yunexpress",
  "checkpoints": [
    {
      "checkpointTime": "2026-03-15T10:30:00Z",
      "city": "Tokyo",
      "state": "Tokyo",
      "countryRegion": "JP",
      "location": null,
      "message": "Shipment information received",
      "tag": "InfoReceived",
      "subtag": "InfoReceived_001",
      "subtagMessage": "Shipment information received",
      "slug": "yunexpress"
    }
  ]
}

The tag field provides the high-level shipment status. See Core Concepts for the full list of tracking statuses.

What success looks like

After completing this quickstart, verify you can:

Authenticate successfully with your API key and API token
Create a test label in the development environment
Retrieve a printable label document (PDF)
Fetch normalized tracking updates for your test label
Parse responses tolerantly — ignore unknown fields and enum values instead of rejecting them (see Versioning)

What’s next

Error Handling

Understand error responses and how to troubleshoot common issues.

Idempotency and Retries

Learn how to retry requests safely without creating duplicate labels.

Core Concepts

Understand the label lifecycle, tracking model, and carrier normalization.

Getting Started

Guides

Use-Case Guides

Platform

Quickstart

Quickstart

Prerequisites

Step 1: Authenticate

Step 2: Create a label

Step 3: Retrieve the label document

Step 4: Track the shipment

What success looks like

What’s next

Error Handling

Idempotency and Retries

Core Concepts

​Quickstart

​Prerequisites

​Step 1: Authenticate

​Step 2: Create a label

​Step 3: Retrieve the label document

​Step 4: Track the shipment

​What success looks like

​What’s next

Error Handling

Idempotency and Retries

Core Concepts

Quickstart

Prerequisites

Step 1: Authenticate

Step 2: Create a label

Step 3: Retrieve the label document

Step 4: Track the shipment

What success looks like

What’s next