List Receptionist plans

List the active billing plans for the Receptionist product. This is the first call on the Receptionist go-live path.

GEThttps://api.spyne.ai/agent-marketplace/billing/products/{productKey}/plans

AuthBearer token (console user)Rate limitNot documentedProcessingSynchronous, two database reads

Spyne looks up the billing product receptionist_agent and returns its plans with status ACTIVE, lowest price first. Each plan carries its kind (free or paid), funding model, price fields, entitlements and a proration preview for a purchase made today.

Auth: Bearer token of a signed-in user · Rate limit: not documented · Processing: synchronous, two database reads

Before you call it

Only a valid Bearer token is needed. The plan list does not depend on the caller's rooftop.
The product key uses underscores. receptionist-agent with a hyphen is a different key. An unknown key returns 404, not an empty list.
Use key from the response as plan_key when starting a checkout.

Path parameters

Requiredalways send

Request checklist

Header: set Authorization: Bearer YOUR_TOKEN.
Send it: no body.
Read the array: the free plan is the one with kind: "FREE".

Parameter	Type	Required	Description
`productKey`	string	Required	Billing product key. For the Receptionist: `receptionist_agent`.

Sample request

curl "https://api.spyne.ai/agent-marketplace/billing/products/receptionist_agent/plans" \
  -H "Authorization: Bearer YOUR_TOKEN"

import requests

res = requests.get(
    "https://api.spyne.ai/agent-marketplace/billing/products/receptionist_agent/plans",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
)
print(res.status_code, res.json())

const res = await fetch(
  'https://api.spyne.ai/agent-marketplace/billing/products/receptionist_agent/plans',
  { headers: { Authorization: 'Bearer YOUR_TOKEN' } }
);
console.log(res.status, await res.json());

Sample response

Amounts are shown as placeholders.

[
  {
    "key": "<freePlanKey>",
    "kind": "FREE",
    "funding_model": "SUBSCRIPTION",
    "price_minor": "<amount>",
    "currency": "usd",
    "interval": null,
    "stripe_price_id": null,
    "entitlements": {
      "meters": { "<meterKey>": { "limit": null, "period": "MONTH" } },
      "features": [],
      "validity_days": "<days>"
    },
    "status": "ACTIVE",
    "proration": {
      "amount_minor": "<amount>",
      "applies": false,
      "prorated_days": "<days>",
      "days_in_month": "<days>",
      "next_charge_date": "2026-11-01",
      "period_start": "2026-10-12",
      "period_end": "2026-10-31"
    }
  },
  {
    "key": "<planKey>",
    "kind": "PAID",
    "funding_model": "SUBSCRIPTION",
    "price_minor": "<amount>",
    "currency": "usd",
    "interval": "month",
    "stripe_price_id": null,
    "entitlements": { "meters": {}, "features": [] },
    "status": "ACTIVE",
    "proration": {
      "amount_minor": "<amount>",
      "applies": true,
      "prorated_days": "<days>",
      "days_in_month": "<days>",
      "next_charge_date": "2026-11-01",
      "period_start": "2026-10-12",
      "period_end": "2026-10-31"
    }
  }
]

{
  "message": "Authorization header is required",
  "error": "Unauthorized",
  "statusCode": 401,
  "code": "UNAUTHORIZED"
}

{
  "code": "BILLING_PRODUCT_NOT_FOUND",
  "message": "No such product: receptionist_agent.",
  "statusCode": 404
}

Response parameters (200)

The response is an array with one entry per active plan, lowest price_minor first.

Parameter	Type	Description
`key`	string	Plan key. Use as `plan_key` at checkout.
`kind`	string	`FREE` or `PAID`.
`funding_model`	string	`SUBSCRIPTION`, `WALLET` or `HYBRID`.
`price_minor`	number	Recurring price in minor units (cents).
`currency`	string	Currency code.
`interval`	string or null	`month`, `year` or `null`.
`stripe_price_id`	string or null	Gateway price ID. Not used by the current checkout path.
`entitlements`	object	What the plan includes.
`meters`	object	Map of meter key to `limit` and `period`. A `null` limit means unlimited. `period` is `LIFETIME` or `MONTH`.
`features`	string[]	Feature list for display.
`overage_rates`	object	Present only if set on the plan.
`validity_days`	number	Present only if set. How many days the plan lasts.
`status`	string	Always `ACTIVE` here.
`proration`	object	What a purchase made today would bill.
`amount_minor`	number	Amount billed today, in minor units.
`applies`	boolean	`false` when the full price would be charged.
`prorated_days`	number	Days charged, today included.
`days_in_month`	number	Days in the current month.
`next_charge_date`	string	`YYYY-MM-DD`, first day of next month.
`period_start`	string	`YYYY-MM-DD`, today.
`period_end`	string	`YYYY-MM-DD`, last day of this month.

Errors

Status	Code	When it happens
`401`	`UNAUTHORIZED`	No `Authorization` header, the header is not a Bearer token, or the token is rejected. The message says which.
`404`	`BILLING_PRODUCT_NOT_FOUND`	The product key does not exist.
`500`	`INTERNAL_ERROR`	Unexpected error. The message is always "Something went wrong. Please try again."

What happens next

Show the plans to the dealer. For the free plan, go straight to Buy a phone number.

The onboarding console does not start a checkout for paid plans today. Picking a paid plan files a sales follow-up request instead, and the flow continues to the number purchase. A direct checkout is possible with Start a paid-plan checkout.