Skip to main content
GET
/
api
/
Shipment
/
list
List shipments with pagination
curl --request GET \
  --url https://api.returnshelper.com/uat/user/api/Shipment/list \
  --header 'x-rr-apikey: <api-key>' \
  --header 'x-rr-apitoken: <api-key>'
{
  "returnRequestId": 123
}
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 stream — labelGenerated, 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

​
returnRequestId
integer<int32>

Return request identifier