Stripe Invoice Custom Fields and QuickBooks

Your customer will not pay an invoice that does not carry their purchase order number. Their accounts payable system matches on it, and an invoice without one gets held, queried, and paid three weeks late. So you put the PO number on the Stripe invoice, where it belongs, using the field Stripe provides for exactly this.

Then the invoice syncs to QuickBooks, and the PO number is not there.

This is not a sync failure, and nothing is broken. It is a straightforward mismatch between two systems that both have a feature called custom fields and mean substantially different things by it. This post covers what a Stripe invoice custom field actually is, what happens to it at the QuickBooks boundary, and the four things you can do instead. If you need the value to be queryable in QuickBooks rather than merely printed in Stripe, the answer is that you have to put it somewhere else, and the choice of where has consequences worth understanding before you pick.

If you want your Stripe invoices arriving in QuickBooks with line items, tax and payments intact while you sort out where the reference data goes, you can start a free trial.

What a Stripe custom field actually is

Stripe's API reference is terse about it. On the invoice object, custom fields are documented as "Custom fields displayed on the invoice." That is the whole entry.

The customization documentation is more useful. Custom fields "allow you to provide up to four key-value pairs that display in the invoice header," and you can set them "in the Invoice Editor, with the Invoices API, or with Invoice Templates."

Three properties of that definition do most of the work in practice.

They are display objects. They live in the invoice header, next to the invoice number and dates. They are not line items, they do not carry an amount, and they do not participate in any total. Stripe renders them; nothing calculates with them.

There are four of them, maximum. Not four per category or four per type. Four key-value pairs on the invoice, total. Businesses that want a PO number, a contract reference, a cost centre and a project code have used their entire allowance and have nothing left for the fifth thing somebody asks for next quarter.

Stripe names your use case explicitly. The documentation lists common uses as "Purchase Order (PO) numbers," "Contractor numbers," and "Tax compliance." The PO number is the first example Stripe gives, which is a fair signal of what this field is mostly used for in the wild.

There is also an inheritance rule that saves a great deal of manual entry, and that surprises people when it fires. Custom fields set on the customer "apply to all of the draft invoices you generate for that customer." If a customer always pays against the same blanket PO, set it once on the customer and every draft picks it up.

The four fields people confuse with each other

Stripe has several places to put free text on an invoice, and they behave differently enough that choosing wrong is a real problem. This is the comparison worth having in front of you.

Field	Where it shows	Editable after finalization	Typical use
Custom fields	Invoice header, PDF and hosted page	No	PO number, contract reference, tax registration
Footer	Bottom of the invoice PDF	No	"Contractual or legally required text"
Description (memo)	PDF, emails, hosted invoice page	Yes	A note to the customer
Metadata	Nowhere customer-facing	Yes	Internal keys for your own systems

The distinction that matters most is the last column crossed with the third. Metadata is the field engineers reach for by instinct, because it is a structured key-value store and that is what a PO number looks like to a developer. But metadata is invisible to the customer. A PO number in metadata does not print, so the accounts payable team never sees it, and the invoice gets held exactly as if you had not recorded it at all.

The footer is the opposite mistake. It prints, so people use it as an overflow field when they have run out of custom fields. Stripe describes it as being "often used for contractual or legally required text," and it is a single block of prose rather than a key-value pair, so anything you put there is unstructured by construction.

The freeze at finalization

Both of the fields that print are frozen once the invoice leaves draft. Stripe states it twice, once for each field. On custom fields: "After the invoice finalizes, you can't update the custom fields." On the footer: "If an invoice has been finalized, you can't update its footer field."

This is the single most expensive fact on this page, because the PO number is usually the thing that turns out to be wrong.

The sequence is familiar to anyone who invoices businesses. You issue the invoice. The customer's AP team replies that the PO number is wrong, or that the PO was reissued, or that procurement changed the reference after the quote was approved. In most invoicing systems you correct the field and resend. In Stripe you cannot, because the invoice is finalized and the field is closed.

What you can do is issue a revision, which creates a new invoice from the old one and lets you set the fields correctly on the new draft. That is a heavier operation than editing a field, and it has its own accounting consequences worth understanding before you reach for it. Stripe invoice revisions and what they do to QuickBooks covers the mechanics, including the one that actually costs money.

The practical corrective is procedural rather than technical: confirm the PO number while the invoice is still a draft. If your invoices are generated from quotes, the draft window is where this belongs, and the quote-to-invoice path already hands you a draft and waits, precisely so that a PO number, a due date or an approval can be added before anything goes out.

What actually crosses into QuickBooks

Here is the honest answer, and it is worth stating plainly rather than burying in caveats.

When a Stripe invoice is finalized, Acodei creates a QuickBooks invoice that reproduces every line item, and tax lines, as the account's mapping settings allow. Line items and tax lines are what the sync is built to carry. Each line uses the product returned by Multiple Product Mapping if that is enabled, and the default product otherwise.

