orderForm

The orderForm is the main object processed by VTEX checkout, and one of the most important data structures in the architecture of every VTEX store.

It stores a lot of contextual information about the order which is important to the processing of the order: order items, client's personal data, delivery address, freight information, etc.

Using VTEX APIs this information can be accessed, processed, and even changed on certain occasions.

VTEX's Checkout API is one of the main interfaces interacting with the orderForm object. Most of its operations will return the orderForm or part of it.

The object's basic structure is:

{
  "allowManualPrice": boolean,
  "canEditData": boolean,
  "clientPreferencesData": {},
  "clientProfileData": {},
  "commercialConditionData": {},
  "customData": {},
  "giftRegistryData": {},
  "hooksData": {},
  "ignoreProfileData": boolean,
  "isCheckedIn": boolean,
  "itemMetadata": {},
  "items": {},
  "itemsOrdination": {},
  "loggedIn": boolean,
  "marketingData": {},
  "messages": [],
  "openTextField": {},
  "orderFormId": "426effeba9210",
  "paymentData": {},  
  "ratesAndBenefitsData": {},
  "salesChannel": "1",
  "selectableGifts": {},
  "sellers": {},
  "shippingData": {},
  "storeId": {},
  "storePreferencesData": {},
  "totalizers": {},
  "userProfileId": {},
  "userType": {},
  "value": number
}

This structure is made of many sections.

🚧

Any properties representing monetary values will have cents as their units. (e.g. 10390 means R$103,90 in Brazilian stores)

In the following menu, you can find details regarding these sections.

OrderForm Sections

clientPreferencesData

Object containing preferences from the client who placed the order.

Example:

{
  "locale": "pt-BR",
  "optinNewsLetter": true
}
FieldTypeDescription
localeStringClient's locale. Examples: "pt-BR" and "en-US". The method sendLocale(), from vtex.js, changes the value of this field.
optinNewsLetterBooleantrue if the client opted to receive newsletters from the store.

clientProfileData

Object containing the data of the customer who placed the order.

If the customer has not yet informed her or his e-mail, much of the data may be empty (null).

If the customer's e-mail has not yet been confirmed, several personal data will be censored, that is, some of its parts will be hidden by asterisks to avoid identification.

Example:

{
  "email": "[email protected]",
  "firstName": "Bre******",
  "lastName": "Bar******",
  "document": "*1*2*5*5*3*",
  "documentType": "cpf",
  "phone": "******0879",
  "corporateName": null,
  "tradeName": null,
  "corporateDocument": null,
  "stateInscription": null,
  "corporatePhone": null,
  "isCorporate": false
}
FieldTypeDescription
emailStringCustomer's email.
firstNameStringCustomer's first name.
lastNameStringCustomer's last name.
documentStringDocument number informed by the customer.
documentTypeStringType of the document informed by the customer.
phoneStringCustomer's phone number.
corporateNameStringIf it's a legal entity, here goes the company name.
tradeNameStringIf legal entity, here goes the trade name.
corporateDocumentStringIf legal entity, here goes the corporate document.
stateInscriptionStringIf legal entity, here goes the state inscription.
corporatePhoneStringIf legal entity, here goes the company phone.
isCorporateBooleanIt has the value true if it's a legal entity.

commercialConditionData

🚧

Work in progress

This guide is currently being written and published as content becomes available.

customData

During the checkout process, some stores need to include data gathered from the client that is not part of our standard orderForm format (e.g. gender, cell phone number, age).

To do that you will need to create extra fields in the orderForm and those will be located inside the customData parameter

Example:

"customData": {
    "attachmentId": "customData",
    "customApps": [
        {
            "fields": {
                "number": "78550693",
                "street": "Rua Voluntários da Pátria",
                "complement": "Em frente à Torre Citi",
                "name": "101 - Delco Autopista,
                "neighborhood": "Botafogo",
                "city": "Rio de Janeiro",
                "state": "RJ"
            },
            "id": "pickupinfo",
            "major": 1
        },
        {
            "fields": {
                "deliveryEstimate": "30"
            },
            "id": "deliveryinfo",
            "major": 1
        }
    ]
}
FieldTypeDescription
customAppsArrayArray containing the apps created by the store.
fieldsObjectObject that contains the fields created by the store for each app.
idStringApp ID.
major

