Plan Tools

Take a window off the schedule and deal with the people who bought it, the way the dashboard's cancel button does. Each holder is resettled in one of three ways, decided per holder:

• rebound — moved to the plan's next window that is on sale;
• leg dropped — for a season-ticket holder, the one date is removed from their series and the rest stands;
• refund due — when the schedule has nothing left to move them to, their pass is ended and flagged for a refund.

Subscriby never moves the money itself: meta.refund_due is the count of holders the creator now owes a refund, and the creator settles it with their payment provider.

Emits pass.window_cancelled once, plus one of pass.holder_moved, pass.holder_stranded or pass_series.leg_dropped per holder. Idempotent: an already-cancelled window is answered with zero tallies and emits nothing.

Add a single window to a pass plan's schedule without touching the rule that generates the rest — a one-off extra session, a make-up date, a special. The window is stored as manual, which is what protects it: when the plan's schedule is rebuilt from its slots, generated windows are pruned and regenerated, manual ones are left alone.

Synchronous — the new window comes back in the get_pass_window row shape, and pass.window_scheduled emits once.

The plan's configured floor and ceiling on window length apply, so duration_minutes outside those bounds is refused rather than clamped.

Create a plan on a project. Delegates to an Action that enforces resource-sync, the plan policy, and cache invalidation before a plan.created event fires.

Every plan has a kind, and the kind decides which one nested block you send with it:

The following rules are enforced — identical inputs are rejected by the dashboard too:

• name is 5–255 chars and unique per project.
• currency_id must be supported by an active payment method on the project.
• price must be at least the $1.00 USD equivalent in the plan currency. 0 publishes a free plan, which only the Starter and Growth plans can sell; on Free the call is rejected with TEAM_TIER_REQUIRED.
• eligibility.newcomers_only, eligibility.customers_only and eligibility.churned_only are mutually exclusive.
• resources must link to at least one existing project resource — except on kind: pass_series, where it is optional. Each window in a series grants that window's own plan's resources, so a series with none still delivers what was sold; anything linked there is a lounge open for the whole span. Never pass a resource one of the slate's own windows opens: a lounge is granted at purchase with no window and kept all season, so the holder gets that channel permanently and the date it was scheduled for stops gating anything. Pass a holders-only room, or nothing.
• kind: pass and kind: pass_series both require Time-Limited Passes — bundled with Growth, or the Passes Addon on Free and Starter. On any other tier the call is rejected.

Retire a plan for good. The row is soft-deleted: it disappears from the portal, the bot and every list, nobody can buy it again, and the subscriptions already sold keep their history and keep running to their end. Emits plan.deleted with a snapshot taken before the row goes.

Idempotent: a second call on the same id finds nothing and answers RESOURCE_NOT_FOUND, exactly as an unknown or out-of-scope id does.

Read one window back before acting on it. The row is the same shape list_pass_windows returns: the instant it opens and closes, the local range in the plan's own timezone, its lifecycle status, whether it is sellable right now, and how many holders bought it.

Read one plan in full. The row is the same one list_plans emits, so an agent that found a plan in the list reads exactly the same fields back, and the row update_plan returns after a change is comparable field for field.

Reads go through the plan service, so the tenant scope and the token's scope:project: allow-list both apply. An id the token cannot see answers RESOURCE_NOT_FOUND, indistinguishable from an id that never existed.

Every row also carries cadence, the human-readable duration the portal and the bot show — "Per Month", "Per 3 Hours", "For all 10 passes". Use it rather than deriving a duration yourself.

List the dated access windows on time-limited pass plans, with their UUIDs, status, local times and holder counts.

It is also the tool for reconciling a schedule into an external calendar, and for checking what is actually still on sale before pointing a customer at a plan.

List subscription plans. Results are always scoped to the caller's team; pass an optional project_id to narrow further. Ordered by newest-first.

Toggle a plan's active flag. Active plans are purchasable and listed on the portal; inactive plans stay on the books but hide from new buyers. Noop when the plan is already in the requested state.

A pass holder who bought a window still has to come through their grant (on Telegram, tap the invite link and send a join request) before the window opens; the ones who have not are the window's queue. This tool re-sends the grant to every holder still in that queue, the way the dashboard's "remind everyone" action on a window does, and answers with how many holders the connector accepted the message for.

A window that has ended or been cancelled has nobody left to remind and answers 0. Holders who already queued are skipped.

Arrange the storefront. Buyers see plans in the order you pass; anything you leave out keeps the built-in order (passes, then seasons, then subscriptions, cheapest first) after the pinned plans. An empty list clears every pin. This is the same write the dashboard's Arrange Storefront Order drag-and-drop performs.

The plan list's "start next season" button, for agents. It creates a new plan of kind pass_series copied from the one you name — same price, currency, description, eligibility, linked resources, overlap rule, sales cutoff and seat cap — with two deliberate differences: it is created inactive, and its slate is empty. A season that went straight on sale with last year's dates in it would be selling something that has already happened.

The step a hand-built successor forgets is the link: the old season's successor_plan_id is pointed at the new plan (and a presale window is set if the old season had none), which is what lets current holders be offered the next season first. Rules are copied forward with their date bounds shifted by the length of the finished season, so "every pass in September" becomes next September; the slate itself and any blackouts are not copied, because both name specific windows that have run.

Emits plan.created for the new plan. The new season is then composed and published like any other: add dates with update_plan — pass_series.window_ids from list_pass_windows, or pass_series.rules — and put it on sale with publish_plan.

Change an existing plan without restating it. Only the arguments present in the call reach the write, the way the REST PATCH behaves, so repricing a plan is one field, not a re-creation. The shared fields are checked the way create_plan checks them, and the one nested block the plan's kind names is shaped exactly as create_plan shapes it.

Synchronous — the row after the change comes back, and plan.updated emits once with the fields that actually moved. A call whose arguments change nothing returns the current row and emits nothing.

Two tiers of entitlement are checked on the way in: a price of 0 makes the plan free, which needs the Starter or Growth tier, and anything touching a pass or pass_series needs Time-Limited Passes. Either failing surfaces as TEAM_TIER_REQUIRED with nothing written.