title: Commercial API description: Read your company's commercial position: plan, subscription term and renewal, programmes and usage against limits. Reports only; nothing here blocks work. keywords: [commercial api, subscription, renewal, trial, licence, license, plan, entitlement, headroom, threshold, grace, founding customer, design partner, pan, commercial status] modules: [core] owner: engineering reviewed: 2026-10-23 cadence: per-release audience: [integrator, sysadmin] not_for: End users. A company administrator sees the same position on the Plan & Set-up tab; there is nothing here for an ordinary user. classification: CUSTOMER
Commercial API¶
Applies to: All subscriptions
Purpose¶
Shows where your company stands commercially: the plan, the subscription term and when it renews, programme membership, and how much of each limit your company has used.
Three facts decide how to use it:
- A customer is a PAN. Your registrations (GSTINs) sit beneath it. If your company holds registrations under more than one PAN, you get one entry per PAN.
- Nothing here blocks work. A subscription past its end date, in grace, marked suspended, or a limit that is exceeded is reported, with
blocks: false. Invoices, IRNs and e-way bills continue. A subscription marked suspended is a note on the term: it does not suspend your company (that is a separate, audited status; see Company Status). The report exists so a person can act before it matters. - A plan carries limits only once Complifly has published what it includes. The plans are Starter, Growth, Enterprise and Custom; what each includes is published deliberately, after commercial approval, and a plan you are on keeps the contents it was assigned with. Until contents are published for your plan, a capacity shows
NO_LIMIT_STATEDunless Complifly has set one for your account. A Custom plan has no standard contents: its limits are set for your account alone.
Audience¶
A customer's own administrators and the IT teams who support them. Not for end users: nothing here changes what they can do. A company administrator sees their own position on the Plan & Set-up tab.
Prerequisites¶
- Your company's view: a signed-in user with
admin.view(Organisation Admin and above) and a bearer token from Authentication. The company is taken from the token. - In the product: a company administrator sees their own plan, term, renewal date and usage against limits, read-only, on the Plan & Set-up tab, which reads
GET /api/commercial/status.
Reference¶
Your company's position¶
GET /api/commercial/status
Returns { customers: [ ... ] }, one entry per PAN your company holds a registration under.
It is about your company only. A PAN can be held by more than one company on Complifly. You see the registrations your own company holds and the use your own company has made. You never see another company's registrations, GSTINs, names or use, even when it sits under the same PAN. The company is taken from your token, never from the request.
| Field | Meaning |
|---|---|
scope |
companyId: the company this answer is for |
customer |
pan, name, type |
plan |
plan, planName, versionNo, effectiveFrom, effectiveTo, or null if none assigned |
licence |
state, trial, expiresOn, graceUntil, daysToExpiry, graceDaysLeft, blocks |
subscription |
status, term (termNo, trial, startDate, endDate, graceUntil, renewalDate, daysToExpiry, graceDaysLeft, adminStatus) and renewal (status, daysToRenewal) |
programs |
foundingCustomer, designPartner |
capacity[] |
per limit: key, label, unit, window, used (your company's), limit, consumptionPct, headroom, state, scope (always COMPANY), blocks |
registrations[] |
gstin, name, status of the registrations your company holds under the PAN |
What is deliberately not in this answer: the reason Complifly staff recorded on a plan or term change, internal notes, who created or renewed anything, internal record numbers, where a limit came from, Complifly's internal programme markers, how your company came to Complifly or who referred it, and anything about Complifly's own view of your account (health, renewal readiness, follow-up). This list is fixed in the product; a new field does not appear here until it has been added on purpose.
Subscription and licence states¶
A subscription is your current licence term read together with your plan. A renewal is a new term that replaces the previous one; the previous term is kept as it was.
| State | Meaning | Does work stop? |
|---|---|---|
ACTIVE |
Within its dates | No |
TRIAL |
A trial term, within its dates | No |
SUSPENDED |
Marked suspended by Complifly. A note only | No |
GRACE |
Past the end date, inside the grace period | No |
EXPIRED |
Past grace | No. Complifly follows up with you |
NOT_STARTED |
Starts in the future | No |
NONE |
No licence recorded | No |
Renewal status¶
renewal.status |
Meaning |
|---|---|
NOT_DUE |
The end date is not near, or the term has no end date |
DUE |
The end date is near. daysToRenewal says how many days remain |
IN_GRACE |
The end date has passed, grace has not. Renewal is overdue |
LAPSED |
Past the end date and past grace, not renewed. Work still continues |
RENEWED |
A later term replaces this one |
NO_TERM |
No term is recorded |
Capacity states¶
| State | Meaning |
|---|---|
WITHIN |
Below 70% of the limit |
WATCH |
70% or more |
WARNING |
85% or more |
AT_LIMIT |
Exactly at the limit (100%) |
OVER |
Beyond the limit. A grace-and-alert condition, not a refusal |
UNLIMITED |
Entitled to unlimited |
NO_LIMIT_STATED |
No limit has been set |
SHARED_LIMIT |
The limit belongs to a PAN that more than one company holds. used is your company's own and no percentage is given, because your company's use against a limit it shares says nothing about how close the limit is. Complifly watches the shared limit |
UNAVAILABLE |
The usage source could not be read right now |
A limit shown to you is the total that applies to your company: your plan's number plus any extra Complifly has added for you (for example five more users), or a number Complifly has set for your account alone, which takes the place of the plan's. You do not see how a limit was made up. Capacities are registrations, users, ERP connections, IRNs per month, e-way bills per month and documents accepted from ERP connections per month. The ERP document figure counts documents, not API calls; the ERP connections figure counts the active connections your company has set up, at this moment.
Usage statement¶
GET /api/usage/statement returns your company's use for a period, per registration, beside the limits above, as something to read or hand to a colleague. It is documented with the other usage reads in Usage API. It is a statement of use: it is not an invoice and does not say what is chargeable.
Administration¶
Complifly administers customers, plans, licences, entitlements and renewals itself, with a recorded reason for every change. Those operations are not part of this reference and are not available to a customer's administrators.
Validation¶
GET /api/commercial/statusas a customer administrator and confirmblocksisfalseeverywhere, no internal notes or reasons appear, and the registrations listed are your own company's only.
Troubleshooting¶
| Symptom | Cause | Action |
|---|---|---|
403 COMMERCIAL_SUPER_ADMIN_ONLY |
The caller reached an administration endpoint, which is for Complifly staff only | Use GET /api/commercial/status for your company's position |
A capacity shows UNAVAILABLE |
The usage source could not be read right now | Retry; the other capacities are unaffected |
A capacity shows NO_LIMIT_STATED |
No plan content or grant sets a limit | Expected until plan contents are published for your plan; ask Complifly to set one |
Subscription is LAPSED but users still work |
Commercial state never blocks work | Nothing is broken; renew the subscription |
The codes you can receive are listed in Platform Error Codes.