Plan cancellation request workflow

Trigger: user:plan_cancellation_request

This trigger fires when a plan cancellation request is made. This can be initiated by the user through the Kinde self-serve portal, by a billing admin on a user’s or an organization’s Billing page in the Kinde admin, or via the Kinde Management API.

This is not a deprovisioning workflow. It runs before a cancellation request is processed — including before a cancellation is scheduled for the end of a billing period.

This event is triggered when:

• the user asks to cancel their plan in the Kinde self-serve portal
• you select Cancel plan (or Cancel now) on a user’s or an organization’s Billing page in the Kinde admin
• plan cancellation is initiated via the Kinde Management API

The workflow does not run when:

• someone selects Keep plan (or calls the revert cancellation API)
• a deferred cancel is requested again on an agreement that is already scheduled

Example use cases

Link to this section

Check if customer is eligible to cancel

Link to this section

You may want to check if the customer is eligible to cancel their plan based on certain criteria, such as outstanding payments or minimum contract periods. If they are not eligible, you can prevent the cancellation and notify them.

You can also branch on event.request.cancellationTiming (immediately, min_period_end, or max_period_end) or event.request.source (self_serve_portal, admin_dashboard, or management_api).

Workflow code

Link to this section

Plan binding

Link to this section

The kinde.plan binding is used for plan related actions, such as denying a cancellation request.

Sample event object

Link to this section

The main argument provided to your code is the Kinde workflow event object which has two keys request and context. This gives you access to the reason the workflow was triggered. Here’s an example:

{
  "request": {
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:135.0) Gecko/20100101 Firefox/135.0",
    "ip": "192.168.0.1",
    "source": "self_serve_portal",
    "cancellationTiming": "min_period_end"
  },
  "context": {
    "domains": {
      "kindeDomain": "https://example.kinde.com" // Your Kinde domain
    },
    "billing": {
      "currentPlanCode": "pro",
      "agreementId": "agreement_01971a7c5c7bf2d05888a8d6c77d08ce", // the subscription ID in Kinde
      "customerId": "customer_019e3e6346421b0df4dec6c4756b4953" // the billing customer identifier
    },
    "workflow": {
      "trigger": "user:plan_cancellation_request"
    }
  }
}

cancellationTiming is the timing that will actually run. If the plan (or cancel_at) asked for a period end but Kinde has no future date to schedule against, the value is immediately.

Example workflows

Link to this section

See examples on GitHub:

Deny cancellation request - Deny a plan cancellation request from a user.