---
title: "Report a buyer's cancel request on a Sales Order"
method: POST
path: "/salesOrder/{orderNumber}/buyerCancelRequest"
tags: ["SalesOrder"]
---

# Report a buyer's cancel request on a Sales Order

`POST /salesOrder/{orderNumber}/buyerCancelRequest`

## Request

- Base URL: `https://api.zentail.com/v1`
- URL: `https://api.zentail.com/v1/salesOrder/{orderNumber}/buyerCancelRequest`
- Auth: API key in header `AUTHORIZATION`

Records a request the buyer made on the sales channel to cancel some or all of an order, keyed on `channelCancelId`, so the merchant can accept or refuse it in Zentail. Send it with `status: PENDING` first. A re-send changes nothing except `refuseReasons`, which are replaced until the merchant answers. Send `CANCELLED` or `CLOSED` once the channel settles the request; neither is ever undone. Read the merchant's answer from `decision`. Every `lineItemId` is checked first, so one unknown line rejects the whole request with a 400 and writes nothing.

## Path parameters

- `orderNumber` number, required

## Request body

- BuyerCancelRequestPostData
  - `channelCancelId` string, required: The unique identifier for the cancel request in the sales channel.
  - `status` 'PENDING' | 'CANCELLED' | 'CLOSED', required: `PENDING` to report the request. Send `CANCELLED` once the channel cancels the units, or `CLOSED` once the request ends any other way. Neither is ever undone.
  - `requestTs` string, date-time: The time the buyer asked to cancel. In [ISO-8601 format](/getting-started/api-basics/timestamps). Defaults to now.
  - `respondByTs` string, date-time: The time the channel needs an answer by. In [ISO-8601 format](/getting-started/api-basics/timestamps).
  - `items` BuyerCancelRequestItem[]: The line items and quantities being cancelled. Required to report a new request, and ignored once it exists.
    - `lineItemId` string, required: The channel's identifier for the line item, as sent in `lineItemId` when the sales order was created.
    - `quantity` integer, required: The quantity the buyer asked to cancel.
  - `refuseReasons` BuyerCancelRequestRefuseReason[]: The reasons the channel accepts for refusing the request. Replaced on each send until the merchant answers.
    - `code` string, required: The channel's code for the reason, sent back to the channel when the merchant picks it.
    - `label` string, required: The reason as the merchant should read it.

## Response `200`

Success

- BuyerCancelRequestData
  - `buyerCancelRequestId` number: The unique identifier for the cancel request in Zentail
  - `channelCancelId` string: The unique identifier for the cancel request in the sales channel
  - `status` 'PENDING' | 'CANCELLED' | 'CLOSED': `PENDING` while the channel waits for an answer, `CANCELLED` once the channel cancelled the units, `CLOSED` once it ended any other way
  - `requestTs` string, date-time: The time the buyer asked to cancel. In [ISO-8601 format](/getting-started/api-basics/timestamps)
  - `respondByTs` string, date-time: The time the channel needs an answer by, if it set one. In [ISO-8601 format](/getting-started/api-basics/timestamps)
  - `items` object[]: The line items and quantities the buyer asked to cancel
    - `lineItemId` string
    - `quantity` integer
  - `refuseReasons` object[]: The reasons the channel accepts for refusing this request
    - `code` string
    - `label` string
  - `decision` 'ACCEPT' | 'REFUSE': The merchant's answer in Zentail: `ACCEPT`, `REFUSE`, or null while unanswered
  - `refuseReason` string: The `code` of the refuse reason the merchant picked, when the decision is `REFUSE`
  - `decidedTs` string, date-time: The time the merchant answered. In [ISO-8601 format](/getting-started/api-basics/timestamps)

## Other responses

- `400`: Bad Request
- `403`: Permission Denied
- `404`: Not Found
- `500`: Zentail Error
- `503`: Zentail Error

---

[API](https://skmtc.dev/zentail/apis/zentail-api.md) - [All operations](https://skmtc.dev/zentail/apis/zentail-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zentail/apis/zentail-api/revisions/55e43cb43caf?raw)