orderForm fields reference

The orderForm is the main object processed by VTEX Checkout and one of the most important data structures in every VTEX architecture's store. It represents a shopping cart and stores all the contextual information needed to turn that cart into an order: the items, the customer's profile, delivery and pickup options, payment options, promotions, and custom information.

The Checkout API is the main interface for reading and changing the orderForm. Most of its endpoints return the complete orderForm in the response body.

This guide describes every field of the orderForm, grouped by section. Each section includes a description of its purpose, a JSON example, and a table with the type, description, and an example value of each field.

The orderForm is composed of root fields, which describe the cart as a whole, and sections, which are objects or arrays that group related information.

The sections are organized in this guide by subject:

Root fields are located directly in the orderForm object and describe the cart as a whole: its identification, the sales channel, the shopper's session state, and the total order value.

The sections in this group describe what is in the cart: the items and their prices, the sellers that fulfill them, the gifts available, and the order totals.

Array containing one object for each item (SKU) in the cart, with identification, catalog, price, quantity, and seller information. Items are identified in other sections, such as shippingData.logisticsInfo, by their position in this array (itemIndex), starting at 0.

If you use integrations that consume price data, such as checkout or order integrations, the sellingPrice field may be subject to rounding discrepancies. We recommend retrieving price data from the priceDefinition object instead.

Example:

items[].priceDefinition

The priceDefinition object provides the correctly rounded prices of an item. When the unit selling price can't be divided evenly among all units, for example because of a percentage discount or a unit multiplier, sellingPrices lists each rounding instance so that the sum of value × quantity matches total.

In the following example, an item sold by weight (unitMultiplier of 0.3 kg) has a unit price of 199 per kg and a quantity of 3. The total of 179 is reached by charging 60 for two units and 59 for one unit:

Object containing catalog metadata of each item in the cart, such as name, image, and product page URL. It is used to display items consistently, including items that aren't part of items, such as gifts and assembly options.

Example:

Object containing the criteria used to sort the items in the items array. Returns null when no sorting is applied.

Example:

Array containing the gifts that the customer can choose from, based on Buy One Get One promotions that offer a gift. Each object represents a list of gift options.

Example:

Array containing one object for each seller responsible for items in the cart.

Example:

Array containing one object for each totalizer of the order. Totalizers contain the sum of values for a specific part of the order, such as the total value of the items, discounts, shipping, and taxes.

Example:

The sections in this group describe who is placing the order and their preferences.

Object containing the profile data of the customer who is placing the order. Returns null until the customer informs their email.

If the customer's identity hasn't been confirmed, some personal data is masked with asterisks to protect the shopper's privacy.

Example:

Object containing the preferences of the customer who is placing the order.

Example:

Object containing information about the gift list associated with the cart, when the customer is buying items from a gift list. Returns null when the cart isn't associated with a gift list.

Example:

Object containing the shipping information of the order: the delivery address, the addresses available to the customer, and the logistics information of each item, including the available shipping options (SLAs) and the option selected by the customer. Returns null until shipping information is available.

Example:

Address object

The address object is used in shippingData.address, shippingData.selectedAddresses, shippingData.availableAddresses, shippingData.logisticsInfo[].slas[].pickupStoreInfo.address, and in the root availableAddresses field.

Disposable addresses

The isDisposable behavior depends on the address type:

• giftRegistry, pickup, search, and inStore: always disposable, as they don't belong to the shopper navigating the cart.
• residential: may be disposable. Addresses from a complete shopper profile, or entered by an authenticated shopper with a complete profile, aren't disposable. All other residential addresses are disposable, including those from first-time purchases, since no complete profile exists yet.
• commercial: corresponds to company addresses used in B2B contexts and follows the same logic as residential addresses.
• invoice: doesn't have the isDisposable flag. In practice, only authenticated shoppers can add invoice data to the cart, so these addresses are never treated as disposable.

When a residential address is marked as disposable and the profile is complete, authentication is required to complete the order. Additionally, when a disposable residential address is used to complete a purchase, saved cards can't be used.

Object containing the payment information of the order: the payment methods available, the installment options, the payments selected by the customer, gift cards, and transactions.

For accurate information on installment options and values, we recommend using the Cart installments endpoint instead of the installmentOptions field.

Example:

Object containing information about the order invoice, including the billing address. Returns null when no invoice data was added to the cart. Use the Add invoice data endpoint to add this information.

Example:

Object containing promotion and campaign data, such as the coupon applied to the cart and the external and internal UTM parameters. Returns null when no marketing data was added. Use the Add marketing data endpoint to add this information.

Example:

Object containing the promotions (benefits) and taxes (rates) that apply to the order, and the teasers of promotions the customer can still qualify for.

Example:

The sections in this group store information that isn't part of the standard orderForm structure.

Object containing custom information added to the cart by the store. Returns null when no custom data was added.

It supports two structures:

• customApps: custom fields grouped by app. See Add and handle custom information in the order and the Set multiple custom field values endpoint.
• customFields: custom fields linked to the order, to an item, or to an address. See Customizable fields with Checkout API.

Example:

Optional field meant to hold free text information about the order, such as delivery notes. Returns null when empty.

We recommend using this field for text, not data formats such as JSON, even if escaped. To store structured data, see Add and handle custom information in the order.

Example:

Object containing hooks information of the cart. Returns null when no hook applies.

Example:

Object containing data from the store configuration, stored in VTEX License Manager, such as country, currency, and time zone.

Example:

Object containing information about the commercial conditions that apply to the order. Returns null when no commercial condition applies.

Example:

Object containing the subscription information of the items in the cart. Returns null if the cart has no subscriptions. Use the Add subscription data endpoint to add this information.

Example:

Array containing one object for each message generated by the server while processing the request, such as errors, warnings, and information about changes in the cart (for example, a price change or an unavailable item). Use the Clear orderForm messages endpoint to remove them. See the possible messages in Checkout error codes.

Example: