# Enable tax by default for subscriptions

Configure Stripe Tax to apply automatically to new subscriptions, without changing your integration code.

The Tax integration configuration lets Stripe calculate tax automatically on [subscriptions](https://docs.stripe.com/api/subscriptions.md) that don’t explicitly set [automatic_tax](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-automatic_tax).

## Limitations 

- **Scope**: This integration covers subscriptions created through the Subscriptions API. It doesn’t change subscriptions created in the Dashboard, or through quotes, Payment Links, Billing Cadences.
- **Existing subscriptions**: Changing the default doesn’t update existing subscriptions. Use the [subscription migration tools](https://docs.stripe.com/tax/subscriptions/update.md) to enable tax on them.
- **No cross-account cascading**: Each account has its own default. Configuring a platform account’s default doesn’t update connected accounts.
- **Best-effort, not guaranteed**: Turning this on doesn’t guarantee every subscription calculates tax. Subscriptions that fail a compatibility check are created with automatic tax disabled instead of returning an error.
- **It doesn’t override explicit requests**: If your integration passes `automatic_tax[enabled]` at all, that value always takes precedence, regardless of your account’s default.

## How Stripe decides whether to calculate tax 

When a request omits `automatic_tax` and the account’s `subscriptions[automatic_tax_default_value]` is `enabled_when_possible`, Stripe runs compatibility checks. Stripe enables automatic tax only if:

- The account has usable [Stripe Tax settings](https://docs.stripe.com/tax/set-up.md), including an [origin address](https://docs.stripe.com/tax/set-up.md#head-office).
- Stripe can resolve the customer’s [tax location](https://docs.stripe.com/tax/customer-locations.md).
- The subscription doesn’t use parameters incompatible with automatic tax.

If a check fails, Stripe creates the subscription with automatic tax disabled. If a later subscription or subscription item update introduces a conflict, Stripe disables inferred tax and applies the update. Removing the conflict doesn’t automatically re-enable tax. To re-enable it, pass `automatic_tax[enabled]=true` explicitly after resolving the conflict.

Subscription invoices inherit the subscription’s tax configuration, including whether tax was inferred. The separate `invoices` default doesn’t control these invoices. Invoice finalization and credit notes still follow the [requirements for automatic tax](https://docs.stripe.com/tax/invoicing.md).

Subscriptions created through Checkout use the [Checkout default](https://docs.stripe.com/tax/checkout/automatic-tax-default.md). Subscription schedules use the same `subscriptions` default, with [per-phase behavior](https://docs.stripe.com/tax/subscription-schedules/automatic-tax-default.md).

## Configure your default 

Tax integration configuration for subscriptions is in private preview. Until access is granted, pass `automatic_tax[enabled]` explicitly when you [create a subscription](https://docs.stripe.com/tax/subscriptions.md).

## Inspect why automatic tax was enabled or disabled 

> #### Debug automatic tax enablement
> 
> `enablement_details` is in private preview. Use it for debugging your integration, not for driving business logic. It’s only available when you explicitly [expand](https://docs.stripe.com/api/expanding_objects.md) it.

Retrieve the subscription and expand `automatic_tax.enablement_details` to see how `automatic_tax` was determined:

```curl
curl -G https://api.stripe.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "expand[]=automatic_tax.enablement_details"
```

The possible values for `automatic_tax.enablement_details.source` are:

| Value | Meaning |
| --- | --- |
| `explicit` | The request passed `automatic_tax` explicitly. |
| `managed_payments` | [Managed Payments](https://docs.stripe.com/payments/managed-payments/tax-compliance.md) enables automatic tax independently of Tax integration configuration. |
| `tax_integration_configuration` | The account’s Tax integration configuration default determined the value. |

When `source` is `tax_integration_configuration` and `automatic_tax[enabled]` is `false`, `automatic_tax.enablement_details.integration_configuration_disabled_reason.conflicting_field` names the request or resource field that failed a compatibility check.

`integration_configuration_disabled_reason` is only present when Stripe attempts inference and a compatibility check fails. If your account’s `subscriptions[automatic_tax_default_value]` is `disabled`, Stripe doesn’t attempt inference, so `integration_configuration_disabled_reason` (and `conflicting_field`) is `null`.

| Conflicting field | Field | Why it’s incompatible | How to resolve it |
| --- | --- | --- | --- |
| `default_tax_rates` | [default_tax_rates](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-default_tax_rates) | Manual tax rates conflict with Stripe Tax calculating its own rate. | Remove `default_tax_rates` and let Stripe Tax calculate tax. |
| `tax_filing_currency` | `tax_filing_currency` | A caller-supplied tax filing currency isn’t compatible with automatic tax. | Remove `tax_filing_currency`. |
| `items[][tax_rates]` | [tax_rates](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-items-tax_rates) | Manual tax rates conflict with Stripe Tax calculating its own rate. | Remove `tax_rates` from recurring or one-time items. |
| `items[][discountable]` | `discountable` | A negative line item can’t be discountable when using automatic tax. | Set `discountable=false` on negative line items. |
| `customer` | [customer](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-customer) | The attached customer’s address isn’t resolvable for tax purposes. | Collect a resolvable address for the customer. See [Collect customer addresses](https://docs.stripe.com/tax/customer-locations.md). |
| `items` | [tax_code](https://docs.stripe.com/api/products/object.md#product_object-tax_code) | The item’s product has no tax code and the account has no default product tax code. | Set `tax_code` on the item’s product, or configure a [default product tax code](https://docs.stripe.com/tax/products-prices-tax-codes-tax-behavior.md). |

This list isn’t stable or exhaustive. During the preview period, Stripe can add values as needed.

The subscription’s enablement details describe its current tax configuration. Inspect the invoice’s `automatic_tax` separately when debugging a particular invoice.

### Tax behavior issues 

Update your [default tax behavior in the Stripe Tax settings](https://docs.stripe.com/tax/products-prices-tax-codes-tax-behavior.md#set-default-tax-behavior) to resolve all the issues below at once. Otherwise, for per line item control of tax behavior, you can update your integration:

| Conflicting field | Field | How to resolve it |
| --- | --- | --- |
| `items[][price][tax_behavior]` | [tax_behavior](https://docs.stripe.com/api/prices/object.md#price_object-tax_behavior) | Set `tax_behavior` on the item’s price. |
| `items[][price_data][tax_behavior]` | [tax_behavior](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-items-price_data-tax_behavior) | Set `tax_behavior` on the item’s `price_data`. |

## See also

- [Enable tax by default for Checkout Sessions](https://docs.stripe.com/tax/checkout/automatic-tax-default.md)
- [Enable tax by default for invoices](https://docs.stripe.com/tax/invoicing/automatic-tax-default.md)
- [Enable tax by default for subscription schedules](https://docs.stripe.com/tax/subscription-schedules/automatic-tax-default.md)
- [Test your tax integration](https://docs.stripe.com/tax/testing.md)