API Reference

Introduction

The API is JSON over HTTPS. Every call is stateless and scoped to the establishment that owns the key. Amounts are in Saudi Riyal (SAR) with two decimals, dates are YYYY-MM-DD, and timestamps are ISO 8601 in Riyadh time (UTC+3).

A standard invoice (B2B, tax invoice) is sent to the Authority for clearance and comes back stamped; a simplified invoice (B2C) is signed here and reported. Both happen inside the one POST /v1/invoices call, and the response already carries the outcome.

Authentication

Every request carries the establishment's API key as a bearer token. Generate it under Settings → API. The key is shown once, at generation, and it has full authority over the establishment's invoicing — keep it in an environment variable, never in source code or a repository. One key is active per establishment; generating a new one revokes the previous one immediately.

curl https://zatcatools.com/api/v1/account \
  -H "Authorization: Bearer ztk_live_..."

Errors

Every error uses the same envelope. The code is stable and meant for your program; the message is for the human reading the log.

{
  "error": {
    "code": "quota_exceeded",
    "message": "Free-plan invoice quota exhausted. Contact us to upgrade."
  }
}

A 2xx with "status": "rejected" is not an error of the API: the document reached the Authority and was refused. The reasons are in zatca.rejection, and each rule code is explained in the validation code guide.

Idempotency

Pass your own order identifier as external_id (or as an Idempotency-Key header). A repeated request with the same value returns the document that was already issued — 200 instead of 201, same body — and never a duplicate. Retries after a timeout are therefore always safe. Notes are namespaced by kind, so a credit note may reuse the id of the invoice it adjusts.

Rate limits

• 60 requests per minute per key. Beyond that: 429.
• Issuing a document consumes one unit of the establishment's plan. Watch what is left on GET /v1/account.
• Signing and clearance take one to three seconds. Set client timeouts to 30 seconds and rely on idempotency for retries.

The establishment, its ZATCA connection, its branches with their devices, and what is left of the plan.

{
  "name": "مؤسسة النخبة للتجارة",
  "vat_number": "310000000000003",
  "cr_number": "1010101010",
  "address": {
    "street": "طريق الملك فهد", "building_number": "8228", "subdivision": "العليا",
    "city": "الرياض", "postal_zone": "12244", "short_address": "RRRD2929"
  },
  "zatca": { "connected": true, "environment": "production", "certificate_expires_at": "2027-07-01" },
  "branches": [
    { "id": 3, "name": "فرع الملز", "city": "الرياض", "connected": true,
      "devices": [ { "id": 7, "name": "كاشير 1", "status": "connected", "usable": true } ] }
  ],
  "quota": { "used": 12, "limit": 50, "remaining": 38, "unlimited": false }
}

Builds the invoice, signs it and submits it to ZATCA in one call — clearance for a standard invoice, reporting for a simplified one. A standard invoice needs a complete customer; a simplified one does not. Customers are matched by VAT number inside your establishment and created when new.

curl -X POST https://zatcatools.com/api/v1/invoices \
  -H "Authorization: Bearer ztk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "standard",
    "external_id": "SO-2026-1188",
    "customer": {
      "name": "شركة المثال للتجارة",
      "vat_number": "311111111101113",
      "cr_number": "1010101010",
      "short_address": "RRRD2929"
    },
    "lines": [
      { "name": "اشتراك سنوي", "quantity": 1, "unit_price": 1000 }
    ],
    "due_date": "2026-08-18",
    "notes": "السداد خلال 30 يومًا بالتحويل البنكي"
  }'

{
  "type": "simplified",
  "external_id": "order-5501",
  "customer_email": "[email protected]",
  "prices_include_vat": true,
  "branch_id": 3,
  "device_id": 7,
  "lines": [
    { "name": "قهوة مختصة 250غ", "quantity": 2, "unit_price": 55,
      "description": "حبوب إثيوبية — تحميصة فاتحة" },
    { "name": "أدوات تحضير", "quantity": 1, "unit_price": 120,
      "discount": 10, "discount_type": "percent" },
    { "name": "دواء", "quantity": 1, "unit_price": 80,
      "tax_category": "Z", "tax_reason_code": "VATEX-SA-35" }
  ]
}

Parameters

{
  "uuid": "8d9f6e0a-4b7c-4f2e-9a1d-3c5b7e9f1a2b",
  "number": "INV-2026-00042",
  "kind": "invoice",
  "type": "standard",
  "status": "accepted",
  "issue_date": "2026-07-19",
  "created_at": "2026-07-19T09:30:00+03:00",
  "totals": {
    "lines": "1000.00", "discount": "0.00",
    "vat": "150.00", "grand": "1150.00", "currency": "SAR"
  },
  "customer": { "name": "شركة المثال للتجارة", "vat_number": "311111111101113" },
  "lines": [
    { "name": "اشتراك سنوي", "quantity": 1, "unit_price": 1000, "tax_category": "S", "total": 1000 }
  ],
  "due_date": "2026-08-18",
  "notes": "السداد خلال 30 يومًا بالتحويل البنكي",
  "zatca": {
    "channel": "clearance",
    "icv": 42,
    "submitted_at": "2026-07-19T09:30:02+03:00",
    "warnings": []
  },
  "links": {
    "view": "https://zatcatools.com/invoice/{uuid}/{token}",
    "xml": "https://zatcatools.com/api/v1/invoices/{uuid}/xml",
    "pdf": "https://zatcatools.com/api/v1/invoices/{uuid}/pdf",
    "qr":  "https://zatcatools.com/api/v1/invoices/{uuid}/qr.svg"
  }
}

