Stripe Charge Mapped to Wrong QuickBooks Product

A $49 charge for your premium tier shows up in QuickBooks under "General Sales." The subscription revenue you were trying to separate out is back in the bucket you built the mapping to escape. Nothing errored. The sales receipt is there, the amount is right, the deposit reconciles, and the only thing wrong is the line item.

This is the most common mapping complaint we see, and it is almost never a bug. It is one design decision behaving exactly as documented, colliding with a rule list that grew over time. Once you know the decision, the diagnosis takes about a minute.

Running into this right now? Start a free trial or read on for the fix.

The design fact everything else follows from

Acodei's mapping engine evaluates your rules from top to bottom, and on the first match it stops searching. The rule that wins is the first one that matches, not the best one, not the most specific one, and not the one you added most recently.

That is the whole mechanism. Every misrouting story below is a variation on it: some rule higher in the list matched a transaction you meant for a rule lower in the list, and the engine never got to yours.

The practical consequence is that a rule list is not a set of independent instructions. It is a sequence, and adding a rule at the wrong position silently changes the behavior of every rule beneath it. A broad description rule dropped at position 2 will quietly intercept traffic from the six specific rules you wrote at positions 3 through 8, and nothing about that shows up as an error. Both rules are valid. Both point at real QuickBooks products. The transactions just stop arriving where you expected.

Acodei's own guidance is to put the most specific rules at the top and let broad catch-all rules sit at the bottom. That ordering is not a style preference. In a first-match system it is the only ordering that makes specific rules reachable.

Where the description actually comes from

Description matching is where ordering bites hardest, because two things compound: the match is loose, and the text being matched is often not the text you are looking at.

The match itself is a substring comparison, and it is not case-sensitive. A rule looking for pro matches "Pro Plan," matches "Professional Services," and matches "Reprocessed Order." If you have a rule for Course sitting above a rule for Course Level 2, the first one wins every time and the second one is dead code.

The subtler half is which field Stripe hands over. Acodei looks for the description in a defined order that depends on what the charge is attached to:

Transaction is	Description read from, in order
Not linked to a Stripe invoice	1. Charge / Payment description<br>2. PaymentIntent
Linked to a Stripe invoice	1. Invoice line item description
Linked to a Stripe Checkout session	1. Product description<br>2. Checkout session line item description

This is the single most useful table in the mapping documentation, and it explains a failure that otherwise looks like nonsense: you set a clean description on the charge, you can see it in the Stripe dashboard, and the rule still does not fire.

If that charge is invoice-linked, Acodei never reads the charge description. It reads the invoice line item description. Those are different objects with different values. In Stripe's API both the Charge and the invoice line item carry a description field documented identically, as "an arbitrary string attached to the object," and nothing forces them to agree. For a subscription renewal the invoice line description is generated by Stripe from the price and product, and it looks like "1 x Pro Plan (at $49.00 / month)," not like whatever you typed on the charge.

This is why description matching is a poor fit for subscription businesses specifically. Acodei's documentation recommends it for low-volume or simple setups where you reliably control the description field, and advises against it for automated or large-scale subscription businesses, because Stripe's default descriptions are generic. The recommendation is not about volume. It is about authorship. On a one-off charge your code writes the description. On a subscription renewal Stripe writes it, and it will change format the moment you rename a product or change a price.

Diagnosis: open the transaction in Stripe, decide which of the three rows above it falls under, and read the description from that object. Then walk your rule list top to bottom and find the first rule whose substring appears in it. That rule is the one that fired.

Value matching, and why a discount breaks it

Transaction value matching compares the gross amount, before fees, against a number you set. For multi-currency accounts it checks the currency first: a charge of 9.99 USD only matches a rule set to USD 9.99, and a rule set to 9.99 in another currency fails.

Two things break it, and both are ordinary business events:

A price change. You raise the Pro tier from $49 to $59. The rule still says 49.00. Every renewal at the new price stops matching that rule and falls through to whatever comes next.

A discount. A 20 percent promo code turns a $49 charge into a $39.20 charge. The base price did not change, the rule did not change, and the match fails anyway, because the rule compares against the amount actually charged. Every customer on that coupon quietly maps somewhere else, and they keep doing it for as long as the coupon lasts.

That second one is worth dwelling on because of how it presents. The revenue does not vanish and no error is raised. You get a clean split in QuickBooks between full-price customers and discounted customers, filed under two different products, and it looks like a reporting quirk rather than a mapping failure. If your income accounts drifted apart right after a promotion, this is the first thing to check.

The durable fix is to stop matching on amounts. Value matching is best reserved for cases where the amount really is the identifying feature and is not going to move.

The archived-price trap

Product mapping with a pricing tier stores both the Stripe product ID and the price ID, which is what lets you route price_monthly and price_annual on the same prod_ to different QuickBooks products. Mapping without a pricing tier routes every charge for that product to one QuickBooks product regardless of which price was used.

The trap is in what archiving a price does. Acodei's documentation notes that when you archive a price in Stripe the mapping stays in place, and a later sync from that archived price can fail. Stripe's side explains why that situation persists rather than resolving itself. The active flag controls "whether the price can be used for new purchases," and Stripe's guidance on archiving a price is explicit about the rest: "If you archive a price, any existing subscriptions that use the price remain active until they're canceled."

