Add Canada specific regions VAT rates (ETA May 11)

[nicomollet]

Is your feature request related to a problem? Please describe.
Sub-issue of:

• https://github.com/wp-media/monies/issues/201

🐴 Epic card

Describe the solution you'd like
Pyvat handles postal codes since v1.0.2 (Spain regions).
Pyvat is capable of handling non-EU countries (see Egypt).

Make Pyvat handle VAT rates for regions of Canada using their postal codes.
The first letter of the postal code indicates the province/territory.

Explicit what happens for Canadians without a postal code (see Fallback section below).
Then update Monies and update automated tests.

---

Tax Rates by Province

📑 Canada - tax rates by province (Dec 2025)

Use the Total Tax column. Rates range from 5% to 15%.

⚠️ Registration constraint: We can only charge the provincial tax (PST/QST/RST) where we are registered. Where we are NOT registered, charge only the federal GST (5%). This means some provinces may currently be charged at 5% (GST only) even if the table shows a higher total rate. Tax values must be easy to update as new provincial registrations are finalized.

Prefix	Province/Territory	Total Tax (when registered)	Notes	Example Postal Code
(none)	No postal code	13%	Fallback: Ontario rate	N/A
A	Newfoundland and Labrador	15%	HST	A1A 5T9
B	Nova Scotia	14%	HST	B3H 1Y2
C	Prince Edward Island	15%	HST	C1A 4P3
E	New Brunswick	15%	HST	E2L 4H8
G	Quebec	14.975%	GST + QST — not currently registered → charge 5%	G1A 0A2
H	Quebec	14.975%	GST + QST — not currently registered → charge 5%	H1A 0A1
J	Quebec	14.975%	GST + QST — not currently registered → charge 5%	J1A 1A1
K	Ontario	13%	HST	K1A 0B1
L	Ontario	13%	HST	L5B 4M7
M	Ontario	13%	HST	M5V 3L9
N	Ontario	13%	HST	N2L 3G1
P	Ontario	13%	HST	P7B 5E1
R	Manitoba	12%	GST + RST — not currently registered → charge 5%	R2C 0A1
S	Saskatchewan	11%	GST + PST (registered)	S7K 1A1
T	Alberta	5%	GST only	T5J 0N3
V	British Columbia	12%	GST + PST (registered)	V6B 4N6
X	Northwest Territories / Nunavut	5%	GST only	X0A 0H0
Y	Yukon	5%	GST only	Y1A 0A1

---

Registration Numbers

These must appear in the free text section of Canadian invoices:

• Federal GST/HST: 77733 7361 RT0001
• British Columbia PST: 77733 7361 BT0001
• Saskatchewan PST: Account #8158362 — Business #777337361

Print all relevant registration numbers for the province of the invoice. Display them even if it means printing all of them, unless we can determine which ones are applicable.

---

Invoice Free Text Requirements

For all Canadian invoices, the free text section must include:

1. The applicable PST rate % and GST rate % separately (their sum = total tax rate on the invoice).
2. All applicable registration numbers (see above).
3. For customers without a postal code: a sentence encouraging them to add their address in their account dashboard, e.g.:

   "Your tax rate is based on the Ontario default. To ensure accurate tax calculation, please update your address in your account dashboard."

---

B2B Handling

• No VAT exemption for B2B: Canadian B2B customers are subject to the same tax as B2C.
• VAT/GST numbers may be collected but have no effect on pricing or tax application.

---

Fallback for Missing Postal Code

• If a customer has no postal code → apply Ontario rate (13%) as default.
• This fallback must be configurable.
• For renewals of customers without a postal code: apply the fallback rate and include the free text notice (see above).

⚠️ Quebec and Manitoba rates pending finance team confirmation — charge GST-only (5%) in the meantime.

---

Monitoring

• Metabase: track Canadian invoices — none should have 0% VAT after this is live.
  • Based on Datator > Matpe Invoice
• Track how many existing customers update their address/postal code after launch, to evaluate invoicing accuracy over time.
  • Based on Datator > Monies Customer
• Klaviyo: check Canada segment, and observe Renewal Discount/Regular Price property are updated (meaning no Canada customer should pay Single $59 but a little less)

Create a Canada folder in https://data.wp-media.me/collection/69-vat

---

Tasks

• Stripe configuration for RocketCDN — needs Canadian tax details (Quebec & Manitoba currently showing only 5% GST due to missing provincial registrations)
• Invoices: display PST/GST registration numbers + rate breakdown in free text
• Invoices: add "please add your address" sentence for customers without postal code
• Adapt Canada-specific rates in Pyvat library (rate table above, with registration constraint)
• Handle fallback to Ontario (13%) for customers without postal code — make it configurable
• Automatic renewals: apply fallback rate for customers without postal code
• No B2B exemption: ensure VAT number collection has no impact on tax rate
• Test Imagify staging order/invoice subtotal consistency
• Test RocketCDN staging order/invoice subtotal consistency
• Monitoring: Metabase dashboard for Canadian invoices (should not have 0% VAT)
• Monitoring: track address completion rate post-launch
• Deploy on staging, QA all apps

Release

• Wait green signal from Mathieu
• Pyvat merge Add Canada VAT rules with province-specific rates #10 and create release version
• Monies update https://github.com/wp-media/monies/pull/352 to use new Pyvat version
• WPR Release https://github.com/wp-media/wp-rocket.me/issues/5716
• RocketCDN: Stripe live mode, configure tax registrations
• Update doc VAT-Tax-rates-Exemption-for-all-countries
• Force update Klaviyo users (renewal prices) with /_scripts/script-klaviyo-user-force-update.php?country=CA
• Monitor (created queries for alerts and graphs)

---

