Billing Engine Reference

Technical reference for the ISP-OS billing engine -- invoice lifecycle, payment allocation, collections pipeline, auto-suspend/reconnect, and amount handling.

Invoice Lifecycle

Every invoice follows a linear status progression. Status transitions are system-driven (not manual).

Status	Description	What triggers it	What clears it
Draft	Invoice created but not yet finalized	Mid-cycle or prorated invoice	Finalized by you or automatically on generation day
Sent	Finalized and visible to subscriber	Generation day arrives, or you manually finalize	Due date passes without full payment
Overdue	Past due date, not fully paid	Checked automatically every day after midnight	Full payment received
Paid	Fully paid	Payment covers the remaining balance	Final status
Partially Paid	Some payment received but balance remains	Partial payment applied	Full payment received (becomes Paid) or due date passes (becomes Overdue)
Void	Cancelled, excluded from all calculations	You manually void the invoice	Final status

Two status tracks

Each invoice has two separate statuses:

Track	What it tells you	Values
Invoice status	Whether the subscriber has paid	Draft, Sent, Paid, Partially Paid, Overdue, Void
Collection status	Where they are in the collections pipeline	Pending, Reminded, Warned, Suspended, Restored, Uncollectible

These are independent. An invoice can be "Overdue" (not paid) and "Warned" (warning sent but not yet suspended) at the same time.

Invoice timeline (default settings)

Day 1     Invoice created (Sent)
Day 12    Pre-due reminder (SMS + email)
Day 15    Due date
Day 16    Post-due warning (SMS + email)
Day 16+   Status transitions to Overdue
Day 20    Auto-suspend (PPPoE session kicked)
Day ???   Subscriber pays -- auto-reconnect < 30 seconds
Day 90+   Flagged as likely uncollectible

Payment Allocation

Payments are applied to invoices oldest-first. ISP-OS handles this automatically.

Rules

1. Oldest invoice first. Payments apply to the invoice with the earliest due date first.
2. Partial payments allowed. If a subscriber pays less than the full amount, the payment is applied as a partial. The invoice shows as Partially Paid.
3. One payment, multiple invoices. A single payment can cover more than one invoice. ISP-OS keeps applying the payment to the next oldest invoice until the amount runs out.
4. Overpayment becomes credit. If the subscriber pays more than they owe, the extra goes to their credit balance and applies automatically to next month's bill.
5. No double-counting. If the same payment notification arrives more than once (e.g., network retry), ISP-OS only counts it once.

Payment sources

Source	How it works
NextPay (GCash QR, bank transfer)	Automatic. Subscriber pays on their payment page, ISP-OS records it instantly
Manual entry	You record the payment from the subscriber's detail page (for cash, check, in-person)

Service Pricing Terms

Plans define the standard monthly price for a service. Subscriber services can then carry their own billing terms when a customer has a negotiated price or one-off discount.

Term	What it means
Plan price	The default monthly price from the selected plan
Individual price	Optional per-subscriber service price that replaces the plan price before discounts
Service discount	Optional discount on that subscriber service, either a fixed peso amount or a percentage
Discount window	Optional start and end dates that control when the discount is active

Discounts belong to the subscriber service, not to the plan catalog. ISP-OS currently supports one discount per subscriber service. Leave the individual price and discount blank when the subscriber should follow the plan price exactly.

How invoices use service terms

When ISP-OS builds a recurring or prorated service invoice line:

1. Start with the individual price, if present; otherwise use the plan price.
2. Apply the active service discount, if one exists for the invoice period.
3. Floor the line total at zero. A discount can fully waive a line, but it cannot make the invoice line negative.
4. Store the applied discount amount, label, source type, and source value on the invoice item.

Prorated service-period amounts use the tenant's Proration basis setting. The default is Fixed 30-day month, which divides prorated monthly service charges by 30 for UCRM-compatible ISP billing behavior. Actual period days divides by the number of days in the billed service period. Whole service periods always charge one monthly amount.

Sent invoices are immutable. If you change a service's individual price or discount later, existing invoice items keep the pricing snapshot that was used when they were generated.

Plan-change upgrade and downgrade classification compares the base recurring service price before discount. The discount still affects the billed charge or credit, but it does not make a discounted upgrade look like a downgrade.

Pricing-only edits are handled separately from network edits. Billing-capable staff can update individual price and discount terms without triggering MikroTik or RADIUS reconciliation.

Collections Pipeline

The collections pipeline automates chasing overdue payments through three escalating stages.

Stage	Timing	Notification	Automated Action
Reminder	due_date - remind_days_before_due (default: 3 days before)	SMS + email with payment link	None -- informational only
Warning	due_date + warn_days_after_due (default: 1 day after)	SMS + email with suspension date	Invoice status transitions to Overdue
Suspension	due_date + suspend_days_after_due (default: 5 days after)	SMS + email confirming disconnection	PPPoE session kicked, RADIUS rejects re-auth

Automatic schedule

ISP-OS runs these checks automatically every day:

What	When	What it does
Mark overdue invoices	After midnight (Manila time)	Invoices past their due date are flagged as Overdue
Suspend non-payers	At your configured time (default 6:00 AM)	Subscribers past the grace period are disconnected
Send notifications	9:00 AM Manila time	Reminders, warnings, and suspension notices are sent by SMS + email

Operators monitor cutoff days from Collections in the main navigation. Most days stay quiet: the page shows the next cutoff, the estimated eligible cohort, the amount at risk, and recent cutoff archives. When a cutoff has an eligible cohort, ISP-OS creates one collection run, freezes the filters used for that run, streams timeline updates live, and records the final outcome counts.

Collections timeline

Every action is logged on the subscriber's detail page under the Timeline tab:

• Reminded — pre-due reminder sent
• Warned — post-due warning sent
• Suspended — internet disconnected
• Restored — paid and reconnected
• CS Reversed — staff restored an automated overdue suspension with an audit note
• Uncollectible — written off as bad debt

Void vs Uncollectible

Both actions live on the invoice page and both stop an invoice from being chased, but they mean different things — keep them distinct:

	Void	Uncollectible
Use it when	The invoice should never have been issued (duplicate, billing error)	The invoice was valid but won't be paid (customer disconnected, gone)
Effect	Invoice status becomes Void, amount due reads ₱0.00	Collection status becomes Uncollectible; the invoice is hidden from overdue and aging
Blocked when	The invoice already has a payment allocated	—
Reversible	No	Yes — Mark collectible puts it back in the cycle
Who can do it	Owner / Admin	Owner / Admin

Marking an invoice uncollectible requires a reason, which is recorded on the invoice Timeline. It is a collections-state flag scoped to that single invoice — the subscriber's account stays active, and they still appear under the Uncollectible filter in Collections while they have at least one written-off invoice. Reversing it (Mark collectible) is also recorded on the Timeline.

TIP

Neither Void nor Uncollectible posts a separate accounting reversal today — they change the invoice's state, not the ledger. Bad-debt is tracked operationally (hidden from overdue), which matches how small ISPs handle write-offs.

Auto-Suspend

When the grace period expires on an overdue invoice, ISP-OS automatically disconnects the subscriber.

What happens when a subscriber is suspended

1. Their status changes to Suspended on the dashboard
2. Their active internet session is disconnected on the MikroTik router
3. Any attempt to reconnect is blocked until they pay
4. A suspension notification is sent (SMS + email)
5. The event is logged in their collections timeline

What suspend does NOT do

• Does not delete the subscriber's account or settings. Everything is preserved for instant restoration once they pay.
• Does not require you to do anything. The entire process is automatic.

At scale

If you have hundreds of subscribers being suspended at once (e.g., after a holiday weekend), ISP-OS processes them in batches to avoid overwhelming your MikroTik routers.

Auto-Reconnect

When a suspended subscriber pays what they owe, ISP-OS reconnects their internet automatically.

How it works

1. Subscriber pays (via NextPay payment page or you record a cash payment).
2. ISP-OS applies the payment to their oldest unpaid invoices.
3. If all overdue invoices past the grace period are now paid, ISP-OS reactivates the subscriber.
4. Their internet is restored within about 30 seconds of payment.

No phone call, no manual reconnect, no waiting until morning.

When auto-reconnect does NOT apply

Situation	What happens
Subscriber was manually suspended by you	They stay suspended. You have to reactivate them manually. Auto-reconnect respects your decision.
Subscriber still has unpaid invoices past grace period	They stay suspended until all overdue invoices are covered.
Subscriber is already active	Nothing happens. The payment is applied but no reconnection is needed.

Fair Usage Policy

Plans can optionally include a Fair Usage Policy (FUP). When a subscriber exceeds their data cap, speeds are throttled to the FUP limits instead of cutting service entirely.

Field	Description
Data cap (GB)	Monthly data allowance before throttling kicks in
FUP download (Mbps)	Reduced download speed after cap is exceeded
FUP upload (Mbps)	Reduced upload speed after cap is exceeded

When a subscriber exceeds their data cap, ISP-OS automatically slows their connection to the FUP speeds. The data counter resets at the start of each billing cycle.

FUP is optional. Plans without a data cap have unlimited usage at the plan's full speed.

Billing Types

	Postpaid	Prepaid
Invoice timing	Generated at start of billing period	Generated before billing period
Service access	Active from day 1; payment due later	Activates only after payment
Suspension trigger	Non-payment after grace period	Non-payment before period start
Common use case	Residential fiber subscribers	WiFi voucher / hotspot users

Amount Handling

All amounts in ISP-OS are displayed in Philippine Pesos (₱). Internally, amounts are stored in centavos (1/100 of a peso) to avoid rounding errors. You don't need to worry about this, everything you see on the dashboard and invoices is in pesos.

What you see	Example
Dashboard, invoices, subscriber balances	₱800.00
NextPay payment amounts	₱800.00 (fee shown separately)

Was this helpful?