giftRegistryData

Object containing the gift registration list data.

Example:

{
  "giftRegistryId": "22222",  
  "giftRegistryType": null,
  "giftRegistryTypeName": null,
  "addressId": null,
  "description": "gift1"    
}
FieldTypeDescription
giftRegistryIdStringGift registry ID.
giftRegistryTypeStringGift registry type.
giftRegistryTypeNameStringGift registration typen name.
addressIdStringAddress ID.
descriptionStringGift registry description.

hooksData

🚧

This guide is currently being written and published as content becomes available.

items

it is an array containing an object describing every item in the buyer's cart.

Example:

"items": [
        {
            "uniqueId": "3B31329E5DDA4A1A81449DD7466D9575",
            "id": "4",
            "productId": "3",
            "productRefId": "",
            "refId": null,
            "ean": "978073487962",
            "name": "Mild Hair Cleanser 50 ml",
            "skuName": "50 ml",
            "modalType": null,
            "parentItemIndex": null,
            "parentAssemblyBinding": null,
            "priceValidUntil": "2022-04-07T18:31:11Z",
            "tax": 0,
            "price": 3190,
            "listPrice": 3190,
            "manualPrice": 1700,
            "manualPriceAppliedBy": "in542e51-5863-4c34-8i86-ed8fcf597a09",
            "sellingPrice": 1700,
            "rewardValue": 0,
            "isGift": false,
            "additionalInfo": {
                "dimension": null,
                "brandName": "VALCOSMETICS",
                "brandId": "2000000",
                "offeringInfo": null,
                "offeringType": null,
                "offeringTypeId": null
            },
            "preSaleDate": null,
            "productCategoryIds": "/2/",
            "productCategories": {
                "2": "Computers"
            },
            "quantity": 3,
            "seller": "seller1",
            "sellerChain": [
                "seller1"
            ],
            "imageUrl": "http://cosmeticsstore.vteximg.com.br/arquivos/ids/155401-55-55/ID-001-MAIN.jpg?v=637109313796670000",
            "detailUrl": "/mild-hair-cleanser/p",
            "bundleItems": [],
            "attachments": [],
            "attachmentOfferings": [],
            "offerings": [],
            "priceTags": [
                {
                    "name": "[email protected]",
                    "value": -4470,
                    "rawValue": -44.7,
                    "isPercentual": false,
                    "identifier": null
                }
            ],
            "availability": "available",
            "measurementUnit": "un",
            "unitMultiplier": 1.0000,
            "manufacturerCode": null,
            "priceDefinition": {
                “sellingPrice”: [
                    {
                        “quantity”: 1,
                        “value”: 1700
                    }
                ],
                “total”: 5100
            }
        }
    ]
FieldTypeDescription
uniqueIdStringThis string is the unique identifier for each occurrence of a SKU in an order. Two same SKUs in an order will have different uniqueIds. Obsolete field.
idStringID of the item.
productIdStringProduct ID.
productRefIdStringProduct Ref ID.
refIdStringRef ID.
eanStringEAN (codebar) field from SKU registry.
nameStringProduct name.
skuNameStringSKU name.
modalTypeStringModal type.
parentItemIndexIntegerParent item index.
parentAssemblyBindingStringParent assembly binding.
priceValidUntilStringPrice expiration date and time.
taxIntegerTax value in cents.
priceIntegerPrice in cents.
listPriceIntegerList price in cents.
manualPriceIntegerManual price in cents.
manualPriceAppliedByStringUser that applied the manual price, if that is the case.
sellingPriceIntegerSelling price in cents. Note that this field may be subject to rounding discrepancies. We recommend retrieving data from the priceDefinition data structure instead.
rewardValueIntegerReward value in cents.
isGiftBooleanIndicates whether item is a gift.
additionalInfoObjectAdditional information.
dimensionStringDimension.
brandNameStringBrand name.
brandIdStringBrand ID.
offeringInfoStringOffering information.
offeringTypeStringOffering type.
offeringTypeIdStringOffering type ID.
preSaleDateStringPresale date.
productCategoryIdsStringProduct category IDs.
productCategoriesObjectObject, where each field is an ID from productCategoryIds.
{ID}StringProduct category corresponding to the ID in the field key.
quantityIntegerQuantity.
sellerStringSeller information.
sellerChainArray of stringsSellers involved in the chain. The list should contain only one seller, unless it is a Multilevel Omnichannel Inventory order.
imageUrlStringImage URL.
detailUrlStringDetail URL.
bundleItemsArray of objectsInformation on services sold along with the SKU. Example: a gift package.
typeStringService type.
idIntegerService identifier.
nameStringService name.
priceIntegerService price in cents.
attachmentsArray of stringsArray containing information on attachments.
priceTagsArray of objectsArray of price tags, each of which, modifies the price in some way, like discounts or rates that apply to the item in the context of the order.
identifierStringPrice tag identifier.
isPercentualBooleanIndicates whether price tag value is applied through a percentage.
nameStringPrice tag name.
rawValueIntegerPrice tag raw value.
valueIntegerPrice tag value.
availabilityStringSKU availability. The values are: available, withoutStockand cannotBeDelivered. Only SKUs with available value can be sold and delivered.
measurementUnitStringMeasurement unit.
unitMultiplierStringUnit multiplier.
manufacturerCodeStringManufacturer code.
priceDefinitionObjectPrice information for all units of a specific item.
calculatedSellingPriceIntegerItem's calculated unitary selling price in cents.
totalIntegerTotal value for all units of the item in cents.
sellingPricesArray of objectsArray of objects, each containing value (in cents) and quantity for the different rounding instances that can be combined to form the correctly rounded total.
valueIntegerValue in cents for that specific rounding.
quantityIntegerRounding quantity, meaning how many items are rounded to this value.

🚧

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

items[].priceDefinition

{
    "items": [
        {
            "id": "1001669",
            "price": 199,
            "quantity": 3,
            "unitMultiplier": 0.3,
            "measurementUnit": "kg",
            "sellingPrice": 59,
            "priceDefinition": {
                "calculatedSellingPrice": 59,
                "total": 179,
                "sellingPrices": [
                    {
                        "value": 60,
                        "quantity": 2
                    },
                    {
                        "value": 59,
                        "quantity": 1
                    }
                ]
            }
        }
    ]
}
AtributeTypeDescription
items[].priceDefinitionObjectPrice information for all units of a specific item.
items[].priceDefinition.totalIntegerTotal value for all units of the item in cents.
items[].priceDefinition.calculatedSellingPriceIntegerItem's calculated unitary selling price in cents.
items[].priceDefinition.sellingPricesArrayArray of objects, each containing value (in cents) and quantity for the different rounding instances that can be combined to form the correctly rounded total.

invoiceData

This is an object containing information pertinent to the order's invoice.

{
   "address": {
   "postalCode": "******000",
   "city": "Rio ** *******",
   "state": "RJ",
   "country": "BRA",
   "street": "Rua *** *****nte",
   "number": "***",
   "neighborhood": "Bot*****",
   "complement": "*** ** *",
   "reference": null
    },
    "settleInvoices":[]  
}
FieldTypeDescription
addressObjectAddress information.
settleInvoicesStringList of strings corresponding to invoice numbers.

itemsOrdination

This is an object containing information about the ordering of items within the orderForm.

Example:

{
  "criteria": "NAME",  
  "ascending": true  
}
FieldTypeDescription
criteriaStringCriteria adopted to order the items in the list. The values are: NAME, ADD_TIME (date information), and GIFT (non-gift items are mentioned before gift items).
ascendingStringIndicates whether the ordering is ascending.

marketingData

This object contains promotion data such as coupon tracking information and internal or external UTMs.

Example:

