Private preview
Set up manual rules as a fallback for automatic tax Private preview
Define tax rules for jurisdictions where Stripe Tax doesn't calculate tax automatically.
Sign up
Request access to manual rules fallback
Manual rules fallback lets you define tax rules for jurisdictions where Stripe Tax doesn't calculate automatically. When a customer is in an unsupported region, Stripe applies your manual rules instead of returning zero tax.
When Stripe Tax can’t calculate tax because a customer’s jurisdiction is unsupported, it attempts to use a manual rule you’ve defined. If a matching rule exists, Stripe applies the tax rate you configured instead of returning zero tax.
How it works
When Stripe Tax processes a transaction for a customer whose location is in an unsupported jurisdiction, it checks whether you’ve defined manual rules that match the customer’s location and product type. If a matching rule exists, Stripe applies it and includes fallback metadata in the response so you know which rules were used.
The fallback applies when all of the following are true:
- Automatic tax is enabled.
- The customer’s location is in a jurisdiction Stripe Tax doesn’t support.
- You’ve created a manual rule that matches the customer’s location and product tax code.
If no matching rule exists, the transaction proceeds with zero tax for that jurisdiction, which is the same behavior as when you’ve enabled no fallback.
Limitations
Some limitations apply depending on how you integrate with Stripe Tax.
Subscriptions
Manual rules fallback is only supported on subscriptions running with billing_mode.type = flexible. See Billing mode for more information.
Checkout
When using Checkout with minimal customer address collection, customers can only select the country for many countries that have special territories (for example, Canary Islands). This means Stripe Tax can’t match manual rules created for these regions to the customer’s address, because the customer can’t input their full address. For a workaround:
- For Payment Links: Collect customer addresses
- For Checkout Sessions, collect the billing or shipping address:
- Collect a billing address
- Collect a shipping address
Before you begin
After you get confirmation that your account was added to the private preview:
- Set up Stripe Tax and enable automatic tax on your subscriptions or invoices.
- This feature is for customers in jurisdictions where Stripe Tax isn’t available. Identify the jurisdictions where your customers are located that Stripe Tax doesn’t currently support.
- See the list of supported jurisdictions
- See the list of unsupported jurisdictions
- Determine the tax rates and tax rate types (for example, VAT, GST, or Sales Tax) that apply to your products in those unsupported jurisdictions.
Create manual rules
Use the Manual Rules API to define tax rules for unsupported jurisdictions. Each rule maps a combination of location and product tax code to a specific tax rate.
You can create rules by country or by both the country and state for more specific coverage:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
When you create a rule, Stripe validates that the location and product tax code combination doesn’t conflict with an existing rule.
Supported locations
Manual rules support country-level and location-specific rules. This includes overseas territories that have distinct tax regimes from their parent country.
Use ISO-3166 country codes for all locations, both when you create the manual rule and when you set the customer’s address:
| Location | Territory |
|---|---|
country: GP | Guadeloupe |
country: MQ | Martinique |
country: GF | French Guiana |
country: RE | Reunion |
country: YT | Mayotte |
country: ES, state: CN | Canary Islands |
country: ES, state: CE | Ceuta |
country: ES, state: ML | Melilla |
country: PT, state: 20 | Azores |
country: PT, state: 30 | Madeira |
You can also define rules for any country code that Stripe Tax doesn’t cover, without specifying a state.
Enable manual rules fallback
Manual rules fallback is in private preview. Sign up to request access.
Test your integration
To verify that manual rules fallback works correctly:
- Create a manual rule for a test jurisdiction and product tax code.
- Create a customer with an address in that jurisdiction.
- Create a subscription or invoice with automatic tax enabled.
- Confirm the response includes tax _ calculation _ fallback with the expected reason and outcome.
- Confirm the total _ taxes array includes entries with the manual _ rule attribute pointing to your rule.
Understand fallback responses
When Stripe applies manual rules as a fallback, the API response includes additional fields that indicate a fallback occurred and which rules we used.
The tax_calculation_fallback attribute
The automatic_tax object on the invoice includes a tax_calculation_fallback attribute when Stripe used a manual rule:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
| Field | Description |
|---|---|
reason | Why Stripe Tax couldn’t calculate tax automatically, for example, unsupported_jurisdiction. |
outcome | What Stripe did instead, for example, manual_rules when we applied a matching rule. |
The manual_rule attribute on tax lines
Each tax line in the taxes and total_taxes arrays includes a manual_rule attribute that identifies which rule produced it:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Use this attribute to:
- Audit which rules are being applied across your invoices.
- Identify rules that need updating when tax rates change.
- Reconcile tax collected through fallback rules separately from standard automatic tax.