Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
All 92 tools →
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/vtex-orders-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Vtex Orders API
version: '1.0'
contact: {}
description: 'Operations tagged Orders across 2 of this provider''s published API definitions: vtex-orders-openapi-original.yml, vtex-orders-pii-openapi-original.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{accountName}.{environment}.com.br
description: VTEX server URL.
variables:
accountName:
description: Name of the VTEX account. Used as part of the URL.
default: apiexamples
environment:
description: Environment to use. Used as part of the URL.
enum:
- vtexcommercestable
default: vtexcommercestable
security:
- appKey:
- '{{appKey}}'
appToken:
- '{{appToken}}'
tags:
- name: Orders
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. \n\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). \n\n> **Onboarding guide** \n>\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. \n\n## Permissions\n\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:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| OMS | OMS access | **List Orders** |\n| Checkout | CheckoutResources | **Orders Full Access** |\n\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\n\n| **Role** | **Resource** | \n| --------------- | ----------------- | \n| OMS - Full access | List Orders |\n| Checkout Admin | List Orders |\n| IntegrationProfile - Fulfillment Oms | List Orders |\n| OMS - Full access | Orders Full Access |\n| Checkout Admin | Orders Full Access |\n| IntegrationProfile - Fulfillment Oms | Orders Full Access |\n\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm). \n\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication)."
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
- 'null'
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
- 'null'
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
- 'null'
description: Reason for order cancellation.
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
- 'null'
description: Information about order cancellation, when applicable.
properties:
RequestedByUser:
type:
- boolean
- 'null'
description: Indicates if the order cancellation was requested by the customer (`true`) or not (`false`).
RequestedBySystem:
type:
- boolean
- 'null'
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.
RequestedBySellerNotification:
type:
- boolean
- 'null'
description: Indicates if the order cancellation was requested by the seller (`true`) or not (`false`).
RequestedByPaymentNotification:
type:
- boolean
- 'null'
description: Indicates if the order cancellation was requested by the payment gateway (`true`) or not (`false`).
Reason:
type:
- string
- 'null'
description: Reason why the order was cancelled.
CancellationDate:
type:
- string
- 'null'
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`.
taxData:
type:
- object
- 'null'
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.
subscriptionData:
type:
- object
- 'null'
description: Information about [subscriptions](https://help.vtex.com/tutorial/how-subscriptions-work--frequentlyAskedQuestions_4453), when applicable.
properties:
SubscriptionGroupId:
type:
- string
- 'null'
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.
Subscriptions:
type:
- array
- 'null'
description: List with subscriptions details.
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
- 'null'
description: Subscriptions' ending date with the format `yyyy-mm-ddThh:mm:ss`.
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
- 'null'
description: '[Assembly options](https://help.vtex.com/en/tutorial/assembly-options--5x5FhNr4f5RUGDEGWzV1nH) information related to the item, if there are any.'
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
- 'null'
description: Assembly option content.
additionalProperties: true
Composition:
type:
- object
- 'null'
description: Assembly option composition.
additionalProperties: true
marketplace:
type: object
description: Details about the marketplace related to the order.
properties:
baseURL:
type: string
description: Marketplace base URL.
isCertified:
type:
- boolean
- 'null'
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`).
currencyLocale:
type: integer
description: Currency Locale Code in [LCID](https://learn.microsoft.com/en-us/openspecs/office_standards/ms-oe376/6c085406-a698-4e12-9d4d-c3b0ee3dbc4a) format.
currencySymbol:
type: string
description: Currency symbol.
timeZone:
type: string
description: Time zone from where the order was made.
customData:
type:
- string
- 'null'
description: Custom information in the order. This field is useful for storing data not included in other fields, for example, a message for a gift or a name to be printed in a shirt.
commercialConditionData:
type:
- string
- 'null'
description: Information about commercial conditions.
openTextField:
type:
- string
- 'null'
description: "Optional field with additional information about the order. This field must be filled in using the following format: \n```\n{\n \"fieldExample\": \"ValueExample\"\n }\n```\n."
invoiceData:
type:
- object
- 'null'
description: Order's invoice information.
properties:
address:
type: object
description: Invoice information.
properties:
postalCode:
type: string
description: Postal code of the order's invoice address.
city:
type: string
description: City of the order's invoice address.
state:
type: string
description: State of the order's invoice address.
country:
type: string
description: Three-digit country code of the order's invoice address in [ISO 3166 ALPHA-3](https://www.iban.com/country-codes) format.
street:
type: string
description: Street of the order's invoice address.
number:
type: string
description: Number of the building of the order's invoice address.
neighborhood:
type: string
description: Neighborhood of the order's invoice address.
complement:
type:
- string
- 'null'
description: Complement to the order's invoice address, such as apartment number.
reference:
type:
- string
- 'null'
description: Additional information to help locate the order's invoice address.
settleInvoices:
type: array
description: Number of settled invoice.
items:
type: string
description: Settled invoices numeric identifiers.
changesAttachment:
type: object
description: Information about changes in the order.
properties:
id:
type: string
description: Object ID, the expected value is `changeAttachment`.
# --- truncated at 32 KB (404 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-orders-api-openapi.yml