API Reference > Cancellation Requests API

Cancellation Requests API

Last Updated: 2026-06-30

Overview

A buyer may request to cancel an order before it ships. Each request is open for a limited response window: the seller (you) must either approve or reject it before the auto-approve deadline elapses, after which the buyer is entitled to an automatic approval.

Cancellation request lifecycle:

pending — awaiting your adjudication
approved — you approved it; the underlying order is cancelled
rejected — you rejected it; the order stays active
auto_approved — the response window expired; the order was auto-cancelled

Authorization: every request is scoped to the seller bound to your access token. A cancellation request owned by another seller returns 404 — ownership is never leaked. Include an Idempotency-Key header to safely retry adjudication without double-processing.

Approve Cancellation

POST/open/v1/cancellation-requests/:id/approveScope: orders:write

Approve a buyer-initiated cancellation request. The request must be in pending status and within its response window. On success the underlying order is cancelled, and order.cancelled + order.updated webhook events are dispatched so subscribers tracking the order lifecycle are notified.

Example Request

curl -X POST "https://api.mallplus.com/open/v1/cancellation-requests/creq_abc123/approve" \
  -H "X-MallPlus-Partner-Id: app_ck9x2mf3w0001" \
  -H "X-MallPlus-Timestamp: 1713254400" \
  -H "X-MallPlus-Signature: a1b2c3d4e5f6..." \
  -H "Idempotency-Key: 7f3e2a1b-9c4d-4e5f-8a6b-..."

Example Response (200 OK)

{
  "success": true,
  "data": {
    "id": "creq_abc123",
    "status": "approved"
  }
}

Error Responses

Status	Code	When
404	NOT_FOUND	Request does not exist or belongs to another seller.
422	CANCELLATION_ALREADY_PROCESSED	The request was already approved, rejected, or auto-approved.
422	CANCELLATION_DEADLINE_EXCEEDED	The response window has expired; the buyer is entitled to auto-approval.

Reject Cancellation

POST/open/v1/cancellation-requests/:id/rejectScope: orders:write

Reject a buyer-initiated cancellation request with a reason. The request must be in pending status and within its response window. On success the order stays active — no order webhook is dispatched because the order state is unchanged.

Request Body

Field	Type	Required	Description
reason	string	Yes	Reason for rejecting the cancellation (1–500 chars).

Example Request

curl -X POST "https://api.mallplus.com/open/v1/cancellation-requests/creq_abc123/reject" \
  -H "X-MallPlus-Partner-Id: app_ck9x2mf3w0001" \
  -H "X-MallPlus-Timestamp: 1713254400" \
  -H "X-MallPlus-Signature: a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3e2a1b-9c4d-4e5f-8a6b-..." \
  -d '{"reason": "Order has already been packed and handed to the courier"}'

Example Response (200 OK)

{
  "success": true,
  "data": {
    "id": "creq_abc123",
    "status": "rejected"
  }
}

Validation: a missing or empty reason returns 400 VALIDATION_ERROR. The same 422 adjudication guards (CANCELLATION_ALREADY_PROCESSED, CANCELLATION_DEADLINE_EXCEEDED) apply symmetrically to approve and reject.