Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: VTex Orders Change Order (Beta) API
description: 'Each purchase a customer makes in your store generates an [order](https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials_196) on VTEX. With the Orders API, you can view orders statuses and manage multiple aspects involved in order fulfillment, such as financial transactions, invoicing, shipping, and subscriptions. You can also [change orders](https://help.vtex.com/en/tutorial/changing-items-from-a-complete-order--tutorials_190) and make configurations to allow or forbid marketplaces and sellers to change or cancel orders.
### Order integration
To automate actions related to order processing, you can [integrate orders](https://developers.vtex.com/docs/guides/erp-integration-guide) with systems like ERP (Enterprise Resource Planning) and WMS (Warehouse Management System) using [Feed and Hook](https://developers.vtex.com/docs/guides/orders-feed).
## Orders API Index
### Orders
- `GET` [Get order](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/orders/-orderId-)
- `GET` [List orders](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/orders)
- `POST` [Start handling order](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/oms/pvt/orders/-orderId-/start-handling)
- `POST` [Cancel order](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/oms/pvt/orders/-orderId-/cancel)
- `POST` [Register change on order](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/oms/pvt/orders/-orderId-/changes)
### Invoice
- `POST` [Order invoice notification](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/oms/pvt/orders/-orderId-/invoice)
- `PATCH` [Update order''s partial invoice (send tracking number)](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/oms/pvt/orders/-orderId-/invoice/-invoiceNumber-)
### Tracking
- `PUT` [Update order tracking status](https://developers.vtex.com/docs/api-reference/orders-api#put-/api/oms/pvt/orders/-orderId-/invoice/-invoiceNumber-/tracking)
### Conversation
- `GET` [Retrieve order conversation](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/orders/-orderId-/conversation-message)
### Payment
- `GET` [Retrieve payment transaction](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/orders/-orderId-/payment-transaction)
- `POST` [Send payment notification](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/oms/pvt/orders/-orderId-/payments/-paymentId-/payment-notification)
### Feed v2 (deprecated)
- `GET` [Get feed order status](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/feed/orders/status)
### Feed v3
- `GET` [Get feed configuration](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/orders/feed/config)
- `POST` [Create or update feed configuration](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/orders/feed/config)
- `DELETE` [Delete feed configuration](https://developers.vtex.com/docs/api-reference/orders-api#delete-/api/orders/feed/config)
- `GET` [Retrieve feed items](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/orders/feed)
- `POST` [Commit feed items](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/orders/feed)
- `POST` [Test JSONata expression](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/orders/expressions/jsonata)
### Order hook
- `GET` [Get hook configuration](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/orders/hook/config)
- `POST` [Create or update hook configuration](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/orders/hook/config)
- `DELETE` [Delete hook configuration](https://developers.vtex.com/docs/api-reference/orders-api#delete-/api/orders/hook/config)
### User orders
- `GET` [Retrieve user''s orders](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/user/orders)
- `GET` [Retrieve user order details](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/user/orders/-orderId-)
### Change seller
- `GET` [Get window to change seller](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/checkout/pvt/configuration/window-to-change-seller)
- `POST` [Update window to change seller](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/checkout/pvt/configuration/window-to-change-seller)'
contact: {}
version: '1.0'
servers:
- url: https://{accountName}.{environment}.com.br
description: VTEX server URL.
variables:
accountName:
description: Name of the VTEX account. Used as part of the URL.
default: apiexamples
environment:
description: Environment to use. Used as part of the URL.
enum:
- vtexcommercestable
default: vtexcommercestable
security:
- appKey:
- '{{appKey}}'
appToken:
- '{{appToken}}'
tags:
- name: Change Order (Beta)
paths:
/api/order-system/orders/{changeOrderId}/changes:
patch:
tags:
- Change Order (Beta)
summary: VTex Create order change
operationId: Createchange
description: "[Change order](https://help.vtex.com/en/tutorial/how-change-order-works-beta--56TO0bOFXsfmpc7YZ3wIUZ) feature allows you to modify an order, whether the change is motivated by customer mistakes, product unavailability, or others. Both sellers and marketplaces can use this endpoint and change orders in multiple scenarios, and it is possible to make a single change or combine multiple ones in the same request. \nThe possible change order operations you can perform are the following:\n- **Add:** Adding items, quantity, or product weight.\n- **Remove:** Removing a part of items or the total quantity.\n- **Replace:** Changing items' quantity, weight, or price. You can also replace one or more items with different ones, including weighable products.\n\n>❗ When removing or adding items to an order, your [inventory](https://help.vtex.com/en/tutorial/inventory-management--tutorials_139) is not automatically updated. You can use the [Update inventory by SKU and warehouse](https://developers.vtex.com/docs/api-reference/logistics-api#put-/api/logistics/pvt/inventory/skus/-skuId-/warehouses/-warehouseId-) endpoint.\n\nThe next sections are listed below:\n- Number of changes per order \n- Acceptable order status for changes \n- Order change and price \n- Combining multiples operations \n\n## Number of changes per order\nBesides being able to combine multiple change operations - add, remove, and replace - in a single request, you can make different change requests, and there is no limit to how many times an order can be changed.\n\nEach order has its change history, you can retrieve it using the [Get order change history](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/order-system/orders/-changeOrderId-/changes) endpoint.\n\n## Acceptable order status for changes\nYou can only change an order when it is one of the following [order flow](https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials_196) status:\n- `handling`\n- `waiting-for-fulfillment` \n- `ready for invoicing` \n\nIt is not possible to change an order when the payment transaction is complete.\n\n## Order change and price\nWhen you add, remove or replace items using this endpoint, the order and payment transaction values are automatically updated. Change order calculates the update of the following values:\n- Item value\n- Total value \n\n**Example:** If you send the request body for replacing items without the unit multiplier (`unitMultiplier`) or measurement (`measurementUnit`), Change order will get this information on your store's Catalog, Pricing and Payment systems. \n>⚠️ Increasing the price of an order is allowed only when the order was paid by credit card, [payable notes](https:/help.vtex.com/en/tutorial/setting-up-payments-with-promissory--5pW7avTwtyQcMu4uiW8quQ), cash, or [credit control](https:/help.vtex.com/en/tutorial/customer-credit-overview--1uIqTjWxIIIEW0COMg4uE0). In addition, the [acquirer](https:/help.vtex.com/en/tutorial/what-is-an-acquirer--7N1oRTG8dGmOiIugC0cs4E) must allow transactions without the CVV code and two charging transactions in the same order. \n\nFor order changes with discounts, Order Management System (OMS) considers that you still can change the order's transactional value, as long as its status in Transaction Details is not `Finished`. \n\n## Order change and payment transaction flow \n\nAn order's [transaction flow](https://help.vtex.com/tracks/payments--6GAS7ZzGAm7AGoEAwDbwJG/1xjzgJZvqwaI1rfxLMCC3Y) goes through various payment statuses before its conclusion. Within certain conditions, it is possible to change settled orders. The requirements are the following:\n\n- The order's [payment method](https://help.vtex.com/en/tutorial/difference-between-payment-methods-and-payment-conditions--3azJenhGFyUy2gsocms42Q) is a credit card.\n- The settlement occurs before the order is invoiced.\n- The payment connector is configured to allow partial refunds.\n\n> Currently, [Adyen](https://help.vtex.com/en/tutorial/configuring-payment-with-adyenv3--7xAz67E2Eg63LWCQNjVdwv) is the only payment connector that supports that operation.\n\nIf the order change increases or decreases the cost for the customer, the platform has the following behavior:\n\n- **Smaller price after order change:** An automatic notification is sent to the payment [gateway](https://help.vtex.com/tracks/payments--6GAS7ZzGAm7AGoEAwDbwJG/kdPbEIWf8Xq8tESQvViMB#gateway) to reimburse the customer for the difference.\n- **Higher price after order change:** An automatic notification is sent to the payment gateway to require the customer to pay for the additional cost.\n\n## Combining multiples operations\nYou can use this endpoint to make a single change operation or combine them in the same request. See some examples below.\n\n### Add request body example:\n\n```json\n{\n \"add\": {\n \"items\": [\n {\n \"id\": \"8\",\n \"quantity\": 1,\n \"measurementUnit\": \"un\",\n \"unitMultiplier\": 1\n }\n ]\n }\n}\n```\n\n### Remove request body example:\n\n```json\n{\n \"reason\": \"The client wants to remove a product.\",\n \"remove\": {\n \"items\": [\n {\n \"id\": \"8\",\n \"quantity\": 2,\n \"measurementUnit\": \"un\",\n \"unitMultiplier\": 1\n }\n ]\n }\n}\n```\n\n### Replace request body example:\n```json\n{\n \"reason\": \"The client wants to increase the product weight.\",\n \"replace\": [\n {\n \"from\": {\n \"items\": [\n {\n \"id\": \"1\",\n \"quantity\": 1\n }\n ]\n },\n \"to\": {\n \"items\": [\n {\n \"id\": \"1\",\n \"quantity\": 1,\n \"measurementUnit\": \"kg\",\n \"unitMultiplier\": 1.0\n }\n ],\n \"shippingData\": {\n \"logisticsInfo\": [\n {\n \"itemIndex\": 0,\n \"slaId\": \"Normal\",\n \"deliveryChannel\": \"delivery\",\n \"addressId\": \"12334048475146857\",\n \"price\": 1000\n }\n ]\n }\n }\n }\n ]\n}\n```\n\n\n### Add, remove and replace request body example:\n\n\n```json\n{\n \"reason\": \"The client wants to add, remove and replace a weighable product.\",\n \"manualDiscountValue\": 0,\n \"add\": {\n \"items\": [\n {\n \"id\": \"8\",\n \"quantity\": 1,\n \"measurementUnit\": \"un\",\n \"unitMultiplier\": 1\n }\n ]\n },\n \"remove\": {\n \"items\": [\n {\n \"id\": \"31\",\n \"quantity\": 1,\n \"measurementUnit\": \"un\",\n \"unitMultiplier\": 1\n }\n ]\n },\n \"replace\": [\n {\n \"from\": {\n \"items\": [\n {\n \"id\": \"1\",\n \"quantity\": 1\n }\n ]\n },\n \"to\": {\n \"items\": [\n {\n \"id\": \"1\",\n \"quantity\": 1,\n \"measurementUnit\": \"kg\",\n \"unitMultiplier\": 1.0\n }\n ],\n \"shippingData\": {\n \"logisticsInfo\": [\n {\n \"itemIndex\": 0,\n \"slaId\": \"Normal\",\n \"deliveryChannel\": \"delivery\",\n \"addressId\": \"12334048475146857\",\n \"price\": 1000\n }\n ]\n }\n }\n }\n ]\n}\n```\n\n## Permissions\n\nAny user or [application key](https://developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) 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:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| Checkout | CheckoutResources | **Orders Full Access** |\n| OMS | OMS access | **Cancel order** |\n| OMS | OMS access | **Change order** |\n\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\n\n| **Role** | **Resource** | \n| --------------- | ----------------- | \n| Checkout Admin | Orders Full Access |\n| OMS - Full access | <p>Cancel order</p><p>Change order</p> |\n| IntegrationProfile - Fulfillment Oms | <p>Cancel order</p><p>Change order</p> |\n| IntegrationProfile - Fulfillment Gateway | Cancel order |\n| IntegrationProfile - Fulfillment Gateway Oms | <p>Cancel order</p><p>Change order</p> |\n| inStore Sales Person | <p>Cancel order</p><p>Change order</p> |\n\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). 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](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).\n\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication)."
parameters:
- name: an
in: query
description: Name of the VTEX account that created the order.
required: true
style: form
explode: true
schema:
type: string
example: storeName
- name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
default: application/json
- name: Accept
in: header
description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
default: application/json
- name: changeOrderId
in: path
description: Order ID of the order you wish to change.
required: true
style: simple
schema:
type: string
example: v12772213qst-02
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Createchange'
- example:
reason: The client wants to change a weighable product.
replace:
- from:
items:
- id: '1'
quantity: 1
to:
items:
- id: '1'
quantity: 1
measurementUnit: kg
unitMultiplier: 1
shippingData:
logisticsInfo:
- itemIndex: 0
slaId: Normal
deliveryChannel: delivery
addressId: '12334048475146857'
price: 1000
example:
reason: The client wants to change a weighable product.
replace:
- from:
items:
- id: '1'
quantity: 1
to:
items:
- id: '1'
quantity: 1
measurementUnit: kg
unitMultiplier: 1
shippingData:
logisticsInfo:
- itemIndex: 0
slaId: Normal
deliveryChannel: delivery
addressId: '12334048475146857'
price: 1000
required: true
responses:
'202':
description: Accepted
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/response202'
example:
requestId: e8532a32-7f7e-434a-88ec-29609f0ede46
workflowId: 74f40e7a-68c6-4699-b874-a8a297fb3f6a
reason: The client did not like the size.
manualDiscountValue: 0
manualIncrementValue: 0
totalChangeValue: 0
totals: []
add: null
remove: null
replace:
- from:
paymentData:
transactions: []
items:
- id: '31'
quantity: 1
price: null
measurementUnit: null
unitMultiplier: 0
sellingPrice: null
name: null
detailUrl: null
imageUrl: null
shippingData:
logisticsInfo: []
to:
items:
- uniqueId: 40E763F4378E4F40AD1FE915FE1078E1
id: '1'
productId: null
productRefId: null
refId: null
ean: null
name: null
skuName: null
modalType: null
parentItemIndex: null
parentAssemblyBinding: null
assemblies: []
priceValidUntil: null
tax: 0
price: null
listPrice: null
manualPrice: null
manualPriceAppliedBy: null
sellingPrice: null
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: null
productCategories: {}
quantity: 1
seller: null
sellerChain:
- null
imageUrl: null
detailUrl: null
components: []
bundleItems: []
attachments: []
attachmentOfferings: []
offerings: []
priceTags: []
availability: null
measurementUnit: un
unitMultiplier: 1
manufacturerCode: null
priceDefinition: null
paymentData:
transactions: []
receiptData: null
shippingData:
logisticsInfo:
- itemIndex: 0
selectedSla: Lenta
selectedDeliveryChannel: delivery
addressId: 9ec276fd3a604eb1aa151b5333ca5db6
slas:
- id: Lenta
deliveryChannel: delivery
name: Lenta
deliveryIds: []
shippingEstimate: null
shippingEstimateDate: null
lockTTL: null
availableDeliveryWindows: []
deliveryWindow: null
price: 600
listPrice: 600
tax: 0
pickupStoreInfo:
isPickupStore: false
friendlyName: null
address: null
additionalInfo: null
dockId: null
pickupPointId: null
pickupDistance: null
polygonName: null
transitTime: null
shipsTo: []
itemId: '1'
deliveryChannels: []
price: 600
listPrice: 600
shippingEstimate: null
dockEstimate: null
shippingEstimateDate: null
lockTTL: null
deliveryCompany: null
polygonName: null
transitTime: null
sellingPrice: 600
deliveryIds: []
deliveryWindow: null
pickupPointId: null
pickupStoreInfo:
isPickupStore: false
friendlyName: null
address: null
additionalInfo: null
dockId: null
pickupDistance: null
date: '2023-07-27T17:52:18.6483116Z'
origin:
account: qastore
orderId: v12772213qst-02
component: MarketplaceComponent
settings:
customPaymentSystemsAllowed: []
get:
tags:
- Change Order (Beta)
summary: VTex Get order change history
operationId: GetChangeHistory
description: "This endpoint retrieves a history of every successful [Change order request](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) made to an order and provides detailed information about each request.\n\nYou can access an order's history using the `changeOrderId`, which corresponds to its `orderId`.\n\n> If you want detailed information about a single change request, you can use the endpoint [Get order change details](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/order-system/orders/-changeOrderId-/changes/-changeRequestId-).\n\n## Permissions\n\nAny user or [application key](https:/developers.vtex.com/docs/guides/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:/help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) 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:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| Checkout | CheckoutResources | **Orders Full Access** |\n| OMS | OMS access | **Cancel order** |\n| OMS | OMS access | **Change order** |\n\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\n\n| **Role** | **Resource** | \n| --------------- | ----------------- | \n| Checkout Admin | Orders Full Access |\n| OMS - Full access | <p>Cancel order</p><p>Change order</p> |\n| IntegrationProfile - Fulfillment Oms | <p>Cancel order</p><p>Change order</p> |\n| IntegrationProfile - Fulfillment Gateway | Cancel order |\n| IntegrationProfile - Fulfillment Gateway Oms | <p>Cancel order</p><p>Change order</p> |\n| inStore Sales Person | <p>Cancel order</p><p>Change order</p> |\n\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). 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](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).\n\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication)."
parameters:
- name: an
in: query
description: Name of the VTEX account that created the order.
required: true
style: form
explode: true
schema:
type: string
example: storeName
- name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
default: application/json
- name: Accept
in: header
description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
default: application/json
- name: changeOrderId
in: path
description: Order ID of the order you wish to get the change history.
required: true
style: simple
schema:
type: string
example: v12772213qst-02
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/GetChangeHistory'
- example:
requests:
- requestId: e8532a32-7f7e-434a-88ec-29609f0ede46
workflowId: 74f40e7a-68c6-4699-b874-a8a297fb3f6a
reason: The client did not like the size.
manualDiscountValue: 0
manualIncrementValue: 0
totalChangeValue: 0
totals: []
add: null
remove: null
replace:
- from:
paymentData:
transactions: []
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
# --- truncated at 32 KB (265 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-change-order-beta-api-openapi.yml