Skip to main content
POST
/
labels
Create a shipping label
curl --request POST \
  --url https://api.flexforward.com/labels \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "unique-key-per-request",
  "courier": "yunexpress",
  "service": {
    "productCode": "JPTHZXR"
  },
  "label": {
    "format": "PDF"
  },
  "units": {
    "weight": "KG",
    "dimension": "CM"
  },
  "order": {
    "customerOrderNumber": "N2026-03-27-TEST-04",
    "orderNumbers": {
      "platformOrderNumber": "your-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": "New jersey",
        "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.01,
        "dimension": {
          "length": 1,
          "width": 1,
          "height": 1
        },
        "items": [
          {
            "descriptionEn": "Muji Ink pen",
            "descriptionLocal": "文具",
            "quantity": 1,
            "unitPrice": {
              "amount": 1,
              "currency": "USD"
            },
            "unitWeight": 0.01
          }
        ]
      }
    ]
  },
  "serviceOptions": [
    {
      "code": "V1",
      "value": "云途预缴"
    }
  ],
  "courierOptions": {
    "yunexpress": {
      "sourceCode": "YT",
      "sensitiveType": "D"
    }
  }
}
'
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": "YT2503010001CN",
  "error": {
    "code": "COURIER_ERROR",
    "message": "YunExpress API returned HTTP 400: Bad request"
  }
}

Authorizations

​
Authorization
string
header
required

API access token issued by the Flex Forward team during onboarding.

Body

application/json
​
idempotencyKey
string
required

Unique key to ensure idempotent label creation. Duplicate requests with the same key return the original result.

Example:

"ord-20250301-abc123"

​
courier
string
required

Courier service identifier.

Example:

"yunexpress"

​
service
object
required
​
shipment
object
required
​
label
object
​
units
object
​
order
object
​
customs
object
​
serviceOptions
object[]
​
dangerousGoods
object
​
pickup
object
​
courierOptions
object

Response

Idempotent replay — the label was already created for this idempotencyKey.

​
id
string<uuid>
required

Unique label identifier.

Example:

"f47ac10b-58cc-4372-a567-0e02b2c3d479"

​
status
string
required

Label creation status — created or failed.

Example:

"created"

​
courier
string
required

Courier service used.

Example:

"yunexpress"

​
courierOrderNumber
string | null
required

Order number assigned by the courier, or null on failure.

Example:

"YT2503010001"

​
courierTrackingNumber
string | null
required

Tracking number assigned by the courier, or null if not yet available.

Example:

"YT2503010001CN"

​
error
object
required

Error details if the label creation failed, otherwise null.