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 low-code checkout, you can add custom fields to the experience.

Digital River adds what these fields contain to the checkout-session so that you can use it in downstream processes.

Setup custom fields

On Digital River 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.

If you mark it as required, then express checkout is disabled in Prebuilt Checkout.

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

Prebuilt Checkout

Physical products in items[]

Digital only products in items[]

Address Component

Physical products in items[]

Digital only products in items[]

If you marked a field as required, and customers don't provide a value, they are prompted for an input.

Prebuilt Checkout

Address Component

Number only fields provide help text if customers enter a non-digit character.

Prebuilt Checkout

Address Component

Number and text fields accept values with a maximum length of 500 characters.

Labels aren't translated into the language of the checkout-session, but instead default to English.

Implement custom fields in Components

The done() function, which submits the data collected by the address component in an update checkout-session request, returns false if the user (1) fails to enter a value in a custom field that you marked as required or (2) enters a value that exceeds 500 characters in a custom number or text field.

If your application is setup correctly, this should block customers from proceeding to the checkout's next stage.

For details, refer to Controlling the checkout flow.

If you mark a custom field as required in Dashboard, then you might want to disable the wallet component. When users click a button in this component, they're redirected to a payment provider. But the form in the provider's interface doesn't contain a field to collect your custom data, and, as a result, it won't get added to the checkout-session.

Retrieve the collected data

After customers successfully 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

{
    "id": "66524f24-74d5-4356-b30f-ff1da95db3eb",
    "type": "order.accepted",
    "data": {
        "object": {
            "id": "295121620336",
           ...
            "metadata": {
                "freeSample": "chewToy",
                "giftCardMessage": "A special treat for Zoey's birthday"
            },
            ...
        }
    },
    ...
}

fulfillment.created

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 to onCheckoutComplete in Prebuilt Checkout's configuration object and then implementing a handler.

• Assigning a callback to onSuccess in the Component's configuration object and then implementing a handler.

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