Tax Exemption Certificates for Magento

Overview

Customers upload a resale or exemption certificate, you approve it for the countries or states and the dates you choose, and Magento stops charging tax to that customer where the certificate applies. The exemption ends by itself on the expiry date, and every order keeps the certificate it was placed under.

Tested on Magento Open Source 2.4.8-p5 with PHP 8.3, self-hosted. Not for SaaS editions that cannot run PHP modules.

What it does

• Customers submit a certificate in My Account (type, number, name, countries or states covered, expiry date, PDF or image). A notice in the cart shows the state: applied, waiting for review, or a link to submit one.
• You review the queue in Customers > Tax Exemption Certificates: approve for chosen jurisdictions and dates, reject with a reason, revoke, change terms, open the documents.
• Tax is removed by Magento's own tax engine: a customer under a valid certificate is calculated with a customer tax class that has no tax rule (the module creates "Tax exempt (certificate)"). Catalog prices, cart, checkout, shipping and admin order creation all follow, and nothing is written to the customer record.
• Every order keeps the reference (number, type, scope, destination) on the order page in the admin and in the customer's account, and the audit log of the certificate lists the orders.
• Records: audit log of every step, documents in protected storage, documents and rows deleted with the customer, optional retention, an REST API for ERP and accounting systems.

What it does not do

• It is a record keeping and workflow tool, not tax advice: you decide which certificates are valid.
• It removes all taxes of the order for a covered destination (Magento tax classes cannot exempt one tax only).
• Guests cannot be exempt: a certificate belongs to a customer account.
• It sends no e-mail. It raises Magento events and admin inbox notices; see the FAQ.

Installation

1. Download the zip from your Kavio Labs account (My licences > Downloads).
2. Extract it into app/code/KavioLabs/TaxExemptCertificates/ (the folder then contains registration.php and etc/).
3. Run:
   • bin/magento module:enable KavioLabs_TaxExemptCertificates
   • bin/magento setup:upgrade
   • in production mode also bin/magento setup:di:compile and bin/magento setup:static-content:deploy
4. Open Stores > Configuration > Kavio Labs > Tax Exemption Certificates and enter your licence key.

The zip is also a Composer package (kaviolabs/module-tax-exempt-certificates, composer.json at the root), so a Composer artifact repository can install it as well.

setup:upgrade creates four tables (kv_tax_exempt_certificates_*) and the customer tax class "Tax exempt (certificate)", and selects it in the settings. Documents are stored in var/kv_tax_exempt_certificates/, outside the public pub/ folder.

Check the tax rules once

The exempt class works because no tax rule names it. Open Stores > Tax Rules and make sure no rule lists "Tax exempt (certificate)" under Customer Tax Class. Rules you create later must not select it either.

If your catalog prices include tax, leave Stores > Configuration > Sales > Tax > Calculation Settings > Enable Cross Border Trade on No (the default). With it on, Magento keeps the gross price for customers whose rate differs from the store rate, so an exempt customer would still pay the gross price.

Update

Replace the folder with the new version and run bin/magento setup:upgrade (plus setup:di:compile and setup:static-content:deploy in production mode). Certificates, documents and settings stay.

Uninstall

• Keep the data: bin/magento module:disable KavioLabs_TaxExemptCertificates, delete the folder and run bin/magento setup:upgrade. Certificates, documents and settings stay for a later reinstall.
• Remove everything (the four tables, the documents in var/kv_tax_exempt_certificates/, the settings, the licence state, and the tax class if the module created it and nothing uses it): bin/magento module:uninstall KavioLabs_TaxExemptCertificates --non-composer first, then module:disable, delete the folder and run setup:upgrade. For a Composer install use bin/magento module:uninstall KavioLabs_TaxExemptCertificates --remove-data.

Export what you need through the REST API before removing the data: orders keep their tax figures, but the certificates themselves are gone.

Configuration

Stores > Configuration > Kavio Labs > Tax Exemption Certificates (default scope).

Licence

Licence key and status. The module works for a 14-day start period without a key. Without an active licence no tax is removed (certificates, the queue and the settings stay available).

General

Certificates

Permissions

Stores > Settings > Permissions > User Roles: Customers > Tax Exemption Certificates lets a role read the queue, documents and the REST list; Approve, reject, revoke and delete certificates lets it decide. The settings have their own resource under Stores > Settings > Configuration.

Which address decides

The jurisdiction of a certificate is compared with the place Magento calculates the tax for: Stores > Configuration > Sales > Tax > Tax Calculation Based On (shipping address by default; with "Shipping Origin" the store origin decides). The order record and the cart notice use the same choice, so they always agree with the tax that was charged.

Warnings

The queue and certificate pages warn when a tax rule names the exempt customer tax class, or when Cross Border Trade is on while prices include tax. Both stop the exemption from working. A customer can have at most 5 certificates pending review.

Dates

An approval "valid until" a day ends at midnight of the store's time zone (Stores > Configuration > General > Locale Options), not of the server. A date that cannot be read, lies in the past or ends before it starts is refused, never saved as "no expiry".

Using it

Customers

My Account > Tax exemption certificates lists the customer's certificates with their status and documents, and has the form: type, number, name on the certificate, countries or states covered (DE, US-CA, US-NY), expiry date, file, note. A pending or rejected certificate can be withdrawn; an approved one can only be ended by the store.

In the cart a notice shows whether the certificate applies to the address the tax is calculated for.

Reviewing

Customers > Tax Exemption Certificates shows tabs with counts (Pending, Approved, Expiring soon, Expired, Rejected, Revoked, All) and a search over number, name, customer name and e-mail.

Open a certificate to see the customer, the documents (downloads are attachments, never served by the web server), the orders that used it and the full history. Then:

• Approve: confirm the jurisdictions (US-CA, DE, or * for everywhere) and the dates. The customer's requested scope and expiry are filled in.
• Reject: a reason is required and shown to the customer.
• Change terms of an approved certificate: scope and dates.
• Revoke: the exemption ends with the next tax calculation.
• Delete documents keeps the record; Delete certificate removes it and its files but keeps its audit log with a "deleted" entry.

What happens to tax

While an approved certificate is valid today and covers the address Magento calculates the tax for, the customer is calculated with the exempt class: product prices, the cart, shipping and the order have no tax. Outside the places, before the start date, after the end date, after a revoke, with the module off or without an active licence, tax is charged again at the next calculation. Orders already placed are never changed.

Orders

The order page in the admin shows "Tax exempt (certificate)" with number, type, scope and destination and a link to the certificate; the customer sees it on the order page in My Account. The reference is stored with the order, so it stays after the certificate is revoked, expired or deleted.

REST API

Admin or integration token; ACL as above. Base /rest/V1/kv-tax-exempt/certificates:

• GET ?status=pending&customerId=5&search=&page=1&limit=50, GET /:id
• POST (customerId, type, number, scope, holderName, expiresAt, note, documentNames[], documentsBase64[])
• POST /:id/approve (scope, validFrom, validUntil), /reject (reason), /revoke (reason), DELETE /:id

Unreadable, past or inconsistent dates answer 400 and change nothing.

FAQ

How is tax removed?

Magento builds a tax "rate request" (destination and customer tax class) for every calculation. For a customer with a valid certificate covering the destination, the module swaps the customer tax class for a class that no tax rule names, so Magento finds no rate. It is the same effect as any customer class without a rule, and it works for catalog prices, cart, checkout, shipping and admin orders. Nothing is written to the customer.

Does it work when catalog prices include tax?

Yes, with Cross Border Trade off (the default): the exempt customer is charged the net price. With Cross Border Trade on, Magento keeps the gross price for customers whose rate differs, which defeats an exemption. See Installation.

Is the full page cache a problem?

Pages and price blocks shown to a customer under a certificate are cached separately from those of the other customers of the group: a fingerprint of the valid certificates (and whether one covers the customer's default tax address) is added to the HTTP context, to the price box cache key and to the CMS products list widget key, like Magento's own tax rates. Customers without a certificate keep the normal cache keys.

Which address decides?

The place Magento itself calculates the tax for (Tax Calculation Based On: the shipping address by default, the billing address, the store's shipping origin, or the default tax destination). A tax configured on the billing address is also removed when the shipping address is covered and shipping is the basis. With a multi-address checkout each order is decided, and recorded, for its own address.

What about fixed product tax (FPT / Weee)?

Fixed product tax amounts are location based, not a tax rate, so they stay; the tax on a taxable FPT amount is removed like any other tax.

Can a guest be exempt?

No. The customer signs in, submits a certificate, and is exempt once it is approved.

Does it send e-mails?

No. It never sends e-mail. It dispatches Magento events (kv_tax_exempt_certificates_certificate_submitted, _approved, _rejected, _revoked, _expiring) that your own observers or an ERP can use, and it adds notices to the admin inbox for new submissions and for certificates entering the "expiring soon" window.

Where are the files?

In var/kv_tax_exempt_certificates/, outside the public folder, under random names without extension. They are served only through the module's controllers: a customer gets their own documents, an admin needs the permission. Downloads are attachments with nosniff and a sandboxing content security policy. Uploads are checked for type, size, real file content and embedded code.

What happens when I delete a customer?

The customer's certificates, documents (files) and log rows are deleted. Orders keep the certificate number.

What if the licence lapses?

Tax is charged again, because the module no longer removes it. The queue, the documents and the settings stay available.

Does it work with multiple websites?

Certificates belong to the customer account and apply on every website that shares the customer; the settings are in the default scope.

Is this tax or legal advice?

No. It keeps records and applies the rules you approve; you decide which certificates are valid.