退款与售后

对订单发起退款、查询退款记录，并读取买家发起的售后单（退货与换货）。

适用场景

在客服工具里处理退款，或把退货与外部系统对账。

前置需求

一个已跑通 OAuth 与 token 存储的公开应用——先完成开发应用。下面的每个请求都带 Access-Token: {token} 头，使用你为每个店铺保存的 token。
OAuth 时已授予订单相关的 access scope。

工作原理

退款与售后单是两个相关但创建路径不同的对象：

退款由你主动发起——对订单调用 refund，响应会返回两个 id：refund_record_id 标识这笔退款本身，之后可以在退款记录列表里回查；post_sale_id——Shoplazza 会在退款的同时自动生成一张售后单。
售后单（退货与换货）则是由买家在店面发起的，不经过你的应用。API 只能读取和删除售后单记录——买家发起的这条链路没有创建端点。

所以，通过 API 发起退款是唯一会产生可回查售后单的路径；其他售后单在买家自己创建之前，都不受你的应用控制。

发起退款

refund_total 是唯一必填字段。整单退款时传订单的 total_price。

POST /openapi/2026-01/orders/{id}/refund

请求体：

{
  "refund": {
    "refund_total": "205.51" // 整单退款时传订单的 total_price
  }
}

响应（节选，data.data 直接就是两个 id）：

{
  "code": "Success",
  "data": {
    "refund_record_id": "626516830554446103",
    "post_sale_id": "56008987-fb4d-41b9-aefa-9d38478f486c"
  }
}

部分退款、按行项或按支付渠道的金额见发起退款。

查询退款记录

GET /openapi/2026-01/orders/refund_records

响应（节选，列表在 data.data.records 下）：

{
  "code": "Success",
  "data": {
    "records": [
      {
        "id": "626516830554446103",
        "order_id": "2386979206089232618121",
        "refund_price": "205.51",
        "refund_method": "customize",
        "refund_status": "finished",
        "created_at": "2026-07-01T07:06:35Z",
        "payment_details": [
          {
            "payment_method": "bogus_gateway",
            "refund_price": "205.51",
            "refund_status": "finished"
          }
        ]
      }
    ]
  }
}

见查询退款记录。

读取售后单（只读）

备注

售后单（退货与换货）由买家在店面发起。API 只能读取（GET /orders/post_sales）和删除一条记录（DELETE /orders/post_sales/{id}）——没有创建端点。

GET /openapi/2026-01/orders/post_sales

响应（节选，注意列表在 data.data.orders 下，而不是 post_sales）：

{
  "code": "Success",
  "data": {
    "orders": [
      {
        "id": "56008987-fb4d-41b9-aefa-9d38478f486c",
        "number": "VMT95165-S1",
        "order_number": "VMT95165",
        "order_total": "205.51",
        "refund_amount": "205.51",
        "financial_status": "refunded",
        "fulfillment_status": "shipped",
        "status": "finished",
        "customer_name": "Jane Doe",
        "line_items": [
          {
            "id": "ee73a839-61a2-4504-b4b6-ea55f73f1340",
            "product_title": "Denim dress",
            "quantity": 1,
            "refund_price": "205.51",
            "sku": "A002013"
          }
        ]
      }
    ]
  }
}

见查询售后单与删除售后单。

从支付应用的退款回调发起退款是另一条链路——见处理退款。

下一步

用 Webhook 监听订单事件（orders/refunded）

适用场景​

前置需求​

工作原理​

发起退款​

查询退款记录​

读取售后单（只读）​

下一步​