Реалізація Upgrade/Downgrade тарифу для SaaS-застосунку

SaaS: апгрейд та даунгрейд тарифного плану

Смена плану — одна з найтрикі операцій в SaaS біллінгу. Stripe обробляє пропорціональні розрахунки, але бізнес-логіка (що відбувається з даними при даунгрейді) — на стороні розробника.

Апгрейд: негайне оновлення

export async function upgradeSubscription(
  tenantId: string,
  newPriceId: string
): Promise<void> {
  const subscription = await db.subscription.findUniqueOrThrow({
    where: { tenantId }
  });

  // Stripe автоматично пересчитує
  // Приклад: залишилось 20 днів з 30, апгрейд з $29 на $99
  // Charge = (99 - 29) * 20/30 = $46.67 негайно
  const updatedSub = await stripe.subscriptions.update(
    subscription.stripeSubscriptionId!,
    {
      items: [{
        id: (await stripe.subscriptions.retrieve(
          subscription.stripeSubscriptionId!
        )).items.data[0].id,
        price: newPriceId,
      }],
      proration_behavior: 'create_prorations',
      payment_behavior: 'error_if_incomplete',
    }
  );

  const previewInvoice = await stripe.invoices.retrieveUpcoming({
    customer: subscription.stripeCustomerId,
    subscription: subscription.stripeSubscriptionId!,
    subscription_items: [{
      id: updatedSub.items.data[0].id,
      price: newPriceId,
    }],
    subscription_proration_behavior: 'create_prorations',
  });

  console.log('Charge now:', previewInvoice.amount_due / 100);
}

Preview суми для UI

export async function POST(request: Request) {
  const { newPriceId } = await request.json();
  const tenant = await getCurrentTenant();
  const subscription = await db.subscription.findUnique({
    where: { tenantId: tenant!.id }
  });

  const preview = await stripe.invoices.retrieveUpcoming({
    customer: subscription!.stripeCustomerId,
    subscription: subscription!.stripeSubscriptionId!,
    subscription_items: [{
      id: (await stripe.subscriptions.retrieve(
        subscription!.stripeSubscriptionId!
      )).items.data[0].id,
      price: newPriceId,
    }],
  });

  return Response.json({
    amountDue: preview.amount_due / 100,
    currency: preview.currency,
    periodEnd: new Date(preview.period_end * 1000),
  });
}

Даунгрейд: в кінці періоду

export async function scheduleDowngrade(
  tenantId: string,
  newPriceId: string
): Promise<void> {
  const subscription = await db.subscription.findUniqueOrThrow({
    where: { tenantId }
  });

  await validateDowngrade(tenantId, newPriceId);

  const stripeSubscription = await stripe.subscriptions.retrieve(
    subscription.stripeSubscriptionId!
  );

  await stripe.subscriptions.update(subscription.stripeSubscriptionId!, {
    items: [{
      id: stripeSubscription.items.data[0].id,
      price: newPriceId,
    }],
    proration_behavior: 'none',
    billing_cycle_anchor: 'unchanged',
  });

  await db.subscription.update({
    where: { tenantId },
    data: {
      pendingPriceId: newPriceId,
      pendingPlanChange: getPlanFromPrice(newPriceId),
    }
  });

  await sendPlanChangeScheduledEmail(tenantId, {
    currentPlan: subscription.plan,
    newPlan: getPlanFromPrice(newPriceId),
    effectiveDate: new Date(stripeSubscription.current_period_end * 1000),
  });
}

Валідація даунгрейду

export async function validateDowngrade(
  tenantId: string,
  newPriceId: string
): Promise<void> {
  const newPlan = getPlanFromPrice(newPriceId);
  const limits = PLAN_LIMITS[newPlan];

  const [projectCount, memberCount, storageGb] = await Promise.all([
    db.project.count({ where: { tenantId } }),
    db.tenantUser.count({ where: { tenantId } }),
    calculateStorageUsage(tenantId),
  ]);

  const violations: string[] = [];

  if (projectCount > limits.projects) {
    violations.push(
      `У вас ${projectCount} проектів. Лімітfor ${newPlan}: ${limits.projects}. ` +
      `Видаліть ${projectCount - limits.projects} проектів.`
    );
  }

  if (memberCount > limits.members) {
    violations.push(
      `У вас ${memberCount} учасників. Лімітfor ${newPlan}: ${limits.members}.`
    );
  }

  if (storageGb > limits.storageGb) {
    violations.push(
      `Використано ${storageGb.toFixed(1)} GB. Лімітfor ${newPlan}: ${limits.storageGb} GB.`
    );
  }

  if (violations.length > 0) {
    throw new PlanDowngradeError(violations);
  }
}

UI: сторінка смены плану

export function PlanChangeModal({
  currentPlan,
  targetPlan,
  previewAmount,
  isUpgrade,
  onConfirm,
}: PlanChangeModalProps) {
  return (
    <Dialog>
      <DialogHeader>
        <DialogTitle>
          {isUpgrade ? 'Апгрейд' : 'Смена'} плану: {currentPlan} → {targetPlan}
        </DialogTitle>
      </DialogHeader>

      {isUpgrade ? (
        <div>
          <p>З вашої карти буде списано <strong>${previewAmount}</strong> прямо сейчас.</p>
          <p>Це пропорціональна оплата за оставшійся період.</p>
        </div>
      ) : (
        <div>
          <p>Поточний план активний до кінця расчётного періоду.</p>
          <p>Після цього переключитесь на <strong>{targetPlan}</strong>.</p>
          {targetPlan === 'FREE' && (
            <Alert>Перевірте лімити: {targetPlan} план підтримує до 3 проектів.</Alert>
          )}
        </div>
      )}

      <DialogFooter>
        <Button variant="outline" onClick={onClose}>Скасування</Button>
        <Button onClick={onConfirm}>
          {isUpgrade ? 'Апгрейднути та оплатити' : 'Підтвердити смену плану'}
        </Button>
      </DialogFooter>
    </Dialog>
  );
}

Реалізація апгрейду/даунгрейду зі Stripe proreration, валідацією та UI — 2–3 робочих дні.