To evolve the VTEX platform for order modifications, we are launching Order modifications, a more complete and flexible solution that provides a new experience in the VTEX Admin.

After interactions between our engineering team, clients, and partners, 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 Order modifications.

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 Order modifications and their recommendations.

Order modifications 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 modify orders through the VTEX Admin, the updated interfaces will be immediately available for you to use Order modifications 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 Order modifications, the Create order modifications 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 modifications operation. This identifier will later be used in some of the endpoints. All the Order modifications endpoints are:

• Create order modifications
• Preview order modifications
• Get order modifications details
• Get order modifications history
• Retry order modifications
• Cancel order modifications
• Update Order modifications settings
• Get Order modifications settings

After changing the order using the Create order modifications endpoint, for new requests to the Order modifications 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
PollingLow complexity

| After the order modifications operation, a unique code, the requestId, is generated to identify the order modifications. You can use it to follow the details of the request through the Get order modifications details endpoint. In this endpoint, once the request has been changed, the response body property finished is set to true.

In addition, Get order modification details can also be used to obtain information about failures and errors that resulted in the eventual cancellation of the order modifications operation, as will be described in the section Requests with errors and failures.

| | PreviewMedium complexity

| Before making a request to Create order modifications, the integration can make a preview that will result in a response body identical to the modification request. To do so, use the same request body in the request to the Preview order modifications endpoint.

This preview is a simulated modification and does not generate any real modifications to the order. Using Preview order modifications is useful for obtaining the total values associated with the order modifications 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 modifications, the integration can proceed with the request to Create order modifications to modify the order.

Then, the integration can be adapted to scenarios such as:

• Optimistic scenario: The validation data obtained by simulating the modifications covers most of the 200 OK success scenarios.
• Polling implementation: Mentioned above.

|

Order modifications maintains some attributes of the previous solution, but others have been created or changes 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 modifications made. As the system automatically calculates the modifications (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 Order modifications:

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 modify existing items, you can modify other fields to override the information for an item being modified. 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 modified in the order. They used to send this value via the discountValue or incrementValue attributes, depending on whether the modifications was an increase or decrease in price.
• Now: The system provides item information and automatically calculates the final order amount after the modifications. Users only need to enter the minimum information required and no longer calculate the final order amount, which reduces potential errors.

When an error or failure occurs in Order modifications, information about the processing can be obtained from the Get order modifications 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 modification request is canceled, and the reason for the error can be found using the Get order modifications 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 modification requested exceeds the limit value set for canceling orders.

This section gathers commonly asked questions from clients and partners who use Order modifications:

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

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

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

4 - How do promotions work in Order modifications?

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 modifications 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 modifications endpoint allows the user to simulate the order modifications to be made with Create order modifications, 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 modified 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 modifications and use it in a request to Create order modifications, 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 modified 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 modify the order manually with Create order modifications 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 modifications endpoint also allows you to use the priceTag attribute of an existing promotion and change its value when modifying the order.

The statuses canceling and canceled mean that the order modification 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 modifications or Preview order modifications endpoints. Learn more in the section Requests with errors and failures.

Help Center	Developer Portal
Modifying orders in the VTEX Admin: How Order modifications works How to modify orders

| Modifying orders via API:

• Create order modifications
• Preview order modifications
• Get order modifications details
• Get order modifications history
• Retry order modifications
• Cancel order modifications

|