Invoices
Invoice Generation & Preview
How MonetizeNow decides when an invoice should exist, what goes into it, how preview simulates without persisting state, and how to diagnose when any step in that chain breaks.
How Invoice Generation Works
Invoice generation anchors to the bill group, not the quote. A chain of dependencies must resolve (bill group, contract, quote, billing schedule) and every link must be valid before an invoice is built.
This sequence applies equally to generation and preview. A failure at any step produces the same outcome in both contexts: no invoice.
MonetizeNow traverses this chain on every invoice run. Preview follows the same path without persisting the result.
Each bill group maintains its own invoice cycle independently. An account with two bill groups — a monthly platform subscription and separately billed API usage — produces two distinct resolution chains with no shared dependency.
MonetizeNow confirms the bill group exists and is active. Bill group determines which contracts belong to the billing context, when invoices are generated, and what the current nextInvoiceDate is.
An inactive or invalid bill group stops the run immediately. No invoice, no preview result.
nextInvoiceDate anchors which billing schedule period is due. A bill group with monthly frequency and a next invoice date of April 1 resolves the period Apr 1–Apr 30.
A null nextInvoiceDate means no period can be evaluated. Generation stops.
nextInvoiceDate is rejected outright. This prevents duplicate or overlapping billing periods.
Contracts are evaluated against the resolved invoice date: status, start/end dates, renewal state, and eligibility rules. A cancelled contract may still contain uninvoiced billing schedule periods. They're not skipped.
| Contract State | Invoiceable? | Condition |
|---|---|---|
| Active | Yes | Standard eligibility rules apply |
| Cancelled | Conditional | Remaining billing schedule periods still apply |
| Finished | Conditional | Only if periods exist beyond the end date |
| Renewal pending | Conditional | Depends on whether the renewal contract is active for the date |
Within the contract, MonetizeNow identifies which quote covers the resolved billing period. That quote defines products, pricing structure, usage rates, minimum commit structures, and billing frequency.
An amendment effective July 1 has no effect on a May invoice. MonetizeNow selects the earlier quote whose billing schedule covers May.
Billing schedule is the definitive structure of invoiceable periods for a contract. MonetizeNow looks for a period whose bounds contain nextInvoiceDate.
No matching period means no invoice. Nothing is contractually due for that date.
MonetizeNow evaluates recurring charges, usage, minimum commitment reconciliation, tax, and credits before assembling the invoice. Each component is evaluated independently. See What an Invoice Can Contain for the full composition model.
nextInvoiceDate is blocked. This prevents duplicate billing periods from being generated.What an Invoice Can Contain
Once a billing period resolves, invoice items are built by evaluating several component types independently. This is why invoice totals often differ from what appears on the quote.
| Item Type | Source | Behavior | Performance Impact |
|---|---|---|---|
| Recurring charges | Quote → billing schedule | Fixed for the period. No additional computation beyond schedule lookup. | Low |
| Usage charges | Metered usage events | Requires usage data retrieval and pricing model evaluation: tiered, graduated, or per-unit. | Medium–High |
| Min commit adjustment | Contract commitment floor | Added when actual usage falls below the committed spend for the period. | Medium |
| Min commit credit | Pre-paid commitment | Offsets usage charges when pre-purchased credit is available. Evaluated after usage is rated. | Medium |
| Tax | Tax configuration + billing address | Estimated during preview; finalized on invoice generation. May vary slightly between the two. | Low–Medium |
| Customer credits | Account credit balance | Applied after invoice construction. Reduces balance due without modifying line items. | Low |
Usage and minimum commit
When a contract includes a minimum spend commitment, usage and min commit interact during reconciliation. Actual usage is rated first, then MonetizeNow determines whether a top-up adjustment is needed.
Pre-paid commit credit
Pre-paid commit credit is evaluated after usage charges are calculated. Invoices show gross usage, then a credit line that offsets the balance. Credits reduce balance due, not the line items themselves.
Customer credits vs. min commit credits
These two are structurally different. Customer credits are account-level balances applied after the total is calculated. Min commit credits are contract-level offsets applied during item construction. Both reduce balance due, but from different points in the pipeline.
Tax estimation in preview
Preview estimates tax using the same configuration as generation, but rounding and finalization rules may produce a small variance. For workflows where tax precision matters, compare preview estimates against a finalized test invoice in a sandbox environment.
A fully composed invoice for an account with a platform subscription, usage-based API billing, and a monthly minimum commitment:
| Line Item | Type | Amount |
|---|---|---|
| Platform Subscription: Apr 1–Apr 30 | Recurring | $500.00 |
| API Usage: 32,000 requests | Usage | $320.00 |
| Minimum Commit Adjustment | Min Commit | $180.00 |
| Subtotal | $1,000.00 | |
| Estimated Tax (8%) | Tax | $80.00 |
| Total | $1,080.00 | |
| Customer Credit Applied | Credit | −$200.00 |
| Balance Due | $880.00 |
How Invoice Preview Works
Invoice preview runs against a bill group's current invoicing state and returns what the next invoice would look like, without creating a record or advancing billing state. It's a non-destructive simulation of generation.
Preview traverses the same resolution chain as generation. Only difference: results are returned, not persisted.
After preview completes, nextInvoiceDate stays unchanged and no invoice record is created. Running preview multiple times against the same configuration produces the same result each time.
| Behavior | Invoice Generation | Invoice Preview |
|---|---|---|
| Runs billing logic | Yes | Yes |
| Creates invoice record | Yes | No |
| Advances nextInvoiceDate | Yes | No |
| Updates subscription billing state | Yes | No |
| Tax finalized | Final | Estimated |
| Credits reflected exactly | Yes | May vary slightly |
| Safe to run multiple times | No | Yes |
Why Preview May Return Nothing, Fail, or Stall
Because preview runs the same billing logic as generation, it surfaces the same configuration gaps. Most preview failures are billing state issues, not UI or API errors.
A preview with no result isn't always an error. In most cases, MonetizeNow evaluated the chain and found nothing due. Here are the five most common conditions.
Without nextInvoiceDate, there's no anchor point. MonetizeNow can't determine which billing schedule period to evaluate, so it stops.
Inactive bill groups are excluded from generation and preview. This eligibility gate fires before any resolution chain evaluation begins.
Most common cause. Billing schedule ends before nextInvoiceDate, typically after a contract term ends without renewal or a fixed-term schedule has elapsed.
Contract has ended or renewal hasn't become invoiceable yet. Common during renewal gaps where the prior contract is finished and the new one starts in two weeks.
Discounts, credits, or pre-paid commitments fully offset the invoice. If zero-value invoice generation is suppressed in your tenant, preview returns nothing.
A preview failure means an invalid configuration was encountered that prevents execution. These require remediation before preview can run.
An unbroken chain is required: Bill Group → Contract → Quote → Billing Schedule. If a quote has been removed, a contract reference is invalid, or the billing schedule is missing for a valid contract, the chain breaks and preview can't proceed.
During renewal transitions, there's often a window where the current contract has completed its invoiceable periods and the renewal contract hasn't become active yet. Both are associated to the bill group, but neither is eligible.
| State | Value |
|---|---|
| Contract A ends | Mar 31 |
| Renewal contract starts | Apr 15 |
| Next invoice date | Apr 1 |
| Result | No eligible contract for Apr 1 |
Preview performance scales with invoice complexity. Here are the primary contributors to processing time.
Work through this checklist before escalating a preview issue. Most cases resolve at step 3 or 4.
- Bill group is active. Confirm status is Active. Inactive bill groups do not participate in invoicing or preview.
- nextInvoiceDate is populated and valid. A null value or a past date relative to tenant timezone produces no result.
- Billing schedule covers the next invoice date. Open the billing schedule for the relevant contract and confirm a period exists that contains
nextInvoiceDate. Most common root cause. - A contract is eligible for the next invoice date. Check contract start/end dates and status. Confirm there is no renewal gap where neither contract covers the date.
- Quote and billing schedule chain is intact. Verify the contract references a valid accepted quote with a billing schedule. Missing or removed quotes break the chain.
- If preview is slow, assess invoice complexity. Usage products, min commit contracts, and PDF format all add processing time. Switch to JSON and note whether the delay persists.
- If charges resolve to zero, check discount and credit configuration. Fully offset invoices may not generate preview results depending on tenant settings. Verify discount structure and account credit balance.
Updated about 3 hours ago