Sample - Stripe API
POST/v1/tax_rates/{tax_rate}

Update a tax rate

Updates an existing tax rate identified by its tax rate ID. Use the form fields to change its active state, displayed name, jurisdiction, country, metadata, or tax classification. A successful response returns the updated tax rate object.

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

1 parameter · 9 body fields
tax_ratestringrequired
The unique identifier of the tax rate to update. Must not exceed 5000 characters.

Optional tax rate fields to update using form-encoded data.

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_namestringoptional
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.
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`.
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 updated tax rate object, including its identifier, active state, display name, percentage, inclusivity, jurisdiction, and metadata.
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
defaultReturns an error object containing an error type and, when available, details such as a message, parameter, code, or documentation URL.
errorobjectrequired

Error handling

tax_rate must identify the tax rate to update and must not exceed 5000 characters. display_name and jurisdiction must not exceed 50 characters, while country, description, and state must not exceed 5000 characters; tax_type must use one of the enumerated tax classifications.