openapi: 3.0.0
info:
title: VTex Anti-fraud Provider Account Orders API
description: ">ℹ️ Onboarding guide\r\n>\r\n> Check the new [Payments onboarding guide](https://developers.vtex.com/docs/guides/payments-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Payments and is organized by focusing on the developer's journey.\r\n\r\nThe Anti-fraud Provider Protocol is a set of definitions to help you integrate your anti-fraud service API into VTEX platform.\r\n\r\nTo achieve this, you need to implement a web API (REST) following the specifications described in this documentation.\r\n\r\n>⚠️ You can also access our [template on GitHub](https://github.com/vtex-apps/antifraud-provider-example) to help you quickly develop your anti-fraud connector using the Anti-fraud Provider Protocol and VTEX IO.\r\n\r\nTo learn more about the Anti-fraud Provider Protocol, check our [developer guide](https://developers.vtex.com/docs/guides/how-the-integration-protocol-between-vtex-and-antifraud-companies-works).\r\n\r\n## Anti-fraud Provider API Index\r\n\r\n### Anti-fraud Flow\r\n\r\n- `POST` [Send Anti-fraud Pre-Analysis Data (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/pre-analysis)\r\n- `POST` [Send Anti-fraud Data](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/transactions)\r\n- `PUT` [Update Anti-fraud Transactions (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#put-/transactions/-transactionId-)\r\n- `GET` [List Anti-fraud Provider Manifest](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/manifest)\r\n- `GET` [Get Anti-fraud Status](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/transactions/-transactions.id-)\r\n- `DELETE` [Stop Anti-fraud Analysis (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#delete-/transactions/-transactions.Id-)\r\n\r\n### OAuth Flow\r\n\r\n1. `POST` [Retrieve Token](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/authorization/token)\r\n2. `GET` [Redirect](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/redirect)\r\n3. `GET` [Return to VTEX](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorizationCode)\r\n4. `GET` [Get Credentials](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorization/credentials)"
version: '1.0'
servers:
- url: https://{providerApiEndpoint}
description: Anti-fraud provider endpoint URL.
variables:
providerApiEndpoint:
description: Anti-fraud provider endpoint URL.
default: '{providerApiEndpoint}'
tags:
- name: 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. \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`).
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
nullable: true
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
nullable: true
description: Information about commercial conditions.
openTextField:
type: string
description: "Optional field with additional information about the order. This field must be filled in using the following format: \n\r```\n\r{\r\n \"fieldExample\": \"ValueExample\"\r\n }\n\r```\n\r."
nullable: true
invoiceData:
type: object
description: Order's invoice information.
nullable: true
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
# --- truncated at 32 KB (389 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-orders-api-openapi.yml