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.