# Manage tax rates on Qualy

> Learn how Qualy handles different types of Tax Rates, including inclusive/exclusive rates.

Learn how Qualy handles different types of Tax Rates, including inclusive/exclusive rates.

---

## Before you start

Tax is an essential part of handling payments. Qualy's [Tax API](https://v1-spec.qualyhq.com/#post-/v1/tax/create) calculates all the amounts for you automatically.

## Creating a Tax rate

To create a Tax rate on Qualy, you will have to use the [Tax API](https://v1-spec.qualyhq.com/#post-/v1/tax/create). You can also use the [Dashboard](https://dashboard.qualyhq.com/preferences/tax?taxType=sales-tax).

This is an example of a request creating a Tax rate using Qualy's API.

```javascript
try {
  const response = await fetch('https://api.qualyhq.com/v1/tax/create', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'ApiKey your-api-key-here',
      'X-TENANT-ID': 'your-tenant-id-here',
    },
    body: JSON.stringify({
      "name":"Example tax rate",
      "description":"User-defined tax rate",
      "country":"AU",
      "state":"New South Wales",
      "taxType":"sales-tax",
      "inclusive":true,
      "percentage":0.1
    }),
  });

  if (response.ok) {
    const data = await response.json();

    console.log(data);
  } else {
    throw new Error(`Request failed with status: ${response.status}`);
  }
} catch (error) {
  console.error(error);
}
```

The above request will return the following payload:

```json
{
    "data": {
        "_id": "669a7b211f74b42e14d63693",
        "name": "Example tax rate",
        "description": "User-defined tax rate",
        "country": "AU",
        "status": "active",
        "taxType": "sales-tax",
        "inclusive": true,
        "state": "New South Wales",
        "percentage": 0.1,
        "createdBy": {
            "_id": "6606ab7bfb9085579f1b5769",
            "profile": {
                "firstName": "Your API Key",
                "lastName": "Name",
                "picture": "https://gravatar.com/avatar/?s=450&d=mp"
            }
        }
    }
}
```

### Using Tax rates

Whenever you have to specify the `tax` field, you will need to specify an entity of Qualy's [Tax API](https://v1-spec.qualyhq.com/#post-/v1/tax/create). Supported `tax` fields accept either the Tax ObjectId or tax name. See [Smart references](/docs/smart-references.md).

Once you send the request specifying the desired `tax` Qualy will return the payload with the correct tax calculations and amounts adjusted.

### Understanding tax calculation in Qualy

In Qualy, tax rates can be applied to payments either inclusively or exclusively. Below is an explanation of how tax calculations are performed.

#### Inclusive vs. Exclusive Tax rates

- **Inclusive Tax**: The tax amount is included in the total payment amount.
- **Exclusive Tax**: The tax amount is added to the total payment amount.

#### Tax rate calculation

The following is a detailed explanation of how Qualy calculates Tax amounts.

1. **Tax calculation**:
    - If you set a `tax` property, the tax amount is calculated: `taxAmount = amount * tax.percentage`.

2. **Inclusive Tax**:
    - If the tax is inclusive:
        - The amount without tax is calculated: `amountWithoutTax = amount / (1 + tax.percentage)`.
        - The total tax amount is determined: `taxTotal = amount - amountWithoutTax`.
        - The total amount and the total tax amount are updated in the original entity:
            - `total = amount`
            - `taxTotal = taxTotal`

3. **Exclusive Tax**:
    - If the tax is exclusive:
        - The total payment amount is increased by the tax amount: `total = amount + taxAmount`.
        - The tax amount and the total tax amount are updated in the payment object:
            - `tax.amount = taxAmount`
            - `taxTotal = taxAmount`

4. **No Tax**:
    - If no `tax` is present, the total amount remains the same as the payment amount: `total = amount`.

### Updating Tax rates

When updating a [Tax rate](https://v1-spec.qualyhq.com/#post-/v1/tax/create), Qualy will archive the previous rate, but not delete it. All entities currently using the Tax which has been archive **will continue** using it. You will need to manually update which entity to the new Tax rate.