> ## 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-Hant/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-Hant/api-reference/returnshipment/create-return-shipment) — 寫入側端點。
* [取得所有運貨單狀態](/zh-Hant/api-reference/shipment/get-all-shipment-statuses) — 將 `shipmentStatusCode` 轉譯為可讀標籤。
* [Webhooks](/zh-Hant/webhooks) — 運貨單生命週期事件的標準通道。請先設定 webhook 再使用本端點。

如需了解錯誤回應的解讀與處理方式，請參閱 [Error codes](/zh-Hant/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

````