Store

get_store_subscription

read

Get store subscription

Copy page

Tell a merchant whether their plan covers what they are asking for, before suggesting a change that their plan would refuse.

Overview

Returns the connected Store subscription state: its status, plan name and display name, billing interval, whether it renews, and its trial and period end dates. It exists so an assistant can tell whether a feature the merchant is asking about is available on their plan. It reads billing state only and never starts, changes or cancels a subscription; this connector has no payment or checkout capability. It requires the store:read scope and has no side effects.

Permission

Requires thestore: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 store:read scope.

Arguments

This tool takes no arguments.

Result

One subscription object. No invoices, no payment method, no card data: none of that is reachable from this connector.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

statusstringalways present

The subscription state. Expected to grow: tolerate unknown values.

One of: none, trialing, active, past_due, incomplete, unpaid, cancelling, cancelled, unknown

planstring or null

The lowercase plan identifier, or null with no plan.

plan_display_namestring or null

billing_intervalstring or null

monthly or yearly, or null with no plan.

recurringboolean or null

Whether the plan renews at the end of its period.

trial_ends_atstring or null

ends_atstring or null

When the current period ends, or null while it renews indefinitely.

Error cases

insufficient_scope

The connection was approved without store:read. Ask the merchant to reconnect and approve it.

Read the connected store plan

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_store_subscription",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "status": "active",
      "plan": "seed",
      "plan_display_name": "Seed",
      "billing_interval": "monthly",
      "recurring": true,
      "trial_ends_at": null,
      "ends_at": null
    }
  }
}

A connection without store:read (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_store_subscription",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "insufficient_scope",
        "title": "Insufficient scope",
        "detail": "The tool [get_store_subscription] requires the store: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 connector and approve the scope named in required_scopes. Do not retry this call.",
        "required_scopes": [
          "store:read"
        ],
        "granted_scopes": [
          "customisers:read"
        ]
      }
    }
  }
}