> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metrifox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription Cancel Scheduled

## 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

<Note>
  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.
</Note>

## Payload Structure

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440006",
  "type": "subscription.cancel_scheduled",
  "created_at": 1704067560000,
  "data": {
   "subscription": {
      "id": "sub_12345",
      "customer_id": "cust_67890",
      "customer_key": "cust_ext_67890",
      "tenant_id": "tenant_abc",
      "order_id": "order_001",
      "plan_id": "plan_456",
      "status": "active",
      "currency_code": "USD",
      "subscription_number": "sub_123",
      "starts_at": "2026-01-01T00:00:00.000Z",
      "ends_at": "2026-02-01T00:00:00.000Z",
      "renews_at": "2026-02-01T00:00:00.000Z",
      "paused_at": null,
      "cancelled_at": "2026-01-20T00:00:00.000Z",
      "metadata": {},
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z",
      "price_option_id": "price_opt_001",
      "trial_end_date": null,
      "converted_at": null,
      "billing_interval": "month",
      "billing_interval_value": 1,
      "renew_date_anchor": 1
    }
  }
}
```

## Data Fields

The `data.subscription` object contains the subscription record with scheduling details:

* `id`: Internal subscription ID
* `customer_id`: ID of the customer who owns the subscription
* `customer_key`: Your external customer identifier
* `tenant_id`: The tenant ID this subscription belongs to
* `order_id`: Order ID that created the subscription
* `plan_id`: ID of the plan associated with this subscription
* `status`: Subscription status
* `currency_code`: Currency code (e.g., "USD", "NGN")
* `subscription_number`: Subscription number
* `starts_at`: Subscription start timestamp
* `ends_at`: Subscription end timestamp (if scheduled to end)
* `renews_at`: Next renewal timestamp
* `paused_at`: Pause timestamp (if paused)
* `cancelled_at`: Cancellation timestamp (if cancelled)
* `metadata`: Custom metadata object
* `created_at`: Timestamp when the subscription was created
* `updated_at`: Timestamp when the subscription was last updated
* `price_option_id`: Price option ID
* `trial_end_date`: Trial end timestamp (if applicable)
* `converted_at`: Conversion timestamp (if converted)
* `billing_interval`: Billing interval (e.g., "month")
* `billing_interval_value`: Billing interval value
* `renew_date_anchor`: Renewal day of month anchor

<Note>
  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.
</Note>

## 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