Stripe Billing Credits (Credit Grants) and QuickBooks

Your customer has a balance of 500 dollars in Stripe. Their next invoice is for 400 dollars. Whether that invoice reads 400 dollars with nothing due, or reads zero dollars, or reads something in between, depends entirely on which of Stripe's three unrelated credit mechanisms put that 500 dollars there.

They are not interchangeable, and the difference is not cosmetic. One of them reduces the size of the sale before tax is calculated. One of them leaves the sale at full value and changes only how it was settled. The third is an adjustment issued after the fact against an invoice that already exists.

This post is about the first one, Stripe billing credits, which Stripe implements as credit grants. It is the newest of the three, the least written about, and the only one that changes the taxable amount. It also behaves in ways that catch people who assume it works like a customer balance, because it does not.

Start a free trial of Acodei if you want Stripe invoices reaching QuickBooks without retyping them.

What a credit grant actually is

A credit grant is a pot of prepaid or promotional billing credits attached to a customer, which gets drawn down as usage is billed. Stripe's own framing is that a Credit Grant "tracks a set of prepaid or promotional billing credits allocated to a customer."

Stripe describes two intended uses, and they are worth separating in your head because they have different accounting consequences.

The first is prepayment. You sell the customer a block of credits up front, and they spend it against usage over time. Stripe's wording: "Grant billing credits to your customers that they can use to pay for usage-based products or services, such as memberships, pay-as-you-go plans, subscriptions, or specific products or services."

The second is promotional. You give credits away. Stripe: "Grant billing credits for free to your customers as a promotional offering. Businesses often offer a limited amount of promotional credits, and typically with an expiration date."

The object itself records which of the two it was. The category field takes paid, which Stripe defines as "The credit grant was purchased by the customer for some amount," or promotional, "The credit grant was given to the customer for free." Stripe notes the field "is for tracking purposes and isn't displayed to the customer," which makes it a reporting field rather than a customer-facing one. For anyone doing revenue work, that distinction between money you collected and money you gave away is the single most useful field on the object, so it is worth setting deliberately rather than by default.

There is a boundary here that Stripe draws explicitly, and it matters for how you treat the balance in your books. Billing credits are not stored value. Stripe's prohibited-use list states you cannot issue them "as gift cards or gift certificates," cannot "offer billing credits as stored value," cannot let customers "use billing credits for payments to third parties," and cannot link them to digital wallets. The credits are spendable only on what you sell. That is a meaningful constraint on what kind of liability you are carrying when you sell a block of them.

The one fact that makes credit grants different

Here is the sentence that separates a credit grant from every other credit on a Stripe invoice, quoted from Stripe's billing credits documentation:

Credit grants apply to invoices after discounts, but before taxes and the invoice_credit_balance.

Read that ordering carefully, because three consequences fall out of it.

Tax is calculated on the reduced amount. The credit lands before taxes, so the taxable base is what remains after the credit is applied. A 1,000 dollar usage bill with a 400 dollar credit grant is a 600 dollar taxable sale, not a 1,000 dollar taxable sale that happens to be partly paid. That is a materially different invoice, and it is the reason this mechanism cannot be treated as a payment.

It sits after discounts. A percentage coupon computes against the pre-credit amount, and the credit then eats into what is left. Discounts and credits are not commutative, and the order Stripe chose is the one that costs you less on the coupon.

It sits before the customer balance. If a customer has both a credit grant and a customer balance, Stripe drains the grant first and applies the balance to whatever remains. Two mechanisms, applied in a fixed order, on the same invoice.

On the invoice object, the credit surfaces in total_pretax_credit_amounts, which Stripe documents as follows:

Contains pretax credit amounts (ex: discount, credit grants, etc) that apply to this invoice. This is a combined list of total_pretax_credit_amounts across all invoice line items.

Two things are worth noticing in that one sentence. The field is an aggregate rolled up from the line items, not an invoice-level adjustment, which tells you the credit is applied per line rather than to the invoice as a whole. And it is a shared field: discounts and credit grants both land in it, so its presence tells you a pretax reduction happened, not which kind.

What Stripe's reference does not spell out is exactly how that reduction renders on the invoice PDF a customer receives. That is worth checking against a real invoice in your own account rather than assuming, and it is the first thing to look at when you are deciding what your books should say.

Credit grant versus customer balance

This is the comparison that sends people wrong, so it is worth being precise.

