# Enable tax by default for Checkout Sessions

Configure Stripe Tax to apply automatically to new Checkout Sessions in payment mode, without changing your integration code.

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

## Limitations 

- **Scope**: Covers Checkout Sessions in `payment` mode only. It doesn’t cover `subscription` mode, Payment Links, Invoices, or the Billing APIs.
- **No cross-account cascading**: On Connect, only a connected account’s own tax integration configuration affects its Checkout Sessions. Configuring a platform account’s default has no effect on connected accounts.
- **Best-effort, not guaranteed**: Turning this on doesn’t guarantee every Checkout Session calculates tax. Sessions that fail a compatibility check are created with automatic tax disabled rather than erroring.
- **Doesn’t override explicit requests**: If your integration passes `automatic_tax[enabled]` at all, that value always wins, regardless of your account’s default.

## How Checkout decides whether to calculate tax 

When a request omits `automatic_tax` and the account’s `checkout_sessions[automatic_tax_default_value]` is `enabled_when_possible`, Checkout runs the same compatibility checks used for explicit `automatic_tax[enabled]=true` requests. Checkout enables automatic tax only if:

- Stripe Tax is [activated](https://docs.stripe.com/tax/set-up.md) for the account, with an [origin address](https://docs.stripe.com/tax/set-up.md#head-office) and [tax registrations](https://docs.stripe.com/tax/set-up.md#add-registrations) configured.
- Checkout can resolve the customer’s tax location from the request.
- The request doesn’t use any [incompatible parameters](https://docs.stripe.com/tax/checkout/automatic-tax-default.md#enablement-details).

If any check fails, Checkout creates the Checkout Session with automatic tax disabled instead of returning an error.

## Configure your default 

Tax integration configuration for Checkout is in private preview. Until access is granted, pass `automatic_tax[enabled]` explicitly on each [Checkout Session you create](https://docs.stripe.com/tax/checkout/page.md).

### Request access to automatic tax configuration for Checkout

Request to join the preview for no-code automatic tax calculation. Available only for one-time payments processed through Stripe Checkout.

```bash
curl https://docs.stripe.com/preview/register \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Referer: https://docs.stripe.com/tax/checkout/automatic-tax-default" \
  -d '{"email": "EMAIL", "preview": "tax_default_on_checkout_preview"}'
```

## Inspect why automatic tax was enabled or disabled 

> `enablement_details` is in private preview. It’s meant for debugging your integration, not for driving business logic, and is only returned when you explicitly [expand](https://docs.stripe.com/api/expanding_objects.md) it.

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

```curl
curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_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` | The Checkout Session uses [Managed Payments](https://docs.stripe.com/payments/managed-payments/tax-compliance.md), which 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 Checkout attempts inference and a compatibility check fails. If your account’s `checkout_sessions[automatic_tax_default_value]` is `disabled`, Checkout 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 |
| --- | --- | --- | --- |
| `customer` | [customer](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-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). |
| `mode` | [mode](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode) | This mode isn’t supported for automatic tax inference. | Pass `automatic_tax[enabled]` explicitly for Checkout Sessions using this mode instead. |
| `ui_mode` | [ui_mode](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-ui_mode) | This UI mode isn’t supported for automatic tax inference. | Pass `automatic_tax[enabled]` explicitly for Checkout Sessions using this UI mode instead. |
| `line_items[][tax_rates]` | [tax_rates](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-tax_rates) | A line item sets explicit tax rates, which conflicts with Stripe Tax calculating its own rate. | Remove `tax_rates` from the line item and let Stripe Tax calculate it, or keep passing `automatic_tax[enabled]` explicitly for this Checkout Session. |
| `line_items[][dynamic_tax_rates]` | [dynamic_tax_rates](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-dynamic_tax_rates) | A line item looks up tax rates dynamically, which conflicts with Stripe Tax calculating its own rate. | Remove `dynamic_tax_rates` from the line item and let Stripe Tax calculate it, or keep passing `automatic_tax[enabled]` explicitly for this session. |
| `payment_intent_data[shipping]` | [shipping](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_intent_data-shipping) | Shipping supplied this way can’t be resolved for tax purposes. | Update your integration to collect shipping through the Checkout Session itself instead of `payment_intent_data.shipping`. |
| `customer_update[shipping]` | [shipping](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_update-shipping) | Stripe Tax can’t sync the collected address for use as the customer’s location. | Update your integration to set `customer_update[shipping]` to `auto`. |

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 |
| --- | --- | --- |
| `line_items[][price][tax_behavior]` | [tax_behavior](https://docs.stripe.com/api/prices/object.md#price_object-tax_behavior) | Set `tax_behavior` on the line item’s price. |
| `line_items[][price_data][tax_behavior]` | [tax_behavior](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-price_data-tax_behavior) | Set `tax_behavior` on the line item’s `price_data`. |
| `shipping_options[][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_options[][shipping_rate_data][tax_behavior]` | [tax_behavior](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-shipping_options-shipping_rate_data-tax_behavior) | Set `tax_behavior` on the shipping option’s `shipping_rate_data`. |
| `automatic_surcharge[tax_behavior]` | [tax_behavior](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-automatic_surcharge-tax_behavior) | Set `tax_behavior` on the automatic surcharge. |

## See also

- [Collect tax with the Checkout page](https://docs.stripe.com/tax/checkout/page.md)
- [Use the Settings API to configure Stripe Tax](https://docs.stripe.com/tax/settings-api.md)
- [Test your tax integration](https://docs.stripe.com/tax/testing.md)