ZATCA Tools for WHMCS: Saudi e-invoicing for hosting companies

How it works

When an invoice in WHMCS is marked paid, the addon sends it to ZATCA Tools. Its lines (hosting, domains, addons, promotional discounts) become a Phase-2 compliant tax invoice: simplified for individuals, standard (B2B) for Saudi companies with a VAT number. We sign it with your establishment's certificate and report it to the Authority within seconds. The e-invoice number, QR code and PDF link appear on the invoice page in the WHMCS admin area, on your client's invoice page, and in the Invoices page of your ZATCA Tools account.

Invoice paid in WHMCS → Signed e-invoice → Reported to ZATCA

Before you start

A ZATCA Tools account connected to Fatoora. Complete the connection in Settings first.
WHMCS 8.0 or newer, PHP 7.4 or newer with cURL.
Client currency Saudi Riyal (SAR). Invoices in other currencies are refused with the reason shown.
A 15% tax rule for Saudi Arabia in WHMCS (Setup, Payments, Tax Rules). Without it your Saudi clients are billed at zero VAT and no e-invoice is issued for them.

Tax in WHMCS. The addon reads the tax rate fixed on the invoice and handles both tax types: Exclusive (VAT added on top of the price) and Inclusive (prices already contain VAT). An invoice for a Saudi client with taxable items and no VAT means a missing tax rule, so the addon stops and explains why on its page instead of reporting a wrong figure to the Authority.

Step 1. Install the addon

Download the .zip and extract it.
Upload the modules/addons/zatcatools folder into modules/addons/ of your WHMCS installation.
In the admin area open Setup, Addon Modules and click Activate next to ZATCA Tools.
Activation creates a table that maps your invoices to their e-invoices, and two client fields for the VAT number and the national short address.

Step 2. Paste your API key

In ZATCA Tools open Settings, API and copy the key (it starts with ztk_live_).
In WHMCS: Setup, Addon Modules, ZATCA Tools, Configure. Paste the key, choose when to issue (on payment is the default and the recommendation), and grant access to your admin roles.
Open Addons, ZATCA Tools: a connection card shows your establishment and remaining plan quota, plus a setup checklist (fields, tax rule, currency).

Step 3. Business clients

Individuals get a simplified tax invoice with no setup. A Saudi company that needs a tax invoice in its name needs two fields on its client profile. The addon creates them on activation and shows them on the order form:

Field	What it does
VAT Number zatca_vat	15 digits, starting and ending with 3. When present, the client receives a standard (B2B) tax invoice. The built-in WHMCS Tax ID field is read as a fallback.
National Short Address zatca_short_address	Eight characters such as RRRD2929. From it we resolve the street, building number, district, city and postal code the Authority requires on a tax invoice.

Step 4. Try one invoice

Create a small invoice for a test client and mark it paid.
Open the invoice in the admin area: a ZATCA e-invoice box shows its status, number and PDF link.
Open the same invoice from the client account: the QR code and the e-invoice download link are there.
If something is off (missing key, incomplete address, non-SAR currency) the exact reason is listed under Addons, ZATCA Tools with a Retry button.

QR code on the PDF that WHMCS generates

The signed e-invoice has its own PDF on ZATCA Tools. To print the QR code and the e-invoice number on the WHMCS invoice PDF as well, paste this block into your template's templates/<your-template>/invoicepdf.tpl before the invoice items table:

$zatcaDocument = \WHMCS\Database\Capsule::table('mod_zatcatools_documents')
    ->where('invoice_id', (int) $invoiceid)->where('kind', 'invoice')
    ->whereIn('status', ['issued', 'warnings'])->orderByDesc('id')->first();

if ($zatcaDocument && ! empty($zatcaDocument->qr_svg)) {
    $pdf->ImageSVG('@'.$zatcaDocument->qr_svg, 160, 12, 32, 32);
    $pdf->SetXY(156, 45);
    $pdf->SetFont($pdfFont ?? 'freesans', '', 7);
    $pdf->Cell(40, 4, 'ZATCA '.$zatcaDocument->number, 0, 1, 'C');
}

The same file ships in the package as snippets/invoicepdf-qr.php. Custom themes also receive {$zatcatools.number}, {$zatcatools.view_url} and {$zatcatools.qr_svg} as template variables on the invoice page.

Details that matter

Never a duplicate. Each WHMCS invoice maps to exactly one document, however often the hook fires, the cron overlaps, or someone clicks "Issue now" after the system already did. An accepted e-invoice cannot be deleted, which makes this the most important property of the addon.
Refunds. A partial refund in WHMCS issues a credit note for the refunded amount with VAT backed out. A full refund or a cancellation issues a credit note for the open balance only, so a partial refund is never credited twice.
Promotional discounts. Negative Promotional Code lines in WHMCS become a document-level discount, and the e-invoice total always matches the WHMCS total. Any difference is written out for you.
Clients outside Saudi Arabia. You choose in the settings how their lines are reported: zero-rated export of services, outside the scope of VAT, or not issued at all.
Invoices that are not sales. Add Funds and Mass Payment invoices are skipped automatically because they are not supplies.
Transient failures. A network outage is retried by the WHMCS cron with increasing backoff. Failures that have a reason (a VAT number without an address, a missing tax rule) wait for you on the addon page and are not retried blindly.
More than one WHMCS installation on one account? Each installation gets its own identifier derived from its system URL, so invoice ids never collide between them.
Logs. Every API call is in Utilities, Logs, Module Log with the key masked; outcomes are in the Activity Log.
Every e-invoice counts against your plan. Track what is left on the connection card of the addon page or in your ZATCA Tools dashboard.

FAQ

When is the e-invoice issued: when the WHMCS invoice is created, or when it is paid?

When it is paid, by default. That is the right moment for a hosting company: the tax point is the payment, and with proforma invoicing the invoice number is final by then. You can switch to "when created" in the addon settings.

My client is a Saudi company and wants a tax invoice in its name. How?

Add its VAT number and national short address in the two client fields the addon creates on activation. From then on it receives a standard (B2B) tax invoice instead of a simplified one, and the full address is resolved from the short address.

What happens on a refund or a cancellation?

Partial refunds, full refunds and cancellations after issue become a credit note tied to the original e-invoice. The open balance is computed on our side, so a partial refund is never credited twice.

Does the addon print the QR on the PDF that WHMCS generates?

Yes, with a snippet you paste into invoicepdf.tpl (the code is on this page). Without it, the QR and the e-invoice link still show on the client invoice page and in the admin area.

Is the addon free?

Yes. The addon is open source and free; each e-invoice counts against your ZATCA Tools plan like any other channel.

Installing for the first time? Contact us and we will run the first invoice with you on a WHMCS staging copy before production.