> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fype.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle

# 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

```mermaid theme={null}
stateDiagram-v2
    [*] --> created : API Request (POST /subscriptions)
    created --> trialing : Mandate Authorized (Trial Period > 0)
    created --> active : Mandate Authorized (Trial Period = 0)
    created --> cancelled : Checkout Abandoned / Fail to Authorize
    trialing --> active : Trial Ends & Successful Charge
    trialing --> past_due : Trial Ends & Payment Fails
    trialing --> cancelled : Trial Ended & Cancelled
    active --> paused : API Pause Command
    active --> past_due : Webhook Recurring Charge Failed
    active --> cancelled : API Cancel Command / Cancel at Period End
    active --> completed : Sub Terminated / Term End
    paused --> active : API Resume Command
    paused --> cancelled : API Cancel Command
    past_due --> active : Webhook Payment Succeeded
    past_due --> halted : Max Retries Exceeded / Hard Failure
    past_due --> cancelled : API Cancel Command
    halted --> cancelled : API Cancel Command
    cancelled --> [*]
    completed --> [*]
```

### State Explanations:

1. **`created`**: The subscription intent is registered, and a hosted checkout URL is generated. Awaiting customer authorization.
2. **`trialing`**: Customer successfully authorized the mandate and has a trial period remaining.
3. **`active`**: Mandate is authorized, and the subscription is billed actively.
4. **`paused`**: Billing is temporarily paused. The mandate remains active on the gateway, but recurring charges are deferred.
5. **`past_due`**: A recurring payment attempt failed. Fype is actively retrying the transaction.
6. **`halted`**: All retries failed. The subscription remains registered but is blocked from further service provision.
7. **`cancelled`**: The subscription is permanently cancelled and cannot be resumed.
8. **`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**:

```json theme={null}
[
  {
    "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"
  }
]
```