> ## 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. # 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 stream](/webhooks) — `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**. ## Related * [Create return shipment](/api-reference/returnshipment/create-return-shipment) — the write counterpart. * [Get all shipment statuses](/api-reference/shipment/get-all-shipment-statuses) — translate `shipmentStatusCode` codes into human-readable labels. * [Webhooks](/webhooks) — the canonical channel for shipment lifecycle events. Always set up webhooks before relying on this endpoint. See [Error codes](/reference/error-codes) for how to interpret and handle the API's error responses. ## OpenAPI ````yaml get /api/Shipment/list 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/Shipment/list: get: tags: - Shipment summary: List shipments with pagination operationId: ReturnUserApi_ListShipment parameters: - name: pageSize in: query required: true schema: type: integer maximum: 50 minimum: 1 description: Number of records per page (max 50) - name: offset in: query required: true schema: type: integer description: Pagination offset - name: createFrom in: query required: true schema: type: string format: date-time description: Filter by creation date from (ISO 8601) - name: createTo in: query required: true schema: type: string format: date-time description: Filter by creation date to (ISO 8601) responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/UserReturnRequestResponse' '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: UserReturnRequestResponse: type: object description: >- Full record of a return shipment. Successful responses also carry the standard envelope fields (`correlationId`, `meta`) alongside the fields below. properties: returnRequestId: type: integer format: int32 description: Return request identifier returnRequestNumber: type: string description: Return request number sellerReferenceNumber: type: string description: Your merchant-supplied reference, echoed back for reconciliation returnStatusCode: type: string description: Current return status code returnTitle: type: string description: Return title totalValue: type: number description: Declared total value of the return totalValueCurrency: type: string description: ISO 4217 currency code of totalValue (e.g. USD) rma: type: string description: >- Warehouse-assigned RMA reference (uppercased). Populated once the warehouse processes the parcel. remarks: type: string description: Free-text remarks isArchived: type: boolean description: Whether the return request is archived returnRequestFrom: type: string description: Origin/source of the return request shipments: type: array description: Shipments belonging to this return request, each with its label. items: type: object properties: shipmentId: type: integer format: int64 description: Shipment identifier returnRequestId: type: integer format: int32 description: Parent return request identifier shipmentNumber: type: string description: Shipment number shipmentStatusCode: type: string description: Shipment status code shipmentServiceType: type: string description: Service type used for the shipment label: type: object description: Label associated with the shipment. properties: labelId: type: integer format: int64 description: Label identifier labelRequestStatusCode: type: string description: Label generation status (e.g. queued, generated, failed) trackingNumber: type: string description: Carrier tracking number labelUrl: type: string description: >- URL of the generated shipping label. Empty until label generation completes; normally delivered via the labelGenerated webhook. Read this field to recover a label that was missed in webhook delivery. qrcodeUrl: type: string description: URL of the label QR code, when applicable carrier: type: string description: Carrier name returnRequestLineItems: type: array description: Line items included in the return request. items: type: object returnInventoryList: type: array description: >- 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. items: type: object returnShipmentCustomFieldList: type: array description: Custom fields attached to the return shipment. items: type: object 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' 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. 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 ````