So archiving does not end the price's transaction stream, it just stops adding to it. Renewals keep arriving on the archived price until the last subscriber churns or migrates, which means the mapping row pointing at that price ID stays load-bearing for every grandfathered customer you have. Meanwhile the new price you created has no mapping row at all until you add one.

The result is a period, potentially a long one, where the same product generates two streams: grandfathered renewals on the old price that map correctly, and new sales on the new price that do not map at all. Both are working as designed. Neither is what you intended.

When you change a price, treat it as two tasks: add a mapping for the new price ID, and leave the old one alone until the last grandfathered subscription is gone.

Metadata, and its three failure modes

Metadata matching is the most robust technique available, because you control the value and it does not drift when marketing renames something. Acodei reads metadata in this order: Payment/Charge, then PaymentIntent, then Invoice, then Subscription. The first one carrying your key wins.

That order matters more than it looks. If your application writes plan_tier onto the subscription and something else writes a different plan_tier onto the charge, the charge value wins and the subscription value is never consulted.

Three documented limits catch people out:

No multi-line matching within one transaction. You cannot map product_a, product_b, and product_c to three different lines at three different amounts inside a single sales receipt. One transaction resolves to one mapped product. This is tracked as a feature request, not a configuration you are missing. If your Stripe charges routinely bundle several distinguishable products, product-level granularity in QuickBooks is not available for those charges today, and it is better to know that before you build a rule list that assumes otherwise.

No multi-key matching. You cannot write a rule that requires region = US and product_type = ABC. Rules match on one key. The workaround is to have your application write a single composite key, for example mapping_key = us_abc, rather than trying to express the conjunction in the rule list.

Keys are matched literally. A missing key fails. A misspelled key fails. Acodei's documentation specifically calls out past problems with special characters and spaces. Stripe's metadata rules give you room here but not unlimited room: up to 50 keys, key names up to 40 characters, values up to 500 characters, everything stored as strings, and square brackets are not allowed in keys. Keys that get truncated at 40 characters or contain a stray trailing space are matching against something other than what you think you typed.

Pick a naming convention with no spaces, no punctuation beyond underscores, and comfortably under the length limit, then have exactly one place in your code that writes it.

When the charge is not misrouted but unrouted

"Wrong product" sometimes means "no product." If no rule matches, Acodei either falls back to a single catch-all default product or raises a sync error, and which one you get depends on your account's settings and environment. Some configurations deliberately forbid a silent fallback so that nothing lands uncategorized.

Both outcomes are recoverable, and they fail in usefully different ways. The sync error is loud, it sits in the Sync Errors queue, and it waits for you. The fallback is silent, and a month of fallback traffic looks like a genuine shift in your revenue mix.

If you do not know which behavior your account has, that is worth establishing before you need the answer. Check whether unmapped transactions from last month are sitting in Sync Errors or sitting in your catch-all product.

Refunds land somewhere else entirely

This one surprises people because the sale mapped perfectly and the refund did not follow it.

In legacy Multiple Product Mapping there is no option to map refunds to specific products, and the routing depends on the shape of the original transaction:

Refund	Original had	Refund posts to
Partial	One invoiced line item	The original product
Partial	Multiple line items	Default Refund Product
Full	One item on the invoice	The original product
Full	Multiple items on the invoice	Default Refund Product

So a refund on a single-line sale nets against the product it came from, and a refund on a multi-line sale does not. Your income accounts end up carrying net figures for some products and gross figures for others depending on how each original invoice happened to be structured, which is not a distinction any report is going to explain to you.

There is an admin setting, "Always process refund to default refund product?", that sends every refund to the Default Refund Product regardless. Acodei's documentation generally recommends it for clean accounting, and the reasoning is worth stating plainly: when refunds net against the original product, gross revenue in QuickBooks reads lower than your actual gross revenue. You lose the ability to see what you sold separately from what you gave back. Routing all refunds to one product keeps the sales side gross and puts returns in one place, which is how most people expect a P&L to read anyway.

This section describes legacy MPM specifically. If you are on a newer configuration, confirm your refund behavior rather than assuming these four rows apply.

The non-taxable rule

Every QuickBooks product used in Acodei mapping must be marked non-taxable. Tax calculated by Stripe syncs across through the Stripe Tax feature instead. Marking a mapped product taxable in QuickBooks conflicts with the sales and payout math.

This is easy to trip when you create a new QuickBooks product to extend your mapping and accept the default settings. If a newly added mapping is producing amounts that are close to right but not right, check the taxable flag on the QuickBooks product before you look anywhere else.

Fixing it, and what the fix does not do

Two properties of rule changes decide your remediation plan.

Rule changes are not versioned, and they apply to future transactions only. Editing or reordering a rule does not reach back and reclassify anything that already synced. There is no history of what the list looked like last Tuesday, which also means that if the list has been edited a few times you cannot reconstruct which rule fired for an old transaction from the current configuration alone.

