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

Get API access

Get your API key and API token from the Return Helper User Portal (Settings → Signing Key and API Token), or contact [email protected] for help.

Create your first label

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

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 "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": "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.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"
        }
      }
  }'

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.

Courier	Slug	Regions
YunExpress	`yunexpress`	Global 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

Environment	Base URL
Production	`https://api.flexforward.com`
Development	`https://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

API key and token header 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.

Getting Started

Guides

Use-Case Guides

Platform

Flex Forward API

Flex Forward API

Core workflows

Create Labels

Get Label Documents

Track Shipments

Get started in 3 steps

Follow the Quickstart guide

Integration flow

First request example

Production scope

Environments

Environment details

Platform reliability

Authentication

Error Handling

Idempotency and Retries

Versioning

OpenAPI specification

Download OpenAPI Spec

Support

Support and FAQ

​Flex Forward API

​Core workflows

Create Labels

Get Label Documents

Track Shipments

​Get started in 3 steps

Follow the Quickstart guide

​Integration flow

​First request example

​Production scope

​Environments

Environment details

​Platform reliability

Authentication

Error Handling

Idempotency and Retries

Versioning

​OpenAPI specification

Download OpenAPI Spec

​Support

Support and FAQ

Flex Forward API

Core workflows

Get started in 3 steps

Integration flow

First request example

Production scope

Environments

Platform reliability

OpenAPI specification

Support