Taxes

Tax Management API

The Taxes API allows you to manage tax settings for your store, including tax rates, exemptions, and rules for different regions and product types.

GET /api/taxes/

Retrieve a list of all tax rules in your store. This endpoint supports pagination and filtering.

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`items_per_page`	integer	No	Number of items per page (default: 10)
`country_code`	string	No	Filter tax rules by country code
`state_code`	string	No	Filter tax rules by state/province code
`rate_min`	float	No	Filter tax rules by minimum rate
`rate_max`	float	No	Filter tax rules by maximum rate

Example Response

{
  "taxes": [
    {
      "tax_id": "12",
      "tax_name": "Sales Tax - California",
      "rate_type": "P",
      "rate_value": "7.25",
      "country_code": "US",
      "state_code": "CA",
      "status": "A"
    },
    {
      "tax_id": "13",
      "tax_name": "GST - Canada",
      "rate_type": "P",
      "rate_value": "5.00",
      "country_code": "CA",
      "state_code": "",
      "status": "A"
    }
  ],
  "params": {
    "page": 1,
    "items_per_page": 10,
    "total_items": 2
  }
}

GET /api/taxes/{tax_id}/

Retrieve details for a specific tax rule by its ID.

Example Response

{
  "tax_id": "12",
  "tax_name": "Sales Tax - California",
  "description": "California state sales tax",
  "rate_type": "P",
  "rate_value": "7.25",
  "priority": "0",
  "country_code": "US",
  "state_code": "CA",
  "zip_codes": "",
  "address_type": "S",
  "product_categories": [],
  "tax_exemptions": [],
  "price_includes_tax": "N",
  "status": "A"
}

POST /api/taxes/

Create a new tax rule.

Request Parameters

Parameter	Type	Required	Description
`tax_name`	string	Yes	Name of the tax rule
`rate_type`	string	Yes	Type of rate: "P" for percentage, "F" for fixed amount
`rate_value`	string	Yes	Tax rate value
`country_code`	string	Yes	Two-letter country code
`state_code`	string	No	State/province code
`address_type`	string	No	Address type: "S" for shipping, "B" for billing
`product_categories`	array	No	Array of product category IDs this tax applies to

Example Request

{
  "tax_name": "New York City Tax",
  "description": "NYC local sales tax",
  "rate_type": "P",
  "rate_value": "4.5",
  "country_code": "US",
  "state_code": "NY",
  "zip_codes": "10001,10002,10003,10004,10005,10006,10007",
  "address_type": "S",
  "price_includes_tax": "N",
  "status": "A"
}

PUT /api/taxes/{tax_id}/

Update an existing tax rule.

Example Request

{
  "rate_value": "8.25",
  "description": "Updated California state sales tax",
  "status": "A"
}

DELETE /api/taxes/{tax_id}/

Delete a tax rule.

Important: Deleting a tax rule will permanently remove it from your store. If you want to temporarily disable a tax rule, consider updating its status to "D" (disabled) instead.

Tax Status Codes

Code	Description
`A`	Active
`D`	Disabled
`H`	Hidden

Rate Type Codes

Code	Description
`P`	Percentage (e.g., 7.25%)
`F`	Fixed amount (e.g., $5.00)

Address Type Codes

Code	Description
`S`	Shipping address
`B`	Billing address