Invoices
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 MonetizeNow resolves bill group → contract → quote → billing schedule before constructing any invoice.
Item types evaluated during construction: recurring, usage, min commit, tax, and credits, and how they interact.
How preview runs the same logic in non-persistent mode, and the conditions that cause it to return nothing or stall.
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.
Bill Group → nextInvoiceDate →
- Determine Billing Period
- Identify Eligible Contract
- Resolve Valid Quote
- Match Billing Schedule Period
- Construct Invoice Items
→ Invoice Generated
Quote resolution
MonetizeNow selects the quote valid for the resolved billing period, not the most recently modified one. An amendment effective July 1 has no effect on a May invoice. Quote selection is period-driven, not recency-driven.
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.
1. Bill group validates the billing context
Entry point. If this fails, nothing proceeds.
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.
2. Next invoice date anchors the billing period
This date drives period resolution, not the current calendar date.
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.
System Rule
Invoice regression is blocked. Requesting a date before
nextInvoiceDateis rejected outright. This prevents duplicate or overlapping billing periods.
3. Identify the contract eligible for billing
Eligibility isn't the same as "active." Cancelled contracts can still be invoiceable.
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 |
4. Resolve the quote that defines pricing
MonetizeNow uses the quote valid for the billing period, not the most recently edited one.
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.
5. Match the billing schedule period
Most common reason preview returns nothing. The period must exist.
Billing schedule is the definitive structure of invoiceable periods for a contract. MonetizeNow looks for a period whose bounds contain nextInvoiceDate.
Billing schedule:
Jan 1 – Jan 31
Feb 1 – Feb 28
Mar 1 – Mar 31
← next invoice date: Apr 1 → no matching period → generation stopsNo matching period means no invoice. Nothing is contractually due for that date.
6. Construct invoice items
Once the period is confirmed, line items are built across multiple components.
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.
- Bill groups are independent. Each bill group resolves its own chain. Previewing one tells you nothing about another's invoice state on the same account.
- No invoice regression. Requesting an invoice for a date before
nextInvoiceDateis blocked. This prevents duplicate billing periods from being generated. - Quote context follows the period. MonetizeNow selects the quote valid for the billing period. Amendment effective dates control when new pricing begins applying to invoices.
- Cancelled ≠ not billable. Contracts cancelled mid-term may still have future billing schedule periods. Those periods are invoiced until the schedule is exhausted.
- Zero-value invoices may not generate. When discounts or credits fully offset all charges, invoice generation may be suppressed. Expected behavior, not a system fault.
- Preview uses the same logic. Preview runs the identical resolution chain without persisting the result. Any chain failure that blocks generation also blocks preview.
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.
Min monthly commitment: $1,000
Usage charges this period: $700
──────────────────────────────────
Min commit adjustment: $300 ← added to reach the committed floor
Invoice total: $1,000Pre-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.
Usage charges: $900
Commit credit applied: -$900
──────────────────────
Balance due: $0Note
A $0 balance due invoice may still generate depending on configuration. If zero-value invoice generation is suppressed in your tenant, this scenario returns no invoice and no preview result.
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 |
Reading this invoice
Min commit adjustment exists because total usage ($500 recurring + $320 usage = $820) falls below the $1,000 commitment. The $180 brings the invoiced amount to the contracted floor.
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.
Key distinction
Preview doesn't show a draft. It runs the actual billing logic and returns real output. If preview returns nothing, MonetizeNow found nothing to invoice. It's not a rendering problem.
Preview traverses the same resolution chain as generation. Only difference: results are returned, not persisted.
Preview Request (Bill Group) →
- Validate Bill Group + Next Invoice Date
- Resolve Eligible Contract
- Resolve Quote + Billing Schedule Period
- Construct Invoice Items
- Estimate Tax + Evaluate Credits
→ Return Preview Result (no state change)
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 |
Variance
Preview totals may differ slightly from finalized invoices due to tax estimation rounding and credit application timing. Treat preview as a high-confidence estimate for pre-bill validation, not a guaranteed exact match.
| Format | Description |
|---|---|
| JSON Preview | Returns invoice structure: line items, subtotal, estimated tax, total. Fastest format. Only runs billing logic, no rendering step. Use for programmatic validation or quick checks before a billing run. |
| PDF Preview | Runs billing, then renders the invoice document. Slower than JSON. Rendering occurs after calculation, adding a second processing phase. Use when reviewing final presentation for customer-facing delivery. |
Diagnosing slow preview
If preview is taking longer than expected, try JSON format first. If JSON is also slow, the delay is in billing calculation. If JSON is fast but PDF is slow, the bottleneck is rendering.
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.
No next invoice date on the bill group
What is happening: Without nextInvoiceDate, there's no anchor point. MonetizeNow can't determine which billing schedule period to evaluate, so it stops.
Check:
- Bill group has a populated nextInvoiceDate
- Date format and timezone are valid for your tenant configuration
Bill group is inactive
What is happening: Inactive bill groups are excluded from generation and preview. This eligibility gate fires before any resolution chain evaluation begins.
Check:
- Bill group status is Active
- If recently deactivated, this behavior is expected
Billing schedule has no period for the next invoice date
What is happening: Most common cause. Billing schedule ends before nextInvoiceDate, typically after a contract term ends without renewal or a fixed-term schedule has elapsed.
Check:
- Billing schedule includes a period covering nextInvoiceDate
- Renewal quote has been accepted and generates a continuing schedule
No contract is eligible for the invoice date
What is happening: 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.
Check:
- Contract start/end dates cover the next invoice date
- Renewal contract start date aligns with or precedes the next invoice date
All charges resolve to zero
What is happening: Discounts, credits, or pre-paid commitments fully offset the invoice. If zero-value invoice generation is suppressed in your tenant, preview returns nothing.
Check:
- Discount configuration on the quote
- Outstanding credit balance applied to the account
A preview failure means an invalid configuration was encountered that prevents execution. These require remediation before preview can run.
Broken contract → quote → billing schedule chain
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.
Remediation required
This isn't recoverable through the UI alone. The underlying data relationship must be corrected — typically by restoring the quote reference or regenerating the billing schedule — before preview can run.
Renewal gap — neither contract produces a valid period
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.
| Contributor | Why it adds time | What to do |
|---|---|---|
| Large usage dataset | Usage data retrieval for the billing period. Tier and graduated pricing evaluation across large event volumes. | Use JSON format to isolate calculation vs. rendering time |
| Min commit reconciliation | Usage must be fully rated before reconciliation can run. Credit structures add an additional evaluation pass. | Expected behavior on contracts with commit structures |
| PDF preview requested | Billing must complete before rendering begins. Template rendering runs as a second phase after calculation. | Switch to JSON to confirm if rendering is the bottleneck |
| External tax provider calls | Tax providers such as Avalara or Anrok are called during estimation. Response latency from the external service adds to total preview time. | Check tax provider response times independently |
Reference
An invoice with multiple subscription products, several usage products, 2M+ usage records, min commit contracts, and tax enabled may take 8–15 seconds to preview. That's expected behavior on a high-complexity invoice.
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.
Skipped vs. Failed
A preview that returns nothing is a billing state condition: MonetizeNow ran and found nothing due. A preview that errors means it couldn't run at all. Nothing returned points to the billing resolution chain. An error points to data integrity issues in the bill group, contract, or quote relationships.
Updated 9 days ago