---
title: "Register modifications on order"
method: POST
path: "/api/oms/pvt/orders/{orderId}/changes"
tags: ["Orders"]
---

# Register modifications on order

`POST /api/oms/pvt/orders/{orderId}/changes`

This request allows [modifying an order](https://help.vtex.com/en/tutorial/changing-items-from-a-completed-order--tutorials_190) 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. 

>❗ This endpoint is being deprecated in March 1st, 2026. We stopped providing support for this API since December 31st, 2025. If you wish to modify an order, you can use the [Create order modifications](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) endpoint for an improved order modification experience.

 > **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.

In order modifications scenarios, it is possible to insert a [Partial invoice](https://help.vtex.com/en/tracks/orders--2xkTisx4SXOWXQel8Jg8sa/q9GPspTb9cHlMeAZfdEUe). 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 the VTEX Payment Gateway, and the customer reimbursement is automatic. 

This action can only be done for orders in the following status:

- `handling`

- `waiting-for-fulfillment`

- `ready for invoicing` 

## Permissions

Any user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:

| **Product** | **Category** | **Resource** |
| --------------- | ----------------- | ----------------- |
| Checkout | CheckoutResources | **Orders Full Access** |
| OMS | OMS access | **Cancel order** |
| OMS | OMS access | **Change order** |

You can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):

| **Role** | **Resource** | 
| --------------- | ----------------- | 
| Checkout Admin | Orders Full Access |
| OMS - Full access | <p>Cancel order</p><p>Change order</p> |
| IntegrationProfile - Fulfillment Oms | <p>Cancel order</p><p>Change order</p> |
| IntegrationProfile - Fulfillment Gateway | Cancel order |
| IntegrationProfile - Fulfillment Gateway Oms | <p>Cancel order</p><p>Change order</p> |
| inStore Sales Person | <p>Cancel order</p><p>Change order</p> |

>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm).

To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).

## Path parameters

- `orderId` string, required

## Headers

- `Content-Type` string, required
- `Accept` string, required

## Request body

- object
  - `requestId` string, required — Request identification of the modification. Only the first modification made with each `requestId` will be effective on a given order. Use different IDs for different modifications to the same order.
  - `reason` string, required — Reason for order modification. This may be shown to the shopper in the UI or transactional emails.
  - `discountValue` integer, required — This field can be used to apply a discount to the total value of the order. Value in cents.
  - `incrementValue` integer, required — This field can be used to increment the total value of the order. Value in cents.
  - `itemsRemoved` object[] — List of items that should be removed from the order.
    - `id` string, required — SKU ID of the item being removed.
    - `price` integer, required — Price of the item being removed in cents.
    - `quantity` integer, required — Amount of items to be removed.
  - `itemsAdded` object[] — List of items that should be added to the order.
    - `id` string, required — SKU ID of the item being added.
    - `price` integer, required — Price of the item being added in cents.
    - `quantity` integer, required — Amount of items to be added.

## Response `200`

OK

- object
  - `date` string — Date of order modification.
  - `orderId` string — ID of the order.
  - `receipt` string — Receipt identification.

---

[API](https://skmtc.dev/vtex/apis/orders-api.md) · [All operations](https://skmtc.dev/vtex/apis/orders-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/vtex/orders-api/revisions/cb5fa08e400c/schema)