Use the Settings API to configure Stripe Tax
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:
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.
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.
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. Other errors can still surface when trying to call the API on your Stripe integration.