A customer balance is money the customer is owed, or owes you. It arrives from overpayments, from manual adjustments in the Stripe dashboard, and indirectly from proration on subscription changes. It does not change the invoice total. It changes what is collected. Stripe's amount_due description makes the mechanism plain: "if there is account credit that can be applied to the invoice, the amount_due may be 0. If there is a positive starting_balance for the invoice (the customer owes money), the amount_due will also take that into account."

Note which field moves. amount_due moves. total, which Stripe defines simply as "Total after discounts and taxes," does not. The sale stays the size it was. The balance settles part of it.

The customer balance also has its own pair of fields tracking the movement, and they are dedicated to it rather than shared. starting_balance is the "Starting customer balance before the invoice is finalized," and ending_balance is the "Ending customer balance after the invoice is finalized." Neither has anything to do with credit grants.

A credit grant is an entitlement the customer has already bought or been given. It reduces the invoice before tax. The sale is genuinely smaller.

Put in the terms a bookkeeper actually thinks in:

	Credit grant	Customer balance
What it represents	An entitlement already bought or granted	Money owed to or by the customer
Where it lands	Before taxes, after discounts	After the total is computed
Effect on invoice total	Reduces it	None
Effect on amount_due	Reduces it, via the total	Reduces it directly
Effect on the taxable amount	Reduces it	None
Invoice fields	total_pretax_credit_amounts	starting_balance, ending_balance
Applies to	Metered subscription lines only	Any invoice

If you take one thing from this post, take that fourth row. A credit grant changes the size of the sale. A customer balance changes how the sale was settled. Those are different journal entries, and they are different revenue numbers.

We cover the second column in depth in Stripe customer balance and applied credits in QuickBooks. The third mechanism, the credit note, which is an adjustment issued against an invoice that already exists, is covered in Stripe credit notes and proration credits in QuickBooks and defined in the Stripe credit note glossary entry.

What a credit grant can be applied to, which is narrower than you think

This is where most people's mental model breaks. Credit grants are not a general-purpose credit. Stripe restricts them to usage-based billing, and the restrictions are specific.

For a grant to apply to an invoice, Stripe requires all of the following:

• The invoice's period_end falls on or after the grant's effective_at.
• The invoice's period_end falls before the grant's expires_at, if one is set.
• The grant has an available balance when the invoice finalizes.
• The grant's currency matches the invoice currency.

And then the constraint that rules out most invoices entirely. Stripe: "You can only apply credit grants to subscription items that use metered prices and report usage through Meters."

The exclusion list is worth reading in full, because each item is a case someone has assumed would work:

• One-off invoices that were not created by a subscription.
• One-time invoice items added to a subscription's previewed invoice, such as an initial setup fee.
• Line items on subscription invoices that use licensed prices.
• Line items on subscription invoices that use metered prices but report usage through legacy Usage Records.

That last one is the quiet one. A business that metered usage before Stripe's Meters existed, and never migrated, has metered prices that still cannot take a credit grant. The prices look right. The reporting mechanism is wrong.

The practical consequence for the books: on a mixed invoice carrying a platform fee on a licensed price and usage on a metered price, the credit reduces only the usage lines. The platform fee is billed and taxed in full. If your revenue reporting splits those two streams, the credit lands entirely on one side of the split.

The states a grant moves through, and the two balances

A credit grant is not simply present or spent. Stripe defines five states, and the difference between two of them causes real confusion at month end.

State	What it means
Pending	The available balance is not yet usable
Granted	Effective and eligible for use, per effective_at
Depleted	The balance is fully used
Expired	Past expires_at, or expired manually
Voided	Cancelled before being applied to any invoice

Two of these have constraints worth knowing. Credits do not expire by default: Stripe states that credits "won't expire unless you set this field," referring to expires_at. And voiding is narrow: "You can only void credit grants that you haven't applied to an invoice, either partially or completely." Once a grant has touched an invoice, void is off the table and expiry is the only remaining lever.

Then there are two separate balances, and they disagree on purpose. Stripe's Credit Balance Summary exposes a ledger balance, "the billing credit balance after recording all relevant account ledger transactions," backed by what Stripe calls "an immutable, append-only ledger." And an available balance, "the billing credit balance available for the customer to use," which "is equal to the ledger balance less any expired credits or unrecorded transactions."

The gap between them opens whenever a draft invoice is holding credits it has not yet consumed. Stripe spells out the case: "If credits from a credit grant appear on a draft invoice, the available balance might show zero, but the ledger balance remains positive until the invoice finalizes."

