To evolve the VTEX platform for order changes, we are launching Change order (Beta), a more complete and flexible solution that provides a new experience in the VTEX Admin.

After interactions between our engineering team, clients, and partners who have joined the beta version, we created this content with the best implementation practices and frequently asked questions. The goal is for future clients and partners to have this support material when they start using Change order (Beta).

The content is organized as follows:

• Adapting to different use cases
• Changes in the request body
• Requests with errors and failures
• Frequently Asked Questions (FAQ)

The following sections outline the main use cases for Change order (Beta) and their recommendations.

Change order (Beta) uses new templates for transactional emails (Message Center) to cover the solution's innovative features.

To customize an email template in the VTEX Admin, copy and paste the link below into your browser, replacing {accountName} with your store's account name, and then click Enter:

https://{accountName}.myvtex.com/admin/message-center/#/templates/vtexcommerce-order-changed-v2

For stores using the current version to change orders through the VTEX Admin, the updated interfaces will be immediately available for you to use Change order (Beta) once the VTEX team has installed the new solution. This includes new management features and communication tools for My Account and transactional email templates.

For stores that use our APIs, the implementation in the integration must comply with the new feature architecture.

In Change order (Beta), the Create order change endpoint works asynchronously, and the user or integration that makes the request receives a requestId from the platform, which is a unique identifier to track the order change operation. This identifier will later be used in some of the endpoints. All the Change order (Beta) endpoints are:

• Create order change
• Preview order change
• Get order change details
• Get order change history
• Retry order change
• Cancel order change
• Update Change order settings
• Get Change order settings

After changing the order using the Create order change endpoint, for new requests to the Change order (Beta) endpoints, you have the following options for the integrator:

• Polling: Low complexity.
• Preview: Medium complexity.

The table below describes each one:

Flow type	How it works
Polling Low complexity	After the change order operation, a unique code, the requestId, is generated to identify the order change. You can use it to follow the details of the request through the Get change details endpoint. In this endpoint, once the request has been changed, the response body property finished is set to true. In addition, Get change details can also be used to obtain information about failures and errors that resulted in the eventual cancellation of the change order operation, as will be described in the section Requests with errors and failures.
Preview Medium complexity	Before making a request to Create order change, the integration can make a preview that will result in a response body identical to the change request. To do so, use the same request body in the request to the Preview order change endpoint. This preview is a simulated change and does not generate any real changes to the order. Using Preview order change is useful for obtaining the total values associated with the order change being made and for validating the request details with a valid request body. After receiving a successful 200 OK response for a preview of the change, the integration can proceed with the request to Create order change to change the order. Then, the integration can be adapted to scenarios such as: Optimistic scenario: The validation data obtained by simulating the change covers most of the 200 OK success scenarios. Polling implementation: Mentioned above.

Change order (Beta) maintains some attributes of the previous solution, but others have been created or modified in terms of nomenclature and functioning. The main changes have been organized as follows:

• Manual values
• Adding and removing items
• Attributes of mandatory and optional items
• User responsibility in system automation

• Previously: The discountValue and incrementValue fields defined the value of the change being made to the order by decreasing or increasing a value, respectively. The user calculated the change value, and the result was added to or subtracted from the order total amount using these fields.

  Example: When adding a $50 item to a $100 order, the user would send the incrementValue as $50, and the system would update the order total to $150. To apply a $30 discount for the customer, the user had to send the discountValue of $30, resulting in a revised order total of $120.

• Now: The new manualDiscountValue and manualIncrementValue fields set additional manual values to be added to or subtracted from the total order amount regardless of the changes made. As the system automatically calculates the changes (considering the price and conditions when the order was placed), the user can add or subtract values using the fields mentioned.

  Example: When adding a $50 item to a $100 order, the system automatically adjusts the total to $150. Users are not required to update the amount manually. If a discount of $30 is needed, users can simply send the manualDiscountValue field as $30, resulting in a new total of $120.

• Previously: The attributes used to add and remove items from the order were the itemsAdded and itemsRemoved arrays, which contained item objects with the id, price, and quantity fields.
• Now: The attributes for adding and removing items from the order are the add and remove objects. They contain a new level that defines an object for each item via the items array.

