Skip to content

Usage API

Applies to: All subscriptions

Purpose

Read how much your company used Complifly: IRNs issued, e-way bills generated, cancellations, uploads, prints and ERP traffic, by registration (GSTIN), for a period.

Three facts decide how to use it:

  1. The numbers are counted from the documents, not from an event log. An IRN counts when the IRN exists on your invoice; an e-way bill counts when the e-way bill exists. A retry, a failed attempt or a duplicate audit entry cannot inflate a count. The one exception is prints, which leave no document and are counted from the audit trail — the response says so.
  2. Usage belongs to the company that owns the GSTIN, not to the person who clicked. A colleague from another company working on your registration adds to your company's figures.
  3. This is a report, not a bill and not a limit. Nothing here decides what you pay, and no number on this API stops a document being issued. Your plan and your contract are separate from it.

Audience

Administrators reconciling usage against a contract; integrators and implementation partners building a report.

Prerequisites

  • A signed-in user with admin.view (Organisation Admin, External Auditor, Support Engineer, Platform Engineer or Super Admin) — see Roles and Permissions
  • A bearer token from Authentication. Your company is taken from the token; you do not send it
  • In the product, the Usage tab shows the same figures by metric and by registration for a chosen period. A company administrator sees their own company; a Super Admin can choose any company or all companies, and that wider read is audited

Reference

Base path /api/usage. All endpoints are GET and read-only.

Path Purpose
/metrics The catalogue below: what can be counted, from what source, and how precisely
/summary Totals per metric, broken down by registration
/daily The same, as a day-by-day series
/statement Your company's use per registration against its limits, as JSON or a CSV download. Not an invoice (below)
/reconciliation Authoritative usage against the older counter table. Complifly Super Admin only

Query parameters

Parameter Default Meaning
from, to the current month YYYY-MM-DD. to is exclusive. Days are India calendar days (UTC+05:30). At most 366 days. Give both or neither
metrics all Comma-separated metric ids from the table below
gstin all of your GSTINs Narrow to one registration. A GSTIN that is not yours is 403 USAGE_GSTIN_NOT_IN_COMPANY, not an empty result
companyId your own company Complifly Super Admin only — another company's id, or all for the platform. Anyone else naming a company that is not their own gets 403 USAGE_SCOPE_NOT_PERMITTED

An X-Org-Id header is ignored. Which company a request acts for is decided by your signed token alone.

What can be counted

Metric id Counts Source Precision
irn_issued IRNs issued (a later-cancelled IRN still counts) The IRN record Exact instant
irn_cancelled IRNs cancelled The IRN record Exact instant
irn_failed Documents whose IRN attempt failed and have no IRN The IRN record Day
ewb_generated E-way bills generated, with or without an IRN The e-way bill record Day
ewb_cancelled E-way bills cancelled (once per bill) The e-way bill history Day
ewb_vehicle_updated Part-B vehicle updates (every update counts) The e-way bill history Day
cewb_generated Consolidated e-way bills generated; a regeneration counts again The consolidated bill record Exact instant
upload_jobs Spreadsheet uploads processed The upload job Exact instant
upload_jobs_failed Spreadsheet uploads that failed The upload job Exact instant
prints Document prints The audit trail Exact instant
ingest_accepted Documents accepted from ERP connections (first revision only) The document Day
ingest_rejected Documents rejected at ingest The rejection record Exact instant
integration_events_delivered Outcomes delivered to ERPs The outbound event Exact instant
integration_events_dead Outcomes the ERP never acknowledged The outbound event Exact instant

Precision "Day" means the day is right but an event within about five and a half hours of midnight can fall on the neighbouring day. The source tables record time in different clocks. Do not build month-end invoicing arithmetic on a "Day" metric without allowing for this.

Usage statement

GET /api/usage/statement is the same usage, laid out as something to read and hand to a colleague: your company's use for a period, per registration, beside the limits that apply. In the product, an administrator downloads it as a spreadsheet from Plan & Set-up (Download usage statement (CSV)).

It is a statement of use. It is not an invoice, and it does not say what is chargeable. There is no price, rate, currency or "billable" column anywhere in it, and the first line of every export says so. What you are charged is set by your contract.

Parameter Default Meaning
from, to the current month As for the other reads: YYYY-MM-DD, to exclusive, India calendar days, at most 366 days
format JSON csv downloads one statement as a spreadsheet (UTF-8, opens in Excel)
pan all One statement is returned per PAN your company holds a registration under. A CSV is one statement, so add pan= when you hold more than one

There is deliberately no companyId. The statement is for the company in your token; you cannot ask for another company's.

