Links
Comment on page

Adding custom fields

Learn how to add custom fields to a Prebuilt Checkout
If you’d like to collect additional information from customers during a Prebuilt Checkout, you can add custom fields to the experience.
This feature is not yet supported in Components.
Digital River adds what these fields collect to the checkout-session so that you can use it in downstream processes.

Setup custom fields

On Dashboard’s Prebuilt Checkout page, you can configure a maximum of two custom fields, each of which can accept a number, text (i.e., string), or a set of pre-defined drop-down options.
For each field, you need to:
  • Indicate whether it’s required or optional.
  • Define a unique key and make sure it contains no whitespaces.
  • Define a label that will be displayed to customers in the experience.
If you’re using the drop-down field, you’ll also need to enumerate a list of acceptable values, along with a display label for each.

The checkout experience

Depending on whether you add physical or digital-only products to the checkout-session’s items[], Digital River renders your custom fields in the shipping information or billing information form, respectively.
Physical products in items[ ]
Only digital products in items[ ]
If you marked a field as required, and customers don't provide a value, they are prompted for an input.
Number only fields provide help text if customers enter a non-digit character.
Number and text fields accept values that have a maximum length of 500 characters—anything longer than that and the update checkout-session request fails, onError is triggered, and customers are blocked from proceeding to the checkout's next stage.
onError
{
"type": "bad_request",
"errors": [
{
"code": "invalid_metadata_value",
"parameter": "metadata",
"message": "The metadata value for metadata key 'giftCardMessage' exceeds
the maximum permitted length of 500 characters."
}
]
}
Labels aren't translated into the language of the checkout-session, but instead default to English.

Retrieve the collected data

After customers submit the form, Digital River adds the key and value of each field they completed to the checkout-session’s metadata.
You can access this data by:
order.accepted
fulfillment.created
{
"id": "66524f24-74d5-4356-b30f-ff1da95db3eb",
"type": "order.accepted",
"data": {
"object": {
"id": "295121620336",
...
"metadata": {
"freeSample": "chewToy",
"giftCardMessage": "A special treat for Zoey's birthday"
},
...
}
},
...
}
Event
{
"id": "9baea62d-cec5-49e1-b8ac-8546b2007e8d",
"type": "fulfillment.created",
"data": {
"object": {
"id": "ful_854dee4b-cf4b-43b9-aecb-89d46a9f96cf",
...
"orderDetails": {
"id": "295121620336",
...
"metadata": {
"freeSample": "chewToy",
"giftCardMessage": "A special treat for Zoey's birthday"
},
...
}
}
},
...
}
Once you have this metadata, you can use it to populate email notifications, fulfill an order’s goods, or perform other operations of your choice.