Subscription Events

subscription_created

Fires when a subscription is created, through POST /v1/subscriptions, or when a checkout that binds a plan settles. Emitted by SubscriptionService.create and CheckoutSettlement.

{
  "id": "evt_01hkbz5created0000000000000",
  "type": "subscription_created",
  "createdAt": "2026-06-28T09:00:00.000Z",
  "data": {
    "subscription": {
      "id": "sub_01hkbz3m4n5p6q7r8s9t0v1w2x",
      "status": "incomplete",
      "customerId": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "planId": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "currentPeriodStart": "2026-06-28T09:00:00.000Z",
      "currentPeriodEnd": "2027-06-28T09:00:00.000Z",
      "trialEndsAt": null
    },
    "customer": {
      "id": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "+2348012345678"
    },
    "plan": {
      "id": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "name": "Pro Annual",
      "amount": 500000,
      "currency": "NGN",
      "interval": "year",
      "intervalCount": 1
    }
  }
}

subscription_activated

Fires when a subscription becomes active: a trial converts, or the first charge succeeds. Emitted via the state machine (activate).

{
  "id": "evt_01hkbz5activated000000000000",
  "type": "subscription_activated",
  "createdAt": "2026-06-28T09:05:00.000Z",
  "data": {
    "subscription": {
      "id": "sub_01hkbz3m4n5p6q7r8s9t0v1w2x",
      "status": "active",
      "customerId": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "planId": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "currentPeriodStart": "2026-06-28T09:00:00.000Z",
      "currentPeriodEnd": "2027-06-28T09:00:00.000Z",
      "trialEndsAt": null
    },
    "customer": {
      "id": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "+2348012345678"
    },
    "plan": {
      "id": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "name": "Pro Annual",
      "amount": 500000,
      "currency": "NGN",
      "interval": "year",
      "intervalCount": 1
    }
  }
}

subscription_updated

Fires when a mutable field changes without a status transition. Today that is setting cancel-at-period-end. The changed flag is carried alongside the subscription.

{
  "id": "evt_01hkbz5updated00000000000000",
  "type": "subscription_updated",
  "createdAt": "2026-06-28T10:00:00.000Z",
  "data": {
    "cancelAtPeriodEnd": true,
    "subscription": {
      "id": "sub_01hkbz3m4n5p6q7r8s9t0v1w2x",
      "status": "active",
      "customerId": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "planId": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "currentPeriodStart": "2026-06-28T09:00:00.000Z",
      "currentPeriodEnd": "2027-06-28T09:00:00.000Z",
      "trialEndsAt": null
    },
    "customer": {
      "id": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "+2348012345678"
    },
    "plan": {
      "id": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "name": "Pro Annual",
      "amount": 500000,
      "currency": "NGN",
      "interval": "year",
      "intervalCount": 1
    }
  }
}

subscription_plan_changed

Fires when a subscription’s plan changes: immediately via POST /v1/subscriptions/{id}/change-plan (carries fromPlanId, toPlanId, and the proration result) or when a scheduled change is applied at renewal (carries toPlanId and scheduled: true). The changed-to plan is the one expanded into plan.

{
  "id": "evt_01hkbz5planchg0000000000000",
  "type": "subscription_plan_changed",
  "createdAt": "2026-06-28T11:00:00.000Z",
  "data": {
    "fromPlanId": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
    "toPlanId": "plan_01hkbz9a8b7c6d5e4f3g2h1j0k",
    "proration": { "amount": 41096, "kind": "credit" },
    "subscription": {
      "id": "sub_01hkbz3m4n5p6q7r8s9t0v1w2x",
      "status": "active",
      "customerId": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "planId": "plan_01hkbz9a8b7c6d5e4f3g2h1j0k",
      "currentPeriodStart": "2026-06-28T09:00:00.000Z",
      "currentPeriodEnd": "2027-06-28T09:00:00.000Z",
      "trialEndsAt": null
    },
    "customer": {
      "id": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "+2348012345678"
    },
    "plan": {
      "id": "plan_01hkbz9a8b7c6d5e4f3g2h1j0k",
      "name": "Team Annual",
      "amount": 1200000,
      "currency": "NGN",
      "interval": "year",
      "intervalCount": 1
    }
  }
}

subscription_paused / subscription_resumed

Fire when a subscription is paused or resumed (POST /v1/subscriptions/{id}/pause and .../resume). Each carries just the subscription (with customer and plan). The example is subscription_paused; subscription_resumed is identical with type and status: "active".

{
  "id": "evt_01hkbz5paused00000000000000",
  "type": "subscription_paused",
  "createdAt": "2026-06-28T12:00:00.000Z",
  "data": {
    "subscription": {
      "id": "sub_01hkbz3m4n5p6q7r8s9t0v1w2x",
      "status": "paused",
      "customerId": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "planId": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "currentPeriodStart": "2026-06-28T09:00:00.000Z",
      "currentPeriodEnd": "2027-06-28T09:00:00.000Z",
      "trialEndsAt": null
    },
    "customer": {
      "id": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "+2348012345678"
    },
    "plan": {
      "id": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "name": "Pro Annual",
      "amount": 500000,
      "currency": "NGN",
      "interval": "year",
      "intervalCount": 1
    }
  }
}

subscription_past_due

Fires when a renewal charge fails and the subscription moves to past_due; dunning has begun. Emitted by the state machine (renewal_failed) from the dunning service.

