Tax Rate

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

  • jurisdiction_levelnullable enum

  • livemodeboolean

  • 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
}
Stripe Shell
Test mode
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Log in to your Stripe account and press Control + Backtick (`) on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g., )
The Stripe Shell is best experienced on desktop.
$