Re-syncing uses the current rules. A transaction that failed or needs review can be retried from the Sync Errors queue, and it runs against the rule set as it stands now, including your fix. That is the path for anything that errored.

For transactions that already synced to the wrong product, the sequence is: correct the rule order first so the bleeding stops, then handle the existing records. Fix the list before you fix the history, because a re-sync against an unfixed list reproduces the original mistake.

Acodei logs the mapping rule used, the QuickBooks item ID, and the outcome for each transaction, so the record of which rule actually fired exists per transaction even though the rule list itself is not versioned.

The 60-second diagnosis

Work it in this order. Most cases resolve at step 2.

1. Read the transaction's log entry and note which rule fired and which QuickBooks item it resolved to. This usually ends the investigation, because the rule that fired is rarely the one you assumed.
2. Walk the rule list top to bottom looking for a broader rule above the one you expected. A general description rule sitting above a specific one is the single most common cause.
3. Confirm which field is being matched. For description rules, use the precedence table above and read the description off the object Acodei actually reads, which for invoice-linked charges is the invoice line item, not the charge.
4. Check for a price or discount change if the rule matches on transaction value.
5. Check for an archived or newly created price ID if the rule matches on product and pricing tier.
6. Check the key spelling and the write path if the rule matches on metadata, remembering that only one key per rule is evaluated.
7. Check the taxable flag on the QuickBooks product if the amounts are close but not exact.
8. Reorder, do not rewrite. Most fixes are moving a specific rule above a general one. Rewriting a rule that was never reached does nothing.

Building a rule list that stays diagnosable

The habits that prevent this are cheap:

• Sort by specificity, always. Exact matches on product ID or metadata at the top. Substring description matches below them. Catch-all at the bottom, if you use one.
• Prefer identifiers over text. Product IDs and metadata keys are stable. Descriptions and amounts are marketing surface area and will change without anyone telling accounting.
• Add the mapping when you add the price, not at month end. The gap between creating a price and mapping it is a window where transactions route somewhere you did not choose.
• Test end to end after every change. Run a test transaction, confirm the QuickBooks entry, and check the mapped product resolves to the income account you wanted. The mapping points at a QuickBooks product, and it is the product that carries the income account, so a correct mapping to a misconfigured product still lands in the wrong place on the P&L.
• Watch the error queue as a signal, not a chore. Unmapped transactions appearing there is often the first evidence that a price or product changed upstream.

For the conceptual background on what Multiple Product Mapping is and when to move off a single catch-all product, see what Multiple Product Mapping does. For how the fee side posts separately from the revenue side, see reconciling Stripe fees in QuickBooks, and for the object underneath all of this, the Stripe balance transaction.

FAQ

Why did my Stripe charge map to the wrong QuickBooks product?

Almost always because a broader rule sits above the specific rule you wrote. Acodei evaluates mapping rules from top to bottom and stops at the first match, so a general rule higher in the list intercepts transactions before a more specific rule below it is ever reached. Check the transaction's log entry to see which rule actually fired.

Does Acodei match descriptions exactly?

No. Description matching is a substring match and it is not case-sensitive, so a rule for "pro" also matches "Professional Services" and "Reprocessed Order." That looseness is why rule order matters so much for description-based rules.

Why doesn't my rule fire when I can see the right description in Stripe?

Because Acodei may be reading a different field. For a charge not linked to an invoice it reads the charge or payment description, then the PaymentIntent. For an invoice-linked charge it reads the invoice line item description. For a Checkout session it reads the product description, then the Checkout session line item description. Subscription renewals are invoice-linked, so the invoice line item text is what gets matched, not the charge description.

Can one Stripe transaction map to several QuickBooks products?

No. Acodei does not support matching multiple lines from the same transaction, so a single charge resolves to a single mapped product. It also does not support rules that require two metadata keys at once. A composite metadata value written by your application is the practical workaround for the second limit.

What happens if no mapping rule matches?

Either the transaction falls back to a single catch-all default product, or it raises a sync error, depending on your account settings and environment. Some configurations deliberately disallow the silent fallback so nothing posts uncategorized.

Why did my refund land on a different product than the sale?

In legacy Multiple Product Mapping, refunds on single-line invoices flow back to the original product, while refunds on multi-line invoices go to the Default Refund Product. There is an admin setting to send all refunds to the Default Refund Product, which is generally the cleaner choice because netting refunds against the original product makes gross revenue in QuickBooks read lower than your actual gross revenue.

Will fixing a rule correct transactions that already synced?

No. Rule changes apply to future transactions only and are not versioned. Transactions sitting in the Sync Errors queue can be retried and will run against your corrected rules, but records that already synced successfully need to be handled separately.

Getting the mapping right the first time

Every failure above comes from the same root: a rule list is an ordered sequence, and the engine stops at the first match. Sort by specificity, prefer stable identifiers over text and amounts, add the mapping when you add the price, and read the log entry before you theorize.

Acodei syncs Stripe activity into QuickBooks Online with the product, fee, and tax routing configurable per rule, so revenue lands in the accounts you chose rather than a single bucket you sort out later. Start a free trial or see how the Stripe to QuickBooks integration works.