Skip to main content
POST
/
api
/
ReturnShipment
/
createReturnShipment
Create return shipment
curl --request POST \
  --url https://api.returnshelper.com/uat/user/api/ReturnShipment/createReturnShipment \
  --header 'Content-Type: application/json' \
  --header 'x-rr-apikey: <api-key>' \
  --header 'x-rr-apitoken: <api-key>' \
  --data '
{
  "serviceTypeCode": "fedex_ground",
  "orderTitle": "Return Label Title",
  "orderNumber": "123123",
  "totalValueCurrency": "usd",
  "shipment": {
    "shipToWarehouseId": 2,
    "boxType": "cus",
    "shipFrom": {
      "country": "usa",
      "contactName": "Your name",
      "street1": "Some address line 1",
      "state": "tx",
      "city": "Houston",
      "postalCode": "77235",
      "phone": "15622708183",
      "email": "user@example.com",
      "fax": "<string>",
      "street2": "Some address line 2",
      "street3": "<string>"
    },
    "parcel": {
      "weight": 10.5,
      "weightUnit": "g",
      "length": 10,
      "width": 10,
      "height": 10,
      "dimensionUnit": "cm",
      "items": [
        {
          "description": "Test item",
          "weight": 10.5,
          "value": 100,
          "weightUom": "g",
          "valueCurrencyCode": "usd"
        }
      ]
    },
    "sellerReferenceNumber": "<string>",
    "customFieldMap": {}
  },
  "totalValue": 100,
  "sellerReferenceNumber": "<string>",
  "remarks": "<string>"
}
'
{
  "data": {
    "returnRequestId": 123,
    "returnRequestNumber": "<string>",
    "shipmentId": 123,
    "referenceNumber": "<string>",
    "labelId": 123,
    "labelRequestStatusCode": "<string>",
    "cost": 123,
    "costCurrencyCode": "<string>"
  }
}
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.
  2. Origin and destination country codes — fetch via Get all from countries and 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 and Get all weight UOMs.
  4. An idempotency key — strongly recommended. Send a fresh UUID in x-returnhelper-idempotency-key so retries don’t create duplicate shipments. See 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 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 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 — they are the source of truth for shipment lifecycle, not a polling fallback.

Authorizations

​
x-rr-apikey
string
header
required

Your API key

​
x-rr-apitoken
string
header
required

Your API token — keep this private

Body

application/json
​
serviceTypeCode
string
default:fedex_ground
required

Return service type code

​
orderTitle
string
default:Return Label Title
required

Order title / return title

​
orderNumber
string
default:123123
required

Order number

​
totalValueCurrency
string
default:usd
required

Currency code for totalValue (e.g. USD)

​
shipment
object
required

Shipment details including origin address and parcel info

​
totalValue
number
default:100

Total declared value of the return

​
sellerReferenceNumber
string

Seller reference number

​
remarks
string

Additional remarks

Response

Success

​
data
object

Created return shipment details