Working with metadata

Gain a better understanding of metadata, including its restrictions, how to manage it, and how it flows from one API object to another

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

In the Digital River APIs, metadata can be added to SKUs, checkouts, checkout sessions, invoices, orders, customers, fulfillments, returns, refunds, plans, subscriptions, fees, and fulfillment orders.

Do not save any sensitive information, such as a customer's bank account or credit card details, in metadata.

You can also attach metadata to each items[] in a checkout, checkout session, invoice, order, and fulfillment order.

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.

Customer

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

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.

Request

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

Response

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 object to true.

Before

Customer

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

Update

After

You can also add new key-value pairs without affecting existing data. For example, if a checkout's metadata contains a key1 and a key2 and you add a key3, Digital River merges the new data into the existing data.

Before

Checkout

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

Update

After

Delete metadata

To remove a key from metadata, assign it an empty string value.

Before

Customer

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

Update

After

Metadata in events

Digital River adds an object's metadata to related events before sending them to your webhooks. For example, when creating a checkout-session, you might decide to add a cartId to metadata.

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 with a type of checkout_session.order.created, adds that cartId to metadata in its data.object, and then pushes that event to any of your webhooks that have subscribed to it. Your webhook handlers can use this data in product fulfillment and other downstream processes.

Event

{
    "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]"
}

Copying metadata

Digital River doesn't always transfer metadata from one related object to another. For example, if an order contains metadata, and that order is refunded, then we don't add its metadata to the refund. To do this, you'd need to write your own code that moves this data from one object to the other.

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

• Checkout sessions to checkouts: When you create a checkout session, its metadata is passed to the underlying checkout.

• Checkout sessions to checkout links: When you create a checkout link, it inherits any metadata that exists in the checkout-session.

• Checkouts to orders: When a checkoutId is passed in a create order request, then any metadata that exists in that checkout is added to the order.

• Orders to fulfillments: When a fulfillment is created, any metadata in its upstream order is added to its orderDetails. If you then later update the order's metadata, those updates are reflected in the fulfillment's orderDetails.