> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.returnhelper.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create return shipment

Creates a return shipment with an attached label request — the entry point for almost every Return Helper integration. The shipment groups one or more parcels with their items, contact details, and dimensions. Label generation is queued asynchronously; the immediate response gives you the shipment ID and a `labelRequestStatusCode` (typically `queued`), with the actual label URL delivered later via webhook.

## Prerequisites

Have these values ready before calling:

1. **A `serviceTypeCode`** — fetch available return services from one of these endpoints.
   * [Get all return service types](/api-reference/servicetype/get-all-return-service-types)
   * [Get service types by origin country and warehouse](/api-reference/servicetype/get-service-types-by-origin-country-and-warehouse)
2. **Origin and destination country codes** — fetch via [Get all from countries](/api-reference/country/get-all-from-countries-origin-countries) and [Get all countries](/api-reference/country/get-all-countries). Codes are **ISO3** (`usa`, `gbr`, `chn`).
3. **Parcel dimensions and weight** — required and must all be `> 0`. Validate units via [Get all dimension UOMs](/api-reference/dimensionuom/get-all-dimension-units-of-measurement) and [Get all weight UOMs](/api-reference/weightuom/get-all-weight-units-of-measurement).
4. **An idempotency key** — strongly recommended. Send a fresh UUID in `x-returnhelper-idempotency-key` so retries don't create duplicate shipments. See [Idempotency](/introduction#idempotency).

## Important fields

* **`totalValue` and `totalValueCurrency`** — `totalValue` must exactly equal the sum of `parcel.items[].value`. The currency is ISO 4217 (e.g. `USD`, `GBP`, `EUR`); use [Get all transaction types](/api-reference/transactiontype/get-all-transaction-types) to confirm a code is supported.
* **`parcel.items`** — multi-line-item support depends on your account configuration. Single-line-item-only accounts that submit multiple items get a validation soft-error. Contact support if you want to update your configuration.
* **Dimensions** — `dimension1` is the longest side, `dimension2` the second-longest, `dimension3` the shortest.
* **`sellerReferenceNumber`** — your merchant-supplied identifier, accepted at three independent layers (top-level, `shipment`, and per-item in `parcel.items[]`). Stored verbatim and echoed back in webhook events for reconciliation against your own order system. See [Seller Reference Number](/reference/seller-reference-number) for layer semantics, fallback behaviour when omitted, and the recommended reconciliation workflow.

## Label generation is asynchronous

The immediate response includes `labelRequestStatusCode: queued`. The final label URL and tracking number arrive via the `labelGenerated` webhook event (or `labelFailed` if generation fails); warehouse receipt is signalled by the `markShipmentArrive` event and then a `inventoryCreated` event. Subscribe to [Webhooks](/webhooks) — they are the source of truth for shipment lifecycle, not a polling fallback.

## Related

* [Get shipping fees from origin location](/api-reference/shipment/get-shipping-fees-from-origin-location) — preview the fee before committing.
* [Webhooks](/webhooks) — subscribe to `labelGenerated`, `labelFailed`, and `markShipmentArrive` for the full shipment lifecycle.
* [Seller Reference Number](/reference/seller-reference-number) — how to set `sellerReferenceNumber` and reconcile webhook events back to your own order records.


## OpenAPI

````yaml post /api/ReturnShipment/createReturnShipment
openapi: 3.1.0
info:
  title: Return Helper API
  description: API documentation for Return Helper — covering User and Public endpoints.
  version: 1.0.0
servers:
  - url: https://api.returnshelper.com/uat/user
    description: Sandbox — User API
  - url: https://api.returnshelper.com/uat/public
    description: Sandbox — Public API
  - url: https://api.returnhelpercentre.com/v1/user
    description: Production — User API
  - url: https://api.returnhelpercentre.com/v1/public
    description: Production — Public API
  - url: https://api.returnhelperchina.com/user
    description: Production — User API (China)
security:
  - ApiKey: []
    ApiToken: []
paths:
  /api/ReturnShipment/createReturnShipment:
    post:
      tags:
        - ReturnShipment
      summary: Create return shipment
      operationId: ReturnUserApi_CreateReturnShipment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReturnShipmentRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralCreateReturnShipmentReply'
        '401':
          description: >-
            Authentication failed. Returned when the `x-rr-apikey` or
            `x-rr-apitoken` header is missing or invalid. The body uses the
            standard `ApiResponse` envelope with `meta.error.message` describing
            the auth failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
      security:
        - ApiKey: []
          ApiToken: []
      servers:
        - url: https://api.returnshelper.com/uat/user
          description: Sandbox — User API
