Partner billing dashboard (full UI payload)

Overview

Get the full partner billing dashboard payload: period overview (total billed, billing/contract model, active stores) plus enriched per-account rows, a summary KPI block (incl. Month-over-month change), an overage breakdown grouped by account, Model-B allocation status rows, and a UI context headline.

Prerequisites

• A bearer token. Callable with Partner tokens.

Base URL

Endpoint

GET /api/v1/partner/billing/dashboard

Authentication

• Requires a bearer token in the Authorization: Bearer <bearer-token> header.

• Who can call it: Partner tokens.

• Mounted under the partner/billing route group.

• The endpoint resolves scope by getAuthPartner, which takes the authenticated user's person.company_id and walks up to the owning partner.

• Returns 403 if the user is not associated with a partner.

• No path target — always the caller's own partner tree.

Rate limit

• No rate limit.

Query parameters

• Query: year (integer, optional) — 2000–2100; defaults to current year.
• Query: month (integer, optional) — 1–12; defaults to current month.

Response

• data.data.total_billed (number) — period sum of client_amount line items for the partner.
• data.data.period (string) — YYYY-MM.
• data.data.billing_model (string|null) — e.g. plan-based / usage-based.
• data.data.contract_model (string|null) — model-a / model-b.
• data.data.active_stores (integer) — total active stores across the partner's accounts.
• data.data.accounts (array) — enriched per-account rows: account_id, account_name, plan_name, store_count, cost, overage, status (within_limits/overage/halted), plus plan_subtitle, enforcement_mode (per-location/aggregate-pool), total_cost, allocation_note, allocation_state (within_allocation/overage/halted), billing_formula (string|null; set only for model-b).
• data.data.summary (object) — total_billed, total_billed_previous_month, total_billed_change_pct (number|null), total_billed_caption_model_b (string|null), active_accounts, active_stores, total_overage, accounts_with_overage, at_limit_locations, halted_locations.
• data.data.overage_breakdown (array) — per-account: account_id, account_name, features[] (feature_name, feature_label, overage_amount, units_over, usage_total, rate, unit_price_label). Empty unless overage line items exist.
• data.data.allocation_status (array) — model-b only (else []); per account×feature: account_id, account_name, feature_name, feature_label, row_title, used, allocation, percentage (number|null), status (on_track/warning/halted), enforcement_mode, locations_at_limit.
• data.data.context (object) — headline (string), billing_model, contract_model.

200 Success · 200

{
  "data": {
    "data": {
      "total_billed": 1249.75,
      "period": "2026-05",
      "billing_model": "usage-based",
      "contract_model": "model-a",
      "active_stores": 12,
      "accounts": [],
      "summary": {},
      "overage_breakdown": [],
      "context": {}
    }
  }
}

403 Not a partner · 403

{
  "message": "Forbidden",
  "status": "error",
  "errors": "Authenticated user is not associated with an partner."
}

Errors

Example request

curl --request GET \
  --url "https://production-api.shoutaboutus.com/api/v1/partner/billing/dashboard?" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'