Checkout API
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,PUTorDELETEendpoints) 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.
Common parameters in the documentation
| Parameter name | Description |
|---|---|
{{accountName}} |
Store account name |
{{environment}} |
The environment that will be called. Change for vtexcommercestable or vtexcommmercebeta |
{{X-VTEX-API-AppKey}} |
Located in the headers of the requests, user authentication key |
{{X-VTEX-API-AppToken}} |
Located in the headers of the requests, authentication password |
Endpoints
Shopping cart
| Summary | Method | Path |
|---|---|---|
| Cart simulation | POST | /api/checkout/pub/orderForms/simulation |
| Get current or create a new cart | GET | /api/checkout/pub/orderForm |
| Get cart information by ID | GET | /api/checkout/pub/orderForm/{orderFormId} |
| Remove all items from shopping cart | POST | /api/checkout/pub/orderForm/{orderFormId}/items/removeAll |
| Remove all personal data from shopping cart | GET | /checkout/changeToAnonymousUser/{orderFormId} |
| Update cart items | POST | /api/checkout/pub/orderForm/{orderFormId}/items/update |
| Add cart items | POST | /api/checkout/pub/orderForm/{orderFormId}/items |
| Handle cart items | PATCH | /api/checkout/pub/orderForm/{orderFormId}/items |
| Change price of an SKU in a cart | PUT | /api/checkout/pub/orderForm/{orderFormId}/items/{itemIndex}/price |
| Delete manual price of an SKU in a cart | DELETE | /api/checkout/pub/orderForm/{orderFormId}/items/{itemIndex}/price |
| Ignore profile data on checkout | PATCH | /api/checkout/pub/orderForm/{orderFormId}/profile |
| Cart installments | GET | /api/checkout/pub/orderForm/{orderFormId}/installments |
| Add coupons to the cart | POST | /api/checkout/pub/orderForm/{orderFormId}/coupons |
Cart attachments
| Summary | Method | Path |
|---|---|---|
| Get client profile by email | GET | /api/checkout/pub/profiles |
| Add client profile | POST | /api/checkout/pub/orderForm/{orderFormId}/attachments/clientProfileData |
| Add shipping address and select delivery option | POST | /api/checkout/pub/orderForm/{orderFormId}/attachments/shippingData |
| Add client preferences | POST | /api/checkout/pub/orderForm/{orderFormId}/attachments/clientPreferencesData |
| Add marketing data | POST | /api/checkout/pub/orderForm/{orderFormId}/attachments/marketingData |
| Add payment data | POST | /api/checkout/pub/orderForm/{orderFormId}/attachments/paymentData |
| Add item attachment | POST | /api/checkout/pub/orderForm/{orderFormId}/items/{itemIndex}/attachments/{attachmentName} |
| Remove item attachment | DELETE | /api/checkout/pub/orderForm/{orderFormId}/items/{itemIndex}/attachments/{attachmentName} |
| Add item subscription attachment | POST | /api/checkout/pub/orderForm/{orderFormId}/attachments/subscriptionData |
| Remove item subscription attachment | DELETE | /api/checkout/pub/orderForm/{orderFormId}/attachments/subscriptionData |
| Add merchant context data | POST | /api/checkout/pub/orderForm/{orderFormId}/attachments/merchantContextData |
| Attach invoice data | POST | /api/checkout/pub/orderForm/{orderFormId}/attachments/invoiceData |
Custom data
| Summary | Method | Path |
|---|---|---|
| Set multiple custom field values | PUT | /api/checkout/pub/orderForm/{orderFormId}/customData/{appId} |
| Set single custom field value | PUT | /api/checkout/pub/orderForm/{orderFormId}/customData/{appId}/{appFieldName} |
| Remove single custom field value | DELETE | /api/checkout/pub/orderForm/{orderFormId}/customData/{appId}/{appFieldName} |
| Batch add custom fields | PUT | /api/checkout/pub/orderForm/{orderFormId}/customFields |
| Add order custom field | PUT | /api/checkout/pub/orderForm/{orderFormId}/customFields/order |
| Add item custom field | PUT | /api/checkout/pub/orderForm/{orderFormId}/customFields/item/{itemId} |
| Remove item custom field | DELETE | /api/checkout/pub/orderForm/{orderFormId}/customFields/item/{itemId} |
| Add address custom field | PUT | /api/checkout/pub/orderForm/{orderFormId}/customFields/address/{addressId} |
Configuration
| Summary | Method | Path |
|---|---|---|
| Get order form configuration | GET | /api/checkout/pvt/configuration/orderForm |
| Update order form configuration | POST | /api/checkout/pvt/configuration/orderForm |
| Get window to change seller | GET | /api/checkout/pvt/configuration/window-to-change-seller |
| Update window to change seller | POST | /api/checkout/pvt/configuration/window-to-change-seller |
| Clear order form messages | POST | /api/checkout/pub/orderForm/{orderFormId}/messages/clear |
Fulfillment
| Summary | Method | Path |
|---|---|---|
| List pickup points by location | GET | /api/checkout/pub/pickup-points |
| Get address by postal code | GET | /api/checkout/pub/postal-code/{countryCode}/{postalCode} |
Order placement
| Summary | Method | Path |
|---|---|---|
| Place order from an existing cart | POST | /api/checkout/pub/orderForm/{orderFormId}/transaction |
| Place order | PUT | /api/checkout/pub/orders |
| Process order | POST | /api/checkout/pub/gatewayCallback/{orderGroup} |
Region
| Summary | Method | Path |
|---|---|---|
| Get sellers by region or address | GET | /api/checkout/pub/regions/{regionId} |