Canada library

What's in it

• Provinces and territories. All 13, with their two-letter codes and their English and French names. findProvince matches what people type into an address form: a code, a name in either language or a common abbreviation such as Nfld. or C.-B., in any case, with or without accents.
• Postal codes. Checks the format and the letters Canada Post uses, returns the code the way Canada Post writes it, and works out the province or territory. The Northwest Territories and Nunavut share the letter X, so for those it uses the first three characters.
• Sales tax rates. GST, HST, PST, QST and Manitoba's RST for any date since April 1, 2013, with the first and last day each rate applied.
• Tax to the cent. Add tax to an amount before tax, or take it out of a price that includes tax. Amounts are whole numbers of cents, each tax is rounded on its own so a receipt can show it, and the parts always add up.

Use it

Install it from npm. It's an ES module with TypeScript types, for Node.js 22 or later and any current browser bundler.

import { calculateSalesTax, parsePostalCode } from '@quickcasa/canada'

parsePostalCode('k1a0b1')?.province
// 'ON'

calculateSalesTax(1999, 'BC').totalCents
// 2239

The README on GitHub covers every function.

Where the data comes from

GST and HST rates come from the Canada Revenue Agency's rate table, and the tests check every province against each period it lists. Provincial rates come from each province's announcement of the change. The French names are as the Canada Revenue Agency writes them, and the postal code rules are Canada Post's.

Before you charge tax

These are the general rates most goods and services are taxed at. Some are exempt, zero-rated or have their own rate, and the place of supply rules decide which province's rates apply to a sale. The library gives you the rates and the math. Check what applies to what you sell with the Canada Revenue Agency, or with the province for PST and QST.

Questions

Why does the history start in 2013?

Before April 1, 2013, British Columbia and Prince Edward Island had different systems, and some provincial taxes were charged on the price including GST. From that date on, every provincial tax is charged on the price before GST, so one calculation covers every date.

Does it check that a postal code is a real address?

No. It checks the format and the letters Canada Post uses. Checking a real address takes Canada Post's own address data.

What happens when a rate changes?

We release a new version with the new rate and the date it takes effect. Earlier dates keep their old rate, so an invoice from before the change works out the same as it did.