Sample - Stripe API
POST/v1/tax_rates

Create a tax rate

Creates a new tax rate for use with invoices, subscriptions, or Checkout Sessions. Supply display_name, inclusive, and percentage, and optionally provide jurisdiction, country, state, metadata, or tax classification details. Inactive rates cannot be used with new applications or Checkout Sessions, although existing subscriptions and invoices can continue using them.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

11 body fields

Tax rate configuration submitted as URL-encoded form data. display_name, inclusive, and percentage are required.

activebooleanoptional
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.
countrystringoptional
Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
descriptionstringoptional
An arbitrary string attached to the tax rate for your internal use only. It will not be visible to your customers.
display_namestringrequired
The display name of the tax rate, which will be shown to users.
expandarray<string>optional
Specifies which fields in the response should be expanded.
inclusivebooleanrequired
This specifies if the tax rate is inclusive or exclusive.
jurisdictionstringoptional
The jurisdiction for the tax rate. You can use this label field for tax reporting purposes. It also appears on your customer’s invoice.
metadataobjectoptional
Set of [key-value pairs](https://docs.stripe.com/api/metadata) 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`.
percentagenumberrequired
This represents the tax rate percent out of 100.
statestringoptional
[ISO 3166-2 subdivision code](https://en.wikipedia.org/wiki/ISO_3166-2), without country prefix. For example, "NY" for New York, United States.
tax_typestringoptional
The high-level tax type, such as `vat` or `sales_tax`.
Allowed:amusement_taxcommunications_taxgsthstigstjctlease_taxmass_transit_parking_taxparking_taxpstqstretail_delivery_fee

2 status codes
200Returns the created tax rate object with its identifier, active status, display name, inclusive setting, percentage, creation time, and object type.
activebooleanrequired
Defaults to `true`. When set to `false`, 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.
countrystringoptional
Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
createdintegerrequired
Time at which the object was created. Measured in seconds since the Unix epoch.
descriptionstringoptional
An arbitrary string attached to the tax rate for your internal use only. It will not be visible to your customers.
display_namestringrequired
The display name of the tax rates as it will appear to your customer on their receipt email, PDF, and the hosted invoice page.
effective_percentagenumberoptional
Actual/effective tax rate percentage out of 100. For tax calculations with automatic_tax[enabled]=true, this percentage reflects the rate actually used to calculate tax based on the product's taxability and whether the user is registered to collect taxes in the corresponding jurisdiction.
flat_amountobjectoptional
The amount of the tax rate when the `rate_type` is `flat_amount`. Tax rates with `rate_type` `percentage` can vary based on the transaction, resulting in this field being `null`. This field exposes the amount and currency of the flat tax rate.
idstringrequired
Unique identifier for the object.
inclusivebooleanrequired
This specifies if the tax rate is inclusive or exclusive.
jurisdictionstringoptional
The jurisdiction for the tax rate. You can use this label field for tax reporting purposes. It also appears on your customer’s invoice.
jurisdiction_levelstringoptional
The level of the jurisdiction that imposes this tax rate. Will be `null` for manually defined tax rates.
Allowed:citycountrycountydistrictmultiplestate
livemodebooleanrequired
If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
metadataobjectoptional
Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:tax_rate
percentagenumberrequired
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.
rate_typestringoptional
Indicates the type of tax rate applied to the taxable amount. This value can be `null` when no tax applies to the location. This field is only present for TaxRates created by Stripe Tax.
Allowed:flat_amountpercentage
statestringoptional
[ISO 3166-2 subdivision code](https://en.wikipedia.org/wiki/ISO_3166-2), without country prefix. For example, "NY" for New York, United States.
tax_typestringoptional
The high-level tax type, such as `vat` or `sales_tax`.
Allowed:amusement_taxcommunications_taxgsthstigstjctlease_taxmass_transit_parking_taxparking_taxpstqstretail_delivery_fee
defaultError response.
errorobjectrequired

Error handling

display_name, inclusive, and percentage are required. display_name must be no more than 50 characters, jurisdiction must be no more than 50 characters, and tax_type must be one of the supported tax type values such as amusement_tax, communications_tax, gst, hst, or retail_delivery_fee.