{
  "attachmentId": "marketingData",
  "coupon": null,
  "marketingTags": [],
  "utmCampaign": "christmas",
  "utmMedium": null,
  "utmSource": "fb",
  "utmiCampaign": "",
  "utmiPart": "",
  "utmipage": ""  
}
FieldTypeDescription
attachmentIdStringAttachment ID.
couponStringCoupon code information.
marketingTagsArrayMarketing tags information. This field can be used to register campaign data or informative tags regarding promotions.
utmCampaignStringValue of the utm_campaign parameter of the URL that led to the request.
utmMediumStringValue of the utm_medium parameter of the URL that led to the request.
utmSourceStringValue of the utm_source parameter of the URL that led to the request.
utmiCampaignStringInternal UTM value utmi_cp.
utmiPartStringInternal UTM value utmi_pc.
utmipageStringInternal UTM value utmi_p.

messages

This array contains an object for each message generated by our servers while processing the request.

Example:

[
  {
    "code": null,
    "status": "error",
    "text": "Voucher code AAAA-BBBB-CCCC-DDDD was not found in the system"
  }
]

openTextField

Optional field meant to hold additional information about the order. We recommend using this field for text, not data formats such as JSON even if escaped. For that purpose, see How to add and handle custom information in the order.

{
    "value": "{\"Phones\":[\"55555555\"]}"
  }
FieldTypeDescription
valueStringAdditional information about the order.

paymentData

This object contains all payment information inserted for this purchase.

Example:

{
  "giftCards": [
    {
      "redemptionCode": "HYUO-TEZZ-QFFT-HTFR",
      "value": 500,
      "balance": 500,
      "name": null,
      "id": "-1390324156495k195pmab4rall3di",
      "inUse": true,
      "isSpecialCard": false
    }, {
      "redemptionCode": "MTHU-WNTD-VXJW-TIDC",
      "value": 0,
      "balance": 700000,
      "name": "loyalty-program",
      "id": "122",
      "inUse": false,
      "isSpecialCard": true
    }
  ],
  "giftCardMessages": [],
  "availableAccounts": [
    {
      "accountId": "71F2775D46BF44B1BF217F828F4E6131",
      "paymentSystem": "2",
      "paymentSystemName": "Visa",
      "cardNumber": "************1111",
      "availableAddresses": ["-1363804954758", "-1366200971560"]
    }
  ],
  "availableTokens": [],
  "installmentOptions": [
    {
      "paymentSystem": "2",
      "value": 16175,
      "installments": [
        {
          "count": 1,
          "hasInterestRate": false,
          "interestRate": 0,
          "value": 16175,
          "total": 16175
        }, {
          "count": 2,
          "hasInterestRate": false,
          "interestRate": 132,
          "value": 4178,
          "total": 16712
        }
      ]
    }
  ],
  "paymentSystems": [
    {
      "id": 2,
      "name": "Visa",
      "groupName": "creditCardPaymentGroup",
      "validator": {
        "regex": "^4",
        "mask": "9999 9999 9999 9999",
        "cardCodeRegex": "[^0-9]",
        "cardCodeMask": "999",
        "weights": [2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2]
      },
      "stringId": null,
      "template": "creditCardPaymentGroup-template",
      "requiresDocument": false,
      "selected": false,
      "isCustom": false,
      "description": null
    }
  ],
  "payments": [
    {
      "accountId": null,
      "bin": null,
      "installments": 2,
      "paymentSystem": "12",
      "referenceValue": 16175,
      "value": 16175
    }
  ]
}
FieldTypeDescription
giftCardsArrayGift cards information.
giftCardMessagesArrayGift cards message information.
availableAccountsArrayAvailable accounts information.
availableTokensArrayAvailable tokes information.
installmentOptionsArrayFor accurate information on installment options and values, we recommend using the Cart installment endpoint, instead of this field's data.
paymentSystemsArrayPayment systems information.
paymentsArrayPayments information.
updateStatusStringCheckout can not be concluded if value is "outdated".

🚧

Work in progress

This guide is currently being written and published as content becomes available.

ratesAndBenefitsData

Information on rates and benefits that apply to the order.

Example:

