Create Tax Rate

Create a new tax rate for a specific jurisdiction

POST /v1/tax/rates

cURL

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"
}'

Response

{
  "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 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

Show Jurisdiction properties

country · string · required

ISO 3166-1 alpha-2 country code

state · string

State/Province code (ISO 3166-2)

county · string

County name

city · string

City name

postal_codes · array

Applicable postal/ZIP codes (empty for all)

district · string

Special tax district name

rules · object

Tax application rules

Show Rule properties

product_categories · array

Applicable product categories (empty for all)

exempt_categories · array

Exempt product categories

customer_types · array

Applicable customer types (empty for all)

exempt_customer_types · array

Exempt customer types (e.g., “wholesale”, “government”)

minimum_amount · integer

Minimum order amount for tax to apply (in cents)

shipping_taxable · boolean

Whether shipping is taxable

compound · boolean

Whether this tax compounds on other taxes

priority · integer

Application order (lower applies first)

validity · object

Tax rate validity period

Show Validity properties

effective_date · string · required

When tax rate becomes effective (ISO 8601)

expiration_date · string

When tax rate expires (ISO 8601)

registration · object

Tax registration details

Show Registration properties

registration_number · string

Tax registration/license number

registered_name · string

Registered business name

registered_address · object

Registered address

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

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"
}'

Response

{
  "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
  }
}