Report a buyer's cancel request on a Sales Order

POST

/v1/salesOrder/{orderNumber}/buyerCancelRequest

curl --request POST \
  --url https://api.zentail.com/v1/salesOrder/1/buyerCancelRequest \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "channelCancelId": "example", "status": "PENDING", "requestTs": {}, "respondByTs": "2026-04-15T12:00:00Z", "items": [ { "lineItemId": "example", "quantity": 1 } ], "refuseReasons": [ { "code": "example", "label": "example" } ] }'

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.

Authorizations

• zentail_oauth
  sales:orders:self

Parameters

Path Parameters

orderNumber

required

number

Zentail Order Number

Request Body

Place all of the cancel request details in a JSON object in the body of the request.

Media typeapplication/json

object

channelCancelId

required

The unique identifier for the cancel request in the sales channel.

string

status

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.

string

Allowed values: PENDING CANCELLED CLOSED

requestTs

The time the buyer asked to cancel. In ISO-8601 format. Defaults to now.

string format: date-time

default: [object Object]

respondByTs

The time the channel needs an answer by. In ISO-8601 format.

string format: date-time

items

The line items and quantities being cancelled. Required to report a new request, and ignored once it exists.

Array<object>

object

lineItemId

required

The channel’s identifier for the line item, as sent in lineItemId when the sales order was created.

string

quantity

required

The quantity the buyer asked to cancel.

integer

refuseReasons

The reasons the channel accepts for refusing the request. Replaced on each send until the merchant answers.

Array<object>

object

code

required

The channel’s code for the reason, sent back to the channel when the merchant picks it.

string

label

required

The reason as the merchant should read it.

string

Responses

200

Success

Media typeapplication/json

object

buyerCancelRequestId

The unique identifier for the cancel request in Zentail

number

channelCancelId

The unique identifier for the cancel request in the sales channel

string

status

PENDING while the channel waits for an answer, CANCELLED once the channel cancelled the units, CLOSED once it ended any other way

string

Allowed values: PENDING CANCELLED CLOSED

requestTs

The time the buyer asked to cancel. In ISO-8601 format

string format: date-time

respondByTs

The time the channel needs an answer by, if it set one. In ISO-8601 format

string format: date-time

items

The line items and quantities the buyer asked to cancel

Array<object>

object

lineItemId

string

quantity

integer

refuseReasons

The reasons the channel accepts for refusing this request

Array<object>

object

code

string

label

string

decision

The merchant’s answer in Zentail: ACCEPT, REFUSE, or null while unanswered

string

Allowed values: ACCEPT REFUSE

refuseReason

The code of the refuse reason the merchant picked, when the decision is REFUSE

string

decidedTs

The time the merchant answered. In ISO-8601 format

string format: date-time

Example

{
  "status": "PENDING",
  "decision": "ACCEPT"
}

400

Bad Request

Media typeapplication/json

object

errorCode

number

errorMessages

Array<string>

referenceId

string format: uuid

Example

{
  "errorCode": 400
}

403

Permission Denied

Media typeapplication/json

object

errorCode

number

errorMessages

Array<string>

referenceId

string format: uuid

Example

{
  "errorCode": 403
}

404

Not Found

Media typeapplication/json

object

errorCode

number

errorMessages

Array<string>

referenceId

string format: uuid

Example

{
  "errorCode": 404
}

500

Zentail Error

Media typeapplication/json

object

errorCode

number

errorMessages

Array<string>

referenceId

string format: uuid

errorMessage

string

Example

{
  "errorCode": 500
}

503

Zentail Error

Media typeapplication/json

object

errorCode

number

errorMessages

Array<string>

referenceId

string format: uuid

Example

{
  "errorCode": 503
}