ZATCA e-invoicing for Shopify
Shopify (online store) tells you when an order is paid; Matheel turns that payment into a ZATCA invoice, filed and accepted, with a bilingual PDF and the QR.
The event to listen to
orders/paid (GraphQL enum ORDERS_PAID): 'Occurs whenever an order is paid.' Needs read_orders scope
Registering it
App config shopify.app.toml: [[webhooks.subscriptions]] topics = ["orders/paid"], uri = "https://your-app.example.com/webhooks/orders-paid" (under [webhooks] api_version), then deploy the app
Checking it came from Shopify
Header X-Shopify-Hmac-SHA256 = base64 HMAC-SHA256 of the raw request body, keyed with the app's client secret; compare with timingSafeEqual
Amount and lines
- Amount:
total_price, total_tax, current_total_price; line_items[].price (unit price before discounts, shop currency), line_items[].discount_allocations[].amount - Lines:
line_items[].name (variant name) / line_items[].title (product title), line_items[].quantity - Customer email:
email (also contact_email)
If the amount includes VAT (it usually does), send it as is with "prices_include_vat": true.
The code
It receives the event, verifies it and calls matheel_invoice(items): the ready function that locks the device row, files the invoice and saves the new token.
import express from "express";
import crypto from "node:crypto";
const app = express();
// Shopify signs the raw body, so keep it as a Buffer.
app.post("/webhooks/orders-paid", express.raw({ type: "*/*" }), async (req, res) => {
const hmac = Buffer.from(req.get("X-Shopify-Hmac-Sha256") || "", "base64");
const mine = crypto.createHmac("sha256", process.env.SHOPIFY_CLIENT_SECRET).update(req.body).digest();
if (hmac.length !== mine.length || !crypto.timingSafeEqual(hmac, mine)) return res.sendStatus(401);
res.sendStatus(200); // answer fast, then file
const order = JSON.parse(req.body.toString("utf8"));
const items = order.line_items.map((li) => {
const discount = li.discount_allocations.reduce((s, d) => s + Number(d.amount), 0);
const unit = Number(li.price) - discount / li.quantity;
const net = order.taxes_included ? unit / 1.15 : unit; // price must be before VAT
return { name: li.name, quantity: String(li.quantity), price: net.toFixed(2) };
});
await matheel_invoice(items);
});
app.listen(3000);
Notes
taxes_included is in the orders/paid sample payload, but the pages read did not define it in words; the code assumes true means line prices include VAT. Shopify recommends discount_allocations over line_items[].total_discount, which is only set for draft orders, scripts or the API. Shipping is in shipping_lines, not line_items. The 1.15 divisor assumes 15% VAT on every line. Shopify's own example compares base64 strings with timingSafeEqual; the sketch compares the decoded bytes and checks the length first, because timingSafeEqual throws on unequal lengths.
FAQ
Does Shopify file invoices with ZATCA by itself?
Shopify is a online store. It reaches ZATCA through a service like Matheel: each successful payment becomes an invoice filed with ZATCA.
Do I have to change my prices for VAT?
No. Send the amount the customer paid with "prices_include_vat": true; Matheel backs the VAT out and keeps the amount due equal to what was paid.
What if two payments arrive in the same second?
A device's invoices go one after another. Lock the device row while filing (the ready function does), and Matheel refuses a stale device token with 409 so the chain never forks.