> For the complete documentation index, see [llms.txt](https://docs.digitalriver.com/digital-river-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts/adding-custom-fields.md).

# Adding custom fields

If you’d like to collect additional customer information during a [low-code checkout](/digital-river-api/integration-options/low-code-checkouts.md), you can add custom fields to the experience.

Digital River adds what these fields contain to the [checkout-session](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/drop-in-checkout-sessions#drop-in-checkout-sessions) so that you can use it in downstream processes.

## Setup custom fields

On [Digital River Dashboard’s Prebuilt Checkout page](/digital-river-api/administration/dashboard/settings/prebuilt-checkout.md), 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.

<figure><img src="/files/CvbKaMw2rE955uzSQl59" alt=""><figcaption></figcaption></figure>

For each field, you need to:

* Indicate whether it’s required or optional.

{% hint style="warning" %}
If you mark it as required, then express checkout is disabled in [Prebuilt Checkout](/digital-river-api/integration-options/low-code-checkouts/drop-in-checkout.md).
{% endhint %}

* 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 must enumerate acceptable values and provide a display label for each.

## The checkout experience

Depending on whether you add [physical or digital-only products](/digital-river-api/product-management/skus.md#how-products-are-classified-as-physical-or-digital) to the [checkout-session’s](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/drop-in-checkout-sessions/checkout-sessions-basics) [`items[]`](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/drop-in-checkout-sessions/checkout-sessions-basics#product-data)Digital River renders your custom fields in the shipping or billing information forms.

{% tabs %}
{% tab title="Prebuilt Checkout" %}
**Physical products in `items[]`**

<div align="left"><figure><img src="/files/uEl6JcyNRNlPx5hjCCnw" alt=""><figcaption></figcaption></figure></div>

**Digital only products in `items[]`**

<div align="left"><figure><img src="/files/muJUFaTr2nJBT0Gda1Dt" alt=""><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="Address Component" %}
**Physical products in `items[]`**

<div align="left"><figure><img src="/files/XRkaGtwrSlkoKFBX3vkw" alt=""><figcaption></figcaption></figure></div>

**Digital only products in `items[]`**

<div align="left"><figure><img src="/files/2H3TMOQh16JWHdxekIEH" alt=""><figcaption></figcaption></figure></div>
{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="Prebuilt Checkout" %}

<div align="left"><figure><img src="/files/cW72ikCpYETfD6rvxzZB" alt=""><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="Address Component" %}

<div align="left"><figure><img src="/files/G7tXBiVK9pC6kWjFEC3h" alt=""><figcaption></figcaption></figure></div>
{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="Prebuilt Checkout" %}

<div align="left"><figure><img src="/files/P0vK8mOQXalwBuLlyLcl" alt=""><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="Address Component" %}

<div align="left"><figure><img src="/files/T9WNnXwYyPXzYinZBkDZ" alt=""><figcaption></figcaption></figure></div>
{% endtab %}
{% endtabs %}

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

Labels aren't translated into the [`language` ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/drop-in-checkout-sessions/checkout-sessions-basics#language)of the [checkout-session](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/drop-in-checkout-sessions), but instead default to English.

## Implement custom fields in Components

The [`done()`](/digital-river-api/integration-options/low-code-checkouts/implementing-a-components-checkout.md#submitting-components) function, which submits the data collected by the [address component](/digital-river-api/developer-resources/digitalrivercheckout.js-reference/digitalrivercheckout-object/components/address-component.md) in an update [checkout-session](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/drop-in-checkout-sessions) 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 set up correctly, this should block customers from proceeding to the checkout's next stage.

For details, refer to [Controlling the checkout flow](/digital-river-api/integration-options/low-code-checkouts/implementing-a-components-checkout.md#controlling-the-checkout-flow).

You might want to disable the [wallet component](/digital-river-api/developer-resources/digitalrivercheckout.js-reference/digitalrivercheckout-object/components/wallet-component.md), if you [mark a custom field as required in the Digital River Dashboard](#setup-custom-fields),  When users click a button in this component, they are redirected to a payment provider. However, the form in the provider's interface lacks a field to collect your custom data, so it won't get added to the [checkout-session](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/drop-in-checkout-sessions/checkout-sessions-basics).

## 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](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/drop-in-checkout-sessions#drop-in-checkout-sessions) `metadata`.

You can access this data by:

* [Configuring a webhook](/digital-river-api/order-management/events-and-webhooks-1/webhooks/creating-a-webhook.md) to listen for certain [types](/digital-river-api/order-management/events-and-webhooks-1/events-1.md#event-types) of [events](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/events), such as [`checkout_session.order.created`](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts/pages/okHqAQ9d1PaLPLjq6nZF#checkout_session.order.created), [`order.accepted`](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts/pages/okHqAQ9d1PaLPLjq6nZF#order.accepted), [`fulfillment.created`](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts/pages/okHqAQ9d1PaLPLjq6nZF#fulfillment.created), `order.fulfilled`, and [`order.refunded`](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts/pages/okHqAQ9d1PaLPLjq6nZF#order.refunded).

{% tabs %}
{% tab title="order.accepted" %}

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

{% endtab %}

{% tab title="fulfillment.created" %}
{% code title="Event" %}

```json
{
    "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"
                },
                ...
            }
        }
    },
   ...
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

* Assigning a callback to [`onCheckoutComplete`](/digital-river-api/developer-resources/digitalrivercheckout.js-reference/digitalrivercheckout-object/configuring-prebuilt-checkout.md#oncheckoutcomplete) in [Prebuilt Checkout's configuration object](/digital-river-api/developer-resources/digitalrivercheckout.js-reference/digitalrivercheckout-object/configuring-prebuilt-checkout.md) and then implementing a handler.
* Assigning a callback to [`onSuccess`](/digital-river-api/developer-resources/digitalrivercheckout.js-reference/digitalrivercheckout-object/components/configuring-components.md#success-event) in the [Component's configuration object](/digital-river-api/developer-resources/digitalrivercheckout.js-reference/digitalrivercheckout-object/components/configuring-components.md) and then implementing a handler.
* Making a call to [retrieve the order](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/orders#orders).

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.