How do I reconcile Rillet usage records against the general ledger?
Rillet's usage-records endpoint returns raw, paginated data — dates and quantities per contract item — with no built-in reconciliation or invoiced-amount comparison. Reconciling against the GL means pulling every usage record for the period, summing by contract item, and comparing that total against what was actually invoiced, entirely outside Rillet's API.
By Zuny Fester, Head of Operations and MarketingPart of the finance integrations guide.
| What the API returns | Paginated usage records: date and quantity per contract_item_id, nothing else |
|---|---|
| What it doesn't do | No reconciliation, invoiced-amount comparison, or overage calculation built in |
| Write behavior | upsert-a-usage-record overwrites by date — same date sent twice replaces, doesn't duplicate |
| Filtering available | Pagination only (limit/cursor) — no date-range or amount filter on the list endpoint |
What Rillet's usage API actually gives you
Rillet's usage-billing surface is three narrow endpoints: upsert a usage record (write), list all contract item usage records (read), and delete a usage record. The upsert endpoint takes a date and a quantity per contract item and is date-keyed — sending the same date twice overwrites the prior value rather than creating a duplicate, which makes it safe to re-run without a separate idempotency key. The list endpoint returns those same date/quantity pairs, paginated, with no date-range filter and no way to filter by amount.
Nothing in the documented surface reconciles usage against what was actually invoiced or recognized. There's no endpoint that returns "usage vs. billed" or flags an overage — the API is a system of record for raw usage, not a reconciliation engine.
Building the reconciliation yourself
Since the list endpoint has no date-range filter, pulling a period's usage means paging through all records for each contract item and filtering by date client-side, then summing quantities per item for the period. Multiply by the contract's usage pricing to get the expected billed amount for that period, and compare it against what was actually invoiced (from the contract's associated invoices, returned on the ExpandedContract object after an amendment, or from a separate invoice lookup) and what landed in the GL.
What a mismatch usually means
Three causes account for most usage-to-GL mismatches: a usage record was upserted after the invoice for that period had already generated (the invoice reflects stale usage); a contract amendment changed the usage price mid-period without the effective_from timing being accounted for in the reconciliation math; or usage was recorded against the wrong contract_item_id, which shows up as one item under-recognizing and a related item over-recognizing by a matching amount.
Next step
Map the finance workflow with the most exposure and prove the automation path.
Bring the invoice, contract, payment reconciliation, or customer finance workflow you have to defend at audit. Loopfour can map the trigger, controls, integrations, and approval loop.
Worked example
A usage record posted one day after invoice generation
A metered contract item bills monthly based on usage. On the 1st, the invoicing job generates the prior month's invoice using 4,200 units of recorded usage. On the 2nd, a late usage-tracking batch job upserts 4,350 units for a date in the prior month — the corrected, real figure. Because upsert overwrites by date rather than triggering a re-invoice, the GL now reflects 4,200 billed units against 4,350 units of actual recorded usage in Rillet: a 150-unit gap that will not resolve itself and will not appear on any Rillet report, because reconciliation isn't something the API does. The fix is procedural, not technical: usage-tracking jobs need to complete and settle before the invoicing job reads them, or the reconciliation step needs to compare final usage against what was actually billed and true up the difference on the next invoice.
Frequently Asked Questions
Sources
Related
Diagnostic
Why doesn't deferred revenue match the general ledger?
Deferred revenue usually drifts from the general ledger when the billing system's revenue schedule isn't synced to GL journal entries, or when manual entries post outside that schedule. Reconcile the deferred revenue roll-forward against the GL trial balance at the contract-line level, not the invoice level, to find exactly where the two diverge each month.
Read moreTopic
Integrations
Every finance automation vendor publishes an integrations page: a grid of logos, a claim of "seamless" connectivity, and not much else. That page answers a marketing question — does this vendor touch…
Read moreHow-to
How do I sync a Rillet contract amendment into my revenue recognition schedule?
Call Rillet's amend-a-contract endpoint with an amendment_date, an amendment_reason, and the changed items, choosing whether each item takes effect as of the amendment date or at the end of the current billing cycle. Rillet regenerates the affected revenue schedule and journal impact for review before anything posts.
Read moreDiagnostic
What breaks when a Rillet contract amendment isn't reflected in the revenue schedule?
Rillet's amend-a-contract endpoint requires an effective_from choice — AS_OF_AMENDMENT_DATE or END_OF_CURRENT_BILLING_CYCLE. If a workflow leaves this unset or picks the wrong one, the amendment is accepted successfully but doesn't change revenue recognition until the next billing cycle starts, which looks identical to a failed or dropped amendment until you check which option was actually sent.
Read more