# Set up manual rules as a fallback for automatic tax 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. ```bash curl https://docs.stripe.com/preview/register \ -X POST \ -H "Content-Type: application/json" \ -H "Referer: https://docs.stripe.com/tax/manual-rules-fallback" \ -d '{"email": "EMAIL", "preview": "manual_rules_fallback_preview"}' ``` 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. ## Before you begin After you get confirmation that your account was added to the private preview: - Set up [Stripe Tax](https://docs.stripe.com/tax/set-up.md) 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](https://docs.stripe.com/tax/supported-countries.md) - [See the list of unsupported jurisdictions](https://docs.stripe.com/tax/zero-tax.md#excluded-territories) - 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](https://docs.stripe.com/api/v2/tax/manual-rules.md) to define tax rules for unsupported jurisdictions. Each rule maps a combination of location and product tax code to a specific tax rate. ```curl curl -X POST https://api.stripe.com/v2/tax/manual_rules \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-06-24.preview" \ --json '{ "location": { "country": "IL" }, "products": [ { "type": "tax_code", "tax_code": "txcd_99999999" } ], "scheduled_tax_rates": [ { "rates": [ { "country": "IL", "description": "Israel VAT", "display_name": "VAT", "percentage": "18" } ] } ] }' ``` You can create rules at the country level or at the country and state level for more specific coverage: ```curl curl -X POST https://api.stripe.com/v2/tax/manual_rules \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-06-24.preview" \ --json '{ "location": { "country": "FR", "state": "RE" }, "products": [ { "type": "tax_code", "tax_code": "txcd_99999999" } ], "scheduled_tax_rates": [ { "rates": [ { "country": "FR", "state": "RE", "description": "Réunion VAT", "display_name": "VAT", "percentage": "8.5" } ] } ] }' ``` 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: | Country | Region code | Territory | | --- | --- | --- | | FR | GP | Guadeloupe | | FR | MQ | Martinique | | FR | GF | French Guiana | | FR | RE | Reunion | | FR | YT | Mayotte | | ES | CN | Canary Islands | | ES | CE | Ceuta | | ES | ML | Melilla | | PT | 20 | Azores | | PT | 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](https://docs.stripe.com/tax/manual-rules-fallback.md#sign-up) to request access. ## Test your integration To verify that manual rules fallback works correctly: 1. Create a manual rule for a test jurisdiction and product tax code. 2. Create a customer with an address in that jurisdiction. 3. Create a subscription or invoice with automatic tax enabled. 4. Confirm the response includes `tax_calculation_fallback` with the expected reason and outcome. 5. 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: ```curl curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}} \ -u "<>:" ``` | 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: ```curl curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}} \ -u "<>:" ``` 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. ## See also - [Set up Stripe Tax](https://docs.stripe.com/tax/set-up.md) - [Supported countries](https://docs.stripe.com/tax/supported-countries.md) - [Collect taxes for recurring payments](https://docs.stripe.com/tax/subscriptions.md)