Billing

Billing is per-organization. These five tools mirror the portal’s Billing home and let an agent read an org’s billing state and start attaching a payment method — the funding rail (Stripe today) is pluggable, so the tools describe what to do without exposing raw card data.

All read tools need the read action and viewer (or higher) role. set_payment_method needs the manage action and owner role.

Is the org billable / can it deploy?

{ "name": "get_billing_status", "arguments": { "organizationId": "…" } }

Returns, at a glance: funding provider, tier (preview | paid), billingEnabled (the comp kill-switch), billingVerified (the billing half of the deploy gate), whether a billing customer and a default payment method are on file, the current subscription, and any remaining deploy blockers. Use it before a cost-bearing action.

Billing is one half of the deploy gate — get_deploy_gate_status combines it with the recovery-method check. See Capabilities overview.

Subscription, invoices, usage

{ "name": "get_subscription", "arguments": { "organizationId": "…" } }

Returns the latest subscription — plan code, status (active | trialing | past_due | incomplete | canceled | …), current period, cancelAtPeriodEnd, provider, services included. Returns { subscription: null } for a preview-tier org that has never subscribed.

{ "name": "list_invoices", "arguments": { "organizationId": "…", "limit": 24 } }

Lists invoices newest-first, live from the provider: number, status (draft/open/paid/void/uncollectible), amount due/paid + currency, billing period, and hosted-view + PDF links. Empty when no billing customer exists yet.

{ "name": "get_usage", "arguments": { "organizationId": "…" } }

Summarizes tier (+ preview expiry / service limit) and live counts of billable resources — services, databases, buckets, registered domains — plus usage events in the last 30 days. v1 pricing is a flat per-service plan, so this is the resource footprint the plan covers rather than a metered bill.

Attaching a payment method

{ "name": "set_payment_method", "arguments": { "organizationId": "…" } }

Raw card data is never accepted here. The tool returns a rail-appropriate way to attach one:

  • a hosted setupUrl to relay to an org owner (renders the provider’s payment element in the browser and saves the card as default), and
  • a SetupIntent client secret + id for a rail-native client that can attach off-session.

No charge occurs; it creates the billing customer if the org has none. Requires owner role — relay the setupUrl to an owner if you are not one.