如何获取 refund details 及已退回商品的 ITEM_ID？

2026-10-24支付阿杰

结论

只查询 refunds 或 payments endpoint，无法确定退款对应的 ITEM_ID。这些记录描述的是资金退回，包含退款金额、退款原因和关联的 payment_id，但没有记录具体退回了哪些商品。

退款也不等于退货。商家可以发起任意金额的部分退款，因此不能根据 refunded_money.amount 可靠地反推出商品明细。

原因

示例中的退款对象是支付层数据：

{
  "type": "PARTIAL",
  "reason": "Returned Goods",
  "refunded_money": {
    "amount": -1100,
    "currency_code": "USD"
  },
  "payment_id": "XXXXXXXXX"
}

各字段的含义如下：

payment_id 只能用于定位原支付；
reason 是退款原因，不是结构化的退货明细；
refunded_money 只表示退款金额；
type: "PARTIAL" 只表示这是部分退款；
退款对象中没有商品行、数量或 ITEM_ID。

通过 payment_id 查询原始订单，只能确认当时购买了哪些商品，不能证明这次退款具体对应哪一件。比如，订单中可能有多个价格相同的商品，退款金额也可能包含折扣、税费或手工调整。仅凭金额无法准确匹配商品。

推荐处理方式

ERP 集成应将“资金退款”和“商品退回”作为两个独立事件处理：

使用 payment_id 查找原支付及对应的内部订单。
读取原订单的商品行，获取可能涉及的商品 ID、SKU 和购买数量。
发起退款时，由操作人员或业务系统明确选择退回的商品和数量。
将退货明细与退款 ID、payment_id、内部订单 ID 一并保存。
ERP 根据已保存的退货明细调整库存，不要通过退款金额推算库存变化。

可以保存类似下面的数据：

{
  "payment_id": "XXXXXXXXX",
  "refund_id": "REFUND_ID",
  "erp_order_id": "ERP-10001",
  "returned_items": [
    {
      "item_id": "ITEM_ID_123",
      "variation_id": "VARIATION_ID_456",
      "sku": "SKU-001",
      "quantity": 1
    }
  ]
}

如果退款来自外部终端、管理后台或其他渠道，而这些渠道没有采集结构化的退货明细，集成程序最多只能识别出“发生了一笔退款”，无法可靠判断实际退回了哪些商品。此时需要增加人工核对流程，或者在退款操作流程中同步记录退货商品。

处理示例

下面的伪代码展示了相应的处理逻辑：

async function handleRefund(refund) {
  const payment = await getPayment(refund.payment_id);
  const order = await findInternalOrder(payment);

  const returnRecord = await findReturnRecord({
    refundId: refund.id,
    paymentId: refund.payment_id
  });

  if (!returnRecord || returnRecord.returned_items.length === 0) {
    await markForManualReview({
      refundId: refund.id,
      paymentId: refund.payment_id,
      reason: "Refund contains no item-level return details"
    });
    return;
  }

  for (const item of returnRecord.returned_items) {
    await adjustErpInventory({
      orderId: order.erp_order_id,
      itemId: item.item_id,
      sku: item.sku,
      quantity: item.quantity,
      operation: "RESTOCK"
    });
  }
}

注意事项

不要根据退款金额自动匹配商品。折扣、税费、运费、小费以及多件同价商品都可能导致误判。
“已退款”不代表商品已经实际入库。是否补回库存应取决于退货验收状态。
同一笔支付可能发生多次部分退款。应使用退款 ID 做幂等处理，避免重复增加库存。
如果所用平台版本支持订单级退货或 return line items，应优先读取这类结构化退货记录，但不要假定支付退款接口会自动包含这些字段。
对于没有保存商品级退货信息的历史退款，通常无法仅凭现有的 refunds 数据补全准确的 ITEM_ID。