In this step, we will verify that your store can fulfill the cart requirements and collect the essential order details necessary to ensure a smooth order placement process in the subsequent steps.

Use the Cart simulation endpoint to obtain the available delivery and payment options for the current cart configuration. In this request, you must provide the following information in the request body:

• items.id: SKU ID.
• items.quantity: The number of items in the cart.
• items.seller: Seller's ID.
• country: Three-letter ISO code of the country of the shipping address.
• postalCode or geoCoordinates: Shipping address's postal code or geocoordinates.

Upon receiving a 200 OK response, the request will provide a response body containing all information about the cart. Take note of the following information, as it will be used in the following steps:

• items
• paymentData
• logisticsInfo

Send a request to the Get client by email endpoint to ensure a customer profile exists in your database associated with the email to be used in the order.

Upon receiving a 200 OK response, the request will provide a response body containing all information about the customer profile. Take note of the following information, as it will be used in the following steps:

• availableAddresses
• userProfile

If the response body fields are empty in this request, it may indicate that no customer is registered under this email, or that the customer profile is invalid or incomplete. In this case, you can use a different email address or enter data for a new customer when assembling the cart.

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

While an orderForm may include various elements, a standard order generally comprises the key components described 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.

Before creating the new order, it is necessary to verify that the orderForm created in the previous steps has the appropriate structure in a valid JSON format.

If the orderForm was created for a new customer (not yet registered in the store's database), it should follow this structure.

If the orderForm was created for an existing customer who already has a customer profile registered in the store's database, it should follow this structure.

Place a new order via the Place order endpoint using the orderForm you built as the request body.

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

• transactionId - ID of the transaction, which can be found within an object contained in the merchantTransactions array.
• orderId - ID of the order within VTEX’s Order Management System (OMS). You can find the orderId within each object in the orders array.
• orderGroup - ID that groups all orders related to the same purchase. For example, when an order is fulfilled by multiple sellers, each seller has its own order ID (v71021570str-01 and v71021570str-02), but they share the same order group ID (v71021570str).
• 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.

Now, we will communicate the necessary payment data to VTEX to finalize the order payment.

Starting from the moment the order is placed, you have 5 minutes to submit the payment information and process the order (Step 4). If the payment information and order are not submitted and processed within 5 minutes, the order will be automatically canceled.

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

  • Use the transactionId value from the previous step as both the path parameter and the value for the id field within the transaction object.
  • Set the merchantName field within the transaction object to your account name.
  • Use the orderId value from the previous step as a query string parameter.
  • Ensure that the request body is based on the paymentData section of your orderForm.
  • In the fields object, you can:
    • Fill in the credit or debit card information (when applicable).
    • Use the addressId field to reference an existing address, or provide a new address object for an entirely new address. This type of information is only required if the shopper's address was not previously entered during checkout.

This request does not return any data in the response body, only a 201 Created success confirmation message.

In this final step, we will process the order.

• Send a request to the Process order endpoint, using the orderGroup value as a path parameter.

If the payment is processed without any issues, the order should be successfully placed (204 No Content status). Otherwise, a 500 Internal Server Error message 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.