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

# Calculate Tax

> Calculate taxes for an order based on location and items

<Note>
  This endpoint calculates applicable taxes for a given order, considering all active tax rates, exemptions, and nexus rules. It returns a detailed breakdown of all taxes to be collected.
</Note>

## Authentication

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

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

## Request Body

<ParamField body="from_address" type="object" required>
  Origin address (seller location)

  <Expandable title="Address properties">
    <ParamField body="line1" type="string" required>
      Street address
    </ParamField>

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

    <ParamField body="state" type="string" required>
      State/Province code
    </ParamField>

    <ParamField body="postal_code" type="string" required>
      Postal/ZIP code
    </ParamField>

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

<ParamField body="to_address" type="object" required>
  Destination address (buyer location)

  <Expandable title="Address properties">
    <ParamField body="line1" type="string" required>
      Street address
    </ParamField>

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

    <ParamField body="state" type="string" required>
      State/Province code
    </ParamField>

    <ParamField body="postal_code" type="string" required>
      Postal/ZIP code
    </ParamField>

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

<ParamField body="line_items" type="array" required>
  Items to calculate tax for

  <Expandable title="Line item properties">
    <ParamField body="id" type="string" required>
      Line item identifier
    </ParamField>

    <ParamField body="quantity" type="integer" required>
      Quantity
    </ParamField>

    <ParamField body="unit_price" type="integer" required>
      Unit price in cents
    </ParamField>

    <ParamField body="product_category" type="string">
      Product category for tax rules
    </ParamField>

    <ParamField body="tax_code" type="string">
      Specific tax code override
    </ParamField>

    <ParamField body="discount" type="integer">
      Discount amount in cents
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="shipping" type="object">
  Shipping details

  <Expandable title="Shipping properties">
    <ParamField body="amount" type="integer" required>
      Shipping cost in cents
    </ParamField>

    <ParamField body="is_taxable" type="boolean">
      Override shipping taxability
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="customer" type="object">
  Customer details for exemptions

  <Expandable title="Customer properties">
    <ParamField body="id" type="string">
      Customer ID
    </ParamField>

    <ParamField body="type" type="string">
      Customer type for exemptions
    </ParamField>

    <ParamField body="tax_exempt" type="boolean">
      Whether customer is tax exempt
    </ParamField>

    <ParamField body="exemption_certificates" type="array">
      Tax exemption certificate numbers
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="transaction_date" type="string">
  Transaction date for rate determination (ISO 8601)
</ParamField>

<ParamField body="currency" type="string">
  ISO 4217 currency code (default: USD)
</ParamField>

### Response

Returns detailed tax calculation breakdown.

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request POST 'https://api.stateset.com/v1/tax/calculate' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-raw '{
      "from_address": {
          "line1": "100 Commerce Way",
          "city": "Los Angeles",
          "state": "CA",
          "postal_code": "90001",
          "country": "US"
      },
      "to_address": {
          "line1": "123 Main St",
          "city": "San Francisco",
          "state": "CA",
          "postal_code": "94105",
          "country": "US"
      },
      "line_items": [
          {
              "id": "item_1",
              "quantity": 2,
              "unit_price": 2999,
              "product_category": "clothing"
          },
          {
              "id": "item_2",
              "quantity": 1,
              "unit_price": 999,
              "product_category": "food_grocery"
          }
      ],
      "shipping": {
          "amount": 1000
      },
      "customer": {
          "id": "cust_abc123",
          "type": "retail"
      }
  }'
  ```

  ```javascript Node.js theme={null}
  const taxCalculation = await stateset.tax.calculate({
    from_address: {
      line1: "100 Commerce Way",
      city: "Los Angeles",
      state: "CA",
      postal_code: "90001",
      country: "US"
    },
    to_address: {
      line1: "123 Main St",
      city: "San Francisco",
      state: "CA",
      postal_code: "94105",
      country: "US"
    },
    line_items: [
      {
        id: "item_1",
        quantity: 2,
        unit_price: 2999,
        product_category: "clothing"
      },
      {
        id: "item_2",
        quantity: 1,
        unit_price: 999,
        product_category: "food_grocery"
      }
    ],
    shipping: {
      amount: 1000
    },
    customer: {
      id: "cust_abc123",
      type: "retail"
    }
  });
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "object": "tax_calculation",
    "order_total": 7997,
    "taxable_amount": 6998,
    "tax_amount": 613,
    "effective_rate": 0.0876,
    "line_items": [
      {
        "id": "item_1",
        "amount": 5998,
        "taxable_amount": 5998,
        "tax_amount": 540,
        "tax_breakdown": [
          {
            "name": "California State Sales Tax",
            "rate": 0.0725,
            "amount": 435,
            "taxable_amount": 5998
          },
          {
            "name": "San Francisco County Tax",
            "rate": 0.0175,
            "amount": 105,
            "taxable_amount": 5998
          }
        ]
      },
      {
        "id": "item_2",
        "amount": 999,
        "taxable_amount": 0,
        "tax_amount": 0,
        "exemption_reason": "food_grocery_exempt"
      }
    ],
    "shipping": {
      "amount": 1000,
      "taxable_amount": 1000,
      "tax_amount": 73,
      "tax_breakdown": [
        {
          "name": "California State Sales Tax",
          "rate": 0.0725,
          "amount": 73
        }
      ]
    },
    "jurisdictions": [
      {
        "name": "California",
        "type": "state",
        "rate": 0.0725,
        "tax_amount": 508
      },
      {
        "name": "San Francisco County",
        "type": "county",
        "rate": 0.0175,
        "tax_amount": 105
      }
    ],
    "has_nexus": true,
    "tax_registration": {
      "state": "CA",
      "registration_number": "CA-123456789"
    },
    "warnings": [],
    "metadata": {
      "calculation_timestamp": "2024-01-20T11:30:00Z",
      "tax_engine_version": "2024.1"
    }
  }
  ```
</ResponseExample>