Create an international shipment

This guide walks through creating a cross-border shipment from Japan to the United States using YunExpress. The same flow applies to any supported courier and shipping lane.

Before you start

You have an API key and API token from onboarding (see Authentication)
You know your courier slug and product code (see Couriers and product codes)

1. Prepare the shipment data

An international shipment requires:

Ship-from address — your warehouse or fulfillment center
Ship-to address — the customer’s delivery address
Parcel details — weight and item-level customs declarations (English description, quantity, unit price, unit weight)

Customs declarations (descriptionEn, unitPrice, unitWeight) are required for cross-border shipments. Missing or inaccurate customs data can cause delays at customs clearance.

Item unitPrice.amount values must be at least 0.01. Free gifts, samples, and promotional inserts must still be declared at a nominal value of 0.01 or higher, never 0. Item unitPrice.currency values must be in USD. The optional unitPrice.currency field accepts only USD; omitting it also means USD. If you need to supply your own IOSS code to the carrier, send it in customs.taxIds.ioss. The API trims and uses a supplied non-blank value. If the field is omitted or left blank and the destination is an EU tax country, FlexForward’s default IOSS code is applied automatically. A code you registered under IOSS registrations is not applied automatically unless you send it in the request. Applying FlexForward’s default code is chargeable because a VAT pre-payment and service charge are posted alongside the shipping charge to recover destination VAT. Supplying your own code here is not charged.

2. Create the label

Use a unique idempotencyKey for every new label; the example uses the placeholder unique-key-per-request, and order.customerOrderNumber uses N-2026-05-27-TEST-03. Replace both with your own unique values before each run. Order numbers accept 1–40 ASCII letters, digits, -, and _; see Customer order numbers. Reuse the key and unchanged body when retrying. A changed body with the same key returns 409 IDEMPOTENCY_CONFLICT; see Idempotency and Retries for the legacy-record exception.

curl -X POST https://api.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://api.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();

import requests

response = requests.post(
    'https://api.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()

3. Check the response

201 Created

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "customerOrderNumber": "N-2026-05-27-TEST-03",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": null,
  "error": null
}

If status is created, the label is ready. Save the id — you’ll use it to retrieve the label document and track the shipment. If status is failed, check the error object for the courier’s rejection reason. See Error Handling for guidance.

4. Next steps

Retrieve the label document

Download the printable PDF or PNG label to attach to the package.

Track the shipment

Monitor shipment progress with normalized tracking data.

Tips for international shipments

HS codes — Including Harmonized System codes (hsCode) speeds up customs clearance. Look up codes at your country’s customs authority.
Local descriptions — The descriptionLocal field provides item descriptions in the destination country’s language, which can help with customs processing.
Idempotency — Always use a meaningful idempotencyKey (e.g., your order ID) so retries are safe. See Idempotency and Retries.

Getting Started

Guides

Use-Case Guides

Platform

Create an International Shipment

Create an international shipment

Before you start

1. Prepare the shipment data

2. Create the label

3. Check the response

4. Next steps

Retrieve the label document

Track the shipment

Tips for international shipments

​Create an international shipment

​Before you start

​1. Prepare the shipment data

​2. Create the label

​3. Check the response

​4. Next steps

Retrieve the label document

Track the shipment

​Tips for international shipments

Create an international shipment

Before you start

1. Prepare the shipment data

2. Create the label

3. Check the response

4. Next steps

Tips for international shipments