The Checkout module handles customer purchase information.

Checkout adds different details needed to create an order, such as customer profile, address, shipping, and item information.

The OrderForm is the structure that contains this clustered data. It has several sections, each with helpful information that can be accessed, manipulated, and changed. To learn more, read the OrderForm documentation.

The checkout module encapsulates all requests that modify the orderForm and adds a cancellation behavior for subsequent requests.

Thus, subsequent requests to perform the same operation cause the abort of the previous request for the same operation. This means that if 3 successive requests are made for the same operation, the first 2 will be aborted, and only the third will be considered. For this reason, if more than one consumer uses the same Checkout instance, requests may be unintentionally aborted.

Consider the following scenario:

• Application A creates variable API = new vtexjs.Checkout()

• Plugin B uses API.sendAttachment() to send an address

• Plugin C uses API.sendAttachment() to simultaneously send another address

• Result: Call from B will be aborted and replaced with the call from C. This is expected. However, if Plugin B is waiting for the resolution of the call promise (e.g., using done()), it will never be successful because the request "failed" (was aborted).

There are two ways to solve this situation:

• Each plugin uses its Checkout instance, e.g., var APIInternaDoPluginA = new vtexjs.Checkout().

• The orderFormUpdated.vtex event handler is used to receive success notifications for Checkout modifications.

We recommend using extended-ajax.js (used by default in the bundle). With that, all requests are queued, so they do not happen in parallel.

When a call updates the orderForm, the orderFormUpdated.vtex event is fired. This is useful for different components that use vtex.js to stay updated without knowing the other present components.

Important: This event is only sent when the last pending request is finished. So, if multiple consecutive calls to the API are queued, the event will only be sent at the end of the last call.

When any request that changes the orderForm is started, this event is fired. It can be used, for example, to initiate a load on the screen and prevent the user from making further modifications. The ajaxOptions parameter is the option object originally used to initiate this request.

When any request that changes the orderForm is finished, with or without success, this event is fired. Note that the argument can be an orderForm on success, or jqXHR in case of failure. It is not recommended to use this request to detect changes in the orderForm. Instead, use orderFormUpdated.vtex.

You will notice that most methods require an expectedOrderFormSections argument.

The orderForm is made up of several sections (or attachments). You can request that only a few be sent in the response.

This primarily improves performance when you know your call will not affect the sections you did not ask for, or if you do not mind the changes.

In general, it is safe not to send this argument, in which case all sections will be required.

You can see a description of each section by taking a look at the _allOrderFormSections property.

Given this explanation, this argument will no longer be detailed in the method documentation.

Gets the current orderForm.

This is one of the most important methods. It is essential to make sure that an orderForm is available before making calls to change it.

Promise for the orderForm.

Sends an attachment to the current orderForm. (An attachment is a section.)

This makes it possible to update this section by sending new information, making changes, or removing something.

You must send the complete attachment. See examples.

Read the OrderForm documentation to learn more about sections.

Do not forget to use getOrderForm first.

Promise for the orderForm.

Name	Type
attachmentId	String containing the name of the attachment being sent.
attachment	Object containing the attachment.

Change clientProfileData

If you want to change the customer's first name, change the property firstName in clientProfileData.

Change openTextField

The openTextField is a field for comments. Read the OrderForm documentation for more information.

Add items to the orderForm.

This method does not automatically apply to promotions through UTM. To add promotions using UTM, do a sendAttachment of marketingData with the required information.

An item to be added is necessarily composed of: id, quantity, and seller. The id property can be obtained from the Catalog by looking at the ItemId of the item in the product item array.

Items that are already in the orderForm will remain unchanged.

Promise for the orderForm.

Name	Type
items	Array containing the set of items that will be added. Even if there is only one item, it must be wrapped in an array.
salesChannel	Number or String(Optional parameter, default = 1).

Add an item with itemId 2000017893 from sales channel 3.

Updates items in the orderForm.

An item is identified by its index property. In the orderForm, this property can be obtained by looking at the item index in the item array.

Read the OrderForm documentation to learn more about the item object.

Properties and orderForm items that are not sent, will remain unchanged.

Do not forget to use getOrderForm first.

Promise for the orderForm.

Name	Type
items	Array containing the set of items that will be updated. Even if there is only one item, it must be wrapped in an array.
splitItem	Boolean default: true. Indicates if a separate item should be created when the items to be updated have attachments/services.

