Orders API

Add log in orders Add a Log in Interactions Order Array. ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Checkout | CheckoutResources | **Orders Full Access** | There are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication). >❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.

Cancel order modifications This endpoint cancels an [order modification](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes). It is meant for when, due to an error, a modification was not completely processed, and you do not wish to [retry](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/order-system/orders/-changeOrderId-/changes/-changeRequestId-/retry) it. For this request, you need the order's `changeRequestId`, the unique identification code generated by the [Create order modifications](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) endpoint. >⚠️ Once an order modification has been successfully processed, canceling it is no longer possible. If you wish to revert the modifications made to an order, you will have to [create a new order modification](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes). ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Checkout | CheckoutResources | **Orders Full Access** | | OMS | OMS access | **Cancel order** | | OMS | OMS access | **Change order** | You 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): | **Role** | **Resource** | | --------------- | ----------------- | | Checkout Admin | Orders Full Access | | OMS - Full access | Cancel orderChange order | | IntegrationProfile - Fulfillment Oms | Cancel orderChange order | | IntegrationProfile - Fulfillment Gateway | Cancel order | | IntegrationProfile - Fulfillment Gateway Oms | Cancel orderChange order | | inStore Sales Person | Cancel orderChange order | >❗ 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-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).

Cancel order Cancels an order using its identification code (`orderId`). A common scenario is when the seller has a problem fulfilling the order and requests the marketplace to cancel it. ## Orders that cannot be canceled The following situations do not allow order cancellation: - **Partial invoices:** [Partially invoiced](https://help.vtex.com/en/tracks/orders--2xkTisx4SXOWXQel8Jg8sa/q9GPspTb9cHlMeAZfdEUe) orders cannot be canceled. However, the customer can [change the order](https://developers.vtex.com/docs/guides/change-order) to replace or remove items from it. - **Invoiced status:** Orders with `invoiced` [status](https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials_196) cannot be canceled. If the order has already been invoiced, you can use the [Order invoice notification](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/oms/pvt/orders/-orderId-/invoice) endpoint to generate a return invoice. - **Incomplete orders:** [Incomplete orders](https://help.vtex.com/en/tutorial/how-incomplete-orders-work--tutorials_294) cannot be canceled. ## Declining order cancelation The order flow has a cancellation window (grace period) in which the customer can automatically cancel the order. Except for that period, the seller can [decline an order cancellation request](https://help.vtex.com/en/tutorial/declining-order-cancelation--F2n0h1TeQ5td540Gjyff4), regardless of whether the customer or the marketplace initiated it. For more information, see [Order canceling improvements](https://developers.vtex.com/docs/guides/order-canceling-improvements). ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | OMS | OMS access | **Cancel order** | You 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): | **Role** | **Resource** | | --------------- | ----------------- | | OMS - Full access | Cancel order | | IntegrationProfile - Fulfillment Oms | Cancel order | >❗ 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-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).

