How to update a canceled order’s status in VTEX

An order can be canceled by the marketplace, or by the VTEX Admin The diagram below describes the notification flow, for cancelling the order and updating the status in VTEX:

38013801

Cancelling the Order and Updating the status

Follow the steps below, once receiving the notification:

  1. Connector receives Cancel Order notification from the marketplace.
    We suggest that connectors store notifications in a queue by store for processing.

  2. Connectors record the order integration status, to validate if the order has been integrated to VTEX, avoiding reprocessing of orders.

  3. For orders that have been integrated in VTEX:
    a. Connectors should verify the order status in VTEX through the Get Order API.
    Orders with the invoiced status cannot be canceled in VTEX right away. Connectors must first issue a return invoice, through the Order Invoice Notification API, use the “type”=”input” parameter in the call, to issue a return invoice.
    b. For orders with statuses other than invoiced, call the Cancel Order API.
    c. VTEX OMS will receive the request and cancel the order.
    d.VTEX notifies the connector through the endpoint /pvt/orders/{orderId}/cancel.
    e. Connectors receive the notification and respond with 200 and the payload described below.
    f. Once receiving the response, VTEX updates the order status to canceled.

  4. For orders that have not been integrated in VTEX:
    a. Inform the user that the order is already canceled in VTEX.

{
    "orderId": string, //ID do pedido na VTEX
    "receipt": string, //GUID gerado pelo integrador 
    "date": string //Data em que a notificação foi recebido
}

🚧

Order status: invoiced

Note that if the order status in VTEX is invoiced, a return invoice must be sent through the Order Invoice Notification API, before following the Cancel Order flow described below. Use the "type"="input" parameter in the call, to issue a return invoice.

API Reference

Use the endpoints described below to perform this step. It is important to note that when consuming this API, the connector must have a valid VTEX App Key and App Token.

52625262

📘

Request bodies for POST calls

All parameters in the endpoints below must be declared in the request. In case one of the parameters does not have a value, you must still send it as null.

Cancel Order

Check out our Cancel Order API Reference to know more details about this call.

Order Invoice Notification

Use the request example below to generate an order invoice. Check out our Order Invoice Notification ​API Reference to know more details.

{
   "type": "Output",
   "invoiceNumber": "NFe-00001",
   "courier": "",
   "trackingNumber": "",
   "trackingUrl": "",
   "items": [
      {
         "id": "345117",
         "quantity": 1,
         "price": 9003
      }
   ],
   "issuanceDate": "2019-11-21T00:00:00",
   "invoiceValue": 9508
}

Scenario 1: customer cancels order in marketplace

This scenario occurs when the marketplace’s customer cancels an order in the marketplace, and the connector sends the cancellation request to VTEX.

When to perform: after receiving the cancellation notification from the marketplace

Connectors should:

  1. Validate if order has been integrated in VTEX.
  2. Validate if order status allows cancellation (all but invoiced).
  3. If steps 1 and 2 are attended, call the Cancel Order API.
  4. Store VTEX's response to the call.
  5. Receive cancelling confirmation from VTEX and respond with 200 status, along with the response received in step 4.
  6. Log status for cancellation action.

Scenario 2: orders canceled in VTEX

This scenario occurs when VTEX cancels an order, and connectors should update the marketplace.

  1. VTEX OMS sends Order Cancel notification.
  2. Connector stores VTEX's response to the call.
  3. Receive cancelling confirmation from VTEX and respond with 200 status, along with the response received in step 2.
  4. Log status for cancellation action.

Scenario 3: orders integrated in VTEX with the “canceled” status

This scenario occurs when connectors list marketplace orders, and orders that had already been integrated in VTEX have been canceled in the marketplace

Connectors should:

  1. Validate if order has been integrated in VTEX.
  2. Validate if order status allows cancellation (all but invoiced).
  3. If steps 1 and 2 are attended, call the Cancel Order API.
  4. Log status for cancellation action.

Did this page help you?