pause_subscription

Pause an active or trialing subscription — billing stops and the member keeps their place. The reversible alternative to cancelling.

Purpose

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.

The member loses resource access while paused

Pausing suspends the member's access to the plan's resources for the duration, not just the billing. Confirm the target with a human before calling.

Required ability

project-subscription:update

Input schema

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

Output shape

{
  "data": {
    "subscription_id": "5b7e2d40-1a86-4c39-97f2-e83d0b16c5a4",
    "plan_id": "9b7c2e15-4d63-4f80-a2b1-7e5d0c9f3a46",
    "payment_status": "paused",
    "outcome": "paused"
  }
}

Example prompts

"Put subscription 5b7e2d40-1a86-4c39-97f2-e83d0b16c5a4 on hold — the member is travelling for two months."

"Freeze this member's billing without cancelling them."

"Pause Ada's Premium subscription until she's back."

Failure modes

VALIDATION_FAILED — the subscription is not in a state that can be paused (for example, already cancelled or expired).
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:update.

unpause_subscription — the reverse.
cancel_subscription — when the member is leaving for good.
get_subscription — read the state back first.
Subscriptions API — the REST equivalent.