Glossary

Stripe Tax Rate

A Stripe tax rate is a stored object, identified by a `txr_` ID, that holds a fixed percentage, an inclusive or exclusive flag, and the labels shown to your customer, and that gets attached to invoice lines and subscriptions to apply tax.

Also called: txr_, tax rate ID, Stripe tax rate object, txr id, Stripe VAT rate

Start a free trial View Pricing

Definition

A tax rate in Stripe is not a number you type onto an invoice. It is an object with its own ID, in the form `txr_1MzS4RLkdIwHu7ixwvpZ9c2i`, and invoice lines reference that object rather than storing a percentage.

That design choice explains most of the confusing behavior people run into. Because the rate is a stored object, the same 20 percent can exist several times over as several different objects. Because invoices point at the object, a rate that was retired years ago still appears on the invoices that used it. And because the object records whether the rate was inclusive or exclusive, "20 percent VAT" is not one rate but potentially two.

The practical consequence for anyone mapping tax into an accounting system is that the identifier, not the percentage, is the thing that carries meaning. Two rates at 5 percent can be two different taxes owed to two different authorities.

Key points

+Identified by a `txr_` ID; invoice lines reference the object rather than storing a percentage.
+`percentage` and `inclusive` are required when the rate is created and cannot be changed afterwards.
+Changing a rate means creating a new object, so accounts accumulate rates over time.
+Archiving sets `active` to false, which blocks new use but leaves existing invoices and subscriptions working.
+`display_name` is what the customer sees; `description` is internal and never shown to them.
+`percentage` and `effective_percentage` can differ, and the effective one is what was actually charged.
+Rates created by Stripe Tax automatically may not appear in a standard tax rate list at all.

What the object actually holds

A handful of fields do all the work, and several of them are routinely misread.

**`percentage`** is the rate out of 100. For calculations made with automatic tax enabled, Stripe notes that this percentage "includes the statutory tax rate of non-taxable jurisdictions", which is the source of a specific surprise covered below.

**`inclusive`** is a boolean that specifies whether the rate is inclusive or exclusive. Inclusive means the listed price already contains the tax. Exclusive means tax is added on top.

**`display_name`** is the customer-facing label, shown "on their receipt email, PDF, and the hosted invoice page". **`description`** is the opposite: an arbitrary string "attached to the tax rate for your internal use only. It will not be visible to your customers." If your invoices are showing an unhelpful tax label, `display_name` is the field to look at.

**`jurisdiction`** is a label for reporting that also appears on the customer invoice, and **`jurisdiction_level`** records whether the tax is imposed at city, county, district, state, country, or multiple levels. That second field carries a useful signal: Stripe documents it as null for manually defined tax rates, so it tells you whether a rate came from Stripe Tax or from a human.

**`tax_type`** is the high-level classification, drawn from a fixed list that includes `vat`, `gst`, `hst`, `pst`, `qst`, `rst`, `igst`, `jct`, `sales_tax`, `service_tax`, and a long tail of narrower ones such as `retail_delivery_fee` and `amusement_tax`.

**`rate_type`** is either `percentage` or `flat_amount`, and is only present on rates that Stripe Tax created. A flat amount is a fixed charge regardless of the taxable amount, such as a retail delivery fee, and its value lives in `flat_amount` rather than in `percentage`.

Why the numbers cannot be edited

This is the single most useful thing to know about the object, and it is visible directly in the API surface.

Creating a tax rate requires three things: `display_name`, `inclusive`, and `percentage`. Updating one accepts a different set: `active`, `country`, `description`, `display_name`, `jurisdiction`, `metadata`, `state`, and `tax_type`.

Compare the two lists and the rule falls out. You can relabel a rate, move its jurisdiction metadata, reclassify its tax type, and archive it. You cannot change what it charges, and you cannot flip it between inclusive and exclusive. Those two values are fixed at creation.

So "we changed our VAT rate" never means an existing object was edited. It means a new object was created with a new `txr_` ID, and everything issued before that point still points at the old one. Over a few years of rate changes, promotional exemptions, and jurisdictions coming and going, an account accumulates a substantial list of rates, most of them no longer in use but all of them still referenced by historical invoices.

Archiving does not undo that. Setting `active` to false means the rate "cannot be used with new applications or Checkout Sessions, but will still work for subscriptions and invoices that already have it set". It is a rule about future use, not a deletion.

Inclusive is a property of the rate, not a setting

People look for an inclusive-or-exclusive toggle at the invoice level and cannot find one, because it does not live there. It lives on the rate, and it is mandatory at creation.

The consequence is that inclusive 20 percent VAT and exclusive 20 percent VAT are two separate objects with two separate `txr_` IDs. They will display similarly and calculate very differently.

That difference is not cosmetic once the numbers reach your books. On a 100 unit sale at 20 percent, an exclusive rate produces 100 of revenue plus 20 of tax, for a total of 120. An inclusive rate on a 120 price produces 100 of revenue and 20 of tax inside the same 120. Same tax, same total, but exclusive tax added to a price that was meant to be inclusive inflates both the total and the revenue.

If you are mapping rates into an accounting system, this is the field to check first when a total does not tie out.

percentage versus effective_percentage

These two fields can disagree, and when they do, the second one is the truth about what was charged.

`percentage` is the statutory rate. Stripe is explicit that under automatic tax it "includes the statutory tax rate of non-taxable jurisdictions", meaning the headline number stays populated even where the transaction was not actually taxable.

