Integrate Clix with your systems

{
  "device": "<device_id from GET /api/devices/>",
  "seller": "<seller_id from the same device>",
  "buyer": "<buyer uuid from GET /api/buyers/>",
  "issue_date": "2026-09-10",
  "issue_time": "12:00:00",
  "type_code": 388,
  "transaction_code": "0100000",
  "currency": "SAR",
  "supply_date": "2026-09-10",
  "supply_end_date": "2026-09-10",
  "payment_means_type_code": "10",
  "notes": [{ "language_id": "en", "note": "Order 1042" }],
  "lines": [{ "item_id": "<item uuid from GET /api/items/>", "quantity": 2 }],
  "form_lines": [],
  "prepaid_invoices": [],
  "document_level_allowances": [],
  "original_invoice_reference": [],
  "exchange_rate": 1,
  "add_prepaid_amount": false
}

# pip install requests
import os
import time

import requests

BASE = os.environ["CLIX_BASE_URL"]  # the "Servers" URL at the top of the API reference, ends in /v1
api = requests.Session()
api.headers["Authorization"] = f"Bearer {os.environ['CLIX_API_KEY']}"

# 1. The device you sign with, and its seller id
device = api.get(f"{BASE}/api/devices/", params={"page_size": 1}).json()["devices"][0]

# 2. The client and the item, prepared once in the Clix app
buyers = api.get(f"{BASE}/api/buyers/", params={"page_size": 100}).json()["buyers"]
items = api.get(f"{BASE}/api/items/", params={"page_size": 100}).json()["items"]
buyer = next(b for b in buyers if b["buyer_name"] == "Acme Trading")
item = next(i for i in items if i["item_name"] == "Consulting hour")

today = time.strftime("%Y-%m-%d")
invoice = {
    "device": device["device_id"],
    "seller": device["seller_id"],
    "buyer": buyer["uuid"],
    "issue_date": today,
    "issue_time": time.strftime("%H:%M:%S"),
    "type_code": 388,  # standard tax invoice
    "transaction_code": "0100000",  # standard B2B
    "currency": "SAR",
    "supply_date": today,
    "supply_end_date": today,
    "notes": [{"language_id": "en", "note": "Order 1042"}],
    "lines": [{"item_id": item["uuid"], "quantity": 2}],
    "form_lines": [],
    "prepaid_invoices": [],
    "document_level_allowances": [],
    "exchange_rate": 1,
    "original_invoice_reference": [],
    "payment_means_type_code": "10",  # cash
    "add_prepaid_amount": False,
}

# 3. Preview: totals and validation errors, nothing stored
preview = api.post(f"{BASE}/api/invoices/preview/", json=invoice)
preview.raise_for_status()
print("payable:", preview.json()["invoice"]["invoice_payable_amount"])

# 4. Create: 202 Accepted - signed and sent to ZATCA in the background.
#    A 400 here means an invoice with the same data was created in the last
#    five minutes; do not retry blindly.
created = api.post(f"{BASE}/api/invoices/", json=invoice)
created.raise_for_status()
location = created.json()["location"]  # "/api/invoices/<uuid>/"

# 5. Poll until ZATCA has answered AND the PDF is stored (usually a few
#    seconds). The status turns CLEARED first; invoice_pdf_url follows shortly
#    after, and /pdf-a3/ answers 404 until it does.
FINAL = ("CLEARED", "REPORTED", "REJECTED")
for _ in range(30):
    result = api.get(f"{BASE}{location}").json()
    status = result.get("zatca_response_status")
    if status == "REJECTED" or (status in FINAL and result.get("invoice_pdf_url")):
        break
    time.sleep(2)
else:
    # Still pending after a minute: the invoice exists, keep polling the location later.
    raise SystemExit(f"ZATCA has not answered yet for {location}")
print(status, result["ref_num"])
if status == "REJECTED":
    # Review why in the Clix app (Invoices -> Rejected), fix the data, and create a new invoice.
    raise SystemExit(f"rejected: {result.get('zatca_response_code')}")

# 6. The PDF/A-3 with the embedded XML, for your customer
pdf = api.get(f"{BASE}{location}pdf-a3/")
pdf.raise_for_status()
with open(f"{result['ref_num']}.pdf", "wb") as f:
    f.write(pdf.content)