Get billing detail for an account

Overview

Get per-store billing detail for one account under the authenticated partner. For model-a each store lists per-feature usage/limit/cost/overage rows. For model-b each store shows a flat charge plus an enabled-feature list. Also returns feature_options (with an All entry) and a flattened per_location_drilldown. An optional feature query narrows the rows to one metered feature.

Prerequisites

• Obtain a bearer token with Partner access.
• Identify the target account's numeric brandId.

Base URL

Endpoint

GET /api/v1/partner/billing/account/{brandId}

Authentication

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

• Who can call it: Partner tokens.

• This endpoint is in the partner/billing route group.

• It resolves the caller's partner with getAuthPartner and returns 403 when no partner is available.

• It loads the {brandId} account (returning 404 if it is missing) and returns 403 unless that account belongs to the caller's partner.

Rate limit

This endpoint has no rate limit.

Path parameters

Query parameters

• Query: year (integer, optional) — 2000–2100; defaults to current year.
• Query: month (integer, optional) — 1–12; defaults to current month.
• Query: feature (string, optional, max 128) — metered feature key to narrow stores[].features / per_location_drilldown; all or omit for every enabled feature. An unknown/disabled feature key returns a 422 validation error on feature.

Response

• data.data.account_id (int), account_name (string|null), period (string YYYY-MM), billing_model (string|null), contract_model (string|null), plan_subtitle (string|null).
• data.data.feature_options (array) — { value, label } pairs (first entry is { "value": "all", "label": "All" }).
• data.data.per_location_drilldown (array) — flattened store×feature rows: store_id, store_name plus the feature fields below (and flat_charge for model-b).
• data.stores (array) — per store: store_id, store_name, features[]. Model-a feature row: feature_name, feature_label, units_consumed, limit (int|null), units_over, overage_rate (number|null), hard_stop (bool), cost, overage_cost, percentage (number|null), row_status (on_track/approaching/overage_billing/hard_stop_over_limit/halted). Model-b stores additionally include flat_charge (number) and features_enabled (string[]); their feature rows carry overage_rate=null, cost=0, overage_cost=0, row_status of on_track/warning/halted.

200 success · 200

{
  "data": {
    "data": {
      "account_id": 42,
      "account_name": "Acme Brand",
      "period": "2026-05",
      "billing_model": "usage-based",
      "contract_model": "model-a",
      "feature_options": [{ "value": "all", "label": "All" }],
      "per_location_drilldown": [],
      "stores": []
    }
  }
}

403 account not under partner · 403

{
  "message": "Forbidden",
  "status": "error",
  "errors": "Brand does not belong to your partner."
}

404 account not found · 404

{
  "message": "Not Found",
  "status": "error",
  "errors": "Brand not found."
}

Errors

Example request

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