openapi: 3.0.0
info:
title: VTex Anti-fraud Provider Account Change Order (Beta) API
description: ">ℹ️ Onboarding guide\r\n>\r\n> Check the new [Payments onboarding guide](https://developers.vtex.com/docs/guides/payments-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Payments and is organized by focusing on the developer's journey.\r\n\r\nThe Anti-fraud Provider Protocol is a set of definitions to help you integrate your anti-fraud service API into VTEX platform.\r\n\r\nTo achieve this, you need to implement a web API (REST) following the specifications described in this documentation.\r\n\r\n>⚠️ You can also access our [template on GitHub](https://github.com/vtex-apps/antifraud-provider-example) to help you quickly develop your anti-fraud connector using the Anti-fraud Provider Protocol and VTEX IO.\r\n\r\nTo learn more about the Anti-fraud Provider Protocol, check our [developer guide](https://developers.vtex.com/docs/guides/how-the-integration-protocol-between-vtex-and-antifraud-companies-works).\r\n\r\n## Anti-fraud Provider API Index\r\n\r\n### Anti-fraud Flow\r\n\r\n- `POST` [Send Anti-fraud Pre-Analysis Data (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/pre-analysis)\r\n- `POST` [Send Anti-fraud Data](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/transactions)\r\n- `PUT` [Update Anti-fraud Transactions (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#put-/transactions/-transactionId-)\r\n- `GET` [List Anti-fraud Provider Manifest](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/manifest)\r\n- `GET` [Get Anti-fraud Status](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/transactions/-transactions.id-)\r\n- `DELETE` [Stop Anti-fraud Analysis (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#delete-/transactions/-transactions.Id-)\r\n\r\n### OAuth Flow\r\n\r\n1. `POST` [Retrieve Token](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/authorization/token)\r\n2. `GET` [Redirect](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/redirect)\r\n3. `GET` [Return to VTEX](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorizationCode)\r\n4. `GET` [Get Credentials](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorization/credentials)"
version: '1.0'
servers:
- url: https://{providerApiEndpoint}
description: Anti-fraud provider endpoint URL.
variables:
providerApiEndpoint:
description: Anti-fraud provider endpoint URL.
default: '{providerApiEndpoint}'
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. \r\nThe possible change order operations you can perform are the following:\r\n- **Add:** Adding items, quantity, or product weight.\r\n- **Remove:** Removing a part of items or the total quantity.\r\n- **Replace:** Changing items' quantity, weight, or price. You can also replace one or more items with different ones, including weighable products.\r\n\r\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.\r\n\r\nThe next sections are listed below:\r\n- Number of changes per order \r\n- Acceptable order status for changes \r\n- Order change and price \r\n- Combining multiples operations \r\n\r\n## Number of changes per order\r\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.\r\n\r\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.\r\n\r\n## Acceptable order status for changes\r\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:\r\n- `handling`\r\n- `waiting-for-fulfillment` \r\n- `ready for invoicing` \r\n\r\nIt is not possible to change an order when the payment transaction is complete.\r\n\r\n## Order change and price\r\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:\r\n- Item value\r\n- Total value \r\n\r\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. \r\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. \r\n\r\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`. \r\n\r\n## Order change and payment transaction flow \r\n\r\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:\r\n\r\n- The order's [payment method](https://help.vtex.com/en/tutorial/difference-between-payment-methods-and-payment-conditions--3azJenhGFyUy2gsocms42Q) is a credit card.\r\n- The settlement occurs before the order is invoiced.\r\n- The payment connector is configured to allow partial refunds.\r\n\r\n> Currently, [Adyen](https://help.vtex.com/en/tutorial/configuring-payment-with-adyenv3--7xAz67E2Eg63LWCQNjVdwv) is the only payment connector that supports that operation.\r\n\r\nIf the order change increases or decreases the cost for the customer, the platform has the following behavior:\r\n\r\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.\r\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.\r\n\r\n## Combining multiples operations\r\nYou can use this endpoint to make a single change operation or combine them in the same request. See some examples below.\r\n\r\n### Add request body example:\r\n\r\n```json\r\n{\r\n \"add\": {\r\n \"items\": [\r\n {\r\n \"id\": \"8\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"un\",\r\n \"unitMultiplier\": 1\r\n }\r\n ]\r\n }\r\n}\r\n```\r\n\r\n### Remove request body example:\r\n\r\n```json\r\n{\r\n \"reason\": \"The client wants to remove a product.\",\r\n \"remove\": {\r\n \"items\": [\r\n {\r\n \"id\": \"8\",\r\n \"quantity\": 2,\r\n \"measurementUnit\": \"un\",\r\n \"unitMultiplier\": 1\r\n }\r\n ]\r\n }\r\n}\r\n```\r\n\r\n### Replace request body example:\r\n```json\r\n{\r\n \"reason\": \"The client wants to increase the product weight.\",\r\n \"replace\": [\r\n {\r\n \"from\": {\r\n \"items\": [\r\n {\r\n \"id\": \"1\",\r\n \"quantity\": 1\r\n }\r\n ]\r\n },\r\n \"to\": {\r\n \"items\": [\r\n {\r\n \"id\": \"1\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"kg\",\r\n \"unitMultiplier\": 1.0\r\n }\r\n ],\r\n \"shippingData\": {\r\n \"logisticsInfo\": [\r\n {\r\n \"itemIndex\": 0,\r\n \"slaId\": \"Normal\",\r\n \"deliveryChannel\": \"delivery\",\r\n \"addressId\": \"12334048475146857\",\r\n \"price\": 1000\r\n }\r\n ]\r\n }\r\n }\r\n }\r\n ]\r\n}\r\n```\r\n\r\n\r\n### Add, remove and replace request body example:\r\n\r\n\r\n```json\r\n{\r\n \"reason\": \"The client wants to add, remove and replace a weighable product.\",\r\n \"manualDiscountValue\": 0,\r\n \"add\": {\r\n \"items\": [\r\n {\r\n \"id\": \"8\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"un\",\r\n \"unitMultiplier\": 1\r\n }\r\n ]\r\n },\r\n \"remove\": {\r\n \"items\": [\r\n {\r\n \"id\": \"31\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"un\",\r\n \"unitMultiplier\": 1\r\n }\r\n ]\r\n },\r\n \"replace\": [\r\n {\r\n \"from\": {\r\n \"items\": [\r\n {\r\n \"id\": \"1\",\r\n \"quantity\": 1\r\n }\r\n ]\r\n },\r\n \"to\": {\r\n \"items\": [\r\n {\r\n \"id\": \"1\",\r\n \"quantity\": 1,\r\n \"measurementUnit\": \"kg\",\r\n \"unitMultiplier\": 1.0\r\n }\r\n ],\r\n \"shippingData\": {\r\n \"logisticsInfo\": [\r\n {\r\n \"itemIndex\": 0,\r\n \"slaId\": \"Normal\",\r\n \"deliveryChannel\": \"delivery\",\r\n \"addressId\": \"12334048475146857\",\r\n \"price\": 1000\r\n }\r\n ]\r\n }\r\n }\r\n }\r\n ]\r\n}\r\n```\r\n\r\n## Permissions\r\n\r\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:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Checkout | CheckoutResources | **Orders Full Access** |\r\n| OMS | OMS access | **Cancel order** |\r\n| OMS | OMS access | **Change order** |\r\n\r\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):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Checkout Admin | Orders Full Access |\r\n| OMS - Full access | <p>Cancel order</p><p>Change order</p> |\r\n| IntegrationProfile - Fulfillment Oms | <p>Cancel order</p><p>Change order</p> |\r\n| IntegrationProfile - Fulfillment Gateway | Cancel order |\r\n| IntegrationProfile - Fulfillment Gateway Oms | <p>Cancel order</p><p>Change order</p> |\r\n| inStore Sales Person | <p>Cancel order</p><p>Change order</p> |\r\n\r\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).\r\n\r\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.\r\n\r\nYou can access an order's history using the `changeOrderId`, which corresponds to its `orderId`.\r\n\r\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-).\r\n\r\n## Permissions\r\n\r\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:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Checkout | CheckoutResources | **Orders Full Access** |\r\n| OMS | OMS access | **Cancel order** |\r\n| OMS | OMS access | **Change order** |\r\n\r\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):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Checkout Admin | Orders Full Access |\r\n| OMS - Full access | <p>Cancel order</p><p>Change order</p> |\r\n| IntegrationProfile - Fulfillment Oms | <p>Cancel order</p><p>Change order</p> |\r\n| IntegrationProfile - Fulfillment Gateway | Cancel order |\r\n| IntegrationProfile - Fulfillment Gateway Oms | <p>Cancel order</p><p>Change order</p> |\r\n| inStore Sales Person | <p>Cancel order</p><p>Change order</p> |\r\n\r\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).\r\n\r\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
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: nul
# --- truncated at 32 KB (263 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-change-order-beta-api-openapi.yml