Plan switch (downgrade)

What this offer does

Plan switch moves the customer to a cheaper monthly plan you’ve pre-approved. The new price takes effect on their next invoice — no immediate charge or credit. See The five offers — Plan-switch for the full description.

Plan switch is monthly downgrade-only at launch. Annual subscriptions and cross-cadence switches aren’t supported yet.

Configuration

In your Unchurn dashboard, under Widget → Switch plan, you set up the approved downgrade map. The map connects each current price ID to a list of allowed target price IDs:

The widget reads the customer’s current price ID, looks it up in allowed_transitions, and shows one tile per target price (capped at 3 tiles). If the customer’s current price has no entry, the offer is hidden.

What counts as a valid transition

For a target to be available, it must be:

• Strictly cheaper than the current price (unit_amount lower)
• Same cadence (monthly, both interval='month')
• Same currency and same tax_behavior
• A licensed per-unit price (not metered, not tiered)

Targets that don’t pass these checks are filtered out when the cancel flow opens. If the filtered list is empty, the offer is hidden.

Proration is locked to none

We always send proration_behavior: 'none' to Stripe. The customer isn’t billed or credited at switch time — the new price applies on their next scheduled invoice.

What gets called on Stripe

When the customer accepts, we swap the subscription item to the target price:

// app/lib/offers/plan-switch.ts
await stripe.subscriptions.update(subscriptionId, {
  items: [{ id: currentItem.id, price: targetPriceId, quantity: currentQuantity }],
  proration_behavior: 'none',
});

The customer isn’t billed or credited at switch time. The new price applies on the next scheduled invoice after Stripe confirms the item changed. See the Stripe subscriptions update reference .

When this offer is hidden

The widget hides the plan-switch tile for annual or non-monthly subscriptions, multi-item subscriptions, subscriptions with automatic_tax, and subscriptions where no allowed transition leads to a strictly cheaper same-cadence target. See Supported subscriptions for the complete list.

Common configurations

One downgrade per top-tier plan. Start with a single target per source — fewer choices typically converts better.

{
  "plan_switch": {
    "enabled": true,
    "allowed_transitions": {
      "price_pro_monthly": ["price_starter_monthly"],
      "price_team_monthly": ["price_pro_monthly"]
    }
  }
}

Multiple downgrades from a top tier. Useful when you have a clearly differentiated mid and budget tier.

{
  "plan_switch": {
    "enabled": true,
    "allowed_transitions": {
      "price_team_monthly": ["price_pro_monthly", "price_starter_monthly"]
    }
  }
}

Pitfalls

• The switch takes effect immediately, not at period end. Stripe applies the item swap right away. proration_behavior: 'none' stops the proration math, but the subscription is on the new price the moment the customer accepts.
• A deleted target price breaks that transition. Confirm target price IDs are still active in Stripe before publishing config changes.
• Cross-currency or cross-cadence targets are silently dropped. If you configure a transition that fails the same-cadence or same-currency check, the offer is hidden and the dashboard records the reason.

Next steps

• Discount — the typical fallback when plan switch is unavailable
• The five offers — the conceptual overview
• Supported subscriptions — full eligibility rules