So a customer can appear to have no credits left while still holding a positive ledger balance. If you are reconciling a credit liability at period end, the ledger balance is the number that reflects what you actually owe them. The available balance reflects what they can spend right now. Reading the wrong one at the wrong moment produces a number that is off by exactly the amount sitting on open drafts.

There is a related timing rule that governs everything above. Stripe: "Credits apply to invoices only at the time of finalization. If you apply credits to a preview or draft invoice, those credits might change if a finalized invoice uses them first." A draft is a forecast, not a reservation. Two subscriptions billing on the same day can both show the same credits on their previews, and only one of them gets them.

When several grants collide

If more than one grant can apply, Stripe resolves the contest with a fixed five-step tiebreak:

1. Priority. Higher priority applies first, and Stripe's numbering is inverted: "The highest priority is 0 and the lowest is 100."
2. Expiration date. Earlier expires_at first.
3. Category. Promotional grants apply before paid ones.
4. Effective date. Earlier effective_at first.
5. Created date. Earlier created first.

Step three is the one with an accounting consequence, and it is a sensible default that you should still know about. Free credits burn before purchased ones. The customer keeps the credits they paid for longer, and your deferred revenue from sold credits unwinds more slowly than it would if the order ran the other way.

Across multiple invoices there is no such determinism. Stripe is candid: "the credit applies first to the invoice that finalizes first. Because subscription invoices finalize independently as soon as they're eligible, we can't guarantee the finalization order." A customer with several subscriptions has no promise about which one consumes a shared pool.

One more operational limit. Customers can hold at most 100 unused credit grants at once, and a request that would exceed it fails. A grant counts as unused while it is not voided, not past expires_at, and either pending or carrying a positive ledger balance. Anyone issuing small promotional grants programmatically should know that ceiling exists before they hit it.

Voids, credit notes, and the one that surprises people

Two rules govern what happens when an invoice carrying credits gets unwound, and they point in opposite directions.

Voiding gives the credits back. Stripe: "Voiding an invoice with credits applied reinstates the applied balance to the credit grant." With one catch attached: "If the credit grant is past the expiration date, the reinstated credits expire immediately." So voiding a stale invoice can return credits into a grant that expires them on arrival, and the customer is out the credits with nothing to show for it.

Issuing a credit note does not. Stripe: "Issuing a Credit Note doesn't refund credit grants applied to an invoice. To restore those billing credits, you must create a new credit grant."

That asymmetry is the single most expensive thing on this page to get wrong. The instinct when an invoice needs correcting after payment is to issue a credit note, because that is the correct instrument for almost every other case. Do it on an invoice that consumed 400 dollars of prepaid credits, and the customer gets a credit note for the cash amount while the 400 dollars of credits they had already bought simply vanishes. Restoring them is a separate, manual act: a new credit grant, which you have to remember to create.

If you sell prepaid credit blocks, that is worth writing into your refund procedure rather than leaving to whoever is on support that day.

What reaches QuickBooks

Here is where this post has to be careful, and where it is going to tell you less than you might want.

Acodei's Invoice Sync documentation covers the applied balance mechanism in detail. It has a dedicated section for it, it documents the default behaviour, and it documents an admin setting that changes that behaviour. It does not document credit grants. There is no section on them, no setting for them, and no statement about how they are treated.

That absence is the honest answer, and stretching the applied-balance documentation to cover credit grants would be exactly the wrong move: as the first half of this post established, they are different fields hitting the invoice at different points in the calculation. So here is what is documented, and where the line falls.

What Invoice Sync does with an invoice generally. When a Stripe invoice is finalized, Acodei creates a QuickBooks Invoice that reproduces every line item, and tax lines, as allowed by your mapping settings. When the invoice is paid, whether by a successful charge, a manual payment per your settings, or a credit balance offset, Acodei creates a QuickBooks Payment Receipt or Credit Memo and applies it to the invoice created earlier, which the documentation notes requires QuickBooks' own automatic application to be on. Each invoice line uses the product returned by Multiple Product Mapping if you have it enabled, and the default product otherwise.

What Invoice Sync does with the applied balance, which is the customer balance and not a credit grant. By default, Acodei includes the applied balance, which is starting_balance, as a line item on the QuickBooks invoice, so the invoice reflects the exact amount Stripe charged. An admin setting called "Skip 'Applied Balance' as line item on Invoice" reverses that: with it enabled, Acodei ignores the applied balance and creates the invoice at the full gross amount of subtotal plus tax, so QuickBooks accounts receivable reflects the full value of the sale.

