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

# Subscription Lifecycle

> How subscriptions start, pause, resume, and cancel — and what each transition means for billing.

A subscription links a customer to a billing plan and drives the entire billing cycle. This guide covers every state a subscription can be in and how to move between them.

## Status overview

```mermaid theme={null}
stateDiagram-v2
    [*] --> active : create

    active --> paused
    active --> canceled

    paused --> active
    paused --> canceled
```

| Status     | Description                                                                                       |
| ---------- | ------------------------------------------------------------------------------------------------- |
| `active`   | The subscription is running. Events accumulate and invoices are generated at period end.          |
| `paused`   | No new events are counted and no invoice is generated until the subscription is resumed.          |
| `canceled` | The subscription has ended. The current period's usage is invoiced and no further billing occurs. |

***

## Creating a subscription

Subscriptions start immediately when created. The first billing period begins at the moment of creation.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.monigo.co/v1/subscriptions \
    -H "Authorization: Bearer mk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "customer_id": "<customer_id>",
      "plan_id": "<plan_id>"
    }'
  ```

  ```go Go theme={null}
  sub, err := client.Subscriptions.Create(ctx, monigo.CreateSubscriptionRequest{
      CustomerID: customerID,
      PlanID:     planID,
  })
  ```

  ```ts TypeScript theme={null}
  const sub = await client.subscriptions.create({
    customer_id: customerId,
    plan_id: planId,
  })
  ```
</CodeGroup>

**Response fields to note:**

| Field                  | Description                                             |
| ---------------------- | ------------------------------------------------------- |
| `id`                   | The subscription UUID — required for invoice generation |
| `status`               | Always `active` on creation                             |
| `current_period_start` | When the first billing period began                     |
| `current_period_end`   | When the first invoice will be generated                |
| `trial_ends_at`        | Present only if the plan has `trial_period_days > 0`    |

***

## Querying subscriptions

Fetch a single subscription or list subscriptions filtered by customer, plan, or status.

<CodeGroup>
  ```bash cURL theme={null}
  # Get one subscription
  curl https://api.monigo.co/v1/subscriptions/<subscription_id> \
    -H "Authorization: Bearer mk_live_..."

  # List active subscriptions for a customer
  curl "https://api.monigo.co/v1/subscriptions?customer_id=<customer_id>&status=active" \
    -H "Authorization: Bearer mk_live_..."
  ```

  ```go Go theme={null}
  // Get one
  sub, err := client.Subscriptions.Get(ctx, subscriptionID)

  // List by customer
  list, err := client.Subscriptions.List(ctx, monigo.ListSubscriptionsParams{
      CustomerID: customerID,
      Status:     monigo.SubscriptionStatusActive,
  })
  ```

  ```ts TypeScript theme={null}
  // Get one
  const sub = await client.subscriptions.get(subscriptionId)

  // List by customer
  const list = await client.subscriptions.list({
    customer_id: customerId,
    status: SubscriptionStatus.Active,
  })
  ```
</CodeGroup>

***

## Pausing a subscription

Pausing freezes billing without ending the customer relationship. While paused:

* Incoming events are **still ingested** and stored
* Those events are **not included** in any invoice until the subscription is resumed
* No invoice is generated at period end

Use pausing for grace periods, customer-initiated downtimes, or when a payment fails and you want to give the customer time to update their payment method.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.monigo.co/v1/subscriptions/<subscription_id>/pause \
    -H "Authorization: Bearer mk_live_..."
  ```

  ```go Go theme={null}
  sub, err := client.Subscriptions.Pause(ctx, subscriptionID)
  ```

  ```ts TypeScript theme={null}
  const sub = await client.subscriptions.pause(subscriptionId)
  ```
</CodeGroup>

***

## Resuming a subscription

Resuming an `active` billing period. Usage accumulated while paused is included in the next invoice.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.monigo.co/v1/subscriptions/<subscription_id>/resume \
    -H "Authorization: Bearer mk_live_..."
  ```

  ```go Go theme={null}
  sub, err := client.Subscriptions.Resume(ctx, subscriptionID)
  ```

  ```ts TypeScript theme={null}
  const sub = await client.subscriptions.resume(subscriptionId)
  ```
</CodeGroup>

***

## Canceling a subscription

Canceling ends the subscription. Monigo generates a final invoice for all usage accumulated in the current period up to the cancellation time.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.monigo.co/v1/subscriptions/<subscription_id>/cancel \
    -H "Authorization: Bearer mk_live_..."
  ```

  ```go Go theme={null}
  sub, err := client.Subscriptions.Cancel(ctx, subscriptionID)
  ```

  ```ts TypeScript theme={null}
  const sub = await client.subscriptions.cancel(subscriptionId)
  ```
</CodeGroup>

<Warning>
  Cancellation is immediate and irreversible. If you need to temporarily stop billing, use **pause** instead. A canceled subscription cannot be reactivated — you would need to create a new subscription.
</Warning>

After cancellation:

1. A final invoice is generated for the partial period
2. The invoice is finalized and sent for collection
3. The `subscription.canceled` webhook is fired
4. No further events are attributed to this subscription

***

## Webhook events

Subscribe to these events in **Dashboard → Webhooks** to react to subscription state changes:

| Event                       | Fired when                             |
| --------------------------- | -------------------------------------- |
| `subscription.created`      | A new subscription is created          |
| `subscription.paused`       | A subscription is paused               |
| `subscription.resumed`      | A paused subscription is resumed       |
| `subscription.canceled`     | A subscription is canceled             |
| `subscription.trial_ending` | The trial period is 3 days from ending |

***

## Related

* [Billing Cycle](/concepts/billing-cycle) — how periods advance and invoices are triggered
* [Invoice Lifecycle](/guides/invoice-lifecycle) — what happens to the invoices a subscription generates
* [Webhooks](/integrations/webhooks) — full event catalog and signature verification