> ## 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 イベントストリーム](/ja/webhooks) であり、`labelGenerated`、`markShipmentArrive` など各種イベントが状態変更のたびにエンドポイントへ配信されます。統合は webhook を中心に構築してください。本リストエンドポイントは一回限りのバックフィルおよびオペレーション照合のためだけに用意されています。
</Warning>

アカウントで作成された返品シップメントのページング付き一覧を返します。日付範囲、ステータス、倉庫、サービスタイプで任意にフィルタできます。

## 呼び出してよいタイミング（それ以外では呼ばないでください）

* **一回限りのバックフィル** — 初回統合時、webhook 購読の前にローカル DB に既存のシップメントを書き込むため。
* **定期的な整合性チェック** — webhook 配信の漏れや順序ずれを検知するため。ローカルキャッシュとこのエンドポイントの結果を差分し、webhook 再送やサポート連携で穴埋めしてください。

それ以外（顧客向けダッシュボードを最新に保つ、ラベル発行を待つ、到着状況を追う）には webhook を購読してください。本エンドポイントを webhook 購読の代替としてポーリングする運用はサポートされず、高負荷時には古いまたは不整合な状態を返します。

## 必須パラメータ

* **`createFrom` / `createTo`** — どちらも必須、ISO 8601 タイムスタンプ。範囲は 90 日が上限（`SearchConfig.simpleRecordsMaxDays`）。それ以上はソフトエラーで拒否されます。
* **`pageSize`** — `1` から `50` の間。
* **`offset`** — 非負整数。`pageSize` と組み合わせてオフセットページングを行います。

## レスポンスの注意

* 総件数は **返されません**。あるページで `pageSize` 未満のレコードが返ってきたら、それが末尾です。
* `labelRequestStatusCode` はクエリ時点の最新状態を表します。状態遷移の履歴が必要な場合は webhook イベントを購読してください——本エンドポイントでは履歴を取得できません。
* レスポンスの国コードは **ISO3** です。

## 関連

* [返品シップメントを作成](/ja/api-reference/returnshipment/create-return-shipment) — 書き込み側エンドポイント。
* [すべてのシップメントステータスを取得](/ja/api-reference/shipment/get-all-shipment-statuses) — `shipmentStatusCode` を可読ラベルへ変換。
* [Webhooks](/ja/webhooks) — シップメントライフサイクル イベントの正規チャネル。本エンドポイントを利用する前に必ず webhook を設定してください。

API のエラーレスポンスの解釈と処理については [Error codes](/ja/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

````