components:
  schemas:
    CreateReturnShipmentRequest:
      type: object
      properties:
        serviceTypeCode:
          type: string
          description: Return service type code
          default: fedex_ground
        orderTitle:
          type: string
          description: Order title / return title
          default: Return Label Title
        totalValue:
          type: number
          description: Total declared value of the return
          default: 100
        totalValueCurrency:
          type: string
          description: Currency code for totalValue (e.g. USD)
          default: usd
        sellerReferenceNumber:
          type: string
          description: Seller reference number
        remarks:
          type: string
          description: Additional remarks
        shipment:
          $ref: '#/components/schemas/CreateShipmentPayload'
          description: Shipment details including origin address and parcel info
      required:
        - serviceTypeCode
        - orderTitle
        - totalValue
        - totalValueCurrency
        - shipment
    GeneralCreateReturnShipmentReply:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CreateReturnShipmentReply'
          description: Created return shipment details
    ApiResponse:
      type: object
      description: >-
        Universal response envelope. Successful responses include the business
        payload as additional top-level fields alongside `correlationId` and
        `meta`. Failed responses (auth errors, validation errors) only populate
        `correlationId` and `meta`, with `meta.errorCode` and `meta.error`
        describing the failure.
      properties:
        correlationId:
          type:
            - string
            - 'null'
          description: >-
            Unique correlation ID for tracing the request through Return Helper
            systems.
        meta:
          $ref: '#/components/schemas/ApiResponseMeta'
    CreateShipmentPayload:
      type: object
      properties:
        shipToWarehouseId:
          type: integer
          description: Destination warehouse ID
          default: 2
        boxType:
          type: string
          description: Box type code
          default: cus
        sellerReferenceNumber:
          type: string
          description: Seller reference number for this shipment
        shipFrom:
          $ref: '#/components/schemas/ReturnShipmentShipFromPayload'
          description: Origin address
        parcel:
          $ref: '#/components/schemas/ReturnShipmentParcelPayload'
          description: Parcel dimensions, weight, and item list
        customFieldMap:
          type: object
          additionalProperties:
            type: string
          description: Custom key-value metadata
      required:
        - shipToWarehouseId
        - boxType
        - shipFrom
        - parcel
    CreateReturnShipmentReply:
      type: object
      properties:
        returnRequestId:
          type: integer
          format: int32
        returnRequestNumber:
          type:
            - string
            - 'null'
        shipmentId:
          type: integer
          format: int64
        referenceNumber:
          type:
            - string
            - 'null'
        labelId:
          type: integer
          format: int64
        labelRequestStatusCode:
          type:
            - string
            - 'null'
        cost:
          type: number
          format: decimal
        costCurrencyCode:
          type:
            - string
            - 'null'
    ApiResponseMeta:
      type: object
      description: >-
        Application-level metadata for every API response. Inspect `status` and
        `errorCode` to detect soft-error responses (validation failures arrive
        as HTTP 200 with `meta.status: 400`).
      properties:
        status:
          type: integer
          description: >-
            Application-level status code. For successful operations this
            mirrors the HTTP status (e.g. 200). For validation failures it
            reports the logical status (e.g. 400) even though the wire HTTP
            status is 200.
        data:
          type: object
          additionalProperties:
            type: string
          description: Reserved free-form metadata key/value pairs. Usually empty.
        errorCode:
          type:
            - string
            - 'null'
          description: >-
            Machine-readable error code (e.g. `VALIDATION_FAILED`). Non-null
            only when the operation failed.
        error:
          type: object
          additionalProperties: true
          description: >-
            Field-level or message-level error detail keyed by request property
            name. Empty object on success.
    ReturnShipmentShipFromPayload:
      type: object
      properties:
        country:
          type: string
          description: ISO3 origin country code
          default: usa
        contactName:
          type: string
          description: Sender contact name
          default: Your name
        phone:
          type: string
          description: Sender phone number
          default: '15622708183'
        email:
          type: string
          description: Sender email address
          default: user@example.com
        fax:
          type: string
          description: Sender fax number
        street1:
          type: string
          description: Address line 1
          default: Some address line 1
        street2:
          type: string
          description: Address line 2
          default: Some address line 2
        street3:
          type: string
          description: Address line 3
        state:
          type: string
          description: State / province
          default: tx
        city:
          type: string
          description: City
          default: Houston
        postalCode:
          type: string
          description: Postal code
          default: '77235'
      required:
        - country
        - contactName
        - street1
        - state
        - city
        - postalCode
    ReturnShipmentParcelPayload:
      type: object
      properties:
        weight:
          type: number
          description: Parcel weight
          default: 10.5
        weightUnit:
          type: string
          description: Weight unit (e.g. kg)
          default: g
        length:
          type: number
          description: Length (longest side)
          default: 10
        width:
          type: number
          description: Width (second longest side)
          default: 10
        height:
          type: number
          description: Height (shortest side)
          default: 10
        dimensionUnit:
          type: string
          description: Dimension unit (e.g. cm)
          default: cm
        items:
          type: array
          items:
            $ref: '#/components/schemas/ReturnShipmentItemPayload'
          description: List of items in the parcel
          default:
            - description: Test item
              weight: 10.5
              value: 100
              weightUom: g
              valueCurrencyCode: usd
      required:
        - weight
        - weightUnit
        - length
        - width
        - height
        - dimensionUnit
        - items
    ReturnShipmentItemPayload:
      type: object
      properties:
        description:
          type: string
          description: Item description
          default: Test item
        weight:
          type: number
          description: Item weight
          default: 10.5
        weightUom:
          type: string
          description: Weight unit of measure (e.g. kg, g)
          default: g
        value:
          type: number
          description: Declared value of the item
          default: 100
        valueCurrencyCode:
          type: string
          description: Currency code for the declared value (e.g. USD)
          default: usd
        sellerReferenceNumber:
          type: string
          description: Seller reference number for the item
        customFieldMap:
          type: object
          additionalProperties:
            type: string
          description: Custom key-value metadata
          default:
            sku: '1234567890'
            hsCode: '1234567890'
            countryOfOrigin: usa
      required:
        - description
        - weight
        - weightUom
        - value
        - valueCurrencyCode
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-rr-apikey
      description: Your API key
    ApiToken:
      type: apiKey
      in: header
      name: x-rr-apitoken
      description: Your API token — keep this private

````