In this step, we will verify if your store can fulfill the cart requirements and gather essential order information to ensure a smooth order placement process in the subsequent steps.

This step provides essential information regarding the available delivery and payment options for the specific combination of items in the cart.

• Send a request to the Cart simulation API endpoint. Specify the SKU ID (items.id), the number of items in the cart (items.quantity), the Seller's ID (items.seller), and the shipping address country (country) in the request body. Also, provide the shipping address's postal code (postalCode) or the geo-coordinates (geoCoordinates).
• Take note of the items, shippingData.logisticsInfo, and paymentData objects, as we will use this data in the following steps.

Now, we will verify whether the email that will be used to place the order is already related to a customer in your database. This verification serves to not only enhance operational efficiency but also proactively prevent potential permission-related issues.

• Send a request to the Get client by email endpoint to check for existing profiles associated with a specific email address. If the response to this request returns any content, it means the shopper’s information is in your database. In such cases, you can proceed using this data in subsequent steps, sparing the shopper from the need to provide their email again.
• If applicable, take note of the availableAddresses and userProfile objects, as we will use this data in the following steps.

In this step, we will arrange the order details into the specified data format, following the orderForm data structure. This formatted cart data will be used as the request body in the following steps.

Below, we will briefly examine the key elements that make up the orderForm, which include:

• items
• clientProfileData
• shippingData.address
• shippingData.logisticsInfo
• paymentData

Note that while an orderForm can have multiple elements, a standard order typically consists of the ones mentioned above.

items is an array that contains all data pertinent to the SKUs being purchased. Build the items array using the items array obtained from the Simulating a cart step. For more complex examples, see the Place order API reference.

clientProfileData is an object that contains information about the customer. If you noted the customer does not exist in your database during the Checking for existing customer step, build the clientProfileData object with the data of the new customer willing to place the order.

If the customer already exists in your database, use the userProfile.email obtained in the Checking for existing customer step to build the clientProfileData object. The email address is enough to register the order to the shopper’s existing account.

shippingData.address is an object that contains information about the shipping address. If you noted the customer does not exist in your database during the Checking for existing customer step, build the shippingData.address object with the data of the new customer willing to place the order.

If the customer already exists in your database, use the desired availableAddresses[i].addressId obtained from the Checking for existing customer step to build the shippingData.address block.

logisticsInfo is an array that contains logistics information, such as the desired delivery option and freight cost for each item in the items array.

• Create the logisticsInfo array with the same number of objects as in the items array. For each object within the logisticsInfo array, define the following elements:

  • itemIndex - index of the corresponding item in the items array. For example, the object referring to the first item in the items array has an itemIndex of 0.
  • selectedSla - desired delivery option. You can find the id value of the available options in the slas array obtained from the Simulating a cart step.
  • price - price of the item. You can retrieve this value from the Simulating a cart step.
  • (Optional) If the delivery method is pickup point, add the information "selectedDeliveryChannel": "pickup-in-point".

paymentData.payments is an array that contains information regarding the chosen payment method and installment preferences for the order. Build the paymentData.payments array considering the response obtained from the Simulating a cart step. For each payment option, define the following elements:

• paymentSystem - ID of the desired payment system.
• referenceValue - reference value used to calculate interest rates. If no interest applies to the order, the value and referenceValue should be the same.
• value - total amount to be paid by the shopper.
• installments - number of installments.

For more complex examples, see the Place order API reference.

In this step, we will use the orderForm we built in the previous steps to place an order on the VTEX platform.

After building the orderForm for your order, ensure it adheres to a valid JSON format. For new customers, your orderForm should resemble this structure.

For returning customers, the orderForm for your order should resemble this structure.

Send a request to the Place order endpoint using the orderForm you built as the request body.

Upon receiving a 201 Created response, take note of these four pieces of information:

• orderId - ID of the order within VTEX’s Order Management System (OMS). You can find the orderId within each object in the orders array.
• transactionId - ID of the transaction, which can be found within the objects contained in the transactionData.merchantTransactions array.
• addressId - ID of the customer address. If you plan to use the same address for both shipping and billing, get the addressId from the orders[].shippingData.address object.
• Vtex_CHKO_Auth - authentication cookie provided in the response.

If you are using an email from an existing customer, ensure that the corresponding customer account is logged into your store. Otherwise, the process will fail.

In this step, we will communicate the necessary payment data to VTEX for the finalization of the order's payment.

Starting from the moment the order is placed, you have a window of five minutes to complete the payment process. Failure to do so will result in automatic cancellation, and the order will be labeled as "incomplete."

• Send a request to the Send payments information public endpoint, considering the following:

  • Use the orderId value obtained in the previous step as the orderId query-string parameter.
  • Use the transactionId value obtained in the previous step as a path parameter.
  • Ensure that the request body is based on the paymentData section of your orderForm.
  • In the fields object, use the addressId field to reference an existing address or introduce a new address object for an entirely new address.

If you intend to send saved credit card data, you can use the Send payments with saved credit card endpoint instead.

In this final step, we will process the order.

• Send a request to the Process order endpoint. If the payment is processed without any issues, the order should be successfully placed. Otherwise, a status 500 error might occur.

Note that this process uses the gateway connectors configured in your VTEX environment. Be careful to prevent any unwanted charges or unexpected payment denials.

Finally, you can confirm if your order was correctly placed by checking the Order management in VTEX Admin. Alternatively, you can use the Get order and List orders endpoints for this purpose.