Skip to main content

​
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

​
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.

​
2. Create the label

curl -X POST https://api.flexforward.com/labels \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "shipment-jp-us-001",
    "courier": "yunexpress",
    "service": {
      "shipperAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "productCode": "YEXP01"
    },
    "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": "[email protected]"
        },
        "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"
            }
          ]
        }
      ]
    }
  }'

​
3. Check the response

201 Created
{
  "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 for guidance.

​
4. Next steps

Retrieve the label document

Download the airway bill PDF 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.