Menu

Tax Regions API Routes

A tax region is a region's tax settings. It has tax rates and rules. So, after you create a region, you must create a tax region for it.

A tax region can extend settings from a parent tax region.

These API routes allow admin users to manage tax regions.

GET /admin/tax-regions#

List Tax Regions

Retrieve a list of tax regions. The tax regions can be filtered by fields such as id. The tax regions 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 term to filter a tax region's searchable properties.
idstring | string[]Optional
Filter by a tax region ID.
country_codestring | string[] | objectOptional
Filter by a country code. Accepts the filter operators.
province_codestring | string[] | objectOptional
Filter by a ISO 3166-2 province code. Must be lower-case. Accepts the filter operators.
parent_idstring | string[] | objectOptional
Filter by the ID of a parent tax region to retrieve its child tax regions. Accepts the filter operators.
created_bystring | string[]Optional
Filter by the ID of the user to retrieve the tax regions they created.
created_atstring | objectOptional
Filter by a tax region's creation date. Accepts the filter operators.
updated_atstring | objectOptional
Filter by a tax region's update date. Accepts the filter operators.
deleted_atstring | objectOptional
Filter by a tax region'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_regionsobject[]
The list of tax regions.

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

POST /admin/tax-regions#

Create Tax Region

Create a tax region.

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)

country_codestring
The tax region's country code.
Example: us
province_codestringOptional
The tax region's ISO 3166-2 province code. Must be lower-case.
Example: us-ca
parent_idstringOptional
The ID of the parent tax region.
default_tax_rateobjectOptional
The tax region's default tax rate.
metadataobjectOptional
The tax region's metadata, used to store custom key-value pairs. Learn more in the Manage Metadata section.
provider_idstringOptional
The ID of the tax provider used to calculate the tax rate in this tax region.

Request examples

Responses

200 OK

tax_regionobject
The tax region's details.

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

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

Get a Tax Region

Retrieve a tax region by its ID. You can expand the tax region'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 region'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_regionobject
The tax region's details.

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

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

Update a Tax Region

Update a tax region's details.

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

Path parameters

idstring
The tax region'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)

province_codestringOptional
The tax region's ISO 3166-2 province code. Must be lower-case.
Example: us-ca
metadataobjectOptional
The tax region's metadata, can hold custom key-value pairs. Learn more in the Manage Metadata section.
provider_idstringOptional
The ID of the tax provider to use when calculating taxes for this tax region.

Request examples

Responses

200 OK

tax_regionobject
The tax region's details.

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

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

Delete a Tax Region

Delete a tax region.

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

Path parameters

idstring
The tax region's ID.

Request examples

Responses

200 OK

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

Default: "tax_region"

deletedboolean
Whether the tax region was deleted.

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