Skip to content

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.

  • An API key with the scope billing:read (scopes). There is no billing:write scope.
  • 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_…"

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": []
  }
}
  • edition is free, pro or enterprise.
  • state is free, active or grace. In grace a payment failed: the edition stays until grace_until (and grace_days_left counts the days), then the organization goes back to Free. Nothing is deleted.
  • billable_servers is the number of enrolled servers that are not revoked; the subscription bills at least one.
  • subscription describes the paid subscription, if there is one. cancel_at_period_end tells you that a cancellation is scheduled; the edition lasts until current_period_end. packages lists the extra backup storage and mail relay you added.
  • profile_complete says whether the billing profile has what a checkout needs.

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/…"
}
  • status is draft, open, paid, uncollectible or void.
  • Amounts (subtotal, tax, total, amount_paid, amount_refunded, and amount and unit_amount in lines) are whole numbers in the smallest unit of currency. Divide by 100 to show them, and show them with the invoice’s own currency.
  • lines has one entry per charge, with quantity, proration (a part-period charge or credit), and the VAT of the line: vat_rate, vat_amount and vat_category (a UNCL5305 code: S, AE, O, Z or E; vat_exemption_code when the VAT does not apply).
  • hosted_invoice_url opens the invoice page at Stripe and invoice_pdf_url downloads the PDF; both are addresses of Stripe’s pages, so open them in a browser instead of sending your API key to them.

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.

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.

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.

The event invoice.ready is reserved for billing and is not sent yet (event list). Until it is, read the invoices on a schedule.