Agent Wranglers

USG-5Recommended

Match your usage totals with the provider before each invoice

Before a usage invoice is finalised, compare your total per customer and meter with the total the billing provider holds. Hold the invoice when they differ.

By Agent Wranglers. Updated .

How to do it

Events sent to a provider can fail, time out or arrive twice. Most billing engines leave a usage invoice in draft for a short time, such as an hour, before they finalise it. Use that window. Fetch the provider's summary for the period and compare it with your own sum. Send any missing events with their original keys, so nothing doubles. Alert a person when a gap remains. This is the usage side of Reconcile every payout.

Examples

JavaScript example

export async function reconcileUsage(customerId, meter, period) {
  const ours = await usage.total(customerId, meter, period)
  const theirs = await billing.meterSummary(customerId, meter, period)
  if (ours === theirs) return 'matched'
  for (const event of await usage.notAcknowledged(customerId, meter, period)) {
    await billing.sendMeterEvent(event, { identifier: event.eventKey })
  }
  return 'resent'
}

Python example

def reconcile_usage(customer_id: str, meter: str, period) -> str:
    ours = usage.total(customer_id, meter, period)
    theirs = billing.meter_summary(customer_id, meter, period)
    if ours == theirs:
        return "matched"
    for event in usage.not_acknowledged(customer_id, meter, period):
        billing.send_meter_event(event, identifier=event.event_key)
    return "resent"

How to check

A test drops one event on the way to a sandbox provider. The reconciliation job finds the gap, resends the event and the draft invoice total then matches your sum. A second run sends nothing.

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/usage-billing/metering/usage-reconciliation">Agent Wranglers usage-based billing playbook</a>. In code you write, add a comment next to it with the same link.