# Enable tax by default for invoices

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

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

## Limitations 

- **Scope**: Covers standalone invoices created through the Invoices API. It doesn’t change invoices created in the Dashboard or through Checkout, subscriptions, or quotes. Invoice revisions inherit the original invoice’s tax configuration.
- **Connect requests**: Stripe uses the caller’s default. Invoices created with a platform key and the `Stripe-Account` header use the platform’s default. A connected account’s default applies when that account calls the API directly.
- **Best-effort, not guaranteed**: Turning this on doesn’t guarantee every invoice calculates tax. Invoices 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 `invoices[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 invoice doesn’t use parameters incompatible with automatic tax.

If the request or included pending invoice items are incompatible, Stripe creates the invoice with automatic tax disabled. If a later invoice, invoice item, or line item update introduces a conflict on a draft invoice with inferred tax, Stripe disables automatic 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.

Finalization and credit notes still follow the [automatic tax requirements for invoices](https://docs.stripe.com/tax/invoicing.md). The default doesn’t bypass those requirements or change tax on a finalized invoice.

## Configure your default 

Tax integration configuration for invoices is in private preview. Until we grant you access, pass `automatic_tax[enabled]` explicitly when you [create an invoice](https://docs.stripe.com/tax/invoicing.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 invoice and expand `automatic_tax.enablement_details` to see how `automatic_tax` was determined:

```curl
curl -G https://api.stripe.com/v1/invoices/{{INVOICE_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 `invoices[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/invoices/create.md#create_invoice-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_percent` | `tax_percent` | A legacy tax percentage conflicts with Stripe Tax calculating its own rate. | Remove the legacy tax percentage. |
| `tax_filing_currency` | `tax_filing_currency` | A caller-supplied tax filing currency isn’t compatible with automatic tax. | Remove `tax_filing_currency`. |
| `customer` | [customer](https://docs.stripe.com/api/invoices/create.md#create_invoice-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). |
| `pending_invoice_items[][tax_rates]`, `tax_rates`, or `lines[][tax_rates]` | [tax_rates](https://docs.stripe.com/api/invoiceitems/create.md#create_invoiceitem-tax_rates) | Manual tax rates conflict with Stripe Tax calculating its own rate. | Remove `tax_rates` from the pending item, invoice item, or invoice line. |
| `tax_amounts` or `lines[][tax_amounts]` | `tax_amounts` | Manual tax amounts conflict with Stripe Tax calculating tax. | Remove `tax_amounts` from the invoice item or invoice line. |
| `pending_invoice_items[][discountable]`, `discountable`, or `lines[][discountable]` | [discountable](https://docs.stripe.com/api/invoiceitems/create.md#create_invoiceitem-discountable) | A negative line item can’t be discountable when using automatic tax. | Set `discountable=false` on negative line items. |
| `pending_invoice_items[][price][product][tax_code]`, `price[product][tax_code]`, `pricing[price][product][tax_code]`, or `price_data[product_data][tax_code]` | [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.

Finalization failures use `automatic_tax.disabled_reason`, such as `finalization_requires_location_inputs`, rather than `integration_configuration_disabled_reason`.

### 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 |
| --- | --- | --- |
| `shipping_cost[shipping_rate][tax_behavior]` | [tax_behavior](https://docs.stripe.com/api/shipping_rates/object.md#shipping_rate_object-tax_behavior) | Set `tax_behavior` on the shipping rate. |
| `shipping_cost[shipping_rate_data][tax_behavior]` | [tax_behavior](https://docs.stripe.com/api/invoices/create.md#create_invoice-shipping_cost-shipping_rate_data-tax_behavior) | Set `tax_behavior` on the invoice’s `shipping_rate_data`. |
| `pending_invoice_items[][price][tax_behavior]` | [tax_behavior](https://docs.stripe.com/api/prices/object.md#price_object-tax_behavior) | Set `tax_behavior` on the pending invoice item’s price. |
| `tax_behavior` | [tax_behavior](https://docs.stripe.com/api/invoiceitems/create.md#create_invoiceitem-tax_behavior) | Set `tax_behavior` on the invoice item. |
| `price[tax_behavior]` or `pricing[price][tax_behavior]` | [tax_behavior](https://docs.stripe.com/api/prices/object.md#price_object-tax_behavior) | Set `tax_behavior` on the invoice item’s price. |
| `price_data[tax_behavior]` | [tax_behavior](https://docs.stripe.com/api/invoiceitems/create.md#create_invoiceitem-price_data-tax_behavior) | Set `tax_behavior` on the invoice item’s `price_data`. |

Bulk line updates can report the corresponding path prefixed with `lines[]`.

## See also

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