ZATCA e-invoicing for Shopify

By Matheel · Updated

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

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.

Official sources: shopify.dev/docs/api/admin-graphql/latest/enums/WebhookSubsc · shopify.dev/docs/api/webhooks/latest?reference=toml · shopify.dev/docs/apps/build/webhooks/subscribe · shopify.dev/docs/apps/build/webhooks/subscribe/https · shopify.dev/docs/api/admin-rest/latest/resources/order

Try it now on the developer sandbox

No key, no signup: a real ZATCA answer, with the bilingual PDF and the QR.

Start Pricing