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
┌─────────────────────────────┐
│ │
create ─→ active ─→ paused ─→ active ─→ canceled
│ │
└──────────── 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.
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>"
}'
| 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_..."
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_..."
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_..."
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_..."
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.
- 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
