Use this api to cancel an order — API Shopee

v2.order.cancel_order

POST/api/v2/order/cancel_orderGọi qua 360: POST https://partner.quantri360.com/v1/shopee/api/v2/order/cancel_order

Endpoint ghi — thay đổi dữ liệu trên Shopee. Key phải được tạo với tick "Cho phép gọi API ghi", nếu không sẽ nhận 403 write_not_allowed. Mỗi lần gọi được ghi nhật ký.

Mô tả API

Người bán hủy toàn bộ hoặc một phần đơn trước khi gửi hàng. Cần kiểm tra điều kiện hủy và số lượng trước khi gửi; thao tác không hoàn tác được.

Gọi qua /v1/shopee/api/v2/order/cancel_order với Authorization: Bearer <key>; dùng platform_shop_id khi có nhiều shop. 360 tự gắn partner_id, shop_id, sign và access_token.
API GHI: thay đổi dữ liệu thật trên Shopee; cần key có quyền ghi (can_write) và gói mở module Đơn hàng. Hủy đơn hoặc số lượng đã chọn, không hoàn tác được.
HTTP 200 vẫn có thể có lỗi nghiệp vụ; kiểm error trước khi dùng kết quả.
Chỉ hủy trước khi gửi hàng; KHÔNG hoàn tác được. Đơn kho Shopee không hủy được.
Đọc can_full_cancel_order / can_partial_cancel_order / buyer_preference_for_partial_cancellation trong get_order_detail và get_package_detail trước khi gọi.
item_list bắt buộc khi cancel_reason=OUT_OF_STOCK; 360 không chặn trước, Shopee báo lỗi nếu thiếu. UNDELIVERABLE_AREA không dùng cho shop VN.
Hủy một phần dùng partial_cancel_item_list và xem trước tiền bằng get_estimate_cancel_value; hủy hết số lượng thì dùng hủy cả đơn.
Hết thời gian chờ hoặc không nhận được phản hồi: đọc order_status bằng get_order_detail trước khi gọi lại.

Request

Địa chỉ

POST https://partner.quantri360.com/v1/shopee/api/v2/order/cancel_order

Xác thực & gian hàng

Tên	Vị trí	Kiểu	Mẫu	Mô tả
Authorization	header	header	Bearer q360_live_ab12cd34_…	Khóa API của brand (tạo ở mục API key). Bắt buộc với mọi request. Brand suy từ key — không truyền mã brand.
platform_shop_id	query	string	100001	Gian hàng (lấy ở GET /v1/platforms → shops[].platform_shop_id). BẮT BUỘC khi brand có > 1 gian hàng trên nền tảng; 360 bỏ tham số này trước khi chuyển tiếp.

Tham số request

Tên	Vị trí	Kiểu	Bắt buộc	Mẫu	Mô tả
order_sn	body	string	Có	2611040DEMO001	Mã đơn Shopee.
cancel_reason	body	string	Có	OUT_OF_STOCK	Lý do hủy: OUT_OF_STOCK (hết hàng), CUSTOMER_REQUEST (người mua yêu cầu), COD_NOT_SUPPORTED (không hỗ trợ COD). UNDELIVERABLE_AREA chỉ dùng tại TW / MY, không dùng cho shop VN.
item_list	body	object[]	Không		Danh sách sản phẩm hết hàng; bắt buộc khi cancel_reason=OUT_OF_STOCK.
partial_cancel_item_list	body	object[]	Không		Các dòng hàng và số lượng cần hủy một phần, tiếp tục giao phần còn lại.

Ví dụ request

curl -s -X POST "https://partner.quantri360.com/v1/shopee/api/v2/order/cancel_order" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_sn":"2611040DEMO001","cancel_reason":"OUT_OF_STOCK","item_list":[{"item_id":100001,"model_id":100002}]}'

Python

import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.post(
    "https://partner.quantri360.com/v1/shopee/api/v2/order/cancel_order",
    params={},
    json={
        "order_sn": "2611040DEMO001",
        "cancel_reason": "OUT_OF_STOCK",
        "item_list": [
            {
                "item_id": 100001,
                "model_id": 100002
            }
        ]
    },
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=60,
)
print(r.status_code)
print(r.json())

Node.js

const KEY = 'q360_live_...'; // khóa API của brand
const url = new URL('https://partner.quantri360.com/v1/shopee/api/v2/order/cancel_order');
for (const [k, v] of Object.entries({})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
  method: 'POST',
  headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({"order_sn":"2611040DEMO001","cancel_reason":"OUT_OF_STOCK","item_list":[{"item_id":100001,"model_id":100002}]}),
});
console.log(r.status, await r.json());

PHP

<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/shopee/api/v2/order/cancel_order' . '?' . http_build_query([]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key, 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"order_sn":"2611040DEMO001","cancel_reason":"OUT_OF_STOCK","item_list":[{"item_id":100001,"model_id":100002}]}');
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;

Response

Tham số phản hồi (nguyên của Shopee)

Phản hồi giữ nguyên cấu trúc của API. Kiểm error / message trước khi dùng kết quả; mẫu chỉ dùng dữ liệu minh họa.

Tên	Kiểu	Mẫu	Mô tả
request_id	string	d52ca43b277a4f9292fb8be658bfd33d	Mã request của Shopee để tra lỗi.
error	string		Mã lỗi Shopee; rỗng = thành công.
message	string		Mô tả lỗi.
response	object		Kết quả xử lý.
update_time	timestamp	1793725200	Thời điểm cập nhật đơn, Unix giây.

Mẫu phản hồi

{
  "request_id": "demo-request",
  "error": "",
  "message": "",
  "response": {
    "update_time": 1793725200
  }
}

Mã lỗi của Shopee (14)

Bấm để xem

Mã	Ý nghĩa
error_not_found	Không tìm thấy đơn / gói / yêu cầu theo mã đã gửi.
error_param	Tham số sai / thiếu / sai kiểu — xem `message` để biết tham số nào.
error_permission	Gian hàng không có quyền xem dữ liệu này (vd yêu cầu trả / đơn không thuộc gian hàng).
error_server	Lỗi hệ thống Shopee — thử lại sau ít phút.
order.error_limit	Không thể hủy đơn này; xem message để biết chi tiết.
order. error_param	Không thể hủy đơn kho Shopee.
order. error_permission	Gian hàng chưa liên kết với 360; chủ gian hàng cần kết nối lại Shopee trong Partner.
error_data	Dữ liệu không tồn tại hoặc không hợp lệ cho thao tác (vd mã không có, loại yêu cầu không cho phép).
error_shop	Gian hàng không hợp lệ — kiểm tra platform_shop_id.
error_auth	Ủy quyền gian hàng cho 360 đã hết hạn hoặc bị thu hồi (360 đã tự làm mới token một lần) — chủ gian hàng kết nối lại Shopee trong Partner.
error_limit	Chạm hạn mức gọi Shopee trong ngày của kết nối — 360 trả kèm thời điểm thử lại; giảm tần suất gọi.
error_rate_limit	Gọi quá nhanh — chờ vài giây rồi gọi lại (360 cũng giới hạn theo key: 429 + Retry-After).
shop_banned	Gian hàng đang bị Shopee khóa — mọi API tạm ngưng tới khi gỡ khóa.
error_kyc_auth	Gian hàng chưa hoàn tất đăng ký người bán trên Kênh Người Bán.

Bắt đầu dùng

Đăng ký tài khoản Partner
Mở loại dữ liệu thuộc nhóm Đơn hàng ở trang nền tảng
Tạo API key (tick kênh Shopee)
Gọi theo ví dụ ở trên