Glossary
Stripe Metadata
Stripe metadata is a set of key-value pairs you can attach to most Stripe objects to carry your own information, such as an internal order ID or a product category, which Stripe stores and returns but never acts on itself.
Also called: metadata keys, charge metadata, metadata mapping
Definition
Every business using Stripe eventually needs Stripe to remember something Stripe does not care about. An internal order number. A course code. Which region a sale belongs to. Metadata is the field for exactly that.
It is a simple structure: a set of key-value pairs, both stored as strings, attached to an object. Stripe describes it as a way "to store additional, structured information on an object", and gives the example of storing a user's full name and internal identifier on a Customer.
The two properties that make it useful are also the two that surprise people. Stripe does not read it, and neither does your customer. Stripe is explicit on both counts: "Stripe doesn't use metadata, for example, we don't use it to authorize or decline a charge and it won't be seen by your users unless you choose to show it to them."
That inertness is the point. Metadata is a place to put your own meaning, and it is the only field on a Stripe object where you can put arbitrary structure without changing how the payment behaves. It is also why metadata matters so much to accounting integrations: it is often the only field carrying the distinction your chart of accounts cares about.
Key points
- +Metadata is available on updateable Stripe objects, including Account, Charge, Customer, PaymentIntent, Refund, Subscription and Transfer.
- +You can specify up to 50 keys per object.
- +Key names are limited to 40 characters and values to 500 characters.
- +Keys and values are stored as strings. A number written into metadata comes back as a string.
- +Keys and values can contain any characters with one exception: square brackets are not allowed in keys.
- +Stripe does not use metadata in its own logic. It will not authorize or decline a charge based on it.
- +Metadata is never shown to your customers unless you build something that shows it to them. It does not appear on receipts or hosted invoice pages.
- +Stripe warns against storing sensitive information, such as bank account numbers or card details, in metadata.
- +The description field is the opposite trade: a single string, visible to customers in places such as Stripe email receipts.
Metadata versus description versus custom fields
These three get confused constantly, and the difference that matters is who can see them.
Metadata is structured and invisible. You get key-value pairs, and nobody outside your systems sees them. Description is unstructured and visible: a single human-readable string, which Stripe notes your users might see, for example in email receipts Stripe sends on your behalf. Invoice custom fields are structured and visible, printing on the invoice itself.
The practical failure follows directly. A purchase order number written into metadata does not print, so the customer's accounts payable team never sees it and the invoice gets held exactly as if you had never recorded it. If a human on the other end needs to read it, metadata is the wrong field. If your own systems need to read it, metadata is the right one.
Where the value has to live
Metadata is attached to a specific object, not to a payment in the abstract, and this is where integrations most often come up empty.
A single completed purchase can involve a Payment Link, a Checkout Session, a PaymentIntent, a Charge, an Invoice and a Subscription. Each of those is a separate object with its own metadata map. Writing a value onto one of them does not put it on the others. Stripe does not propagate metadata down the chain for you.
So the question is never just "did we set metadata". It is "which object did we set it on, and is that one of the objects the thing reading it actually looks at". A no-code setup that writes everything useful onto the Payment Link has metadata that a reader looking at charges will never find.
How Acodei uses Stripe metadata
Metadata is one of the six ways Acodei can decide which QuickBooks product a transaction posts against, alongside description, transaction value, Stripe product with and without a pricing tier, and Stripe account.
Acodei reads mapping metadata in a fixed order: Payment or Charge first, then PaymentIntent, then Invoice, then Subscription. The first object carrying your key wins. The Checkout Session and the Payment Link are not in that list, so metadata attached to either of those is not what metadata mapping matches on.
Mapping rules are evaluated top to bottom and evaluation stops at the first match, so a broad rule sitting above a specific one will intercept transactions meant for the specific one. Acodei recommends placing exact metadata matches at the top of the list for that reason. If no rule matches, the behaviour depends on your settings: either a default catch-all product is used, or the transaction raises a sync error, which surfaces as "No matching product rule found".
Two limits are documented and worth knowing before you design your keys. Acodei does not support multi-key matching, so a single rule cannot require both a region value and a product-type value; the usual workaround is writing one composite key. It also does not support matching multiple lines from the same transaction, so one transaction resolves to one mapped product rather than a per-line breakdown. Matching is literal, and Acodei records past problems with special characters and spaces, so a misspelled or missing key simply fails to match.
One boundary is worth stating plainly, because the natural assumption is wrong. Metadata drives product mapping, not customer resolution. Acodei's customer documentation states that it does not currently support syncing customer names via Stripe metadata, does not pull addresses from Stripe metadata or custom fields, and lists no metadata support among the known limitations of customer matching. Customer records are resolved by name, with email or a default name as fallbacks.
Want to see this on your own Stripe data?
Start a free trialFrequently asked questions
How many metadata keys can a Stripe object have?
Up to 50. Key names can be up to 40 characters long and values up to 500 characters. Both are stored as strings, and square brackets are not allowed in key names.
Can customers see Stripe metadata?
No. Stripe states that metadata will not be seen by your users unless you choose to show it to them. It does not print on invoices or appear on receipts. If you need a reference the customer can read, use an invoice custom field or the description instead.
Does Stripe use metadata for anything?
No. Stripe stores it and returns it, but does not act on it. Stripe gives declining or authorizing a charge as an explicit example of something metadata does not influence.
Why is my metadata not being picked up for product mapping?
The most common reason is that the value is on the wrong object. Acodei reads metadata from the Payment or Charge, then the PaymentIntent, then the Invoice, then the Subscription. Metadata on a Payment Link or a Checkout Session is not read for mapping. The next most common reasons are a key that does not match literally, including a stray space or special character, and a broader rule sitting above yours in the list and matching first.
Can one mapping rule match two metadata keys at once?
No. Multi-key matching is documented as unsupported, so a rule cannot require two metadata values together. Writing a single composite key that encodes both values is the usual approach.
Can Acodei match QuickBooks customers using Stripe metadata?
No. Customer matching does not read metadata. Acodei documents that it does not support syncing customer names via metadata and does not pull addresses from metadata or custom fields. Customers are resolved by name, falling back to email or a default name depending on your settings.
What customers say about running Stripe through Acodei
“If you're testing out all the different Stripe/QuickBooks integration apps right now, let me save you some time. This one is the best one by far.”
“Works well and is really helpful for massive transactions. The support is really fast and helpful. 100% recommended.”
Related reading
- When a Stripe charge maps to the wrong QuickBooks product
- What Multiple Product Mapping does
- Stripe Payment Links in QuickBooks
- Amounts product mapping cannot reach
- Stripe invoice custom fields in QuickBooks
More glossary terms
- Undeposited Funds
- Stripe Balance Transaction
- Available vs Pending Balance
- Stripe Dispute
- Stripe Dispute Evidence
- Stripe Fee
- Stripe Balance Adjustment
- QuickBooks Credit Memo
- Stripe Tax
- QuickBooks Tax Code
- Stripe Reserve
- Stripe Tax Rate
- Stripe Fee Credit
- Stripe Credit Note
- QuickBooks Product/Service Item
- Stripe Payout
- QuickBooks Sales Receipt
- QuickBooks Bank Deposit
- QuickBooks Transfer
- Stripe Authorization Hold
- QuickBooks Refund Receipt
- QuickBooks Payment
- QuickBooks Expense
- QuickBooks Journal Entry
- Stripe Financial Account
- Holding Account
- Accounts Receivable
- Bank Feed
- Deferred Revenue
- Stripe PaymentIntent
- Stripe Checkout Session
- Stripe SetupIntent
- Stripe PaymentMethod
- Stripe Charge
- Stripe Refund
- QuickBooks Invoice
- QuickBooks Class Tracking
- QuickBooks Location Tracking
- QuickBooks Project
- QuickBooks Closing Date
- Stripe Invoice Line Item
- Stripe Proration
- Stripe Invoice Status
- Stripe Shipping Rate
- Stripe Transfer
- Stripe Mandate
- Stripe on_behalf_of
- Stripe Invoice Item
- QuickBooks Estimate
- Stripe Invoice Payment
- Stripe Invoice Payment Settings
- Stripe Billing Meter
- Stripe Invoice Template
- Stripe Price
- Stripe Subscription Schedule
- Stripe Subscription Item
- QuickBooks Recurring Transaction
- QuickBooks Sub-Customer
- QuickBooks Audit Log
- QuickBooks Bank Rule
- Stripe Subscription Status
- Stripe Mixed Interval Subscription
- Stripe Trial Settings
- QuickBooks Payment Terms
- Stripe Pending Update
- QuickBooks Tags
- QuickBooks Credit Card Credit
- QuickBooks Vendor Credit
- QuickBooks Bill
- QuickBooks Delayed Charge
- Stripe Billing Mode
- QuickBooks Billable Expense
- Stripe Customer Cash Balance
- QuickBooks Purchase Order
- QuickBooks Opening Balance
- QuickBooks Account Type
- QuickBooks Sales Tax Center
- Stripe Webhook
Ready to try Acodei?
Connect Stripe to QuickBooks Online in minutes and let the fees, refunds, and payouts land where your accountant expects them.