Skip to main content

​
Overview

The subscription.cancel_scheduled webhook is triggered when a subscription is scheduled to be cancelled at the end of the current billing period, rather than being cancelled immediately.

​
When It’s Triggered

This event is sent immediately after a subscription cancellation is scheduled, which can happen when:
  • A customer schedules their subscription to cancel at period end
  • A subscription cancellation is scheduled through the API
  • A subscription cancellation is scheduled manually in the dashboard
This event is different from subscription.cancelled, which is sent when a subscription is cancelled immediately. This event indicates the subscription will remain active until the end of the current billing period.

​
Payload Structure

{
  "id": "550e8400-e29b-41d4-a716-446655440006",
  "type": "subscription.cancel_scheduled",
  "created_at": 1704067560000,
  "data": {
    "subscription": {
      "id": "101",
      "subscription_key": "sub_abc123",
      "customer_id": "123",
      "customer_key": "cust_abc123",
      "plan_id": "plan_456",
      "plan_name": "Pro Plan",
      "status": "active",
      "billing_interval": "monthly",
      "cancel_at_period_end": true,
      "scheduled_cancel_at": "2024-02-01T00:00:00Z",
      "current_period_start": "2024-01-01T00:00:00Z",
      "current_period_end": "2024-02-01T00:00:00Z",
      "tenant_id": "456",
      "created_at": "2024-01-01T00:04:00Z",
      "updated_at": "2024-01-01T00:06:00Z"
      // ... other subscription fields
    }
  }
}

​
Data Fields

The data.subscription object contains the subscription record with scheduling details:
  • id: Internal subscription ID
  • subscription_key: Unique subscription identifier
  • customer_id: ID of the customer who owns the subscription
  • customer_key: Customer key
  • plan_id: ID of the plan that will be cancelled
  • plan_name: Name of the plan
  • status: Subscription status (typically still “active” until cancellation)
  • billing_interval: Billing frequency
  • cancel_at_period_end: Boolean indicating cancellation is scheduled
  • scheduled_cancel_at: Timestamp when the subscription will be cancelled
  • current_period_start: Start date of the current billing period
  • current_period_end: End date of the current billing period (when cancellation will occur)
  • tenant_id: The tenant ID this subscription belongs to
  • created_at: Original timestamp when the subscription was created
  • updated_at: Timestamp when the cancellation was scheduled
  • Additional subscription-specific fields
The subscription remains active and the customer retains access until current_period_end. After that date, the subscription will be cancelled and a subscription.cancelled event will be sent.

​
Example Use Cases

  • Send cancellation scheduled confirmation emails
  • Trigger retention campaigns before the cancellation date
  • Update internal systems with scheduled cancellation information
  • Set reminders to follow up with the customer
  • Update analytics and forecasting