> For the complete documentation index, see [llms.txt](https://docs.digitalriver.com/digital-river-api-reference/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-reference/digital-river-api-reference-guide/working-with-metadata.md).

# Working with metadata

You can use `metadata` to store additional information, structured as key-value pairs.

In the Digital River APIs, `metadata` can be added to [SKUs](/digital-river-api-reference/2021-12-13/skus.md), [checkouts](/digital-river-api-reference/2021-12-13/checkouts.md), [checkout sessions](/digital-river-api-reference/2021-12-13/drop-in-checkout-sessions.md), [invoices](/digital-river-api-reference/2021-12-13/invoices.md), [orders](/digital-river-api-reference/2021-12-13/orders.md), [customers](/digital-river-api-reference/2021-12-13/customers.md), [fulfillments](/digital-river-api-reference/2021-12-13/fulfillments.md), [returns](/digital-river-api-reference/2021-12-13/returns.md), [refunds](/digital-river-api-reference/2021-12-13/refunds.md), [plans](/digital-river-api-reference/2021-12-13/plans.md), [subscriptions](/digital-river-api-reference/2021-12-13/subscriptions.md), [fees](/digital-river-api-reference/2021-12-13/fees.md), and [fulfillment orders](/digital-river-api-reference/2021-12-13/fulfillment-orders.md). 

{% hint style="warning" %}
Do not save any sensitive information, such as a customer's bank account or credit card details, in `metadata`.
{% endhint %}

You can also attach `metadata` to each `items[]` in a [checkout](/digital-river-api-reference/2021-12-13/checkouts.md), [checkout session](/digital-river-api-reference/2021-12-13/drop-in-checkout-sessions.md), [invoice](/digital-river-api-reference/2021-12-13/invoices.md), [order](/digital-river-api-reference/2021-12-13/orders.md), and [fulfillment order](/digital-river-api-reference/2021-12-13/fulfillment-orders.md).

Digital River doesn't use this data; your users will only see it if you display it.

## Supported data types

The keys in `metadata` can be assigned strings, numbers, booleans, objects, arrays, and `null`.

{% code title="Customer" %}

```json
{
    "id": "674583010336",
    ...
    "metadata": {
        "adminName": "John Doe",
        "adminId": 5827134,
        "rewardProgram": false,
        "marketingConsents": {
            "email": true,
            "SMS": false,
            "newsLetter": true
        },
        "previousAddresses": [
            {
                "line1": "Rudi-Dutschke-Straße 26",
                "city": "Berlin",
                "postalCode": "10176",
                "jurisdiction": null,
                "country": "DE"
            },
            {
                "line1": "21 Delaware",
                "city": "Saint Paul",
                "postalCode": "55017",
                "jurisdiction": "MN",
                "country": "US"
            }
        ]
    },
    ...
}
```

{% endcode %}

## Restrictions

There must be at least one valid key-value pair in `metadata`. 

You can add a maximum of 20 primary key-value pairs to `metadata`. However, if you need additional entries, you can use nested keys.

A key's name can't contain more than 40 characters, and its assigned value can't exceed 500 characters. If you have values longer than this, store them in an external database and use a key-value pair in `metadata` to reference that external object’s identifier.

## Add metadata

In applicable create and update API operations, you can add one or more key-value pairs to `metadata`.

{% tabs %}
{% tab title="Request" %}

```
curl --location 'https://api.digitalriver.com/customers' \
--header 'Authorization: Bearer <API key>' \
--data '{
    "metadata": {
        "adminName": "John Doe",
        "adminId": 5827134
    }
}'
```

{% endtab %}

{% tab title="Response" %}
{% code title="Customer" %}

```json
{
    "id": "674582640336",
    "createdTime": "2024-07-11T15:22:25Z",
    "enabled": true,
    "requestToBeForgotten": false,
    "metadata": {
        "adminName": "John Doe",
        "adminId": 5827134
    },
    "locale": "en_US",
    "type": "individual",
    "liveMode": false
}
```

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

## Update metadata

When updating certain API resources, you can replace the value of an existing key in `metadata`. For example, if a shopper agrees to start receiving newsletters from your organization, you could handle that by flipping your `metadata.marketingConsents.newsLetter` in the [customer  ](/digital-river-api-reference/2021-12-13/customers.md)object to `true`.&#x20;

{% tabs %}
{% tab title="Before" %}
{% code title="Customer" %}

```json
{
    "id": "674545580336",
    ...
    "metadata": {
        "marketingConsents": {
            "email": true,
            "SMS": false,
            "newsLetter": false
        }
    },
    ...
}
```

{% endcode %}
{% endtab %}

{% tab title="Update" %}
{% code title="Update customer" %}

```
curl --location 'https://api.digitalriver.com/customers/674545590336' \
--header 'Authorization: Bearer <API key>' \
--data '{
    "metadata": {
        "marketingConsents": {
            "newsLetter": true
        }
    }
}'
```

{% endcode %}
{% endtab %}

{% tab title="After" %}
{% code title="Customer" %}

```json
{
    "id": "674545590336",
    ...
    "metadata": {
        "marketingConsents": {
            "email": true,
            "SMS": false,
            "newsLetter": true
        }
    },
    ...
}
```

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

You can also add new key-value pairs without affecting existing data. For example, if a [checkout's](/digital-river-api-reference/2021-12-13/checkouts.md) `metadata` contains a `key1` and a `key2` and you add a `key3`, Digital River merges the new data into the existing data.&#x20;

{% tabs %}
{% tab title="Before" %}
{% code title="Checkout" %}

```json
{
    "id": "e68062ca-b705-40c9-b491-29b6110c62a8",
    ...
    "metadata": {
        "key1": "value",
        "key2": "value"
    },
    ...
}
```

{% endcode %}
{% endtab %}

{% tab title="Update" %}

```
curl --location 'https://api.digitalriver.com/checkouts/e68062ca-b705-40c9-b491-29b6110c62a8' \
--header 'Authorization: Bearer <API key>' \
    "metadata": {
        "key3": "value"
    }
}'
```

{% endtab %}

{% tab title="After" %}
{% code title="Checkout" %}

```json
{
    "id": "e68062ca-b705-40c9-b491-29b6110c62a8",
    ...
    "metadata": {
        "key1": "value",
        "key2": "value",
        "key3": "value"
    },
    ...
}
```

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

## Delete metadata

To remove a key from `metadata`, assign it an empty string value.&#x20;

{% tabs %}
{% tab title="Before" %}
{% code title="Customer" %}

```json
{
    "id": "674545630336",
    ...
    "metadata": {
        "key1": "value",
        "key2": "value"
    },
    ...
}
```

{% endcode %}
{% endtab %}

{% tab title="Update" %}
{% code title="Update customer" %}

```
curl --location 'https://api.digitalriver.com/customers/674545630336' \
--header 'Authorization: Bearer <API key>' \
--data '{
    "metadata": {
        "key1": ""
    }
}'
```

{% endcode %}
{% endtab %}

{% tab title="After" %}
{% code title="Customer" %}

```json
{
    "id": "674545630336",
    ...
    "metadata": {
        "key2": "value"
    },
    ...
}
```

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

## Metadata in events

Digital River adds an object's `metadata` to related [events](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Events) before sending them to your [webhooks](/digital-river-api-reference/2021-12-13/webhooks.md). For example, when [creating a checkout-session](/digital-river-api-reference/2021-12-13/drop-in-checkout-sessions.md#drop-in-checkout-sessions), you might decide to add a `cartId` to `metadata`.&#x20;

```
curl --location 'https://api.digitalriver.com/drop-in/checkout-sessions' \
--header 'Authorization: Bearer <API key>' \
--data-raw '{
    ...
    "metadata": {
        "cartId": "efv4334t6"
    },
    ...
}'
```

After the customer provides payment and completes checkout, Digital River creates an [event](/digital-river-api-reference/2021-12-13/webhooks.md) with a [`type` ](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-types)of [`checkout_session.order.created`](https://docs.digitalriver.com/digital-river-api-reference/digital-river-api-reference-guide/spaces/-LqH4RJfLVLuHPXuJyTZ/pages/okHqAQ9d1PaLPLjq6nZF#checkout_session.order.created), adds that `cartId` to `metadata` in its [`data.object`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-data), and then pushes that [event ](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1)to any of your [webhooks ](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1)that have subscribed to it. Your webhook handlers can use this data in product fulfillment and other downstream processes.&#x20;

{% code title="Event" %}

```json
{
    "id": "e7fab7e3-d4ad-4c21-b29d-abe589ec7017",
    "type": "checkout_session.order.created",
    "data": {
        "object": {
            ...
            "metadata": {
                "cartId": "efv4334t6"
            },
            ...
        }
    },
    "liveMode": false,
    "createdTime": "2024-07-11T17:09:47.559906Z[UTC]"
}
```

{% endcode %}

## Copying metadata

Digital River doesn't always transfer `metadata` from one related object to another. For example,  if an [order](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Orders) contains `metadata`, and that [order](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Orders) is refunded, then we don't add its `metadata` to the [refund](/digital-river-api-reference/2021-12-13/refunds.md). To do this, you'd need to write your own code that moves this data from one object to the other. &#x20;

In some cases, however, Digital River handles this transfer. For example:

* **Checkout sessions to checkouts**: When you [create a checkout session](/digital-river-api-reference/2021-12-13/drop-in-checkout-sessions.md#drop-in-checkout-sessions), its `metadata` is passed to the underlying [checkout](/digital-river-api-reference/2021-12-13/checkouts.md).
* **Checkout sessions to checkout links**: When you [create a checkout link](/digital-river-api-reference/2021-12-13/drop-in-checkout-links.md), it inherits any `metadata` that exists in the [checkout-session](/digital-river-api-reference/2021-12-13/drop-in-checkout-sessions.md).&#x20;
* **Checkouts to orders**: When a `checkoutId` is passed in a [create order request](/digital-river-api-reference/2021-12-13/orders.md#orders-1), then any `metadata` that exists in that [checkout ](/digital-river-api-reference/2021-12-13/checkouts.md)is added to the [order](/digital-river-api-reference/2021-12-13/orders.md).
* **Orders to fulfillments**: When a [fulfillment](/digital-river-api-reference/2021-12-13/fulfillments.md) is created, any `metadata` in its upstream [order](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Orders) is added to its `orderDetails`. If you then later update the [order's](/digital-river-api-reference/2021-12-13/orders.md) `metadata`, those updates are reflected in the [fulfillment's ](/digital-river-api-reference/2021-12-13/fulfillments.md)`orderDetails`.&#x20;