Sign Customiser

Navigation

Dark mode

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

readOnlyHinttrue
destructiveHintfalse
idempotentHinttrue
openWorldHintfalse

Prerequisites

  • A merchant has connected this store and approved the billing:read scope.

Arguments

sectionstringrequired

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.

request_idstringalways present
storeobjectalways present
store.idintegeralways present
store.namestringalways present
sectionstringalways present

One of: credits, credit_pricing, plan_features, coupons

creditsobject

The AI credit balance, present for section credits.

credits.balanceintegeralways present

plan_balance and purchased_balance together.

credits.plan_balanceintegeralways present
credits.purchased_balanceintegeralways present
credits.plan_cycle_ends_atstring or null

When the plan credits reset, UTC.

credits.last_used_atstring or null
credit_pricingobject

The credit purchase rules, present for section credit_pricing.

credit_pricing.min_creditsintegeralways present
credit_pricing.max_creditsintegeralways present
credit_pricing.credit_stepintegeralways present
credit_pricing.base_unit_amountintegeralways present

The price of one credit, in minor units.

credit_pricing.currencystringalways present
credit_pricing.volume_threshold_creditsintegeralways present
credit_pricing.volume_discount_percentintegeralways present
credit_pricing.referral_bonus_percentintegeralways present
credit_pricing.referral_bonusobjectalways present

The referral code itself is never returned.

credit_pricing.referral_bonus.appliesbooleanalways present
credit_pricing.referral_bonus.can_add_codebooleanalways present
credit_pricing.referral_bonus.from_saved_codebooleanalways present
plan_featuresobject

What the plan allows, present for section plan_features.

plan_features.subscribedbooleanalways present
plan_features.can_go_livebooleanalways present
plan_features.planstring or null

The lowercase plan identifier, as get_store_subscription reports it. Expected to grow.

plan_features.billing_intervalstring or null

One of: monthly, yearly

plan_features.ends_atstring or null
plan_features.on_generic_trialbooleanalways present
plan_features.has_incomplete_paymentbooleanalways present
plan_features.is_past_duebooleanalways present
plan_features.plan_credits_enabledbooleanalways present
plan_features.has_ai_designerbooleanalways present
plan_features.featuresobjectalways present

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.

couponsobject

The Store coupons, present for section coupons.

coupons.pendingobject or null

The coupon the next subscription uses, or null.

coupons.pending.objectstringalways present

One of: coupon

coupons.pending.codestringalways present
coupons.pending.percentnumberalways present
coupons.pending.intervalsinteger or null

The number of billing cycles the discount applies to, or null for every cycle.

coupons.pending.is_retention_offerbooleanalways present
coupons.pending.is_win_back_offerbooleanalways present
coupons.pending.redeemed_atstring or null
coupons.activeobject or null

The coupon the subscription uses now, or null.

coupons.active.objectstringalways present

One of: coupon

coupons.active.codestringalways present
coupons.active.percentnumberalways present
coupons.active.intervalsinteger or null

The number of billing cycles the discount applies to, or null for every cycle.

coupons.active.is_retention_offerbooleanalways present
coupons.active.is_win_back_offerbooleanalways present
coupons.active.redeemed_atstring or null
coupons.active_expires_atstring or null

Error cases

insufficient_scope

The connection was approved without billing:read.

Read the AI credit balance

tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_store_billing",
    "arguments": {
      "section": "credits"
    }
  }
}
result
{
  "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

tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_store_billing",
    "arguments": {
      "section": "plan_features"
    }
  }
}
result
{
  "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)

tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_store_billing",
    "arguments": {
      "section": "coupons"
    }
  }
}
result
{
  "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"
        ]
      }
    }
  }
}

Type a question and press Enter. Use the arrow keys to move between the results.