Acodei's product documentation does not describe a destination for a Stripe invoice custom field or footer in QuickBooks. It does not say the value is mapped somewhere, and it does not say the value is deliberately discarded. It simply does not cover the question, and the correct thing to do with an undocumented behavior is to check your own QuickBooks file rather than assume in either direction. Open a synced invoice, look at whether any field carries your PO value, and you will know in thirty seconds what no amount of reasoning from first principles will tell you.

There is one adjacent behavior that is documented, and it points the same way. On customer data specifically, Acodei's documentation states that it "does not currently support pulling addresses from Stripe metadata or custom fields," and lists "No metadata support" among the known limitations of customer matching. That is a narrow statement about customer address and name resolution rather than a general rule about invoice fields, so it should not be stretched into one. But it does tell you that custom fields are not a channel the integration reads for the one purpose where the documentation addresses them directly. If you were planning to route customer identity through a custom field, that path is documented as closed. How Acodei matches Stripe customers to QuickBooks covers what it does read instead.

This is the same shape as another field that buyers care about and that has no documented landing zone, and rather than repeat the argument, the customer tax ID case works through it in full.

QuickBooks has custom fields too, and they are not the same thing

The reason this feels like it should work is that QuickBooks Online also has a feature called custom fields. It is worth understanding what they are, because the resemblance is superficial and it sets false expectations.

Intuit's documentation puts the allowance at "4 per transaction" on Essentials and Plus, and "12 per transaction" on Advanced. They can be added to "invoices, sales receipts, refund receipts, estimates, credit memos, purchase orders, expenses, and bills," and each has a Print on form toggle controlling whether it appears on the document the customer receives.

So both systems cap the ordinary tier at four fields, both attach them to invoices, and both print them. The similarity ends at the point that matters: they are separate definitions in separate systems, and one does not populate the other. A field named "PO Number" in QuickBooks is a QuickBooks object you created. A field named "PO Number" in Stripe is a Stripe object you created. Nothing about the matching label creates a mapping between them.

There is a second, sharper trap here, and it catches people who have already read about custom fields in a QuickBooks context. QuickBooks custom fields are not the Custom transaction numbers setting, which lives under Account and settings, then Sales, then Sales form content, and which governs the invoice number itself rather than any additional field. That setting matters a great deal for a synced account, for reasons covered in duplicate protection between Stripe and QuickBooks. It is a different thing from what this post is about, and conflating the two produces a plan that does not work.

While we are on invoice numbers: Acodei's Invoice Number Suffix setting appends "-AC1", "-AC2" and so on to synced invoices, to prevent duplicate-number errors when someone also hand-enters invoices directly in QuickBooks. It is on by default. If you have been trying to match a Stripe invoice to a QuickBooks invoice by number and the numbers look almost but not quite right, that suffix is the reason, and it is doing its job.

Four things that actually work

None of these is a mapping, because there is no mapping. They are the four honest options, ranked by how much operational weight they can carry.

1. Put the PO number in the line item description. Line items are what the sync is built to carry, so a reference that lives in a line description travels with the transaction into QuickBooks by the same path as everything else on the invoice. This is the highest-reliability option available and it is deliberately boring. The cost is aesthetic: the reference appears mid-invoice rather than in the header where AP teams expect it, and it will not look like a proper PO field on the printed document. Many businesses put it in both places, header custom field for the customer's benefit and line description for their own.

2. Use the custom field for the customer and accept the reference stops at Stripe. If the PO number's entire job is to get the invoice through the customer's AP process, this is sufficient and you should not over-engineer it. The invoice prints correctly, the customer pays, and your QuickBooks record is a clean revenue entry that reconciles to the payment. The Stripe invoice remains the system of record for the reference, and the hosted invoice page and PDF are permanently available for audit. Not every field needs to be in every system.

3. Record it in QuickBooks separately, after the fact. If you genuinely need the value queryable in QuickBooks, this is where a QuickBooks custom field earns its place, populated by hand or by your own process. It is real work per invoice and it will not scale past modest volume, but it produces the thing you actually asked for: a reportable field in your accounting system. Reserve it for the invoices where the reference is doing real work, such as contract billing where you will need to reconcile against a purchase order.

4. Restructure so the reference is the customer. For customers who bill against a single standing PO for a long engagement, the reference is arguably an attribute of the relationship rather than the invoice. Setting the custom field at the customer level in Stripe means every draft inherits it, and the reporting question in QuickBooks becomes "show me this customer" rather than "show me this PO," which QuickBooks answers natively. This only works when the mapping between customer and PO is genuinely one to one, and it fails badly when a customer has many concurrent POs.

Deciding which one you need

