Skip to content

Usage and quotas

The endpoint

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

{
  "month": "2026-09",
  "plan_name": "Pro",
  "invoices_used": 43,
  "invoices_limit": 200,
  "api_calls_used": 0,
  "api_calls_limit": 0,
  "public_api_validations_used": 0,
  "public_api_validations_limit": 100,
  "grace_used": false,
  "grace_exceeded": false,
  "invoices_allowed": true
}

The call is free — it never counts against anything.

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.

What actually limits you

Limit Enforced as Affects
Invoice allowance The plan's monthly count Creating invoices
Rate limit 200 req/min per key Every call
Fair use 403 fair_use_limit 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 invoices submitted to ZATCA in a calendar month — standard and simplified, plus credit and debit notes. Drafts and previews do not count.

There is a 10% grace above the plan limit. grace_used turns true once you are into it; grace_exceeded turns true when even the grace is spent. invoices_allowed is the single field to branch on before attempting a create.

The month is the Asia/Riyadh calendar month, not UTC and not a rolling 30 days. An invoice at 01:00 Riyadh on the first belongs to the new month.

A sensible integration pattern

  1. Call usage/current/ when your job starts.
  2. If invoices_allowed is false, stop and alert a human — do not spend the run generating 403s.
  3. 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 buckets and do not touch your invoice allowance: 10 a day per IP anonymously, 100 a month for a free-tier organisation, unmetered on paid tiers. public_api_validations_* in the response above tracks that. See Public tools.