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.

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:

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

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.

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:

• 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.
• appFieldName: name of the app's field 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/street

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

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:

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.

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:

• orderFormId: ID of the orderForm where the custom field value will be deleted.
• appId: ID of the app created through the Update orderForm Configuration endpoint.
• appFieldName: name of the app's field created through the Update orderForm Configuration endpoint and which will be deleted.

See a URL and request body example below:

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

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

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.

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

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.

• 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.

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.