There are many scenarios where canceling an order is necessary, whether on behalf of sellers, marketplaces or shoppers. To cover multiple scenarios, we made the following improvements in order cancellation:

• Cancel order requested by shopper: When the marketplace customer care service cancels an order after a shopper requests it, now the seller is notified about the cancellation reason and whether or not it was made on behalf of the shopper.
• Deny cancel order: After the cancellation window period – or grace period –, now the seller can deny cancellation requests.

In each case, both seller and marketplace will be notified about changes, have access to information about each other's reasons for canceling and/or denying a cancel request, and sellers will know when the shopper requested the cancellation.

For information about this feature in VTEX Admin, see Declining order cancelation.

In this article, the term marketplace will refer to VTEX marketplace and seller to VTEX seller. For more information, see Marketplace strategies at VTEX.

Using the endpoints mentioned in this article requires having the Cancel order resource associated with the user or integration key. This resource is included in the following predefined roles:

For more information, see users and License Manager resources at VTEX.

With the Cancel order endpoint, now it is possible to indicate if the canceling request was demanded by the shopper or not. This is possible because of the new request body field requestedByUser. This is useful for sellers to know when the marketplace cancels an order on behalf of the shopper.

A common scenario is when the shopper contacts the marketplaces customer care service via telephone, for example, and requests an order cancellation. In the cancellation request, the customer care now can inform both marketplace and seller that the cancellation was demanded by the shopper.

The order flow for canceling orders remains the same.

The following image shows the flow when canceling an order on behalf of the shopper:

The step by step is the following:

1. The shopper contacts the marketplace customer care service to cancel an order.
2. The customer care cancels it using the Cancel order endpoint. The request body contains the reason for order cancellation and indicates if it was requested by the shopper.
3. The cancel order request notifies the seller about the cancellation reason and if the request came from the shopper or not.
4. VTEX seller cancels the order.

See below the Cancel order endpoint, where orderId corresponds to the ID of the order been canceled:

POST - https://{accountName}.{environment}.com.br/api/oms/pvt/orders/{orderId}/cancel

cURL

See below a request body example:

The following table presents the request body fields’ description:

Field	Type	Description
reason	string	Brief explanation of why the order is being canceled.
requestedByUser	boolean	When set as true, the cancellation was requested by the shopper, and when set as false, the cancellation was not canceled on behalf of the shopper.

See below a response body example:

The following table presents the response body fields’ description:

Field	Type	Description
date	string	Date and time of when the platform processed the cancellation request. The format is according to ISO 8601 YYYY-MM-DDThh:mm:ssTZD, meaning a complete date plus hours, minutes, seconds and a decimal fraction of a second. For example, 2023-08-04T15:45:02.1306363+00:00.
orderId	string	ID that identifies the order being canceled.
receipt	string	Protocol code generated by the update. It may be null.

The possible response status codes are shown in the table below:

Status Code	Description
200 OK	The order was successfully canceled.
403 Forbidden	Unauthorized request. Update the credentials used in the request and try again.
404 Not Found	The requested order was not found. Check the order ID and try again.
429 Too Many Requests	We were unable to process the request due to the high volume of submissions. Wait a few minutes before trying again.
500 Internal Server Error	An unexpected application error occurred. Review the request data and try again.

After the seller agrees to cancel the order, as requested by the marketplace on behalf of the shopper, it reaches the canceled status. By using one of the endpoints below, both seller and marketplace can retrieve cancellation information:

• GET - Get order
• GET - Retrieve user order details

The information will be in the cancellationData object of the response body, as shown in the example below:

Seller and marketplace will get the same order cancellation information.

The fields’ description are shown below:

Response body field	Type	Description
cancellationData	object	Object with information about the order cancellation.
requestedByUser	boolean	When set as true, the cancellation was requested by the shopper, and when set as false, the cancellation was not canceled on behalf of the shopper.
reason	string	Explanation of why the order was canceled.
cancellationDate	string	Date and time of when the platform processed the cancellation request. The format is according to ISO 8601 YYYY-MM-DDThh:mm:ssTZD, meaning a complete date plus hours, minutes, seconds and a decimal fraction of a second. For example, 2023-08-04T15:45:02.1306363+00:00 It could also be 2023-08-04T15:45:02.1306363Z, where Z stands for zone in Time Zone Designator (TZD). Z is equal to +hh:mm or -hh:mm.
cancellationRequestId	string	ID that identifies the cancellation operation.

In the order flow, there is a cancellation window period – or grace period – in which an order can be automatically canceled by the shopper. Except for that period, now the seller can deny order cancel requests, regardless if the cancellation request came from the shopper or the marketplace.

