Billing & Payments

10. Billing & Payments

10.1 How Billing Works

The billing system operates on a ledger model. Every financial event creates an immutable financial transaction on the customer's ledger:

• Service charges (positive — customer owes more)
• Payments received (negative — customer owes less)
• Credits (negative — customer owes less)
• Late fees (positive — customer owes more)
• Refunds (negative — reduces a previous payment)
• Sales tax (positive — added to charges)

The customer's current balance is the sum of all their financial transactions. A positive balance means they owe money; a negative balance means they have a credit.

10.2 Invoices

In Per-Service Mode:

• An invoice is automatically generated when a service is completed and charged.
• Each invoice has a unique number (e.g., INV-2026-0042), line items, subtotal, tax, and total.
• Invoices can be downloaded as PDF or viewed in the customer portal.

In Monthly Statement Mode:

• Invoices are generated from closed monthly statements (see Section 8.3).

Invoice Status:

• Draft — created but not yet sent.
• Open — sent to the customer, awaiting payment.
• Paid — full payment received.
• Partial — a partial payment has been applied, but a balance remains.
• Overdue — past the due date with an outstanding balance.
• Refunded — the invoice payment has been refunded.
• Cancelled — the invoice has been voided.

10.3 Statements (Monthly Mode)

If you're using the Monthly Statement billing method:

1. Each statement covers a period (e.g., March 1–31).
2. During the period, all completed services, credits, payments, and fees are recorded as financial transactions.
3. At the end of the period, the statement is closed with:
   • Opening balance (carried from previous statement)
   • All transactions for the period
   • Closing balance
4. The statement can be:
   • Emailed to the customer automatically.
   • Downloaded as PDF.
   • Viewed in the customer portal.

Statement Day: Set the anchor day of the month for statements and due dates (1–28). Configure this in Settings > Company.

Statement Integrity: Each statement has a cryptographic signature to ensure transaction data hasn't been altered.

10.4 Autopay

Autopay automatically charges a customer's saved payment method when an invoice is due.

Enabling Autopay for a Customer:

1. The customer saves a payment method (credit card or bank account) — either through the portal or you can add it on their behalf.
2. The customer opts in to autopay.
3. Mark one payment method as the default autopay method.
4. When an invoice is due, the system automatically charges the default method.

Autopay Retry Schedule: If a payment fails (e.g., declined card), the system retries according to your configured retry schedule. For example:

• Retry 1: 3 days after failure
• Retry 2: 7 days after failure
• Retry 3: 14 days after failure

After all retries are exhausted, the system can optionally disable autopay for that customer and send a notification.

10.5 Manual Payments

You can record payments made outside the system:

1. Open the customer's billing tab.
2. Click Record Payment.
3. Enter the amount, date, and payment method:
   • Cash
   • Check (enter check number)
   • Venmo
   • Wire transfer
   • Other
4. The payment is posted to the customer's ledger and reduces their balance.

10.6 Credits & Debits

Issuing a Credit:

• Use credits for adjustments, goodwill discounts, or promotional offers.
• Open the customer's info page, go to the Billing tab, then click the Credit sub-tab.
• Enter the amount, reason, and description.
• The credit is posted as a negative transaction, reducing the customer's balance.

Issuing a Debit (Manual Charge):

• Use debits for one-time charges outside of regular services (e.g., repair charges, supply fees, service call fees).
• Open the customer's info page, go to the Billing tab, then click the Charge sub-tab.
• Enter the amount, customer, and description.
• The charge is posted as a positive transaction, increasing the customer's balance.

Confirmation Thresholds: To prevent accidental large credits or refunds, you can set a confirmation threshold (e.g., require confirmation for credits over $500) in Settings.

10.7 Refunds

To refund a payment:

1. Open the customer's billing tab and find the payment.
2. Click Refund.
3. Enter the refund amount (full or partial).
4. Select a reason: Duplicate, Service Not Rendered, Goodwill, Pricing Error, or Other.
5. Add optional notes.
6. The refund is processed through the original payment gateway and recorded on the ledger.

10.8 Late Fees

If late fees are enabled (see Section 2.6), they are automatically applied when:

1. An invoice is past its due date.
2. The grace period has elapsed (e.g., 15 days after due date).
3. The invoice still has an outstanding balance.

Late fees appear as a separate Late Fee transaction on the customer's ledger. The fee amount depends on your configuration (flat amount or percentage of balance, with an optional maximum cap).

Per-Subscription Override: You can override the late fee grace period on individual subscriptions. For example, give a long-standing customer a longer grace period without changing the company-wide default.

10.9 Failed Payments & Retry Logic

When an autopay charge fails:

1. The payment is recorded with a Failed status.
2. The customer's autopay failure count is incremented.
3. The system schedules a retry based on your retry schedule (Settings > Company, Payments section).
4. If configured, the customer receives a notification about the failed payment.
5. If all retries are exhausted:
   • Autopay can be automatically disabled for the customer.
   • An admin alert is generated so your team is aware.
   • The subscription may be auto-paused if you've enabled that feature.