---
title: "Create order modifications"
method: PATCH
path: "/api/order-system/orders/{changeOrderId}/changes"
tags: ["Order modifications"]
---

# Create order modifications

`PATCH /api/order-system/orders/{changeOrderId}/changes`

[Order modifications](https://help.vtex.com/docs/tutorials/how-order-modification-works) feature allows you to modify an order, whether the modification is motivated by customer mistakes, product unavailability, or others. Both sellers and marketplaces can use this endpoint and modify orders in multiple scenarios, and it is possible to make a single modification or combine multiple ones in the same request. 
The possible order modifications operations you can perform are the following:
- **Add:** Adding items, quantity, or product weight.
- **Remove:** Removing a part of items or the total quantity.
- **Replace:** Changing items' quantity, weight, or price. You can also replace one or more items with different ones, including weighable products. In addition, you can change your clients's data. 

>❗ When removing or adding items to an order, your [inventory](https://help.vtex.com/en/tutorial/inventory-management--tutorials_139) is not automatically updated. You can use the [Update inventory by SKU and warehouse](https://developers.vtex.com/docs/api-reference/logistics-api#put-/api/logistics/pvt/inventory/skus/-skuId-/warehouses/-warehouseId-) endpoint.

 >⚠️ The Order modifications feature isn't applicable to the Catalog API - Seller Portal. 

>❗ If the order you are modifying has more than one shipping address, you cannot add products that were not in the original order. You can only increase or decrease the quantity of the existing items, or remove items. 

The next sections are listed below:
- Number of modifications per order 
- Acceptable order status for modifications 
- Order modifications and price 
- Combining multiple operations 

## Number of modifications per order
Besides being able to combine multiple modification operations - add, remove, and replace - in a single request, you can make different modification requests, and there is no limit to how many times an order can be modified.

Each order has its modifications history, you can retrieve it using the [Get order modifications history](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/order-system/orders/-changeOrderId-/changes) endpoint.

## Acceptable order status for modifications
You can only modify an order when it is one of the following [order flow](https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials_196) status:
- `handling`
- `waiting-for-fulfillment` 
- `ready for invoicing` 

It is not possible to modify an order when the payment transaction is complete.

## Order modifications and price
When you add, remove or replace items using this endpoint, the order and payment transaction values are automatically updated. Order modifications calculates the update of the following values:
- Item value
- Total value 

**Example:** If you send the request body for replacing items without the unit multiplier (`unitMultiplier`) or measurement (`measurementUnit`), Order modifications will get this information on your store's Catalog, Pricing and Payment systems. 
>⚠️ Increasing the price of an order is allowed only when the order was paid by credit card, [payable notes](https:/help.vtex.com/en/tutorial/setting-up-payments-with-promissory--5pW7avTwtyQcMu4uiW8quQ), cash, or [credit control](https:/help.vtex.com/en/tutorial/customer-credit-overview--1uIqTjWxIIIEW0COMg4uE0). In addition, the [acquirer](https:/help.vtex.com/en/tutorial/what-is-an-acquirer--7N1oRTG8dGmOiIugC0cs4E) must allow transactions without the CVV code and two charging transactions in the same order. 

For order modifications with discounts, Order Management System (OMS) considers that you still can modify the order's transactional value, as long as its status in Transaction Details is not `Finished`. 

## Order modifications and payment transaction flow 

An order's [transaction flow](https://help.vtex.com/tracks/payments--6GAS7ZzGAm7AGoEAwDbwJG/1xjzgJZvqwaI1rfxLMCC3Y) goes through various payment statuses before its conclusion. Within certain conditions, it is possible to modify settled orders. The requirements are the following:

- The order's [payment method](https://help.vtex.com/en/tutorial/difference-between-payment-methods-and-payment-conditions--3azJenhGFyUy2gsocms42Q) is a credit card.
- The settlement occurs before the order is invoiced.
- The payment connector is configured to allow partial refunds.

> Currently, [Adyen](https://help.vtex.com/en/tutorial/configuring-payment-with-adyenv3--7xAz67E2Eg63LWCQNjVdwv) is the only payment connector that supports that operation.

If the order modification increases or decreases the cost for the customer, the platform has the following behavior:

- **Smaller price after order modification:**
    - If the payment is marked as `settled` in the [transaction flow](https://help.vtex.com/tracks/payments--6GAS7ZzGAm7AGoEAwDbwJG/1xjzgJZvqwaI1rfxLMCC3Y), an automatic notification is sent to the payment [gateway](https://help.vtex.com/tracks/payments--6GAS7ZzGAm7AGoEAwDbwJG/kdPbEIWf8Xq8tESQvViMB#gateway) to reimburse the customer for the difference.
    - If the payment hasn't been settled, an automatic notification is sent to the payment gateway to change the order's total amount.
- **Higher price after order modification:** An automatic notification is sent to the payment gateway to require the customer to pay for the additional cost.

 ## Order modifications settings

The Order modifications settings allow you to customize your account's behavior when receiving a modification request, such as configuring the order payments, defining tax recalculation, and compensating shipping costs. Before or during the API integration, you can consult and, if necessary, adjust the settings of the modifications.

* If you wish to consult the current settings, run the [Get Order modifications settings](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/order-system/orders/changes/settings) endpoint. 
* If you wish to alter the current settings, run the [Update Order modifications settings](https://developers.vtex.com/docs/api-reference/orders-api#put-/api/order-system/orders/changes/settings) endpoint.  

 ## Combining multiple operations

You can use this endpoint to make a single change operation or combine them in the same request. See some examples below.

### Adding request body example:

```json
{
   "add": {
      "items": [
          {
              "id": "8",
              "quantity": 1,
              "measurementUnit": "un",
              "unitMultiplier": 1
          }
      ]
    }
}
```

### Removing request body example:

```json
{
    "reason": "The client wants to remove a product.",
    "remove": {
        "items": [
            {
                "id": "8",
                "quantity": 2,
                "measurementUnit": "un",
                "unitMultiplier": 1
            }
        ]
    }
}
```

### Replacing request body example:
```json
{
    "reason": "The client wants to increase the product weight.",
    "replace": [
        {
            "from": {
                "items": [
                    {
                        "id": "1",
                        "quantity": 1
                    }
                ]
            },
            "to": {
                "items": [
                    {
                        "id": "2",
                        "quantity": 1,
                        "measurementUnit": "kg",
                        "unitMultiplier": 1.0
                    }
                ],
                "shippingData": {
                    "logisticsInfo": [
                        {
                            "itemIndex": 0,
                            "selectedSla": "Normal",
                            "selectedDeliveryChannel": "delivery",
                            "addressId": "12334048475146857",
                            "price": 1000
                        }
                    ]
                }
            }
        }
    ]
}
```


### Adding, removing and replacing request body example:


```json
{
  "reason": "The client wants to add, remove and replace a weighable product.",
  "manualDiscountValue": 0,
  "add": {
      "items": [
          {
              "id": "8",
              "quantity": 1,
              "measurementUnit": "un",
              "unitMultiplier": 1
          }
      ]
  },
  "remove": {
      "items": [
          {
              "id": "31",
              "quantity": 1,
              "measurementUnit": "un",
              "unitMultiplier": 1
          }
      ]
  },
  "replace": [
                        {
                          "from": {
                            "items": [
                              {
                                "id": "1",
                                "quantity": 1
                              }
                            ]
                          },
                          "to": {
                            "items": [
                              {
                                "id": "2",
                                "quantity": 1,
                                "measurementUnit": "kg",
                                "unitMultiplier": 1.0
                              }
                            ],
                            "shippingData": {
                              "logisticsInfo": [
                                {
                                  "itemIndex": 0,
                                  "selectedSla": "Normal",
                                  "selectedDeliveryChannel": "delivery",
                                  "addressId": "12334048475146857",
                                  "price": 1000
                                }
                           ]
                       }
                  }
            }
     ]
}
```

## 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

- `changeOrderId` string, required

## Query parameters

- `accountName` string, required

## Headers

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

## Request body

- Createchange
  - `reason` string, required — Reason why you wish to modify order. Since you can make several modifications to an order, filling this field with a clear explanation helps organize the order modifications history. The shopper can view this field value in [transactional emails](https://help.vtex.com/en/tutorial/order-transactional-email-templates--3g2S2kqBOoSGcCaqMYK2my) and [My Account](https://help.vtex.com/en/tutorial/how-my-account-works--2BQ3GiqhqGJTXsWVuio3Xh).
  - `replace` Replace[] — Array containing `replace` change information. Besides `replace`, you can `add` or `remove` items from an order. - `add`: the schema will correspond to the object `to` inside the `replace` array. - `remove`: the schema will correspond to the object `from` inside the `replace` array. You will find request body examples of both cases in the endpoint description on the top of the page. The successful response `202 - Accepted` schema is the same for all three operations, whether they are used separately or combined in the same request.
    - `from` object, required — Object with information about the items been replaced. If instead of an order `replace` you wish to `remove` items, you will use the same schema naming the object `remove` instead of `from`. For a complete example, see the description at the top of the page.
      - `items` object[], required — Array with information about the item to be replaced.
        - `id` string, required — SKU ID of the item that will be modified.
        - `uniqueId` string — Unique ID of the item being modified. We recommend always using this field to avoid modification errors for items with the same `id`.
        - `quantity` integer, required — Quantity of the item being modified. Must be greater than 0.
        - `price` integer — Price of the item being changed in cents. Must be 0 or greater.
      - `customData` object — Object with information about the custom data.
        - `customFields` object[] — Array with information about the custom fields.
          - `linkedEntity` object — Object with information about the linked entity. If you wish to modify the linked entity `type` and `id`, you must first use this endpoint to `remove` the old `type` and `id`, then you call this same endpoint to `add` the new `type` and `id`.
            - `type` string — Type of the linked entity such as `cart`, `item`, `address`.
            - `id` string — ID of the linked entity.
          - `fields` object[] — Array with information about the custom field's name and value.
            - `name` string — Name of the custom field.
            - `value` string — Value of the custom field.
    - `to` object, required — Object with information about the new replacing items. If instead of an order `replace` you wish to `add` items, you will use the same schema naming the object `add` instead of `to`. For a complete example, see the description at the top of the page.
      - `items` object[], required — Array with information about the replacing items.
        - `id` string, required — SKU ID of the item that will replace the previous one. If you only wish to replace the product weight, you will repeat the SKU ID used in `from`.
        - `uniqueId` string — Unique ID of the item being modified. We recommend always using this field to avoid modification errors for items with the same `id`.
        - `quantity` integer, required — Updated quantity of the item being modified. Must be greater than 0.
        - `measurementUnit` string — Measurement unit of the new item. The values accepted are the measurement units registered in the store's catalog. For example, `kg` for kilograms or `un` for unitary items. When you don't specify a value, the request gets the information from the Catalog.
        - `unitMultiplier` number — Unit multiplier for item update. For example, if you wish to increase an order with three times more items than a single one, you would fill in with `3.0`.
        - `manualDiscountValue` integer — This field shows if a manual price was applied to the total order amount. The value is in cents. Must be 0 or greater.
        - `manualIncrementValue` integer — This field shows if an increment value was applied to the total order amount. The value is in cents. Must be 0 or greater.
        - `clientProfileData` object[]
          - `firstName` string — Customer's first name.
          - `lastName` string — Customer's last name.
          - `documentType` string — Type of the document informed by the customer.
          - `document` string — Document number informed by the customer.
          - `phone` string — Customer's phone number.
          - `corporateName` string — If it's a legal entity, here goes the company name.
          - `tradeName` string — If it's a legal entity, here goes the trade name.
          - `corporateDocument` string — If it's a legal entity, here goes the corporate document.
          - `stateInscription` string — If it's a legal entity, here goes the state inscription.
          - `corporatePhone` string — If it's a legal entity, here goes the company phone.
          - `isCorporate` boolean — It has the value `true` if it's a legal entity.
      - `customData` object — Object with information about the custom data.
        - `customFields` object[] — Array with information about the custom fields.
          - `linkedEntity` object — Object with information about the linked entity. If you wish to modify the linked entity `type` and `id`, you must first use this endpoint to `remove` the old `type` and `id`, then you call this same endpoint to `add` the new `type` and `id`.
            - `type` string — Type of the linked entity such as `cart`, `item`, `address`.
            - `id` string — ID of the linked entity.
          - `fields` object[] — Array with information about the custom field's name and value.
            - `name` string — Name of the custom field.
            - `value` string — Value of the custom field.
      - `shippingData` object — Shipping data object.
        - `logisticsInfo` object[], required — Array containing information about the shipping address of the modified order. This field is optional, when you don't send it the request body, the system assumes there were no modifications in shipping.
          - `itemIndex` integer, required — Index that identifies the position of this item in the original array, starting from `0`.
          - `selectedSla` string, required — Shipping method of the [shipping policy](https://help.vtex.com/en/tutorial/shipping-policy--tutorials_140) used in the order.
          - `selectedDeliveryChannel` 'delivery' | 'pickup-in-point', required — Order shipping type, which can be `pickup-in-point` for [pickup point](https://help.vtex.com/en/tutorial/pickup-points--2fljn6wLjn8M4lJHA6HP3R), and `delivery` for delivery.
          - `addressId` string, required — Shipping address ID.
          - `price` integer, required — Shipping price for the item in cents. Does not account for the whole order's shipping price.
  - `settings` ChangeOrderSettingsRequest
    - `paymentConfiguration` object — [Order modifications](https://help.vtex.com/en/tutorial/how-change-order-works-beta--56TO0bOFXsfmpc7YZ3wIUZ) payment configurations. When sending these fields with the [Create order modifications](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) or the [Preview order modifications](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/order-system/orders/-changeOrderId-/changes/preview) endpoints, the settings override the account's default Order modifications settings for this request only.
      - `customPaymentSystemsAllowed` string[] — List of custom payment system IDs configured for the VTEX account.
    - `rolloutConfiguration` object — **Order modifications** settings regarding VTEX Admin, [Orders API](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes?endpoint=patch-/api/order-system/orders/-changeOrderId-/changes) and **My Account** feature. When sending these fields with the [Create order modifications](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) or the [Preview order modifications](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/order-system/orders/-changeOrderId-/changes/preview) endpoints, the settings override the account's default Order modifications settings for this request only.
      - `enableApi` boolean — Defines if the [Order modifications API](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) is enabled (`true`) or not (`false`). The account can only use the [Order modifications via VTEX Admin](https://help.vtex.com/en/tutorial/how-to-change-orders-beta--7btlG91rb6sHpW1dkd2kBw) or [via API](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) if this field is set to `true`.
      - `enableAdminOrders` object — Object about enabling the [Order modifications feature via VTEX Admin](https://help.vtex.com/en/tutorial/how-to-change-orders-beta--7btlG91rb6sHpW1dkd2kBw).
        - `enabledWorkspaces` string[] — List with the workspaces' names that have the **Order modifications** feature enabled via VTEX Admin.
      - `enableMyOrders` object — Object about enabling the **Order modifications** feature via [My Account](https://help.vtex.com/en/tutorial/how-my-account-works--2BQ3GiqhqGJTXsWVuio3Xh).
        - `enabledWorkspaces` string[] — List with the workspace names that have the **Order modifications** feature enabled via **My Account**.
    - `pipelineConfiguration` object — **Order modifications** settings related to taxes and shipping calculation. When sending these fields with the [Create order modifications](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) or the [Preview order modifications](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/order-system/orders/-changeOrderId-/changes/preview) endpoints, the settings override the account's default Order modifications settings for this request only.
      - `enableTaxHubRecalculation` boolean — Defines if the tax recalculation is enabled for **Order modifications** (`true`) or not (`false`).
      - `compensateShippingChanges` boolean — Defines if the orders modified will have zero shipping cost (`true`) or not (`false`). Merchants can enable this configuration to modify only items and prices, without impacting the orders' original freight costs.
      - `enablePromotionRecalculation` boolean — Defines if the promotion recalculation is enabled for **Order modifications** (`true`) or not (`false`).
      - `enableNativeTaxRecalculation` boolean — Defines if the native tax recalculation is enabled for **Order modifications** (`true`) or not (`false`).

## Response `202`

Accepted

- Response202
  - `requestId` string, required — Unique code that identifies an order modification request.
  - `workflowId` string, required — Code that identifies the transaction of modifying the orders in the [order flow](https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials_196).
  - `reason` string, required — Reason that motivated the order modifications.
  - `manualDiscountValue` integer, required — This field shows if a manual price was applied to the total order amount. The value is in cents.
  - `manualIncrementValue` integer, required — This field shows if an increment value was applied to the total order amount. The value is in cents.
  - `totalChangeValue` integer, required — This field shows how much the order total price is considering that price modifications might have been made. The value is in cents.
  - `totals` string[], required — Array containing information about change prices per item.
  - `add` string[], nullable, required — Array with information about the `add` operation, when applicable. The schema will correspond to the object `to` inside the `replace` array.
  - `remove` string[], nullable, required — Array with information about the `remove` operation, when applicable. The schema will correspond to the object `from` inside the `replace` array.
  - `replace` Replace1[], nullable, required — Array with information about the `replace` operation, when applicable.
    - `from` object, required — Information about what items were replaced.
      - `paymentData` PaymentDataV2, required — Payment data object.
        - `transactions` string[], required — Information about financial transactions.
      - `items` object[], required — Array with items information.
        - `id` string, required — SKU ID of the item being replaced.
        - `quantity` integer, required — Quantity of items been replaced.
        - `price` integer, nullable, required — Shipping price for the replaced item, in cents. It does not account for the whole order's shipping price.
        - `measurementUnit` string, nullable, required — Measurement unit of the item being replaced. For example, `kg` for kilograms or `un` for unitary items.
        - `unitMultiplier` integer, required — Unit multiplier for item being updated.
        - `sellingPrice` integer, nullable, required — Selling price of the item being replaced.
        - `name` string, nullable, required — Name of the item being replaced.
        - `detailUrl` string, nullable, required — URL slug of the item being replaced.
        - `imageUrl` string, nullable, required — Image URL slug of the item being replaced.
      - `shippingData` ShippingData1, required — Shipping data object.
        - `logisticsInfo` string[], required — Array with logistics information about the order been replaced. If not sent in the original request, it will be an empty array in the response.
    - `to` object, required — Information about items that replaced the previous one.
      - `items` Item3[], required — Array containing information about the item replacing the previous one.
        - `uniqueId` string, required — Item's unique ID in the order modifications request.
        - `id` string, required — SKU ID of the item replacing the previous one.
        - `productId` string, nullable, required — Product ID of the item replacing the previous one.
        - `productRefId` string, nullable, required — Product Ref ID of the item replacing the previous one.
        - `refId` string, nullable, required — Reference ID of the item replacing the previous one.
        - `ean` string, nullable, required — European Article Number (EAN) of the item replacing the previous one.
        - `name` string, nullable, required — Name of the Product associated with the item replacing the previous one.
        - `skuName` string, nullable, required — Name of the SKU replacing the previous one.
        - `modalType` string, nullable, required — A [modal](https://help.vtex.com/en/tutorial/how-does-the-modal-work--tutorials_125) attaches an unusual product, such as meat or glass, to a carrier specialized in shipping it.
        - `parentItemIndex` integer, nullable, required — Parent item index of the item replacing the previous one.
        - `parentAssemblyBinding` string, nullable, required — Parent assembly binding of the item replacing the previous one.
        - `assemblies` string[], nullable, required — Array with information about services that may be offered for the item replacing the previous one. For example, the assembly of a piece of furniture or warranty.
        - `priceValidUntil` string, nullable, required — Price expiration date of item replacing the previous one. The value is in the format `yyyy-mm-ddThh:mm:ss.sss`.
        - `tax` integer, required — Tax in cents of the item replacing the previous one, when applicable.
        - `price` integer, nullable, required — Final price of the item replacing the previous one, calculated in cents.
        - `listPrice` integer, nullable, required — Item's price list for the item replacing the previous one.
        - `manualPrice` integer, nullable, required — Manual price of the item replacing the previous one. It is calculated in cents.
        - `manualPriceAppliedBy` string, nullable, required — User ID or appKey that made the manual price modification of the item replacing the previous one.
        - `sellingPrice` integer, nullable, required — Selling price of the item replacing the previous one. It is calculated in cents.
        - `rewardValue` integer, required — Reward value of the item replacing the previous one. It is calculated in cents.
        - `isGift` boolean, required — This field is `true` when the replacing item is a gift in the order context and `false` when it is not.
        - `additionalInfo` AdditionalInfoV2, required — Additional information object.
          - `dimension` string, nullable, required — Replacing item's dimensions in the measure unit configured in the catalog.
          - `brandName` string, nullable, required — Replacing item's brand name.
          - `brandId` string, nullable, required — Replacing item's brand ID.
          - `offeringInfo` string, nullable, required — Offering information.
          - `offeringType` string, nullable, required — Offering type.
          - `offeringTypeId` string, nullable, required — Offering type ID.
          - `categoriesIds` string, nullable, required — ID of the replacing item product category.
          - `productClusterId` string, nullable, required — All product clusters related to the replacing item.
          - `commercialConditionId` string, nullable, required — Replacing item commercial conditions ID.
        - `preSaleDate` string, nullable, required — Pre sale date of the item replacing the previous one.
        - `productCategoryIds` string, nullable, required — Replacing item's category path composed of category IDs separated by `/`. For example: `/3/15/`.
        - `productCategories` object, required — Object containing product categories of the replacing item. Structure: `{CategoryID}: {CategoryName}`. Both the key and the value are strings.
        - `quantity` integer, required — Quantity of replacing items.
        - `seller` string, nullable, required — Seller ID that identifies the seller the replacing item belongs to.
        - `sellerChain` string[], nullable, required — Array containing information about sellers involved in the chain. The list should contain only one seller, unless it is a [Multilevel Omnichannel Inventory](https://developers.vtex.com/docs/guides/multilevel-omnichannel-inventory) order.
        - `imageUrl` string, nullable, required — Image URL slug of the replacing item.
        - `detailUrl` string, nullable, required — URL slug of the replacing item.
        - `components` string[], required — Array with information about replacing item's components.
        - `bundleItems` string[], required — Array with information about services sold along with the replacing item, such as a gift package.
        - `attachments` string[], required — Array containing information on attachments.
        - `attachmentOfferings` string[], required — Array with the properties of the content declared in the field `attachments`.
        - `offerings` string[], required — Array with replacing items Item's offerings.
        - `priceTags` string[], required — Array containing objects with replacing item's price modifiers.
        - `availability` string, nullable, required — Availability to fulfill the order with the item.
        - `measurementUnit` string, required — Replacing item's measurement unit.
        - `unitMultiplier` integer, required — Replacing item's unit multiplier.
        - `manufacturerCode` string, nullable, required — Provided by the manufacturers to identify their product. This field must be completed if the replacing item has a manufacturer's code.
        - `priceDefinition` string, nullable, required — Replacing item's price information.
      - `paymentData` PaymentDataV2, required — Payment data object.
        - `transactions` string[], required — Information about financial transactions.
      - `receiptData` object, nullable, required — Information about the receipt after order modifications.
      - `shippingData` object, required — Shipping data object.
        - `logisticsInfo` LogisticsInfo1[], required — Array with shipping information.
          - `itemIndex` integer, required — Index that identifies the position of the replacing item in the array, starting from `0`.
          - `selectedSla` string, required — Shipping method of the [shipping policy](https://help.vtex.com/en/tutorial/shipping-policy--tutorials_140) used in the replacing order.
          - `addressId` string, required — Shipping address ID of the replacing item.
          - `slas` SlaV2[], required — Information on Service Level Agreement (SLA) of the order modifications shipping policy.
            - `id` string, required — Shipping method of the [shipping policy](https://help.vtex.com/en/tutorial/shipping-policy--tutorials_140) used in the order delivery or pickup.
            - `deliveryChannel` string, required — Order shipping type, which can be `pickup-in-point` for [pickup point](https://help.vtex.com/en/tutorial/pickup-points--2fljn6wLjn8M4lJHA6HP3R), and `delivery` for delivery.
            - `name` string, required — Shipping method of the [shipping policy](https://help.vtex.com/en/tutorial/shipping-policy--tutorials_140) used in the order delivery or pickup. It corresponds to the `id` value.
            - `deliveryIds` DeliveryIdV2[], required — Information about delivery IDs.
              - …
            - `shippingEstimate` string, nullable, required — Total shipping duration estimated in days. For instance, three business days is represented as `3bd`.
            - `shippingEstimateDate` string, nullable, required — Shipping estimate date. The value is in UTC ISO 8601 format `yyyy-mm-ddThh:mm:ss.sssZ`.
            - `lockTTL` string, nullable, required — Logistics [reservation](https://help.vtex.com/en/tutorial/how-does-reservation-work--tutorials_92) waiting time of the SLA. For instance, one business day is represented as `1bd`.
            - `availableDeliveryWindows` string[], required — Available [scheduled delivery](https://help.vtex.com/en/tutorial/scheduled-delivery--22g3HAVCGLFiU7xugShOBi) information, for when the shipping policy has shipping windows configurations.
            - `deliveryWindow` object, nullable, required — [Scheduled delivery](https://help.vtex.com/en/tutorial/scheduled-delivery--22g3HAVCGLFiU7xugShOBi) information, when applicable.
              - …
            - `price` integer, required — Shipping price for the item in cents. Does not account for the whole order's shipping price.
            - `listPrice` integer, required — Item's price list for a specific trade policy.
            - `tax` integer, required — Tax in cents, when applicable.
            - `pickupStoreInfo` PickupStoreInfoV2, required — Information about a loading dock that was transformed into a [pickup point](https://help.vtex.com/en/tutorial/pickup-points--2fljn6wLjn8M4lJHA6HP3R).
              - …
            - `pickupPointId` string, nullable, required — Pickup point ID is the unique identifier of the [pickup point](https://help.vtex.com/en/tutorial/pickup-points--2fljn6wLjn8M4lJHA6HP3R) related to the SLA.
            - `pickupDistance` number, nullable, required — Distance in kilometers between the pickup point and the customer's address. The distance is measured as a straight line.
            - `polygonName` string, nullable, required — Name of the [polygon](https://help.vtex.com/en/tutorial/registering-geolocation/) associated with the shipping policy.
            - `transitTime` string, nullable, required — Duration in business days of the time the [carrier](https://help.vtex.com/en/tutorial/carriers-on-vtex--7u9duMD5UQa2QQwukAWMcE) takes in transit to fulfill the order. For example, three business days is represented as `3bd`.
          - `shipsTo` string[], required — List of countries of the order modification shipping address.
          - `itemId` string, required — Replacing item's SKU ID, which is a unique numerical identifier.
          - `deliveryChannels` DeliveryChannel[], required — Array with the delivery channels associated with the trade policy.
            - `id` string, required — Order modifications shipping type, which can be `pickup-in-point` for [pickup point](https://help.vtex.com/en/tutorial/pickup-points--2fljn6wLjn8M4lJHA6HP3R), and `delivery` for delivery.
          - `price` integer, required — Replacing item's final price, calculated in cents.
          - `listPrice` integer, required — Replacing item's price list, calculated in cents.
          - `shippingEstimate` string, nullable, required — Replacing item's shipping estimate date. The value is in UTC ISO 8601 format `yyyy-mm-ddThh:mm:ss.sssZ`.
          - `dockEstimate` string, nullable, required — Replacing item's estimate duration of the [loading dock](https://help.vtex.com/en/tutorial/loading-dock--5DY8xHEjOLYDVL41Urd5qj) time. For instance, one business day is represented as `1bd`.
          - `shippingEstimateDate` string, nullable, required — Replacing item's total shipping duration estimated in days. For instance, three business days are represented as `3bd`.
          - `lockTTL` string, nullable, required — Logistics [reservation](https://help.vtex.com/en/tutorial/how-does-reservation-work--tutorials_92) waiting time of the SLA. For instance, one business day is represented as `1bd`.
          - `deliveryCompany` string, nullable, required — [Carrier](https://help.vtex.com/en/tutorial/carriers-on-vtex--7u9duMD5UQa2QQwukAWMcE) company's name.
          - `polygonName` string, nullable, required — Name of the [polygon](https://help.vtex.com/en/tutorial/registering-geolocation/) associated with the shipping policy.
          - `transitTime` string, nullable, required — Duration in business days of the time the [carrier](https://help.vtex.com/en/tutorial/carriers-on-vtex--7u9duMD5UQa2QQwukAWMcE) takes in transit to fulfill the order. For example, three business days are represented as `3bd`.
          - `sellingPrice` integer, required — Change item's selling price.
          - `deliveryIds` DeliveryIdV2[], required — Array with delivery information.
            - `courierId` string, required — ID of the [shipping policy](https://help.vtex.com/en/tutorial/shipping-policy--tutorials_140).
            - `warehouseId` string, required — ID of the [warehouse](https://help.vtex.com/tutorial/warehouse--6oIxvsVDTtGpO7y6zwhGpb).
            - `dockId` string, required — ID of the [loading dock](https://help.vtex.com/pt/tutorial/doca--5DY8xHEjOLYDVL41Urd5qj).
            - `courierName` string, required — Name of the [shipping policy](https://help.vtex.com/en/tutorial/shipping-policy--tutorials_140).
            - `quantity` integer, required — Quantity of items.
            - `kitItemDetails` string[], required
            - `accountCarrierName` string, nullable, required — Name of the account's [carrier](https://help.vtex.com/en/tutorial/carriers-on-vtex--7u9duMD5UQa2QQwukAWMcE).
          - `deliveryWindow` string, nullable, required — Order modification [scheduled delivery](https://help.vtex.com/en/tutorial/scheduled-delivery--22g3HAVCGLFiU7xugShOBi) information, when applicable.
          - `pickupPointId` string, nullable, required — ID of the [pickup point](https://help.vtex.com/en/tutorial/pickup-points--2fljn6wLjn8M4lJHA6HP3R).
          - `pickupStoreInfo` PickupStoreInfoV2, required — Information about a loading dock that was transformed into a [pickup point](https://help.vtex.com/en/tutorial/pickup-points--2fljn6wLjn8M4lJHA6HP3R).
            - `isPickupStore` boolean, nullable, required — This field is related to converting a loading dock into a pickup point. It should always correspond to `false` because it has been deprecated.
            - `friendlyName` string, nullable, required — Name of the loading dock converted to pickup point to be displayed at checkout. This field has been deprecated.
            - `address` string, nullable, required — Address of the loading dock converted to pickup point. This field has been deprecated.
            - `additionalInfo` string, nullable, required — Additional information about the loading dock converted to pickup point. This field has been deprecated.
            - `dockId` string, nullable, required — ID of the loading dock converted to pickup point. This field has been deprecated.
          - `pickupDistance` number, nullable, required — Distance in kilometers between the pickup point and the customer's address. The distance is measured as a straight line.
      - `clientProfileData` object[]
        - `firstName` string — Customer's first name.
        - `lastName` string — Customer's last name.
        - `documentType` string — Type of the document informed by the customer.
        - `document` string — Document number informed by the customer.
        - `phone` string — Customer's phone number.
        - `corporateName` string — If it's a legal entity, here goes the company name.
        - `tradeName` string — If it's a legal entity, here goes the trade name.
        - `corporateDocument` string — If it's a legal entity, here goes the corporate document.
        - `stateInscription` string — If it's a legal entity, here goes the state inscription.
        - `corporatePhone` string — If it's a legal entity, here goes the company phone.
        - `isCorporate` boolean — It has the value `true` if it's a legal entity.
  - `date` string, required — Date and time of the request. The value is in UTC ISO 8601 format `yyyy-mm-ddThh:mm:ss.sssZ`.
  - `origin` OriginV2, required — Object containing information about the order origin.
    - `account` string, required — Name of the account where the order was made.
    - `orderId` string, required — Order ID is a unique code that identifies an order.
    - `component` string, required — Component information.
  - `settings` ChangeOrderSettingsResponse, required — Object with all VTEX account settings related to the **Order modifications** feature.
    - `paymentConfiguration` object — [Order modifications](https://help.vtex.com/en/tutorial/how-change-order-works-beta--56TO0bOFXsfmpc7YZ3wIUZ) payment configurations.
      - `customPaymentSystemsAllowed` string[] — List of custom payment system IDs configured for the VTEX account.
    - `rolloutConfiguration` object — **Order modifications** settings regarding VTEX Admin, [Orders API](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes?endpoint=patch-/api/order-system/orders/-changeOrderId-/changes) and **My Account** feature.
      - `usingDefaultBehavior` boolean — Defines if the **Order modifications** configurations are the default behaviour (`true`) or if the account made customizations to it (`false`). Subaccounts will have the same configurations as the main account.
      - `enableApi` boolean — Defines if the account enabled the [Order modifications API](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) (`true`) or not (`false`). The account can only use the [Order modifications via VTEX Admin](https://help.vtex.com/en/tutorial/how-to-change-orders-beta--7btlG91rb6sHpW1dkd2kBw) or [via API](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) if this field is set to `true`.
      - `enableAdminOrders` object — Object about enabling the [Order modifications feature via VTEX Admin](https://help.vtex.com/en/tutorial/how-to-change-orders-beta--7btlG91rb6sHpW1dkd2kBw).
        - `enabledWorkspaces` string[] — List with the workspaces' names that have the **Order modifications** feature enabled via VTEX Admin.
      - `enableMyOrders` object — Object about enabling the **Order modifications** feature via [My Account](https://help.vtex.com/en/tutorial/how-my-account-works--2BQ3GiqhqGJTXsWVuio3Xh).
        - `enabledWorkspaces` string[] — List with the workspace names that have the **Order modifications** feature enabled via **My Account**.
    - `pipelineConfiguration` object — **Order modifications** settings related to taxes and shipping calculation.
      - `enableTaxHubRecalculation` boolean — Defines if the tax calculation is enabled for **Order modifications** (`true`) or not (`false`).
      - `compensateShippingChanges` boolean — Defines if orders changed will have zero shipping cost (`true`) or not (`false`). Merchants usually enable this configuration to change only items and prices, without impacting the orders original freight costs.
      - `enablePromotionRecalculation` boolean — Defines if the promotion recalculation is enabled for **Order modifications** (`true`) or not (`false`).
      - `enableNativeTaxRecalculation` boolean — Defines if the native tax recalculation is enabled for **Order modifications** (`true`) or not (`false`).

## Changes

> 62 revisions in range; 1 could not be searched.

- **2026-07-24** `3713706cdfe3` — 1 breaking, 3 info
  - removed the required property `settings/customPaymentSystemsAllowed` from the response with the `202` status
  - added the optional property `settings/paymentConfiguration` to the response with the `202` status
  - added the optional property `settings/pipelineConfiguration` to the response with the `202` status
  - added the optional property `settings/rolloutConfiguration` to the response with the `202` status
- **2026-07-24** `09925ac90abc` — 1 info
  - added the new optional request property `settings`
- **2026-06-16** `62f0cb2bad6c` — 1 breaking
  - the `replace/items/from/items/items/sellingPrice` response's property type/format changed from `string`/`` to `integer`/`` for status `202`
- **2026-01-23** `20f8898bfce5` — 2 info
  - added the new optional request property `replace/items/from/customData`
  - added the new optional request property `replace/items/to/customData`

[Change history](https://skmtc.dev/vtex/apis/orders-api/changes/api/order-system/orders/:changeOrderId/changes/patch.md)

---

[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)