A common scenario for using this endpoint is when the marketplace works with sellers whose products are made on demand by each purchase. If a shopper contacts the marketplace customer care service via telephone demanding the order cancellation, and the marketplace cancels the order, now the seller can deny the cancellation request.

To deny an order cancellation request, the order status in the marketplace and seller must be the following:

• Marketplace status: waiting-for-seller-decision.
• Seller status: cancellation-requested.

The following image shows the flow of denying an order’s cancel request outside the cancellation window:

The step by step is the following:

1. The shopper contacts the marketplace to cancel an order.
2. After receiving the request, the marketplace sends a cancellation request to the seller.

   At this point, the order status for the marketplace is waiting-for-seller-decision.

3. If the order is within the cancellation window period, this order is automatically canceled, which is the platform default behavior. The next steps are for when the order is no longer within the cancellation window.
4. The seller receives the cancel order request and decides to accept it or not. The next steps are for when the seller decides not to cancel the order.
5. The seller’s request to deny the order cancellation and that notifies the marketplace, with the reason included.
6. After the marketplace receives the denial request, the order moves on in the order workflow, from the status below:
   • For the marketplace: payment-approved.
   • For the seller: ready-for-handling or handling, depending on which was the status before the cancel request.
7. Optional: marketplace can, via webhook, notify a subscribed shopper about the order change in payment-approved and cancellation-request-denied status. It is also possible for some applications to collect the order cancellation denial reason given by the seller and inform the shopper.

See below the endpoint deny order cancellation, where orderId corresponds to the ID of the order witches cancellation is being denied:

POST - [https://{accountName}.{environment}.com.br/api/orders/pvt/document/{OrderId}/deny-cancellation-request](https://{accountName}.{environment}.com.br/api/orders/pvt/document/{OrderId}/deny-cancellation-request)

cURL

See below a request body example:

The following table presents the request body fields’ description:

Field	Type	Description	Mandatory
cancellationRequestId	string	Unique identifier of an order requested to be canceled. This ID format is a sequence of numbers and letters. The cancellationRequestId is generated by the endpoint Cancel order, and can be found in the responses of the following endpoints: Get order Retrieve user order details	Yes
denyReason	string	Brief explanation of why the seller will deny order cancellation.	Yes

The endpoint does not return a response body in the successful 200 OK response.

The possible response status codes are shown in the table below:

Status Code	Description
200 OK	The order cancellation was successfully denied.
400 Bad Request	The request was not processed, some possible reasons are: Cancellation request ID not found. Order already canceled. Order workflow not found. Invalid order status. The acceptable status for the seller is cancellation-requested , and for the marketplace is waiting-for-seller-decision.
403 Forbidden	Unauthorized request. Update the credentials used in the request and try again.
404 Not Found	The requested order was not found. Check the order ID and try again.
429 Too Many Requests	We were unable to process the request due to the high volume of submissions. Wait a few minutes before trying again.
500 Internal Server Error	An unexpected application error occurred. Review the request data and try again.

After the seller denies the cancellation request made by the marketplace outside the cancellation window, the related information can be retrieved both by marketplace and seller using one of the endpoints below:

• GET - Get order
• GET - Retrieve user order details

The information will be in the cancellationRequests array of the response body, as shown in the example below:

Seller and marketplace will get the same denial cancellation information.

The fields’ description are shown below:

Response body field	Type	Description
cancellationRequests	array	Array with information regarding the order witches cancellation was denied.
id	string	ID that identifies the original cancellation operation made by the marketplaces or its customer care service using the Cancel order endpoint.
reason	string	Explanation of why there was a request for canceling the order.
cancellationRequestDate	string	Date and time of when the platform processed the cancellation request. The format is ISO 8601 YYYY-MM-DDThh:mm:ssTZD, a complete date plus hours, minutes, seconds and a decimal fraction of a second. For example, 2023-08-04T15:45:02.1306363+00:00 It could also be 2023-08-04T15:45:02.1306363Z, where Z stands for zone in Time Zone Designator (TZD), and Z is equal to +hh:mm or -hh:mm.
requestedByUser	boolean	When set as true, the cancellation was requested by the shopper, and when set as false, the cancellation was not canceled on behalf of the shopper.
deniedBySeller	boolean	When set as true, the seller denied the order cancellation, and when set as false, the seller did not deny it.
deniedBySellerReason	string	Reason given by the seller for denying order cancellation.
cancellationRequestDenyDate	string	Date and time of when the seller’s request to deny order cancellation was processed. The format is ISO 8601 YYYY-MM-DDThh:mm:ssTZD, a complete date plus hours, minutes, seconds and a decimal fraction of a second. For example, 2023-08-04T15:45:02.1306363+00:00 It could also be 2023-08-04T15:45:02.1306363Z, where Z stands for zone in Time Zone Designator (TZD), and Z is equal to +hh:mm or -hh:mm.