This guide explains how to implement a shopping cart and manage the checkout process in a headless ecommerce store, using the Checkout API to handle all interactions through API requests, without a traditional user interface.
A headless store handles all ecommerce integration without a traditional user interface, relying solely on API requests. In this guide, you will learn how to create a shopping cart and manage the checkout flow using features from the Checkout API in your headless store.
New fields can be added in the Checkout API payload without previous warning.
Shopping cart
In the Checkout API, the VTEX shopping cart information is organized using the orderForm, an object containing all information relevant to the purchase, from the products to shipping and payment information, among others.
The orderForm is a complex data structure with many customization possibilities. The essential section for placing an order is divided into items and attachments.
For a customer to make a purchase, the store must have a shopping cart that contains an orderForm for them. When you use the Get current or create a new cart endpoint, you get an orderFormId in the response.
If your headless storefront is not browser-based (e.g., native app), it is important that you save the
orderFormIdand use it to manage the cart's information with the requests above. Otherwise, VTEX cookies will automatically manage this information in the customer's browser.
Cart items
In the orderForm, product information is stored inside items, where each object corresponds to a SKU contained in the cart. Below is a basic example of a shopping cart containing two units of SKU 123, to be fulfilled by seller 1, at a price of $100.00 per unit.
The information above is sufficient to place an order, but there are other possible fields for shopping cart items, many of which are populated by VTEX modules.
To learn how to add products to a shopping cart, read the guide Add cart items.
If the customer leaves the store, make sure you keep the
orderFormIdso you can retrieve their previously abandoned cart with the Get cart information by ID endpoint.
Cart attachments
Shopping cart attachments are orderForm objects containing order information related to the client profile, shipping address and delivery option, marketing data, payment data, and merchant context data. Check a basic example of a cart attachments.
Some attachments may contain arrays of objects, where each object corresponds to an item in the items array.
Place order
There are two ways of placing orders with the Checkout API:
- Place new order: Manage shopping cart information in your frontend and then use one API request to send all order information to VTEX.
- Place order from existing cart: Manage shopping cart information in the VTEX platform throughout the shopping experience, then place an order from that data using just the cart ID.
The place new order method increases the complexity of your application since you must manage all shopping cart data to correctly assemble the orderForm. Additionally, placing a new order does not send shopping cart information to VTEX until the customers complete their purchase.
The place order from existing cart method is recommended in most cases. Use place new order if your operation has specific requirements, such as limiting the number of HTTP requests sent from your storefront.
Place new order
To place a new order without any shopping cart data previously stored on the VTEX platform, use the Place order endpoint.
For a tutorial of this method, check the guide Create a regular order from an existing cart or follow the steps in the Create a regular order using the Checkout API.
Place order from existing cart
You can also place an order from an existing cart, which already has an orderForm structure and a shopping cart ID. To do so, use the Place order from an existing cart endpoint or follow the steps in the Create a regular order from an existing cart guide.
This endpoint may be used to perform tasks such as adding products to a cart or linking shipping information to the order.
Order privacy
During the process of placing the order, merchants need to account for the security and privacy of customer information throughout checkout.
When a new cart is created, a new cookie named CheckoutOrderFormOwnership is sent empty alongside the existing checkout.vtex.com cookie, which contains the cart's orderFormId. This mechanism ensures that only the customer who created the cart has unrestricted access to their personal information.
You need to make requests with the client data to set CheckoutOrderFormOwnership to a value. Without this cookie, the returned order form will have masked personal data such as clientProfileData and shippingData.
Please contact VTEX support to enable this feature in your store. This feature is not available to stores using FastStore.
Add client profile data
Once you created a new cart, use the Get current or create a new cart endpoint to retrieve the created orderForm, as in the example.
Once you have the orderForm, you must add the client data to it. To do so, send the profile data in the Add client profile endpoint request, as in the example.
For more information about this endpoint, check the guide Adding customer profile information to the cart.
After making this request, the CheckoutOrderFormOwnership cookie will be set as a string with encrypted values of the client profile data.
Add address data
Once the client data has been added, it is also important to add the customer address data to the orderForm. This data includes all information about the delivery of the order to the customer. To do so, use the Add shipping address and select delivery option endpoint.
For more information about this endpoint, check the Adding shipping address and delivery options to the cart guide.
When making this request, the CheckoutOrderFormOwnership cookie is updated with this new information.
Unmask orderForm
VTEX Personal Identifiable Information (PII) data is masked by default. This means that when you access a shopper's order history in the VTEX Admin panel or when you request their profile information via API, for example, any PII information returned will be masked.
After adding the client profile data and address data, you can access the previously masked information. Use the Get current or create a new cart endpoint again, but include the latest CheckoutOrderFormOwnership cookie value in the request.
With the correct ownership cookie, both client profile data and address data are unmasked, providing the full details.
Complete order
After placing an order using either of the methods presented above, you will receive an orderId and transactionId in the response body, along with some login values. Your integration must use this information to complete the purchase process within five minutes. This involves sending payment information and then requesting order processing.
Failing to perform these steps within five minutes will cause the order to be automatically canceled and tagged as
incomplete.
Send payment information
To send the payment information to VTEX, use one of these endpoints:
The request body used in this step is based on the order's paymentData attachment. You can get this data from the response of the Get client profile by email, as in the example.
Learn more about these endpoints:
Make sure that all value-related fields match the information sent when placing the order to create a successful request.
Retrieving saved credit cards
In the payment section at checkout, we recommend retrieving the saved credit card information from the customer profile. This can ease the checkout process as the customer would only need to select the chosen credit card and input the CVV (Card Verification Value). This process will only display the last four numbers of a credit card to the customer, making it a secure interaction with the client data.
To check if the customer has any saved cards, use the Get client profile by email endpoint. This endpoint returns the available cards. The card information is displayed in the availableAccounts array, as shown in the examples.
You can enable a checkbox that allows the customer to choose if they want to save the credit card information or not. To learn how to enable it, read the guide Enable the Save user data opt-in.
Cart items
In the orderForm, product information is stored inside items, where each object corresponds to a SKU contained in the cart. Below is a basic example of a shopping cart containing two units of SKU 123, to be fulfilled by seller 1, at a price of $100.00 per unit.
The information above is sufficient to place an order, but there are other possible fields for shopping cart items, many of which are populated by VTEX modules.
To learn how to add products to a shopping cart, read the guide Add cart items.
If the customer leaves the store, make sure you keep the
orderFormIdso you can retrieve their previously abandoned cart with the Get cart information by ID endpoint.
Cart attachments
Shopping cart attachments are orderForm objects containing order information related to the client profile, shipping address and delivery option, marketing data, payment data, and merchant context data. Check a basic example of a cart attachments.
Some attachments may contain arrays of objects, where each object corresponds to an item in the items array.
Place order
There are two ways of placing orders with the Checkout API:
- Place new order: Manage shopping cart information in your frontend and then use one API request to send all order information to VTEX.
- Place order from existing cart: Manage shopping cart information in the VTEX platform throughout the shopping experience, then place an order from that data using just the cart ID.
The place new order method increases the complexity of your application since you must manage all shopping cart data to correctly assemble the orderForm. Additionally, placing a new order does not send shopping cart information to VTEX until the customers complete their purchase.
The place order from existing cart method is recommended in most cases. Use place new order if your operation has specific requirements, such as limiting the number of HTTP requests sent from your storefront.
Place new order
To place a new order without any shopping cart data previously stored on the VTEX platform, use the Place order endpoint.
For a tutorial of this method, check the guide Create a regular order from an existing cart or follow the steps in the Create a regular order using the Checkout API.
Place order from existing cart
You can also place an order from an existing cart, which already has an orderForm structure and a shopping cart ID. To do so, use the Place order from an existing cart endpoint or follow the steps in the Create a regular order from an existing cart guide.
This endpoint may be used to perform tasks such as adding products to a cart or linking shipping information to the order.
Order privacy
During the process of placing the order, merchants need to account for the security and privacy of customer information throughout checkout.
When a new cart is created, a new cookie named CheckoutOrderFormOwnership is sent empty alongside the existing checkout.vtex.com cookie, which contains the cart's orderFormId. This mechanism ensures that only the customer who created the cart has unrestricted access to their personal information.
You need to make requests with the client data to set CheckoutOrderFormOwnership to a value. Without this cookie, the returned order form will have masked personal data such as clientProfileData and shippingData.
Please contact VTEX support to enable this feature in your store. This feature is not available to stores using FastStore.
Add client profile data
Once you created a new cart, use the Get current or create a new cart endpoint to retrieve the created orderForm, as in the example.
Once you have the orderForm, you must add the client data to it. To do so, send the profile data in the Add client profile endpoint request, as in the example.
For more information about this endpoint, check the guide Adding customer profile information to the cart.
After making this request, the CheckoutOrderFormOwnership cookie will be set as a string with encrypted values of the client profile data.
Add address data
Once the client data has been added, it is also important to add the customer address data to the orderForm. This data includes all information about the delivery of the order to the customer. To do so, use the Add shipping address and select delivery option endpoint.
For more information about this endpoint, check the Adding shipping address and delivery options to the cart guide.
When making this request, the CheckoutOrderFormOwnership cookie is updated with this new information.
Unmask orderForm
VTEX Personal Identifiable Information (PII) data is masked by default. This means that when you access a shopper's order history in the VTEX Admin panel or when you request their profile information via API, for example, any PII information returned will be masked.
After adding the client profile data and address data, you can access the previously masked information. Use the Get current or create a new cart endpoint again, but include the latest CheckoutOrderFormOwnership cookie value in the request.
With the correct ownership cookie, both client profile data and address data are unmasked, providing the full details.
Complete order
After placing an order using either of the methods presented above, you will receive an orderId and transactionId in the response body, along with some login values. Your integration must use this information to complete the purchase process within five minutes. This involves sending payment information and then requesting order processing.
Failing to perform these steps within five minutes will cause the order to be automatically canceled and tagged as
incomplete.
Send payment information
To send the payment information to VTEX, use one of these endpoints:
The request body used in this step is based on the order's paymentData attachment. You can get this data from the response of the Get client profile by email, as in the example.
Learn more about these endpoints:
Make sure that all value-related fields match the information sent when placing the order to create a successful request.
Retrieving saved credit cards
In the payment section at checkout, we recommend retrieving the saved credit card information from the customer profile. This can ease the checkout process as the customer would only need to select the chosen credit card and input the CVV (Card Verification Value). This process will only display the last four numbers of a credit card to the customer, making it a secure interaction with the client data.
To check if the customer has any saved cards, use the Get client profile by email endpoint. This endpoint returns the available cards. The card information is displayed in the availableAccounts array, as shown in the examples.
You can enable a checkbox that allows the customer to choose if they want to save the credit card information or not. To learn how to enable it, read the guide Enable the Save user data opt-in.
Process order
Lastly, you must request order processing by using the Process order endpoint after the order's payment is approved. If the payment has not been approved yet, it will return a status code 500 error.
Keep in mind that this process uses the gateway connectors configured in your VTEX environment. Be careful when using it to avoid any unwanted charges or unexpected payment denials.
Verify order status
Once you have successfully placed an order, sent payment information, and requested order processing, you will be able to see the order in the Order management module in VTEX Admin.
You can also use the Get order and List orders endpoints for this purpose. Another way to check the order updates is by integrating Feed v3 and Hook with your store.
Checkout interface
When a customer goes to your store checkout, your frontend implementation must handle several tasks. Follow the sections below to implement these tasks effectively.
Order details
Order details provided by customers at checkout, such as profile information or shipping address, are attachments of the shopping cart.
You must handle this information based on the order placement method you choose. Refer to the corresponding section for detailed instructions:
Address autofill
Implement an address autofill feature using the following endpoint:
Pickup points
Shipping information is added to the order as orderForm attachments. To allow customers to choose nearby pickup points, use the following endpoint:
reCAPTCHA integration does not work in Headless checkout. It only works with stores using Checkout v6.
Learn more
Check these other guides to learn more about building a headless shopping experience using VTEX: