Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
Versioning
Changelog
Upgrade your API version
Upgrade your SDK version
Developer tools
SDKs
API
    API v2
    API keys
    Stripe-Context header
    Daily changelog
    Rate limits
    Automated testing
    Metadata
      Metadata use cases
    Expanding responses
    Pagination
    Domains and IP addresses
    Search
    Localization
    Error handling
    Error codes
Testing
Workbench
Event Destinations
Workflows
Stripe CLI
Stripe Shell
Developers Dashboard
Agent toolkit
Stripe health alertsBuild with LLMsStripe for Visual Studio CodeFile uploads
Security
Security
Extend Stripe
Stripe Apps
Stripe Connectors
Partners
Partner ecosystem
Partner certification
HomeDeveloper toolsAPI

Metadata

Learn how to use metadata to save additional information.

Copy page

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.

If you want to display a single field to customers, explore using description.

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.

Command Line
cURL
curl https://api.stripe.com/v1/customers \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d name="Jenny Rosen" \ -d "metadata[cms_id]"=6573
{ "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.

Command Line
cURL
curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "metadata[loyalty_program]"=no
Before
After
{ "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_program": "no" to"loyalty_program": "yes".

Command Line
cURL
curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "metadata[loyalty_program]"=yes
Before
After
{ "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_program" key and pass the key’s value of "yes" to a new "rewards_program" key.

Command Line
cURL
curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "metadata[loyalty_program]"= \ -d "metadata[rewards_program]"=yes
Before
After
{ "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.

Command Line
cURL
curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "metadata[loyalty_program]"=yes \ -d "metadata[loyalty_member_id]"=
Before
After
{ "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.

Command Line
curl
curl https://api.stripe.com/v1/customers/
{{CUSTOMER_ID}}
-u
sk_test_BQokikJOvBiI2HlWgH4olfQ2
-d "metadata"=""
Before
After
{ "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 mappingDescription
Payment Intent to ChargeWhen 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 SessionWhen 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 InvoiceWhen 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 ItemWhen 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_intent_data.metadata when you create a Checkout Session to provide and set metadata on the underlying Payment Intent the session creates.

Object mappingDescription
Checkout Session to Payment IntentData sent with the payment_intent_data.metadata attribute saves to the underlying Payment Intent’s metadata.
Checkout Session to SubscriptionData sent with the subscription_data.metadata attribute saves to the underlying Subscription’s metadata.
Payment Link to Payment IntentData sent with the payment_intent_data.metadata attribute saves to the metadata of each Payment Intent created by the Payment Link.
Payment Link to SubscriptionData sent with the subscription_data.metadata attribute saves to the metadata of each Subscription created by the Payment Link.
Prices to ProductsData sent with the product_data.metadata attribute saves to the associated Product’s metadata.
Subscription Schedule to SubscriptionData sent with the phases.metadata attribute saves to the underlying Subscription’s metadata when the phase is entered.
Quote to SubscriptionData 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:

Command Line
cURL
curl https://api.stripe.com/v1/checkout/sessions \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ --data-urlencode success_url="https://example.com/success" \ -d mode=payment \ -d "line_items[0][price]"=price_1MotwRLkdIwHu7ixYcPLm5uZ \ -d "line_items[0][quantity]"=1 \ -d "metadata[cart_id]"=6943

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.

Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc