API reference
Tax Rates
Tax rates can be applied to invoices, subscriptions and Checkout Sessions to collect tax. Related guide: Tax rates
https://api.knoxapi.comCreate a tax rate
POST/v1/tax_rates
Creates a new tax rate.
Body parameters
display_namestringRequiredThe display name of the tax rate, which will be shown to users.
inclusivebooleanRequiredThis specifies if the tax rate is inclusive or exclusive.
percentagenumberRequiredThis represents the tax rate percent out of 100.
activebooleanFlag 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.
countrystringTwo-letter country code (ISO 3166-1 alpha-2).
descriptionstringAn arbitrary string attached to the tax rate for your internal use only. It will not be visible to your customers.
expandarray of stringsSpecifies which fields in the response should be expanded.
jurisdictionstringThe jurisdiction for the tax rate. You can use this label field for tax reporting purposes. It also appears on your customer’s invoice.
metadataobjectSet 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.statestringISO 3166-2 subdivision code, without country prefix. For example, "NY" for New York, United States.
tax_typestringThe high-level tax type, such as
vatorsales_tax.Possible valuesamusement_taxcommunications_taxgsthstigstjctlease_taxmass_transit_parking_taxparking_taxpstqstretail_delivery_feerstsales_taxservice_taxvat
Returns
The tax_rate object.
curl https://api.knoxapi.com/v1/tax_rates \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
-d display_name=VAT \
-d inclusive=false \
-d percentage=19const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const taxRate = await stripe.taxRates.create({
display_name: 'VAT',
inclusive: false,
percentage: 19,
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
tax_rate = client.v1.tax_rates.create(params={
"display_name": "VAT",
"inclusive": False,
"percentage": 19,
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
tax_rate = Stripe::TaxRate.create({
display_name: 'VAT',
inclusive: false,
percentage: 19,
}){
"active": true,
"country": "DE",
"created": 1234567890,
"description": "VAT Germany",
"display_name": "VAT",
"effective_percentage": null,
"id": "txr_1Pgc7BB7WZ01zgkW4Iwwvf6z",
"inclusive": false,
"jurisdiction": "DE",
"jurisdiction_level": null,
"livemode": false,
"metadata": {},
"object": "tax_rate",
"percentage": 19,
"state": null,
"tax_type": "vat",
"flat_amount": {
"amount": 1413853096,
"currency": "currency"
},
"rate_type": null
}List all tax rates
GET/v1/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.
Query parameters
activebooleanOptional flag to filter by tax rates that are either active or inactive (archived).
createdobject | integerOptional range for filtering created date.
Show 4 child parameters
gtintegergteintegerltintegerlteinteger
ending_beforestringA cursor for use in pagination.
ending_beforeis an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting withobj_bar, your subsequent call can includeending_before=obj_barin order to fetch the previous page of the list.expandarray of stringsSpecifies which fields in the response should be expanded.
inclusivebooleanOptional flag to filter by tax rates that are inclusive (or those that are not inclusive).
limitintegerA limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
starting_afterstringA cursor for use in pagination.
starting_afteris an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending withobj_foo, your subsequent call can includestarting_after=obj_fooin order to fetch the next page of the list.
Returns
A list of tax_rate objects.
curl -G https://api.knoxapi.com/v1/tax_rates \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
--data-urlencode limit=3const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const page = await stripe.taxRates.list({
limit: 3,
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
page = client.v1.tax_rates.list(params={
"limit": 3,
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
page = Stripe::TaxRate.list({
limit: 3,
}){
"object": "list",
"url": "/v1/tax_rates",
"has_more": false,
"data": [
{
"active": true,
"country": "DE",
"created": 1234567890,
"description": "VAT Germany",
"display_name": "VAT",
"effective_percentage": null,
"id": "txr_1Pgc7BB7WZ01zgkW4Iwwvf6z",
"inclusive": false,
"jurisdiction": "DE",
"jurisdiction_level": null,
"livemode": false,
"metadata": {},
"object": "tax_rate",
"percentage": 19,
"state": null,
"tax_type": "vat",
"flat_amount": {
"amount": 1413853096,
"currency": "currency"
},
"rate_type": null
}
]
}Update a tax rate
POST/v1/tax_rates/{tax_rate}
Updates an existing tax rate.
Path parameters
tax_ratestringRequired
Body parameters
activebooleanFlag 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.
countrystringTwo-letter country code (ISO 3166-1 alpha-2).
descriptionstringAn arbitrary string attached to the tax rate for your internal use only. It will not be visible to your customers.
display_namestringThe display name of the tax rate, which will be shown to users.
expandarray of stringsSpecifies which fields in the response should be expanded.
jurisdictionstringThe jurisdiction for the tax rate. You can use this label field for tax reporting purposes. It also appears on your customer’s invoice.
metadataobjectSet 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.statestringISO 3166-2 subdivision code, without country prefix. For example, "NY" for New York, United States.
tax_typestringThe high-level tax type, such as
vatorsales_tax.Possible valuesamusement_taxcommunications_taxgsthstigstjctlease_taxmass_transit_parking_taxparking_taxpstqstretail_delivery_feerstsales_taxservice_taxvat
Returns
The tax_rate object.
curl https://api.knoxapi.com/v1/tax_rates/txr_1Pgc7BB7WZ01zgkW4Iwwvf6z \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
-d "metadata[order_id]=6735"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const taxRate = await stripe.taxRates.update('txr_1Pgc7BB7WZ01zgkW4Iwwvf6z', {
metadata: {
order_id: '6735',
},
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
tax_rate = client.v1.tax_rates.update("txr_1Pgc7BB7WZ01zgkW4Iwwvf6z", params={
"metadata": {
"order_id": "6735",
},
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
tax_rate = Stripe::TaxRate.update('txr_1Pgc7BB7WZ01zgkW4Iwwvf6z', {
metadata: {
order_id: '6735',
},
}){
"active": true,
"country": "DE",
"created": 1234567890,
"description": "VAT Germany",
"display_name": "VAT",
"effective_percentage": null,
"id": "txr_1Pgc7BB7WZ01zgkW4Iwwvf6z",
"inclusive": false,
"jurisdiction": "DE",
"jurisdiction_level": null,
"livemode": false,
"metadata": {},
"object": "tax_rate",
"percentage": 19,
"state": null,
"tax_type": "vat",
"flat_amount": {
"amount": 1413853096,
"currency": "currency"
},
"rate_type": null
}Retrieve a tax rate
GET/v1/tax_rates/{tax_rate}
Retrieves a tax rate with the given ID
Path parameters
tax_ratestringRequired
Query parameters
expandarray of stringsSpecifies which fields in the response should be expanded.
Returns
The tax_rate object.
curl https://api.knoxapi.com/v1/tax_rates/txr_1Pgc7BB7WZ01zgkW4Iwwvf6z \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const taxRate = await stripe.taxRates.retrieve('txr_1Pgc7BB7WZ01zgkW4Iwwvf6z');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
tax_rate = client.v1.tax_rates.retrieve("txr_1Pgc7BB7WZ01zgkW4Iwwvf6z")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
tax_rate = Stripe::TaxRate.retrieve('txr_1Pgc7BB7WZ01zgkW4Iwwvf6z'){
"active": true,
"country": "DE",
"created": 1234567890,
"description": "VAT Germany",
"display_name": "VAT",
"effective_percentage": null,
"id": "txr_1Pgc7BB7WZ01zgkW4Iwwvf6z",
"inclusive": false,
"jurisdiction": "DE",
"jurisdiction_level": null,
"livemode": false,
"metadata": {},
"object": "tax_rate",
"percentage": 19,
"state": null,
"tax_type": "vat",
"flat_amount": {
"amount": 1413853096,
"currency": "currency"
},
"rate_type": null
}Operations and schemas come from the pinned Stripe OpenAPI specification (MIT); response examples from its fixtures. Nested object definitions and enums are in the complete specification.