Getting All Tax Zones
Endpoint: GET/admin /tax_zones
Purpose
This endpoint retrieves a list of tax zones, which define regions where specific tax rules apply. These zones can be based on geographic locations, radius-based areas, or country/state selections, helping businesses apply the correct tax rates based on customer locations.
Path Parameters
This endpoint does not require any path parameters.
Query Parameters:
| Field | Type | Description |
|---|---|---|
| limit | integer | The maximum number of tax zones to return per request (default: 20) |
| offset | integer | The starting point for fetching tax zones (used for pagination) |
| order_by | string | The field by which results should be sorted (e.g., created_at, name) |
| direction | string | The sorting direction (asc for ascending, desc for descending`) |
Use Case
A user retrieves a list of tax zones to apply appropriate tax rates based on location. Businesses can use this to manage tax rules for different regions, ensuring compliance with taxation policies while simplifying tax calculations. The query parameters allow users to control pagination and sorting, making it easier to find relevant tax zones.
Request Body
This endpoint does not require a request body.
Response
The response contains a list of tax zones, including zone ID, name, status, geographic coverage, and creation details. Each tax zone may be defined by a radius-based location, country, state, or postal code selection. If use_radius is true, the zone is defined based on distance from a central point. If use_radius is false, tax zones are determined by specific countries, states, or postal codes. The response also includes pagination details, allowing users to navigate through large datasets.
{
"tax_zones": [
{
"status": "TAX_ZONE_STATUS",
"id": "TAX_ZONE_ID",
"name": "TAX_ZONE_NAME",
"use_radius": USE_RADIUS,
"start_location": "START_LOCATION",
"radius": RADIUS,
"countries": ["COUNTRY_LIST"],
"states": ["STATE_LIST"],
"post_code": "POSTAL_CODE",
"created_by": "CREATED_BY",
"created_at": "CREATED_TIMESTAMP",
"updated_at": "UPDATED_TIMESTAMP"
}
],
"pagination": {
"records": TOTAL_RECORDS,
"limit": RECORDS_LIMIT,
"offset": RECORDS_OFFSET,
"previous_page": "PREVIOUS_PAGE_LINK",
"next_page": "NEXT_PAGE_LINK"
}
}
Getting Specific Tax Zone
Endpoint: GET/admin /tax_zones/{$zone_id}
Purpose
This endpoint retrieves details for a specific tax zone, including its name, geographic coverage, and system settings. It helps businesses define and apply tax rules for different regions based on country, state, or radius-based locations.
Path Parameters
| Field | Type | Description |
|---|---|---|
| zone_id | integer | The unique identifier of the tax zone |
Query Parameters
This endpoint does not require any query parameters.
Use Case
A user retrieves detailed information about a specific tax zone to verify tax settings and regional coverage. This helps businesses apply accurate tax rates to transactions based on country, state, or geographic radius rules.
Request Body
This endpoint does not require a request body.
Response
The response contains the tax zone’s details, including ID, name, default status, radius-based settings, and geographic coverage. If use_radius is false, the tax zone is defined by specific countries, states, or postal codes. The response also provides timestamps for creation and last update, ensuring businesses can track tax zone modifications.
{
"tax_zone": {
"id": TAX_ZONE_ID,
"name": "TAX_ZONE_NAME",
"system_generated": SYSTEM_GENERATED,
"default": DEFAULT_STATUS,
"use_radius": USE_RADIUS,
"radius": RADIUS_VALUE,
"start_location": "START_LOCATION",
"countries": [
{
"id": COUNTRY_ID,
"name": "COUNTRY_NAME",
"code": "COUNTRY_CODE"
}
],
"states": [
{
"id": STATE_ID,
"name": "STATE_NAME",
"code": "STATE_CODE"
}
],
"post_code": ["POSTAL_CODE_LIST"],
"created_at": "CREATED_TIMESTAMP",
"updated_at": "UPDATED_TIMESTAMP"
}
}
