Checkout API
>ℹ️ Check the new [Checkout onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/checkout-overview). We created this guide to improve the…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
>ℹ️ Check the new Checkout onboarding guide. 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.
The 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.
>ℹ️ 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.
>⚠️ 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.
Shopping cart
Allows merchants to simulate, configure and customize shopping cart information.
- POST - Cart Simulation
- GET - Get current or create a new cart
- GET - Get cart information by ID
- POST - Remove all items
- GET - Remove all personal data
- POST - Update cart items
- POST - Add cart items
- PUT - Change price
- PATCH - Ignore profile data
- GET - Cart installments
- POST - Add coupons to the cart
Cart attachments
Allows merchants to obtain client profiles and add information to a given shopping cart.
- GET - Get client profile by email
- POST - Add client profile
- POST - Add shipping address and select delivery option
- POST - Add client preferences
- POST - Add marketing data
- POST - Add payment data
- POST - Add merchant context data
Custom data
Allows merchants to manage custom fields that were created by an app in their account.
- PUT - Set multiple custom field values
- PUT - Set single custom field value
- DELETE - Remove single custom field value
Configuration
Allows merchants to configure orderForm in the account and seller exchange on a given order.
- GET - Get orderForm configuration
- POST - Update orderForm configuration
- GET - Get window to change seller
- POST - Update window to change seller
- POST - Clear orderForm messages
Fulfillment
Allows merchants to obtain pickup points and address information.
Order placement
Allows merchants to place and process orders by creating a new cart or using an existing cart.
- [POST - Place order from an existing…
Endpoints 32
Shopping cart
- GETGet current or create a new cart
/api/checkout/pub/orderForm?forceNewCart=trueYou can use this request to get your current shopping cart information (orderFormId) or to create a new cart. Important: To create a new empty shopping cart… - GETGet cart information by ID
/api/checkout/pub/orderForm/:orderFormId?refreshOutdatedData=trueUse this request to get all information associated to a given shopping cart. The orderForm is the data structure which represents a shopping cart and contains… - POSTAdd coupons to the cart
/api/checkout/pub/orderForm/:orderFormId/couponsUse this request to add coupons to a given shopping cart. - GETCart installments
/api/checkout/pub/orderForm/:orderFormId/installments?paymentSystem=0Retrieves possible amount of installments and respective values for a given cart with a given payment method. The orderForm is the data structure which… - POSTAdd cart items
/api/checkout/pub/orderForm/:orderFormId/items?allowedOutdatedData=paymentDataUse this request to add a new item to the shopping cart. The orderForm is the data structure which represents a shopping cart and contains all information… - POSTRemove all items
/api/checkout/pub/orderForm/:orderFormId/items/removeAllThis request removes all items from a given cart, leaving it empty. You must send an empty JSON in the body of the request. The orderForm is the data… - POSTUpdate cart items
/api/checkout/pub/orderForm/:orderFormId/items/update?allowedOutdatedData=paymentDataYou can use this request to: 1. Change the quantity of one or more items in a specific cart. 2. Remove an item from the cart (by sending the quantity value =… - PUTChange price
/api/checkout/pub/orderForm/:orderFormId/items/:itemIndex/priceThis request changes the price of an SKU in a cart. You can also perform type of bulk price change with the Update cart items request The orderForm is the… - PATCHIgnore profile data
/api/checkout/pub/orderForm/:orderFormId/profileWhen a shopper provides an email address at Checkout, the platform tries to retrieve existing profile information for that email and add it to the shopping… - POSTCart simulation
/api/checkout/pub/orderForms/simulation?RnbBehavior=0&sc=1This endpoint is used to simulate a cart in VTEX Checkout. It receives an SKU ID, the quantity of items in the cart and the ID of the Seller. It sends back… - GETRemove all personal data
/checkout/changeToAnonymousUser/:orderFormIdThis call removes all user information, making a cart anonymous while leaving the items. The orderForm is the data structure that represents a shopping cart…
Cart attachments
- POSTAdd client preferences
/api/checkout/pub/orderForm/:orderFormId/attachments/clientPreferencesDataUse this request to include client preferences information to a given shopping cart. The orderForm is the data structure which represents a shopping cart and… - POSTAdd client profile
/api/checkout/pub/orderForm/:orderFormId/attachments/clientProfileDataUse this request to include client profile information to a given shopping cart. The orderForm is the data structure which represents a shopping cart and… - POSTAdd marketing data
/api/checkout/pub/orderForm/:orderFormId/attachments/marketingDataUse this request to include marketing information to a given shopping cart. The orderForm is the data structure which represents a shopping cart and contains… - POSTAdd merchant context data
/api/checkout/pub/orderForm/:orderFormId/attachments/merchantContextDataThis endpoint is used for the merchant to add to the cart any relevant information that is related to the context of a specific order. The orderForm is the… - POSTAdd payment data
/api/checkout/pub/orderForm/:orderFormId/attachments/paymentDataUse this request to include payment information to a given shopping cart. The payment information attachment in the shopping cart does not determine the final… - POSTAdd shipping address and select delivery option
/api/checkout/pub/orderForm/:orderFormId/attachments/shippingDataUse this request to include shipping information and/or selected delivery option to a given shopping cart. To add shipping addresses send the… - GETGet client profile by email
/api/checkout/pub/profiles?email=clark.kent@examplemail.comRetrieve a client's profile information by providing an email address. If the response body fields are empty, the following situations may have occurred: 1.…
Custom data
- PUTSet multiple custom field values
/api/checkout/pub/orderForm/:orderFormId/customData/:appIdYour account may create apps, which contain custom fields, through the Update orderForm configuration request. The values of these custom fields can then be… - PUTSet single custom field value
/api/checkout/pub/orderForm/:orderFormId/customData/:appId/:appFieldNameYour account may create apps, which contain custom fields, through the Update orderForm configuration request. The value of a specific custom field can then… - DELETERemove single custom field value
/api/checkout/pub/orderForm/:orderFormId/customData/:appId/:appFieldNameYour account may create apps, which contain custom fields, through the Update orderForm configuration request. The value of a specific custom field can be…
Configuration
- POSTClear orderForm messages
/api/checkout/pub/orderForm/:orderFormId/messages/clearThis request removes all messages from the messages field of the orderForm , leaving it empty. You must send an empty JSON in the body of the request. The… - GETGet orderForm configuration
/api/checkout/pvt/configuration/orderFormRetrieves the settings that are currently applied to every orderForm in the account. These settings are defined by the request Update orderForm configuration.… - POSTUpdate orderForm configuration
/api/checkout/pvt/configuration/orderFormDetermines settings that will apply to every orderForm in the account. For example, if you create an app using this request, every orderForm of this account… - GETGet window to change seller
/api/checkout/pvt/configuration/window-to-change-sellerRetrieves 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… - POSTUpdate window to change seller
/api/checkout/pvt/configuration/window-to-change-sellerUpdates 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…
Fulfillment
- GETList pickup points by location
/api/checkout/pub/pickup-points?geoCoordinates=-47.924747467041016,-15.832582473754885&postalCode=1234000&countryCode=BRARetrieves information on pickup points close to a given location determined by geocoordinates or postal code. The pickup points returned are not necessarily… - GETGet address by postal code
/api/checkout/pub/postal-code/:countryCode/:postalCodeRetrieves address information for a given postal code and country. This request can be used to implement auto complete functionality when a customer needs to…
Order placement
- POSTProcess order
/api/checkout/pub/gatewayCallback/:orderGroupOrder processing callback request, which is made after an order's payment is approved. > This request has to be made until five minutes after the Place order… - POSTPlace order from an existing cart
/api/checkout/pub/orderForm/:orderFormId/transactionThis endpoint places an order from an existing orderForm object, meaning an existing cart. After the creation of an order with this request, you have five… - PUTPlace order
/api/checkout/pub/orders?sc=1Places order without having any prior cart information. This means all information on items, client, payment and shipping must be sent in the body. >⚠️ The…
Region
- GETGet sellers by region or address
/api/checkout/pub/regions/:regionId?country=BRA&postalCode=1234000&geoCoordinates=-47.924747467041016,-15.832582473754885Retrieve a list of sellers that cater to a specific region or address, according to your set up of our regionalization feature. Learn more about Region v2. To…
API details
- Base URL
https://vtex.localhttps://{accountName}.{environment}.com.br- Authentication
- An API key in the X-VTEX-API-AppKey header
An API key in the X-VTEX-API-AppToken header - Operations
- 32 operations on 29 pathsPOST 16GET 10PUT 4PATCH 1DELETE 1
- Main resources
- Shopping cart 11Cart attachments 7Configuration 5Custom data 3Order placement 3Fulfillment 2Region 1
- Response formats
application/jsontext/plain- Description format
- OpenAPI 3.0.0, API version
1.0 - Links
- OpenAPI document
- Listed from
- APIs.guru OpenAPI Directory (CC0-1.0)
Source updated
How to test the Checkout API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Checkout API collection, without the publisher's secrets.
- Add your credentialsThis API uses an API key in the X-VTEX-API-AppKey header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Get current or create a new cart” (GET /api/checkout/pub/orderForm?forceNewCart=true), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Checkout API?
>ℹ️ Check the new [Checkout onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/checkout-overview). We created this guide to improve the… It is listed under Other and has 32 endpoints.
Who publishes the Checkout API?
It is listed from VTEX's public API description (an OpenAPI document), not published by VTEX on Swastik Codes. Anyone who controls vtex.com can claim the profile by adding a DNS TXT record.
What is the base URL of the Checkout API?
Its description lists 2 base URLs: https://vtex.local, https://{accountName}.{environment}.com.br. The first is the usual one; the others are typically sandbox or regional servers.
How do I authenticate with the Checkout API?
It accepts 2 methods: an API key in the X-VTEX-API-AppKey header; an API key in the X-VTEX-API-AppToken header.
How many endpoints does the Checkout API have?
32 operations on 29 paths (16 POST, 10 GET, 4 PUT, 1 PATCH, 1 DELETE). The largest groups are Shopping cart, Cart attachments, Configuration, Custom data.
Is forking the Checkout API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.