Billing for one location

Overview

Get a location's charges for the period, by capability.

Use this to explain one location's cost.

You'll need the store_id.

Returns the location's billing detail.

Prerequisites

A Partner bearer token. See Authentication.
The location's id (storeId). The location must be under your own partner.
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/store/{storeId}

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.).
The location must exist (404 if not) and sit directly under your own partner. A sub-partner can open its own locations, but not its parent partner's or a sibling's (403).

Rate limit

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

Request parameters

Parameter	In	Type	Required	Description
`storeId`	path	integer	Yes	The location's id. Digits only.
`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, not data. The response has no billing_model or contract_model; use Billing summary for those.

Field	Type	Description
`data.data`	object	The location's billing detail.
`data.data.store_id`	integer	The location's id.
`data.data.store_name`	string	The location's name.
`data.data.period`	string	The billing period, as `YYYY-MM`.
`data.data.features`	array of objects	One row per feature enabled on the account's plan. Empty when the account has no plan or no enabled features.
`data.data.features[].feature_name`	string	The feature, e.g. `response_posting`.
`data.data.features[].usage`	integer	Units the location used in the period.
`data.data.features[].limit`	integer or null	The location's limit for the feature: the plan's service limit for usage-based billing, or its included units for plan-based billing. `null` when there's no limit.
`data.data.features[].percentage`	number or null	`usage` as a percentage of `limit`, to 1 decimal. `null` when there is no limit.
`data.data.features[].status`	string	`halted` when a hard limit was hit, `hard_stop_over_limit` or `overage` when usage is over the limit, `approaching` from 75%, otherwise `within_limits`.
`data.data.features[].cost`	number	The period's charges for the location and feature, to 2 decimals.

Response payload

{
  "data": {
    "data": {
      "store_id": 3007,
      "store_name": "Acme Coffee",
      "period": "2026-09",
      "features": [
        {
          "feature_name": "ai_response",
          "usage": 42,
          "limit": 50,
          "percentage": 84.0,
          "status": "approaching",
          "cost": 0.0
        },
        {
          "feature_name": "response_posting",
          "usage": 61,
          "limit": 50,
          "percentage": 122.0,
          "status": "overage",
          "cost": 0.44
        },
        {
          "feature_name": "review_widgets",
          "usage": 2,
          "limit": null,
          "percentage": null,
          "status": "within_limits",
          "cost": 0.0
        }
      ]
    }
  }
}

Examples

Success payload

See Response payload.

Error payload

403 Location not under your partner

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

403 Not a partner

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

404 Location not found

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

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 location's billing detail.
`401`	The token is missing, expired or invalid.
`403`	The caller isn't associated with a partner (`Authenticated user is not associated with an partner.`), or the location isn't under the caller's partner (`Store does not belong to your partner.`).
`404`	No location exists with that `storeId` (`Store not found.`).
`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/store/3007?year=2026&month=9" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'