# 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;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digitalriver.com/digital-river-api-reference/digital-river-api-reference-guide/working-with-metadata.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.