Metadata use cases

Use these examples to store your data on Stripe objects.

Use metadata to store your important data on Stripe objects with these common examples. The following use cases aren’t exhaustive; how you use metadata depends on your specific use cases.

Security tip

Don’t include sensitive data in metadata, such as PII, bank account details, or customer card details.

Store IDs for objects or records

You can use metadata in Stripe objects to store IDs that belong to objects or records from your other systems. This allows you to build references between Stripe objects and their related resources from your other systems.

Order or cart ID

When you create IDs to track your customers’ carts, you can store those IDs as metadata on Checkout Sessions. This allows you to use the related Stripe object to locate the associated cart in your system after the checkout process is complete.

Store the cart ID in the metadata of the Checkout Session after you create it:

Then, you can view, update, or delete the ID on the Checkout Session object. It also appears in the events sent to your webhook endpoint that contain that Checkout Session (including the checkout.session.completed event).

{
  "id": "evt_1PYCL6CzbZon1zn9VivIehz7",
  "object": "event",
  "api_version": "2024-06-20",
  "created": 1719948368,
  "data": {
    "object": {
      "id": "cs_test_a1Znb7gdtlLEPzSi8qMIJzvsSPpIBMKFWovXx0h0O43WS411PpICgCqKjw",
      "object": "checkout.session",
      ...
      "metadata": {
        "cart_id": "cart_6943"
      },
      ...
    }
  },
  ...
  "type": "checkout.session.completed",
}

Customer or CMS ID

You can associate the Customers you create in Stripe with your customer management system (CMS) records to help track and manage your customers.

Store the ID of the customer record from your CMS in the metadata of the Customer you create in Stripe.

Stripe includes this information in the events sent to your webhook endpoint that contain that Customer object. For example, when you receive customer.updated events, you can use the stored ID to identify the record you need to update in your CMS.

{
  "id": "evt_1PajAGCzbZon1zn9FUsn7IoG",
  "object": "event",
  "api_version": "2024-06-20",
  "created": 1720551204,
  "data": {
    "object": {
      "id": "cus_QRcNyZh9aZHXnI",
      "object": "customer",
      ...
      "metadata": {
        "cms_id": "cust_6573"
      },
      ...
    }
  },
  ...
  "type": "customer.updated"
}

Track order fulfillment

Use metadata to store data that facilitates or tracks your order fulfillment processes.

Price or Product ID on a payment intent

When you directly create payment intents, you can associate them with your products or prices using metadata. This allows you to store the ID of the associated objects on the payment intent, which lacks an existing field that associates them with a price or product.

You can locate the ID of the associated object in events that include that payment intent, such as payment_intent.succeeded events. Then, pass the metadata from the event to your downstream processes (for example, order fulfillment or inventory management).

{
  "id": "evt_3PajIyCzbZon1zn90b9Wvsqf",
  "object": "event",
  "api_version": "2024-06-20",
  "created": 1720551759,
  "data": {
    "object": {
      "id": "pi_3PajIyCzbZon1zn901xQeOdi",
      "object": "payment_intent",
      ...
      "metadata": {
        "price_id": "price_1MoBy5LkdIwHu7ixZhnattbh",
        "product_id": "prod_NWjs8kKbJWmuuc"
      },
      ...
    }
  },
  ...
  "type": "payment_intent.succeeded",
}

Fulfillment status and tracking

After you begin your order fulfillment flow, you can use metadata to record the current fulfillment status on the associated Stripe object. This allows you to retrieve an object from Stripe, and receive both the payment status and fulfillment status simultaneously.

To update the current fulfillment status:

Track affiliate links

In some cases, Stripe copies metadata from the original object to a related object. If you have affiliates hosting Payment Links on their sites and offer incentives for sales originating from those links, you can use this behavior in your affiliate tracking.

When you create payment links, you can populate metadata to track your affiliate:

Every time a customer uses that link to complete a purchase, Stripe creates a Checkout Session that inherits the metadata that you provided on the payment link. You can monitor checkout.session.completed events to receive notifications from Stripe when a customer completes a purchase. You can then pull your affiliate tracking details from the Checkout Session’s metadata to attribute the sale accurately.

{
 "id": "evt_1PajfeCzbZon1zn9S7pNlQkU",
 "object": "event",
 "api_version": "2024-06-20",
 "created": 1720553150,
 "data": {
   "object": {
      "id": "cs_test_a1zgRtgzjvamTgTnqMqIaqP6zehBIkaM03iYzxNjZiJ7FMDRRhibd5w3gL",
      "object": "checkout.session",
      ...
      "metadata": {
        "affiliate": "afl_7920"
      },
      ...
    }
  },
  ...
  "type": "checkout.session.completed",
}

Store notes

