> ## 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.

# 列出 Shipments（分页）

<Warning>
  本端点**不**是追踪运货单状态的推荐方式。Return Helper API 中运货单生命周期的真实数据源是 [Webhook 事件流](/zh-Hans/webhooks)——`labelGenerated`、`markShipmentArrive` 等事件会在状态变更时即时推送至您的端点。请围绕 webhook 构建集成；本列表端点仅用于一次性回填与运营对账。
</Warning>

返回您账户上已建立的退件运货单分页列表，可按日期范围、状态、仓库或服务类型筛选。

## 仅在以下情况调用

* **一次性回填**：首次集成时，于订阅 webhook 之前，将既有运货单写入本地数据库。
* **定期对账**：用以侦测遗漏或乱序的 webhook 推送——将本地快取与本端点结果比对，再透过 webhook 重发或客服工单进行补齐。

至于其他用途——保持客户介面的运货单状态最新、监控面单可用性、追踪到达状态——请订阅 webhook。以本端点轮询替代 webhook 订阅不受支持，且在高负载下会产生过期或不一致的状态。

## 必要参数

* **`createFrom` / `createTo`** — 均必填，ISO 8601 时间戳。范围上限为 90 天（`SearchConfig.simpleRecordsMaxDays`），超出会返回软错误。
* **`pageSize`** — 介于 `1` 与 `50` 之间。
* **`offset`** — 非负整数。配合 `pageSize` 用于按位移分页。

## 响应说明

* 总数**不会**返回；当某页返回少于 `pageSize` 条记录时，即表示已到结尾。
* `labelRequestStatusCode` 反映查询时点的最新状态。状态变更历史请改用 webhook 事件；本端点无法提供。
* 响应中的国家代码为 **ISO3**。

## 相关

* [建立退件运货单](/zh-Hans/api-reference/returnshipment/create-return-shipment) — 写入侧端点。
* [取得所有运货单状态](/zh-Hans/api-reference/shipment/get-all-shipment-statuses) — 将 `shipmentStatusCode` 转译为可读标签。
* [Webhooks](/zh-Hans/webhooks) — 运货单生命周期事件的标准管道。请先设置 webhook 再使用本端点。

如需了解错误响应的解读与处理，请参阅 [Error codes](/zh-Hans/reference/error-codes)。


## 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

````