Subscription Lifecycle

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

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.

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>"
  }'

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

const sub = await client.subscriptions.create({
  customer_id: customerId,
  plan_id: planId,
})

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.

# 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_..."

// 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,
})

// Get one
const sub = await client.subscriptions.get(subscriptionId)

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

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.

curl -X POST https://api.monigo.co/v1/subscriptions/<subscription_id>/pause \
  -H "Authorization: Bearer mk_live_..."

sub, err := client.Subscriptions.Pause(ctx, subscriptionID)

const sub = await client.subscriptions.pause(subscriptionId)

Resuming a subscription

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

curl -X POST https://api.monigo.co/v1/subscriptions/<subscription_id>/resume \
  -H "Authorization: Bearer mk_live_..."

sub, err := client.Subscriptions.Resume(ctx, subscriptionID)

const sub = await client.subscriptions.resume(subscriptionId)

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.

curl -X POST https://api.monigo.co/v1/subscriptions/<subscription_id>/cancel \
  -H "Authorization: Bearer mk_live_..."

sub, err := client.Subscriptions.Cancel(ctx, subscriptionID)

const sub = await client.subscriptions.cancel(subscriptionId)

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.

After cancellation:

A final invoice is generated for the partial period
The invoice is finalized and sent for collection
The subscription.canceled webhook is fired
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

Billing Cycle — how periods advance and invoices are triggered
Invoice Lifecycle — what happens to the invoices a subscription generates
Webhooks — full event catalog and signature verification

Get Started

Concepts

Guides

SDKs

Integrations

API Reference

Subscription Lifecycle

Status overview

Creating a subscription

Querying subscriptions

Pausing a subscription

Resuming a subscription

Canceling a subscription

Webhook events

​Status overview

​Creating a subscription

​Querying subscriptions

​Pausing a subscription

​Resuming a subscription

​Canceling a subscription

​Webhook events

​Related

Status overview

Creating a subscription

Querying subscriptions

Pausing a subscription

Resuming a subscription

Canceling a subscription

Webhook events

Related