Order modifications
Preview order modifications
This endpoint allows you to simulate an order modification and preview what the real modification will look like if you use the Create order modifications endpoint. A preview is especially useful for more complex scenarios, such as orders with multiple items and combinations of change operations — add, remove, and replace. Ensuring you get the desired results before making the actual modification helps prevent mistakes.
Tax and promotion recalculation
We recommend using this endpoint to preview an order modification for items with promotions or tax recalculation. You can use the fields in the pipelineConfiguration object to preview an order's discount and native taxes for rates and benefits. This way, you can validate the financial impact before modifying an order.
The request body is the same one to be used in the Create order modifications endpoint, and the response body of a successful request provides a preview of the order modifications effect.
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.
post/api/order-system/orders/{changeOrderId}/changes/preview
Path parameters
changeOrderIdstring required
Example:v12772213qst-02
Order ID of the order you wish to preview modification.
Query parameters
anstring required
Example:storeName
Name of the VTEX account that created the order.
Headers
Content-Typestring required
Type of the content being sent.
Acceptstring required
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
OK
Example response
{
"replace": [
{
"from": {
"paymentData": {
"transactions": [
"creditcard"
]
},
"items": [
{
"id": "31",
"quantity": 1,
"price": 5000,
"measurementUnit": "un",
"unitMultiplier": 1,
"sellingPrice": 5000,
"name": "Fusca miniatura Fusca preto",
"detailUrl": "/fusca-miniatura-24/p",
"imageUrl": "http://qastore.vteximg.com.br/arquivos/ids/155431-55-55/image-bdab69af1e5c41cdbc498d02e370b376.jpg?v=636579391945870000"
}
],
"shippingData": {
"logisticsInfo": [
{
"itemIndex": 0,
"selectedSla": "Lenta",
"selectedDeliveryChannel": "delivery",
"addressId": "9ec276fd3a604eb1aa151b5333ca5db6",
"slas": [
{
"id": "Lenta",
"deliveryChannel": "delivery",
"name": "Lenta",
"deliveryIds": [
{
"courierId": "1c083bf",
"warehouseId": "1_1",
"dockId": "1",
"courierName": "Donkey",
"quantity": 1,
"kitItemDetails": [],
"accountCarrierName": null
}
],
"shippingEstimate": "25bd",
"shippingEstimateDate": "2023-08-30T10:17:24.6436519Z",
"lockTTL": "12d",
"availableDeliveryWindows": [],
"deliveryWindow": null,
"price": 180,
"listPrice": 180,
"tax": 0,
"pickupStoreInfo": {
"isPickupStore": false,
"friendlyName": null,
"address": null,
"additionalInfo": null,
"dockId": null
},
"pickupPointId": null,
"pickupDistance": null,
"polygonName": "",
"transitTime": "25bd"
},
{
"id": "Normal",
"deliveryChannel": "delivery",
"name": "Normal",
"deliveryIds": [
{
"courierId": "1",
"warehouseId": "1_1",
"dockId": "1",
"courierName": "Transportadora",
"quantity": 1,
"kitItemDetails": [],
"accountCarrierName": null
}
],
"shippingEstimate": "3bd",
"shippingEstimateDate": null,
"lockTTL": "12d",
"availableDeliveryWindows": [],
"deliveryWindow": null,
"price": 500,
"listPrice": 500,
"tax": 0,
"pickupStoreInfo": {
"isPickupStore": false,
"friendlyName": null,
"address": null,
"additionalInfo": null,
"dockId": null
},
"pickupPointId": null,
"pickupDistance": null,
"polygonName": "",
"transitTime": "3bd"
},
{
"id": "Pickup",
"deliveryChannel": "delivery",
"name": "Pickup",
"deliveryIds": [
{
"courierId": "ech018654",
"warehouseId": "1_1",
"dockId": "1",
"courierName": "Retirada",
"quantity": 1,
"kitItemDetails": [],
"accountCarrierName": null
}
],
"shippingEstimate": "25bd",
"shippingEstimateDate": null,
"lockTTL": "12d",
"availableDeliveryWindows": [],
"deliveryWindow": null,
"price": 700,
"listPrice": 700,
"tax": 0,
"pickupStoreInfo": {
"isPickupStore": false,
"friendlyName": null,
"address": null,
"additionalInfo": null,
"dockId": null
},
"pickupPointId": null,
"pickupDistance": null,
"polygonName": "",
"transitTime": "25bd"
}
],
"shipsTo": [
"BRA"
],
"itemId": "31",
"deliveryChannels": [
{
"id": "delivery"
}
],
"price": 180,
"listPrice": 180,
"shippingEstimate": "25bd",
"dockEstimate": null,
"shippingEstimateDate": "2023-08-30T10:17:24.6436519Z",
"lockTTL": "12d",
"deliveryCompany": null,
"polygonName": "",
"transitTime": "25bd",
"sellingPrice": 180,
"deliveryIds": [
{
"courierId": "1c083bf",
"warehouseId": "1_1",
"dockId": "1",
"courierName": "Donkey",
"quantity": 1,
"kitItemDetails": null,
"accountCarrierName": "qastoreecho"
}
],
"deliveryWindow": null,
"pickupPointId": null,
"pickupStoreInfo": {
"isPickupStore": false,
"friendlyName": null,
"address": null,
"additionalInfo": null,
"dockId": null
},
"pickupDistance": null
}
]
}
},
"to": {
"items": [
{
"uniqueId": "40E763F4378E4F40AD1FE915FE1078E1",
"id": "1",
"productId": "1",
"productRefId": "",
"refId": "codrefxicaraazul",
"ean": "8745121641",
"name": "xícara azul",
"skuName": "azul",
"modalType": null,
"parentItemIndex": null,
"parentAssemblyBinding": null,
"assemblies": [],
"priceValidUntil": null,
"tax": 0,
"price": 5000,
"listPrice": null,
"manualPrice": null,
"manualPriceAppliedBy": null,
"sellingPrice": 5000,
"rewardValue": 0,
"isGift": false,
"additionalInfo": {
"dimension": null,
"brandName": null,
"brandId": null,
"offeringInfo": null,
"offeringType": null,
"offeringTypeId": null,
"categoriesIds": null,
"productClusterId": null,
"commercialConditionId": null
},
"preSaleDate": null,
"productCategoryIds": "/1/",
"productCategories": {
"1": "Category"
},
"quantity": 1,
"seller": "1",
"sellerChain": [
"1"
],
"imageUrl": "http://qastore.vteximg.com.br/arquivos/ids/155394-55-55/xicara.jpg?v=636565506415770000",
"detailUrl": "/xicara/p",
"components": [],
"bundleItems": [],
"attachments": [],
"attachmentOfferings": [],
"offerings": [],
"priceTags": [],
"availability": null,
"measurementUnit": "un",
"unitMultiplier": 1,
"manufacturerCode": null,
"priceDefinition": {
"calculatedSellingPrice": 5000,
"total": 5000,
"sellingPrices": [
{
"value": 5000,
"quantity": 1
}
]
}
}
],
"paymentData": {
"transactions": []
},
"receiptData": null,
"shippingData": {
"logisticsInfo": [
{
"itemIndex": 0,
"selectedSla": "Lenta",
"selectedDeliveryChannel": "delivery",
"addressId": "9ec276fd3a604eb1aa151b5333ca5db6",
"slas": [
{
"id": "Lenta",
"deliveryChannel": "delivery",
"name": "Lenta",
"deliveryIds": [
{
"courierId": "1c083bf",
"warehouseId": "1_1",
"dockId": "1",
"courierName": "Donkey",
"quantity": 1,
"kitItemDetails": [],
"accountCarrierName": null
}
],
"shippingEstimate": "25bd",
"shippingEstimateDate": "2023-08-30T10:17:24.6436519Z",
"lockTTL": "12d",
"availableDeliveryWindows": [],
"deliveryWindow": null,
"price": 600,
"listPrice": 180,
"tax": 0,
"pickupStoreInfo": {
"isPickupStore": false,
"friendlyName": null,
"address": null,
"additionalInfo": null,
"dockId": null
},
"pickupPointId": null,
"pickupDistance": null,
"polygonName": "",
"transitTime": "25bd"
},
{
"id": "Normal",
"deliveryChannel": "delivery",
"name": "Normal",
"deliveryIds": [
{
"courierId": "1",
"warehouseId": "1_1",
"dockId": "1",
"courierName": "Transportadora",
"quantity": 1,
"kitItemDetails": [],
"accountCarrierName": null
}
],
"shippingEstimate": "3bd",
"shippingEstimateDate": null,
"lockTTL": "12d",
"availableDeliveryWindows": [],
"deliveryWindow": null,
"price": 500,
"listPrice": 500,
"tax": 0,
"pickupStoreInfo": {
"isPickupStore": false,
"friendlyName": null,
"address": null,
"additionalInfo": null,
"dockId": null
},
"pickupPointId": null,
"pickupDistance": null,
"polygonName": "",
"transitTime": "3bd"
},
{
"id": "Pickup",
"deliveryChannel": "delivery",
"name": "Pickup",
"deliveryIds": [
{
"courierId": "ech018654",
"warehouseId": "1_1",
"dockId": "1",
"courierName": "Retirada",
"quantity": 1,
"kitItemDetails": [],
"accountCarrierName": null
}
],
"shippingEstimate": "25bd",
"shippingEstimateDate": null,
"lockTTL": "12d",
"availableDeliveryWindows": [],
"deliveryWindow": null,
"price": 700,
"listPrice": 700,
"tax": 0,
"pickupStoreInfo": {
"isPickupStore": false,
"friendlyName": null,
"address": null,
"additionalInfo": null,
"dockId": null
},
"pickupPointId": null,
"pickupDistance": null,
"polygonName": "",
"transitTime": "25bd"
}
],
"shipsTo": [
"BRA"
],
"itemId": "1",
"deliveryChannels": [
{
"id": "delivery"
}
],
"price": 600,
"listPrice": 180,
"shippingEstimate": "25bd",
"dockEstimate": null,
"shippingEstimateDate": "2023-08-30T10:17:24.6436519Z",
"lockTTL": "12d",
"deliveryCompany": null,
"polygonName": "",
"transitTime": "25bd",
"sellingPrice": 600,
"deliveryIds": [
{
"courierId": "1c083bf",
"warehouseId": "1_1",
"dockId": "1",
"courierName": "Donkey",
"quantity": 1,
"kitItemDetails": null,
"accountCarrierName": "qastoreecho"
}
],
"deliveryWindow": null,
"pickupPointId": null,
"pickupStoreInfo": {
"isPickupStore": false,
"friendlyName": null,
"address": null,
"additionalInfo": null,
"dockId": null
},
"pickupDistance": null
}
]
}
}
}
]
}