You can use metadata to store notes on objects. For example, to create a note of a customer’s preferred call time, add metadata to the Customer object:

To store a note that details why an Invoice was voided, you can use the metadata on the Invoice object:

Set metadata indirectly

The placement of your metadata determines which event types contain the information you provide. Similarly, if you’re tracking certain event types in your integration, it determines where you place your metadata.

Certain object creation endpoints contain multiple fields for your metadata: one for storing metadata directly on the object being created, and others for setting metadata on downstream-created objects. Learn more about the indirect metadata fields.

The following example creates a Checkout Session that generates a subscription when completed. This uses the top-level metadata field, and the subscription_data.metadata field:

You can set metadata on the object that you create (in this case, the Checkout Session). After your customer completes the checkout process, the metadata previously provided in subscription_data.metadata is set on the newly created Subscription object. This determines which events include the metadata. For example, events that contain a Checkout Session, such as checkout.session.completed, contain values provided through the top-level metadata parameter.

{
  "id": "evt_1PakshCzbZon1zn9PlQwJYn0",
  "object": "event",
  "api_version": "2024-06-20",
  "created": 1720557803,
  "data": {
    "object": {
      "id": "cs_test_a1lsYmNYnEqQAxHT9knVy8v7u7m5ChjKtyB3M68ovMCjUQgCADsCkUviUU",
      "object": "checkout.session",
      ...
      "metadata": {
        "checkout_metadata": "Checkout Session metadata goes here"
      },
      ...
    }
  },
  ...
  "type": "checkout.session.completed",
}

Events that contain a Subscription object, such as customer.subscription.created, contain values provided through subscription_data.metadata. However, because that event contains a Subscription object, Stripe provides the values in the top-level metadata field on the Subscription object.

{
  "id": "evt_1PaksgCzbZon1zn9x9u3MTSC",
  "object": "event",
  "api_version": "2024-06-20",
  "created": 1720557800,
  "data": {
    "object": {
      "id": "sub_1PaksdCzbZon1zn9D6DQjr9L",
      "object": "subscription",
      ...
      "metadata": {
        "subscription_metadata": "Subscription metadata goes here"
      },
      ...
    }
  },
  ...
  "type": "customer.subscription.created",
}

You can access the metadata you provide in subscription_data.metadata in the invoice events. This occurs because the subscription’s metadata is transferred to subscription_details.metadata on the Invoice objects created by the subscription.

{
  "id": "evt_1PaksgCzbZon1zn9wD24BlvY",
  "object": "event",
  "api_version": "2024-06-20",
  "created": 1720557800,
  "data": {
    "object": {
      "id": "in_1PaksdCzbZon1zn9Z4bl0z7k",
      "object": "invoice",
      ...
      "subscription_details": {
        "metadata": {
          "subscription_metadata": "Subscription metadata goes here"
        }
        ...
      },
    }
  },
  ...
  "type": "invoice.finalized",
}

Store large amounts of metadata

Use metadata fields in Stripe to store data directly or store an external lookup key to access additional data from your own database, minimizing the information you need to retrieve.

Store structured data

Metadata can accept any string, including those representing structured data such as JSON, up to 500 characters. You can use it to store more data within your metadata fields, reducing the number of keys you need to access to retrieve all your information.

Store metadata externally

To associate more data with an object than the 500 characters the provided metadata fields allow, store the excess data in your own database. You can then use metadata to store the ID or lookup key for accessing that information. This approach is similar to storing the ID of any other record in your system.

Use metadata with other Stripe APIs and products

You can use metadata with other Stripe APIs and products to enhance their flexibility and extensibility.

Radar

You can write Radar rules to reference metadata values and use them to determine if a rule triggers its associated action for a transaction.

Perform initial review of customer transactions

You can set up a flow to flag a customer’s initial transaction for review, then update the customer’s details to omit subsequent transactions from review.

Review if ::customer:verified_customer:: != 'true'

Stripe only triggers this rule for payments if verified_customer is set to false on the customer. Customers who have that set to true aren’t affected.

A/B testing rules

You can use metadata with Radar to create A/B testing scenarios for new rules, allowing you to evaluate a new rule’s effectiveness before implementing it across your entire customer base.

Block if ::experiment_group:: = 'treatment' and :card_funding: = 'prepaid'

Stripe only triggers this rule for payments that you label as part of the treatment group. It doesn’t affect payments set to control as their experiment_group.

The Search API

Use the Search API to query and filter results based on the metadata that you set on the supported objects you’re searching for.

For example, you can track your “premium” customers by adding metadata to the Customer object. To offer them exclusive promotions, use the Search API to identify customers marked as premium, then reach out to them with the promotion.

Objects must be indexed before they appear in results from the Search API. The objects won’t show up in search results until that indexing completes.