Example of removing items in Change order (Beta):

The items in the request body need fewer mandatory attributes than before: id and quantity. The other attributes are obtained from the request or the Catalog system.

If you need to add or change existing items, you can change other fields to override the information for an item being changed. The optional fields are price, unitMultiplier, and measurementUnit. The system disregards any other fields sent in the request.

• Previously: Users had to calculate the value to be changed in the order. They used to send this value via the discountValue or incrementValue attributes, depending on whether the change was an increase or decrease in price.
• Now: The system provides item information and automatically calculates the final order amount after the change. Users only need to enter the minimum information required and no longer calculates the final order amount, which reduces potential errors.

When an error or failure occurs in Change order (Beta), information about the processing can be obtained from the Get change details endpoint via the logs attribute.

Example of logs with a processing error:

For each system failure (untreated errors), the system automatically makes new processing attempts. If the new attempts don't work, the change request is canceled, and the reason for the error can be found using the Get change details endpoint via the cancellationData attribute.

If the source of the error is the user's non-compliance with the request validation rules, the operation will be canceled automatically, and no further processing attempts will be made. In this case, the reason for the error is also communicated via cancellationData.

Example of the cancellationData object: The price change requested exceeds the limit value set for canceling orders.

This section gathers commonly asked questions from clients and partners who use Change order (Beta):

1 - How do I overwrite the price of a specific item?

2 - How do I know and change the total amount of the order before it is changed?

3 - Do I need to indicate the shipping cost, or is it automatically recalculated?

4 - How do promotions work in Change orders (Beta)?

5 - What should I do when the request leads to a canceling or canceled status?

You can apply a manual value to a specific item's price while changing its quantity to overwrite its price.

In the Create order change endpoint, the price attribute has the same function as for the order placing flow and refers to the nominal price of the item. For example, in an order with a weighable item, such as an apple, the price refers to the kilo price of apples.

Example of price overwriting on a weighable item:

The Preview order change endpoint allows the user to simulate the order change to be made with Create order change, as it uses the same request body and provides the same response body but without changing the order. The totalChangeValue attribute indicates the total value being changed in the order, either to a higher value (e.g., tax or adding items) or a lower value (e.g., manually reducing the price or removing items).

If you want the integration to handle variations in the order amount, you can use the same request body as in the Preview order change and use it in a request to Create an order change, adjusting the values of the manualIncrementValue and manualDiscountValue fields up or down respectively.

When item quantity, size, or weight changes, the shipping cost is automatically recalculated and added to the new order total.

The rule for calculating the new shipping cost follows the same conditions applied when the order was placed.

Changing the order automatically applies the same promotions and taxes that were valid for the items when the order was placed, but only replicates the conditions that were valid then. New promotions and taxes are not recalculated under the changed order conditions.

Example: In one store, there was a 'Get 3 for the price of 2' promotion. However, the customer only purchased 2 items initially and did not qualify for the discount. If the customer then decides to add one more item to the order, making it a total of 3 items purchased, they still wouldn't receive the promotion because it wasn't part of the original order.

You can inform the promotion of an item when you change the order manually with Create order change using the priceTags attribute. This is already the platform's default behavior.

Example of an item with promotions applied to the original order:

In this example, the manual discount tag used was DISCOUNT@MANUALPRICE. The equivalent for manual rates would be TAX@MANUALPRICE. The Create order change endpoint also allows you to use the priceTag attribute of an existing promotion and change its value when changing the order.

The statuses canceling and canceled mean that the order change was not processed correctly and not applied to the order, so the user can disregard the request. Failures and errors can occur due to:

• User non-compliance with the request validation rules.
• Exceeded number of automatic reprocessing attempts by the system.
• Other system processing failures.

The general recommendation is to investigate the error source and check the request body being sent from the Create order change or Preview order change endpoints. Learn more in the section Requests with errors and failures.

Help Center	Developer Portal
Changing orders in the VTEX Admin: How Change order works (Beta) How to change orders (Beta)	Changing orders via API: Create order change Preview order change Get order change details Get order change history Retry order change Cancel order change