# Enable tax by default for subscription schedules

Configure Stripe Tax to apply automatically to subscription schedule phases, without changing your integration code.

The Tax integration configuration lets Stripe calculate tax automatically on [subscription schedule](https://docs.stripe.com/api/subscription_schedules.md) phases that don’t explicitly set `automatic_tax` or inherit an explicit value from `default_settings`.

## Limitations 

- **Shared default**: Schedules use `subscriptions[automatic_tax_default_value]`. Subscriptions don’t have a separate schedule default, so changing this setting also affects [new subscriptions](https://docs.stripe.com/tax/subscriptions/automatic-tax-default.md).
- **Existing schedules**: Changing the account default doesn’t retroactively update existing schedules. Use [explicit automatic tax settings](https://docs.stripe.com/tax/subscriptions/update.md#existing-subscription-schedules) to update 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**: Stripe checks each phase separately. A schedule can have some phases with automatic tax enabled and others with it disabled.
- **It doesn’t override explicit requests**: An explicit phase value overrides `default_settings`. An explicit default applies to phases that omit their own value. These values take precedence over account-level inference.

## How Stripe decides whether to calculate tax 

When a phase has no explicit automatic tax setting 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 phase doesn’t use parameters incompatible with automatic tax.

If a check fails, Stripe leaves automatic tax disabled for that phase. When you update phases, Stripe checks eligible phases again. After resolving a conflict, a phase update can re-enable inferred tax. Explicit settings continue to use the usual automatic tax validation.

The subscription created or updated by a phase inherits that phase’s tax configuration, including whether tax was inferred. Its invoices inherit the subscription’s configuration. The separate `invoices` default doesn’t control these invoices.

## Configure your default 

Tax integration configuration for subscription schedules is in private preview. Until we grant you access, set `default_settings[automatic_tax][enabled]` or `phases[][automatic_tax][enabled]` explicitly when you [create or update a schedule](https://docs.stripe.com/billing/subscriptions/subscription-schedules.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 schedule and expand `default_settings.automatic_tax.enablement_details` and `phases.automatic_tax.enablement_details` to see how `automatic_tax` was determined:

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

Inspect each phase’s `automatic_tax.enablement_details` to understand its effective tax configuration. The possible values for `automatic_tax.enablement_details.source` are:

| Value | Meaning |
| --- | --- |
| `explicit` | The request passed `automatic_tax` explicitly for the phase or schedule defaults. |
| `managed_payments` | [Managed Payments](https://docs.stripe.com/payments/managed-payments/tax-compliance.md) enables automatic tax independently of Stripe 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.

If Stripe doesn’t record a conflicting parameter, `integration_configuration_disabled_reason` (and `conflicting_field`) is `null`.

| Conflicting field | Field | Why it’s incompatible | How to resolve it |
| --- | --- | --- | --- |
| `customer` | [customer](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-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). |
| `phases[][default_tax_rates]` | [default_tax_rates](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-default_tax_rates) | Manual tax rates conflict with Stripe Tax calculating its own rate. | Remove `default_tax_rates` from the phase. |
| `phases[][items][][tax_rates]` | [tax_rates](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-items-tax_rates) | Manual tax rates conflict with Stripe Tax calculating its own rate. | Remove `tax_rates` from the phase’s items. |
| `phases[][items]` or `phases[][add_invoice_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 compatibility checks evolve.

### 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 |
| --- | --- | --- |
| `phases[][items][][price][tax_behavior]` | [tax_behavior](https://docs.stripe.com/api/prices/object.md#price_object-tax_behavior) | Set `tax_behavior` on the recurring item’s price. |
| `phases[][items][][price_data][tax_behavior]` | [tax_behavior](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-items-price_data-tax_behavior) | Set `tax_behavior` on the recurring item’s `price_data`. |
| `phases[][add_invoice_items][][price][tax_behavior]` | [tax_behavior](https://docs.stripe.com/api/prices/object.md#price_object-tax_behavior) | Set `tax_behavior` on the one-time item’s price. |

## 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 subscriptions](https://docs.stripe.com/tax/subscriptions/automatic-tax-default.md)
- [Test your tax integration](https://docs.stripe.com/tax/testing.md)