Create custom columns using metadata

You can store and send supplementary information through metadata. Metadata consists of key-value pairs associated with objects or transactions. Metadata lets you attach custom information to Stripe data, so you can store and retrieve relevant details alongside your core transaction data.

You can use metadata to filter and retrieve specific information from Stripe reports, facilitating the creation of targeted reports to extract precise data.

Learn more about metadata.

Use metadata

You can use metadata as part of your Stripe integration in various ways. Some possible use cases are:

• Storing internal IDs to match Stripe objects to objects in your own systems
• Reconciling financial data provided by Stripe with your own systems
• Adding context to Stripe objects, like payments, to assist with troubleshooting
• Custom reporting and advanced querying of Stripe data in Sigma

See sample API calls for these use cases.

Select metadata in financial reports

1. Go to the relevant report, such as Balance, Payout Reconciliation, or Activity.
2. Click Download.
3. Select All Columns.
4. If you have objects with metadata attached, they appear in the corresponding Metadata section.

Where metadata can be used

You can use metadata for reporting purposes across a range of objects, specifically: Charge, Refund, Invoice, Payment, PaymentIntent, Transfer, Product, Customer, Subscription, InvoiceItem, Price, TaxTransaction, CreditNote, Contract, and ContractItem.

Troubleshoot missing metadata

Metadata might be missing if the amount of metadata exceeds the limit of 50 metadata keys that can be displayed in a download. The metadata columns included in the export contains the first 50 keys that were defined on the relevant objects.

If you have ceased using certain keys and subsequently introduced new ones, the newer keys won’t be incorporated into the export. This is the case even if you retroactively remove all instances of the older keys from your charges or other objects. The metadata columns are not dynamically generated during the export process; instead, they’re established when a new key is added, up to the maximum limit of 50 keys.

If the 50 key limit for an object is reached and not all keys are currently in use for a specific object, contact Stripe support. Request the removal of unused keys from the object to enable the report download with the necessary fields.

Best practices

Here are some recommendations:

• Plan your metadata strategy in advance to avoid reaching the 50 key limit
• Use consistent naming conventions for your metadata keys
• Regularly review and clean up unused metadata keys
• Consider using prefixes for different types of metadata (for example, “customer_”, “order_”) for better organization