Tax rates can be applied to invoices, subscriptions and Checkout Sessions to collect tax.
Related guide: Tax rates
Attributes
- idstring
Unique identifier for the object.
- activeboolean
Defaults to
true. When set tofalse, this tax rate cannot be used with new applications or Checkout Sessions, but will still work for subscriptions and invoices that already have it set. - countrynullable string
Two-letter country code (ISO 3166-1 alpha-2).
- descriptionnullable string
An arbitrary string attached to the tax rate for your internal use only. It will not be visible to your customers.
- display_
namestring The display name of the tax rates as it will appear to your customer on their receipt email, PDF, and the hosted invoice page.
- inclusiveboolean
This specifies if the tax rate is inclusive or exclusive.
- jurisdictionnullable string
The jurisdiction for the tax rate. You can use this label field for tax reporting purposes. It also appears on your customer’s invoice.
- metadatanullable object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
- percentagefloat
Tax rate percentage out of 100. For tax calculations with automatic_tax[enabled]=true, this percentage includes the statutory tax rate of non-taxable jurisdictions.
- statenullable string
ISO 3166-2 subdivision code, without country prefix. For example, “NY” for New York, United States.
More attributes
- objectstring
- createdtimestamp
- effective_
percentagenullable float - flat_
amountnullable object - jurisdiction_
levelnullable enum - livemodeboolean
- rate_
typenullable enum - tax_
typenullable enum
{ "id": "txr_1MzS4RLkdIwHu7ixwvpZ9c2i", "object": "tax_rate", "active": true, "country": null, "created": 1682114687, "description": "VAT Germany", "display_name": "VAT", "inclusive": false, "jurisdiction": "DE", "livemode": false, "metadata": {}, "percentage": 16, "state": null, "tax_type": null}Creates a new tax rate.
Parameters
- display_
namestringRequired The display name of the tax rate, which will be shown to users.
- inclusivebooleanRequired
This specifies if the tax rate is inclusive or exclusive.
- percentagefloatRequired
This represents the tax rate percent out of 100.
- activeboolean
Flag determining whether the tax rate is active or inactive (archived). Inactive tax rates cannot be used with new applications or Checkout Sessions, but will still work for subscriptions and invoices that already have it set.
- countrystring
Two-letter country code (ISO 3166-1 alpha-2).
- descriptionstring
An arbitrary string attached to the tax rate for your internal use only. It will not be visible to your customers.
- jurisdictionstring
The jurisdiction for the tax rate. You can use this label field for tax reporting purposes. It also appears on your customer’s invoice.
- metadataobject
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to
metadata. - statestring
ISO 3166-2 subdivision code, without country prefix. For example, “NY” for New York, United States.
More parameters
- tax_
typeenum
Returns
The created tax rate object.
{ "id": "txr_1MzS4RLkdIwHu7ixwvpZ9c2i", "object": "tax_rate", "active": true, "country": null, "created": 1682114687, "description": "VAT Germany", "display_name": "VAT", "inclusive": false, "jurisdiction": "DE", "livemode": false, "metadata": {}, "percentage": 16, "state": null, "tax_type": null}Updates an existing tax rate.
Parameters
- activeboolean
Flag determining whether the tax rate is active or inactive (archived). Inactive tax rates cannot be used with new applications or Checkout Sessions, but will still work for subscriptions and invoices that already have it set.
- countrystring
Two-letter country code (ISO 3166-1 alpha-2).
- descriptionstring
An arbitrary string attached to the tax rate for your internal use only. It will not be visible to your customers.
- display_
namestring The display name of the tax rate, which will be shown to users.
- jurisdictionstring
The jurisdiction for the tax rate. You can use this label field for tax reporting purposes. It also appears on your customer’s invoice.
- metadataobject
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to
metadata. - statestring
ISO 3166-2 subdivision code, without country prefix. For example, “NY” for New York, United States.
More parameters
- tax_
typeenum
Returns
The updated tax rate.
{ "id": "txr_1MzS4RLkdIwHu7ixwvpZ9c2i", "object": "tax_rate", "active": false, "country": null, "created": 1682114687, "description": "VAT Germany", "display_name": "VAT", "effective_percentage": 16, "inclusive": false, "jurisdiction": "DE", "livemode": false, "metadata": {}, "percentage": 16, "state": null, "tax_type": null}Retrieves a tax rate with the given ID
Parameters
No parameters.
Returns
Returns an tax rate if a valid tax rate ID was provided. Raises an error otherwise.
{ "id": "txr_1MzS4RLkdIwHu7ixwvpZ9c2i", "object": "tax_rate", "active": true, "country": null, "created": 1682114687, "description": "VAT Germany", "display_name": "VAT", "inclusive": false, "jurisdiction": "DE", "livemode": false, "metadata": {}, "percentage": 16, "state": null, "tax_type": null}