Stripe Proration Edge Cases on Mid-Cycle Plan Changes

One helper, one call path

Every mid-cycle plan change has to pass through one helper. Not three places in the codebase. Not the dashboard. One helper that takes the inputs the product team actually thinks about — from_plan, to_plan, effective_at (now or period_end), bill_immediately (yes or no), preserve_trial (yes or no) — and translates those into the exact Stripe call. Everything else routes through it, including the admin panel, the customer-facing self-service upgrade, and the internal CLI that account managers use to comp accounts.

The reason this matters is that the four Stripe levers — proration_behavior, proration_date, billing_cycle_anchor, and trial_end — interact non-obviously. The helper centralizes that interaction in one place where you can write tests for every combination, log the inputs, and change the policy globally when product changes its mind. Without it, every developer adding a new upgrade path makes the same decisions over again, and one of them gets it wrong.

Lever one: proration_behavior

The first lever is proration_behavior. The API documents three values: create_prorations (the default), always_invoice, and none. The default creates proration items but only invoices them under certain conditions, which in practice means they land on the next regular invoice. always_invoice creates the prorations and immediately tries to collect payment. none skips proration entirely and bills the new price at the next cycle. Picking the right one is a policy decision, not a technical one — but if you do not pick, you get create_prorations, and that is the default that produces most of the "why did my upgrade not charge me?" tickets.

Lever two: proration_date

The second lever is proration_date. Stripe prorates to the second, so the prorated amount can differ between the preview and the update if any time passes between them. On a high-value plan, that drift is real money. The helper should preview the invoice, pin the moment with a Unix timestamp, show the customer the exact number, and then pass the same timestamp to the update call so the actual invoice matches the quote to the cent.

Lever three: billing_cycle_anchor

The third lever is billing_cycle_anchor. Most plan changes leave it alone. The cases where you do touch it are the trial-end transition (the default behavior resets the anchor to the trial end, which is what you usually want) and a deliberate "restart the billing cycle on plan change" policy (rare, but valid for products that bill on calendar months). Touching it accidentally is a frequent bug source — passing billing_cycle_anchor=now on what you thought was a simple price change resets the cycle and surprises the customer.

Lever four: trial_end

The fourth lever is trial_end. If the customer is on a trial and you call subscriptions.update to change the price without setting trial_end, the behavior depends on the API version and the specific call shape — sometimes the trial survives, sometimes it ends, sometimes the new price's own trial settings take over. The safe default is to read the current trial_end, preserve it across the update if the policy is "trial survives plan changes," and explicitly clear it (trial_end=now) if the policy is "upgrading ends the trial."

Helper shape

Here is the shape of the helper:

type PlanChangeInput = {
  subscriptionId: string;
  fromPriceId: string;
  toPriceId: string;
  effective: "now" | "period_end";
  billImmediately: boolean;
  preserveTrial: boolean;
};

type PlanChangePreview = {
  prorationDate: number; // unix seconds, pinned
  immediateCharge: number; // cents, 0 if no immediate invoice
  nextInvoiceTotal: number; // cents on next regular invoice
  nextInvoiceDate: number; // unix seconds
  trialEndAfter: number | null;
};

async function previewPlanChange(
  input: PlanChangeInput,
): Promise<PlanChangePreview> {
  const sub = await stripe.subscriptions.retrieve(input.subscriptionId);
  const prorationDate = Math.floor(Date.now() / 1000);

  if (input.effective === "period_end") {
    // Schedules don't proration — they swap at the boundary.
    // Preview returns the upcoming invoice as-is.
    const upcoming = await stripe.invoices.retrieveUpcoming({
      subscription: input.subscriptionId,
    });
    return {
      prorationDate,
      immediateCharge: 0,
      nextInvoiceTotal: upcoming.amount_due,
      nextInvoiceDate: upcoming.period_end,
      trialEndAfter: input.preserveTrial ? (sub.trial_end ?? null) : null,
    };
  }

  const itemId = sub.items.data.find(
    (i) => i.price.id === input.fromPriceId,
  )?.id;
  if (!itemId) throw new Error("from_price_id not on subscription");

  const upcoming = await stripe.invoices.retrieveUpcoming({
    subscription: input.subscriptionId,
    subscription_items: [{ id: itemId, price: input.toPriceId }],
    subscription_proration_date: prorationDate,
    subscription_proration_behavior: input.billImmediately
      ? "always_invoice"
      : "create_prorations",
    subscription_trial_end: input.preserveTrial
      ? (sub.trial_end ?? undefined)
      : "now",
  });

  // immediateCharge is what always_invoice would bill right now;
  // nextInvoiceTotal is what create_prorations would defer.
  const prorationLines = upcoming.lines.data.filter(
    (l) => l.proration === true,
  );
  const prorationTotal = prorationLines.reduce(
    (sum, l) => sum + l.amount,
    0,
  );

  return {
    prorationDate,
    immediateCharge: input.billImmediately ? prorationTotal : 0,
    nextInvoiceTotal: upcoming.amount_due,
    nextInvoiceDate: upcoming.period_end,
    trialEndAfter: input.preserveTrial ? (sub.trial_end ?? null) : null,
  };
}

The corresponding applyPlanChange takes the same input plus the prorationDate from the preview, so the customer is invoiced for the exact number they were quoted:

async function applyPlanChange(
  input: PlanChangeInput,
  prorationDate: number,
): Promise<Stripe.Subscription> {
  const sub = await stripe.subscriptions.retrieve(input.subscriptionId);
  const itemId = sub.items.data.find(
    (i) => i.price.id === input.fromPriceId,
  )?.id;
  if (!itemId) throw new Error("from_price_id not on subscription");

  if (input.effective === "period_end") {
    // Create a subscription schedule that holds the current plan
    // until period end, then transitions to the new plan.
    const schedule = await stripe.subscriptionSchedules.create({
      from_subscription: input.subscriptionId,
    });
    const currentPhase = schedule.phases[0];
    return stripe.subscriptionSchedules.update(schedule.id, {
      phases: [
        {
          items: [{ price: input.fromPriceId, quantity: 1 }],
          start_date: currentPhase.start_date,
          end_date: currentPhase.end_date,
          proration_behavior: "none",
        },
        {
          items: [{ price: input.toPriceId, quantity: 1 }],
          proration_behavior: "none",
        },
      ],
    }) as unknown as Stripe.Subscription;
  }

  return stripe.subscriptions.update(input.subscriptionId, {
    items: [{ id: itemId, price: input.toPriceId }],
    proration_date: prorationDate,
    proration_behavior: input.billImmediately
      ? "always_invoice"
      : "create_prorations",
    trial_end: input.preserveTrial
      ? (sub.trial_end ?? undefined)
      : "now",
  });
}

Audit logging on every call site

Every call site logs the full PlanChangeInput, the returned PlanChangePreview, the actual Stripe response, and the customer's billing_mode. When the customer-support ticket arrives three weeks later asking why they were billed $47, the audit row has every input that produced that number.