The VTEX Checkout API manages the complete checkout lifecycle for VTEX stores. It handles cart management, order simulation, address validation, payment selection, order placement, and cart attachment operations. This API is central to the purchase flow in any VTEX storefront.
openapi: 3.0.0
info:
title: VTex Checkout API
description: ">ℹ️ Check the new [Checkout onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/checkout-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about the Checkout and is organized by focusing on the developer's journey.\r\n\r\nThe Checkout API allows you to obtain and configure information about the shopping cart and its attachments, personalization of custom fields, orderForm structure, fulfillment data, order management, and identification of the sellers delivery region.\r\n\r\n>ℹ️ Data modification operations (`POST`, `PATCH`, `PUT` or `DELETE` endpoints) shall not be performed in parallel in the Checkout APIs. They need to be enqueued by the client/requester. Otherwise, old values can be overwritten incorrectly or competition errors may occur.\r\n\r\n>⚠️ All endpoints that consult or edit the orderForm can change the authentication depending on the customer context. If you are handling information from a customer with a complete profile on the store, authentication will be required. You can only access or modify the customer data for these profiles with an authenticated request.\r\n\r\n## Shopping cart\r\n\r\nAllows merchants to simulate, configure and customize shopping cart information.\r\n\r\n- [POST - Cart Simulation](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForms/simulation): simulate a cart in VTEX Checkout.\r\n- [GET - Get current or create a new cart](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/orderForm): get your current shopping cart information or to create a new cart.\r\n- [GET - Get cart information by ID](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/orderForm/-orderFormId-): get all information associated to a given shopping cart.\r\n- [POST - Add cart items](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/items): add a new item to the shopping cart.\r\n- [POST - Update cart items](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/items/update): change the quantity of one or more items in a specific cart or remove an item from the cart.\r\n- [PATCH - Handle cart items](https://developers.vtex.com/docs/api-reference/checkout-api#patch-/api/checkout/pub/orderForm/-orderFormId-/items): change the quantity or price of one or more items to the shopping cart or add a new item to the shopping cart.\r\n- [POST - Remove all items](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/items/removeAll): removes all items from a given cart, leaving it empty.\r\n- [PUT - Change price](https://developers.vtex.com/docs/api-reference/checkout-api#put-/api/checkout/pub/orderForm/-orderFormId-/items/-itemIndex-/price): changes the price of an SKU in a cart.\r\n- [GET - Cart installments](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/orderForm/-orderFormId-/installments): retrieves possible amount of installments and respective values for a given cart with a given payment method.\r\n\r\n## Cart attachments\r\n\r\nAllows merchants to obtain client profiles and add information to a given shopping cart.\r\n\r\n- [GET - Get client profile by email](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/profiles): retrieve a client's profile information by providing an email address.\r\n- [POST - Add client profile](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/attachments/clientProfileData): include client profile information to a given shopping cart.\r\n- [Patch - Ignore profile data](https://developers.vtex.com/docs/api-reference/checkout-api#patch-/api/checkout/pub/orderForm/-orderFormId-/profile): disable the automatic inclusion of profile information in a shopping cart when a shopper provides
an email address at checkout.\r\n- [GET - Remove all personal data](https://developers.vtex.com/docs/api-reference/checkout-api#get-/checkout/changeToAnonymousUser/-orderFormId-): removes all user information, making a cart anonymous while leaving the items.\r\n- [POST - Add client preferences](https://developers.vtex.com/docs/api-reference/checkout-api#patch-/api/checkout/pub/orderForm/-orderFormId-/items): include client preferences information to a given shopping cart.\r\n- [POST - Add shipping address and select delivery option](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/attachments/shippingData): include shipping information and/or selected delivery option to a given shopping cart.\r\n- [POST - Add marketing data](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/attachments/marketingData): include marketing information to a given shopping cart.\r\n- [POST - Add payment data](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/attachments/paymentData): include payment information to a given shopping cart.\r\n- [POST - Add merchant context data](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/attachments/merchantContextData): add to the cart any relevant information that is related to the context of a specific order.\r\n- [POST - Add coupons to the cart](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/coupons): add coupons to a given shopping cart.\r\n\r\n## Custom data\r\n\r\nAllows merchants to manage custom fields that were created by an app in their account.\r\n\r\n- [PUT - Set multiple custom field values](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/coupons): allows you to update the values of custom fields created in your account's apps.\r\n- [PUT - Set single custom field value](https://developers.vtex.com/docs/api-reference/checkout-api#put-/api/checkout/pub/orderForm/-orderFormId-/customData/-appId-/-appFieldName-): allows you to update the value of a specific custom field created in your account's apps.\r\n- [DELETE - Remove single custom field value](https://developers.vtex.com/docs/api-reference/checkout-api#delete-/api/checkout/pub/orderForm/-orderFormId-/customData/-appId-/-appFieldName-): allows you to remove the value of a specific custom field created in your account's apps.\r\n\r\n## Configuration\r\n\r\nAllows merchants to configure orderForm in the account and seller exchange on a given order.\r\n\r\n- [GET - Get orderForm configuration](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pvt/configuration/orderForm): retrieves the settings that are currently applied to every [`orderForm`](https://developers.vtex.com/docs/guides/orderform-fields) in the account.\r\n- [POST - Update orderForm configuration](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pvt/configuration/orderForm): determines settings that will apply to every [`orderForm`](https://developers.vtex.com/docs/guides/orderform-fields) in the account.\r\n- [GET - Get window to change seller](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pvt/configuration/window-to-change-seller): retrieves a marketplace’s window to change seller.\r\n- [POST - Update window to change seller](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pvt/configuration/window-to-change-seller): updates a marketplace’s window to change seller.\r\n- [POST - Clear orderForm messages](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/messages/clear): removes all messages from the `messages` field of the [`orderForm`](https://developers.vtex.com/docs/guides/orderform-fields).\r\n\r\n## Fulfillment\r\n\r\nAllows merchants to obtain pickup points
and address information.\r\n\r\n- [GET - List pickup points by location](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/pickup-points): retrieves information on pickup points close to a given location determined by geocoordinates or postal code.\r\n- [GET - Get address by postal code](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/postal-code/-countryCode-/-postalCode-): retrieves address information for a given postal code and country.\r\n\r\n## Order placement\r\n\r\nAllows merchants to place and process orders by creating a new cart or using an existing cart.\r\n\r\n- [POST - Place order from an existing cart](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/transaction): places an order from an existing [`orderForm`](https://developers.vtex.com/docs/guides/orderform-fields) object, meaning an existing cart.\r\n- [PUT - Place order](https://developers.vtex.com/docs/api-reference/checkout-api#put-/api/checkout/pub/orders): places order without having any prior cart information.\r\n- [POST - Process order](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/gatewayCallback/-orderGroup-): order processing callback request, which is made after an order's payment is approved.\r\n\r\n## Region\r\n\r\nAllows merchants to obtain a list of sellers serving a specific delivery region.\r\n\r\n- [GET - Get sellers by region or address](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/regions/-regionId-)\": retrieves a list of sellers that cater to a specific region or address.\r\n\r\n## Common parameters in the documentation\r\n\r\n| Parameter name | Description |\r\n|---------------------------|-----------------------------------------------------------------------------------------|\r\n| `{{accountName}}` | Store account name |\r\n| `{{environment}}` | The environment that will be called. Change for vtexcommercestable or vtexcommmercebeta |\r\n| `{{X-VTEX-API-AppKey}}` | Located in the headers of the requests, user authentication key |\r\n| `{{X-VTEX-API-AppToken}}` | Located in the headers of the requests, authentication password |\r\n"
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/checkout/pub/orderForms/simulation:
post:
tags:
- Shopping Cart
summary: VTex Cart simulation
description: "This endpoint is used to simulate a cart in VTEX Checkout.\r\n\r\nIt receives an SKU ID, the quantity of items in the cart and the seller ID.\r\n\r\nIt returns all information about the cart, such as the selling price of each item, pricing and promotion data, payment and logistics info.\r\n\r\nThis request is useful whenever you need to know the availability of fulfilling an order for a specific cart setting, since the API response will let you know the updated price, inventory and shipping data.\r\n\r\n>⚠️ The fields (`sku id`, `quantity`, `seller`, `country`, `postalCode` and `geoCoordinates`) are just examples of content that you can simulate in your cart. You can add more fields to the request as per your need. Access the [orderForm](https://developers.vtex.com/docs/guides/orderform-fields) guide to check the available fields.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3)."
operationId: CartSimulation
security: []
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
- name: RnbBehavior
in: query
description: "This parameter defines which promotions apply to the simulation. Use `0` for simulations at cart stage, which means all promotions apply. In case of window simulation use `1`, which indicates promotions that apply nominal discounts over the total purchase value shouldn't be considered on the simulation.\n\r\n\rNote that if this not sent, the parameter is `1`."
required: false
style: form
schema:
type: integer
example: 0
- name: sc
in: query
description: Trade Policy (Sales Channel) identification.
required: false
style: form
schema:
type: integer
example: 1
requestBody:
content:
application/json:
schema:
type: object
required:
- id
- quantity
- seller
properties:
items:
type: array
description: Array containing information about the SKUs inside the cart to be simulated.
items:
type: object
description: SKU information.
properties:
id:
type: string
description: The SKU ID.
example: '1'
quantity:
type: integer
format: int32
description: The quantity of items of this specific SKU in the cart to be simulated.
example: 1
seller:
type: string
description: The ID of the seller responsible for this SKU. This ID can be found in your VTEX Admin.
example: '1'
country:
type: string
description: Three letter ISO code of the country of the shipping address. This value must be sent along with the `postalCode` or `geoCoordinates` values.
example: BRA
postalCode:
type: string
description: Postal code.
example: 12345-000
geoCoordinates:
type: array
description: Array containing two floats with geocoordinates, first longitude, then latitude.
example:
- -47.924747467041016
- -15.832582473754883
items:
description: Geocoordinates.
type: number
example: -47.924747467041016
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
items:
type: array
description: Information on each item in the cart.
items:
type: object
description: Object containing information of the item.
properties:
id:
type: string
description: ID of the item.
requestIndex:
type: integer
description: Request index information.
quantity:
type: integer
description: The quantity of the item the cart.
seller:
type: string
description: The seller responsible for the SKU.
sellerChain:
type: array
description: Sellers involved in the chain. The list should contain only one seller, unless it is a [Multilevel Omnichannel Inventory](https://help.vtex.com/en/tutorial/multilevel-omnichannel-inventory--7M1xyCZWUyCB7PcjNtOyw4) order.
items:
type: string
description: Seller.
tax:
type: integer
description: Tax value in cents.
taxCode:
type: string
description: A unique identifier code assigned to a tax within the VTEX Admin.
priceValidUntil:
type: string
description: Price expiration date and time.
price:
type: integer
description: Price in cents.
listPrice:
type: integer
description: List price in cents.
rewardValue:
type: integer
description: Reward value in cents.
sellingPrice:
type: integer
description: Selling price in cents. Note that this field may be subject to rounding discrepancies. We recommend retrieving data from the `priceDefinition` data structure instead.
offerings:
type: array
description: Array containing offering information of SKU service. A service is an item that may come with a product, optionally and with cost. It is used to assign a value of an additional service itself to an SKU.
items:
type: object
description: Service general information.
properties:
type:
type: string
description: Service type.
id:
type: string
description: Service type ID.
name:
type: string
description: Name of the service type.
allowGiftMessage:
type: boolean
description: Option to display the service type on the gift card.
attachmentOfferings:
type: array
description: Array of attachments that will be added to the service type. The attachment is used to add customized information to the service.
items:
type: string
description: Attachment of the product.
price:
type: integer
description: Service type price.
priceTags:
type: array
description: Array of price tags, each of which, modifies the price in some way, like discounts or rates that apply to the item in the context of the order.
items:
type: object
description: Price tag information.
properties:
name:
type: string
description: Price tag name.
value:
type: integer
description: Price tag value.
rawValue:
type: integer
description: Price tag raw value.
isPercentual:
type: boolean
description: Indicates whether price tag value is applied through a percentage.
identifier:
type: string
description: Price tag identifier.
nullable: true
owner:
type: string
description: Identification of the responsible for the price tag.
measurementUnit:
type: string
description: Measurement unit.
unitMultiplier:
type: integer
description: Unit multiplier.
parentItemIndex:
type: integer
description: Parent item index.
nullable: true
parentAssemblyBinding:
type: string
description: Parent assembly binding.
nullable: true
availability:
type: string
description: Availability.
priceDefinition:
type: object
description: Price information for all units of a specific item.
properties:
calculatedSellingPrice:
type: integer
description: Item's calculated unitary selling price in cents.
total:
type: integer
description: Total value for all units of the item in cents.
sellingPrices:
type: array
description: Array of objects, each containing value (in cents) and quantity for the different rounding instances that can be combined to form the correctly rounded total.
items:
type: object
description: Item value and rounding quantity.
properties:
value:
type: integer
description: Value in cents for that specific rounding.
quantity:
type: integer
description: Rounding quantity, meaning how many items are rounded to this value.
ratesAndBenefitsData:
type: object
description: Information on pricing and promotions that apply to the order.
properties:
rateAndBenefitsIdentifiers:
type: array
description: List with pricing and promotions identifiers.
items:
type: string
description: Promotion identifier.
teaser:
type: array
description: List with pricing and promotions teaser.
items:
type: string
description: Promotion teaser.
paymentData:
type: object
description: Payment data information.
properties:
installmentOptions:
type: array
description: List of Installment options.
items:
type: object
description: Information about the installment option.
properties:
paymentSystem:
type: integer
description: Payment system identification.
bin:
type: string
description: Card bin.
nullable: true
paymentName:
type: string
description: Payment name.
nullable: true
paymentGroupName:
type: string
description: Payment group name.
nullable: true
value:
type: integer
description: Total value assigned to this payment.
installments:
type: array
description: Installment information.
items:
type: object
description: Installment information.
properties:
count:
type: integer
description: Count information.
hasInterestRate:
type: boolean
description: Indicates whether the payment has interest.
interestRate:
type: integer
description: Interest rate value.
value:
type: integer
description: Value of the order without the interest rate. The value is shown without separating cents.
total:
type: integer
description: Total value of the order without separating cents. For example, $24.99 is represented `2499`.
sellerMerchantInstallments:
type: array
description: Seller merchant installments information.
items:
type: object
description: Installment information.
paymentSystems:
type: array
description: Information on payment systems.
items:
type: object
description: Payment system information.
properties:
id:
type: integer
description: Payment system ID.
name:
type: string
description: Payment system name.
groupName:
type: string
description: Payment group name.
validator:
type: object
description: Payment system validator.
nullable: true
stringId:
type: string
description: String ID.
template:
type: string
description: Template.
requiresDocument:
type: boolean
description: Indicates whether a document is required.
displayDocument:
type: boolean
description: Indicates whether a document is shown.
isCustom:
type: boolean
description: Indicates whether it is custom.
description:
type: string
description: Description.
requiresAuthentication:
type: boolean
description: Indicates whether a authentication is required.
dueDate:
type: string
description: Payment due date.
availablePayments:
type: string
description: Availability of payment.
nullable: true
payments:
type: array
description: Information on each payment.
items:
type: string
description: Payment information.
giftCards:
type: array
description: Gift card information, if it applies to the order.
items:
type: string
description: Gift card.
giftCardMessages:
type: array
description: Array of gift card messages.
items:
type: string
description: Gift card message.
availableAccounts:
type: array
description: Available accounts.
items:
type: string
description: Available account.
availableTokens:
type: array
description: Available tokens.
items:
type: string
description: Available token.
availableAssociations:
type: object
description: Available associations.
selectableGifts:
type: array
description: Array containing the data of the items selected as a gift.
items:
type: string
description: Selected gift item.
marketingData:
type: object
description: Object containing promotion data such as coupon tracking information and internal or external UTMs.
nullable: true
postalCode:
type: string
description: Postal code.
nullable: true
country:
type: string
description: Three letter ISO code of the country of the shipping address.
logisticsInfo:
type: array
description: Array with logistics information on each item of the `items` array in the `orderForm`.
items:
description: Logistics information of a item.
type: object
properties:
itemIndex:
type: integer
description: Index of item in items array.
addressId:
type: string
description: Address ID.
nullable: true
selectedSla:
type: string
description: Selected SLA. For example, `"normal"` or `"express"`.
nullable: tr
# --- truncated at 32 KB (618 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-checkout-openapi-original.yml