Documentation
Feedback
Guides
API Reference

Guides
CheckoutCustom Data
Add and handle custom information in the order

When the end customer enters the checkout process at a VTEX store, all order information is organized within fields of the orderForm object.

However, some stores have the need to request customer data that is not part of the orderForm's default set of objects. For example: gender, cell phone number, age, etc.

To include them, you must use the customData field in the orderForm. The purpose of this field is to be populated with custom information needed for the specific operation of the store.

To work with this field, you must use VTEX’s Checkout API. Three steps are required:

  1. Creating apps and fields through the configuration request.

  2. Using the API to record/update/query the data (via orderForm and placeOrder).

  3. Finding the desired data in the created order.

Creating apps and fields through the configuration request

Before populating the customData field, you need to use the Update orderForm configuration request to create an app. This app will contain custom fields that will be populated during checkout.

The Update orderForm configuration defines settings that apply to all orderForms generated in your account. This means that, from the moment you add an app through it, all the store’s orders will contain the extra fields defined in that app. To create an app and its fields, this call only needs to happen once. For more information, access the Update an account’s orderForm configuration developers guide.

See below a request body example of the Updater orderForm configuration endpoint containing an apps object:


_19
...
_19
"apps": [
_19
{
_19
"fields": [
_19
"gender",
_19
"age"
_19
],
_19
"id": "profile",
_19
"major": 1
_19
},
_19
{
_19
"fields": [
_19
"street"
_19
],
_19
"id": "address",
_19
"major": 1
_19
}
_19
]
_19
...

In this case, two applications will be created, which function as groups of fields: one with ID profile and one with ID address.

The profile app has two fields:

  • gender
  • age

The address app has only one field:

  • street

Using the API to record/update/query the data

After creating the fields, we need to save the data in them. This can be done using one of the following requests: Set single custom field value or Set multiple custom field values.

Set single custom field value

To update a value of a specific custom field, you can use this endpoint by sending the value to be updated (appFieldValue) through the request body. The following information must be sent as path parameters in the URL:

See a URL and request body example below:

URl: https://{accountName}.{environment}.com.br/api/checkout/pub/orderForm/ede846222cd44046ba6c638442c3505a/customData/address/street


_10
{
_10
"value": "Bourbon Street"
_10
}

Set multiple custom field values

To update values of multiple custom fields at the same time, you can use this endpoint by sending all the values and their respective fields to be updated in the request body (appFieldValue and appFieldName). The following information must be sent as path parameters in the URL:

  • orderFormId: ID of the orderForm that will receive the new custom field values.
  • appId: ID of the app created through the Update orderForm Configuration endpoint.

See a URL and request body example below:

URl: https://{accountName}.{environment}.com.br/api/checkout/pub/orderForm/ede846222cd44046ba6c638442c3505a/customData/address


_10
{
_10
"street": "Bourbon Street",
_10
"number": "78",
_10
"postalCode": "11554"
_10
}

After choosing one of the methods and sending the URL request, the terminal will return the response body containing the updated custom data information, as shown in the example below:


_15
...
_15
"customData": {
_15
"customApps": [
_15
{
_15
"fields": {
_15
"street": "Bourbon Street",
_15
"number": "78",
_15
"postalCode": "11554"
_15
},
_15
"id": "address",
_15
"major": 1
_15
}
_15
]
_15
},
_15
...

Finding the desired data in the created order

Finally, it is necessary to implement access to the data saved in the orderForm’s extra fields. To do this, use the Get Order API, appending the order ID to the URL.

The fields and their respective values will be inside the customData object.

Remove single custom field value

To remove the value of a specific custom field, you can use the Remove single custom field value endpoint by sending the following information as path parameters in the URL:

See a URL and request body example below:

https://{accountName}.{environment}.com.br/api/checkout/pub/orderForm/ede846222cd44046ba6c638442c3505a/customData/address/street

Error codes

The following errors may appear as a message in the response body.

Set single custom field value and Set multiple custom field values endpoints

400 - Bad Request

  • Message error example (code ORD002): "Invalid order form": this message indicates that the orderFormId used in the request does not exist or is incorrect.

_10
{
_10
"fields": {},
_10
"error": {
_10
"code": "ORD002",
_10
"message": "Invalid order form",
_10
"exception": null
_10
},
_10
"operationId": "f2b8107f-e5d5-4b7c-b719-344d1b05d1fa"
_10
}

  • Message error example (code CHK0121): "Invalid app fields": this message indicates that the value was not sent in this request.

_10
{
_10
"fields": {},
_10
"error": {
_10
"code": "CHK0121",
_10
"message": "Invalid app fields",
_10
"exception": null
_10
},
_10
"operationId": "62cf897f-2025-4304-8e25-2104b58d416d"
_10
}

404 - Not found

  • Message error example (code CHK0090): "App id not found": this message indicates that the appId parameter used in the request does not exist or is incorrect.

_10
{
_10
"fields": {},
_10
"error": {
_10
"code": "CHK0090",
_10
"message": "App id not found",
_10
"exception": null
_10
},
_10
"operationId": "0926942a-769b-45ec-a7c3-3d733ed76a46"
_10
}

  • Message error example (code CHK0091): "App key not found for id profile": this message indicates that the appFieldName parameter used in the request does not exist or is incorrect. This message code is applicable only for the Set single custom field value endpoint.

_10
{
_10
"fields": {},
_10
"error": {
_10
"code": "CHK0091",
_10
"message": "App key not found for id profile",
_10
"exception": null
_10
},
_10
"operationId": "6e8191fb-4f2a-41c8-8155-92d2595a96b3"
_10
}

Update orderForm configuration endpoint

400 - Bad Request

  • Message error example (code CHK0288): "Invalid configuration": this message indicates that the mandatory parameters (paymentConfiguration, requiresAuthenticationForPreAuthorizedPaymentOption and minimumQuantityAccumulatedForItems) was not sent in this request.

_10
{
_10
"fields": {},
_10
"error": {
_10
"code": "CHK0288",
_10
"message": "Invalid configuration",
_10
"exception": null
_10
},
_10
"operationId": "f2b8107f-e5d5-4b7c-b719-344d1b05d1fa"
_10
}

Contributors
2
Photo of the contributor
Photo of the contributor
+ 2 contributors
Was this helpful?
Yes
No
Suggest edits (Github)
Contributors
2
Photo of the contributor
Photo of the contributor
+ 2 contributors
On this page