{
    "rateAndBenefitsIdentifiers": [
    {
            "items": {}
    }
  ],
    "teaser":[
    {
            "items": {}
    }
    ]
}
FieldTypeDescription
rateAndBenefitsIdentifiersArrayList with rates and benefits identifiers.
itemsObjectObject that contains identifiers information.
teaserArrayList with rates and benefits teasers.
itemsObjectObject that contains teasers information.

selectableGifts

Array containing the data of the item selected as a gift.

[
  {
    "id": null,
    "availableQuantity": "3",
    "availableGifts": {
      "items": [
                                {},
                       "isSelected": true
                             ]
  }
]
FieldTypeDescription
idStringIdentification of the selectable gifts list.
availableQuantityIntegerNumber of items available.
itemsIntegerArray containing an object describing each item that can be selected as a gift.
isSelectedBooleanIndication if the item was selected as a gift.

sellers

An array containing an object for each seller being used in the order.

Example:

[
  {
    "id": "1",
    "name": "meuamigopet",
    "logo": "http://portal.vtexcommerce.com.br/arquivos/logo.jpg"
  }
]
FieldTypeDescription
idStringID of the seller.
nameStringName of the seller.
logoStringURL pointing to where the image is hosted.

shippingData

This object contains shipping information for the order.

Example:

{
  "attachmentId": "shippingData",
  "address": {
    "addressType": "residential",
    "receiverName": "Gui***rme",
    "addressId": "-1368194386810",
    "postalCode": "******000",
    "city": "Rio ** *******",
    "state": "RJ",
    "country": "BRA",
    "street": "Rua *** *****nte",
    "number": "***",
    "neighborhood": "Bot*****",
    "complement": "*** ** *",
    "reference": null
  },
  "availableAddresses": [
    {
      "addressType": "residential",
      "receiverName": "Gui***rme",
      "addressId": "-1368194386810",
      "postalCode": "******000",
      "city": "Rio ** *******",
      "state": "RJ",
      "country": "BRA",
      "street": "Rua *** *****nte",
      "number": "***",
      "neighborhood": "Bot*****",
      "complement": "*** ** *",
      "reference": null
    }
  ],
  "logisticsInfo": [
    {
      "itemIndex": 0,
      "selectedSla": ".Transportadora",
      "selectedDeliveryChannel": "delivery",
      "addressId": "teste",
      "slas": [
        {
          "id": ".Transportadora",
          "deliveryChannel": "delivery",
          "name": ".Transportadora",
          "deliveryIds": [
            {
              "courierId": "67",
              "warehouseId": "1_1",
              "dockId": "1_1_1",
              "courierName": "Transportadora",
              "quantity": 1
            }
          ],
          "shippingEstimate": "3d",
          "shippingEstimateDate": null,
          "lockTTL": null,
          "availableDeliveryWindows": [],
          "deliveryWindow": null,
          "price": 956,
          "tax": 0
        }, {
          "id": "Agendada",
          "name": "Agendada",
          "deliveryIds": [
            {
              "courierId": "FA02F72F-FEBD-41A0-AF70-83A77E8C77A0",
              "warehouseId": "1_1",
              "dockId": "1_1_1",
              "courierName": "Entrega agendada",
              "quantity": 1
            }
          ],
          "shippingEstimate": "90d",
          "shippingEstimateDate": null,
          "lockTTL": null,
          "availableDeliveryWindows": [
            {
              "startDateUtc": "2014-04-21T09:00:00+00:00",
              "endDateUtc": "2014-04-21T12:00:00+00:00",
              "listprice": 1000,
              "tax": 0
            }, {
              "startDateUtc": "2014-04-21T13:00:00+00:00",
              "endDateUtc": "2014-04-21T17:00:00+00:00",
              "listprice": 1000,
              "tax": 0
            }
          ],
          "deliveryWindow ": [
            {
              "startDateUtc": "2014-04-21T09:00:00+00:00",
              "endDateUtc": "2014-04-21T12:00:00+00:00",
              "listprice": 1000,
              "tax": 0
            }, {
              "startDateUtc": "2014-04-21T13:00:00+00:00",
              "endDateUtc": "2014-04-21T17:00:00+00:00",
              "listprice": 1000,
              "tax": 0
            }
          ],          
          "price": 1220,
          "tax": 0,
          "pickupStoreInfo": {
              "isPickupStore": false,
              "friendlyName": null,
              "address": null,
              "additionalInfo": null,
              "dockId": null
            },
            "pickupPointId": null,
            "pickupDistance": 0,
            "polygonName": null,
            "transitTime": "3bd"
          }
        ],
         "shipsTo": [
           "BRA",
           "COL",
           "USA"
        ],
         "itemId": "2",
         "deliveryChannels": [
           {
             "id": "delivery"
           },
           {
             "id": "pickup-in-point"
           }
         ]
       }
      ],
  "selectedAddresses": []
}
FieldTypeDescription
attachmentIdStringAttachment ID.
addressObjectAddress information.
availableAddressesArrayInformation about available shipping addresses.
logisticsInfoArrayLogistics information.
itemIndexIntegerIndex corresponding to the position of the object in the items array.
selectedSlaStringSLA selected by the customer.
selectedDeliveryChannelStringDelivery channel selected by the customer.
addressIdStringAddress ID.
slasArrayInformation on available SLAs.
idStringSLA ID.
deliveryChannelStringDelivery channel.
nameStringSLA name.
deliveryIdsArrayInformation on each delivery ID.
courierIdStringCourier ID.
warehouseIdStringWarehouse ID.
dockIdStringDock ID.
courierNameStringCourier name.
quantityIntegerQuantity.
shippingEstimateStringShipping estimate. For instance, Three business days will be represented 3bd.
shippingEstimateDateStringShipping estimate date.
lockTTLStringEstimate date of delivery.
availableDeliveryWindowsStringAvailable shipping date.
startDateUtcStringAvailable delivery window start date in UTC.
endDateUtcStringAvailable delivery window end date in UTC.
deliveryWindowObjectScheduled delivery window information, in case it applies to the item.
startDateUtcStringScheduled delivery window start date in UTC.
endDateUtcStringScheduled delivery window end date in UTC.
listPriceIntegerScheduled delivery window list price.
priceIntegerPrice in cents.
taxIntegerTax in cents.
pickupStoreInfoObjectInformation on the pickup store.
isPickupStoreBooleanIndicates whether it is the pickup store.
friendlyNameStringFriendly name.
addressObjectAddress information.
additionalInfoStringAdditional information.
dockIdStringCorresponding dock ID.
pickupPointIdStringPickup point ID.
pickupDistanceIntegerPickup point distance.
polygonNameStringPolygon name.
transitTimeStringTransit time. For instance, "three business days" is represented 3bd.
shipsToArrayList of countries that the item may be shipped to.
itemIdStringItem ID.
deliveryChannelsStringList of available delivery channels.
idStringelivery channel ID.
selectedAddressesArraySelected addresses information.

storeId

It is a string containing the store ID.

Example:

{
    "storeId": "2"
  }
FieldTypeDescription
storeIdintegerIdentification of the store.

storePreferencesData

This object contains data from the store's configuration (stored in VTEX's License Manager).

Example:

{
  "countryCode": "BRA",
  "saveUserData": true,
  "templateOptions": {
    "toggleCorporate": false
  },
  "timeZone": "E. South America Standard Time",
  "currencyCode": "BRL",
  "currencyLocale": 0,
  "currencySymbol": "R$",
  "currencyFormatInfo": {
    "currencyDecimalDigits": 2,
    "currencyDecimalSeparator": ",",
    "currencyGroupSeparator": ".",
    "currencyGroupSize": 3,
    "startsWithCurrencySymbol": true
  }
}

totalizers

This array contains an object for each totalizer for the purchase. Totalizers contain the sum of values for a specific part of the order (e.g. Total item value, Total shipping value).

Example:

[
  {
    "id": "Items"
    "name": "Total items"
    "value": 35620
  }, {
    "id": "Shipping"
    "name": "Total freight"
    "value": 399
  }
]