Get one plan

Overview

Get the full definition of a single plan.

Use this to show a customer exactly what their plan includes, or to check a capability before calling something that depends on it.

You'll need the plan_id.

Returns the plan's capabilities, limits, review sites, cadence, and price.

Prerequisites

A Partner token. See Authentication.
The plan's id (planId), e.g. from List your plans.

Base URL

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

Endpoint

GET /api/v1/partner/plans/{planId}

Authentication

Partner token

The plan must be set up for your partner and match its billing model; otherwise 403.
A plan id that doesn't exist returns 404.

Rate limit

This endpoint has no rate limit.

Request parameters

Parameter	In	Type	Required	Description
`planId`	path	integer	Yes	The plan's id.

Request body

None.

Request payload

None.

Response body

The payload is inside data.

Field	Type	Description
`data`	object	The plan.
`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[].service_limit`	integer or null	Usage-based plans: the usage limit. `null` means no limit.
`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[].overage_rate`	string or null	The price per unit over the limit, as a decimal string, e.g. `"0.0800"`.
`data.features[].hard_stop`	boolean	`true`: the feature stops at its limit. `false`: usage over the limit is billed at `overage_rate`.
`data.features[].created_at`	string	When the feature row was created.
`data.features[].updated_at`	string	When the feature row was last changed.
`data.features[].deleted_at`	string or null	Always `null` here.
`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[].pull_times`	array of strings	Times of day to collect, as `HH:MM`.
`data.plan_review_sites[].pull_days`	array of integers or null	Days of the week to collect (`0` to `6`), or `null`.
`data.plan_review_sites[].created_at`	string	When the row was created.
`data.plan_review_sites[].updated_at`	string	When the row was last changed.
`data.plan_review_sites[].deleted_at`	string or null	Always `null` here.
`data.plan_review_sites[].review_site`	object	The review site, including `id`, `name`, `link`, `logo` and `auth_type`.
`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.
`data.plan_review_sites[].review_site.link`	string	The review site's home page.
`data.plan_review_sites[].review_site.logo`	string or null	The review site's logo URL, or `null`.
`data.plan_review_sites[].review_site.auth_type`	string or null	How the site connects: `oauth`, `cookie`, `credential`, `default`, `restapi` or `null`. See List supported review sites.
`data.features[].partner_billing_enabled`	boolean	`true` when your partner's billing setup has this feature turned on (or has no setting for it).
`meta`	object	About the plan.
`meta.read_only`	boolean	Always `true`: plans can't be changed through the API.

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,
          "service_limit": null,
          "limit_type": null,
          "included_units": 100,
          "overage_rate": "0.0800",
          "hard_stop": false,
          "created_at": "2026-09-21T13:53:10.000000Z",
          "updated_at": "2026-09-21T13:53:10.000000Z",
          "deleted_at": null,
          "partner_billing_enabled": true
        },
        {
          "id": 1117,
          "plan_id": 36,
          "feature_name": "review_flag",
          "enabled": true,
          "service_limit": null,
          "limit_type": null,
          "included_units": 121,
          "overage_rate": "0.0800",
          "hard_stop": false,
          "created_at": "2026-09-21T13:53:10.000000Z",
          "updated_at": "2026-09-21T13:53:10.000000Z",
          "deleted_at": null,
          "partner_billing_enabled": true
        },
        {
          "id": 1118,
          "plan_id": 36,
          "feature_name": "response_to_past_reviews",
          "enabled": true,
          "service_limit": null,
          "limit_type": "monthly",
          "included_units": 12,
          "overage_rate": "0.0500",
          "hard_stop": false,
          "created_at": "2026-09-21T13:53:10.000000Z",
          "updated_at": "2026-09-21T13:53:10.000000Z",
          "deleted_at": null,
          "partner_billing_enabled": true
        }
      ],
      "plan_review_sites": [
        {
          "id": 218,
          "plan_id": 36,
          "review_site_id": 1,
          "pull_frequency": "daily",
          "pull_interval": 1,
          "pull_times": [
            "06:00"
          ],
          "pull_days": null,
          "created_at": "2026-09-21T13:53:10.000000Z",
          "updated_at": "2026-09-21T13:53:10.000000Z",
          "deleted_at": null,
          "review_site": {
            "id": 1,
            "name": "Yelp",
            "link": "http://www.yelp.com",
            "logo": null,
            "auth_type": "cookie"
          }
        },
        {
          "id": 219,
          "plan_id": 36,
          "review_site_id": 3,
          "pull_frequency": "daily",
          "pull_interval": 1,
          "pull_times": [
            "06:00"
          ],
          "pull_days": null,
          "created_at": "2026-09-21T13:53:10.000000Z",
          "updated_at": "2026-09-21T13:53:10.000000Z",
          "deleted_at": null,
          "review_site": {
            "id": 3,
            "name": "Facebook",
            "link": "http://www.facebook.com",
            "logo": null,
            "auth_type": "oauth"
          }
        }
      ]
    },
    "meta": {
      "read_only": true
    }
  }
}

The example shows three of the plan's features and two of its review sites.

Examples

Success payload

See Response payload.

Error payload

403 Plan not set up for your partner

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

403 Plan doesn't match your billing model

A usage-based partner gets This plan is not a partner-managed usage-based plan.

{
  "message": "Forbidden",
  "status": "error",
  "errors": "This plan is not available for your billing model."
}

403 Billing model not configured

{
  "message": "Forbidden",
  "status": "error",
  "errors": "Partner billing model is not configured."
}

404 Plan not found

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

Status	Meaning
`200`	The plan.
`401`	The token is missing, expired or invalid.
`403`	The plan isn't set up for your partner or doesn't match its billing model, or your partner has no billing model configured.
`404`	The plan doesn't exist.
`500`	Unexpected server error.

Example request

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