Skip to main content
Migo Docs

Subscription Lifecycle

A subscription has exactly four states: active, cancelled, expired, and inactive.

                ┌──────────────┐
                │   active     │
                └──────┬───────┘
                       │
        ┌──────────────┼──────────────────┐
        ▼              ▼                  ▼
  ┌──────────┐   ┌──────────┐       ┌──────────┐
  │ cancelled│   │ inactive │       │ expired  │
  └──────────┘   └──────────┘       └──────────┘

Transitions — who triggers what​

From → ToTriggered by
active → cancelledYour DELETE /v1/subscriptions/{subUid} (immediate)
active → inactiveCharge retries exhausted (cron, automatic)
active → expiredFixed-term subscription reached its end

There are no trialing, past_due, unpaid, or paused states, so there is no trial-end, pause/resume, plan-change, or proration transition.

Plan changes and prorations​

The current API does not support changing a subscription's plan or prorating mid-cycle. PUT /v1/subscriptions only updates the notification email (see Subscriptions → Update).

Cancellation​

Cancellation is immediate: DELETE /v1/subscriptions/{subUid} sets the subscription's status to cancelled. There are no cancelAt, immediate, or period_end modes and no currentPeriodEnd concept.

Failed charges​

When a scheduled charge fails, retries are governed per-plan by dailyAttempts and intervalAttempt (plus an optional graceDays window). Once attempts are exhausted the subscription transitions to inactive. See Scheduled charges → Retry schedule.

Reactivation​

A cancelled or inactive subscription cannot be un-cancelled or reactivated through the API. A new subscription is created via the verify-card flow with shouldCreateSubscription: true, tied to a new transaction.

Notifications​

The subscription flow sends email notifications (notifyEvent) and a merchant callback (subsCallback) rather than a public outbound webhook contract. See Subscriptions → Notifications.