Cancel subscription

POST https://app.speybooks.com/api/v1/admin/orgs/{id}/cancel-subscription

Cancel an organisation's Stripe subscription. Supports two modes:

  • immediately: true — cancels now via stripe.subscriptions.cancel(), sets local status to canceled
  • immediately: false (default) — sets cancel_at_period_end: true via stripe.subscriptions.update(), local status stays active until period end

Flow

  1. Look up organisation and stripe_subscription_id
  2. Return 400 if no subscription exists
  3. Call Stripe API (cancel or update)
  4. Update local subscription_status and cancel_at_period_end
  5. Write SUBSCRIPTION_CANCELED audit log

Request Body

  • immediately — boolean (default false)
  • reason — minimum 5 characters, required for audit

Error responses:

  • 400 { code: "NO_SUBSCRIPTION" } — no active Stripe subscription
  • 404 { code: "NOT_FOUND" } — organisation not found

Path parameters

id string required
Organisation ID.

Body parameters

reason string required
Reason for cancellation (audit trail). Min 5 characters.
min length: 5
immediately boolean optional
Cancel immediately (true) or at period end (false). Default false.

Response

200 Subscription cancelled (immediately or at period end).
Show response fields
message string

Error codes

400 No active subscription.
404 Organisation not found.