Commit feed items Commit items in the [feed](https://developers.vtex.com/docs/guides/orders-feed) queue.

Create order modifications [Order modifications](https://help.vtex.com/docs/tutorials/how-order-modification-works) 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](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. >⚠️ 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](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/order-system/orders/-changeOrderId-/changes) endpoint. ## Acceptable order status for modifications You can only modify an order when it is one of the following [order flow](https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials_196) 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](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. 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](https://help.vtex.com/tracks/payments--6GAS7ZzGAm7AGoEAwDbwJG/1xjzgJZvqwaI1rfxLMCC3Y) 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](https://help.vtex.com/en/tutorial/difference-between-payment-methods-and-payment-conditions--3azJenhGFyUy2gsocms42Q) is a credit card. - The settlement occurs before the order is invoiced. - The payment connector is configured to allow partial refunds. > Currently, [Adyen](https://help.vtex.com/en/tutorial/configuring-payment-with-adyenv3--7xAz67E2Eg63LWCQNjVdwv) 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](https://help.vtex.com/tracks/payments--6GAS7ZzGAm7AGoEAwDbwJG/1xjzgJZvqwaI1rfxLMCC3Y), 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. - 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](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/order-system/orders/changes/settings) endpoint. * If you wish to alter the current settings, run the [Update Order modifications settings](https://developers.vtex.com/docs/api-reference/orders-api#put-/api/order-system/orders/changes/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: ```json { "add": { "items": [ { "id": "8", "quantity": 1, "measurementUnit": "un", "unitMultiplier": 1 } ] } } ``` ### Removing request body example: ```json { "reason": "The client wants to remove a product.", "remove": { "items": [ { "id": "8", "quantity": 2, "measurementUnit": "un", "unitMultiplier": 1 } ] } } ``` ### Replacing request body example: ```json { "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: ```json { "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 } ] } } } ] } ``` #…

Delete hook configuration Deletes a given hook configuration. Learn more with the [orders hook guide](https://developers.vtex.com/vtex-rest-api/docs/orders-feed#hook).

Create or update feed configuration The Orders Feed v3 is the best way to create order integrations. Below you can find details on the configuration API specification, and to know more see our [Feed v3 guide](https://developers.vtex.com/vtex-rest-api/docs/orders-feed) and our [order integration guide](https://developers.vtex.com/vtex-rest-api/docs/erp-integration-set-up-order-integration) There are two types of filtering that can be used. The `FromWorkflow` type filters orders by status, whereas the `FromOrders` type uses JSONata expressions to filter orders according to any property in the orders JSON document. This enables stores to filter delivered orders and orders in which products have been added or removed, for example. To learn more, access the [JSONata documentation](https://docs.jsonata.org/overview.html) and test filtering JSONata expressions with our [Test JSONata expression](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/orders/expressions/jsonata) endpoint. ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | OMS | OMS Access | **Feed v3 and Hook view only** | | OMS | OMS Access | **Feed v3 and Hook Admin** | There are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication). >❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.

Delete feed configuration Deletes the configuration set up in [Feed v3](https://developers.vtex.com/docs/guides/orders-feed). ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | OMS | OMS Access | **Feed v3 and Hook view only** | | OMS | OMS Access | **Feed v3 and Hook Admin** | There are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication). >❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.

Get order modifications details This endpoint retrieves detailed information about a specific order modification. So after creating multiple modifications, you can get information on each one of them by its `changeRequestId`, the unique identification code generated by the [Create order modifications](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) endpoint. The successful status code is `200 OK`, and its response body schema is very similar to the [Create order modifications](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) endpoint, with some additional fields: - `status`: The modification request status in the workflow, which progresses in the following order: - `waiting-acknowledgement` - `waiting-confirmation` - `done` - `canceled` - `inProgress`: When set as `true`, the order is still progressing in the order flow, when set as `false`, it is complete, whether by cancellation or because the customer received it. - `logs`: Lists the workflow processing logs. > If you want information about all the modifications made to an order, use the [Get order modifications history](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/order-system/orders/-changeOrderId-/changes) endpoint. ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Checkout | CheckoutResources | **Orders Full Access** | | OMS | OMS access | **Cancel order** | | OMS | OMS access | **Change order** | You 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): | **Role** | **Resource** | | --------------- | ----------------- | | Checkout Admin | Orders Full Access | | OMS - Full access | Cancel orderChange order | | IntegrationProfile - Fulfillment Oms | Cancel orderChange order | | IntegrationProfile - Fulfillment Gateway | Cancel order | | IntegrationProfile - Fulfillment Gateway Oms | Cancel orderChange order | | inStore Sales Person | Cancel orderChange order | >❗ 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-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).

Get order modifications history This endpoint retrieves a history of every successful [Create order modifications 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. You can access an order's history using the `changeOrderId`, which corresponds to its `orderId`. > If you want detailed information about a single modification request, you can use the endpoint [Get order modifications details](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/order-system/orders/-changeOrderId-/changes/-changeRequestId-). ## Permissions Any user or [API key](https:/developers.vtex.com/docs/guides/authentication-overview#api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Checkout | CheckoutResources | **Orders Full Access** | | OMS | OMS access | **Cancel order** | | OMS | OMS access | **Change order** | You 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): | **Role** | **Resource** | | --------------- | ----------------- | | Checkout Admin | Orders Full Access | | OMS - Full access | Cancel orderChange order | | IntegrationProfile - Fulfillment Oms | Cancel orderChange order | | IntegrationProfile - Fulfillment Gateway | Cancel order | | IntegrationProfile - Fulfillment Gateway Oms | Cancel orderChange order | | inStore Sales Person | Cancel orderChange order | >❗ 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-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).

Get order modifications summary This endpoint retrieves a summary of modifications of every successful [Create order modifications request](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) made to an order and provides an overview of each request. > ⚠️ If you want information about all the modifications made to an order, use the [Get order modifications history endpoint](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/order-system/orders/-changeOrderId-/changes). ## Permissions Any user or API key must have the appropriate License Manager resource to successfully run this request: | Product | Category | Resource | |---------|----------|----------| | OMS | OMS access | **OMS Viewer** | You can create a custom role with this resource or use one of the following predefined roles: - **OMS - Full access** (OMS Viewer) - **Checkout Admin** (OMS Viewer) - **IntegrationProfile - Fulfillment Oms** (OMS Viewer) For more information about security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm).

Retrieve order conversation List all order conversations of an order by its order ID. ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Checkout | CheckoutResources | **Orders Full Access** | There are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication). >❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.

Get feed configuration The Orders Feed v3 is the best way to create order integrations. Below you can find details on the configuration API specification, and to know more see our [Feed v3 guide](https://developers.vtex.com/vtex-rest-api/docs/orders-feed) and our [order integration guide](https://developers.vtex.com/vtex-rest-api/docs/erp-integration-set-up-order-integration). > Check the [Orders onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/orders-overview) for a journey-based overview of the Orders documentation available in the Developer Portal. ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | OMS | OMS Access | **Feed v3 and Hook view only** | | OMS | OMS Access | **Feed v3 and Hook Admin** | There are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication). >❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.

Get hook configuration Retrieves a given hook's configuration details. Learn more with the [orders hook guide](https://developers.vtex.com/vtex-rest-api/docs/orders-feed#hook). > Check the [Orders onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/orders-overview) for a journey-based overview of the Orders documentation available in the Developer Portal. ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | OMS | OMS Access | **Feed v3 and Hook view only** | | OMS | OMS Access | **Feed v3 and Hook Admin** | There are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication). >❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.

Get order Retrieves order details by searching by order ID or sequence number. >⚠️ Throttling: Each VTEX account can make up to 6000 requests per minute. > You can only access information from orders created in the last two years, and that same period is valid for customers through [My Account](https://help.vtex.com/en/tutorial/how-my-account-works--2BQ3GiqhqGJTXsWVuio3Xh). >Check the [Orders onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/orders-overview) for a journey-based overview of the Orders documentation available in the Developer Portal. ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | OMS | OMS access | **View order** | | Checkout | CheckoutResources | **Orders Full Access** | You 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): | **Role** | **Resource** | | --------------- | ----------------- | | OMS - Full access | View order | | Checkout Admin | View order | | IntegrationProfile - Fulfillment Oms | View order | | OMS - Full access | Orders Full Access | | Checkout Admin | Orders Full Access | | IntegrationProfile - Fulfillment Oms | Orders Full Access | >❗ 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-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).

Retrieve payment transaction Retrieves transaction details by order ID. All events in the transaction will be registered in this call's response body. In scenarios of [order changes](https://developers.vtex.com/vtex-rest-api/reference/registerchange), it is possible to insert a [Partial invoice](https://help.vtex.com/en/tracks/orders--2xkTisx4SXOWXQel8Jg8sa/q9GPspTb9cHlMeAZfdEUe). The total value of the order will be updated after the insertion of the invoice, even when there is a [Partial invoice](https://help.vtex.com/en/tracks/orders--2xkTisx4SXOWXQel8Jg8sa/q9GPspTb9cHlMeAZfdEUe) scenario. The updated value is settled by VTEX's Payment Gateway. The reimbursement for the shopper is automatic. >⚠️ At this time, this route does not support Fulfillment payment queries, only Marketplace orders. ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | OMS | OMS access | **View order** | You 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): | **Role** | **Resource** | | --------------- | ----------------- | | View order | View order | >❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or API 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 API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).

Get window to change seller Retrieves a marketplace's window to change seller, that is, the period when it is possible to choose another seller to fulfill a given order after the original seller has canceled it. The default period for this window is of 2 days, but it can be configured by the request Update window to change seller.

Get feed order status (deprecated)

Retrieve feed items Retrieve items from [feed](https://developers.vtex.com/docs/guides/orders-feed) queue. The event will be removed if the message `send retry` is equal to, or greater than the maximum retention period. > This API will return `404 Not Found` if there is no [Feed Configuration](https://developers.vtex.com/docs/guides/orders-feed) available for the given X-VTEX-API-AppKey.

Create or update hook configuration Configures filtering rules applied to orders hook. Learn more with the [orders hook guide](https://developers.vtex.com/vtex-rest-api/docs/orders-feed#hook). There are two types of filtering that can be used: - `FromWorkflow`: filters orders by status. - `FromOrders`: uses JSONata expressions to filter orders according to any property in the orders JSON document. This enables stores to filter delivered orders and orders in which products have been added or removed, for example. To learn more, access the [JSONata documentation](https://docs.jsonata.org/overview.html) and test filtering JSONata expressions with our [expressions API](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/orders/expressions/jsonata).

Order invoice notification This request is used for [invoicing an order](https://help.vtex.com/en/tracks/orders--2xkTisx4SXOWXQel8Jg8sa/2WgQrlHTyVo4hLjhUs1LMT). Entering the order's invoice means it was successfully completed, and the order status can be changed to `invoiced` in the [order flow](https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials_196). Once an order is `invoiced`, its status cannot be changed. After the insertion of the invoice, the order's total value will be updated, even in [partial invoice](https://help.vtex.com/en/tracks/orders--2xkTisx4SXOWXQel8Jg8sa/q9GPspTb9cHlMeAZfdEUe) scenarios. >❗ To avoid rounding errors, we recommend always sending the object of items being invoiced. ## Partial invoices After adding a [partial invoice](https://help.vtex.com/en/tracks/orders--2xkTisx4SXOWXQel8Jg8sa/q9GPspTb9cHlMeAZfdEUe), the order's value will be updated, corresponding to a partial settled value in the VTEX payment gateway. Partially invoiced orders cannot be canceled, and cancellation attempts will result in a `400` status code error. If the customer wants to replace or remove items, it is possible to [change the order](https://developers.vtex.com/docs/guides/change-order). > The partial invoices feature is available for all VTEX stores. The partial settlement in the gateway is in Beta, and requires a connector with the Payment Provider Protocol. ## Returning items Besides using this endpoint for generating invoices for sold items, you can use it for generating invoices for returned items. You determine this in the request body `type` field by choosing one of the following values: - `Output`: selling order invoice. - `Input`: returning items invoice. Be aware of generating return invoices only after the full order amount was invoiced, otherwise, no refund will occur. >⚠️ Generating a return `(type: Input)` invoice with this endpoint will automatically create a refund without the need of additional API requests. ## Changing the receipt code Every time this endpoint is called using the same `invoiceNumber`, a new `receipt` code is generated, and it overrides the previous one. By doing this, you cannot change other information, only the `receipt` code. ## Integration with marketplaces The invoice should be pushed to the fulfillment account, not to the marketplace account. Once the order is invoiced, the seller should use this request to send the invoice information to the marketplace. This endpoint is also used by the seller to send the order tracking information. However, this only should be done after the seller has the tracking information. ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | OMS | OMS access | **Notify invoice** | | OMS | OMS access | **Notify refund** | You 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): | **Role** | **Resource** | | --------------- | ----------------- | | OMS - Full access | Cancel order | | IntegrationProfile - Fulfillment Oms | Cancel order | >❗ 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-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).

List orders Retrieves a list of orders according to the filters described below. >⚠️ **B2B Buyer Portal** > > When filtering by [contact information fields](https://developers.vtex.com/docs/api-reference/b2b-contact-information-api#post-/api/dataentities/contact_information/documents), you must use the exact value of the field in the contact information. Partial matches are not supported. The limit of information retrieval is 30 pages, the default number of orders per page is 15 and it is possible to configure it up to 100 using the `per_page` parameter. Be aware that since October 3rd, 2018, this endpoint does not return the `items` property. > You can only access information from orders created in the last two years, and that same period is valid for customers through [My Account](https://help.vtex.com/en/tutorial/how-my-account-works--2BQ3GiqhqGJTXsWVuio3Xh). > This endpoint should **not** be used for integrations. Use the [orders Feed or hook](https://developers.vtex.com/docs/guides/orders-feed) for this purpose. This endpoint returns only orders that already have been indexed, which takes approximately four minutes. Because of this, the data retrieved may present inconsistencies. To get live up-to-date information and [build order integrations](https://developers.vtex.com/vtex-rest-api/docs/erp-integration-set-up-order-integration) use the [orders Feed or hook](https://developers.vtex.com/docs/guides/orders-feed). > Check the [Orders onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/orders-overview) for a journey-based overview of the Orders documentation available in the Developer Portal. ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | OMS | OMS access | **List Orders** | | Checkout | CheckoutResources | **Orders Full Access** | You 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): | **Role** | **Resource** | | --------------- | ----------------- | | OMS - Full access | List Orders | | Checkout Admin | List Orders | | IntegrationProfile - Fulfillment Oms | List Orders | | OMS - Full access | Orders Full Access | | Checkout Admin | Orders Full Access | | IntegrationProfile - Fulfillment Oms | Orders Full Access | >❗ 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-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).

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](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) 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](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) endpoint, and the response body of a successful request provides a preview of the order modifications effect. ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Checkout | CheckoutResources | **Orders Full Access** | | OMS | OMS access | **Cancel order** | | OMS | OMS access | **Change order** | You 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): | **Role** | **Resource** | | --------------- | ----------------- | | Checkout Admin | Orders Full Access | | OMS - Full access | Cancel orderChange order | | IntegrationProfile - Fulfillment Oms | Cancel orderChange order | | IntegrationProfile - Fulfillment Gateway | Cancel order | | IntegrationProfile - Fulfillment Gateway Oms | Cancel orderChange order | | inStore Sales Person | Cancel orderChange order | >❗ 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-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).

Register modifications on order This request allows [modifying an order](https://help.vtex.com/en/tutorial/changing-items-from-a-completed-order--tutorials_190) by: - Adding items to an order. - Removing items from an order. - Applying discounts to the total value of the order. - Incrementing the total value of the order. >❗ This endpoint is being deprecated in March 1st, 2026. We stopped providing support for this API since December 31st, 2025. If you wish to modify an order, you can use the [Create order modifications](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) endpoint for an improved order modification experience. > **Timeout settings:** This is a synchronous API, which means the application requests data and waits until a value is returned. This behavior can cause timeout errors. To avoid them, we recommend setting the timeout in 20 seconds. In order modifications scenarios, it is possible to insert a [Partial invoice](https://help.vtex.com/en/tracks/orders--2xkTisx4SXOWXQel8Jg8sa/q9GPspTb9cHlMeAZfdEUe). The total value of the order will be updated after the insertion of the invoice, even when there is a partial invoice scenario. The updated value is settled by the VTEX Payment Gateway, and the customer reimbursement is automatic. This action can only be done for orders in the following status: - `handling` - `waiting-for-fulfillment` - `ready for invoicing` ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Checkout | CheckoutResources | **Orders Full Access** | | OMS | OMS access | **Cancel order** | | OMS | OMS access | **Change order** | You 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): | **Role** | **Resource** | | --------------- | ----------------- | | Checkout Admin | Orders Full Access | | OMS - Full access | Cancel orderChange order | | IntegrationProfile - Fulfillment Oms | Cancel orderChange order | | IntegrationProfile - Fulfillment Gateway | Cancel order | | IntegrationProfile - Fulfillment Gateway Oms | Cancel orderChange order | | inStore Sales Person | Cancel orderChange order | >❗ 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-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).

Retry order modifications This endpoint makes a new attempt to perform an order modification previously made using the [Create order modifications](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) endpoint that, for some reason, was not completely processed. To make this request, you need the `changeRequestId`, a unique change identification code that you get when you make a [Create order modifications](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) request. When you retry to modify an order using the `changeRequestId`, instead of creating a new modification, you avoid duplications. This endpoint's successful response status code is `204 No Content`, therefore with no response body. ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Checkout | CheckoutResources | **Orders Full Access** | | OMS | OMS access | **Cancel order** | | OMS | OMS access | **Change order** | You 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): | **Role** | **Resource** | | --------------- | ----------------- | | Checkout Admin | Orders Full Access | | OMS - Full access | Cancel orderChange order | | IntegrationProfile - Fulfillment Oms | Cancel orderChange order | | IntegrationProfile - Fulfillment Gateway | Cancel order | | IntegrationProfile - Fulfillment Gateway Oms | Cancel orderChange order | | inStore Sales Person | Cancel orderChange order | >❗ 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-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).

Send payment notification Send a payment notification of a given order, by order ID. ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | OMS | OMS access | **Notify payment** | You 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): | **Role** | **Resource** | | --------------- | ----------------- | | OMS - Full access | Notify payment | | IntegrationProfile - Fulfillment Oms | Notify payment | >❗ 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-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).

Start handling order Changes the status of an order to indicate that it is in `handling`. > Expect a `status 204` response with no content in case of a successful request. The store must validate this response to retry the call if the response differs from the `204` code, making this flow the store's responsibility. This endpoint can also respond with `status 500`. ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | OMS | OMS access | **Change order workflow status** | You 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): | **Role** | **Resource** | | --------------- | ----------------- | | OMS - Full access | Change order workflow status | | IntegrationProfile - Fulfillment Oms | Change order workflow status | >❗ 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-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).

Test JSONata expression This endpoint allows you to test a JSON document with a JSONata expression, returning `true` if the document meets the criteria posed in the expression, or `false` if it does not. Since JSONata expressions can be used to filter order updates in the [Orders API feed and hook](https://developers.vtex.com/docs/guides/orders-feed), this endpoint can be used to test an expression's results before configuring the [feed or hook](https://developers.vtex.com/docs/guides/orders-feed). Learn more about how to use JSONata expressions, in the [JSONata documentation](https://docs.jsonata.org/overview.html).

Update order tracking status This endpoint sends a tracking event to an order that already has a tracking number registered to its invoice. This request is not meant to send a tracking number and URL to the invoice. If you wish to send a tracking number and URL to an order, use the [Update order's partial invoice](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/oms/pvt/orders/-orderId-/invoice/-invoiceNumber-) endpoint. For more information, see [Partial invoice](https://help.vtex.com/en/tracks/partial-invoices--2xkTisx4SXOWXQel8Jg8sa/q9GPspTb9cHlMeAZfdEUe) scenarios. This endpoint applies to orders with any shipping type, whether delivery or [pickup](https://help.vtex.com/en/tutorial/pickup-points--2fljn6wLjn8M4lJHA6HP3R). ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | OMS | OMS access | **Notify invoice** | You 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): | **Role** | **Resource** | | --------------- | ----------------- | | OMS - Full access | Notify invoice | | IntegrationProfile - Fulfillment Oms | Notify invoice | >❗ 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-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).

Update window to change seller Updates a marketplace's window to change seller, that is, the period when it is possible to choose another seller to fulfill a given order after the original seller has canceled it. It is possible to check the current window using the request Get window to change seller.

Update order's partial invoice (send tracking number) Update a given order, adding its tracking number to its [Partial invoice](https://help.vtex.com/en/tracks/pedidos--2xkTisx4SXOWXQel8Jg8sa/q9GPspTb9cHlMeAZfdEUe). After using this call to add a tracking number to an order, you can use the [Update order tracking status](https://developers.vtex.com/docs/api-reference/orders-api#put-/api/oms/pvt/orders/-orderId-/invoice/-invoiceNumber-/tracking) API request to add tracking events. ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | OMS | OMS access | **Notify invoice** | You 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): | **Role** | **Resource** | | --------------- | ----------------- | | OMS - Full access | Notify invoice | | IntegrationProfile - Fulfillment Oms | Notify invoice | >❗ 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-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).

Retrieve user order details Lists all details from an order, through the perspective of the customer who placed the order. > You can only access information from orders created in the last two years, and that same period is valid for customers through [My Account](https://help.vtex.com/en/tutorial/how-my-account-works--2BQ3GiqhqGJTXsWVuio3Xh). ## B2B Buyer Portal orders You can use this endpoint to list orders by filtering with the following fields: - Text: texts in existing order fields, [custom fields](https://developers.vtex.com/docs/guides/custom-fields-integration), and [contact information fields](https://developers.vtex.com/docs/api-reference/b2b-contact-information-api#post-/api/dataentities/contact_information/documents). - Status: the current status of the orders you wish to list. - Creation date: the date the order was created. - The purchase agent ID: ID of the purchase agent that made the order. - Pending approval: You can also filter by orders which are pending approval (`true`) or orders which are not pending approval (`false`). >⚠️ When using the `text` field to filter by contact information, you must use the exact value of the field in the contact information. Partial matches are not supported. For example: If the user's first name is set to `John Henry`, you must write `John Henry` in the `text` field. Searching for `John` will return orders made by `John`, and not `John Henry`. > Note that this request should be made by an [user](https://developers.vtex.com/docs/guides/user-authentication-and-login) or [an appKey / appToken pair](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) that is associated with the [Call center operator](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy#call-center-operator) role. Otherwise, it will return only orders from the same email informed in the `clientEmail` query parameter. ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | View My Contract Orders | My Account / OMS | **ViewMyContractOrders** | | View My Org Unit Orders | My Account / OMS | **ViewMyOrgUnitOrders** | | OMS | OMS access | **View order** | You 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): | **Role** | **Resource** | | --------------- | ----------------- | | Call center operator | View order | | OMS - Read only | View order | >❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or API 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 API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).

Retrieve user's orders Lists all orders. > You can only access information from orders created in the last two years, and that same period is valid for customers through [My Account](https://help.vtex.com/en/tutorial/how-my-account-works--2BQ3GiqhqGJTXsWVuio3Xh). ## B2C orders You can use this endpoint to list all orders from a given customer, filtering by their email. ## B2B Buyer Portal orders You can use this endpoint to list orders by filtering with the following fields: - Text: texts in existing order fields, [custom fields](https://developers.vtex.com/docs/guides/custom-fields-integration), and [contact information fields](https://developers.vtex.com/docs/api-reference/b2b-contact-information-api#post-/api/dataentities/contact_information/documents). - Status: the current status of the orders you wish to list. - Creation date: the date the order was created. - The purchase agent ID: ID of the purchase agent that made the order. - Pending approval: You can also filter by orders which are pending approval (`true`) or orders which are not pending approval (`false`). >⚠️ When using the `text` field to filter by contact information, you must use the exact value of the field in the contact information. Partial matches are not supported. For example: If the user's first name is set to `John Henry`, you must write `John Henry` in the `text` field. Searching for `John` will return orders made by `John`, and not `John Henry`. > Note that this request should be made by an [user](https://developers.vtex.com/docs/guides/user-authentication-and-login) or [an appKey / appToken pair](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) that is associated with the [Call center operator](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy#call-center-operator) role. Otherwise, it will return only orders from the same email informed in the `clientEmail` query parameter. ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | OMS | OMS access | **View order** | | View My Contract Orders | My Account / OMS | **ViewMyContractOrders** | | View My Org Unit Orders | My Account / OMS | **ViewMyOrgUnitOrders** | You 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): | **Role** | **Resource** | | --------------- | ----------------- | | Call center operator | View order | | OMS - Read only | View order | >❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or API 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 API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).

Get orders by order group ID Retrieves details about all orders related to the same purchase by searching by order group ID. >⚠️ Throttling: Each VTEX account can make up to 6000 requests per minute. > You can only access information from orders created in the last two years, and that same period is valid for customers through [My Account](https://help.vtex.com/en/tutorial/how-my-account-works--2BQ3GiqhqGJTXsWVuio3Xh). ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | OMS | OMS access | **View order** | | Checkout | CheckoutResources | **Orders Full Access** | You 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): | **Role** | **Resource** | | --------------- | ----------------- | | OMS - Full access | View order | | Checkout Admin | View order | | IntegrationProfile - Fulfillment Oms | View order | | OMS - Full access | Orders Full Access | | Checkout Admin | Orders Full Access | | IntegrationProfile - Fulfillment Oms | Orders Full Access | >❗ 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-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).

Get Order modifications settings Retrieves the [Order modifications settings](https://developers.vtex.com/docs/api-reference/orders-api#put-/api/order-system/orders/changes/settings) from a store. >ℹ️ To know more about **Order modifications**, see [How Order modifications works](https://help.vtex.com/en/tutorial/how-change-order-works-beta--56TO0bOFXsfmpc7YZ3wIUZ). ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | OMS | OMS access | **View order** | | Checkout | CheckoutResources | **Orders Full Access** | You 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): | **Role** | **Resource** | | --------------- | ----------------- | | OMS - Full access | View order | | Checkout Admin | View order | | IntegrationProfile - Fulfillment Oms | View order | | OMS - Full access | Orders Full Access | | Checkout Admin | Orders Full Access | | IntegrationProfile - Fulfillment Oms | Orders Full Access | >❗ 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-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).

Update Order modifications settings Updates the [Order modifications](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/order-system/orders/-changeOrderId-/changes) settings from a store. >ℹ️ To know more about **Order modifications**, see [How Order modifications works](https://help.vtex.com/en/tutorial/how-change-order-works-beta--56TO0bOFXsfmpc7YZ3wIUZ). ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-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: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Checkout | CheckoutResources | **Orders Full Access** | | OMS | OMS access | **Cancel order** | | OMS | OMS access | **Change order** | You 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): | **Role** | **Resource** | | --------------- | ----------------- | | Checkout Admin | Orders Full Access | | OMS - Full access | Cancel orderChange order | | IntegrationProfile - Fulfillment Oms | Cancel orderChange order | | IntegrationProfile - Fulfillment Gateway | Cancel order | | IntegrationProfile - Fulfillment Gateway Oms | Cancel orderChange order | | inStore Sales Person | Cancel orderChange order | >❗ 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-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).