`effective_percentage` is described as the "actual/effective tax rate percentage out of 100", reflecting "the rate actually used to calculate tax based on the product’s taxability and whether the user is registered to collect taxes in the corresponding jurisdiction".

Two different things can therefore drive an effective rate of zero on a rate that reads as 20 percent: the product was not taxable in that jurisdiction, or you are not registered to collect there. Both are correct behavior, and neither is obvious from the headline percentage.

When tax collected looks lower than the rates on the invoices suggest, comparing these two fields is usually faster than recalculating anything.

Why mapping keys on the ID

Any system that moves Stripe tax into an accounting ledger has to decide what identifies a rate. Using the percentage seems natural and does not survive contact with real data.

A Canadian seller can easily have 5 percent GST federally and a 5 percent provincial rate that is a different tax, owed to a different authority, filed on a different return. Both read as 5. Nothing about the number distinguishes them, and merging them produces a return that is wrong in both directions.

The `txr_` ID is the only field guaranteed to identify a specific rate, which is why mapping is built on it. The cost of that correctness is that a new rate is a new ID, and a new ID is something that has to be mapped before transactions using it can be classified.

There is one more wrinkle worth knowing before you go looking for an ID. Automatically calculated rates are not always associated with a manually created tax rate object, and archived rates do not appear in standard API responses unless they are queried explicitly. A `txr_` that is plainly visible on an invoice can therefore be absent from a list of your tax rates, which is a confusing but documented situation rather than a fault.

How txr_ IDs become QuickBooks tax codes

Acodei offers two routes for Stripe Tax, and only one of them involves tax rate IDs.

Under **QuickBooks Tax Rate (Advanced)** mapping, Acodei pulls the Stripe tax rate IDs available to it using Stripe’s List tax rates endpoint, and you map each `txr_` to a corresponding QuickBooks tax code such as "GST 5%". The setting lives in Account Mapping under the Stripe Tax section, alongside the Default Product Tax Rate and Default Fee Tax Rate, which are typically set to Exempt so that only mapped rates apply tax.

When more than one Stripe rate lands on a single line item, for example GST plus PST, Acodei detects that and lets you map the combination to a single QuickBooks group tax code, so the total tax matches Stripe exactly rather than approximately.

How the mapping is applied depends on your sync mode. Real-time sync maps each invoice’s distinct tax lines one to one into QuickBooks, which is where advanced mapping works best. Daily summaries split lines by product and rate instead, so a day with two products and two rates produces separate lines for each combination.

Two limitations are worth knowing before choosing this route. In US QuickBooks, the Sales Tax Center does not expose custom rates to third parties, so advanced mapping is often not fully usable there, and US accounts generally use the Tax Product approach instead, aggregating all tax to a single product mapped to a liability account. And if an archived Stripe rate turns up on older invoices, its `txr_` may need to be added manually in Acodei so those invoices can be mapped.

The wider setup, including which approach to pick and how the tax lines land, is covered in the [Stripe Tax to QuickBooks guide](/blog/stripe-tax-quickbooks-online).

Want to see this on your own Stripe data?

Start a free trial

Frequently asked questions

What is a Stripe tax rate?

A stored object with its own ID in the form `txr_...`, holding a percentage, an inclusive or exclusive flag, a customer-facing display name, and jurisdiction details. Invoice lines and subscriptions reference the object rather than storing a raw percentage.

What does txr_ mean in Stripe?

`txr_` is the prefix Stripe uses for tax rate object IDs, in the same way `in_` prefixes invoices and `cus_` prefixes customers. Seeing a `txr_` value on an invoice line tells you which specific stored rate was applied.

Can I edit a Stripe tax rate percentage?

No. `percentage` and `inclusive` are required when a rate is created and are not among the fields the update endpoint accepts. You can change the display name, description, jurisdiction, country, state, tax type, metadata, and active status. Changing what a rate charges means creating a new tax rate object.

What happens when I archive a Stripe tax rate?

Archiving sets `active` to false. Stripe documents that the rate then cannot be used with new applications or Checkout Sessions, but will still work for subscriptions and invoices that already have it set. Historical invoices are unaffected and keep referencing it.

Why is percentage different from effective_percentage?

`percentage` is the statutory rate, and under automatic tax it includes the statutory rate of non-taxable jurisdictions. `effective_percentage` reflects the rate actually used, accounting for whether the product is taxable there and whether you are registered to collect tax in that jurisdiction. An effective rate of zero on a 20 percent rate usually means one of those two conditions applied.

Why can I not find a txr_ ID in my tax rate list?

Two documented reasons. Rates calculated automatically are not always associated with a manually created tax rate object, and archived rates do not appear in standard API responses unless they are explicitly queried. The ID can still be read from the invoice itself.

Why does mapping use the tax rate ID instead of the percentage?

Because the percentage does not identify a tax. Two rates can both be 5 percent while being different taxes owed to different authorities and filed on different returns. The `txr_` ID is the only field that reliably identifies one specific rate.

Can two Stripe tax rates map to one QuickBooks tax code?

Yes. When two or more Stripe rates apply to a single line item, such as GST plus PST, Acodei detects the combination and lets you map it to a QuickBooks group tax code, so the total tax in QuickBooks matches Stripe exactly.

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.”

RyanOwner at Indie Music Academy