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

# subscription.plan_changed

> A live subscription has been moved onto a different payment plan.

# subscription.plan\_changed

> Generated from COPE public event contracts. Do not edit this page by hand.

Use this event to follow a subscription that changed plan rather than price — the sibling of subscription.amount\_changed, which announces a new amount on the SAME plan. The switch is applied in place with no proration; the new plan's amount bills at the existing cycle boundary, and the currency does not move. A plan on another cadence starts it at that same boundary: the period already paid for is kept, and nothing is charged until then. `new_plan` is the plan the subscription now runs on; `old_plan` is the plan it moved off, and null when no recorded fact names that plan. `effective_at` is a prediction on the same terms as subscription.amount\_changed. The body names the business, the order, the line item and the subscription, each as `object` and `id`; store `subscription.id` to match later events on the same subscription, and read everything else about them through the API.

## Delivery Contract

| Field        | Value                                                                                                   |
| ------------ | ------------------------------------------------------------------------------------------------------- |
| Encoding     | JSON: `id`, `type`, `version`, `source`, `created_at`, `data`                                           |
| Delivery     | At least once                                                                                           |
| Idempotency  | Deduplicate on `id`: every retry and replay of this event repeats it, and `X-Cope-Event-Id` carries it. |
| Source       | `cope.subscription`                                                                                     |
| Category     | Subscriptions                                                                                           |
| Availability | Available in the public webhook reference.                                                              |
| Schema title | subscription.plan\_changed webhook body                                                                 |
| Schema ID    | `https://schemas.cope.com/webhooks/subscription.plan_changed/v1`                                        |

## Payload Fields

| Field                        | Required | Type      | Allowed Values | Description                                                                               |                                                                                                                                                                                             |
| ---------------------------- | -------- | --------- | -------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `business`                   | no       | `object`  | -              | The business that sold the subscription.                                                  |                                                                                                                                                                                             |
| `currency`                   | yes      | `string`  | -              | ISO 4217 currency code of both amounts.                                                   |                                                                                                                                                                                             |
| `effective_at`               | yes      | \`string  | null\`         | -                                                                                         | The renewal the new amount first bills. A prediction taken at the time of the change; the charge itself is the confirmation. Null when no renewal date is known.                            |
| `line_item`                  | no       | `object`  | -              | The order line the subscription belongs to.                                               |                                                                                                                                                                                             |
| `new_plan`                   | no       | `object`  | -              | The plan the subscription now runs on.                                                    |                                                                                                                                                                                             |
| `new_recurring_amount_cents` | yes      | `integer` | -              | What the buyer is billed per cycle from effective\_at, in minor units, quantity included. |                                                                                                                                                                                             |
| `old_plan`                   | no       | \`object  | null\`         | -                                                                                         | The plan the subscription moved off. Null when no recorded fact names that plan — for example, terms sold through an offer, a plan since deleted, or terms from before plans were recorded. |
| `old_recurring_amount_cents` | yes      | `integer` | -              | What the buyer was billed per cycle before the change, in minor units, quantity included. |                                                                                                                                                                                             |
| `order`                      | no       | `object`  | -              | The order the subscription was bought on.                                                 |                                                                                                                                                                                             |
| `subscription`               | no       | `object`  | -              | The subscription. Absent when the event names no subscription id of the right shape.      |                                                                                                                                                                                             |

## Example delivery

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "created_at": "2026-04-20T11:02:46Z",
  "data": {
    "business": {
      "id": "biz_g7-Jq2PxT_4mRvNa",
      "object": "business"
    },
    "currency": "EUR",
    "effective_at": "2026-05-01T08:00:00Z",
    "line_item": {
      "id": "li_4nHs8QwZ2pLk7XcY",
      "object": "line_item"
    },
    "new_plan": {
      "id": "plan_Yr8K2vPd",
      "object": "payment_plan"
    },
    "new_recurring_amount_cents": 9900,
    "old_plan": {
      "id": "plan_Hn4W7sQe",
      "object": "payment_plan"
    },
    "old_recurring_amount_cents": 5900,
    "order": {
      "id": "ord_V7kP2mQx9RtL",
      "object": "order"
    },
    "subscription": {
      "id": "ps_Gm3Tq8ZrW1bN",
      "object": "subscription"
    }
  },
  "id": "6e0b4d8a-7f2c-4b19-8d36-1a9c5e7f2b40",
  "source": "cope.subscription",
  "type": "subscription.plan_changed",
  "version": "v1"
}
```

## Compatibility

Fields may be added within the same major version. Removing or changing the meaning of a documented field requires a new event version.