Get the account billing summary

Account-wide (or single-tenant) consolidated billing snapshot — period usage, upcoming invoice, card on file, and recent invoices.

POSThttps://api.swarmz.net/functions/v1/platform-billing-summary

Returns a consolidated billing snapshot for the account or a single tenant — period usage, the upcoming invoice, the card on file, and recent invoices. Pairs with usage for live numbers, but adds the card and invoice context you typically render in an admin dashboard or customer-area panel.

All parameters are optional. Omit them for an account-wide snapshot, or supply exactly one identifier to scope to a single workspace.

Parameters

Prop

Type

Request

curl -X POST https://api.swarmz.net/functions/v1/platform-billing-summary \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_ref": "whmcs:1234" }'

const res = await fetch('https://api.swarmz.net/functions/v1/platform-billing-summary', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ external_ref: 'whmcs:1234' }),
});

const data = await res.json();

import requests

res = requests.post(
    "https://api.swarmz.net/functions/v1/platform-billing-summary",
    headers={"Authorization": "Bearer sk_live_..."},
    json={"external_ref": "whmcs:1234"},
)
data = res.json()

Response

{
  "ok": true,
  "account":  { "id": "<uuid>", "name": "...", "slug": "...", "email": "..." },
  "usage": {
    "credits_used": 0,
    "usd_credits": 0,
    "cloud_usd": 0,
    "period": { "from": "<ISO>", "to": "<ISO>", "label": "current_month" },
    "by_workspace": [
      { "workspace_id": "<uuid>", "credits_used": 0, "usd_credits": 0, "cloud_usd": 0 }
    ]
  },
  "upcoming": {
    "amount_due_cents": 0,
    "currency": "usd",
    "period_end": "<ISO>",
    "next_attempt": "<ISO>"
  },
  "card": {
    "brand": "visa",
    "last4": "0000",
    "exp_month": 12,
    "exp_year": 2030
  },
  "card_on_file": true,
  "billing": {
    "company": "...",
    "email": "...",
    "address": "...",
    "vat": "..."
  },
  "invoices": [
    {
      "id": "<uuid>",
      "stripe_invoice_id": "in_...",
      "status": "paid",
      "amount_due_cents": 0,
      "amount_paid_cents": 0,
      "currency": "usd",
      "period_start": "<ISO>",
      "period_end": "<ISO>",
      "hosted_invoice_url": "https://...",
      "paid_at": "<ISO>",
      "created_at": "<ISO>"
    }
  ]
}

Any of upcoming, card, or billing may be null when not yet set on the account — for example, a fresh account with no card attached.

Errors

Status	`error`	`reason`	When
400	`missing_fields`	`tenant_id or external_ref required`	Neither identifier supplied when scoping to a tenant
401	`unauthorized`	—	See Authentication
404	`tenant_not_found`	—	No tenant matched the identifier under your account
405	`method_not_allowed`	—	Anything other than `POST`
410	`terminated`	—	The tenant has been terminated
429	`rate_limited`	`per_key` / `per_ip`	Rate limit hit — see Rate limits
500	`summary_failed`	RPC message	A read failed server-side; safe to retry

Idempotency

Not applicable — billing summary is a pure read. Safe to call as often as you like. See Idempotency.

Notes

Pair with platform-usage

Use usage when you only need the live period roll-up. billing-summary is the right call when you also need the upcoming invoice, the card on file, or recent invoice history — typically for an admin dashboard or a customer-area panel.

This endpoint is limited to 60 requests/min per key. See Rate limits.