Billing summary

Overview

Get the current period's charges in brief: total, active locations, and any overage.

Use this for a billing header.

You'll need a partner token.

Returns the summary.

Prerequisites

A Partner bearer token. See Authentication.
Optional: a year and month. Leave them out for the current month.

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

GET /api/v1/partner/billing/overview

Authentication

Partner token

Only partner and sub-partner users can call it. Any other token gets 403 (Authenticated user is not associated with an partner.).
It always covers your own partner: the accounts directly under it. There is no id to send.

Rate limit

120 requests per minute, counted per user (the token’s user). See Rate limits.

Request parameters

Parameter	In	Type	Required	Description
`year`	query	integer	No	Billing year, 2000 to 2100. Defaults to the current year.
`month`	query	integer	No	Billing month, 1 to 12. Defaults to the current month.

Request body

None.

Request payload

None.

Response body

The payload is nested one level deeper than usual: it sits in data.data.

Field	Type	Description
`data.data`	object	The billing summary.
`data.data.total_billed`	number	Total charged to your accounts for the period, to 2 decimals.
`data.data.period`	string	The billing period, as `YYYY-MM`.
`data.data.billing_model`	string or null	Your partner's billing model: `plan-based` or `usage-based`. `null` when not set.
`data.data.contract_model`	string or null	Your partner's contract model: `model-a` (overage is charged) or `model-b` (a flat rate per location, hard stop, no overage). `null` when not set.
`data.data.active_stores`	integer	Active and pending locations across your accounts.
`data.data.accounts`	array of objects	One row per account directly under your partner.
`data.data.accounts[].account_id`	integer	The account's id.
`data.data.accounts[].account_name`	string	The account's name.
`data.data.accounts[].plan_name`	string or null	Name of the account's latest plan, or `null` when it has none.
`data.data.accounts[].store_count`	integer	The account's active and pending locations.
`data.data.accounts[].cost`	number	Charges for the period, excluding overage, to 2 decimals.
`data.data.accounts[].overage`	number	Overage charges for the period, to 2 decimals.
`data.data.accounts[].status`	string	`halted` when a location hit a hard limit in the period, `overage` when there are overage charges, otherwise `within_limits`.

Response payload

{
  "data": {
    "data": {
      "total_billed": 40.44,
      "period": "2026-09",
      "billing_model": "usage-based",
      "contract_model": "model-a",
      "active_stores": 2,
      "accounts": [
        {
          "account_id": 5994,
          "account_name": "Acme Coffee",
          "plan_name": "Growth",
          "store_count": 2,
          "cost": 40.0,
          "overage": 0.44,
          "status": "overage"
        }
      ]
    }
  }
}

Examples

Success payload

See Response payload.

Error payload

403 Not a partner

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

422 Invalid period

{
  "message": "The year field must be at least 2000. (and 1 more error)",
  "errors": {
    "year": [
      "The year field must be at least 2000."
    ],
    "month": [
      "The month field must not be greater than 12."
    ]
  }
}

429 Too many requests

{
  "message": "Too Many Attempts."
}

Status	Meaning
`200`	The billing summary.
`401`	The token is missing, expired or invalid.
`403`	The caller isn't a partner or sub-partner user.
`422`	`year` is outside 2000 to 2100, or `month` is outside 1 to 12.
`429`	More than 120 requests in a minute from this user.
`500`	Unexpected server error.

Example request

curl --request GET \
  --url "https://production-api.shoutaboutus.com/api/v1/partner/billing/overview?year=2026&month=9" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'

Updated 17 days ago

Did this page help you?