From d0e19395e26f7de76165018aa4812fc1de85a8f5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mariana=20N=C3=A2ntua?= <mariananantua@gmail.com>
Date: Fri, 16 May 2025 14:47:17 -0300
Subject: [PATCH] Add info about payment transaction flow

---
 VTEX - Orders API.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/VTEX - Orders API.json b/VTEX - Orders API.json
index ab8c51ef0..e1ab6ac66 100644
--- a/VTEX - Orders API.json	
+++ b/VTEX - Orders API.json	
@@ -8128,7 +8128,7 @@
               ],
               "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\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:** 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- **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 [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-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-application-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\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:**  - 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.\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 [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-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-application-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).",
               "parameters": [
                 {
                   "name": "an",