Proration

Generate credit/debit invoices when customers change plans mid-period.

When a customer upgrades or downgrades their plan in the middle of a billing period, PayBridge NP can automatically calculate the unused credit on their current plan and the cost of the new plan for the remaining time - then generate a proration invoice for the net difference.

How proration works

Proration is calendar-day based:

• Credit = (remaining days / total days in period) × current plan amount
• Debit = (remaining days / total days in period) × new plan amount
• Net = debit − credit

A positive net means the customer owes more (upgrade). A negative net means a credit balance (downgrade) - no invoice is generated in that case.

Preview before applying

Always preview the proration amounts before committing a change so you can show the customer what they’ll owe:

TypeScript

const preview = await pb.subscriptions.previewProration(
  "sub_xxx",
  "plan_premium_monthly"
);

console.log(`Credit:  NPR ${preview.creditAmount / 100}`);
console.log(`Debit:   NPR ${preview.debitAmount / 100}`);
console.log(`Net due: NPR ${preview.netAmount / 100}`);

Apply a plan change with proration

Pass prorationBehavior: "create_prorations" to apply the change immediately:

TypeScript

const result = await pb.subscriptions.changePlan("sub_xxx", {
  newPlanId: "plan_premium_monthly",
  prorationBehavior: "create_prorations",
});

if ("prorationApplied" in result && result.prorationApplied) {
  const invoice = result.prorationInvoice;
  console.log("Proration invoice:", invoice?.id, "Amount:", invoice?.amountDue);
}

Schedule for next billing cycle (default)

To keep the existing behaviour - plan change applies at next renewal with no proration:

const result = await pb.subscriptions.changePlan("sub_xxx", {
  newPlanId: "plan_premium_monthly",
  // prorationBehavior defaults to "none"
});

Proration invoice

When a proration invoice is created it:

• Has status: "open" if netAmount > 0 (customer owes money)
• Is skipped (no invoice) if netAmount ≤ 0
• Contains two line items: proration_credit (negative) and proration_debit (positive)
• Is due immediately - link the customer to the hosted invoice page to collect payment

API reference

Endpoint	Description
GET /v1/billing/subscriptions/:id/preview-proration?newPlanId=	Preview amounts without committing
POST /v1/billing/subscriptions/:id/change-plan	Change plan; pass prorationBehavior