> ## 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.

# Create Tax Rate

> Create a new tax rate for a specific jurisdiction

<Note>
  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.
</Note>

## Authentication

This endpoint requires a valid API key with `tax:write` permissions.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Request Body

<ParamField body="name" type="string" required>
  Tax rate name (e.g., "California State Sales Tax")
</ParamField>

<ParamField body="code" type="string" required>
  Unique tax code identifier
</ParamField>

<ParamField body="rate" type="number" required>
  Tax rate as a decimal (e.g., 0.0725 for 7.25%)
</ParamField>

<ParamField body="type" type="string" required>
  Tax type: "sales", "vat", "gst", "pst", "hst", "custom"
</ParamField>

<ParamField body="jurisdiction" type="object" required>
  Tax jurisdiction details

  <Expandable title="Jurisdiction properties">
    <ParamField body="country" type="string" required>
      ISO 3166-1 alpha-2 country code
    </ParamField>

    <ParamField body="state" type="string">
      State/Province code (ISO 3166-2)
    </ParamField>

    <ParamField body="county" type="string">
      County name
    </ParamField>

    <ParamField body="city" type="string">
      City name
    </ParamField>

    <ParamField body="postal_codes" type="array">
      Applicable postal/ZIP codes (empty for all)
    </ParamField>

    <ParamField body="district" type="string">
      Special tax district name
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="rules" type="object">
  Tax application rules

  <Expandable title="Rule properties">
    <ParamField body="product_categories" type="array">
      Applicable product categories (empty for all)
    </ParamField>

    <ParamField body="exempt_categories" type="array">
      Exempt product categories
    </ParamField>

    <ParamField body="customer_types" type="array">
      Applicable customer types (empty for all)
    </ParamField>

    <ParamField body="exempt_customer_types" type="array">
      Exempt customer types (e.g., "wholesale", "government")
    </ParamField>

    <ParamField body="minimum_amount" type="integer">
      Minimum order amount for tax to apply (in cents)
    </ParamField>

    <ParamField body="shipping_taxable" type="boolean">
      Whether shipping is taxable
    </ParamField>

    <ParamField body="compound" type="boolean">
      Whether this tax compounds on other taxes
    </ParamField>

    <ParamField body="priority" type="integer">
      Application order (lower applies first)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="validity" type="object">
  Tax rate validity period

  <Expandable title="Validity properties">
    <ParamField body="effective_date" type="string" required>
      When tax rate becomes effective (ISO 8601)
    </ParamField>

    <ParamField body="expiration_date" type="string">
      When tax rate expires (ISO 8601)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="registration" type="object">
  Tax registration details

  <Expandable title="Registration properties">
    <ParamField body="registration_number" type="string">
      Tax registration/license number
    </ParamField>

    <ParamField body="registered_name" type="string">
      Registered business name
    </ParamField>

    <ParamField body="registered_address" type="object">
      Registered address
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="is_inclusive" type="boolean">
  Whether prices include this tax (common for VAT)
</ParamField>

<ParamField body="status" type="string">
  Tax rate status: "active", "pending", "inactive"
</ParamField>

<ParamField body="metadata" type="object">
  Additional custom fields
</ParamField>

### Response

Returns the created tax rate object.

<RequestExample>
  ```bash cURL theme={null}
  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"
  }'
  ```

  ```javascript Node.js theme={null}
  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"
  });
  ```

  ```python Python theme={null}
  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"
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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
    }
  }
  ```
</ResponseExample>