The VTEX Orders API provides comprehensive order management for VTEX stores. It enables listing, retrieving, filtering, and updating orders, managing order lifecycle events, processing cancellations, handling returns, and generating order invoices. This API is the backbone of post-purchase operations.
openapi: 3.0.0
info:
title: VTex Orders API
description: "Each purchase a customer makes in your store generates an [order](https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials_196) on VTEX. With the Orders API, you can view orders statuses and manage multiple aspects involved in order fulfillment, such as financial transactions, invoicing, shipping, and subscriptions. You can also [change orders](https://help.vtex.com/en/tutorial/changing-items-from-a-complete-order--tutorials_190) and make configurations to allow or forbid marketplaces and sellers to change or cancel orders.\r\n\r\n### Order integration\n\r\nTo automate actions related to order processing, you can [integrate orders](https://developers.vtex.com/docs/guides/erp-integration-guide) with systems like ERP (Enterprise Resource Planning) and WMS (Warehouse Management System) using [Feed and Hook](https://developers.vtex.com/docs/guides/orders-feed).\r\n\r\n## Orders API Index\r\n\r\n### Orders\r\n\r\n- `GET` [Get order](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/orders/-orderId-)\r\n- `GET` [List orders](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/orders)\r\n- `POST` [Start handling order](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/oms/pvt/orders/-orderId-/start-handling)\r\n- `POST` [Cancel order](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/oms/pvt/orders/-orderId-/cancel)\r\n- `POST` [Register change on order](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/oms/pvt/orders/-orderId-/changes)\r\n\r\n### Invoice\r\n\r\n- `POST` [Order invoice notification](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/oms/pvt/orders/-orderId-/invoice)\r\n- `PATCH` [Update order's partial invoice (send tracking number)](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/oms/pvt/orders/-orderId-/invoice/-invoiceNumber-)\r\n\r\n### Tracking\r\n\r\n- `PUT` [Update order tracking status](https://developers.vtex.com/docs/api-reference/orders-api#put-/api/oms/pvt/orders/-orderId-/invoice/-invoiceNumber-/tracking)\r\n\r\n### Conversation\r\n\r\n- `GET` [Retrieve order conversation](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/orders/-orderId-/conversation-message)\r\n\r\n### Payment\r\n\r\n- `GET` [Retrieve payment transaction](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/orders/-orderId-/payment-transaction)\r\n- `POST` [Send payment notification](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/oms/pvt/orders/-orderId-/payments/-paymentId-/payment-notification)\r\n\r\n### Feed v2 (deprecated)\r\n\r\n- `GET` [Get feed order status](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/feed/orders/status)\r\n\r\n### Feed v3\r\n\r\n- `GET` [Get feed configuration](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/orders/feed/config)\r\n- `POST` [Create or update feed configuration](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/orders/feed/config)\r\n- `DELETE` [Delete feed configuration](https://developers.vtex.com/docs/api-reference/orders-api#delete-/api/orders/feed/config)\r\n- `GET` [Retrieve feed items](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/orders/feed)\r\n- `POST` [Commit feed items](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/orders/feed)\r\n- `POST` [Test JSONata expression](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/orders/expressions/jsonata)\r\n\r\n### Order hook\r\n\r\n- `GET` [Get hook configuration](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/orders/hook/config)\r\n- `POST` [Create or update hook configuration](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/orders/hook/config)\r\n- `DELETE` [Delete hook configuration](https://developers.vtex.com/docs/api-reference/orders-api#delete-/api/orders/hook/config)\r\n\r\n### User orders\r\n\r\n- `GET` [Retrieve user's orders](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/user/orders)\r\
\n- `GET` [Retrieve user order details](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/user/orders/-orderId-)\r\n\r\n### Change seller\r\n\r\n- `GET` [Get window to change seller](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/checkout/pvt/configuration/window-to-change-seller)\r\n- `POST` [Update window to change seller](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/checkout/pvt/configuration/window-to-change-seller)"
contact: {}
version: '1.0'
servers:
- url: https://{accountName}.{environment}.com.br
description: VTEX server URL.
variables:
accountName:
description: Name of the VTEX account. Used as part of the URL.
default: apiexamples
environment:
description: Environment to use. Used as part of the URL.
enum:
- vtexcommercestable
default: vtexcommercestable
paths:
/api/oms/pvt/orders/{orderId}:
get:
tags:
- Orders
summary: VTex Get order
description: "This endpoint retrieves order details by searching a specific order ID or sequence number. \r\n\r\n> 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). \r\n\r\n> **Onboarding guide** \r\n>\r\n> Check the new [Orders onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/orders-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Orders and is organized by focusing on the developer's journey. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-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| OMS | OMS access | **List Orders** |\r\n| Checkout | CheckoutResources | **Orders Full Access** |\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| OMS - Full access | List Orders |\r\n| Checkout Admin | List Orders |\r\n| IntegrationProfile - Fulfillment Oms | List Orders |\r\n| OMS - Full access | Orders Full Access |\r\n| Checkout Admin | Orders Full Access |\r\n| IntegrationProfile - Fulfillment Oms | Orders Full Access |\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)."
operationId: GetOrder
parameters:
- 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: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
default: application/json
- name: orderId
in: path
description: 'Order ID is a unique code that identifies an order. Instead of using `orderId`, you can also make the request using the sequence, a six-digit string that follows the order ID. For example, in order 1268540501456-01 (501456), the sequence is 501456. To use this parameter, replace the value between `{ }` keys in `seq{sequence-number}` with the sequence. For example: `seq501456`.'
example: 1172452900788-01 or seq501456
required: true
style: simple
schema:
type: string
example: 1172452900788-01 or seq501456
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
orderId:
type: string
description: Unique code that identifies an order.
sequence:
type: string
description: Six-digit string that follows the order ID. For example, in order `1268540501456-01 (501456)`, the sequence is `501456`.
marketplaceOrderId:
type: string
description: Marketplace order ID.
marketplaceServicesEndpoint:
type: string
description: Endpoint provided by the marketplace for post purchase communication.
sellerOrderId:
type: string
description: ID of the seller related to the order. It can be a VTEX seller or an external seller.
origin:
type: string
description: Order's [origin in the order flow](https://developers.vtex.com/docs/guides/orders-overview#understanding-order-flow-types), which can be `Marketplace`, `Fulfillment` or `Chain`.
affiliateId:
type: string
description: Three-digit [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187) code that identifies the marketplace where the order originates. This ID is configured in the seller's VTEX account.
salesChannel:
type: string
description: Sales channel (or [trade policy](https://help.vtex.com/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV)) ID related to the order.
merchantName:
type: string
description: For a VTEX store, the merchant's name will be the same as the account name. An external seller can have a `merchantName`, and in this case the field will not correspond to an account name.
status:
type: string
description: Order [status](https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials_196).
workflowIsInError:
type: boolean
description: Indicates if the order workflow presents an error that cannot be solved by automatic retry (`true`), or if there are no processing errors (`false`).
statusDescription:
type: string
description: '`Deprecated`. Status description which is displayed on the Admin panel. This field is obsolete and may not return any value.'
deprecated: true
value:
type: integer
description: Order's total value in cents.
creationDate:
type: string
description: Order's creation date in [ISO 8601 time zone offset format](https://learn.microsoft.com/pt-br/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DD hh:mm:ss[.nnnnnnn]+hh:mm`.
lastChange:
type: string
description: Order's last change date in [ISO 8601 time zone offset format](https://learn.microsoft.com/pt-br/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DD hh:mm:ss[.nnnnnnn]+hh:mm`.
orderGroup:
type: string
description: Order's group ID.
followUpEmail:
type: string
description: Email of the store's employee responsible for managing the order.
lastMessage:
type: string
nullable: true
description: Transactional message sent most recently.
hostname:
type: string
description: Account host name, which is the [domain](https://help.vtex.com/en/tutorial/configuring-the-store-domain--tutorials_2450#store-address-structure) registered in **Account Settings**.
isCompleted:
type: boolean
description: When set as `true`, the order's payment has been settled, and when set as `false`, it has not been settled yet.
roundingError:
type: integer
description: Rounding error total amount, if it applies. For example, in orders with a discount over non-integer multiplier items, the rounding price is performed per item, not after the sum of all items. That can cause a difference in the total discount amount, which is informed in this field.
orderFormId:
type: string
description: Unique identifier of the [orderForm](https://developers.vtex.com/docs/guides/orderform-fields).
allowCancellation:
type: boolean
description: When set as `true`, the order can be canceled, and when set as `false`, it is no longer possible to cancel the order.
allowEdition:
type: boolean
description: When set as `true`, the order can be edited, and when set as `false`, it is no longer possible to edit the order.
isCheckedIn:
type: boolean
description: This field is set as `true` when the order was placed via [VTEX Sales App](https://help.vtex.com/en/tracks/instore-getting-started-and-setting-up--zav76TFEZlAjnyBVL5tRc) and `false` when it was not.
authorizedDate:
type: string
description: Authorized order date in [ISO 8601 time zone offset format](https://learn.microsoft.com/pt-br/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DD hh:mm:ss[.nnnnnnn]+hh:mm`.
invoicedDate:
type: string
nullable: true
description: Order's invoice date in [ISO 8601 time zone offset format](https://learn.microsoft.com/pt-br/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DD hh:mm:ss[.nnnnnnn]+hh:mm`.
cancelReason:
type: string
description: Reason for order cancellation.
nullable: true
checkedInPickupPointId:
type: string
description: If the field `isCheckedIn` is set as `true`, the `checkedInPickupPointId` will retrieve the ID of the physical store where the order was made.
totals:
type: array
description: List with details about orders' totals.
items:
type: object
description: Information about orders' totals.
properties:
id:
type: string
description: Code that identifies if the information is about `Items`, `Discounts`, `Shipping`, `Tax` or `Change`.
name:
type: string
description: Name of the total count.
value:
type: integer
description: Total value in cents of `Items`, `Discounts`, `Shipping`, `Tax` or `Change`.
sellers:
type: array
description: List of all the sellers associated with the order.
items:
type: object
description: Information about the seller associated with the order.
properties:
id:
type: string
description: Unique identifier of the seller.
name:
type: string
description: Seller's name.
logo:
type: string
description: URL of the seller's logo.
fulfillmentEndpoint:
type: string
description: URL of the endpoint for fulfillment of seller's orders.
clientPreferencesData:
type: object
description: Information about customer's preferences.
properties:
locale:
type: string
description: Language code of the customer's preferred language while accessing the store.
optinNewsLetter:
type: boolean
description: When set as `true`, this field indicates that the customer opted to receive the newsletter, and when set as `false`, it means they did not.
cancellationData:
type: object
description: Information about order cancellation, when applicable.
properties:
RequestedByUser:
type: boolean
description: Indicates if the order cancellation was requested by the customer (`true`) or not (`false`).
nullable: true
RequestedBySystem:
type: boolean
description: Indicates if the order cancellation was made by the system (`true`) or not (`false`). This type of order cancellation happens in [incomplete orders](https://help.vtex.com/en/tutorial/how-incomplete-orders-work--tutorials_294), for example.
nullable: true
RequestedBySellerNotification:
type: boolean
description: Indicates if the order cancellation was requested by the seller (`true`) or not (`false`).
nullable: true
RequestedByPaymentNotification:
type: boolean
description: Indicates if the order cancellation was requested by the payment gateway (`true`) or not (`false`).
nullable: true
Reason:
type: string
description: Reason why the order was cancelled.
nullable: true
CancellationDate:
type: string
description: Order cancellation date in [UTC time format](https://learn.microsoft.com/pt-br/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`.
nullable: true
nullable: true
taxData:
type: object
description: Order's tax information.
properties:
areTaxesDesignatedByMarketplace:
type: boolean
description: Indicates if the taxes were designated by the marketplace (`true`) or not (`false`).
taxInfoCollection:
type: array
description: Array with taxes' details.
items:
type: object
description: Taxes' details.
properties:
itemIndex:
type: integer
description: Item's index number.
sku:
type: string
description: Alphanumeric sequence that identifies an SKU.
priceTags:
type: array
description: Items' price tag information with original taxes calculated at order placement.
items:
type: object
description: Price tag information.
properties:
identifier:
type: string
description: Price tag identifier code.
isPercentual:
type: boolean
description: Defines if the price tag is a percentage (`true`) or not (`false`).
name:
type: string
description: Price tag name.
value:
type: number
description: Price tag value in cents.
rawValue:
type: number
description: Price tag raw value that can contain up to five decimals, separated by a period.
nullable: true
subscriptionData:
type: object
description: Information about [subscriptions](https://help.vtex.com/tutorial/how-subscriptions-work--frequentlyAskedQuestions_4453), when applicable.
nullable: true
properties:
SubscriptionGroupId:
type: string
description: ID of the subscription's group. If this field returns `null` and the `executionCount` is `0`, the order is the first one with subscriptions.
nullable: true
Subscriptions:
type: array
description: List with subscriptions details.
nullable: true
items:
type: object
description: Subscription details.
properties:
ExecutionCount:
type: integer
description: Position of the order in the subscription cycle. The first order will have the value `0`, the second will have the value `1`, and so on.
PriceAtSubscriptionDate:
type: number
description: Value of the order when the customer signed up for subscriptions. Subscriptions created via Admin or APIs do not have an original order, so the field returns `0.0`. This field was valid only for Subscriptions v2 and is deprecated in Subscriptions v3.
deprecated: true
ItemIndex:
type: integer
description: Each item in the subscription order is identified by an index. The position starts in`0`, followed by `1`, `2`, and so on.
Plan:
type: object
description: Information about the subscription's validility and frequency.
properties:
type:
type: string
description: Type of plan.
frequency:
type: object
description: Information about subscriptions' recurrence.
properties:
periodicity:
type: string
description: Defines the subscriptions recurrence period. The possible values are `DAILY`,`WEEKLY`, `MONTHLY` and `YEARLY`.
interval:
type: integer
description: Number of the time interval configured between subscription orders, which depends on the periodicity. For a `DAILY` periodicity, the field's value will correspond to days, for `MONTHLY` to months, and so on.
validity:
type: object
description: Information about the period during which the subscription will be valid.
properties:
begin:
type: string
description: Subscriptions' beginning date in [UTC time format](https://learn.microsoft.com/pt-br/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`.
end:
type: string
description: Subscriptions' ending date with the format `yyyy-mm-ddThh:mm:ss`.
nullable: true
itemMetadata:
type: object
description: Metadata information about the order's items.
properties:
Items:
type: array
description: List of order items' metadata.
items:
type: object
description: Order item metadata.
properties:
Id:
type: string
description: Unique numerical identifier of the SKU.
Seller:
type: string
description: Unique identifier of the SKU seller.
Name:
type: string
description: Name of the item as displayed to customers in the storefront.
SkuName:
type: string
description: Name of the SKU corresponding to the item.
ProductId:
type: string
description: ID of the product associated with the item.
RefId:
type: string
description: SKU reference ID.
Ean:
type: string
description: SKU EAN.
ImageUrl:
type: string
description: SKU image URL.
DetailUrl:
type: string
description: SKU slug.
AssemblyOptions:
type: array
description: '[Assembly options](https://help.vtex.com/en/tutorial/assembly-options--5x5FhNr4f5RUGDEGWzV1nH) information related to the item, if there are any.'
nullable: true
items:
type: object
description: '[Assembly option](https://help.vtex.com/en/tutorial/assembly-options--5x5FhNr4f5RUGDEGWzV1nH) details.'
properties:
Id:
type: string
description: Assembly option ID.
Name:
type: string
description: Assembly option name.
Required:
type: boolean
description: If this field is set as `true`, when the customer purchases the item sending the attachment is required, and when set as `false`, sending the attachment is optional.
InputValues:
type: object
description: Assembly option content.
additionalProperties: true
nullable: true
Composition:
type: object
description: Assembly option composition.
additionalProperties: true
nullable: true
marketplace:
type: object
description: Details about the marketplace related to the order.
properties:
baseURL:
type: string
description: Marketplace base URL.
isCertified:
type: boolean
nullable: true
description: Defines if it is a [VTEX certified marketplace](https://help.vtex.com/en/tutorial/marketplace-strategies-at-vtex--tutorials_402#integrating-with-a-certified-marketplace) (`true`) or not (`false`).
name:
type: string
description: Marketplace name.
storePreferencesData:
type: object
description: Store's configuration data, stored in [Account settings](https://help.vtex.com/en/tutorial/account-details-page--2vhUVOKfCaswqLguT2F9xq).
properties:
countryCode:
type: string
description: Three-digit country code, in [ISO 3166 ALPHA-3](https://www.iban.com/country-codes) format.
currencyCode:
type: string
description: Currency code in [ISO 4217](https://www.iban.com/currency-codes) format.
currencyFormatInfo:
type: object
description: Object with currency format details.
properties:
CurrencyDecimalDigits:
type: integer
description: Quantity of currency decimal digits.
CurrencyDecimalSeparator:
type: string
description: Defines what currency decimal separator will be applied.
CurrencyGroupSeparator:
type: string
description: Defines what currency group separator will be applied.
CurrencyGroupSize:
type: integer
description: Defines how many characters will be grouped.
StartsWithCurrencySymbol:
type: boolean
description: Defines if all prices will be initiated with the currency symbol (`true`) or not (`false`).
# --- truncated at 32 KB (791 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-orders-openapi-original.yml