{
  "id": "evt_01hkbz5pastdue0000000000000",
  "type": "subscription_past_due",
  "createdAt": "2026-07-28T09:00:00.000Z",
  "data": {
    "subscription": {
      "id": "sub_01hkbz3m4n5p6q7r8s9t0v1w2x",
      "status": "past_due",
      "customerId": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "planId": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "currentPeriodStart": "2026-06-28T09:00:00.000Z",
      "currentPeriodEnd": "2027-06-28T09:00:00.000Z",
      "trialEndsAt": null
    },
    "customer": {
      "id": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "+2348012345678"
    },
    "plan": {
      "id": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "name": "Pro Annual",
      "amount": 500000,
      "currency": "NGN",
      "interval": "year",
      "intervalCount": 1
    }
  }
}

subscription_recovered

Fires when dunning wins and a past_due subscription returns to active. Emitted by the state machine (recover).

{
  "id": "evt_01hkbz5recovrd0000000000000",
  "type": "subscription_recovered",
  "createdAt": "2026-07-29T09:00:00.000Z",
  "data": {
    "subscription": {
      "id": "sub_01hkbz3m4n5p6q7r8s9t0v1w2x",
      "status": "active",
      "customerId": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "planId": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "currentPeriodStart": "2026-06-28T09:00:00.000Z",
      "currentPeriodEnd": "2027-06-28T09:00:00.000Z",
      "trialEndsAt": null
    },
    "customer": {
      "id": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "+2348012345678"
    },
    "plan": {
      "id": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "name": "Pro Annual",
      "amount": 500000,
      "currency": "NGN",
      "interval": "year",
      "intervalCount": 1
    }
  }
}

subscription_unpaid

Fires when dunning is exhausted and the subscription is written off to unpaid. Emitted by the state machine (exhaust_dunning).

{
  "id": "evt_01hkbz5unpaid00000000000000",
  "type": "subscription_unpaid",
  "createdAt": "2026-08-05T09:00:00.000Z",
  "data": {
    "subscription": {
      "id": "sub_01hkbz3m4n5p6q7r8s9t0v1w2x",
      "status": "unpaid",
      "customerId": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "planId": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "currentPeriodStart": "2026-06-28T09:00:00.000Z",
      "currentPeriodEnd": "2027-06-28T09:00:00.000Z",
      "trialEndsAt": null
    },
    "customer": {
      "id": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "+2348012345678"
    },
    "plan": {
      "id": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "name": "Pro Annual",
      "amount": 500000,
      "currency": "NGN",
      "interval": "year",
      "intervalCount": 1
    }
  }
}

subscription_cancelled

Fires on an immediate cancel (POST /v1/subscriptions/{id}/cancel). Any unused-time credit granted at cancellation is carried as creditKobo (minor units; 0 when none). Cancelling at period end emits subscription_updated instead, then subscription_cancelled when the period actually ends.

{
  "id": "evt_01hkbz5cancel00000000000000",
  "type": "subscription_cancelled",
  "createdAt": "2026-07-01T09:00:00.000Z",
  "data": {
    "creditKobo": 41096,
    "subscription": {
      "id": "sub_01hkbz3m4n5p6q7r8s9t0v1w2x",
      "status": "canceled",
      "customerId": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "planId": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "currentPeriodStart": "2026-06-28T09:00:00.000Z",
      "currentPeriodEnd": "2027-06-28T09:00:00.000Z",
      "trialEndsAt": null
    },
    "customer": {
      "id": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "+2348012345678"
    },
    "plan": {
      "id": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "name": "Pro Annual",
      "amount": 500000,
      "currency": "NGN",
      "interval": "year",
      "intervalCount": 1
    }
  }
}

subscription_expired

Fires when a subscription reaches its maxCycles and stops. Emitted by the state machine (reach_limit).

{
  "id": "evt_01hkbz5expired0000000000000",
  "type": "subscription_expired",
  "createdAt": "2029-06-28T09:00:00.000Z",
  "data": {
    "subscription": {
      "id": "sub_01hkbz3m4n5p6q7r8s9t0v1w2x",
      "status": "expired",
      "customerId": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "planId": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "currentPeriodStart": "2028-06-28T09:00:00.000Z",
      "currentPeriodEnd": "2029-06-28T09:00:00.000Z",
      "trialEndsAt": null
    },
    "customer": {
      "id": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "+2348012345678"
    },
    "plan": {
      "id": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "name": "Pro Annual",
      "amount": 500000,
      "currency": "NGN",
      "interval": "year",
      "intervalCount": 1
    }
  }
}

subscription_incomplete_expired

Fires when an incomplete subscription expires before it was ever activated (the initial payment never completed). Emitted by the state machine (expire_incomplete).

{
  "id": "evt_01hkbz5incexp00000000000000",
  "type": "subscription_incomplete_expired",
  "createdAt": "2026-06-28T10:00:00.000Z",
  "data": {
    "subscription": {
      "id": "sub_01hkbz3m4n5p6q7r8s9t0v1w2x",
      "status": "incomplete_expired",
      "customerId": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "planId": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "currentPeriodStart": "2026-06-28T09:00:00.000Z",
      "currentPeriodEnd": "2027-06-28T09:00:00.000Z",
      "trialEndsAt": null
    },
    "customer": {
      "id": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "+2348012345678"
    },
    "plan": {
      "id": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "name": "Pro Annual",
      "amount": 500000,
      "currency": "NGN",
      "interval": "year",
      "intervalCount": 1
    }
  }
}