> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.bentoweb.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# ดูข้อมูลคืนสินค้า/คืนเงินของออเดอร์ผ่าน API

# ดูข้อมูลคืนสินค้า/คืนเงินของออเดอร์ผ่าน API (order-full)

ใช้เมื่อระบบของร้าน (ERP, ระบบบัญชี, คลังสินค้า) ต้องรู้ว่าออเดอร์มีคำขอคืนสินค้า/คืนเงินหรือไม่ สถานะถึงไหน และคืนเงินไปแล้วเท่าไร ข้อมูลเป็นรูปแบบเดียวกันทุกช่องทาง ทั้ง Shopee, Lazada, TikTok Shop และหน้าร้าน BentoWeb

## วิธีเรียก

```
GET https://order.bentoweb.com/api/order/order-full/{order_id}?store_id={store_id}&scope=return_refund
Authorization: Bearer {access_token}
Accept: application/json
```

- ต้องใส่ `scope=return_refund` ถ้าไม่ใส่จะไม่มีข้อมูลส่วนนี้ ใส่ร่วมกับ scope อื่นได้ด้วยเครื่องหมายจุลภาค เช่น `scope=order_history,return_refund`
- ถ้าต้องการหาก่อนว่าออเดอร์ไหนมีคำขอคืน ให้เรียก `GET /order/list/{store_id}?action=6` แล้วนำ `order_id` ที่ได้มาเรียก order-full ทีละใบ

ข้อมูลอยู่ที่ `data.order.return_refund`

## ภาพรวมของออเดอร์

| Field | ความหมาย |
| ---- | ---- |
| `enabled` | `true` = อ่านข้อมูลได้ · `false` = ไม่พบร้าน (`returns` จะว่างเสมอ) |
| `has_return` | `true` = ออเดอร์นี้มีคำขอคืนอย่างน้อย 1 ใบ (นับทุกสถานะ) |
| `summary.count` | จำนวนคำขอคืนทั้งหมดของออเดอร์ |
| `summary.active_count` | จำนวนคำขอที่ยังไม่จบ (ไม่นับที่ถูกปฏิเสธหรือปิดแล้ว) |
| `summary.total_refunded_amount` | ยอดที่คืนเงินไปแล้วจริง รวมเฉพาะคำขอที่ `refund_status = 3` · เป็น `null` ถ้ามีหลายสกุลเงิน ให้รวมจากแต่ละใบเอง |
| `summary.currency` | สกุลเงินของยอดรวม |

## รายละเอียดแต่ละคำขอ (`returns[]`)

ออเดอร์เดียวมีคำขอคืนได้หลายใบ แต่ละใบมีข้อมูลดังนี้

| Field | ความหมาย |
| ---- | ---- |
| `order_refund_id` | เลขคำขอคืนใน BentoWeb |
| `channel` | `marketplace` หรือ `own_channel` (หน้าร้าน BentoWeb) |
| `platform` | `shopee` · `lazada` · `tiktok` · `bentoweb` |
| `marketplace_return_id` | เลขคำขอคืนบน marketplace (คำขอจากหน้าร้านจะเป็น `BW-{order_id}-{ลำดับ}`) |
| `return_type` | ประเภทคำขอตามที่ marketplace ส่งมา เช่น `RETURN` คืนสินค้า · `ONLY_REFUND` / `REFUND` คืนเงินอย่างเดียว · `RETURN_AND_REFUND` คืนสินค้าและคืนเงิน · `REPLACEMENT` / `EXCHANGE` เปลี่ยนสินค้า · `CANCEL` ยกเลิก · Shopee ใช้ `RRBOC` (ขอคืนก่อนออเดอร์สำเร็จ) และ `RRAOC` (ขอคืนหลังออเดอร์สำเร็จ) — ถ้าต้องรู้ว่าต้องรอรับของคืนไหม ให้ดู `needs_logistics` |
| `needs_logistics` | `true` = ผู้ซื้อต้องส่งสินค้ากลับมา · `null` = ไม่ทราบ |
| `return_status` / `return_status_name` | สถานะคำขอคืน (ดูตารางด้านล่าง) |
| `refund_status` / `refund_status_name` | สถานะการคืนเงิน (ดูตารางด้านล่าง) |
| `raw_platform_status` | สถานะดิบจาก marketplace ใช้อ้างอิงเท่านั้น |
| `is_refunded` | `true` = คืนเงินแล้วจริง |
| `requested_at` | เวลาที่ผู้ซื้อยื่นคำขอ |
| `requested_at_source` | `platform` = เวลาจาก marketplace · `system` = เวลาที่ BentoWeb รับคำขอ (ใช้เมื่อ marketplace ไม่ส่งเวลามา) |
| `return_updated_at` / `refund_updated_at` | เวลาที่สถานะคืนสินค้า/คืนเงินเปลี่ยนล่าสุด |

