Skip to main content

Subscription events

PaymentsAI dispatches subscription events whenever a subscription changes state. Use these events to update customer access, send notifications, and react to plan changes without polling the API.

All event names use hyphens (for example, subscription-activated, not subscription.activated).

Events​

Event typeWhen it fires
subscription-activatedThe subscription moved to active. The first payment succeeded.
subscription-canceledThe subscription was canceled (immediately or scheduled for the end of the current period).
subscription-churnedThe subscription reached the end of its grace period after failed renewals and was permanently ended.
subscription-downgradedThe subscription was moved to a lower-priced plan. See Upgrade and downgrade.
subscription-modifiedThe subscription was modified (changes other than a plan upgrade or downgrade).
subscription-reactivatedA scheduled cancellation was reversed and the subscription continues. See Subscription reactivation.
subscription-renewedA billing cycle completed and the renewal charge succeeded.
subscription-upgradedThe subscription was moved to a higher-priced plan. See Upgrade and downgrade.
subscription-items-changedThe line items on the subscription changed.
subscription-trial-changedThe trial configuration on the subscription was updated.
subscription-trial-endedThe trial period ended.
subscription-trial-end-reminderDispatched ahead of trial end. See the dedicated reference page.
subscription-renewal-reminderDispatched 7 days before a scheduled renewal. See the dedicated reference page.

Spelling note: subscription-canceled uses American single-L spelling. This matches the API enum.

Payload​

All subscription events share the same payload shape:

type Event = {
  deduplicationId: string;
  type: string;
  organizationId: string;
  metadata: Subscription;
};

See Schemas for the full Subscription type definition.

Typical sequence: first subscription with inactive instrument​

  1. Subscription is created in pending.
  2. Customer is redirected to the hosted payment form and completes the first payment.
  3. offsite-payment-completed fires when the customer finishes the hosted-form step. See Order and payment events.
  4. transaction-processed fires for the first payment. See Transaction events.
  5. subscription-activated fires when the subscription moves to active.

For a subscription created against an already-active payment instrument, transaction-processed and subscription-activated follow creation without an intermediate hosted-form step.

Typical sequence: failed renewal and recovery​

  1. Scheduled renewal charge fails → transaction-declined.
  2. Dunning retries fire further transaction-declined events on each failed attempt.
  3. Either the renewal eventually succeeds (transaction-processed → subscription-renewed), or retries are exhausted → subscription-canceled or subscription-churned.

See Dunning and retries for the full retry schedule.