Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
Billing
Tax
    Overview
    Get started
    How Tax works
    Set up
    Using the Settings API
    Testing
    Integrate by payment flow
    Payment Links
    Checkout
    Invoicing
    Subscriptions
    Rate card subscriptions
    Custom payment integration
    Integrate with Stripe Connect
    Overview
    Tax for software platforms
    Tax for marketplaces
    Manage your compliance
    Monitor your obligations
    Register
    Calculate tax
    Report
    Third-Party Tax Apps
    File and Remit
    Tax Reference
    Product tax codes
    Supported countries
    FAQ
Reporting
Data
Startup incorporation
HomeFinance automationTax

Use the Settings API to configure Stripe Tax

Learn how to configure tax settings, and check whether an account is ready to perform tax calculations.

Copy page

The Stripe Tax Settings API lets you retrieve and configure the settings required to calculate tax without relying on the Stripe Dashboard.

  • Connect platform: As a platform, you can use this API to set up your connected accounts to use Stripe Tax, or to validate whether an account is already set up appropriately.
  • Direct usage: You can use this API to set up Stripe Tax, or to validate whether you’re already set up appropriately.

Check if the connected account is ready to use Stripe Tax

Complete this check when the Standard account configures Stripe Tax through the Stripe Dashboard but your platform needs to assess if Stripe Tax can be enabled.

Use our official libraries for access to the Stripe API from your application. To check the Stripe Tax settings on the connected account, retrieve the tax.settings object using the Stripe-Account header with a value of the connected account ID:

Command Line
cURL
curl https://api.stripe.com/v1/tax/settings \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -H "Stripe-Account:
{{CONNECTED_ACCOUNT_ID}}
"

You can also listen to the tax.settings.updated webhook event which triggers when accounts update their tax settings or when new required tax settings are introduced. See take webhooks live to learn how to add a webhook endpoint, and make sure you select Listen to events on Connected accounts in the Dashboard.

An account is ready to use Stripe Tax if the response tax.settings object retrieved by the API or webhook event returns "active" for status. The defaults.tax_code and defaults.tax_behavior settings are only required if not provided in the product or price on each API call.

{ "object": "tax.settings", "defaults": { "tax_code": null, "tax_behavior": null }, "head_office": { "address": { "country": "DE" } }, "livemode": false, "status": "active", "status_details": { "active": {} } }

An account isn’t ready to use Stripe Tax if the response tax.settings object returns "pending" for status. The status_details[pending][missing_fields] has a list of all required missing fields.

{ "object": "tax.settings", "defaults": { "tax_code": null, "tax_behavior": null }, "head_office": null, "livemode": false, "status": "pending", "status_details": { "pending": { "missing_fields": ["head_office"] } } }

Configure connected account settings

Complete this step when you manage all Stripe Tax configuration through an interface on your platform.

You can modify the connected account settings through an update settings call. Perform a call providing the head office location, the preset tax code, and the tax behavior by using the Stripe-Account header with a value of the connected account ID.

Command Line
cURL
curl https://api.stripe.com/v1/tax/settings \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -H "Stripe-Account:
{{CONNECTED_ACCOUNT_ID}}
"
\ -d "defaults[tax_code]"=txcd_10000000 \ -d "defaults[tax_behavior]"=inclusive \ -d "head_office[address][country]"=DE

The updated tax.settings object now has a head office, a preset tax code, and a default tax behavior, which allows you to enable Stripe Tax for this connected account.

{ "object": "tax.settings", "defaults": { "tax_code": "txcd_10000000", "tax_behavior": "inclusive" }, "head_office": { "address": { "country": "DE" } }, "livemode": false, "status": "active", "status_details": { "active": {} } }

Validations and errors

The tax codes must refer to available tax codes and the tax behavior must be set as inclusive, exclusive, or inferred_by_currency (after being set, it can’t be set to null). The head_office must include a supported address.

The head_office[address] has the fields line1, line2, city, state, postal_code, and country. The tables below describe the supported address formats.

Example addresses ExplanationSupported
  • line1: 27 Fredrick Ave
  • city: Brothers
  • state: OR
  • postal_code: 97712
  • country: US

Full address

A full address includes at least a line1 (street address or PO Box), city, state, postal code, and country.

The address is matched to the closest address or street in the US Postal Service address database. If a match isn’t found, we use the geographical center (average location of addresses) of the 5-digit postal code as a fallback.

9-digit postal code:

  • postal_code: 97712-4918
  • country: US

5-digit postal code:

  • postal_code: 97712
  • country: US

Country and postal code

If you provide a 5-digit or 9-digit postal code, our system only uses the initial 5 digits for tax calculations. The tax is calculated at the geographical center, which reflects the average location of addresses within the 5-digit postal code area. Check that this is suitable for your business.

  • state: OR
  • country: US

Country and state

We can’t calculate tax for US customers with only an ISO country code and state code.

  • country: US

Country

We can’t calculate tax for US customers with only an ISO country code.

Use one of the above address formats to make sure that we can consistently recognize your connected account’s head office location. The country field must always be a valid ISO country code.

Note

The validation and errors listed here are part of the setup phase. You can still see other errors when trying to call the API on your Stripe integration.

See also

  • Use the Registrations API to manage tax registrations
  • Use Stripe Tax with Connect
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc