# 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](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/skus), [checkouts](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts), [checkout sessions](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/drop-in-checkout-sessions), [invoices](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/invoices), [orders](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders), [customers](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers), [fulfillments](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillments), [returns](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/returns), [refunds](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/refunds), [plans](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans), [subscriptions](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions), [fees](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fees), and [fulfillment orders](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders). 

{% 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](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts), [checkout session](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/drop-in-checkout-sessions), [invoice](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/invoices), [order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders), and [fulfillment order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders).

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  ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers)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](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) `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](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/webhooks). For example, when [creating a checkout-session](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/drop-in-checkout-sessions#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](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/webhooks) with a [`type` ](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1#event-types)of [`checkout_session.order.created`](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1/event-types#checkout_session.order.created), adds that `cartId` to `metadata` in its [`data.object`](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1#event-data), and then pushes that [event ](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1)to any of your [webhooks ](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/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](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/refunds). 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](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/drop-in-checkout-sessions#drop-in-checkout-sessions), its `metadata` is passed to the underlying [checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts).
* **Checkout sessions to checkout links**: When you [create a checkout link](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/drop-in-checkout-links), it inherits any `metadata` that exists in the [checkout-session](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/drop-in-checkout-sessions).&#x20;
* **Checkouts to orders**: When a `checkoutId` is passed in a [create order request](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders#orders-1), then any `metadata` that exists in that [checkout ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)is added to the [order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders).
* **Orders to fulfillments**: When a [fulfillment](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillments) 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](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders) `metadata`, those updates are reflected in the [fulfillment's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillments)`orderDetails`.&#x20;