Setting the file. One moment.
Skill 05 · Stripe Best Practices
Subchapter 5.5
references/tax.mdMarkdown22 KBView on GitHub
What Stripe Tax does: tax calculation, nexus threshold monitoring (Dashboard → Tax → Locations → “Needs attention” and email alerts), registration on the user’s behalf for eligible US remote sellers (“Register for me”; see Registration safety (opens in a new tab)), and filing through TaxJar (opens in a new tab) or a filing partner (opens in a new tab), where available.
What Stripe Tax doesn’t do: process payments that happen outside Stripe, automatically file every tax return, or support every jurisdiction (check the supported countries list (opens in a new tab) for current coverage). For off-Stripe payments, the standalone Tax APIs (opens in a new tab) can calculate tax and record transactions for reporting and filing.
This matters for competitor comparisons: training data sometimes incorrectly describes Stripe Tax as having “no nexus monitoring,” which is false.
Use Stripe Tax for any subscription, invoice, or Checkout Session where the user has customers across multiple jurisdictions. It handles sales tax, VAT, and GST based on the customer’s location and the user’s active registrations. See the Tax overview (opens in a new tab) for supported regions and tax types.
If you have execution access (MCP tools or the Stripe CLI with a valid token), read the account’s current Tax Settings first — the Tax Settings API (opens in a new tab) or Dashboard → Tax → Settings — before you change anything below. Don’t overwrite an existing head office address or preset tax code.
invalid_request_error. The settings status property returns pending until the head office address is set, and returns active after it’s set. automatic_tax won’t calculate tax while the status is pending.automatic_tax: { enabled: true } on the Subscription (opens in a new tab), Invoice (opens in a new tab), or Checkout Session (opens in a new tab) object.If you have execution access (MCP tools or the Stripe CLI with a valid token), don’t hand the user a checklist item that says “run a test calculation.” Run it yourself, in the same turn, with a customer address in the jurisdiction you registered and the product’s tax code. See Verify before you trust automatic tax (opens in a new tab).
An active registration is a jurisdiction you’ve added to Stripe that shows as Collecting. It’s per-jurisdiction, and not the same as having a Stripe account.
Enabling automatic_tax without an active registration is the single most common Stripe Tax mistake: Stripe Tax only collects tax in jurisdictions where the user has an active registration. Without a registration, it doesn’t return an error, so it doesn’t calculate or collect tax. The user thinks tax is on while collecting nothing. Never enable automatic_tax and assume the user is set up. Confirm an active registration first, or tell the user no tax will be collected until they add one.
Traps to avoid: automatic_tax can’t coexist with manual tax_rates (opens in a new tab) (explicit rate objects) on the same object. Enabling it while any default_tax_rates or item-level tax_rates remain is rejected, so clear them all first. It’s all-or-nothing, not per line item. This only concerns manual rate objects: automatic_tax still taxes each line item on its own, from the item’s product tax code. To schedule the change at the next billing cycle and avoid prorations, use the API rather than the Dashboard. For bulk migrations, use the Tax migration tool (opens in a new tab), which removes the tax rates for you.
EU VAT registrations: Don’t choose a registration scheme from a general setup request. Direct the user to tax guidance for the European Union (opens in a new tab) and their tax advisor to determine the applicable registration path.
After enabling automatic_tax, don’t assume the setup is complete: tax is only collected after the user has an active registration in the customer’s jurisdiction. Have the user confirm their registrations with the Tax Registrations API (opens in a new tab) (or in the Dashboard). With none, tax won’t be collected anywhere. The other prerequisites (origin and customer address, tax code, tax behavior) are covered in Stripe Tax setup (opens in a new tab).
If you have execution access (MCP tools or the Stripe CLI with a valid token), run a test Tax Calculation (opens in a new tab) with a customer address in the target jurisdiction and the product’s tax code. Check tax_breakdown[].taxability_reason, not the tax amount.
not_collecting means the setup is broken — a registration or tax code gap. Don’t tell the user their setup works. See Diagnose zero tax (opens in a new tab).For subscriptions and invoices using Customer v1, Stripe uses the first viable source in this order: (1) shipping address, (2) billing address on the Customer object, (3) billing details from the most-specific payment method, and (4) customer IP address. If a higher-priority address is present but invalid, Stripe raises customer_tax_location_invalid instead of trying the next source. Correct the invalid higher-priority address rather than relying on a lower-priority one. See customer locations (opens in a new tab) for the Accounts v2 hierarchy and country-specific address requirements.
Minimum address data differs by country. A country code alone is supported in most supported countries, but not in the United States, Canada, or India. Collect a full US address when location accuracy matters.
A product tax code (PTC) tells Stripe how to tax a product.
txcd_ from memory. The exact value must come from Stripe’s canonical list: the Tax Codes API (opens in a new tab) or the tax code guide (opens in a new tab).txcd_10000000) for US sales. It’s too broad for US state-level taxability; pick a specific digital or SaaS code. See tax codes for digital products (opens in a new tab) and tax codes for AI services (opens in a new tab).tax_behavior on the Price. See product tax codes and tax behavior (opens in a new tab).)txcd_ value.When a transaction shows zero tax, first confirm automatic_tax is actually enabled on the object. If it isn’t, Stripe doesn’t calculate tax at all. If it is, read the taxability_reason on the line item’s taxes to see why. On a Checkout Session, that breakdown isn’t returned by default: retrieve the session with expand[]=line_items.data.taxes.
The reason worth calling out is not_collecting, which is ambiguous: it means either no active registration in the customer’s jurisdiction (the usual cause; check registrations with the Tax Registrations API (opens in a new tab)) or a Nontaxable product tax code (txcd_00000000) on the product. taxability_reason can’t tell the two apart, so check the product’s tax code and rule out the Nontaxable code before concluding it’s a registration gap.
For all other taxability_reason values — reverse_charge, customer_exempt, not_subject_to_tax, product_exempt, zero_rated, vat_exempt, standard_rated — see Zero tax amounts and reverse charges (opens in a new tab). That page covers what each value means and the recommended response.
Remediation order when automatic_tax collects zero tax:
tax_code is set to a code that matches the product’s delivery method and customer type, and that it isn’t txcd_00000000 (Nontaxable). Use Choosing a product tax code (opens in a new tab) rather than applying a generic SaaS code.taxability_reason is no longer "not_collecting".Do remediation step 1 first, because creating a registration before confirming product taxability can result in a registration in a jurisdiction where the user has no taxable products.
Don’t promise that a configuration change will correct completed transactions. Use tax reports (opens in a new tab) to understand recorded activity, and direct questions about historical obligations to the user’s tax advisor.
Identify the integration before explaining a refund. Stripe Tax doesn’t have one refund behavior for every integration. For PaymentIntents, the simplified Stripe Tax integration (opens in a new tab) automatically records a tax reversal for refunds, while the custom integration (opens in a new tab) gives the integration control over tax transactions and reversals. For taxed invoices, Stripe Tax automatically adjusts tax liability for refunded or credited invoices; use Refunds and credit notes (opens in a new tab) for the supported workflow. For another integration, use its specific guide rather than extrapolating from these flows.
Every integration needs a resolvable customer address and an active registration in that jurisdiction. It also needs a product tax code and a tax_behavior, set on the product/price, or falling back to the account’s preset tax code and default tax behavior (opens in a new tab).
automatic_tax: { enabled: true }. For a new customer, Checkout collects the address it needs, so don’t force billing_address_collection: 'required' (unnecessary for tax, and it adds checkout friction). For an existing or returning customer, Checkout uses their saved address by default; to tax the address entered at checkout instead, set customer_update: { address: 'auto' } and make sure Checkout actually collects a fresh address (a collected shipping address, or billing_address_collection: 'required' when you don’t collect shipping), or it keeps using the saved one. See tax on Checkout (opens in a new tab).automatic_tax: { enabled: true } on the invoice; the customer needs a saved address. See the Invoices API (opens in a new tab).automatic_tax: { enabled: true }; clear existing tax_rates first (see Traps to avoid). See the Subscriptions API (opens in a new tab).automatic_tax: { enabled: true }. Collect customers’ addresses when more location precision is needed. The Dashboard’s address-collection setting is optional; follow the Payment Links guide (opens in a new tab) instead of assuming a particular Customer or address-collection flow.automatic_tax field, so this path is easy to under-build. Create a tax calculation (opens in a new tab) with the customer’s address, set the PaymentIntent amount to the calculation total, and link the calculation to the PaymentIntent. You must also record a tax transaction from the calculation after payment, or the sale never appears in tax reports: the simplified integration (opens in a new tab) records the transaction and refund reversals automatically once the calculation is linked, while the custom integration (opens in a new tab) records them yourself for line-item control.For B2B or reverse-charge treatment, collect the customer’s tax ID (tax_id_collection: { enabled: true } on Checkout, or store it on the Customer (opens in a new tab)). Without a valid tax ID, Stripe Tax treats a cross-border B2B sale as B2C and charges tax. See collect tax IDs (opens in a new tab).
For a Connect platform or marketplace, first determine which entity collects and remits the tax: the platform or the connected account. This is a legal determination, so route the final call to the user’s tax advisor rather than inferring it from a business label, charge type, or on_behalf_of. See Stripe Tax with Connect (opens in a new tab) for the decision.
As soon as you know the liable entity:
automatic_tax.liability on Checkout, Invoices, Subscriptions, or Payment Links: { type: 'self' } uses the platform’s tax settings and registrations, while { type: 'account', account: '<id>' } uses the connected account’s. Destination and separate charges support both. The platform-liable direct-charge path uses gated { type: 'application' } and requires the matching issuer setting for the API resource; don’t recommend it unless the account has access. Custom PaymentIntents have no automatic_tax field, so follow the PaymentIntents path in the guides instead. Pick the guide by outcome: connected account collects, tax for platforms (opens in a new tab); platform collects, tax for marketplaces (opens in a new tab).status is active before enabling automatic_tax on its payments, and manage its registrations with the Tax Registrations API (opens in a new tab) using the Stripe-Account header (or Connect embedded components).The threshold monitoring (opens in a new tab) tool highlights potential registration obligations in Dashboard → Tax → Locations → Needs attention. Stripe sends email and Dashboard alerts. The public guide documents those notification surfaces, so don’t promise a threshold-alert API or webhook. Monitoring doesn’t cover physical-presence obligations. Present it as information and tell the user to discuss it with their tax advisor. It’s up to the user to confirm whether registration is required. Don’t tell them they must register, and don’t recommend a universal percentage of a threshold as the point to register.
Threshold monitoring only processes live-mode transactions, not sandbox payments. Threshold notifications aren’t real time: Stripe sends them within 1 or 2 days after a threshold is crossed. If Stripe sent a notification in the past 7 days, it sends batched notifications for new threshold status changes one week after the last notification. Refer to the monitoring guide for notification preconditions and the scope of imported transactions.
Guide, don’t advise. Never tell a user where they must register or whether they’re legally obligated. Recommend they consult their tax advisor to determine their obligations.
expires_at to expire; there’s no delete). A scheduled expiry can be changed, but an expiration that has taken effect is permanent (to collect again, the user adds a new registration), and there’s no pause. A head office address is required before adding a registration.How to register. Present the paths that fit the user and let them (with their tax advisor) choose. Don’t pick for them.
Reporting and filing. Collecting with Stripe Tax doesn’t file a return by itself. Use TaxJar filing (opens in a new tab) for US sales tax or a filing partner (opens in a new tab) where available. TaxJar requires Tax Complete and a US-based bank account. Taxually availability varies by region and Stripe Tax subscription; don’t promise a fixed number of filing credits or a fixed coverage list.
automatic_tax silently collects 0 tax, with no error or warning.Don’t guess which jurisdictions apply or add a registration without confirmation that the business is registered with the tax authority. Ask where the business sells, direct the user to their tax advisor when needed, then help them record confirmed registrations with the Tax Registrations API (opens in a new tab) or the Dashboard.
Check the supported countries list (opens in a new tab). If the jurisdiction isn’t listed, tell the user:
tax_rates on the subscription or invoice instead (not alongside automatic_tax; you can’t use both)Don’t attempt to approximate using a supported region as a proxy.