---
title: Tax rates
description: Define rates for countries and regions, stack components like GST and PST, and schedule rate changes ahead of time.
domain: tax
status: shipped
visibility: public
last_verified: 2026-08-01
order: 10
---
A tax rate is a named percentage that applies to a place. You give it a name, a country, and a percentage, and optionally a state or region within that country. yRecurring keeps your rates in a catalog and picks the right ones for each customer when it makes an invoice.

## Country and region

A rate covers a country, and can narrow to a state or region inside it:

- A country-wide rate applies everywhere in that country.
- A region rate applies to just that state or province.

You can have both. When a customer's address matches a region that has its own rates, the region rates are used. If only country-wide rates exist, those apply. The most specific scope for the customer's billing address wins.

## Stacking rates

Some places charge more than one tax on the same amount. Canada charges GST plus a provincial tax, and India splits GST into CGST and SGST. To handle this, add several rates to the same country and region, one per component, each with its own name. They all apply together, and the invoice shows each component on its own line.

For example, for a customer in British Columbia you could add "GST" at 5% and "BC PST" at 7%, both scoped to CA / BC. The invoice then carries both, and reports break them out separately.

## Scheduling a rate change

Governments announce rate changes ahead of time. You can schedule them instead of editing rates at midnight:

- Each rate can have a start date and an end date. Leave both empty for a rate that always applies.
- To schedule a change, set an end date on the current rate and add the new rate with the same name, starting on that date.

Two same-named rates for the same place can only exist when their date windows do not overlap, so the same tax can never apply twice at once.

## Percentages

A rate is a percentage from 0 to 100. It is stored precisely, so a rate like 8.25% is kept exactly, with no rounding drift when it is applied.

## Turning a rate off

A rate can be archived when you no longer use it. An archived rate stops applying to new invoices but stays on record, and past invoices keep the tax they already calculated.

## Automatic tax with Avalara

Rates in this catalog are the ones you set up yourself, and they are always the fallback. If you want tax computed automatically across many jurisdictions, connect [Avalara](/guide/integrations/avalara) and it takes over the calculation for invoices, with your manual rates still covering any outage.

## In the API

Create a tax rate with the `POST /v1/tax-rates` endpoint, giving the name, country, optional region, the percentage, and optional effective dates. You can list rates and archive one too. See the [API reference](/reference).

## Edge cases

- **A country needs a two-letter code.** Countries use the standard two-letter country codes.
- **Region is optional.** Leave it off for a country-wide rate.
- **Most specific scope wins as a set.** When any region rates match, only region rates apply; country-wide rates step back entirely.
- **Same name, same place, overlapping dates is rejected.** That would apply the same tax twice.