List plans visible to an account

Overview

Get the plans an account can see, for display in an account-facing UI.

Use this when you're building the plan page a business owner sees. Partners should use List your plans instead.

With a token, you'll need the account's company_id (or leave it out for your own account). Without a token, you'll need the partner's referral_code.

Returns the plans visible to that account: the plans set up for its partner, cheapest first.

Prerequisites

With a token: a bearer token (see Authentication) and, optionally, the account's company_id.
Without a token: the partner's referral_code, for example from a sign-up link.

Base URL

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

Endpoint

GET /api/v1/plans/list

Authentication

Public (no token)

A bearer token is optional.
With a token: company_id must be inside your own account tree, otherwise 422. Leave it out to get the plans for the token's own company.
Without a token: send referral_code to get that partner's plans. company_id on its own is rejected with 422. With neither, you get the default plans.

Rate limit

100 requests per minute, counted per client IP address. See Rate limits.

Request parameters

Parameter	In	Type	Required	Description
`company_id`	query	integer	No	With a token only: the account to list plans for. Must be inside your account tree. Leave it out to use the company of the user behind the token. Without a token it's rejected unless you also send `referral_code` (then it's ignored).
`referral_code`	query	string	No	Without a token: the partner's referral code, to list that partner's plans. Must be an existing code. Up to 255 characters.

Request body

None.

Request payload

None.

Response body

The payload is inside data.

Field	Type	Description
`data`	array	The plans, sorted by price (lowest first).
`data[].id`	integer	The plan's id.
`data[].plan_name`	string	The plan's name.
`data[].price`	number	The plan's price.
`data[].original_price`	number or null	The original price, or `null`.
`data[].status`	string	`active` or `inactive`.
`data[].plan_type`	string	`plan-based` or `usage-based`.
`data[].enforcement_mode`	string	`per-location` or `aggregate-pool`.
`data[].is_admin_managed`	boolean	`true` for plans set up by Shout About Us (plan-based partners), `false` for plans your partner creates (usage-based partners).
`data[].description`	string or null	The plan's description.
`data[].plan_end_date`	string or null	The date the plan ends, or `null`.
`data[].short_info`	string or null	A one-line summary of the plan.
`data[].created_at`	string	When the plan was created.
`data[].updated_at`	string	When the plan was last changed.
`data[].deleted_at`	string or null	Always `null` here.
`data[].features`	array	The plan's features, one entry per feature.
`data[].features[].id`	integer	The feature row's id.
`data[].features[].plan_id`	integer	The plan's id.
`data[].features[].feature_name`	string	The feature, e.g. `ai_response` or `review_solicitation_email`.
`data[].features[].enabled`	boolean	Whether the feature is on in this plan.
`data[].features[].limit_type`	string or null	`monthly` or `quantity`, or `null`.
`data[].features[].included_units`	integer or null	Plan-based plans: the units included. `null` means unlimited.
`data[].features[].hard_stop`	boolean	`true`: the feature stops at its limit. `false`: usage over the limit is billed at `overage_rate`.
`data[].features[].options`	array	The feature's display options, each with `id`, `plan_feature_id`, `feature_key` and `feature_value`. Usually `[]`.
`data[].plan_review_sites`	array	The review sites on the plan, with how often reviews are collected from each.
`data[].plan_review_sites[].id`	integer	The row's id.
`data[].plan_review_sites[].plan_id`	integer	The plan's id.
`data[].plan_review_sites[].review_site_id`	integer	The review site's id.
`data[].plan_review_sites[].pull_frequency`	string	How often reviews are collected: `hourly`, `daily`, `weekly` or `monthly`.
`data[].plan_review_sites[].pull_interval`	integer	Collect every this many hours, days, weeks or months (1 to 30).
`data[].plan_review_sites[].review_site`	object	The review site: `id` and `name`.
`data[].plan_review_sites[].review_site.id`	integer	The review site's id.
`data[].plan_review_sites[].review_site.name`	string	The review site's name.

Response payload

{
  "data": {
    "data": [
      {
        "id": 36,
        "plan_name": "Growth — Unlimited",
        "price": 2,
        "original_price": null,
        "status": "active",
        "plan_type": "plan-based",
        "enforcement_mode": "per-location",
        "is_admin_managed": true,
        "description": null,
        "plan_end_date": null,
        "short_info": null,
        "created_at": "2026-09-21T13:53:10.000000Z",
        "updated_at": "2026-09-21T13:53:10.000000Z",
        "deleted_at": null,
        "features": [
          {
            "id": 1116,
            "plan_id": 36,
            "feature_name": "ai_response",
            "enabled": true,
            "included_units": 100,
            "limit_type": null,
            "hard_stop": false,
            "options": []
          },
          {
            "id": 1117,
            "plan_id": 36,
            "feature_name": "review_flag",
            "enabled": true,
            "included_units": 121,
            "limit_type": null,
            "hard_stop": false,
            "options": []
          },
          {
            "id": 1118,
            "plan_id": 36,
            "feature_name": "response_to_past_reviews",
            "enabled": true,
            "included_units": 12,
            "limit_type": "monthly",
            "hard_stop": false,
            "options": []
          }
        ],
        "plan_review_sites": [
          {
            "id": 218,
            "plan_id": 36,
            "review_site_id": 1,
            "pull_frequency": "daily",
            "pull_interval": 1,
            "review_site": {
              "id": 1,
              "name": "Yelp"
            }
          },
          {
            "id": 219,
            "plan_id": 36,
            "review_site_id": 3,
            "pull_frequency": "daily",
            "pull_interval": 1,
            "review_site": {
              "id": 3,
              "name": "Facebook"
            }
          }
        ]
      }
    ]
  }
}

The example shows one plan, with three of its features and two of its review sites.

Examples

Success payload

See Response payload.

Error payload

404 Company not found

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

422 Unknown company_id

{
  "message": "The selected company id is invalid.",
  "errors": {
    "company_id": ["The selected company id is invalid."]
  }
}

422 company_id outside your tree

{
  "message": "The selected company id does not belong to your company hierarchy.",
  "errors": {
    "company_id": ["The selected company id does not belong to your company hierarchy."]
  }
}

422 company_id without a token

{
  "message": "Without a token, send referral_code instead of company_id.",
  "errors": {
    "company_id": ["Without a token, send referral_code instead of company_id."]
  }
}

422 Unknown referral_code

{
  "message": "The selected referral code is invalid.",
  "errors": {
    "referral_code": ["The selected referral code is invalid."]
  }
}

429 Too many requests

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

Status	Meaning
`200`	The plans.
`404`	The company can't be found.
`422`	`company_id` doesn't exist or is outside your tree, `company_id` was sent without a token, or `referral_code` doesn't exist.
`429`	Rate limit exceeded.
`500`	Unexpected server error.

Example request

curl --request GET \
  --url "https://production-api.shoutaboutus.com/api/v1/plans/list?company_id=5994" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'