Usage and quotas¶

The endpoint¶

curl -s "$CLIX_API/api/usage/current/" -H "Authorization: Bearer $CLIX_KEY"

{
  "month": "2026-09-01",
  "subscribed_plan": "business",
  "invoices_used": 58,
  "invoices_limit": -1,
  "api_calls_used": 0,
  "api_calls_limit": 0,
  "public_api_validations_used": 0,
  "public_api_validations_limit": -1,
  "grace_used": false,
  "grace_exceeded": false,
  "invoices_allowed": true,
  "plan_name": "Business"
}

month is the first day of the month, YYYY-MM-01.

To read a past month, pass ?month=YYYY-MM, for example ?month=2026-08. Any other format, including 2026-08-01, returns 400 with {"message": "Invalid month; use YYYY-MM."}.

The call does not count toward your invoice allowance or fair use. It does count toward the per-minute rate limit, like every other request.

Read `invoices_`, ignore `api_calls_`¶

api_calls_used and api_calls_limit are hardcoded to 0

They are kept only so older clients keep parsing. API calls are not metered against a monthly quota. Do not build a "calls remaining" display from them — it will always read zero of zero.

The figures that matter are invoices_used against invoices_limit.

invoices_limit: -1 means unlimited. public_api_validations_limit: -1 means the public tools are not metered on your plan.

What actually limits you¶

Limit	Enforced as	Affects
Invoice allowance	The plan's monthly count	Creating invoices
Rate limit	200 requests a minute per API key	Every call
Fair use	403 `fair_use_limit`, only when Clix has switched it on	Write operations only
Plan API access	403 at every request	Whether a key works at all

Only the first is visible in this endpoint. See Errors and rate limits for the other three.

The invoice allowance¶

Counts every invoice you create in the month, by its issue date: standard and simplified invoices, credit notes and debit notes. An invoice ZATCA rejected still counts. It was created and numbered, and it cannot be resubmitted. Its replacement is a new invoice, and that counts too. Drafts, previews and sample invoices do not count.

There is a 10% grace above the plan limit, rounded up. The last invoice allowed is number ceil(limit × 1.1):

Plan	Limit	Last invoice allowed	Refused from
Free	15	17th	18th
Pro	200	220th	221st
A plan whose `invoices_limit` is `-1`	Unlimited	—	—

The limit is a value on the plan, which Clix sets. Read invoices_limit for yours rather than relying on this table.

grace_used turns true when the next invoice would be over the plan limit. grace_exceeded turns true when the next invoice would be over the grace as well. invoices_allowed is the single field to branch on before a create.

Over the grace, POST /api/invoices/ returns 403. The body has no code field:

{ "message": "Monthly invoice limit exceeded. You have used your grace period. Please upgrade your plan.",
  "current_usage": 17, "limit": 15, "plan_name": "Free", "upgrade_url": "…" }

An invoice's month is the month of its issue date, which Clix stamps in Riyadh time. The check before a create, and this endpoint without ?month, read the server's current month, which runs on UTC. The two differ for the first three hours of each month, Riyadh time: from 00:00 to 03:00 on the 1st, the check still counts the month before, while the invoice you create is dated, and counted, in the new month.

A sensible integration pattern¶

Call usage/current/ when your job starts.
If invoices_allowed is false, stop and alert a human — do not spend the run generating 403s.
Otherwise proceed, and re-check if you are pushing a large batch.

Polling it before every single invoice is wasteful; once per run, or once an hour for a long-running service, is right.

The public tools API is metered separately¶

/api/public/ endpoints (QR scanning, ZATCA validation, VAT calculation) have their own limits and do not touch your invoice allowance:

Caller	Limit	Resets
Not signed in, or calling with an API key	10 a day per IP address	Midnight UTC
A Free-plan organisation	100 a month	The 1st of the UTC month
A paid plan	Not metered	—

These endpoints do not recognise API keys, so calls made with a key count toward the per-IP daily limit. An organisation on a card trial counts as Free here. public_api_validations_* in the response above tracks the monthly count. See Public tools.