### สถานะคำขอคืน (`return_status`)

| ค่า | ชื่อ | ความหมาย |
| ---- | ---- | ---- |
| 0 | NONE | ไม่มีขั้นตอนคืนสินค้า |
| 1 | PENDING | รอร้านอนุมัติ |
| 2 | APPROVED | ร้านอนุมัติแล้ว |
| 3 | REJECTED | ถูกปฏิเสธ (จบ) |
| 4 | DISPUTED | อยู่ระหว่างโต้แย้ง |
| 5 | GOODS_RECEIVED | ร้านได้รับสินค้าคืนแล้ว |
| 6 | CLOSED | ปิดคำขอแล้ว (จบ) |

### สถานะการคืนเงิน (`refund_status`)

| ค่า | ชื่อ | ความหมาย |
| ---- | ---- | ---- |
| 0 | NONE | ยังไม่มีการคืนเงิน |
| 1 | PENDING | รอคืนเงิน |
| 2 | PROCESSING | กำลังคืนเงิน |
| 3 | REFUNDED | คืนเงินแล้ว |
| 4 | CANCELLED | ยกเลิกการคืนเงิน |
| 5 | EXCHANGED | เปลี่ยนสินค้าให้แทน ไม่มีการคืนเงิน |

## ยอดเงิน (`amount`)

> **ถือว่าเงินออกจริงเฉพาะเมื่อ** **`is_refunded = true`** **เท่านั้น** ถ้าสถานะยังไม่จบ หรือเป็น CANCELLED/EXCHANGED ตัวเลขในส่วนนี้เป็นเพียงยอดที่ขอคืน ห้ามนำไปลงบัญชีเป็นเงินที่คืนแล้ว

| Field | ความหมาย |
| ---- | ---- |
| `refund_amount` | ยอดคืนของคำขอนี้ · คำขอหน้าร้านที่คืนชิ้นสุดท้ายจนครบทั้งใบ (โอนเงิน) รวมค่าส่งและค่าธรรมเนียมชำระเงินของทั้งใบด้วย |
| `currency` | สกุลเงิน |
| `gross_refund_amount` | ยอดคืนก่อนหักค่าต่างๆ (อาจเป็น `null`) |
| `platform_fee_refund` | ค่าธรรมเนียมที่ marketplace คืนให้ร้าน (อาจเป็น `null`) |
| `shipping_fee_refund` | ค่าส่งที่คืนหรือถูกเรียกเก็บ (อาจเป็น null) · หน้าร้าน BentoWeb เป็น null เสมอ ค่าส่งที่คืนรวมอยู่ใน refund_amount |
| `net_seller_amount` | ผลสุทธิที่กระทบร้าน (อาจเป็น `null`) |

## สินค้าในคำขอ (`items[]`)

