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.

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 you’re ready to use Stripe Tax

Complete this check if you need to assess whether Stripe Tax can be enabled. Use our official libraries for access to the Stripe API. Retrieve the tax.settings object:

You can also listen to the tax.settings.updated webhook event, which triggers when you update tax settings through the Stripe Dashboard or when new required tax settings are introduced. See take webhooks live to learn how to add a webhook endpoint.

You’re 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": {}
  }
}

You aren’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 your settings

Complete this step when you manage all Stripe Tax configuration through your own interface.

You can modify the settings through an update settings call. Perform a call providing the head office location, the preset tax code, and the tax behavior.

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.

{
  "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	Explanation	Supported
`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 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.