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

# Preview order modifications

`POST /api/order-system/orders/{changeOrderId}/changes/preview`

This endpoint allows you to simulate an order modification and preview what the real modification will look like if you use the [Create order modifications](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) endpoint. A preview is especially useful for more complex scenarios, such as orders with multiple items and combinations of change operations — add, remove, and replace. Ensuring you get the desired results before making the actual modification helps prevent mistakes.

 ## Tax and promotion recalculation 

 We recommend using this endpoint to preview an order modification for items with promotions or tax recalculation. You can use the fields in the `pipelineConfiguration` object to preview an order's discount and native taxes for rates and benefits. This way, you can validate the financial impact before modifying an order.

The request body is the same one to be used in the [Create order modifications](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) endpoint, and the response body of a successful request provides a preview of the order modifications effect.

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

- `an` string, required

## Headers

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

## Request body

- object
  - `reason` string, required — Reason why you wish to modify the 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[], required — Name of the change operation you are performing, which can be `replace`, `add` or `remove`. If you want, you can combine all change operations in a single 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 `200`

OK

- object
  - `reason` string, required — Reason why you wish to modify the 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).
  - `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 is the order total price considering that price modifications might have been made. The value is in cents.
  - `totals` object[], required — Array containing total costs information.
    - `id` string — Changing price type, for example the item price or shipping costs.
    - `name` string — Changing price name.
    - `value` number — Changing price value in cents.
  - `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` object[], required — Array with information about the `replace` operation, when applicable.
    - `from` From2, required — What the order is changing from.
      - `paymentData` PaymentDataV2, required — Payment data object.
        - `transactions` string[], required — Information about financial transactions.
      - `items` Item4[], required — Items information from before the order change.
        - `id` string, required — SKU ID of the item.
        - `quantity` integer, required — Quantity of items been replaced.
        - `price` string, nullable, required — Item's shipping price. It does not account for the whole order's shipping price and is presented in cents.
        - `measurementUnit` string, nullable, required — Item's measurement unit. For example, `kg` for kilograms or `un` for unitary items.
        - `unitMultiplier` integer, required — Item's unit multiplier.
        - `sellingPrice` integer, required — Item's selling price.
        - `name` string, nullable, required — Item's name.
        - `detailUrl` string, nullable, required — Item's URL slug.
        - `imageUrl` string, nullable, required — Item's image URL slug.
      - `shippingData` ShippingData3, required
        - `logisticsInfo` LogisticsInfo2[], 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.
          - `slas` SlaV2[], required — Information on Service Level Agreement (SLA) of the order modifications.
            - `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 modifications 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 — Item's final price, calculated in cents.
          - `listPrice` integer, required — Item's price list, calculated in cents.
          - `shippingEstimate` string, nullable, required — Item's shipping estimate date. The value is in UTC ISO 8601 format `yyyy-mm-ddThh:mm:ss.sssZ`.
          - `dockEstimate` string, nullable, required — 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 — 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 modifications [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.
    - `to` To2, required
      - `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` ShippingData3, required
        - `logisticsInfo` LogisticsInfo2[], 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.
          - `slas` SlaV2[], required — Information on Service Level Agreement (SLA) of the order modifications.
            - `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 modifications 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 — Item's final price, calculated in cents.
          - `listPrice` integer, required — Item's price list, calculated in cents.
          - `shippingEstimate` string, nullable, required — Item's shipping estimate date. The value is in UTC ISO 8601 format `yyyy-mm-ddThh:mm:ss.sssZ`.
          - `dockEstimate` string, nullable, required — 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 — 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 modifications [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.
  - `date` string, required — Date and time of the request in UTC ISO 8601 format, as in `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** `9ee2b2a5024c` — 1 info
  - added the new optional request property `settings`
- **2026-07-23** `a1243cf04a05` — 1 breaking, 3 info
  - removed the required property `settings/customPaymentSystemsAllowed` from the response with the `200` status
  - added the optional property `settings/paymentConfiguration` to the response with the `200` status
  - added the optional property `settings/pipelineConfiguration` to the response with the `200` status
  - added the optional property `settings/rolloutConfiguration` to the response with the `200` status
- **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 `200`
- **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/preview/post.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)