EDU-18068 - Update order modifications description#1716
Open
mariananantua wants to merge 2 commits into
Open
Conversation
mariananantua
force-pushed
the
improve-info-on-change-settings
branch
from
07a8b24 to
d905c04
Compare
|
Thanks for your contribution. The .json file will be checked now with Spectral. |
julia-rabello
requested changes
May 29, 2026
| "summary": "Create order modifications", | ||
| "operationId": "Createchange", | ||
| "description": "[Order modifications](https:\/\/help.vtex.com\/en\/tutorial\/how-change-order-works-beta--56TO0bOFXsfmpc7YZ3wIUZ) 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. \r\nThe possible order modifications operations you can perform are the following:\r\n- **Add:** Adding items, quantity, or product weight.\r\n- **Remove:** Removing a part of items or the total quantity.\r\n- **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. \r\n\r\n>❗ 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.\r\n\r\n >⚠️ The Order modifications feature isn't applicable to the Catalog API - Seller Portal. \r\n\r\n>❗ 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. \r\n\r\nThe next sections are listed below:\r\n- Number of modifications per order \r\n- Acceptable order status for modifications \r\n- Order modifications and price \r\n- Combining multiple operations \r\n\r\n## Number of modifications per order\r\nBesides 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.\r\n\r\nEach 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.\r\n\r\n## Acceptable order status for modifications\r\nYou 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:\r\n- `handling`\r\n- `waiting-for-fulfillment` \r\n- `ready for invoicing` \r\n\r\nIt is not possible to modify an order when the payment transaction is complete.\r\n\r\n## Order modifications and price\r\nWhen 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:\r\n- Item value\r\n- Total value \r\n\r\n**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. \r\n>⚠️ 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. \r\n\r\nFor 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`. \r\n\r\n## Order modifications and payment transaction flow \r\n\r\nAn 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:\r\n\r\n- The order's [payment method](https://help.vtex.com/en/tutorial/difference-between-payment-methods-and-payment-conditions--3azJenhGFyUy2gsocms42Q) is a credit card.\r\n- The settlement occurs before the order is invoiced.\r\n- The payment connector is configured to allow partial refunds.\r\n\r\n> Currently, [Adyen](https://help.vtex.com/en/tutorial/configuring-payment-with-adyenv3--7xAz67E2Eg63LWCQNjVdwv) is the only payment connector that supports that operation.\r\n\r\nIf the order modification increases or decreases the cost for the customer, the platform has the following behavior:\r\n\r\n- **Smaller price after order modification:**\r\n - 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.\r\n - If the payment hasn't been settled, an automatic notification is sent to the payment gateway to change the order's total amount.\r\n- **Higher price after order modification:** An automatic notification is sent to the payment gateway to require the customer to pay for the additional cost.\r\n\r\n## Combining multiple operations\r\nYou can use this endpoint to make a single change operation or combine them in the same request. See some examples below.\r\n\r\n### Adding request body example:\r\n\r\n```json\r\n{\r\n \"add\": {\r\n \"items\": [\r\n {\r\n \"id\": \"8\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"un\",\r\n \"unitMultiplier\": 1\r\n }\r\n ]\r\n }\r\n}\r\n```\r\n\r\n### Removing request body example:\r\n\r\n```json\r\n{\r\n \"reason\": \"The client wants to remove a product.\",\r\n \"remove\": {\r\n \"items\": [\r\n {\r\n \"id\": \"8\",\r\n \"quantity\": 2,\r\n \"measurementUnit\": \"un\",\r\n \"unitMultiplier\": 1\r\n }\r\n ]\r\n }\r\n}\r\n```\r\n\r\n### Replacing request body example:\r\n```json\r\n{\r\n \"reason\": \"The client wants to increase the product weight.\",\r\n \"replace\": [\r\n {\r\n \"from\": {\r\n \"items\": [\r\n {\r\n \"id\": \"1\",\r\n \"quantity\": 1\r\n }\r\n ]\r\n },\r\n \"to\": {\r\n \"items\": [\r\n {\r\n \"id\": \"2\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"kg\",\r\n \"unitMultiplier\": 1.0\r\n }\r\n ],\r\n \"shippingData\": {\r\n \"logisticsInfo\": [\r\n {\r\n \"itemIndex\": 0,\r\n \"selectedSla\": \"Normal\",\r\n \"selectedDeliveryChannel\": \"delivery\",\r\n \"addressId\": \"12334048475146857\",\r\n \"price\": 1000\r\n }\r\n ]\r\n }\r\n }\r\n }\r\n ]\r\n}\r\n```\r\n\r\n\r\n### Adding, removing and replacing request body example:\r\n\r\n\r\n```json\r\n{\r\n \"reason\": \"The client wants to add, remove and replace a weighable product.\",\r\n \"manualDiscountValue\": 0,\r\n \"add\": {\r\n \"items\": [\r\n {\r\n \"id\": \"8\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"un\",\r\n \"unitMultiplier\": 1\r\n }\r\n ]\r\n },\r\n \"remove\": {\r\n \"items\": [\r\n {\r\n \"id\": \"31\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"un\",\r\n \"unitMultiplier\": 1\r\n }\r\n ]\r\n },\r\n \"replace\": [\r\n {\r\n \"from\": {\r\n \"items\": [\r\n {\r\n \"id\": \"1\",\r\n \"quantity\": 1\r\n }\r\n ]\r\n },\r\n \"to\": {\r\n \"items\": [\r\n {\r\n \"id\": \"2\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"kg\",\r\n \"unitMultiplier\": 1.0\r\n }\r\n ],\r\n \"shippingData\": {\r\n \"logisticsInfo\": [\r\n {\r\n \"itemIndex\": 0,\r\n \"selectedSla\": \"Normal\",\r\n \"selectedDeliveryChannel\": \"delivery\",\r\n \"addressId\": \"12334048475146857\",\r\n \"price\": 1000\r\n }\r\n ]\r\n }\r\n }\r\n }\r\n ]\r\n}\r\n```\r\n\r\n## Permissions\r\n\r\nAny 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:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Checkout | CheckoutResources | **Orders Full Access** |\r\n| OMS | OMS access | **Cancel order** |\r\n| OMS | OMS access | **Change order** |\r\n\r\nYou 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):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Checkout Admin | Orders Full Access |\r\n| OMS - Full access | <p>Cancel order<\/p><p>Change order<\/p> |\r\n| IntegrationProfile - Fulfillment Oms | <p>Cancel order<\/p><p>Change order<\/p> |\r\n| IntegrationProfile - Fulfillment Gateway | Cancel order |\r\n| IntegrationProfile - Fulfillment Gateway Oms | <p>Cancel order<\/p><p>Change order<\/p> |\r\n| inStore Sales Person | <p>Cancel order<\/p><p>Change order<\/p> |\r\n\r\n>\u2757 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).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).", | ||
| "description": "[Order modifications](https:\/\/help.vtex.com\/en\/tutorial\/how-change-order-works-beta--56TO0bOFXsfmpc7YZ3wIUZ) 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. \r\nThe possible order modifications operations you can perform are the following:\r\n- **Add:** Adding items, quantity, or product weight.\r\n- **Remove:** Removing a part of items or the total quantity.\r\n- **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. \r\n\r\n>❗ 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.\r\n\r\n >⚠️ The Order modifications feature isn't applicable to the Catalog API - Seller Portal. \r\n\r\n>❗ 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. \r\n\r\nThe next sections are listed below:\r\n- Number of modifications per order \r\n- Acceptable order status for modifications \r\n- Order modifications and price \r\n- Combining multiple operations \r\n\r\n## Number of modifications per order\r\nBesides 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.\r\n\r\nEach 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.\r\n\r\n## Acceptable order status for modifications\r\nYou 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:\r\n- `handling`\r\n- `waiting-for-fulfillment` \r\n- `ready for invoicing` \r\n\r\nIt is not possible to modify an order when the payment transaction is complete.\r\n\r\n## Order modifications and price\r\nWhen 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:\r\n- Item value\r\n- Total value \r\n\r\n**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. \r\n>⚠️ 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. \r\n\r\nFor 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`. \r\n\r\n## Order modifications and payment transaction flow \r\n\r\nAn 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:\r\n\r\n- The order's [payment method](https://help.vtex.com/en/tutorial/difference-between-payment-methods-and-payment-conditions--3azJenhGFyUy2gsocms42Q) is a credit card.\r\n- The settlement occurs before the order is invoiced.\r\n- The payment connector is configured to allow partial refunds.\r\n\r\n> Currently, [Adyen](https://help.vtex.com/en/tutorial/configuring-payment-with-adyenv3--7xAz67E2Eg63LWCQNjVdwv) is the only payment connector that supports that operation.\r\n\r\nIf the order modification increases or decreases the cost for the customer, the platform has the following behavior:\r\n\r\n- **Smaller price after order modification:**\r\n - 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.\r\n - If the payment hasn't been settled, an automatic notification is sent to the payment gateway to change the order's total amount.\r\n- **Higher price after order modification:** An automatic notification is sent to the payment gateway to require the customer to pay for the additional cost.\r\n\r\n ## Order modifications settings\r\n 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.\r\n - 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. \r\n - 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. \r\n\r\n ## Combining multiple operations\r\nYou can use this endpoint to make a single change operation or combine them in the same request. See some examples below.\r\n\r\n### Adding request body example:\r\n\r\n```json\r\n{\r\n \"add\": {\r\n \"items\": [\r\n {\r\n \"id\": \"8\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"un\",\r\n \"unitMultiplier\": 1\r\n }\r\n ]\r\n }\r\n}\r\n```\r\n\r\n### Removing request body example:\r\n\r\n```json\r\n{\r\n \"reason\": \"The client wants to remove a product.\",\r\n \"remove\": {\r\n \"items\": [\r\n {\r\n \"id\": \"8\",\r\n \"quantity\": 2,\r\n \"measurementUnit\": \"un\",\r\n \"unitMultiplier\": 1\r\n }\r\n ]\r\n }\r\n}\r\n```\r\n\r\n### Replacing request body example:\r\n```json\r\n{\r\n \"reason\": \"The client wants to increase the product weight.\",\r\n \"replace\": [\r\n {\r\n \"from\": {\r\n \"items\": [\r\n {\r\n \"id\": \"1\",\r\n \"quantity\": 1\r\n }\r\n ]\r\n },\r\n \"to\": {\r\n \"items\": [\r\n {\r\n \"id\": \"2\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"kg\",\r\n \"unitMultiplier\": 1.0\r\n }\r\n ],\r\n \"shippingData\": {\r\n \"logisticsInfo\": [\r\n {\r\n \"itemIndex\": 0,\r\n \"selectedSla\": \"Normal\",\r\n \"selectedDeliveryChannel\": \"delivery\",\r\n \"addressId\": \"12334048475146857\",\r\n \"price\": 1000\r\n }\r\n ]\r\n }\r\n }\r\n }\r\n ]\r\n}\r\n```\r\n\r\n\r\n### Adding, removing and replacing request body example:\r\n\r\n\r\n```json\r\n{\r\n \"reason\": \"The client wants to add, remove and replace a weighable product.\",\r\n \"manualDiscountValue\": 0,\r\n \"add\": {\r\n \"items\": [\r\n {\r\n \"id\": \"8\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"un\",\r\n \"unitMultiplier\": 1\r\n }\r\n ]\r\n },\r\n \"remove\": {\r\n \"items\": [\r\n {\r\n \"id\": \"31\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"un\",\r\n \"unitMultiplier\": 1\r\n }\r\n ]\r\n },\r\n \"replace\": [\r\n {\r\n \"from\": {\r\n \"items\": [\r\n {\r\n \"id\": \"1\",\r\n \"quantity\": 1\r\n }\r\n ]\r\n },\r\n \"to\": {\r\n \"items\": [\r\n {\r\n \"id\": \"2\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"kg\",\r\n \"unitMultiplier\": 1.0\r\n }\r\n ],\r\n \"shippingData\": {\r\n \"logisticsInfo\": [\r\n {\r\n \"itemIndex\": 0,\r\n \"selectedSla\": \"Normal\",\r\n \"selectedDeliveryChannel\": \"delivery\",\r\n \"addressId\": \"12334048475146857\",\r\n \"price\": 1000\r\n }\r\n ]\r\n }\r\n }\r\n }\r\n ]\r\n}\r\n```\r\n\r\n## Permissions\r\n\r\nAny 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:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Checkout | CheckoutResources | **Orders Full Access** |\r\n| OMS | OMS access | **Cancel order** |\r\n| OMS | OMS access | **Change order** |\r\n\r\nYou 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):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Checkout Admin | Orders Full Access |\r\n| OMS - Full access | <p>Cancel order<\/p><p>Change order<\/p> |\r\n| IntegrationProfile - Fulfillment Oms | <p>Cancel order<\/p><p>Change order<\/p> |\r\n| IntegrationProfile - Fulfillment Gateway | Cancel order |\r\n| IntegrationProfile - Fulfillment Gateway Oms | <p>Cancel order<\/p><p>Change order<\/p> |\r\n| inStore Sales Person | <p>Cancel order<\/p><p>Change order<\/p> |\r\n\r\n>\u2757 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).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).", |
Contributor
There was a problem hiding this comment.
Suggested change
| "description": "[Order modifications](https:\/\/help.vtex.com\/en\/tutorial\/how-change-order-works-beta--56TO0bOFXsfmpc7YZ3wIUZ) 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. \r\nThe possible order modifications operations you can perform are the following:\r\n- **Add:** Adding items, quantity, or product weight.\r\n- **Remove:** Removing a part of items or the total quantity.\r\n- **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. \r\n\r\n>❗ 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.\r\n\r\n >⚠️ The Order modifications feature isn't applicable to the Catalog API - Seller Portal. \r\n\r\n>❗ 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. \r\n\r\nThe next sections are listed below:\r\n- Number of modifications per order \r\n- Acceptable order status for modifications \r\n- Order modifications and price \r\n- Combining multiple operations \r\n\r\n## Number of modifications per order\r\nBesides 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.\r\n\r\nEach 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.\r\n\r\n## Acceptable order status for modifications\r\nYou 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:\r\n- `handling`\r\n- `waiting-for-fulfillment` \r\n- `ready for invoicing` \r\n\r\nIt is not possible to modify an order when the payment transaction is complete.\r\n\r\n## Order modifications and price\r\nWhen 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:\r\n- Item value\r\n- Total value \r\n\r\n**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. \r\n>⚠️ 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. \r\n\r\nFor 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`. \r\n\r\n## Order modifications and payment transaction flow \r\n\r\nAn 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:\r\n\r\n- The order's [payment method](https://help.vtex.com/en/tutorial/difference-between-payment-methods-and-payment-conditions--3azJenhGFyUy2gsocms42Q) is a credit card.\r\n- The settlement occurs before the order is invoiced.\r\n- The payment connector is configured to allow partial refunds.\r\n\r\n> Currently, [Adyen](https://help.vtex.com/en/tutorial/configuring-payment-with-adyenv3--7xAz67E2Eg63LWCQNjVdwv) is the only payment connector that supports that operation.\r\n\r\nIf the order modification increases or decreases the cost for the customer, the platform has the following behavior:\r\n\r\n- **Smaller price after order modification:**\r\n - 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.\r\n - If the payment hasn't been settled, an automatic notification is sent to the payment gateway to change the order's total amount.\r\n- **Higher price after order modification:** An automatic notification is sent to the payment gateway to require the customer to pay for the additional cost.\r\n\r\n ## Order modifications settings\r\n 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.\r\n - 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. \r\n - 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. \r\n\r\n ## Combining multiple operations\r\nYou can use this endpoint to make a single change operation or combine them in the same request. See some examples below.\r\n\r\n### Adding request body example:\r\n\r\n```json\r\n{\r\n \"add\": {\r\n \"items\": [\r\n {\r\n \"id\": \"8\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"un\",\r\n \"unitMultiplier\": 1\r\n }\r\n ]\r\n }\r\n}\r\n```\r\n\r\n### Removing request body example:\r\n\r\n```json\r\n{\r\n \"reason\": \"The client wants to remove a product.\",\r\n \"remove\": {\r\n \"items\": [\r\n {\r\n \"id\": \"8\",\r\n \"quantity\": 2,\r\n \"measurementUnit\": \"un\",\r\n \"unitMultiplier\": 1\r\n }\r\n ]\r\n }\r\n}\r\n```\r\n\r\n### Replacing request body example:\r\n```json\r\n{\r\n \"reason\": \"The client wants to increase the product weight.\",\r\n \"replace\": [\r\n {\r\n \"from\": {\r\n \"items\": [\r\n {\r\n \"id\": \"1\",\r\n \"quantity\": 1\r\n }\r\n ]\r\n },\r\n \"to\": {\r\n \"items\": [\r\n {\r\n \"id\": \"2\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"kg\",\r\n \"unitMultiplier\": 1.0\r\n }\r\n ],\r\n \"shippingData\": {\r\n \"logisticsInfo\": [\r\n {\r\n \"itemIndex\": 0,\r\n \"selectedSla\": \"Normal\",\r\n \"selectedDeliveryChannel\": \"delivery\",\r\n \"addressId\": \"12334048475146857\",\r\n \"price\": 1000\r\n }\r\n ]\r\n }\r\n }\r\n }\r\n ]\r\n}\r\n```\r\n\r\n\r\n### Adding, removing and replacing request body example:\r\n\r\n\r\n```json\r\n{\r\n \"reason\": \"The client wants to add, remove and replace a weighable product.\",\r\n \"manualDiscountValue\": 0,\r\n \"add\": {\r\n \"items\": [\r\n {\r\n \"id\": \"8\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"un\",\r\n \"unitMultiplier\": 1\r\n }\r\n ]\r\n },\r\n \"remove\": {\r\n \"items\": [\r\n {\r\n \"id\": \"31\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"un\",\r\n \"unitMultiplier\": 1\r\n }\r\n ]\r\n },\r\n \"replace\": [\r\n {\r\n \"from\": {\r\n \"items\": [\r\n {\r\n \"id\": \"1\",\r\n \"quantity\": 1\r\n }\r\n ]\r\n },\r\n \"to\": {\r\n \"items\": [\r\n {\r\n \"id\": \"2\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"kg\",\r\n \"unitMultiplier\": 1.0\r\n }\r\n ],\r\n \"shippingData\": {\r\n \"logisticsInfo\": [\r\n {\r\n \"itemIndex\": 0,\r\n \"selectedSla\": \"Normal\",\r\n \"selectedDeliveryChannel\": \"delivery\",\r\n \"addressId\": \"12334048475146857\",\r\n \"price\": 1000\r\n }\r\n ]\r\n }\r\n }\r\n }\r\n ]\r\n}\r\n```\r\n\r\n## Permissions\r\n\r\nAny 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:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Checkout | CheckoutResources | **Orders Full Access** |\r\n| OMS | OMS access | **Cancel order** |\r\n| OMS | OMS access | **Change order** |\r\n\r\nYou 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):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Checkout Admin | Orders Full Access |\r\n| OMS - Full access | <p>Cancel order<\/p><p>Change order<\/p> |\r\n| IntegrationProfile - Fulfillment Oms | <p>Cancel order<\/p><p>Change order<\/p> |\r\n| IntegrationProfile - Fulfillment Gateway | Cancel order |\r\n| IntegrationProfile - Fulfillment Gateway Oms | <p>Cancel order<\/p><p>Change order<\/p> |\r\n| inStore Sales Person | <p>Cancel order<\/p><p>Change order<\/p> |\r\n\r\n>\u2757 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).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).", | |
| "description": "[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. \r\nThe possible order modifications operations you can perform are the following:\r\n- **Add:** Adding items, quantity, or product weight.\r\n- **Remove:** Removing a part of items or the total quantity.\r\n- **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. \r\n\r\n>\u2757 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.\r\n\r\n >\u26A0\uFE0F The Order modifications feature isn't applicable to the Catalog API - Seller Portal. \r\n\r\n>\u2757 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. \r\n\r\nThe next sections are listed below:\r\n- Number of modifications per order \r\n- Acceptable order status for modifications \r\n- Order modifications and price \r\n- Combining multiple operations \r\n\r\n## Number of modifications per order\r\nBesides 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.\r\n\r\nEach 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.\r\n\r\n## Acceptable order status for modifications\r\nYou 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:\r\n- `handling`\r\n- `waiting-for-fulfillment` \r\n- `ready for invoicing` \r\n\r\nIt is not possible to modify an order when the payment transaction is complete.\r\n\r\n## Order modifications and price\r\nWhen 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:\r\n- Item value\r\n- Total value \r\n\r\n**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. \r\n>\u26A0\uFE0F 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. \r\n\r\nFor 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`. \r\n\r\n## Order modifications and payment transaction flow \r\n\r\nAn 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:\r\n\r\n- The order's [payment method](https:\/\/help.vtex.com\/en\/tutorial\/difference-between-payment-methods-and-payment-conditions--3azJenhGFyUy2gsocms42Q) is a credit card.\r\n- The settlement occurs before the order is invoiced.\r\n- The payment connector is configured to allow partial refunds.\r\n\r\n> Currently, [Adyen](https:\/\/help.vtex.com\/en\/tutorial\/configuring-payment-with-adyenv3--7xAz67E2Eg63LWCQNjVdwv) is the only payment connector that supports that operation.\r\n\r\nIf the order modification increases or decreases the cost for the customer, the platform has the following behavior:\r\n\r\n- **Smaller price after order modification:**\r\n - 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.\r\n - If the payment hasn't been settled, an automatic notification is sent to the payment gateway to change the order's total amount.\r\n- **Higher price after order modification:** An automatic notification is sent to the payment gateway to require the customer to pay for the additional cost.\r\n\r\n## Order modifications settings\r\n\r\nThe 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.\r\n\r\n* 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.\r\n* 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.\r\n\r\n## Combining multiple operations\r\n\r\nYou can use this endpoint to make a single change operation or combine them in the same request. See some examples below.\r\n\r\n### Adding request body example:\r\n\r\n```json\r\n{\r\n \"add\": {\r\n \"items\": [\r\n {\r\n \"id\": \"8\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"un\",\r\n \"unitMultiplier\": 1\r\n }\r\n ]\r\n }\r\n}\r\n```\r\n\r\n### Removing request body example:\r\n\r\n```json\r\n{\r\n \"reason\": \"The client wants to remove a product.\",\r\n \"remove\": {\r\n \"items\": [\r\n {\r\n \"id\": \"8\",\r\n \"quantity\": 2,\r\n \"measurementUnit\": \"un\",\r\n \"unitMultiplier\": 1\r\n }\r\n ]\r\n }\r\n}\r\n```\r\n\r\n### Replacing request body example:\r\n```json\r\n{\r\n \"reason\": \"The client wants to increase the product weight.\",\r\n \"replace\": [\r\n {\r\n \"from\": {\r\n \"items\": [\r\n {\r\n \"id\": \"1\",\r\n \"quantity\": 1\r\n }\r\n ]\r\n },\r\n \"to\": {\r\n \"items\": [\r\n {\r\n \"id\": \"2\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"kg\",\r\n \"unitMultiplier\": 1.0\r\n }\r\n ],\r\n \"shippingData\": {\r\n \"logisticsInfo\": [\r\n {\r\n \"itemIndex\": 0,\r\n \"selectedSla\": \"Normal\",\r\n \"selectedDeliveryChannel\": \"delivery\",\r\n \"addressId\": \"12334048475146857\",\r\n \"price\": 1000\r\n }\r\n ]\r\n }\r\n }\r\n }\r\n ]\r\n}\r\n```\r\n\r\n\r\n### Adding, removing and replacing request body example:\r\n\r\n\r\n```json\r\n{\r\n \"reason\": \"The client wants to add, remove and replace a weighable product.\",\r\n \"manualDiscountValue\": 0,\r\n \"add\": {\r\n \"items\": [\r\n {\r\n \"id\": \"8\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"un\",\r\n \"unitMultiplier\": 1\r\n }\r\n ]\r\n },\r\n \"remove\": {\r\n \"items\": [\r\n {\r\n \"id\": \"31\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"un\",\r\n \"unitMultiplier\": 1\r\n }\r\n ]\r\n },\r\n \"replace\": [\r\n {\r\n \"from\": {\r\n \"items\": [\r\n {\r\n \"id\": \"1\",\r\n \"quantity\": 1\r\n }\r\n ]\r\n },\r\n \"to\": {\r\n \"items\": [\r\n {\r\n \"id\": \"2\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"kg\",\r\n \"unitMultiplier\": 1.0\r\n }\r\n ],\r\n \"shippingData\": {\r\n \"logisticsInfo\": [\r\n {\r\n \"itemIndex\": 0,\r\n \"selectedSla\": \"Normal\",\r\n \"selectedDeliveryChannel\": \"delivery\",\r\n \"addressId\": \"12334048475146857\",\r\n \"price\": 1000\r\n }\r\n ]\r\n }\r\n }\r\n }\r\n ]\r\n}\r\n```\r\n\r\n## Permissions\r\n\r\nAny 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:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Checkout | CheckoutResources | **Orders Full Access** |\r\n| OMS | OMS access | **Cancel order** |\r\n| OMS | OMS access | **Change order** |\r\n\r\nYou 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):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Checkout Admin | Orders Full Access |\r\n| OMS - Full access | <p>Cancel order<\/p><p>Change order<\/p> |\r\n| IntegrationProfile - Fulfillment Oms | <p>Cancel order<\/p><p>Change order<\/p> |\r\n| IntegrationProfile - Fulfillment Gateway | Cancel order |\r\n| IntegrationProfile - Fulfillment Gateway Oms | <p>Cancel order<\/p><p>Change order<\/p> |\r\n| inStore Sales Person | <p>Cancel order<\/p><p>Change order<\/p> |\r\n\r\n>\u2757 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).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).", |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add information about order modifications settings on the Create order modifications endpoint. Refers to EDU-18068.
Types of changes
Changelog
Do not forget to update your changes to our Developer Portal's changelog. Did you create a release note?