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.
Digital River adds what these fields collect to the checkout-session so that you can use it in downstream processes.
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.
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."
}
]
}

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:
- ​Configuring a webhook to listen for certain types of events, such as
checkout_session.order.created
,order.accepted
,fulfillment.created
,order.fulfilled
, andorder.refunded
.
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.Last modified 24d ago