Billing

Set up recurring subscriptions and automated invoicing for your customers.

The PayBridgeNP Billing system handles recurring payments - create a plan, add customers, and start subscriptions. PayBridgeNP generates invoices automatically at each renewal, sends payment links to customers, and manages retries when payments fail.

The Billing API requires a Premium plan on your PayBridgeNP account. You can manage billing from the dashboard without the API on any plan.

Core concepts

Plans define the recurring charge - amount, interval (monthly, yearly, etc.), trial period, and dunning behavior. Plans are templates; subscriptions are instances.

Customers are the people being billed. They exist independently of subscriptions - you can have a customer with no active subscriptions.

Subscriptions link a customer to a plan. When you create a subscription, PayBridgeNP immediately generates the first invoice (unless there’s a trial period).

Invoices are generated automatically at each billing cycle. Each invoice has a payment link that PayBridgeNP sends to the customer. Invoices go from open → paid once the customer pays, or past_due if they don’t pay in time.

---

Step 1: Create a plan

const plan = await paybridge.billing.plans.create({
  name: "Pro Monthly",
  amount: 99900,          // Rs. 999.00 in paisa
  intervalUnit: "month",
  intervalCount: 1,       // every 1 month
  trialDays: 14,          // 14-day free trial
  gracePeriodDays: 3,     // 3 days after due before going overdue
  overdueAction: "mark_past_due",
});

console.log(plan.id); // bp_...

Interval options

intervalUnit	intervalCount	Billing frequency
month	1	Monthly
month	3	Quarterly
year	1	Yearly
week	2	Every 2 weeks
day	30	Every 30 days

Dunning settings

Dunning controls what happens when a customer doesn’t pay on time:

Setting	Description
gracePeriodDays	Days after due before triggering the overdue action
reminderDaysBeforeDue	Send a reminder email N days before the invoice is due
overdueReminderIntervalDays	Repeat overdue reminders every N days
overdueAction	What to do when overdue: keep_active, mark_past_due, pause, or cancel

---

Step 2: Create a customer

const customer = await paybridge.billing.customers.create({
  name: "Aarav Sharma",
  email: "[e-mail]",
  phone: "9801234567",          // optional
  externalCustomerId: "user_123", // optional - your internal user ID
});

console.log(customer.id); // bc_...

The externalCustomerId field lets you link PayBridgeNP customers to your own user records.

---

Step 3: Create a subscription

const subscription = await paybridge.billing.subscriptions.create({
  customerId: customer.id,
  planId: plan.id,
});

console.log(subscription.id);            // sub_...
console.log(subscription.displayStatus); // "trialing" (if plan has trialDays > 0)

When a subscription is created:

• If the plan has trialDays > 0 - the subscription starts in trial mode, no invoice is generated until the trial ends
• Otherwise - an invoice is generated immediately and PayBridgeNP sends a payment link to the customer’s email

---

Subscription lifecycle

draft → active (trialing) → active → past_due → cancelled
                                    ↳ paused → active

Display status	Meaning
draft	Start date is in the future
trialing	Active, in trial period - no invoices yet
active	Billing normally
past_due	Invoice unpaid past grace period
paused	Billing paused - no invoices generated
cancelled	Ended - no further invoices
completed	Reached a natural end date

---

Managing subscriptions

Pause

await paybridge.billing.subscriptions.pause(subscription.id, {
  reason: "Customer requested temporary pause",
});

No invoices are generated while paused. Resume resumes billing from the current period.

Resume

await paybridge.billing.subscriptions.resume(subscription.id);

Cancel

// Cancel immediately
await paybridge.billing.subscriptions.cancel(subscription.id, {
  reason: "Customer churned",
});

// Cancel at end of current period
await paybridge.billing.subscriptions.cancel(subscription.id, {
  atPeriodEnd: true,
});

Change plan

// Change takes effect at the next renewal
await paybridge.billing.subscriptions.changePlan(subscription.id, {
  planId: newPlan.id,
});

The current period continues on the old plan. At renewal, the subscription switches to the new plan.

---

Invoices

Invoices are read-only from the API - PayBridgeNP creates them automatically. Use them to display billing history to customers.

const { data: invoices } = await paybridge.billing.invoices.list({
  subscriptionId: subscription.id,
});

for (const invoice of invoices) {
  console.log(invoice.status, invoice.amount, invoice.dueAt);
}

Invoice status	Meaning
draft	Not yet sent
open	Sent to customer, awaiting payment
paid	Customer paid
past_due	Not paid by due date
voided	Cancelled

---

Webhook events

PayBridgeNP fires webhook events throughout the subscription lifecycle:

Event	When
subscription.created	New subscription created
subscription.activated	Trial ended, billing started
subscription.past_due	Invoice went past due
subscription.paused	Subscription paused
subscription.resumed	Subscription resumed
subscription.cancelled	Subscription cancelled
invoice.created	New invoice generated
invoice.paid	Customer paid an invoice
invoice.past_due	Invoice went past due