Menu

Tax Rates API Routes

A tax rate is a percentage amount used to calculate the tax amount of each taxable item's price, such as line items or shipping methods.

Each tax region has a default tax rate. You can create tax rates that override the default using tax rules.

These API routes allow admin users to manage tax rates and their rules.

GET /admin/tax-rates#

List Tax Rates

Retrieve a list of tax rates. The tax rates can be filtered by fields such as id. The tax rates can also be sorted or paginated.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
qstringOptional
Search terms to filter the tax rate's searchable properties.
tax_region_idstring | string[] | objectOptional
Filter by a tax region ID to retrieve its associated rates. Accepts the filter operators.
is_default"true" | "false"Optional
Filter by whether the tax rate is a default in its tax region.
created_atobjectOptional
Filter by a tax rate's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a tax rate's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by a tax rate's deletion date. Accepts the filter operators.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
with_deletedbooleanOptional
Whether to include deleted records in the result.

Request examples

Responses

200 OK

limitnumber
The maximum number of items returned.
offsetnumber
The number of items skipped before retrieving the returned items.
countnumber
The total number of items.
tax_ratesobject[]
The tax rate's tax rates.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/tax-rates#

Create Tax Rate

Create a tax rate.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

namestring
The tax rate's name.
Example: VAT
tax_region_idstring
The ID of the tax region this rate belongs to.
ratenumberOptional
The rate to charge.
Example: 10
codestring
The code the tax rate is identified by.
rulesobject[]Optional
The tax rate's rules.
is_defaultbooleanOptional
Whether the tax rate is the default in its tax region.
is_combinablebooleanOptional
Whether the tax rate should be combined with parent rates.
metadataobjectOptional
The tax rate's metadata, used to store custom key-value pairs. Learn more in the Manage Metadata section.

Request examples

Responses

200 OK

tax_rateobject
The tax rate's details.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/tax-rates/{id}#

Get a Tax Rate

Retrieve a tax rate by its ID. You can expand the tax rate's relations or select the fields that should be returned.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The tax rate's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request examples

Responses

200 OK

tax_rateobject
The tax rate's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/tax-rates/{id}#

Update a Tax Rate

Update a tax rate's details.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The tax rate's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

ratenumberOptional
The rate to charge.
codestringOptional
The code that the tax rate is identified by.
rulesobject[]Optional
The tax rate's rules.
namestringOptional
The tax rate's name.
is_defaultbooleanOptional
Whether the tax rate is the default in the store.
is_combinablebooleanOptional
Whether the tax rate should be combined with parent rates.
metadataobjectOptional
The tax rate's metadata, can hold custom key-value pairs. Learn more in the Manage Metadata section.

Request examples

Responses

200 OK

tax_rateobject
The tax rate's details.

400, 401, 404, 409, 422, 500: an error response is returned.

DELETE /admin/tax-rates/{id}#

Delete a Tax Rate

Delete a tax rate.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The tax rate's ID.

Request examples

Responses

200 OK

idstring
The tax rate's ID.
objectstring
The name of the deleted object.

Default: "tax_rate"

deletedboolean
Whether the tax rate was deleted.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/tax-rates/{id}/rules#

Create Tax Rule for a Rate

Create a tax rule for a rate.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The tax rate's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

referencestring
The name of a table in the database that this rule points to.
Example: product_type
reference_idstring
The ID of a record in the table specified in reference.
Example: ptype_123

Request examples

Responses

200 OK

tax_rateobject
The tax rate's details.

400, 401, 404, 409, 422, 500: an error response is returned.

DELETE /admin/tax-rates/{id}/rules/{rule_id}#

Remove Rule of Tax Rate

Remove a tax rate's rule.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The tax rate's ID.
rule_idstring
The tax rate rule's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request examples

Responses

200 OK

idstring
The tax rate's ID.
objectstring
The name of the deleted object.
deletedboolean
Whether the Tax Rate was deleted.
parentobjectOptional
The tax rate's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Found a problem with this page?Report Issue
Edited Nov 14·Edit this page