Change the quantity and the seller of the first item.

Removes items from the orderForm.

An item is identified by its index property. In the orderForm, this property can be obtained by looking at the item index in the item array.

Do not forget to use getOrderForm first.

Promise for the orderForm.

Name	Type
items	Array containing the set of items that will be removed. Even if there is only one item, it must be wrapped in an array.

Remove the first item.

Removes all items from the orderForm.

Do not forget to use getOrderForm first.

Promise for the orderForm.

Creates one or more items in the cart based on another item. The item to be cloned must have an attachment.

An item is identified by its index property. In the orderForm, this property can be obtained by looking at the item index in the item array.

Do not forget to use getOrderForm first.

Promise for the orderForm.

Name	Type
itemIndex	Index number of the item to which the offer is applied.
newItemsOptions	Array (optional) with the properties that should be assigned to the new items.

Create a new item based on the item with index 0.

Create a new item based on an item with index 0, quantity 2, and an attachment already configured.

Receives an address and records it in the user's shippingData.

The effect is that the shipping will be calculated and available in one of the orderForm totalizers.

Do not forget to use getOrderForm first.

Promise for the orderForm.

Name	Type
address	Object containing the address that must have at least postalCode and country. From these two properties, the others will be inferred.

Receives an item list, postalCode, and country and simulates the shipping of these items for this address.

The difference from calculateShipping is that this call is isolated. It can be used for an arbitrary set of items and does not bind the address to the user.

The result of this simulation includes the different carriers that can be used for each item, including name, delivery date, and price.

It is ideal for simulating shipping on the product page.

Promise with the result. The result has the property logisticsInfo.

Name	Type
items	Array of objects that have at least ID, quantity, and seller.
postalCode	String with the postal code. (CEP for Brazil.)
country	String with the three-letter country code. For example, "BRA" for Brazil.
salesChannel	Number or string. (Optional parameter, default = 1.)

Receives an object containing shipping information (shippingData), the orderFormId, and country, and simulates the shipping of these items for this address.

The difference from calculateShipping is that this call receives different parameters to get the same result.

This is an overloaded function.

The result of this simulation is the same as the last one; it returns different carriers that can be used for each item, including name, delivery date, and price.

Promise for the result. The result has the property logisticsInfo.

Name	Type
shippingData	Object containing shipping and item information through logisticsInfo and selectedAddresses.
orderFormId	String representing the ID of the current session's orderForm.
country	String with the three-letter country code. For example, "BRA" for Brazil.
salesChannel	Number or string. (Optional parameter, default = 1.)

Given an incomplete address with postalCode and country, returns a complete address with city, state, street, and any other available information.

Promise for the complete address.

Name	Type
address	Object with the address that must have at least postalCode and country. With these two properties, the others will be inferred.

Performs partial user login using email.

The information will likely come masked, and you will not be able to edit it if the user already exists. For this, you need to authenticate with VTEX ID. You can check through the canEditData property of the orderForm. For more information, read the OrderForm documentation.

Do not forget to use getOrderForm first.

Promise for the orderForm.

Name	Type
email	String
salesChannel	Number or string (default = 1).

In orderForm.paymentData.availableAccounts, you find the user's payment accounts. Each account has several details, one of which is the accountId. This ID can be used in this method for removing the payment account.

Do not forget to use getOrderForm first.

Promise of success.

Name	Type
accountId	String

Adds a discount coupon to the orderForm.

Only one discount coupon can be applied per purchase.

Do not forget to use getOrderForm first.

Promise for the orderForm.

Name	Type
couponCode	String

Removes the orderForm discount coupon.

Only one discount coupon can be applied per purchase. Therefore, there is no need to specify anything here.

Do not forget to use getOrderForm first.

Promise for the orderForm.

Removes the gift registry from the orderForm.

This unlinks the gift list to which the orderForm is associated, if any. If it is not linked, it does not do anything.

Do not forget to use getOrderForm first.

Promise for the orderForm.

Adds an offer to the orderForm.

Each orderForm item may have a list of offerings. These offers are linked to the item, like extended warranty or installation service.

When an offer is added, it will appear in the item's bundleItems field.

Do not forget to use getOrderForm first.

Promise for the orderForm.

Name	Type
offeringId	String or number. This may be found in the id property of the offer.
itemIndex	Number. The index of the item to which the offer is applied.

Removes an offer.

