Tax Rates

Overview

The Tax Rates endpoint allows you to retrieve a list of all available tax rates configured in the Curosa platform. Tax rates are used to calculate the appropriate tax amount for products and orders based on the customer's location (country and optionally state/province). Each tax rate is associated with a specific geographic region and includes the percentage rate to be applied.

Authentication

This endpoint requires authentication. Include your API key in the Authorization header. For more information on obtaining an API key, see the Authentication guide.

Get All Tax Rates

Retrieve a list of all available tax rates.

Request

curl -X GET "https://api.curosa.com/v1/tax-rates" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

All responses are returned in JSON format:

{
    "data": [
        {
            "id": 1,
            "name": "Standard Rates",
            "rate": "20.00",
            "country_code": "GB",
            "state_code": null,
            "display_name": "Standard Rates (20%)"
        }
    ]
}

Response Fields:

• id (integer): A unique identifier for the tax rate
• name (string): The name of the tax rate (e.g., "Standard Rates", "Reduced Rate")
• rate (string): The tax rate percentage as a decimal string (e.g., "20.00" for 20%)
• country_code (string): The ISO country code where this tax rate applies (e.g., "GB" for United Kingdom, "US" for United States)
• state_code (string|null): The state or province code where this tax rate applies, if applicable. null indicates the rate applies to the entire country
• display_name (string): A formatted display name combining the tax rate name and percentage (e.g., "Standard Rates (20%)")

Using Tax Rates

Tax rates are automatically applied to products and orders based on the customer's shipping address. When creating or updating products, you can reference tax rates by their id if you need to specify a particular tax rate. The system will use the appropriate tax rate based on the customer's location when processing orders.

Tax rates can be country-specific (when state_code is null) or state/province-specific (when state_code is provided). State-specific rates take precedence over country-wide rates when applicable.