Subscription Lifecycle & State Machine

Subscriptions in Fype are governed by a deterministic state machine that tracks the status of customer payment mandates from creation to termination.

State Machine State Diagram

State Explanations:

created: The subscription intent is registered, and a hosted checkout URL is generated. Awaiting customer authorization.
trialing: Customer successfully authorized the mandate and has a trial period remaining.
active: Mandate is authorized, and the subscription is billed actively.
paused: Billing is temporarily paused. The mandate remains active on the gateway, but recurring charges are deferred.
past_due: A recurring payment attempt failed. Fype is actively retrying the transaction.
halted: All retries failed. The subscription remains registered but is blocked from further service provision.
cancelled: The subscription is permanently cancelled and cannot be resumed.
completed: The subscription reached its scheduled end date or max cycles.

Lifecycle Operations

Fype provides endpoints to transition subscription states via API or the Dashboard.

1. Pausing Subscriptions

Pauses billing cycles for an active subscription. Mandates remain active on the gateway, but automatic billing cycles are temporarily deferred.

Endpoint: POST /subscriptions/{id}/pause
SDK: fype.subscriptions.pause(subscription_id)

2. Resuming Subscriptions

Resumes billing cycles for a paused subscription.

Endpoint: POST /subscriptions/{id}/resume
SDK: fype.subscriptions.resume(subscription_id)

3. Cancelling Subscriptions

Terminates a subscription. You can cancel immediately or schedule cancellation for the end of the current billing cycle.

Endpoint: POST /subscriptions/{id}/cancel?cancel_at_period_end=true
SDK: fype.subscriptions.cancel(subscription_id, cancel_at_period_end=True)
Behavior:
- cancel_at_period_end=true: The status remains active but updates cancel_at_period_end = true. When the current billing period ends, the status changes to cancelled and webhook event subscription.cancelled is fired.
- cancel_at_period_end=false (Default): Subscription terminates immediately at both the gateway and Fype.

State Transition Audit Logs

Fype records every state transition, the user/system action that triggered it, and the database event reference.

Endpoint: GET /subscriptions/{id}/events
SDK: fype.subscriptions.getEvents(subscription_id) (Node.js) / fype.subscriptions.get_events(subscription_id=...) (Python)
Response Structure:

[
  {
    "id": "event_uuid",
    "subscription_id": "sub_uuid",
    "from_state": "active",
    "to_state": "past_due",
    "triggered_by": "webhook",
    "event_type": "subscription.payment_failed",
    "metadata_json": {
      "gateway_decline_reason": "insufficient_funds",
      "retry_attempt": 1
    },
    "created_at": "2026-06-24T01:23:55Z"
  }
]

​Subscription Lifecycle & State Machine

​State Machine State Diagram

​State Explanations:

​Lifecycle Operations

​1. Pausing Subscriptions

​2. Resuming Subscriptions

​3. Cancelling Subscriptions

​State Transition Audit Logs