Describe alternatives you've considered
N/A

[nicomollet]

I fear that Facturation doesn't handle that kind of decimals for VAT
Example with 14.975%

curl --location 'https://www.facturation.pro/firms/68456/invoices.json' \
--header 'Content-Type: application/json' \
--header 'charset: utf-8' \
--header 'Authorization: ••••••' \
--header 'Cookie: AWSELB=6D375FE70A5474BC11D270DC598145472115DD116DCA1FDECA62B59CF59FBD3889F8D72A42AF4B4C15AC4378ACFF1308F4C332763D1146F876ACCECD02F11034333C28B527; AWSELBCORS=6D375FE70A5474BC11D270DC598145472115DD116DCA1FDECA62B59CF59FBD3889F8D72A42AF4B4C15AC4378ACFF1308F4C332763D1146F876ACCECD02F11034333C28B527' \
--data '{
    "title": "WP Rocket",
    "currency": "USD",
    "accounting_entry": "706130",
    "language": "en",
    "payment_mode": 2,
    "category_id": 32424,
    "invoiced_on": "2025-11-19",
    "paid_on": "2025-11-19",
    "customer_id": 3722373,
    "vat_exemption": null,
    "vat_country": "CA",
    "items": [
        {
            "quantity": "1.0",
            "measure": null,
            "title": "Single",
            "unit_price": 49.3,
            "vat": 0.14975,
            "product_id": null,
            "position": 1,
            "optional": false,
            "style": null,
            "nature": 9,
            "sap_nature": null
        }
    ]
}'

[nicomollet]

Next steps for this issue, it is currently blocked until we know the Canadian VAT rates.

• Once we get Canadian VAT rates and GTmetrix is ready: update Pyvat and create a version
• Deploy Monies on staging, QA all apps on staging

[MathieuLamiot]

Canada - indirect tax rates by province_2025-12.xlsx

Here are the tax rates that we will apply for Canada. The "Total tax" is the value to be used.

[nicomollet]

Current status for Canada:

• Prices:
  • RocketCDN and Imagify: 0% VAT all customers
  • WP Rocket: the "fake VAT" is in place, Single is $59
• B2B:
  • Exemption: no VAT exemption for B2B
  • Validation: we collect VAT numbers without validation, without consequence on pricing
• Invoices:
  • VAT number appears on the invoice
  • No "mention"

What would happen:

• Prices:
  • Imagify: standard price + province tax
  • RocketCDN: standard price + province tax: ⚠️ Stripe configuration for RocketCDN, needs tax details
  • WP Rocket: remove "fake VAT" for Canada, Single is $49.17+14% for Nova Scotia
  • Price depends on postal code and related tax
  • Renewals: ⚠️ what to do with (automatic) renewals of customer that didn't put their postal code?
• B2B:
  • Exemption: no VAT exemption for B2B
  • Validation: we collect VAT numbers without validation, without consequence on pricing
• Invoices:
  • VAT number appears on the invoice
  • No "mention" ⚠️ to be confirmed, we might need to display our RST/PST/QST/GST/HST registration numbers

Stripe tax configuration for RocketCDN:

Questions asked there

[MathieuLamiot]

@piotrbak, @nicomollet we received some additional information to unlock this:

• In the "free text" part of the invoice, for Canadian invoices, we should add:
  • The PST / GST registration numbers. We can start by printing all our Canadian PST/GST numbers if it fits. Otherwise, only write those that are relevant for the invoice.
  • The applied PST rate and GST rate in %. The sum of both should be the applied tax rate on the invoice.
• For users renewing without a region, we should fall back to a fallback state and apply the taxes of that state for invoice generation. I'll get which state soon, to make configurable.
• For users renewing with a region, add a sentence in the free text to ask them to fill their address in the account dashboard.
• We must have data about how many existing customers set their address details after we start this process, to monitor & evaluate the accuracy of our invoicing.

I'll get the list of PST/GST numbers and states where we are registered shortly.

@piotrbak, @nicomollet can you look into prioritizing this along with EUR billing? Thanks

[MathieuLamiot]

New info:

Fallback state is confirmed to be Ontario for tax value computation.
We should charge all taxes for all states according to this file: https://github.com/user-attachments/files/25385690/Canada.-.indirect.tax.rates.by.province_2025-12.xlsx

Remaining info to get:
PST/GST numbers to display in the free text section to be shared soon

[MathieuLamiot]

Registration numbers:

• Federal GST/HST Registration: 77733 7361 RT0001
• British Columbia (PST Registration): 77733 7361 BT0001
• Saskatchewan (PST Registration): Account number 8158362 - Business number 777337361

[MathieuLamiot]

@piotrbak, @nicomollet Will this be done this sprint? Otherwise, can you share an ETA?

[nicomollet]

Klaviyo flow would be ready on April 16 (@marija-nikolic info)

In the meantime, @wp-media/engineering-wpr-addons-team can work on this issue (to be confirmed)

[nicomollet]

@MathieuLamiot Canada registrations are still not OK with Stripe.

It seems our Canada registrations are incomplete for 2 regions: Quebec & Manitoba.

⛔ Stripe RocketCDN with Quebec (postal code G1A 1A3) returns 5% while expectation is 14,975%

⛔ Stripe RocketCDN with Manitoba (postal code R3C 0V8) returns 5% while expectation is 14,975%

RocketCDN test mode Stripe tax locations for Canada:
https://dashboard.stripe.com/acct_14YBo0J5Wooyjvfz/test/tax/locations?region[ca]=true
shows issues with Quebec and Manitoba, I am supposed to fill some registrations numbers in there...

[MathieuLamiot]

We are not registered in Quebec nor Manitoba @nicomollet so we can't collect tax from there I believe 🤔