API reference¶

The spec is the authority¶

https://<your-gateway-host>/v1/api/integrations/docs           Swagger UI, with Authorize for a clix_ key
https://<your-gateway-host>/v1/api/integrations/openapi.json   the OpenAPI 3 document

Both are public — no key needed to read them — and both are generated from the running code, so they cannot drift from what the API actually does. Point your client generator at the JSON; use Swagger UI to try any call with your own key. The gateway host comes with your key.

Every request and response body of a complete run, captured on the sandbox, is on Worked example, key to cleared invoice; each endpoint below links to its step there.

This page lists the same surface in prose. Where the two disagree, the spec is right.

What a key can call¶

21 paths, 27 operations. The Role column is the least privilege that works.

Invoices¶

Method	Path	Role	Live example
`GET`	`/api/invoices/`	ViewInvoice
`POST`	`/api/invoices/`	CreateInvoice	example
`POST`	`/api/invoices/preview/`	ViewInvoice	example
`GET`	`/api/invoices/{invoice_id}/`	ViewInvoice	example
`PATCH`	`/api/invoices/{invoice_id}/clearance-reporting/`	CreateInvoice
`GET`	`/api/invoices/{invoice_id}/pdf-a3/`	ViewInvoice	example
`POST`	`/api/invoices/{invoice_id}/pdf-a3/`	ViewInvoice

PATCH …/clearance-reporting/ retries the ZATCA submission of an invoice that has no ZATCA answer yet, for example after POST /api/invoices/ replied that the submission to ZATCA failed. It returns 202 and a location to poll. An invoice ZATCA has already answered, or one whose retry is still in flight, gets 409. It does not change the invoice: to correct an issued invoice, issue a credit or debit note.

Notes on an invoice¶

Method	Path	Role	Live example
`GET`	`/api/invoices/{invoice_id}/notes/`	ViewInvoice
`POST`	`/api/invoices/{invoice_id}/notes/`	CreateInvoice

These are annotations, not credit or debit notes

The body is {"title": "…", "details": "…"} — free text kept against the invoice for your own audit trail. It has no VAT effect, is never sent to ZATCA, and does not correct anything.

To issue a credit or debit note, post a document to /api/invoices/ with the right type_code — 381 for a credit note, 383 for a debit note — and the original invoice's id in original_invoice_reference (a list of invoice UUIDs). reason_id is optional; when sent, it must be an active reason from your organisation's configured reasons. The codes come from /api/invoices/invoice-type-codes/. See Credit and debit notes for what the reasons are and who sets them up.

Clients¶

Method	Path	Role	Live example
`GET`	`/api/buyers/`	ViewInvoice	example
`GET`	`/api/buyers/{buyer_id}/`	ViewInvoice
`PATCH`	`/api/buyers/{buyer_id}/`	CreateInvoice
`POST`	`/api/onboarding/organizations/clients/`	CreateInvoice

Creating a client uses the onboarding path, not POST /api/buyers/. The body is multipart/form-data, not JSON: a client_data field holding the client as a JSON string, and an optional file field for a logo. street, province_state, buyer_name, business_type and industry are required; the last two are UUIDs, which you can copy from an existing client (see Reference data). Other fields are required depending on the client, and the spec lists them all.

curl -X POST "$CLIX_API/api/onboarding/organizations/clients/" \
  -H "Authorization: Bearer $CLIX_KEY" \
  -F 'client_data={"buyer_name": "Al Noor Trading", "street": "King Fahd Road", "city": "Riyadh", "province_state": "Riyadh", "business_type": "<business-type-uuid>", "industry": "<industry-uuid>"}'

Success is 201 with location: /api/buyers/{buyer_id}/. Client creation has its own limit of 50 a minute per key; beyond it you get 429.

Items¶

Method	Path	Role	Live example
`GET`	`/api/items/`	ViewInvoice	example
`POST`	`/api/items/`	CreateInvoice
`GET`	`/api/items/{item_id}/`	ViewInvoice
`PATCH`	`/api/items/{item_id}/`	CreateInvoice

POST /api/items/ is multipart/form-data too: an item_data field holding the item as a JSON string, and optional files for images. PATCH /api/items/{item_id}/ takes plain JSON.

Devices and usage¶

Method	Path	Role	Live example
`GET`	`/api/devices/`	ViewInvoice	example
`GET`	`/api/usage/current/`	any	example

Reference data¶

Eight GET endpoints, any authenticated key — see Reference data.

What a key deliberately cannot do¶

No deletes. DELETE on items and clients is Admin-only and off the key surface. Invoices cannot be deleted by anyone: DELETE /api/invoices/{invoice_id}/ answers 403 {"message": "Invoice deletion is not allowed."} even for an Admin. A leaked key cannot destroy records.

No administration. Users, roles, branches, devices, billing and API keys themselves are all Admin-only. A key cannot create another key.

No webhooks. There is no callback registration. Poll — see Quickstart.

Conventions¶

Base URL — your gateway host including the version segment, https://<your-gateway-host>/v1. Every path on this page goes after it. It comes with your key.
Auth — Authorization: Bearer clix_… on every request.
Ids — UUIDs in paths.
Async creation — POST /api/invoices/ returns 202 and a location to poll. The location is a path, /api/invoices/{invoice_id}/; put the base URL in front of it.
Errors — 400 for validation, never 422; a validation 400 carries an array of "field.path: message" strings in message. Other errors carry message or detail; see Errors.

One key, one organisation¶

A key is bound to one organisation when it is issued, and every call acts in that organisation. There is no organisation switch: an X-Active-Org header is ignored for a key.