Metadata
Learn how to use metadata to save additional information.
Metadata is an attribute on certain Stripe objects that lets you store more information, structured as key-value pairs, to these objects for your own use and reference. For example, you can store your user’s unique identifier from your system on a Stripe Customer object.
Configuration 
Data
You can add 50 total key-value pairs within these data limits:
- key: 40 character limit. Square brackets (
[]) can’t be included in keys. - value: 500 character limit.
If your system requires more space than this, store your data in your external database and use a key-value pair to store the external object’s ID in metadata.
Unless you use metadata with Radar, Stripe doesn’t use metadata—for example, to authorize or decline a charge. Additionally, metadata isn’t visible to your customers unless you choose to show it.
Security tip
Never store sensitive information, such as bank account information or credit card details, to metadata.
Requests
Stripe only returns metadata when you use a secret key in your requests. We redact metadata from objects in response to publishable key requests, such as Stripe.js or Mobile SDKs client-side requests.
Add and update metadata
Add key-values pairs to metadata, update metadata values, and replace keys using the API. You can combine different actions into a single request to perform multiple metadata additions, updates, and deletions simultaneously.
Add key-value pairs
To add key-value pairs to metadata when creating an object, provide the keys and values in the object creation request.
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "cms_id": "6573" }, ... }
Add key-value pairs to existing metadata
To add key-value pairs to an existing object’s metadata, provide the keys and values in an update request.
Note
This parameter uses a merge mechanism, which allows you to add new key-value pairs to an object in an update call without affecting any existing metadata. For example, if a Customer object has key1 and key2, when you update it to add key3, the updated object contains all three keys.
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "cms_id": "6573" }, ... }
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "no", "cms_id": "6573" }, ... }
Update metadata values
To update the value for an existing key in metadata, pass in the new value using the existing key. For example, you can update a Customer object with an existing key-value pair of "loyalty_ to"loyalty_.
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "no" }, ... }
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "yes" }, ... }
Update metadata keys
To update a key that has an existing value, delete the key and pass its value to a new key. For example, you can update a Customer object to delete its "loyalty_ key and pass the key’s value of "yes" to a new "rewards_ key.
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "yes" }, ... }
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "rewards_program": "yes" }, ... }
Delete metadata
Delete a single key or an entire set of keys using the API.
Delete a single key
Pass in the key with an empty string as the value to remove the key from the metadata.
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "yes", "loyalty_member_id": "12345678" }, ... }
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "yes" }, ... }
Delete all keys
Pass an empty object as the value for the metadata attribute to delete all of the keys simultaneously.
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": { "loyalty_program": "yes", "loyalty_member_id": "12345678" }, ... }
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", ... "metadata": {} ... }
Copy metadata to another object
An object’s metadata doesn’t automatically copy to related objects. To view an object’s metadata, you must inspect that object. To retrieve metadata from a related object, build custom logic to find and inspect the related object. To explicitly copy metadata from one object to another, you need to build your own flow.
Exceptions
In certain cases, we copy metadata from one object to another for backwards compatibility and other unique scenarios.
| Object mapping | Description |
|---|---|
| Payment Intent to Charge | When a Payment Intent creates a Charge, the metadata copies to the Charge in a one-time snapshot. Updates to the Payment Intent’s metadata won’t apply to the Charge. |
| Payment Link to Checkout Session | When a Payment Link creates a Checkout Session, the metadata copies to the Checkout Session in a one-time snapshot. Updates to the Payment Link’s metadata won’t apply to the Checkout Session. |
| Subscription to Invoice | When a Subscription creates an Invoice, the metadata copies to the Invoice object’s parent.subscription_details.metadata attribute in a one-time snapshot. Updates to the subscription’s metadata won’t apply to the Invoice. |
| Subscription to Invoice Line Item | When an Invoice Line Item’s type is set to subscription, it presents the subscription’s current metadata. |
Set metadata indirectly
Some endpoints accept a metadata parameter nested inside of another parameter. You can use these parameters when you create an object to set metadata on an underlying object. For example, you can use payment_ when you create a Checkout Session to provide and set metadata on the underlying Payment Intent the session creates.
| Object mapping | Description |
|---|---|
| Checkout Session to Payment Intent | Data sent with the payment_intent_data.metadata attribute saves to the underlying Payment Intent’s metadata. |
| Checkout Session to Subscription | Data sent with the subscription_data.metadata attribute saves to the underlying Subscription’s metadata. |
| Payment Link to Payment Intent | Data sent with the payment_intent_data.metadata attribute saves to the metadata of each Payment Intent created by the Payment Link. |
| Payment Link to Subscription | Data sent with the subscription_data.metadata attribute saves to the metadata of each Subscription created by the Payment Link. |
| Prices to Products | Data sent with the product_data.metadata attribute saves to the associated Product’s metadata. |
| Subscription Schedule to Subscription | Data sent with the phases.metadata attribute saves to the underlying Subscription’s metadata when the phase is entered. |
| Quote to Subscription | Data sent with the subscription_data.metadata attribute saves to the Subscription’s metadata when a Quote is accepted. |
Events and webhook endpoints
When Stripe sends an Event to your webhook endpoint, it includes the corresponding object and any metadata the object contains. This allows your webhook handler to receive any metadata that you set on Stripe objects and pass it to downstream processes, such as order fulfillment.
For example, to include a cart ID when a customer makes a purchase using a Checkout Session, provide it as metadata when you create the Checkout Session:
When the customer completes the checkout process, we send a checkout.session.completed Event containing the Checkout Session object’s metadata to your webhook endpoint. You must configure your webhook to listen for that Event so you can access the metadata and use it when processing data.
{ "id": "evt_1P8pqUAgEBCHsfP6JfNctbLv", "object": "event", "api_version": "2022-11-15", "created": 1713903702, "data": { "object": { "id": "cs_test_a1aDQuoXLoddIOV9iOvZRgKAtPoRIfFkYHBWxF9AQAPlGG3STB1ndqqaUw", "object": "checkout.session", ... "metadata": { "cart_id": "6943" },
Search metadata
You can search for existing metadata on supported objects by using specific formatting. This includes searching for records with a specific value for a metadata field or checking if a metadata key is present on an object. Learn more about searching for metadata.
Prevent fraud with metadata and Radar
Use metadata with Radar to create custom rules that help prevent fraud. Learn more about Radar metadata attributes.