> ## Documentation Index > Fetch the complete documentation index at: https://openapidocs.flexforwardship.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a shipping label > Creates a shipping label for the specified courier and shipment details. Supports idempotent creation — replaying a request with the same idempotencyKey returns the original result with HTTP 200 instead of creating a duplicate. ## OpenAPI ````yaml /flex-forward.yaml post /labels openapi: 3.1.0 info: title: Flex Forward Shipping API description: >- Flex Forward provides a unified API for creating shipping labels, retrieving label documents, and tracking shipments across multiple courier services. version: 1.0.0 servers: - url: https://api.flexforwardship.com description: Production - url: https://api-staging.flexforwardship.com description: Staging security: [] tags: - name: CreateLabels description: Create shipping labels. - name: Labels description: Retrieve shipping labels and label documents. - name: Tracking description: Track shipment status and checkpoints. - name: Products description: List available shipping products. paths: /labels: post: tags: - CreateLabels summary: Create a shipping label description: >- Creates a shipping label for the specified courier and shipment details. Supports idempotent creation — replaying a request with the same idempotencyKey returns the original result with HTTP 200 instead of creating a duplicate. operationId: createLabel requestBody: required: true content: application/json: schema: additionalProperties: false description: Request payload for creating a shipping label. type: object required: - idempotencyKey - courier - service - shipment properties: idempotencyKey: minLength: 1 maxLength: 100 description: >- Client-generated unique key to ensure idempotent label creation. Replaying a request with the same key returns the original result. type: string example: unique-key-per-request courier: minLength: 1 description: >- Courier code to use. Call GET /couriers to list valid courier codes available to your account, then pass one of the returned code values. type: string example: yunexpress service: additionalProperties: false description: Courier service configuration. type: object required: - productCode properties: shipperAccountId: minLength: 1 description: Shipping account identifier. type: string example: optional-shipper-account-id serviceCode: description: Service level code. type: string productCode: minLength: 1 description: Courier product code. type: string example: HKMUZXR label: additionalProperties: false description: Label output preferences. type: object properties: format: description: Label document format (PDF or png). type: string example: PDF units: additionalProperties: false description: Measurement units for weight and dimensions. type: object properties: weight: description: Weight unit (default KG). type: string example: KG dimension: description: Dimension unit (default CM). type: string example: CM order: additionalProperties: false description: Order reference information. type: object properties: customerOrderNumber: minLength: 1 description: Your order number for cross-referencing. type: string example: N-2026-05-27-TEST-03 orderNumbers: additionalProperties: false description: Additional order identifiers. type: object properties: platformOrderNumber: description: Marketplace platform order number. type: string trackingNumber: description: Pre-assigned tracking number. type: string referenceNumbers: description: Additional reference numbers. type: array items: type: string shipment: additionalProperties: false description: Shipment details including origin, destination, and parcels. type: object required: - shipTo - parcels properties: shipTo: $ref: '#/components/schemas/ShipEndpoint' shipFrom: $ref: '#/components/schemas/ShipEndpoint' parcels: minItems: 1 description: Parcels to ship. type: array items: $ref: '#/components/schemas/Parcel' customs: additionalProperties: false description: Customs declaration information for cross-border shipments. type: object properties: taxIds: additionalProperties: false description: Tax identifiers for customs clearance. type: object properties: taxNumber: description: Tax identification number. type: string ioss: description: EU Import One-Stop Shop (IOSS) number. type: string vat: description: VAT registration number. type: string eori: description: >- Economic Operators Registration and Identification (EORI) number. type: string serviceOptions: description: Additional service options as code-value pairs. type: array items: additionalProperties: false type: object required: - code properties: code: minLength: 1 description: Option code. type: string example: V1 value: description: Option value. type: string dangerousGoods: additionalProperties: false description: Dangerous goods declaration. type: object properties: code: description: Dangerous goods classification code. type: string pickup: additionalProperties: false description: Pickup point configuration. type: object properties: pickupPointCode: description: Pickup point identifier. type: string courierOptions: additionalProperties: false description: Courier-specific options. type: object properties: yunexpress: additionalProperties: false description: YunExpress-specific options. type: object properties: sourceCode: description: Source code for YunExpress. type: string platformAccountCode: description: Platform account code. type: string sensitiveType: description: Sensitive goods type classification. type: string signatureService: description: Signature service flag (Y/N). type: string houseNumber: description: Recipient house number. type: string packageCount: minimum: 1 description: Number of packages in the order. type: integer senderUsci: description: Sender Unified Social Credit Identifier. type: string platformName: description: Sales platform name. type: string platformState: description: Sales platform state or province. type: string platformAddress: description: Sales platform address. type: string platformPostalCode: description: Sales platform postal code. type: string platformPhone: description: Sales platform phone. type: string platformEmail: description: Sales platform email. type: string platformSalesUrl: description: Sales platform listing URL. type: string cargoType: description: Cargo type code (W/F/O, required for Japan). type: string paymentPlatform: description: Payment platform. type: string paymentPlatformAccount: description: Payment platform account. type: string paymentTransactionNumber: description: Payment transaction number. type: string labelUrl: description: Pre-generated label URL. type: string examples: createLabel: summary: YunExpress cross-border label value: 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: alex.smith@example.com address: streetLines: - 18 Distribution Blvd city: Edison state: New jersey postalCode: 8817 countryCode: US shipFrom: contact: firstName: John lastName: Doe phone: 886900676877 email: john.doe@example.com 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 description: Request payload for creating a shipping label. responses: '200': description: Result of a label creation request. content: application/json: schema: $ref: '#/components/schemas/LabelResponse' '201': description: Result of a label creation request. content: application/json: schema: $ref: '#/components/schemas/LabelResponse' '400': description: Default Response content: application/json: schema: anyOf: - $ref: '#/components/schemas/ValidationErrorResponse' - $ref: '#/components/schemas/ErrorResponse' '401': description: Default Response content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Default Response content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Default Response content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Default Response content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '502': description: Result of a label creation request. content: application/json: schema: $ref: '#/components/schemas/LabelResponse' security: - bearerAuth: [] - apiKey: [] apiToken: [] components: schemas: ShipEndpoint: additionalProperties: false description: A shipment party with contact and address. type: object required: - contact - address properties: contact: $ref: '#/components/schemas/Contact' address: $ref: '#/components/schemas/Address' Parcel: additionalProperties: false description: A parcel containing one or more items. type: object required: - weight - items properties: parcelId: description: Optional client-assigned parcel identifier. type: string weight: minimum: 0 description: Parcel weight in the unit specified by units.weight (default kg). type: number example: 0.5 dimension: additionalProperties: false description: Parcel dimensions. type: object required: - length - width - height properties: length: minimum: 0 description: Length. type: number example: 30 width: minimum: 0 description: Width. type: number example: 20 height: minimum: 0 description: Height. type: number example: 10 items: minItems: 1 description: Items in this parcel. type: array items: $ref: '#/components/schemas/ParcelItem' LabelResponse: additionalProperties: false description: Result of a label creation request. type: object required: - id - status - courier - customerOrderNumber - courierOrderNumber - courierTrackingNumber - error properties: id: format: uuid description: Unique label identifier. type: string example: f47ac10b-58cc-4372-a567-0e02b2c3d479 status: description: Label creation outcome — created or failed. anyOf: - type: string enum: - created - type: string enum: - failed example: created courier: description: Courier service used. type: string example: yunexpress customerOrderNumber: description: Customer order number associated with this label. type: string example: N-2026-05-27-TEST-03 courierOrderNumber: description: Order number assigned by the courier, or null on failure. anyOf: - type: string - type: 'null' example: YT2503010001 courierTrackingNumber: description: >- Tracking number assigned by the courier, or null if not yet available. anyOf: - type: string - type: 'null' example: YT2503010001CN error: description: Error details if the label creation failed, otherwise null. anyOf: - additionalProperties: false type: object required: - code - message properties: code: description: Machine-readable error code. examples: - COURIER_ERROR type: string message: description: Human-readable error description. examples: - 'YunExpress API returned HTTP 400: Bad request' type: string - type: 'null' ValidationErrorResponse: additionalProperties: false description: Returned when request body fails schema validation. type: object required: - error - details properties: error: description: Summary error message. type: string enum: - Validation failed details: description: List of field-level validation errors. type: array items: additionalProperties: false type: object required: - field - message properties: field: description: Dot-delimited path to the invalid field. type: string example: service.productCode message: description: Human-readable validation message. type: string example: service.productCode is required ErrorResponse: additionalProperties: false type: object required: - error properties: error: description: Human-readable error message. type: string example: Shipping account not found code: description: Machine-readable error code. type: string example: COURIER_ERROR Contact: additionalProperties: false description: Contact information for a shipment party. type: object required: - firstName properties: firstName: minLength: 1 description: First name. type: string example: John lastName: description: Last name. type: string example: Doe company: description: Company or organization name. type: string phone: description: Phone number with country code. type: string example: +1-908-555-1234 email: format: email description: Email address. type: string example: john@example.com identification: additionalProperties: false description: Government-issued identification. type: object properties: type: description: ID type (e.g. passport, national_id). type: string example: passport number: description: ID number. type: string example: AB1234567 Address: additionalProperties: false description: Physical address for a shipment endpoint. type: object required: - countryCode - city - postalCode - streetLines properties: countryCode: minLength: 2 maxLength: 2 description: ISO 3166-1 alpha-2 country code. type: string example: US state: description: State or province. type: string example: NJ city: minLength: 1 description: City name. type: string example: EDISON postalCode: minLength: 1 description: Postal or ZIP code. type: string example: '08817' streetLines: minItems: 1 description: Street address lines. type: array items: minLength: 1 type: string example: - 18 Distribution Blvd shortAddress: description: Compact address for label printing. type: string ParcelItem: additionalProperties: false description: A single item within a parcel. type: object required: - descriptionEn - quantity - unitPrice - unitWeight properties: sku: maxLength: 50 description: Stock-keeping unit identifier. type: string example: SKU-001 descriptionEn: minLength: 1 description: Item description in English (required for customs). type: string example: Wireless earbuds descriptionLocal: description: Item description in the destination country language. type: string quantity: minimum: 1 description: Number of units. type: integer example: 1 unitPrice: additionalProperties: false description: Price per unit. type: object required: - amount properties: amount: minimum: 0 description: Price amount. type: number example: 29.99 currency: minLength: 3 maxLength: 3 description: ISO 4217 currency code. type: string example: USD unitWeight: minimum: 0 description: Weight per unit in the unit specified by units.weight (default kg). type: number example: 0.5 hsCode: maxLength: 50 description: Harmonized System tariff code. type: string example: '851830' salesUrl: format: uri description: URL to the product listing. type: string attributes: $ref: '#/components/schemas/ParcelItemAttributes' ParcelItemAttributes: additionalProperties: false description: Extended item attributes for customs and logistics. type: object properties: material: description: Material composition. type: string purpose: description: Intended use of the item. type: string brand: description: Brand name. type: string spec: description: Product specification. type: string model: description: Model number or name. type: string remark: description: Additional remarks. type: string manufacturer: $ref: '#/components/schemas/ParcelItemManufacturer' fabricCreationMethod: description: Fabric creation method (e.g. woven, knitted). type: string sellingPrice: minimum: 0 description: Retail selling price. type: number originCountry: minLength: 2 maxLength: 2 description: ISO 3166-1 alpha-2 country code of the item origin. type: string example: CN ParcelItemManufacturer: additionalProperties: false description: Manufacturer details for customs declaration. type: object properties: manufacturerId: description: Manufacturer identifier. type: string manufacturerName: description: Manufacturer name. type: string example: Acme Corp manufacturerAddress: description: Street address. type: string manufacturerCity: description: City. type: string manufacturerProvince: description: Province or state. type: string manufacturerCountry: description: Country name or code. type: string manufacturerPostalcode: description: Postal code. type: string securitySchemes: bearerAuth: type: http scheme: bearer apiKey: type: apiKey in: header name: x-rr-apikey apiToken: type: apiKey in: header name: x-rr-apitoken ````