Subscriptions

The subscription lifecycle — trial, activation, pause, cancellation — and plan changes, with the proration each one produces.

Families on this page

Family	Tools	read	write	destructive
subscriptions — Subscriptions	16	4	8	4
plan-changes — Plan changes	11	6	4	1
subscription-changes — Subscription changes	5	3	1	1

subscriptions

Tool	Kind	Permission	Endpoint	What it does
billing_billing_accounts_subscriptions	read	subscriptions.list	GET /v1/billing_accounts/:id/subscriptions	List the subscriptions of one billing account.
billing_subscriptions_list	read	subscriptions.list	GET /v1/subscriptions	List subscriptions.
billing_subscriptions_get	read	subscriptions.show	GET /v1/subscriptions/:id	Fetch one subscription with its items and current period.
billing_subscriptions_create	write	subscriptions.create	POST /v1/subscriptions	Create a subscription.
billing_subscriptions_upsert	write	subscriptions.create	PUT /v1/subscriptions	Create or update a subscription matched on id → external_id.
billing_subscriptions_update	write	subscriptions.update	PATCH /v1/subscriptions/:id	Update a subscription in place.
billing_subscriptions_delete	destructive	subscriptions.delete	DELETE /v1/subscriptions/:id	Soft-delete a subscription.
billing_subscriptions_activate	write	subscriptions.update	POST /v1/subscriptions/:id/activate	Activate a draft/confirmed subscription and open its first billing period.
billing_subscriptions_cancel	destructive	subscriptions.cancel	POST /v1/subscriptions/:id/cancel	Cancel a subscription.
billing_subscriptions_pause	destructive	subscriptions.pause	POST /v1/subscriptions/:id/pause	Pause a subscription.
billing_subscriptions_resume	write	subscriptions.resume	POST /v1/subscriptions/:id/resume	Resume a paused subscription and reopen billing.
billing_subscriptions_revert_to_confirmed	destructive	subscriptions.update	POST /v1/subscriptions/:id/revert-to-confirmed	Send an active subscription back to confirmed, undoing an activation.
billing_subscriptions_change_plan	write	subscriptions.update	POST /v1/subscriptions/:id/change-plan	Move a subscription to another plan, computing proration: an upgrade charges the prorated difference now, a downgrade credits the next invoice.
billing_subscriptions_items_list	read	subscriptions.show	GET /v1/subscriptions/:id/items	List the items of a subscription.
billing_subscriptions_items_change	write	subscriptions.update	POST /v1/subscriptions/:id/items	Apply up to 50 item operations to a subscription in one transaction, with proration.
billing_subscriptions_sync_plan_items	write	subscriptions.update	POST /v1/subscriptions/:id/sync-plan-items	Re-align a subscription with its plan: adds items the plan gained and removes items it dropped.

plan-changes

Tool	Kind	Permission	Endpoint	What it does
billing_plan_changes_list	read	plan-changes.list	GET /v1/plan_changes	List plan changes — the audit trail of every plan swap, with its proration.
billing_plan_changes_get	read	plan-changes.show	GET /v1/plan_changes/:id	Fetch one plan change with the proration it produced.
billing_plan_changes_execute	write	subscriptions.update	POST /v1/plan_changes	Execute a plan change against the organization rules.
billing_plan_changes_stats	read	plan-changes.list	GET /v1/plan_changes/stats	Aggregate plan-change counts and amounts over the last days (default 30).
billing_plan_changes_config_get	read	plan-changes.config	GET /v1/plan_changes/config	Read the organization plan-change policy: whether upgrades/downgrades are allowed, and how each is prorated and timed.
billing_plan_changes_config_update	write	plan-changes.config	PATCH /v1/plan_changes/config	Update the organization plan-change policy.
billing_plan_changes_rules_list	read	plan-changes.config	GET /v1/plan_changes/rules	List the per-plan-pair rules that override the global policy — which moves are allowed, and with which discount or bonus.
billing_plan_changes_rules_get	read	plan-changes.config	GET /v1/plan_changes/rules/:id	Fetch one plan-change rule.
billing_plan_changes_rules_create	write	plan-changes.config	POST /v1/plan_changes/rules	Create a plan-change rule.
billing_plan_changes_rules_update	write	plan-changes.config	PATCH /v1/plan_changes/rules/:id	Update a plan-change rule.
billing_plan_changes_rules_delete	destructive	plan-changes.config	DELETE /v1/plan_changes/rules/:id	Delete a plan-change rule; the pair falls back to the global policy.

subscription-changes

Tool	Kind	Permission	Endpoint	What it does
billing_subscription_item_changes_list	read	subscription-changes.list	GET /v1/subscription_item_changes	List item changes applied to subscriptions, with the proration each produced and who initiated it.
billing_subscription_item_changes_get	read	subscription-changes.show	GET /v1/subscription_item_changes/:id	Fetch one subscription item change.
billing_subscription_item_changes_cancel	destructive	subscription-changes.update	DELETE /v1/subscription_item_changes/:id	Cancel a scheduled item change before it takes effect.
billing_subscription_changes_config_get	read	subscription-changes.list	GET /v1/subscription_changes/config	Read the organization item-change policy: which item operations are allowed, how each is prorated and timed, and what the customer portal may do by itself.
billing_subscription_changes_config_update	write	subscription-changes.update	PUT /v1/subscription_changes/config	Replace the organization item-change policy.

---

The fields of each resource are in the API reference and in billing_schemas_get.

A tool you cannot run is not listed by tools/list at all. If one from this page is missing, see Authentication.