Manage tax rates on Qualy

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 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. You can also use the Dashboard.

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

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:

{
    "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 specificy the tax field, you will need to specify an entity of Qualy's Tax API.

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