# Get store billing (`get_store_billing`)

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.

- Source URL: https://www.signcustomiser.com/help/mcp/tools/get_store_billing/
- Markdown URL: https://www.signcustomiser.com/help/mcp/tools/get_store_billing.md
- MCP endpoint: https://mcp.signcustomiser.com
- Required scope: `billing:read`
- Behaviour: read

## Purpose

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.

## Annotations

| Hint | Value |
| --- | --- |
| readOnlyHint | true |
| destructiveHint | false |
| idempotentHint | true |
| openWorldHint | false |

## Prerequisites

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

## Arguments

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `section` | string | yes | 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.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | yes |  |
| `store` | object | yes |  |
| `store.id` | integer | yes |  |
| `store.name` | string | yes |  |
| `section` | string | yes | One of: `credits`, `credit_pricing`, `plan_features`, `coupons`. |
| `credits` | object | no | The AI credit balance, present for section credits. |
| `credits.balance` | integer | yes | plan_balance and purchased_balance together. |
| `credits.plan_balance` | integer | yes |  |
| `credits.purchased_balance` | integer | yes |  |
| `credits.plan_cycle_ends_at` | string or null | no | When the plan credits reset, UTC. |
| `credits.last_used_at` | string or null | no |  |
| `credit_pricing` | object | no | The credit purchase rules, present for section credit_pricing. |
| `credit_pricing.min_credits` | integer | yes |  |
| `credit_pricing.max_credits` | integer | yes |  |
| `credit_pricing.credit_step` | integer | yes |  |
| `credit_pricing.base_unit_amount` | integer | yes | The price of one credit, in minor units. |
| `credit_pricing.currency` | string | yes |  |
| `credit_pricing.volume_threshold_credits` | integer | yes |  |
| `credit_pricing.volume_discount_percent` | integer | yes |  |
| `credit_pricing.referral_bonus_percent` | integer | yes |  |
| `credit_pricing.referral_bonus` | object | yes | The referral code itself is never returned. |
| `credit_pricing.referral_bonus.applies` | boolean | yes |  |
| `credit_pricing.referral_bonus.can_add_code` | boolean | yes |  |
| `credit_pricing.referral_bonus.from_saved_code` | boolean | yes |  |
| `plan_features` | object | no | What the plan allows, present for section plan_features. |
| `plan_features.subscribed` | boolean | yes |  |
| `plan_features.can_go_live` | boolean | yes |  |
| `plan_features.plan` | string or null | no | The lowercase plan identifier, as get_store_subscription reports it. Expected to grow. |
| `plan_features.billing_interval` | string or null | no | One of: `monthly`, `yearly`. |
| `plan_features.ends_at` | string or null | no |  |
| `plan_features.on_generic_trial` | boolean | yes |  |
| `plan_features.has_incomplete_payment` | boolean | yes |  |
| `plan_features.is_past_due` | boolean | yes |  |
| `plan_features.plan_credits_enabled` | boolean | yes |  |
| `plan_features.has_ai_designer` | boolean | yes |  |
| `plan_features.features` | object | yes | 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. |
| `coupons` | object | no | The Store coupons, present for section coupons. |
| `coupons.pending` | object or null | no | The coupon the next subscription uses, or null. |
| `coupons.pending.object` | string | yes | One of: `coupon`. |
| `coupons.pending.code` | string | yes |  |
| `coupons.pending.percent` | number | yes |  |
| `coupons.pending.intervals` | integer or null | no | The number of billing cycles the discount applies to, or null for every cycle. |
| `coupons.pending.is_retention_offer` | boolean | yes |  |
| `coupons.pending.is_win_back_offer` | boolean | yes |  |
| `coupons.pending.redeemed_at` | string or null | no |  |
| `coupons.active` | object or null | no | The coupon the subscription uses now, or null. |
| `coupons.active.object` | string | yes | One of: `coupon`. |
| `coupons.active.code` | string | yes |  |
| `coupons.active.percent` | number | yes |  |
| `coupons.active.intervals` | integer or null | no | The number of billing cycles the discount applies to, or null for every cycle. |
| `coupons.active.is_retention_offer` | boolean | yes |  |
| `coupons.active.is_win_back_offer` | boolean | yes |  |
| `coupons.active.redeemed_at` | string or null | no |  |
| `coupons.active_expires_at` | string or null | no |  |

## Error cases

| Code | Recovery |
| --- | --- |
| `insufficient_scope` | The connection was approved without billing:read. |

## Example: Read the AI credit balance

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_store_billing",
    "arguments": {
      "section": "credits"
    }
  }
}
```

Response:

```json
{
  "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"
      }
    }
  }
}
```

## Example: Read the plan features

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_store_billing",
    "arguments": {
      "section": "plan_features"
    }
  }
}
```

Response:

```json
{
  "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
        }
      }
    }
  }
}
```

## Example: A connection without billing:read (error)

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_store_billing",
    "arguments": {
      "section": "coupons"
    }
  }
}
```

Response:

```json
{
  "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"
        ]
      }
    }
  }
}
```
