Skip to main content
GET
List shipments with pagination
本端點是追蹤運貨單狀態的建議方式。Return Helper API 中運貨單生命週期的真實資料來源是 Webhook 事件流——labelGeneratedmarkShipmentArrive 等事件會在狀態變更時即時推送至您的端點。請圍繞 webhook 設計整合;本列表端點僅用於一次性回填與營運對帳。
回傳您帳戶上已建立的退件運貨單分頁列表,可依日期範圍、狀態、倉庫或服務類型篩選。

僅在以下情況呼叫

  • 一次性回填:首次整合時,於訂閱 webhook 之前,將既有運貨單寫入本地資料庫。
  • 定期對帳:用以偵測遺漏或亂序的 webhook 傳遞——將本地快取與本端點結果比對,再透過 webhook 重發或客服單進行補齊。
至於其他用途——保持客戶介面的運貨單狀態最新、監控面單可用性、追蹤到達狀態——請訂閱 webhook。以本端點輪詢替代 webhook 訂閱不受支援,且在高負載下會產生過期或不一致的狀態。

必要參數

  • createFrom / createTo — 均必填,ISO 8601 時間戳。範圍上限為 90 天(SearchConfig.simpleRecordsMaxDays),超出會傳回軟錯誤。
  • pageSize — 介於 150 之間。
  • offset — 非負整數。搭配 pageSize 用於位移分頁。

回應備註

  • 總數不會回傳;當某頁回傳少於 pageSize 筆記錄時,即表示已到尾。
  • labelRequestStatusCode 反映查詢當下的最新狀態。狀態變更歷史請改用 webhook 事件;本端點無法提供。
  • 回應中的國家代碼為 ISO3

相關

如需了解錯誤回應的解讀與處理方式,請參閱 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.