Do not forget to use getOrderForm first.

Promise for the orderForm.

Name	Type
offeringId	String or number. This may be found in the offer's id property.
itemIndex	Number. The index of the item to which the offer is applied.

This method adds an attachment to an item in the cart. This allows you to add extra information to the item.

You can link an attachment to the SKU through the admin interface. To see which attachments can be inserted, check the item's attachmentOfferings property.

For example, when adding a sports team shirt to the cart, you can add the 'customization' attachment to allow the customer to choose the number that will be printed on the shirt.

If the attachment has more than one property in its object, you must send the complete object even if you only changed one field.

Example

The item has an attachmentOffering as follows:

The content object must always send all its properties:

Do not forget to call getOrderForm at least once before.

Promise for the orderForm.

Name	Type
itemIndex	Number. The index of the item that will be included in the attachment.
attachmentName	String that can be found in the name property of attachmentOfferings in the item object.
content	Object. An object that follows the schema described in the schema property of attachmentOfferings.
splitItem	Boolean default: true. Indicates that a separate item should be created if the items to be updated have attachments.

404: The item does not have this linked attachment or the content object has an invalid property. 400: The content object was not passed correctly.

If the call fails, check the error object returned: (error.message). This will give you clues about what is wrong in the call.

Removes an item attachment from the cart.

Do not forget to use getOrderForm first.

Promise for the orderForm.

Name	Type
itemIndex	Number. The index of the item that will be included in the attachment.
attachmentName	String that can be found in the name property of attachmentOfferings in the item object.
content	Object. An object that follows the schema described in the schema property of attachmentOfferings.

This method adds an attachment to the service (bundleItem) of an item in the cart.

You can link an attachment to the service through the admin interface. To see which attachments can be inserted, check the attachmentOfferings property of the service.

Do not forget to use getOrderForm first.

Promise for the orderForm.

Name	Type
itemIndex	Number. The index of the item to which the service is applied.
bundleId	String or number. This may be found in the id property of the bundleItem.
attachmentName	String that can be found in the name property of attachmentOfferings in the service object.
content	Object. An object that follows the schema described in the schema property of attachmentOfferings.

Removes an attachment from a service.

Do not forget to use getOrderForm first.

Promise for the orderForm.

Name	Type
itemIndex	Number. The index of the item to which the service is applied.
bundleId	String ou Number May be found in the id property of the bundleItem
attachmentName	String that can be found in the name property of attachmentOfferings in the service object.
content	An object that follows the schema described in the schema property of attachmentOfferings.

Changes the user locale.

This causes a change in the orderForm, in clientPreferencesData.

Do not forget to use getOrderForm first.

Promise of success (no orderForm section is requested).

Name	Type
locale	String examples: "pt-BR", "en-US".

Occasionally, the orderForm has its messages section populated with informational or error messages.

To clear the messages, use this method.

Do not forget to use getOrderForm first.

Promise of success (no orderForm section is requested).

This method returns a URL that logs the user out, but keeps their cart.

You are responsible for making this redirection.

Do not forget to use getOrderForm first.

String

Gets the orders (order) contained in an order group (orderGroup).

If an order has been finalized and fulfilled by multiple sellers, it will be split into several orders — one for each seller.

The orderGroupId looks like v50123456abc, while group orders have identifiers such as v50123456abc-01, v50123456abc-02.

In most cases, an orderGroup will only contain one order.

In terms of data, an orderGroup is an array of order objects. An order has several properties related to the completion of the purchase. Full documentation of this object will be available soon.

Promise for the orders.

Name	Type
orderGroupId	String

Changes the sort order of the items based on the criteria (criteria) and an ascending parameter (ascending).

This causes a change in the itemsOrdination object of the OrderForm and also in the sort order of the objects in the items array.

Promise for the orderForm.

Name	Type
criteria	String name or add_time
ascending	Boolean. True for increasing and false for decreasing.

Removes a SKU from a current item and replaces it with a new one.

Promise for the orderForm.

Name	Type
items	Array object with the SKU to be removed in quantity 0 and the new SKU to be added. Must be wrapped in an array.
splitItem	Boolean default: true. Indicates a separate item should be created if the items to be updated have attachments/services.

Tells the Checkout API to finish a transaction and go to the final URL (e.g. order-placed, checkout).

Promise for the orderForm.

Name	Type
orderGroupId	Number. ID of the order to be created after finishing the checkout process.****