Lines come back as they were sent: a line with a discount also carries discount, discount_type and the resulting net_unit_price; a line with a description carries it; and totals.line_discounts appears when any line was discounted. links.view is the one link to put in front of a person — an order screen, an email — it opens in any browser with no key. The xml, pdf and qr links need the bearer key and are for server-to-server use.

Line items & discounts

Tax categories

Each line carries its own VAT treatment, so one basket can hold a standard-rated item beside zero-rated medicine; the document gets one subtotal per category, as the Authority requires. A zero-rated, exempt or out-of-scope line must say why — ZATCA rejects one without a reason code. Send the code; the official reason text is written into the XML for you.

Prices including VAT

A shelf price in a Saudi shop already includes VAT; an agency quotes before it. With "prices_include_vat": true every amount in the request — line prices and the document discount — is what the customer actually pays, and the net is derived per line at that line's own rate, so a zero-rated line is never "un-taxed" by mistake. The stored, signed document is always net, as the regulation requires: the flag changes what a sent riyal means, never the shape of the invoice. Without it (the default) prices are net and 15% is added on top.

Branches & devices

One VAT number, many outlets. Each branch issues through its own device — ZATCA's own model, the EGS unit: every device is activated with its own OTP from the Fatoora portal (Onboard new solution unit/device; single-use, valid one hour), carries its own certificate and its own invoice chain, so branches issue in parallel. The head office's device is the establishment's main connection. A branch cannot issue until a device of its own is connected; a branch may have several.

An invoice from a branch then names both branch_id and device_id — standard and simplified alike. The point of sale knows its till; the document carries the branch's address and CR and is signed by that device on its own chain. One without the other is refused (device_required / branch_required). The legal name and VAT number always stay the establishment's. Notes follow the branch of the invoice they adjust; device_id on a note is optional. The full list of branches and devices is on GET /v1/account, and they can also be managed under Settings → Establishment.

Newest first, paginated. This is also the polling trigger automation platforms build on: ask for what is newer than the last document you saw.

{
  "data": [ { "uuid": "…", "number": "INV-2026-00042", "kind": "invoice", "status": "accepted", "created_at": "…", … } ],
  "meta": { "page": 1, "per_page": 25, "total": 128, "last_page": 6 }
}

The full document — the same shape as the create response, including the lines, the note or due date if any, zatca.rejection when the Authority refused it, and origin_invoice (uuid, number) on a credit or debit note.

XML · PDF · QR

Every issued document has three downloads, under the same bearer key:

To show a document to a person, use links.view from the invoice object instead: it carries its own per-document token, opens in any browser, and never exposes your key.

Emails the PDF. to is optional and defaults to the account owner's address. Answers { "sent": true, "to": "bu…@example.com" }, or 422 invalid_recipient / 502 send_failed.

A credit note (credit) or a debit note (debit) against an issued invoice named by invoice_uuid. The reason is mandatory (BR-KSA-17). Lines take the same shape as on an invoice — description and discount included — and are priced net: give the price the buyer actually paid. A returned quantity may not exceed the invoice's, and a credit note may not exceed the invoice's open balance after earlier notes (Article 40). The note is issued from the same branch as its invoice.

{
  "kind": "credit",
  "invoice_uuid": "8d9f6e0a-4b7c-4f2e-9a1d-3c5b7e9f1a2b",
  "reason": "إرجاع جزئي للبضاعة",
  "external_id": "return-5501-1",
  "lines": [
    { "name": "أدوات تحضير", "quantity": 1, "unit_price": 120, "discount": 10, "discount_type": "percent" }
  ]
}

The response is the note in the same shape as an invoice, with kind, a CRN- or DBN- number and origin_invoice. Errors: origin_not_found, reason_required, quantity_exceeds_origin, exceeds_open_balance.

Cancel & reinstate

An issued invoice is signed and reported: it is never deleted, it is reversed. Send a credit note with "full": true and no lines, and the open balance after any earlier notes is credited — computed here, so it can never exceed the legal ceiling. An invoice already fully covered answers 422 nothing_to_credit.

To reinstate, send the same request with "kind": "debit" and "full": true: a debit note for exactly what was written off, and the invoice is owed again (422 nothing_to_restore when nothing was). To undo one specific credit note rather than everything ever credited, pass its uuid as reverses instead. Use a different external_id for each cancel/reinstate cycle, or the earlier note is returned.