Action guide

Prove a customer moved from plan X to plan Y, and when

POST/v1/events · subscription.upgraded

Emit a `subscription.upgraded` event every time a customer moves to a higher-tier plan. Keep the from/to plan slugs in metadata for cohort analysis.

Start logging for free Open the playground

When to emit

After the provider confirms the subscription update and your own DB is in sync.

Example payload

await recalled.events.create({
  action: "subscription.upgraded",
  actor: { id: user.id, email: user.email },
  organization: user.organizationId,
  metadata: {
    fromPlan: "value",
    toPlan: "value",
    mrrDelta: "value"
  },
});

Metadata to include

Keep metadata flat and consistent across your service so it plays well with search and CSV exports.

Key	Purpose
`fromPlan`	Plan slug before the change
`toPlan`	Plan slug after the change
`mrrDelta`	Monthly recurring revenue delta in smallest unit

Suggested retention

Keep forever, plan change history is priceless for churn and LTV analysis.

Related actions

Log subscription cancellations

subscription.cancelled

Log paid invoices

invoice.paid