Skip to main content
GET
List shipments with pagination
This is not the recommended way to track shipment state. The Return Helper API’s source of truth for shipment lifecycle is the webhook event streamlabelGenerated, markShipmentArrive, and related events deliver every state change to your endpoint as it happens. Build your integration around webhooks; this list endpoint exists for one-time backfill and operational reconciliation only.
Returns a paginated list of return shipments created on your account, optionally filtered by date range, status, warehouse, or service type.

When (and only when) to call

  • One-time backfill when first integrating, to populate a local database with existing shipments before subscribing to webhooks.
  • Periodic reconciliation to detect dropped or out-of-order webhook deliveries — diff your local cache against this endpoint’s results, then catch up via webhook replay or a support ticket.
For all other uses — keeping a customer-facing dashboard up to date, watching for label availability, tracking arrivals — subscribe to webhooks. Polling this endpoint as a substitute for webhook subscription is unsupported and will produce stale or inconsistent state under load.

Required parameters

  • createFrom / createTo — both required, ISO 8601 timestamps. The window is capped at 90 days (SearchConfig.simpleRecordsMaxDays); wider ranges are rejected with a soft-error.
  • pageSize — between 1 and 50 inclusive.
  • offset — non-negative integer. Combine with pageSize for offset-based pagination.

Response notes

  • The total count is not returned; you discover the end of the list when a page returns fewer than pageSize records.
  • labelRequestStatusCode reflects the latest known state at query time. For state transitions, listen to webhook events — this endpoint cannot give you the history.
  • Country codes in the payload are ISO3.
See Error codes for how to interpret and handle the API’s error responses.

Authorizations

x-rr-apikey
string
header
required

Your API key

x-rr-apitoken
string
header
required

Your API token — keep this private

Query Parameters

pageSize
integer
required

Number of records per page (max 50)

Required range: 1 <= x <= 50
offset
integer
required

Pagination offset

createFrom
string<date-time>
required

Filter by creation date from (ISO 8601)

createTo
string<date-time>
required

Filter by creation date to (ISO 8601)

Response

Success

Full record of a return shipment. Successful responses also carry the standard envelope fields (correlationId, meta) alongside the fields below.

returnRequestId
integer<int32>

Return request identifier

returnRequestNumber
string

Return request number

sellerReferenceNumber
string

Your merchant-supplied reference, echoed back for reconciliation

returnStatusCode
string

Current return status code

returnTitle
string

Return title

totalValue
number

Declared total value of the return

totalValueCurrency
string

ISO 4217 currency code of totalValue (e.g. USD)

rma
string

Warehouse-assigned RMA reference (uppercased). Populated once the warehouse processes the parcel.

remarks
string

Free-text remarks

isArchived
boolean

Whether the return request is archived

returnRequestFrom
string

Origin/source of the return request

shipments
object[]

Shipments belonging to this return request, each with its label.

returnRequestLineItems
object[]

Line items included in the return request.

returnInventoryList
object[]

Return inventory records derived from this request, populated once the warehouse has received the parcel. Empty before receipt — use Get return inventory details for full inventory data at that stage.

returnShipmentCustomFieldList
object[]

Custom fields attached to the return shipment.