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": {},
  "products": {},
  "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 que contém os apps criados pela loja
fieldsobjectObjeto que contém os campos criados pela loja para cada app
idstringApp ID
major

giftRegistryData

🚧

Work in progress

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

hooksData

🚧

Work in progress

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,
            "assemblies": [],
            "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",
            "components": [],
            "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
            }
        }
    ]

🚧

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.

itemsOrdination

🚧

Work in progress

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

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
attachmentIdstring
couponstring
marketingTagsstring
utmCampaignstringValor do parâmetro utm_campaign da URL que levou ao pedido
utmMediumstringValor do parâmetro utm_medium da URL que levou ao pedido
utmSourcestringValor do parâmetro utm_source da URL que levou ao pedido
utmiCampaignstringValor da UTM interna utmi_cp
utmiPartstringValor da UTM interna utmi_pc
utmipagestringVvalor da UTM interna 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": "O vale compra de código AAAA-BBBB-CCCC-DDDD não foi encontrado no sistema"
  }
]

openTextField

🚧

Work in progress

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

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
giftCardsarray
giftCardMessagesarray
availableAccountsarray
availableTokensarray
installmentOptionsarrayFor accurate information on installment options and values, we recommend using the Cart installment endpoint, instead of this field's data.
paymentSystemsarray
paymentsarray
updateStatusstringcheckout can not be concluded if value is "outdated".

🚧

Work in progress

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

products

🚧

Work in progress

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

ratesAndBenefitsData

🚧

Work in progress

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

selectableGifts

🚧

Work in progress

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

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",
      "slas": [
        {
          "id": ".Transportadora",
          "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",
              "price": 1000,
              "tax": 0
            }, {
              "startDateUtc": "2014-04-21T13:00:00+00:00",
              "endDateUtc": "2014-04-21T17:00:00+00:00",
              "price": 1000,
              "tax": 0
            }
          ],
          "deliveryWindow": null,
          "price": 1220,
          "tax": 0
        }
      ]
    }
  ],
  "selectedAddresses": []
}
FieldTypeDescription
attachmentIdstring
addressobject
availableAddressesarray
logisticsInfoarray
selectedAddressesarray

storeId

🚧

Work in progress

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

storePreferencesData

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

Example:

{
  "countryCode": "BRA",
  "checkToSavePersonDataByDefault": 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 dos Itens"
    "value": 35620
  }, {
    "id": "Shipping"
    "name": "Total do Frete"
    "value": 399
  }
]