Create order modifications
Order modifications 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. The possible order modifications operations you can perform are the following:
- Add: Adding items, quantity, or product weight.
- Remove: Removing a part of items or the total quantity.
- 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.
❗ When removing or adding items to an order, your inventory is not automatically updated. You can use the Update inventory by SKU and warehouse endpoint.
⚠️ The Order modifications feature isn't applicable to the Catalog API - Seller Portal.
❗ 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.
The next sections are listed below:
- Number of modifications per order
- Acceptable order status for modifications
- Order modifications and price
- Combining multiple operations
Number of modifications per order
Besides 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.
Each order has its modifications history, you can retrieve it using the Get order modifications history endpoint.
Acceptable order status for modifications
You can only modify an order when it is one of the following order flow status:
- handling
- waiting-for-fulfillment
- ready for invoicing
It is not possible to modify an order when the payment transaction is complete.
Order modifications and price
When 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:
- Item value
- Total value
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.
⚠️ Increasing the price of an order is allowed only when the order was paid by credit card, payable notes, cash, or credit control. In addition, the acquirer must allow transactions without the CVV code and two charging transactions in the same order.
For 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.
Order modifications and payment transaction flow
An order's transaction flow goes through various payment statuses before its conclusion. Within certain conditions, it is possible to modify settled orders. The requirements are the following:
- The order's payment method is a credit card.
- The settlement occurs before the order is invoiced.
- The payment connector is configured to allow partial refunds.
Currently, Adyen is the only payment connector that supports that operation.
If the order modification increases or decreases the cost for the customer, the platform has the following behavior:
- Smaller price after order modification:
- If the payment is marked as settled in the transaction flow, an automatic notification is sent to the payment 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.
- Higher price after order modification: An automatic notification is sent to the payment gateway to require the customer to pay for the additional cost.
Order modifications settings
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.
- If you wish to consult the current settings, run the Get Order modifications settings endpoint.
- If you wish to alter the current settings, run the Update Order modifications settings endpoint.
Combining multiple operations
You can use this endpoint to make a single change operation or combine them in the same request. See some examples below.
Adding request body example:
{
"add": {
"items": [
{
"id": "8",
"quantity": 1,
"measurementUnit": "un",
"unitMultiplier": 1
}
]
}
}
Removing request body example:
{
"reason": "The client wants to remove a product.",
"remove": {
"items": [
{
"id": "8",
"quantity": 2,
"measurementUnit": "un",
"unitMultiplier": 1
}
]
}
}
Replacing request body example:
{
"reason": "The client wants to increase the product weight.",
"replace": [
{
"from": {
"items": [
{
"id": "1",
"quantity": 1
}
]
},
"to": {
"items": [
{
"id": "2",
"quantity": 1,
"measurementUnit": "kg",
"unitMultiplier": 1.0
}
],
"shippingData": {
"logisticsInfo": [
{
"itemIndex": 0,
"selectedSla": "Normal",
"selectedDeliveryChannel": "delivery",
"addressId": "12334048475146857",
"price": 1000
}
]
}
}
}
]
}
Adding, removing and replacing request body example:
{
"reason": "The client wants to add, remove and replace a weighable product.",
"manualDiscountValue": 0,
"add": {
"items": [
{
"id": "8",
"quantity": 1,
"measurementUnit": "un",
"unitMultiplier": 1
}
]
},
"remove": {
"items": [
{
"id": "31",
"quantity": 1,
"measurementUnit": "un",
"unitMultiplier": 1
}
]
},
"replace": [
{
"from": {
"items": [
{
"id": "1",
"quantity": 1
}
]
},
"to": {
"items": [
{
"id": "2",
"quantity": 1,
"measurementUnit": "kg",
"unitMultiplier": 1.0
}
],
"shippingData": {
"logisticsInfo": [
{
"itemIndex": 0,
"selectedSla": "Normal",
"selectedDeliveryChannel": "delivery",
"addressId": "12334048475146857",
"price": 1000
}
]
}
}
}
]
}
Permissions
Any user or API key must have at least one of the appropriate License Manager resources 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:
| Product | Category | Resource |
|---|---|---|
| Checkout | CheckoutResources | Orders Full Access |
| OMS | OMS access | Cancel order |
| OMS | OMS access | Change order |
You can create a custom role with that resource or use one of the following predefined roles:
| Role | Resource |
|---|---|
| Checkout Admin | Orders Full Access |
| OMS - Full access | <p>Cancel order</p><p>Change order</p> |
| IntegrationProfile - Fulfillment Oms | <p>Cancel order</p><p>Change order</p> |
| IntegrationProfile - Fulfillment Gateway | Cancel order |
| IntegrationProfile - Fulfillment Gateway Oms | <p>Cancel order</p><p>Change order</p> |
| inStore Sales Person | <p>Cancel order</p><p>Change order</p> |
❗ Assigning a predefined role to users or application keys usually grants permission to multiple License Manager resources. 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.
To learn more about machine authentication at VTEX, see Authentication overview.
Path parameters
Order ID of the order you wish to modify.
Query parameters
Name of the VTEX account that created the order.
Headers
Type of the content being sent.
HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
Request body
Example request
{
"replace": [
{
"to": {
"customData": {
"customFields": [
{
"fields": [
{
"name": "desktop",
"value": "DSK-NEW"
}
]
}
]
}
}
}
]
}Response
Accepted
Example response
{
"replace": [
{
"from": {
"paymentData": {
"transactions": [
"creditcard"
]
}
},
"to": {
"items": [
{
"uniqueId": "40E763F4378E4F40AD1FE915FE1078E1",
"id": "3",
"productId": "7",
"productRefId": "smallcup",
"refId": "356",
"ean": "8745121641680",
"name": "Small cup of coffee with pink logo",
"skuName": "Small blue cup",
"modalType": "GLASS",
"priceValidUntil": "2023-03-01T22:58:28.143",
"price": 600,
"listPrice": 600,
"manualPrice": 6500,
"manualPriceAppliedBy": "4cc81d44-e42e-464b-8199-1e883bf4ab6b",
"sellingPrice": 600,
"rewardValue": 50,
"additionalInfo": {
"brandName": "Special coffee cup",
"brandId": "2000001",
"productClusterId": "135,137,143,518,1272",
"commercialConditionId": "5"
},
"preSaleDate": "2023-01-01T00:00:00.0000000+00:00",
"productCategoryIds": "/2/",
"productCategories": {
"2": "Clothes"
},
"quantity": 1,
"seller": "1",
"imageUrl": "http://store.com.br/ids/155419-55-55//cupcoffee.png?v=6368858582363",
"detailUrl": "/cup-coffee/p",
"availability": "available",
"measurementUnit": "un",
"unitMultiplier": 1,
"manufacturerCode": "manf-00005"
}
],
"paymentData": {
"transactions": [
"creditcard"
]
},
"shippingData": {
"logisticsInfo": [
{
"selectedSla": "Normal",
"addressId": "9ec276fd3a604eb1aa151b5333ca5db7",
"slas": [
{
"id": "Normal",
"deliveryChannel": "delivery",
"name": "Normal",
"deliveryIds": [
{
"courierId": "1c083bf",
"warehouseId": "1_1",
"dockId": "1",
"courierName": "Donkey",
"quantity": 1,
"kitItemDetails": [],
"accountCarrierName": null
}
],
"shippingEstimate": "3bd",
"shippingEstimateDate": "2023-07-27T17:52:18.6483116Z",
"lockTTL": "1bd",
"deliveryWindow": {
"startDateUtc": "2024-03-14T00:00:00+00:00",
"endDateUtc": "2024-03-14T23:59:59+00:00"
},
"price": 600,
"listPrice": 600,
"pickupStoreInfo": {
"dockId": "dockAjs28"
},
"pickupPointId": "pup215rkw",
"pickupDistance": 1,
"polygonName": "114 - Polanco _ H-05",
"transitTime": "3bd"
}
],
"shipsTo": [
"BRA"
],
"itemId": "3",
"deliveryChannels": [
{
"id": "delivery"
}
],
"price": 600,
"listPrice": 600,
"shippingEstimate": "2023-07-29T17:52:18.6483116Z",
"dockEstimate": "1bd",
"shippingEstimateDate": "3bd",
"lockTTL": "1bd",
"deliveryCompany": "Correios",
"polygonName": "114 - Polanco _ H-05",
"transitTime": "3bd",
"sellingPrice": 600,
"deliveryIds": [
{
"courierId": "1c083bf",
"warehouseId": "1_1",
"dockId": "1",
"courierName": "Donkey",
"quantity": 1,
"kitItemDetails": [],
"accountCarrierName": null
}
],
"pickupPointId": "pup215rkw",
"pickupStoreInfo": {
"dockId": "dockAjs28"
}
}
]
}
}
}
]
}