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 orderFormId so you can retrieve their previously abandoned cart with the Get cart information by ID endpoint.

Shopping cart attachments are orderForm objects containing order information related to:

• Customer profile
• Shipping address and delivery option
• Marketing data
• Payment data
• Merchant context data

Check on the right side of the screen a basic example of a cart attachment.

Some attachments may contain arrays of objects, where each object corresponds to an item in the items array.

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. You should use this method if your operation has specific requirements, such as limiting the number of HTTP requests sent from your storefront.
• 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. This method is generally recommended.

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.

To place a new order without any shopping cart data previously stored on the VTEX platform, use the Place order endpoint.

For a tutorial on this method, check the guide Creating a regular order with the Checkout API.

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 Creating 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.

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.

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.

After obtaining 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.

The next step is 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.

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.

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 5 minutes. This involves sending payment information and then requesting order processing.

Failing to perform these steps within 5 minutes will cause the order to be automatically canceled and tagged as incomplete.

To forward payment data to VTEX, use the Send payments information endpoint.

The request body used in this step is based on the order's paymentData attachment as in the example.

Make sure that all value-related fields match the information sent when placing the order to create a successful request. If incorrect payment details are provided, the system cannot redirect the user to the Order Confirmation page, thereby interrupting the checkout flow and preventing purchase completion.

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.