Clix as your e-invoicing middleware

Your system already knows what it sold and to whom. ZATCA's Phase 2 asks for much more than that: a UBL 2.1 XML document, a cryptographic stamp from a registered unit, a QR code, a hash chain linking every invoice to the one before, and a live exchange with ZATCA before a business invoice is valid. Clix does all of that behind one REST call.

Clix is listed as a Phase Two solution in ZATCA's E-Invoicing Solution Providers Directory. See Clix and ZATCA compliance.

The picture

Your system sends the commercial facts in JSON. Clix returns the legal facts: the ZATCA status, ZATCA's messages, and the PDF with the signed XML inside.

What you would otherwise build

Each row is a ZATCA Phase 2 requirement that your own systems would have to meet if they talked to ZATCA directly.

ZATCA requirement	Built into each of your systems	With Clix
Register every invoicing unit with ZATCA and hold its certificate (CSID), renewing it before expiry	One onboarding and one certificate per system, with the private key kept safe	Done once per ZATCA connection in the Clix app
Produce the e-invoice as UBL 2.1 XML to ZATCA's standard	An XML builder that follows every ZATCA rule	You send JSON
Stamp, sign and add the QR code	Cryptography code and key handling	Clix signs with the connection's certificate
Chain every invoice to the one before (UUID, counter, previous hash)	Strict sequencing, even across retries and restarts	Clix keeps the chain
Clear standard invoices before they are valid; report simplified ones within 24 hours	Two ZATCA APIs, their responses and error codes	One create call; you poll one status
Keep working when ZATCA is slow or down	A queue and retry logic	Clix queues and retries
Give the buyer a PDF with the XML inside	A PDF generator that embeds the XML	GET …/pdf-a3/
Keep records for at least six years, in the Kingdom	Storage and retention	Clix stores them in Jeddah
Follow new versions of ZATCA's standards	Change and retest every system	Changed once, in Clix

Several systems, one Clix organisation

A business often invoices from more than one place: an ERP for contracts, tills in each branch, a web store. Each connects to the same Clix organisation with its own API key, and each invoice names the ZATCA connection it is issued from.

• One key per system. Revoke one without stopping the others. See Authentication.
• One or more ZATCA connections. A connection can be business-level or tied to a branch, whose address then appears on its invoices. Each invoice sends its connection's device id.
• One record. All invoices land in one organisation, so the VAT report, payments and reconciliation see everything.

Ways to issue invoices

Way	Best for
The REST API	Systems that already hold the sale: ERP, point of sale, e-commerce, billing
The Clix web app	Teams that invoice by hand, and for checking, correcting and sharing what the API issued

Both write to the same organisation. Clix does not import sales invoices from files, and offers no ready-made ERP plug-ins; connect through the API.

Who does what

Task	Your system	Clix	ZATCA
Decide what was sold, to whom, at what price	✓
Keep clients (and, optionally, items) in Clix	✓ via the API	stores them
Check the invoice against ZATCA's business rules		✓ on preview and on create	checks again
Work out line totals, VAT, rounding		✓
Number the invoice, chain it to the previous one (UUID, counter, hash)		✓	verifies
Build the UBL 2.1 XML		✓
Hold the ZATCA certificate and stamp the invoice		✓ per ZATCA connection	issues the certificate
Clear standard invoices before they are valid		✓ sends	✓ clears
Report simplified invoices within 24 hours		✓ sends straight away	✓ receives
Produce the invoice PDF with the XML embedded		✓
Keep the record for the retention period, in the Kingdom		✓
Store Clix's invoice id, issue date and status	✓
Correct an issued invoice	✓ asks for a credit or debit note	✓ issues it	clears or receives it

A standard invoice, end to end

A business-to-business invoice is not valid until ZATCA clears it. Your system does not wait on ZATCA directly: it gets 202 Accepted at once and polls.

sequenceDiagram
    participant ERP as Your ERP
    participant C as Clix API
    participant Z as ZATCA
    ERP->>C: POST /api/invoices/preview/
    C-->>ERP: 201 totals, or 400 with the first broken rule
    ERP->>C: POST /api/invoices/
    C-->>ERP: 202 Accepted + location
    C->>Z: signed XML for clearance
    Z-->>C: Cleared, Cleared with warnings, or Rejected
    loop every 1–2 seconds
        ERP->>C: GET location
        C-->>ERP: zatca_response_status
    end
    ERP->>C: GET …/pdf-a3/
    C-->>ERP: PDF with the cleared XML embedded

Steps, payloads and responses: Quickstart. A full recorded run: Worked example.

A simplified invoice

A business-to-consumer invoice is valid when issued; ZATCA is told afterwards. Clix reports it straight after creation, well inside ZATCA's 24 hours.

sequenceDiagram
    participant POS as Your point of sale
    participant C as Clix API
    participant Z as ZATCA
    POS->>C: POST /api/invoices/ (transaction_code 0200000)
    C-->>POS: 202 Accepted + location
    C->>Z: signed XML for reporting
    Z-->>C: Reported, or Not reported
    POS->>C: GET location
    C-->>POS: REPORTED
    POS->>C: GET …/pdf-a3/
    C-->>POS: PDF with QR code

A till must reach Clix to issue

Clix is the unit ZATCA registered, so an invoice exists only once Clix creates it. A point of sale that cannot reach Clix cannot issue a valid invoice until it reconnects. See Why you cannot choose the issue date.

The life of an invoice

• A cleared or reported invoice is final. Corrections are credit or debit notes: POST /api/invoices/ with type_code 381 or 383, original_invoice_reference and reason_id. See Codes → reason_id.
• A rejected invoice is never resubmitted. Create a corrected one.
• Status values and where ZATCA's messages are: Codes → zatca_response_status.

Handling every answer

The full list, with bodies: Errors. Rate limits and the monthly allowance: Usage.

Going live

1. API access comes with the Business plan. See Plans.
2. A ZATCA connection must be Active (device_status pcsid_generated). See Connect to ZATCA.
3. One API key per system that calls Clix, so you can revoke one without stopping the others. See Authentication.
4. Codes: VAT categories, exemption reasons, units, payment means. See Reference data.
5. Clients: create each buyer once with POST /api/onboarding/organizations/clients/ and keep the uuid. The invoice refers to the buyer by uuid. See The buyer is an ID.
6. Lines: send them in full with form_lines, or bill catalogue items with lines. See Two ways to send lines.
7. Preview each scenario you will send: standard, simplified, export, credit note, debit note, foreign currency.
8. In production, store Clix's invoice uuid, issue_date, issue_time and final status against your own record.

Try it

• Swagger UI at https://sandbox.api.goclix.ai/v1/api/integrations/docs lists every call a key can make; Authorize with your key and try them. The OpenAPI document is next to it. See API reference.
• Postman: import the same OpenAPI document. See Postman.
• Without a key: the public tools calculate VAT, decode a QR code and run ZATCA's rules on an invoice.

Related

• Quickstart — the first invoice, step by step
• Worked example — a recorded run with real responses
• API reference · Codes · Errors · Usage
• ZATCA e-invoicing in Clix · Invoice types