Skip to main content
GET
List shipments with pagination
本エンドポイントはシップメント状態の追跡方法として 推奨されません。Return Helper API におけるシップメントライフサイクルの真実のソースは Webhook イベントストリーム であり、labelGeneratedmarkShipmentArrive など各種イベントが状態変更のたびにエンドポイントへ配信されます。統合は webhook を中心に構築してください。本リストエンドポイントは一回限りのバックフィルおよびオペレーション照合のためだけに用意されています。
アカウントで作成された返品シップメントのページング付き一覧を返します。日付範囲、ステータス、倉庫、サービスタイプで任意にフィルタできます。

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

  • 一回限りのバックフィル — 初回統合時、webhook 購読の前にローカル DB に既存のシップメントを書き込むため。
  • 定期的な整合性チェック — webhook 配信の漏れや順序ずれを検知するため。ローカルキャッシュとこのエンドポイントの結果を差分し、webhook 再送やサポート連携で穴埋めしてください。
それ以外(顧客向けダッシュボードを最新に保つ、ラベル発行を待つ、到着状況を追う)には webhook を購読してください。本エンドポイントを webhook 購読の代替としてポーリングする運用はサポートされず、高負荷時には古いまたは不整合な状態を返します。

必須パラメータ

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

レスポンスの注意

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

関連

API のエラーレスポンスの解釈と処理については Error codes を参照してください。

承認

x-rr-apikey
string
header
必須

Your API key

x-rr-apitoken
string
header
必須

Your API token — keep this private

クエリパラメータ

pageSize
integer
必須

Number of records per page (max 50)

必須範囲: 1 <= x <= 50
offset
integer
必須

Pagination offset

createFrom
string<date-time>
必須

Filter by creation date from (ISO 8601)

createTo
string<date-time>
必須

Filter by creation date to (ISO 8601)

レスポンス

Success

Full record of a return shipment. Successful responses also carry the standard envelope fields (correlationId, meta) alongside the fields below.

returnRequestId
integer<int32>

Return request identifier

returnRequestNumber
string

Return request number

sellerReferenceNumber
string

Your merchant-supplied reference, echoed back for reconciliation

returnStatusCode
string

Current return status code

returnTitle
string

Return title

totalValue
number

Declared total value of the return

totalValueCurrency
string

ISO 4217 currency code of totalValue (e.g. USD)

rma
string

Warehouse-assigned RMA reference (uppercased). Populated once the warehouse processes the parcel.

remarks
string

Free-text remarks

isArchived
boolean

Whether the return request is archived

returnRequestFrom
string

Origin/source of the return request

shipments
object[]

Shipments belonging to this return request, each with its label.

returnRequestLineItems
object[]

Line items included in the return request.

returnInventoryList
object[]

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.

returnShipmentCustomFieldList
object[]

Custom fields attached to the return shipment.