Skip to main content

​
Flex Forward API

Flex Forward provides a single API for creating shipping labels, retrieving airway bill documents, and tracking shipments. One integration covers multiple courier services with a consistent request format, normalized tracking data, and built-in idempotency.

​
Core workflows

Create Labels

Create shipping labels through supported courier services with idempotent requests.

Get Label Documents

Retrieve airway bill PDFs or PNGs for your created labels.

Track Shipments

Get real-time tracking status in a unified format across all couriers.

​
Get started in 3 steps

1

Get API access

Request your API credentials by contacting the Flex Forward team at [email protected]. You will receive a Bearer token for authentication.
2

Create your first label

Send a POST /labels request with your shipment details. The API returns a label ID and tracking number.
3

Retrieve documents and track

Use the label ID to retrieve the airway bill document (GET /labels/{id}) and track the shipment (GET /tracking/{id}).

Follow the Quickstart guide

Step-by-step walkthrough from authentication to your first label.

​
Integration flow

​
First request example

curl -X POST https://api.flexforward.com/labels \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "ord-20250301-abc123",
    "courier": "yunexpress",
    "service": {
      "shipperAccountId": "your-account-id",
      "productCode": "YEXP01"
    },
    "shipment": {
      "shipFrom": {
        "contact": { "firstName": "Sender", "lastName": "Name", "phone": "+81-90-1234-5678" },
        "address": { "countryCode": "JP", "city": "Tokyo", "postalCode": "100-0001", "streetLines": ["1-1 Marunouchi"] }
      },
      "shipTo": {
        "contact": { "firstName": "Recipient", "lastName": "Name", "phone": "+1-555-0100" },
        "address": { "countryCode": "US", "city": "Los Angeles", "state": "CA", "postalCode": "90001", "streetLines": ["123 Main St"] }
      },
      "parcels": [{
        "weight": 0.5,
        "items": [{
          "descriptionEn": "T-Shirt",
          "descriptionLocal": "Tシャツ",
          "quantity": 2,
          "unitPrice": { "amount": 25.00, "currency": "USD" },
          "unitWeight": 0.25
        }]
      }]
    }
  }'
201 Created
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": "YT2503010001CN",
  "error": null
}

​
Production scope

Flex Forward is currently enabled for production shipments with YunExpress, supporting global cross-border e-commerce shipping lanes.
CourierSlugRegions
YunExpressyunexpressGlobal cross-border e-commerce
Additional carrier enablement is available based on shipping lane requirements and account onboarding. Contact the Flex Forward team to discuss carrier availability for your integration.

​
Environments

EnvironmentBase URL
Productionhttps://api.flexforward.com
Developmenthttps://sandbox.flexforward.com
All API requests must be made over HTTPS. The development environment connects to courier sandbox services for safe testing.

Environment details

Credential separation, environment behavior, and operational notes.

​
Platform reliability

Authentication

Bearer token authentication with best practices for credential management.

Error Handling

HTTP status codes, error response formats, and troubleshooting guidance.

Idempotency and Retries

Prevent duplicate label creation and retry requests safely.

Versioning

How the API handles changes and backward compatibility.

​
OpenAPI specification

Download OpenAPI Spec

Download the OpenAPI 3.1 specification for code generation, client SDKs, and API tooling.

​
Support

For onboarding, integration support, or carrier availability inquiries, contact the Flex Forward team at [email protected].

Support and FAQ

Technical support, onboarding guidance, and frequently asked questions.