| Field | ความหมาย |
| ---- | ---- |
| `order_line_item_id` | ใช้จับคู่กับรายการสินค้าในออเดอร์ |
| `product_variant_id` | รหัสสินค้าย่อยใน BentoWeb |
| `sku` | SKU บน marketplace |
| `bentoweb_sku` | SKU ใน BentoWeb ใช้จับคู่กับ `order_item[].sku` (เป็น `null` ถ้าจับคู่ไม่ได้) |
| `product_name` / `quantity` | ชื่อสินค้า / จำนวนที่ขอคืน |
| `refund_amount` | ยอดคืนของสินค้ารายการนี้ (ไม่รวมค่าส่ง/ค่าธรรมเนียม ผลรวม items อาจน้อยกว่า amount.refund_amount) |
| `item_status` | การรับสินค้าคืนเข้าร้าน: `null` ยังไม่ดำเนินการ · `pending` รอรับ · `received` รับแล้ว |
| `reason_code` | เหตุผลแบบมาตรฐาน: `defective` สินค้าชำรุด · `shipping_damage` เสียหายจากขนส่ง · `wrong_item` ส่งผิด · `not_as_described` ไม่ตรงปก · `size_fit` ขนาดไม่พอดี · `quality` คุณภาพ · `change_mind` เปลี่ยนใจ · `late_delivery` ส่งช้า · `missing_item` ได้ไม่ครบ · `other` อื่นๆ |
| `reason` | ข้อความเหตุผลจากผู้ซื้อหรือ marketplace |

## คำขอคืนจากหน้าร้าน BentoWeb

มีเฉพาะคำขอที่ `platform = bentoweb` ถ้าเป็นคำขอจาก marketplace จะเป็น `null`

| Field | ความหมาย |
| ---- | ---- |
| `refund_method` | ช่องทางคืนเงิน: `BANK_TRANSFER` โอนเงิน · `POINTS` คืนเป็นแต้ม |
| `refund_account` | บัญชีที่ลูกค้าให้โอนเงินคืน: `type` (`bank` หรือ `promptpay`), `account_name`, `account_number`, `bank_name` (มีเฉพาะ `bank`) |

## ตัวอย่าง

```json
"return_refund": {
  "enabled": true,
  "has_return": true,
  "summary": { "count": 1, "active_count": 1, "total_refunded_amount": "0.00", "currency": "THB" },
  "returns": [{
    "order_refund_id": 12,
    "channel": "marketplace",
    "platform": "shopee",
    "marketplace_return_id": "RN2508ABC",
    "return_type": "RETURN_AND_REFUND",
    "needs_logistics": true,
    "return_status": 2, "return_status_name": "APPROVED",
    "refund_status": 1, "refund_status_name": "PENDING",
    "raw_platform_status": "ACCEPTED",
    "is_refunded": false,
    "amount": { "refund_amount": "150.00", "currency": "THB", "gross_refund_amount": null,
                "platform_fee_refund": null, "shipping_fee_refund": null, "net_seller_amount": null },
    "refund_method": null,
    "refund_account": null,
    "requested_at": "2026-08-01 10:00:00",
    "requested_at_source": "platform",
    "return_updated_at": "2026-08-02 09:00:00",
    "refund_updated_at": null,
    "items": [{
      "return_refund_item_id": 55, "order_line_item_id": "9001", "product_variant_id": 99,
      "sku": "ABC-01", "bentoweb_sku": "1060000702", "product_name": "T-Shirt M",
      "quantity": 2, "refund_amount": "75.00", "item_status": null,
      "reason_code": "defective", "reason": "สินค้าชำรุด"
    }]
  }]
}
```

ในตัวอย่างนี้ ร้านอนุมัติคำขอแล้ว (`APPROVED`) แต่ยังไม่ได้คืนเงิน (`is_refunded = false`) ยอด 150.00 จึงเป็นยอดที่ขอคืน ยังไม่ใช่เงินที่ออกไปแล้ว

## ข้อควรรู้

- เวลาทุกช่องเป็นรูปแบบ `YYYY-MM-DD HH:mm:ss` เวลาประเทศไทย
- ออเดอร์ที่ไม่มีคำขอคืน จะได้ `has_return: false` และ `returns: []`
- ข้อมูลจาก marketplace อัปเดตตามที่ marketplace แจ้งเข้ามา ถ้าสถานะยังไม่เปลี่ยน ให้เรียกใหม่อีกครั้งภายหลัง
- ในอนาคตอาจมี field เพิ่ม แต่ field เดิมจะไม่ถูกเปลี่ยนชื่อหรือลบ ระบบของร้านควรข้าม field ที่ไม่รู้จัก