Creating customizable fields in the cart with Checkout API

During the checkout process, 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 do this, you can use both Custom Data calls: one to create extra fields in the orderForm and the other to set the value of each of these fields.

This data will be available within the Order, in the orders APIs (Orders management).

See here the Custom Data API full documentation.

Creating customizable fields

To create custom fields in the orderForm, use the call below:

• URL: https://{{AccountName}}.vtexcommercestable.com.br/api/checkout/pvt/configuration/orderForm

• Method: POST

See below an example of the JSON that we must pass in the body of this call.


_27{
_27	"paymentConfiguration": 
_27	{
_27		"requiresAuthenticationForPreAuthorizedPaymentOption": false
_27	},
_27	"minimumQuantityAccumulatedForItems": 1,
_27	"decimalDigitsPrecision": 2,
_27	"minimumValueAccumulated": 0,
_27	"apps": 
_27	[
_27		{
_27			"id":"profile",
_27			"fields":
_27			[
_27				"age",
_27				"gender"
_27			]
_27		},
_27		{
_27			"id":"address",
_27			"fields":
_27			[
_27				"phone2"
_27			]
_27		}
_27	]
_27}

The apps object is what defines the customizable fields that will be inserted into the store's orderForm.

When we make the call by passing the sample body above, two applications will be created, which function as groups of fields: one with ID profile and one with ID address.

In the profile app, we have two fields:

age
gender

In the address app, we will have one field:

phone2

Defining the value of customizable fields

Once the fields are created with the call explained above, you can also send values to them using the API.

To do this, use the call below:

• URL: https://{{AccountName}}.vtexcommercestable.com.br/api/checkout/pub/orderForm/{{orderFormId}}/customData/{{appName}}/{{appFieldName}}

• Method: PUT

See below an example of the JSON that we must pass in the body of this call.


_18{
_18  "expectedOrderFormSections":
_18  [
_18    "items",
_18    "gifts",
_18    "totalizers",
_18    "clientProfileData",
_18    "shippingData",
_18    "paymentData",
_18    "sellers",
_18    "messages",
_18    "marketingData",
_18    "clientPreferencesData",
_18    "storePreferencesData",
_18    "customData"
_18  ],
_18  "value":{{appFieldValue}}
_18}

In the URL of the call, you must pass the following parameters:

{{orderFormId}}: ID of the orderForm to which the values will be sent.
{{appName}}: name of the app (that is, of the group of fields defined in the previous call) where the values will be sent.
{{appFieldName}}: name of the field for which to set the value. In the example of the fields created in the previous call, it could be age, gender or phone2.

In the body you must pass the {{appFieldValue}}, which is the value to be sent.