The JSON carries statements[], each with the customer (PAN and name), the plan (code, name, version), the period, the registrations your company holds under that PAN, metrics (a total and a plain-words statement of how each was obtained), byGstin (the same counts per registration), limits and caveats. It carries notAnInvoice: true and blocks: false: nothing here stops a document being issued.

  • Limits. A limit you share with another company on the same PAN is shown with your own use and no percentage, and the statement says it is shared. A capacity for which no limit has been stated is left out for you.
  • Caveats are part of the statement, not fine print: metrics accurate only to the day, and a shared PAN.
  • A spreadsheet cannot run it. Any text cell that begins with =, +, - or @ is written as text, so a registered name cannot become a formula.

Response

GET /api/usage/summary?from=2026-10-01&to=2026-11-01&metrics=irn_issued,ewb_generated

{
  "period": { "from": "2026-10-01", "to": "2026-11-01", "days": 31, "timezone": "Asia/Kolkata (UTC+05:30)" },
  "scope": { "type": "COMPANY", "companyId": "1001", "gstin": null },
  "asOf": "2026-10-15T04:12:09.114Z",
  "metrics": [
    { "id": "irn_issued", "label": "IRNs issued", "unit": "documents", "source": "BUSINESS", "precision": "INSTANT", "total": 579 },
    { "id": "ewb_generated", "label": "E-way bills generated", "unit": "documents", "source": "BUSINESS", "precision": "DAY", "total": 378 }
  ],
  "byGstin": [
    { "gstin": "29AAACW3775F000", "companyId": "1001", "unattributed": false, "counts": { "irn_issued": 412, "ewb_generated": 290 } }
  ]
}
  • total is null and error is SOURCE_UNAVAILABLE for a metric whose source could not be read; the other metrics are still returned.
  • byGstin always sums to total. An entry with "gstin": null or "unattributed": true is usage that could not be tied to a registration — for example an upload that loaded no documents.
  • /daily adds series: [{ "day": "2026-10-03", "counts": { … } }], which also sums to the totals.

What you can and cannot see

Caller Sees
Your administrators Their own company's registrations
A Complifly Super Admin Any company, or companyId=all for the whole platform with a separate unattributed bucket. Every such read is audited

Two metrics are only partly visible to a company-scoped caller, and the platform-wide view is exact for both:

  • prints — an audit entry is visible to the company it was filed under. A print by a user of another company is not.
  • upload_jobs, upload_jobs_failed — a job that carries no GSTIN cannot be shown to a company. Older jobs carry none, because the registration was not recorded on the job when they ran. The platform-wide view still attributes such a job to a company through the documents it loaded; a company's own view cannot, so for a company with older uploads the platform-wide figure is the larger one.

Errors

Code HTTP Meaning Fixed by
USAGE_PERIOD_INVALID 400 A date is malformed, to is not after from, only one bound was given, or the span exceeds 366 days you
USAGE_METRIC_UNKNOWN 400 A metric id that is not in the catalogue you
USAGE_GSTIN_INVALID 400 gstin is not 15 characters you
USAGE_COMPANY_REQUIRED 400 Your session carries no company admin — sign in again, or contact Complifly
USAGE_GSTIN_NOT_IN_COMPANY 403 The GSTIN belongs to another company you
USAGE_SCOPE_NOT_PERMITTED 403 You named another company, all, or the reconciliation as a non-Super-Admin you
USAGE_FAILED 500 An unexpected failure; no detail is returned support

See Platform Error Codes for the full table.

Validation

Check Pass condition
Your own company is reported scope.companyId is your company, whatever headers you send
The breakdown adds up The sum of byGstin equals total for every metric
It agrees with the documents irn_issued for a month equals the count of IRNs on your invoices for that month, within the "Day" tolerance
Another company is refused ?companyId=<someone else> returns 403, not an empty report

Troubleshooting

Symptom Cause Action
403 USAGE_SCOPE_NOT_PERMITTED You named a company, or all Remove companyId; only a Complifly Super Admin can read other companies
A month-end figure differs from your own count by a few documents The metric has "Day" precision and the event fell within about five and a half hours of midnight Compare against a window that ends mid-day, or use an "Exact instant" metric
prints is lower than users report An audit entry is filed under the user's company, not the document's Ask Complifly for the platform-wide figure
STATEMENT_PAN_REQUIRED on a CSV Your company holds registrations under more than one PAN and a CSV is one statement Add ?pan= with one of the PANs the message lists
The statement shows no percentage against a limit The limit is shared with another company on the same PAN Expected; the statement says the limit is shared
Upload figures are lower than expected for older periods Older jobs carry no GSTIN and cannot be attributed to a company Expected; the platform-wide view shows them as unattributed
A metric shows SOURCE_UNAVAILABLE One data source could not be read Retry; if it persists, send the asOf time to support
The numbers do not match your invoice from Complifly This API is a report and is not the billing basis Your contract defines what is billed; raise it with your Complifly contact