Skip to main content

​
Changelog

All notable changes to the Flex Forward API and documentation are listed here in reverse chronological order.

​
October 2026

​
API changes

  • EU product identifiers: shipment.parcels[].items[].attributes.productIdentifiers documents the product identifiers for customs declarations. For each item shipped to the EU, Monaco, the French overseas regions, or Northern Ireland (postal code starting BT), provide mpid, nspid, and spid as lists of codes. Each is optional elsewhere. The descriptions specify code restrictions, including that spid must not be blank and may use Y081 only when the product has no barcode.

​
September 2026

​
API changes

  • Endpoint: GET /orders/{orderId} — retrieve one order together with the carrier details supplied at label creation. The response returns the order’s shipment stage (status), commercial exceptionState, courier identifiers, declared parcel measurements, and any courier submission error, plus the order numbers, customs identifiers, service options, and courier options you sent. Pass the label id returned by POST /labels as {orderId}; this endpoint accepts only the UUID, not customerOrderNumber. It complements GET /labels/{id}, which returns only the label document.
  • Idempotency: Reusing an idempotencyKey with a different request body returns 409 IDEMPOTENCY_CONFLICT. Requests with the same key and body replay the stored result. Older records without a stored request fingerprint retain their previous replay behavior.
  • Label formats: label.format accepts PDF and PNG, defaulting to PDF when omitted. Document responses report the selected format as lowercase pdf or png.
  • Customer order numbers: Supplied values must contain 1–40 ASCII letters, digits, -, or _ and are case-sensitive and unique per account. Omitted values are system-generated. FlexForward passes {clientCode}-{customerOrderNumber} to the carrier for use as its customer reference and printing where supported.
  • Item values: unitPrice.amount must be at least 0.01. Free gifts, samples, and promotional inserts must be declared at a nominal value of 0.01 or higher, never 0. unitPrice.currency accepts only USD. Omitted currency values also mean USD.
  • IOSS handling: customs.taxIds.ioss now documents that supplied non-blank values are trimmed and used. If the field is omitted or blank and the destination is an EU tax country, FlexForward’s default IOSS code is applied. A code registered under IOSS registrations is not applied automatically unless you send it in the request. Applying FlexForward’s default code is chargeable because a VAT pre-payment and service charge are posted alongside the shipping charge; supplying your own code here is not charged.

​
Documentation corrections

  • Added the order resource and GET /orders/{orderId} to the core concepts resource table and integration flow.
  • Updated the international shipment guide to reflect the unitPrice.amount minimum of 0.01 and to clarify that zero-value customs declarations are not accepted.
  • Clarified IOSS resolution and billing: a supplied customs.taxIds.ioss value is preserved, FlexForward’s default IOSS code applies automatically for EU tax destinations when the field is omitted or blank, and that default-code path is chargeable while supplying your own code is not.

​
Documentation maintenance

  • Added checks to keep generated API documentation aligned with its source and to review related guide updates.

​
July 2026

​
Changed

  • Documentation / OpenAPI: Corrected public authentication guidance. Customer integrations must send both x-rr-apikey and x-rr-apitoken. Bearer-token examples and the public OpenAPI bearerAuth scheme were removed as the documented customer method.
  • Authentication: API credentials are now obtained from the Return Helper User Portal under Settings → Signing Key and API Token, replacing the previous process of requesting a token by email.

​
June 2026

​
Added

  • Endpoint: GET /couriers — list courier codes available to your account. Use a returned code value as courier when creating labels or listing courier products.

​
May 2026

​
Added

  • Endpoint: GET /products — list available shipping products for a courier. Use the returned product codes when creating labels.
  • Authentication: API key + token header authentication (x-rr-apikey / x-rr-apitoken) documented for Flex Forward requests.
  • Endpoint: GET /labels/{id} — now accepts comma-separated identifiers (label UUIDs or customer order numbers) for batch retrieval. Missing or failed labels are omitted from the response.
  • Response: GET /labels/{id} response now includes customerOrderNumber field.

​
Changed

  • service.shipperAccountId is now optional. When omitted, the label is created with your account’s default shipping account for the requested courier. Requests that still send it continue to work.
  • API spec: Enriched with detailed descriptions, examples, and operation IDs across all endpoints.
  • Documentation: Improved quickstart guide, request samples, and general fixes.

​
v1.0.0

Initial public release of the Flex Forward API and developer documentation.

​
Added

  • Endpoints: POST /labels (create shipping label), GET /labels/{id} (retrieve label document URL), GET /tracking/{id} (retrieve shipment tracking)
  • Production courier: YunExpress with global cross-border e-commerce shipping lanes
  • Idempotency: Built-in duplicate prevention for label creation via idempotencyKey
  • Unified tracking: Normalized status tags (Pending, InfoReceived, InTransit, Delivered, Exception, Cancelled, Unknown) and structured checkpoint format across all couriers
  • Authentication: API key + token header authentication (x-rr-apikey / x-rr-apitoken) with separate credentials for production and development environments
  • Documentation: Quickstart guide, authentication reference, error handling guide, idempotency and retry patterns, environment details, core concepts, versioning policy, and FAQ