Billing
list_plans
readList plans
Name and price a plan identifier that get_store_subscription or get_store_billing reports.
Overview
Lists every Sign Customiser subscription plan, the same list for every Store, with each plan identifier, its display name, its billing interval and its list price for one interval in minor units of USD before coupons. The list includes plans that are no longer offered, so it is not the set of plans the Store can choose. It cannot change a plan. It requires the billing:read scope and has no side effects.
Permission
Requires thebilling:readpermission. A connection without it answersinsufficient_scopenaming the permission to approve.
Annotations
Prerequisites
- A merchant has connected this store and approved the billing:read scope.
Arguments
This tool takes no arguments.
Result
Every plan in one page, in a fixed order, with the shared pagination block reporting no further pages.
Every plan, in a fixed order.
The lowercase plan identifier, as get_store_subscription reports it. Expected to grow.
One of: monthly, yearly
The list price for one billing interval, in minor units of currency, before coupons. Null when the plan has no price.
Error cases
The connection was approved without billing:read.
Every plan
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_plans",
"arguments": {}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
"store": {
"id": 12,
"name": "Demo Signs"
},
"plans": [
{
"plan": "growth_10",
"plan_display_name": "Growth 10",
"billing_interval": "monthly",
"price_amount": 4900,
"currency": "USD"
},
{
"plan": "growth_10_yearly",
"plan_display_name": "Growth 10 Yearly",
"billing_interval": "yearly",
"price_amount": 47000,
"currency": "USD"
}
],
"pagination": {
"has_more": false,
"next_cursor": null
}
}
}
}A connection without billing:read (error)
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_plans",
"arguments": {}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"isError": true,
"structuredContent": {
"error": {
"code": "insufficient_scope",
"title": "Insufficient scope",
"detail": "The tool [list_plans] requires the billing:read scope, which this connection was not granted.",
"recovery": "The connection was authorised without the scope this tool needs. Ask the merchant to reconnect the Sign Customiser connector and approve the scope named in required_scopes. If the approval screen does not offer that permission, ask them to remove the connector from this AI agent and add it again. Do not retry this call.",
"required_scopes": [
"billing:read"
],
"granted_scopes": [
"store:read"
]
}
}
}
}