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"
}'
const taxRate = await stateset.tax.rates.create({
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"
});
tax_rate = stateset.tax.rates.create(
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
}
}
Create a new tax rate for a specific jurisdiction
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"
}'
const taxRate = await stateset.tax.rates.create({
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"
});
tax_rate = stateset.tax.rates.create(
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
}
}
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 withtax:write permissions.
Authorization: Bearer YOUR_API_KEY
Request Body
string
required
Tax rate name (e.g., “California State Sales Tax”)
string
required
Unique tax code identifier
number
required
Tax rate as a decimal (e.g., 0.0725 for 7.25%)
string
required
Tax type: “sales”, “vat”, “gst”, “pst”, “hst”, “custom”
object
required
object
Tax application rules
Show Rule properties
Show Rule properties
array
Applicable product categories (empty for all)
array
Exempt product categories
array
Applicable customer types (empty for all)
array
Exempt customer types (e.g., “wholesale”, “government”)
integer
Minimum order amount for tax to apply (in cents)
boolean
Whether shipping is taxable
boolean
Whether this tax compounds on other taxes
integer
Application order (lower applies first)
object
object
boolean
Whether prices include this tax (common for VAT)
string
Tax rate status: “active”, “pending”, “inactive”
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"
}'
const taxRate = await stateset.tax.rates.create({
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"
});
tax_rate = stateset.tax.rates.create(
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
}
}
⌘I