The question that resolves this quickly is not "how do I map custom fields," because that is asking for something that does not exist. The useful question is: who needs to read this value, and in which system?

If the answer is the customer's AP department, the value needs to print in Stripe, and where it lands in QuickBooks does not matter. Use a custom field and stop.

If the answer is your own bookkeeper, reconciling against a contract or a purchase order, the value needs to be queryable in QuickBooks, and the custom field is the wrong instrument. Use the line description, or accept manual entry.

If the answer is both, use both, and be explicit that they are two records of the same fact rather than one record synced between two systems. That distinction is what stops someone from later assuming that correcting one corrects the other.

A checklist before your next invoice run

Decide the PO number before finalization, not after. The field is frozen at finalization and a correction means issuing a revision.
Count your custom fields. Four is the cap. If you are near it, decide now which reference matters most.
Do not put a printing requirement in metadata. Metadata does not print. If the customer needs to see it, it is a custom field or a line description.
Check one synced invoice in your own QuickBooks file and confirm where, if anywhere, your header values arrive. Thirty seconds of looking beats any assumption.
If you need it queryable in QuickBooks, put it in a line description. That is the field the sync is built to carry.
Do not confuse QuickBooks custom fields with Custom transaction numbers. They are different settings solving different problems.

The underlying point is a general one. A sync between two accounting systems carries the things both systems model the same way: amounts, dates, customers, line items, tax. Free-text reference data that one system treats as header decoration and the other treats as a user-defined column is exactly the category where a clean mapping does not exist, and the productive move is to decide which system owns the fact rather than to keep looking for a setting that would make both own it.

If you want your Stripe invoices in QuickBooks with the line items, tax and payments landing correctly, start a free trial or see how Stripe to QuickBooks sync handles invoice sync end to end.

Sources: Stripe's invoice object reference and invoice customization documentation, and Intuit's guidance on custom fields in QuickBooks Online, all fetched August 2026.

Frequently asked questions

Does Acodei sync Stripe invoice custom fields to QuickBooks?

Acodei's product documentation does not describe a destination in QuickBooks for a Stripe invoice custom field or footer. It documents that a finalized Stripe invoice creates a QuickBooks invoice reproducing every line item and tax lines as your mapping settings allow, which is what the sync is built to carry. Because the custom field question is not covered either way, check a synced invoice in your own QuickBooks file rather than assuming. If you need the value to be reliably present in QuickBooks, put it in a line item description.

How many custom fields can a Stripe invoice have?

Four. Stripe documents that custom fields "allow you to provide up to four key-value pairs that display in the invoice header." That is the total for the invoice, not four per category. You can set them in the Invoice Editor, through the Invoices API, or with Invoice Templates.

Can I change a PO number on a Stripe invoice after sending it?

No. Stripe states that "after the invoice finalizes, you can't update the custom fields," and the same restriction applies to the footer. Correcting a reference on a finalized invoice means issuing a revision, which creates a new invoice from the original. Confirm the PO number while the invoice is still a draft.

Should I put a PO number in Stripe metadata instead?

Not if the customer needs to see it. Metadata is an internal key-value store and does not appear on the invoice PDF, the hosted invoice page or the emails, so a PO number stored there will not reach the customer's accounts payable team. Metadata is the right place for internal identifiers your own systems read, and the wrong place for anything that has to print.

Are QuickBooks custom fields the same as Stripe custom fields?

No. They are separate user-defined fields in separate systems, and a matching label does not create a mapping between them. Intuit allows four custom fields per transaction on Essentials and Plus and twelve on Advanced, attachable to invoices, sales receipts, refund receipts, estimates, credit memos, purchase orders, expenses and bills. Creating a field called "PO Number" in QuickBooks does not cause Stripe's field of the same name to populate it.

Why do my synced invoice numbers have a suffix like -AC1?

That is Acodei's Invoice Number Suffix setting, which appends "-AC1", "-AC2" and so on to prevent duplicate-number errors when invoices are also entered by hand in QuickBooks. It is on by default. If you are matching Stripe invoices to QuickBooks invoices by number, expect the suffix.

Can Acodei use a custom field to identify the customer?

No, and this one is documented directly. Acodei's customer data documentation states that it "does not currently support pulling addresses from Stripe metadata or custom fields," and lists "No metadata support" among the known limitations of customer matching. Customer resolution reads the Stripe customer name, with the billing name on the charge as a fallback, and address data from the customer address or the charge billing details.

A custom field is a key-value pair displayed in the invoice header, capped at four. The footer is a single free-text block at the bottom of the PDF, which Stripe describes as "often used for contractual or legally required text" such as a company registration number. Both print, and both are frozen once the invoice is finalized. The footer is unstructured, so it is a poor substitute for a custom field when you have run out of the four.

Stripe Invoice Custom Fields and QuickBooks: Where the PO Number Goes