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:
​Configuring a webhook to listen for certain types of events, such as checkout_session.order.created, order.accepted, fulfillment.created, order.fulfilled, and order.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"
                },
                ...
            }
        }
    },
   ...
}
Assigning a callback method to onCheckoutComplete.
Making a call to retrieve the order.
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.
Processing subscription acquisitions
Offering store credit
Last modified 24d ago