get_subscription

One subscription by UUID — plan, subscriber, payment method, status, price, trial and end dates, and whether it was cancelled. Read it before acting on it.

Purpose

Read a subscription's current state back rather than assuming it. Every subscription write tool — cancel_subscription, pause_subscription, unpause_subscription, reactivate_subscription, remind_pass_holder — refuses a subscription in the wrong state, and this is how an agent finds out which state it is in first. The fields are the ones the REST subscription payload carries.

`canceled` and `ends_at` together tell the story

A subscription cancelled at period end has canceled: true and an ends_at still in the future — the member keeps access until then, and reactivate_subscription can still call the cancellation off. Once ends_at has passed there is nothing to reactivate.

Required ability

project-subscription:view

Input schema

{
  "type": "object",
  "required": ["subscription_id"],
  "properties": {
    "subscription_id": {
      "type": "string",
      "description": "UUID of the subscription to fetch."
    }
  }
}

Output shape

{
  "data": {
    "id": "5b7e2d40-1a86-4c39-97f2-e83d0b16c5a4",
    "plan_id": "9b7c2e15-4d63-4f80-a2b1-7e5d0c9f3a46",
    "subscriber_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",
    "method_id": "a15d70c8-3e46-4b92-b70f-58c9d2140e63",
    "payment_status": "active",
    "payment_price": "12.00",
    "currency_id": "0f6c3b2a-8e19-4d57-b4a2-1c9e7d5f3a80",
    "trial_ends_at": null,
    "ends_at": "2026-10-06T10:05:00+00:00",
    "canceled": false,
    "compensation_seconds": 0,
    "redeemed_at": null,
    "created_at": "2026-09-06T10:05:00+00:00",
    "updated_at": "2026-09-06T10:05:00+00:00",
    "grants": []
  }
}

compensation_seconds is the outage time Outage Compensation banked on the purchase; ends_at already includes it, so on a recurring plan the gateway's renewal is ends_at minus compensation_seconds.

grants lists the access grants the subscription holds, one row per resource and dated window, in the shape list_subscription_grants documents. payment_price is a decimal string in the plan's currency; parse it as a decimal, not a float. redeemed_at is set only for a subscription that came from an access code, and method_id is null for those.

Example prompts

"What state is subscription 5b7e2d40-1a86-4c39-97f2-e83d0b16c5a4 in? Can it still be reactivated?"

"When does this member's access end, and are they on a trial?"

"Which payment method is that subscription billed through?"

Failure modes

RESOURCE_NOT_FOUND — unknown subscription_id, or a subscription outside the token's scope.
AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks project-subscription:view.

list_subscription_grants
list_subscribers — the members a subscription belongs to.
get_subscriber — the member behind subscriber_id.
list_recent_payments — what was charged.
Subscriptions API — the REST equivalent.