Read billing data
Read your organization's edition, subscription, invoices and billing profile through the API, and what the API does not let a key change.
This guide shows how to read the billing data of your organization with the API: the edition and subscription, the invoices and the billing profile. An API key can only read billing data. Buying, changing or cancelling a subscription and editing the billing profile are done in the panel.
What you need
Section titled “What you need”- An API key with the scope
billing:read(scopes). There is nobilling:writescope. - A user who may see billing. Only organization administrators can read it: a key of a reseller or client user
answers
403.
export PLUSPANEL_URL="https://panel.example.com"
export PLUSPANEL_API_KEY="ppk_…"
1. Read the edition and subscription
Section titled “1. Read the edition and subscription”GET /api/v1/billing answers with the state of the organization’s billing.
curl -fsS "$PLUSPANEL_URL/api/v1/billing" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY"
{
"edition": "pro",
"state": "active",
"managed": true,
"billable_servers": 3,
"profile_complete": true,
"subscription": {
"plan": "pro_monthly",
"status": "active",
"servers": 3,
"current_period_end": "2026-12-01T00:00:00Z",
"cancel_at_period_end": false,
"packages": []
}
}
editionisfree,proorenterprise.stateisfree,activeorgrace. Ingracea payment failed: the edition stays untilgrace_until(andgrace_days_leftcounts the days), then the organization goes back to Free. Nothing is deleted.billable_serversis the number of enrolled servers that are not revoked; the subscription bills at least one.subscriptiondescribes the paid subscription, if there is one.cancel_at_period_endtells you that a cancellation is scheduled; the edition lasts untilcurrent_period_end.packageslists the extra backup storage and mail relay you added.profile_completesays whether the billing profile has what a checkout needs.
2. List the invoices
Section titled “2. List the invoices”GET /api/v1/billing/invoices lists the invoices that Stripe issued, newest first. It is
paginated with limit and cursor.
curl -fsS -G "$PLUSPANEL_URL/api/v1/billing/invoices" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY" \
--data-urlencode "limit=12" \
| jq '.items[] | {number, status, issued_at, currency, total, hosted_invoice_url}'
{
"number": "PP-2026-0042",
"status": "paid",
"issued_at": "2026-11-01T00:00:12Z",
"currency": "eur",
"total": 0,
"hosted_invoice_url": "https://invoice.stripe.com/…"
}
statusisdraft,open,paid,uncollectibleorvoid.- Amounts (
subtotal,tax,total,amount_paid,amount_refunded, andamountandunit_amountinlines) are whole numbers in the smallest unit ofcurrency. Divide by 100 to show them, and show them with the invoice’s own currency. lineshas one entry per charge, withquantity,proration(a part-period charge or credit), and the VAT of the line:vat_rate,vat_amountandvat_category(a UNCL5305 code:S,AE,O,ZorE;vat_exemption_codewhen the VAT does not apply).hosted_invoice_urlopens the invoice page at Stripe andinvoice_pdf_urldownloads the PDF; both are addresses of Stripe’s pages, so open them in a browser instead of sending your API key to them.
3. Read the billing profile
Section titled “3. Read the billing profile”GET /api/v1/billing/profile is the buyer shown on the invoices: the company, its address and its tax
identifiers.
curl -fsS "$PLUSPANEL_URL/api/v1/billing/profile" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY" \
| jq '{legal_name, country, vat_id, vat_status, complete}'
vat_status is none, pending (the check against VIES was not possible yet; VAT is charged as without a VAT
ID until it succeeds) or valid. When the organization has never saved a profile, the answer is 404.
Like every GET, these answers carry an ETag: send it back in If-None-Match and an unchanged answer is
304. See ETags.
What a key cannot do
Section titled “What a key cannot do”Checkout, changing the plan or packages, cancelling, resuming, the customer portal and saving the billing
profile need a signed-in session. With an API key they answer 403 api_key_not_allowed, whatever the key’s
scopes. Do these in the panel’s Billing page.
Errors
Section titled “Errors”| Status | Code | Meaning |
|---|---|---|
401 |
invalid_api_key |
The key is missing, expired or revoked. |
403 |
The key has no billing:read scope, or the user is not an administrator. |
|
403 |
api_key_not_allowed |
The operation needs a signed-in session (see above). |
404 |
No billing profile was saved yet. |
Errors are problem details: branch on code.
Events
Section titled “Events”The event invoice.ready is reserved for billing and is not sent yet (event list).
Until it is, read the invoices on a schedule.
Related
Section titled “Related”- Billing and editions: editions, packages, VAT, failed payments and refunds. Amounts are on the pricing page.
- API reference: every
billingoperation, with its fields. - API conventions: errors, pagination and ETags.
- Authentication & API keys: scopes and key handling.