North America

Tax handling for United States and Canada.

Setup

Create an entity with your business’s country code (US or CA):

Create US entitytypescript

const _entity = await sdk.entities.create({
  name: "Acme Corp",
  country: "US",
  state: "CA",
  address: "123 Main St",
  city: "San Francisco",
  post_code: "94105",
});

Tax Calculation

Each line item can have multiple independent taxes. Taxes are calculated per-item, not at the document level, so different items can carry different tax rates.

By default, taxes are exclusive (added on top of the price). Set is_tax_inclusive: true on the item if the price already includes tax.

United States

US sales tax varies by jurisdiction. You specify the applicable tax rates — the API does not auto-determine nexus or rates.

Typical US invoices include a combination of state, county, and city taxes:

US state + county taxtypescript

const _invoice = await sdk.invoices.create({
  customer: { name: "US Client", country: "US", state: "CA" },
  items: [
    {
      name: "Consulting Services",
      quantity: 10,
      price: 150,
      taxes: [
        { rate: 7.25 },
        { rate: 0.25 },
        { rate: 0.75 },
      ],
    },
  ],
});

Each tax is calculated and displayed separately on the generated invoice PDF.

Common US Tax Types

Tax	Typical Rate	Notes
State sales tax	0–7.25%	Varies by state; some states have no sales tax
County tax	0–2%	Applied in addition to state tax
City/local tax	0–3%	Some municipalities levy additional tax
Special district	Varies	Transit, stadium, or other district taxes

Canada

Canadian invoices typically combine federal and provincial taxes:

Canadian GST + PSTtypescript

const _invoice = await sdk.invoices.create({
  customer: { name: "Canadian Client", country: "CA" },
  items: [
    {
      name: "Software License",
      quantity: 1,
      price: 500,
      taxes: [
        { rate: 5 },
        { rate: 7 },
      ],
    },
  ],
});

Canadian Tax Types by Province

Tax	Rate	Provinces
GST	5%	All provinces (federal)
HST	13–15%	ON, NB, NS, NL, PE (replaces GST + PST)
PST	6–7%	BC, SK, MB
QST	9.975%	QC (in addition to GST)

For HST provinces, use a single tax entry instead of separate GST + PST.

Tax Exempt Transactions

For tax-exempt sales, either omit the taxes array on the item or add a tax with rate: 0:

items: [{
  name: "Exempt Service",
  quantity: 1,
  price: 200,
  taxes: [{ name: "Sales Tax", rate: 0 }],
}]

Multi-Tax Support

North American jurisdictions often require multiple taxes per line item (e.g., state + county + city taxes, or GST + PST in Canada).

Multi-tax (US/Canada)typescript

const _invoice = await sdk.invoices.create({
  customer: { name: "US Client", country: "US", state: "CA" },
  items: [
    {
      name: "Software License",
      quantity: 1,
      price: 1000,
      taxes: [
        { rate: 7.25 },
        { rate: 1.0 },
      ],
    },
  ],
});

Each line item can have multiple taxes applied, each calculated and displayed separately on the invoice.