> ## Documentation Index
> Fetch the complete documentation index at: https://openapidocs.flexforwardship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an International Shipment

> End-to-end guide for creating a cross-border shipping label

# 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 token from onboarding (see [Authentication](/authentication#how-access-works))
* You know your courier slug and product code (see [Couriers and product codes](/core-concepts#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)

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

## 2. Create the label

<Note>
  Replace `unique-key-per-request` with your own unique value on every call. Reusing the same `idempotencyKey` returns the original result (idempotent replay) instead of creating a new label.
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.flexforward.com/labels \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "idempotencyKey": "unique-key-per-request",
      "courier": "yunexpress",
      "service": {
        "productCode": "HKMUZXR"
      },
      "shipment": {
        "shipFrom": {
          "contact": {
            "firstName": "Warehouse",
            "lastName": "Staff",
            "phone": "+81-90-1234-5678"
          },
          "address": {
            "countryCode": "JP",
            "city": "Tokyo",
            "postalCode": "100-0001",
            "streetLines": ["1-1 Marunouchi"]
          }
        },
        "shipTo": {
          "contact": {
            "firstName": "Jane",
            "lastName": "Smith",
            "phone": "+1-555-0100",
            "email": "jane.smith@example.com"
          },
          "address": {
            "countryCode": "US",
            "city": "Los Angeles",
            "state": "CA",
            "postalCode": "90001",
            "streetLines": ["456 Oak Avenue", "Apt 12"]
          }
        },
        "parcels": [
          {
            "weight": 0.8,
            "items": [
              {
                "descriptionEn": "Cotton T-Shirt",
                "descriptionLocal": "コットンTシャツ",
                "quantity": 2,
                "unitPrice": { "amount": 29.99, "currency": "USD" },
                "unitWeight": 0.3,
                "hsCode": "6109.10"
              },
              {
                "descriptionEn": "Phone Case",
                "descriptionLocal": "スマホケース",
                "quantity": 1,
                "unitPrice": { "amount": 12.00, "currency": "USD" },
                "unitWeight": 0.2,
                "hsCode": "3926.90"
              }
            ]
          }
        ]
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.flexforward.com/labels', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      idempotencyKey: 'unique-key-per-request',
      courier: 'yunexpress',
      service: {
        productCode: 'HKMUZXR'
      },
      shipment: {
        shipFrom: {
          contact: { firstName: 'Warehouse', lastName: 'Staff', phone: '+81-90-1234-5678' },
          address: { countryCode: 'JP', city: 'Tokyo', postalCode: '100-0001', streetLines: ['1-1 Marunouchi'] }
        },
        shipTo: {
          contact: { firstName: 'Jane', lastName: 'Smith', phone: '+1-555-0100', email: 'jane.smith@example.com' },
          address: { countryCode: 'US', city: 'Los Angeles', state: 'CA', postalCode: '90001', streetLines: ['456 Oak Avenue', 'Apt 12'] }
        },
        parcels: [{
          weight: 0.8,
          items: [
            { descriptionEn: 'Cotton T-Shirt', descriptionLocal: 'コットンTシャツ', quantity: 2, unitPrice: { amount: 29.99, currency: 'USD' }, unitWeight: 0.3, hsCode: '6109.10' },
            { descriptionEn: 'Phone Case', descriptionLocal: 'スマホケース', quantity: 1, unitPrice: { amount: 12.00, currency: 'USD' }, unitWeight: 0.2, hsCode: '3926.90' }
          ]
        }]
      }
    })
  });
  const label = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.flexforward.com/labels',
      headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
      json={
          'idempotencyKey': 'unique-key-per-request',
          'courier': 'yunexpress',
          'service': {
              'productCode': 'HKMUZXR'
          },
          'shipment': {
              'shipFrom': {
                  'contact': {'firstName': 'Warehouse', 'lastName': 'Staff', 'phone': '+81-90-1234-5678'},
                  'address': {'countryCode': 'JP', 'city': 'Tokyo', 'postalCode': '100-0001', 'streetLines': ['1-1 Marunouchi']}
              },
              'shipTo': {
                  'contact': {'firstName': 'Jane', 'lastName': 'Smith', 'phone': '+1-555-0100', 'email': 'jane.smith@example.com'},
                  'address': {'countryCode': 'US', 'city': 'Los Angeles', 'state': 'CA', 'postalCode': '90001', 'streetLines': ['456 Oak Avenue', 'Apt 12']}
              },
              'parcels': [{
                  'weight': 0.8,
                  'items': [
                      {'descriptionEn': 'Cotton T-Shirt', 'descriptionLocal': 'コットンTシャツ', 'quantity': 2, 'unitPrice': {'amount': 29.99, 'currency': 'USD'}, 'unitWeight': 0.3, 'hsCode': '6109.10'},
                      {'descriptionEn': 'Phone Case', 'descriptionLocal': 'スマホケース', 'quantity': 1, 'unitPrice': {'amount': 12.00, 'currency': 'USD'}, 'unitWeight': 0.2, 'hsCode': '3926.90'}
                  ]
              }]
          }
      }
  )
  label = response.json()
  ```
</CodeGroup>

## 3. Check the response

```json 201 Created theme={null}
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": "YT2503010001CN",
  "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](/error-handling#downstream-courier-errors-502) for guidance.

## 4. Next steps

<CardGroup cols={2}>
  <Card title="Retrieve the label document" icon="file-pdf" href="/guides/label-documents">
    Download the airway bill PDF to attach to the package.
  </Card>

  <Card title="Track the shipment" icon="location-dot" href="/guides/tracking-updates">
    Monitor shipment progress with normalized tracking data.
  </Card>
</CardGroup>

## 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](/idempotency-and-retries).