Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

The Tax Rate object 

Attributes

  • idstring

    Unique identifier for the object.

  • activeboolean

    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.

  • 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

The 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
}

Create a tax rate 

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.

POST /v1/tax_rates
curl https://api.stripe.com/v1/tax_rates \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d display_name=VAT \
  -d description="VAT Germany" \
  -d percentage=16 \
  -d jurisdiction=DE \
  -d inclusive=false
Response
{
  "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
}

Update a tax rate 

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.

POST /v1/tax_rates/:id
curl https://api.stripe.com/v1/tax_rates/txr_1MzS4RLkdIwHu7ixwvpZ9c2i \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d active=false
Response
{
  "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
}

Retrieve a tax rate 

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.

GET /v1/tax_rates/:id
curl https://api.stripe.com/v1/tax_rates/txr_1MzS4RLkdIwHu7ixwvpZ9c2i \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
Response
{
  "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
}

List all tax rates 

Returns a list of your tax rates. Tax rates are returned sorted by creation date, with the most recently created tax rates appearing first.

Parameters

  • activeboolean

    Optional flag to filter by tax rates that are either active or inactive (archived).

More parameters

  • createdobject

  • ending_beforestring

  • inclusiveboolean

  • limitinteger

  • starting_afterstring

Returns

A dictionary with a data property that contains an array of up to limit tax rates, starting after tax rate starting_after. Each entry in the array is a separate tax rate object. If no more tax rates are available, the resulting array will be empty.

GET /v1/tax_rates
curl -G https://api.stripe.com/v1/tax_rates \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d limit=3
Response
{
  "object": "list",
  "url": "/v1/tax_rates",
  "has_more": false,
  "data": [
    {
      "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
    }
  ]
}