Skip to main content
POST
/
v1
/
tax
/
rates
curl --location --request POST 'https://api.stateset.com/v1/tax/rates' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "name": "California State Sales Tax",
    "code": "CA_STATE_SALES",
    "rate": 0.0725,
    "type": "sales",
    "jurisdiction": {
        "country": "US",
        "state": "CA"
    },
    "rules": {
        "exempt_categories": ["food_grocery", "prescription_drugs"],
        "exempt_customer_types": ["wholesale", "government"],
        "shipping_taxable": true,
        "compound": false,
        "priority": 1
    },
    "validity": {
        "effective_date": "2024-01-01T00:00:00Z"
    },
    "registration": {
        "registration_number": "CA-123456789"
    },
    "is_inclusive": false,
    "status": "active"
}'

{
  "id": "tax_rate_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "object": "tax_rate",
  "name": "California State Sales Tax",
  "code": "CA_STATE_SALES",
  "rate": 0.0725,
  "type": "sales",
  "jurisdiction": {
    "country": "US",
    "state": "CA",
    "level": "state",
    "display_name": "California, United States"
  },
  "rules": {
    "product_categories": [],
    "exempt_categories": ["food_grocery", "prescription_drugs"],
    "customer_types": [],
    "exempt_customer_types": ["wholesale", "government"],
    "minimum_amount": null,
    "shipping_taxable": true,
    "compound": false,
    "priority": 1
  },
  "validity": {
    "effective_date": "2024-01-01T00:00:00Z",
    "expiration_date": null,
    "is_active": true
  },
  "registration": {
    "registration_number": "CA-123456789",
    "registered_name": null,
    "registered_address": null
  },
  "is_inclusive": false,
  "status": "active",
  "created_at": "2024-01-20T11:00:00Z",
  "updated_at": "2024-01-20T11:00:00Z",
  "created_by": "user_123",
  "statistics": {
    "orders_count": 0,
    "total_tax_collected": 0,
    "last_applied": null
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.stateset.com/llms.txt

Use this file to discover all available pages before exploring further.

This endpoint creates a new tax rate that can be applied to orders based on location, product category, or customer type. Tax rates support complex jurisdiction hierarchies and exemptions.

​
Authentication

This endpoint requires a valid API key with tax:write permissions. 
Authorization: Bearer YOUR_API_KEY

​
Request Body

​
name
string
required
Tax rate name (e.g., “California State Sales Tax”)
​
code
string
required
Unique tax code identifier
​
rate
number
required
Tax rate as a decimal (e.g., 0.0725 for 7.25%)
​
type
string
required
Tax type: “sales”, “vat”, “gst”, “pst”, “hst”, “custom”
​
jurisdiction
object
required
Tax jurisdiction details
​
rules
object
Tax application rules
​
validity
object
Tax rate validity period
​
registration
object
Tax registration details
​
is_inclusive
boolean
Whether prices include this tax (common for VAT)
​
status
string
Tax rate status: “active”, “pending”, “inactive”
​
metadata
object
Additional custom fields

​
Response

Returns the created tax rate object. 
curl --location --request POST 'https://api.stateset.com/v1/tax/rates' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "name": "California State Sales Tax",
    "code": "CA_STATE_SALES",
    "rate": 0.0725,
    "type": "sales",
    "jurisdiction": {
        "country": "US",
        "state": "CA"
    },
    "rules": {
        "exempt_categories": ["food_grocery", "prescription_drugs"],
        "exempt_customer_types": ["wholesale", "government"],
        "shipping_taxable": true,
        "compound": false,
        "priority": 1
    },
    "validity": {
        "effective_date": "2024-01-01T00:00:00Z"
    },
    "registration": {
        "registration_number": "CA-123456789"
    },
    "is_inclusive": false,
    "status": "active"
}'

{
  "id": "tax_rate_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "object": "tax_rate",
  "name": "California State Sales Tax",
  "code": "CA_STATE_SALES",
  "rate": 0.0725,
  "type": "sales",
  "jurisdiction": {
    "country": "US",
    "state": "CA",
    "level": "state",
    "display_name": "California, United States"
  },
  "rules": {
    "product_categories": [],
    "exempt_categories": ["food_grocery", "prescription_drugs"],
    "customer_types": [],
    "exempt_customer_types": ["wholesale", "government"],
    "minimum_amount": null,
    "shipping_taxable": true,
    "compound": false,
    "priority": 1
  },
  "validity": {
    "effective_date": "2024-01-01T00:00:00Z",
    "expiration_date": null,
    "is_active": true
  },
  "registration": {
    "registration_number": "CA-123456789",
    "registered_name": null,
    "registered_address": null
  },
  "is_inclusive": false,
  "status": "active",
  "created_at": "2024-01-20T11:00:00Z",
  "updated_at": "2024-01-20T11:00:00Z",
  "created_by": "user_123",
  "statistics": {
    "orders_count": 0,
    "total_tax_collected": 0,
    "last_applied": null
  }
}