Subscription lifecycle

Overview

Every Nimbus license moves through a predictable set of states. Your backend should listen for webhooks and update local entitlement records accordingly. The diagram below shows the happy path and every edge case we handle.

State machine

PENDING  ──► ACTIVE ──► GRACE ──► EXPIRED
                  │                    │
                  └──► CANCELLED ◄─────┘

ACTIVE → ACTIVE   (renewal processed)
GRACE  → ACTIVE   (payment recovered)
GRACE  → EXPIRED  (grace window exhausted)

Webhook payload

Nimbus sends a signed JSON payload to your configured endpoint. Verify the signature before processing.

{
  "event": "subscription.updated",
  "license_key": "NMB-XXXX-YYYY-ZZZZ",
  "status": "active",
  "expires_at": "2026-06-15T00:00:00Z",
  "grace_ends_at": null,
  "tier": "pro"
}

Recommended flow

1. Receive webhook → verify HMAC-SHA256 signature.
2. Upsert local license row with new status and expiry.
3. If status is expired or cancelled, disable feature flags within 60 seconds.
4. Return 200 within 2 seconds; Nimbus retries on 5xx.

Grace period handling

When a renewal payment fails, the license enters grace. Keep the product fully functional during this window. If the grace period expires without recovery, transition to expired and restrict access.