What that setting decides is how a gap gets represented: with a customer balance, the value of the sale and the amount Stripe charged are two different numbers, and the two options pick which of them the QuickBooks invoice shows. A credit grant does not open that gap, because it changes the total itself. Which is another way of saying the setting is not the answer to this question.

What is documented about validation. Acodei compares the final invoice generated in QuickBooks against the Stripe invoice amount to confirm they match exactly. That check applies only when tax is enabled. It is worth stating the condition every time, because the rule gets repeated without it.

What to do about it. Run one usage invoice that consumed a credit grant, and read the resulting QuickBooks invoice line by line against the Stripe invoice. Confirm the total matches, and confirm the revenue and tax amounts are the ones you expect to report. That takes ten minutes and it replaces guessing with knowing, which is the only responsible answer while the behaviour is undocumented.

If you sell prepaid credits at any volume, it is also worth deciding separately how you want the sale of the credit block itself to appear, because that is a distinct commercial event from the usage it later pays for, and it happens at a different time.

A short checklist

1. Establish which mechanism is actually on the invoice. total_pretax_credit_amounts means a pretax reduction, from a discount or a credit grant. starting_balance means a customer balance. They are different rows in your books.
2. Set category on every grant, paid or promotional, so you can separate credits sold from credits given away.
3. At period end, read the ledger balance, not the available balance, when you need to know what you owe customers in credits.
4. Check which of your subscription lines can actually take a credit. Licensed prices and legacy Usage Records cannot.
5. Add the credit-note rule to your refund procedure: a credit note does not restore billing credits, and only a new grant will.
6. Run one credit-consuming invoice end to end and read what landed in QuickBooks against what Stripe shows.

Start a free trial of Acodei to get Stripe invoices and their line items into QuickBooks, or read more about how Acodei syncs Stripe to QuickBooks.

Frequently asked questions

What is the difference between Stripe billing credits and a Stripe customer balance?

A billing credit, implemented as a credit grant, is a prepaid or promotional entitlement that reduces the invoice before tax is calculated, so the sale itself is smaller. A customer balance is money owed to or by the customer, and it reduces what is collected without changing the invoice total. Stripe applies credit grants "after discounts, but before taxes and the invoice_credit_balance," so on an invoice carrying both, the grant is consumed first.

Do Stripe billing credits reduce the amount of tax charged?

Yes. Stripe applies credit grants before taxes, so tax is calculated on the amount remaining after the credit. This is the main practical difference from a customer balance, which is applied after the total, including tax, has already been computed.

Can I apply a Stripe credit grant to any invoice?

No. Credit grants apply only to subscription items that use metered prices and report usage through Meters. Stripe excludes one-off invoices not created by a subscription, one-time invoice items such as setup fees on a previewed invoice, lines using licensed prices, and metered lines that still report through legacy Usage Records.

Does a credit note restore billing credits that were used on an invoice?

No, and this is the rule most likely to cost you money. Stripe states that "Issuing a Credit Note doesn't refund credit grants applied to an invoice. To restore those billing credits, you must create a new credit grant." Voiding the invoice does return them, but a credit note does not.

Why does a customer's credit balance show zero when they still have credits?

Because the available balance and the ledger balance measure different things. Credits sitting on a draft invoice are subtracted from the available balance but remain in the ledger balance until that invoice finalizes. Stripe notes the available balance "might show zero, but the ledger balance remains positive until the invoice finalizes."

Do Stripe billing credits expire?

Only if you set an expiry. Stripe states that credits "won't expire unless you set this field," referring to expires_at. You can also expire remaining credits on demand. Voiding, by contrast, is only possible on a grant that has not yet been applied to an invoice.

Which credit grant gets used first when a customer has several?

Stripe resolves it in five steps: priority first, where 0 is the highest and 100 the lowest, then earliest expiry, then category with promotional before paid, then earliest effective date, then earliest creation date. Promotional credits burning before purchased ones is the step with the clearest accounting consequence.

Does Acodei sync Stripe billing credits to QuickBooks?

Acodei's product documentation does not cover credit grants, so there is no documented behaviour to describe. What is documented is that a finalized Stripe invoice creates a QuickBooks invoice reproducing the line items and tax lines according to your mapping settings, and that a separate admin setting governs the applied balance, which is the customer balance mechanism rather than credit grants. Run one credit-consuming invoice and check the result against the Stripe invoice rather than assuming the two mechanisms are treated the same way.

Sources: Stripe's Billing credits guide, Credit Grant object reference and Invoice object reference, all fetched at the time of writing. Acodei behaviour is grounded in Acodei's Invoice Sync product documentation.