How Order modifications works

5 min read

The Order modifications feature allows you to edit an order in different ways, either due to customer requests, product unavailability, or other reasons. These are the main order modifications that can be made:

Add: Increase the number of items or add new products.
Remove: Remove the partial or total number of items.
Weight change: Adjust the weight assigned to items.
Replace items: Replace items, including those priced by weight.
Price change: Change the order total amount.

For detailed instructions on each action, read the How to modify orders documentation. This article covers other aspects of Order modifications and is structured as follows:

Modifications through the VTEX Admin and API
General characteristics
Price changes

Modifications through the VTEX Admin and API

You can modify an order in two ways; see details in the table below:

How to modify	Description	Changeable status
Via the VTEX Admin	Modifications are made from the order details page, which can be accessed under Orders > All orders, by selecting the desired order.You can also access the order using the search bar at the top of the VTEX Admin. To do this, click the bar, select the Orders option, and use any of the following criteria: Order ID Customer name Customer email Customer document Help Center article: How to modify orders	`handling`
Via API	Modifications using the endpoints: Create order modifications Preview order modifications Get order modifications detail Get order modifications history Retry order modifications Cancel order modifications Get Order modifications settings Update Order modifications settings	`handling` `waiting-for-fulfillment` `ready for invoicing`

The order's change history is recorded on its details page in the History of changed items section. To view this information via API, use the Get order modifications history endpoint.

General characteristics

Order modifications has specific characteristics, as shown in the table below:

Characteristic	Description
Number of order modifications	There is no limit to how many times an order can be modified.
Incomplete orders	You cannot modify incomplete orders — those lacking necessary information to be processed by the VTEX platform.
Franchise accounts	You can modify orders where the seller is a franchise account.
VTEX marketplace, certified, partner and external marketplaces	Modifying orders works differently across various marketplace scenarios on VTEX: You can modify orders from stores that act as both a VTEX seller and a VTEX marketplace. You can modify Multilevel Omnichannel Inventory (MOI) orders placed on external marketplaces. You cannot modify orders placed on certified marketplaces and marketplaces partners.
Reservation	In order modifications scenarios, item reservation is automatic.
Inventory update	When you modify an order, the store's inventory is not updated automatically. The store must update the inventory in the VTEX Admin under Catalog > Inventory > Inventory Management or via API, using the Update inventory by SKU and warehouse endpoint.
License Manager permission	For a user to be able to modify orders, their role must be associated with at least one of the following Licence Manager resources: `Orders Full Access` `Change order`

Price changes

When a modification to an order item increases or decreases the original amount of the purchase, the Orders module automatically communicates with Payments as follows:

Lower price after a modification: The behavior depends on the payment status in the transaction flow.
- If the payment has already been settled (settled status), the payment gateway is notified to reverse the amount that must be returned to the customer.
- If the payment hasn't been settled yet, the gateway is notified to update the order total.
Higher price after a modification: A notification is sent to the payment gateway to request the customer to pay the additional amount.

See the table below for more information on payment and invoicing when modifying orders:

Characteristic	Description
Conditions for increasing the order amount	You can only increase the amount of an order when it meets the following criteria: The order was placed using credit card, notes payable or customer credit. The order acquirer allows transactions without the CVV code. The order acquirer allows two billing transactions for the same order. If the connector does not allow modifications for higher amounts, a new transaction will be processed for the excess value, and the transaction will not be linked to the original order.
Modifications of settled order	In the transaction flow, the order can be modified to `settled`, provided it meets the following conditions: The order was placed using a credit card. Payment is settled before the order is invoiced. The payment connector is configured to allow partial refunds. Adyen is currently the only payment connector that supports this operation. Orders with the transaction status `finished` cannot be modified.
Shared transaction between sellers and marketplace	You can modify orders with more than one seller and payment in marketplaces, i.e., in split payment scenarios.
Discounts	You cannot modify an order by applying discounts greater than or equal to the total amount of the original order.
Invoice	For invoices, order modifications behave as follows: If the order has already been invoiced in full, it can no longer be modified. Orders not yet invoiced or only partially invoiced can be modified. The amount of partial invoices for the modified order must be equal to or greater than the amount of an invoice already issued. If the total amount of the modified order is lower than the amount of an invoice that has already been issued, it cannot be modified. In general, it is the invoicing of the order that triggers payment settlement. However, this behavior is different for stores with automatic settlement configured.