Billing
get_store_billing
readGet store billing
Answer what the Store plan includes, how many AI credits it has left, what credits cost, and which coupon the subscription uses, before a merchant decides to change anything in the merchant admin.
Overview
Reads one billing document of the connected Store, chosen by section: credits (the AI credit balance, split into plan and purchased credits, with the plan cycle end), credit_pricing (the rules a credit purchase in the merchant admin is priced by, in minor units of USD, and whether the next purchase earns the referral bonus), plan_features (whether the Store is subscribed and can put a customiser live, and which plan features are included) or coupons (the pending and the active subscription coupon). It cannot pay, change a plan, buy credits or apply a coupon. 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
The billing document to read: credits, credit_pricing, plan_features or coupons (closed).
One of: credits, credit_pricing, plan_features, coupons
Result
The section that was read and its document under the same name.
One of: credits, credit_pricing, plan_features, coupons
The AI credit balance, present for section credits.
plan_balance and purchased_balance together.
When the plan credits reset, UTC.
The credit purchase rules, present for section credit_pricing.
The price of one credit, in minor units.
The referral code itself is never returned.
What the plan allows, present for section plan_features.
The lowercase plan identifier, as get_store_subscription reports it. Expected to grow.
One of: monthly, yearly
The plan entitlements: customiser_limit (null for no limit) and one boolean per feature (advanced_letter, per_word_styling, svg_files, sharing, icons, free_transform, custom_design_forms, quote_mode, custom_support_background, size_scaling). A false feature is locked in the merchant admin.
The Store coupons, present for section coupons.
The coupon the next subscription uses, or null.
One of: coupon
The number of billing cycles the discount applies to, or null for every cycle.
The coupon the subscription uses now, or null.
One of: coupon
The number of billing cycles the discount applies to, or null for every cycle.
Error cases
The connection was approved without billing:read.
Read the AI credit balance
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_store_billing",
"arguments": {
"section": "credits"
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
"store": {
"id": 12,
"name": "Demo Signs"
},
"section": "credits",
"credits": {
"balance": 42,
"plan_balance": 40,
"purchased_balance": 2,
"plan_cycle_ends_at": "2026-12-01T00:00:00Z",
"last_used_at": "2026-11-14T09:30:00Z"
}
}
}
}Read the plan features
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_store_billing",
"arguments": {
"section": "plan_features"
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
"store": {
"id": 12,
"name": "Demo Signs"
},
"section": "plan_features",
"plan_features": {
"subscribed": true,
"can_go_live": true,
"plan": "growth_10",
"billing_interval": "monthly",
"ends_at": null,
"on_generic_trial": false,
"has_incomplete_payment": false,
"is_past_due": false,
"plan_credits_enabled": true,
"has_ai_designer": true,
"features": {
"customiser_limit": null,
"advanced_letter": true,
"per_word_styling": true,
"svg_files": true,
"sharing": true,
"icons": true,
"free_transform": true,
"custom_design_forms": true,
"quote_mode": true,
"custom_support_background": true,
"size_scaling": true
}
}
}
}
}A connection without billing:read (error)
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_store_billing",
"arguments": {
"section": "coupons"
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"isError": true,
"structuredContent": {
"error": {
"code": "insufficient_scope",
"title": "Insufficient scope",
"detail": "The tool [get_store_billing] 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"
]
}
}
}
}