List shipments with pagination
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.
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— between1and50inclusive.offset— non-negative integer. Combine withpageSizefor offset-based pagination.
Response notes
- The total count is not returned; you discover the end of the list when a page returns fewer than
pageSizerecords. labelRequestStatusCodereflects 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.
Related
- Create return shipment — the write counterpart.
- Get all shipment statuses — translate
shipmentStatusCodecodes into human-readable labels. - Webhooks — the canonical channel for shipment lifecycle events. Always set up webhooks before relying on this endpoint.
Authorizations
Your API key
Your API token — keep this private
Query Parameters
Number of records per page (max 50)
1 <= x <= 50Pagination offset
Filter by creation date from (ISO 8601)
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.
Return request identifier
Return request number
Your merchant-supplied reference, echoed back for reconciliation
Current return status code
Return title
Declared total value of the return
ISO 4217 currency code of totalValue (e.g. USD)
Warehouse-assigned RMA reference (uppercased). Populated once the warehouse processes the parcel.
Free-text remarks
Whether the return request is archived
Origin/source of the return request
Shipments belonging to this return request, each with its label.
Line items included in the return request.
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.
Custom fields attached to the return shipment.