Subscription Tools

Cancel a subscription. Delegates to an Action which queues a job — provider-side cancellation (Stripe / PayPal / Razorpay / Paystack), local state mutation, and the subscription.cancelled event all fire on the webhooks queue. Already-cancelled subscriptions return SUBSCRIPTION_ALREADY_ACTIVE instead of silently succeeding.

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.

Read the access ledger for one purchase: every grant the subscription holds, one per resource (and per dated window for a pass), with the connector that gave it, the mode (an invite link, a membership, a role, a task for the creator), the state (pending_identity, pending, held, granted, revoked, failed) and, for a failure, the classified reason and the sentence a creator reads. Use it to answer "does this member actually have access to the channel?" instead of inferring it from the subscription's payment status.

Put a subscription on hold: billing stops and the member is not cancelled, so their place, their history and their plan survive. This is the tool to reach for when a human says "stop billing", "put them on hold" or "freeze the account", because it can be undone with unpause_subscription while cancel_subscription cannot.

Emits subscription.paused. Idempotent: pausing an already-paused subscription is a no-op.

A cancellation made "at period end" leaves the subscription running until its current period ends. Until then it can be called off, and that is what this tool does: the member goes back on their normal billing cycle as if nothing had happened. It is the recovery path for a cancellation made in error and the tool to reach for on a win-back — "they changed their mind". Safe to call: it restores an intent the member already had.

Refuses a subscription that was never cancelled, and one whose cancellation has already taken effect. Emits subscription.reactivated.

Give a member a clean set of grants. The grants they hold on the subscription's resources are revoked (on Telegram, their personal invite links die) and the dispatcher that grants at purchase runs again, so fresh grants are issued and the bot sends the member the new links. Use it when a member says a link is expired or was leaked, or after a channel's admins cleared a ban; pass resource_id to touch one resource and leave the others as they are.

Every revoked grant raises member.resource_reissued, and each fresh grant raises member.resource_added moments later. Read the result back with list_subscription_grants.

The members page's per-holder nudge: re-sends one subscriber's invite links for the window they bought, when they have not yet come through their grant. Use it when a specific member says "I never got the link"; to reach everyone still missing from a window at once, use remind_pass_window_queue.

reminded: false is a normal answer, not an error. It means there was nothing to send: the subscription holds no window, the window has ended or been cancelled, the holder has already queued, or they cannot be reached on their connector. It is the dashboard's "Nothing sent" notice.

The reverse of pause_subscription: billing restarts on the plan's schedule and the member's access to the plan's resources is restored, with fresh invite links where they are needed. Safe to call — it restores service rather than removing it.

Refuses a subscription that is not currently paused, so it cannot be used to revive a cancelled or expired one; that is reactivate_subscription for a scheduled cancellation, or a new purchase. Emits subscription.unpaused.