Register change on order


Timeout settings

This is a synchronous API, which means the application requests data and waits until a value is returned. This behavior can cause timeout errors; to avoid them, we recommend setting the timeout in 20 seconds.

This request allows changing an order by:

  • Adding items to an order

  • Removing items from an order

  • Applying discounts to the total value of the order

  • Incrementing the total value of the order.

In those scenarios of order changes, it is possible to insert a Partial invoice. The total value of the order will be updated after the insertion of the invoice, even when there is a partial invoice scenario. The updated value is settled by VTEX's Payment Gateway. The reimbursement for the shopper is automatic.

This action can only be done for orders in these status:

  • handling

  • waiting-for-fulfillment

The Change order resource is needed to use this API request. This is included in OMS - Full access and IntegrationProfile - Fulfillment Oms, among other default roles available in the Admin. Learn more about the License manager roles and resources.


Prices and discounts expressed in cents

Take note that discountValue, incrementValue and price should be expressed in cents. As such, $100 would be written as 10000 in the request body.

Request body example

curl --location --request POST 'https://{{accountName}}.{{environment}}{{orderId}}/changes' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-VTEX-API-AppToken: {{X-VTEX-API-AppToken}}' \
--header 'X-VTEX-API-AppKey: {{X-VTEX-API-AppKey}}' \
--data-raw '{
  "itemsAdded": [
      "id": "1234568064",
      "quantity": 1,
      "price": 0
      "id": "1234568356",
      "quantity": 1,
      "price": 90
  "itemsRemoved": [
      "id": "267",
      "quantity": 1,
      "price": 8990
  "reason": "Unavailable Product",
  "discountValue": 8900,
  "incrementValue": 0

Response body example

  "date": "2019-02-08T13:54:33.6868469+00:00",
  "orderId": "v502538llux-01",
  "receipt": "535d4581-a2a2-4fd2-a206-1c61eae91b1e"
Click Try It! to start a request and see the response here!