Skip to main content
Usage data helps partners reconcile payroll activity to billing. Nmbr exposes usage in two levels of detail:
  • usage_records: the individual billable events Nmbr recorded.
  • usage_summaries: monthly rollups of those records by company and event type.
Use usage summaries when you need invoice totals. Use usage records when you need to explain or reconcile a specific count.

​
How usage is counted

Usage summaries group records by their recorded_at month. Paid usage (employee_paid, contractor_paid, employee_paid_unique, and contractor_paid_unique) is recorded in the month of the payroll’s pay date. The pay period the payroll covers and the day the money reaches the bank don’t change the month. Historical and correction payrolls generate no usage records. Example:
  • A payroll for 15 employees has a pay date of May 29. It covers April 16 to April 30.
  • Nmbr records 15 employee_paid records with a May 29 recorded_at.
  • The count appears in the May usage summary, even if a payment settles in June.
Each pay stub records employee_paid or contractor_paid once. If a payment fails and is retried, the retry doesn’t record it again. The failure records its own disbursement_failure instead. See Failed payments. If a summary count looks unexpected, inspect the underlying records and compare their recorded_at timestamps.

​
Failed payments

When an employee’s or contractor’s bank rejects a payment, Nmbr records a disbursement_failure for that attempt. It’s recorded in the month the bank reports the failure, which can be later than the pay date month. Example:
  • A payroll has a pay date of May 29. The employee’s bank rejects the payment on June 2.
  • The payment is retried on June 3 and settles.
  • The employee_paid record stays in May.
  • The disbursement_failure record appears in June.
Each failed attempt is recorded once. A payment that fails twice before it settles records two disbursement_failure records.

​
Usage event types

Each usage summary has an event and a count. These are the usage event types Nmbr currently returns: Partners billed per employee per pay run usually reconcile against employee_paid and contractor_paid. Partners billed per employee per month usually reconcile against employee_paid_unique and contractor_paid_unique.

​
Get monthly usage summaries

Use GET /usage_summaries to retrieve monthly rollups. Usage endpoints are partner-level endpoints, so authenticate with your partner secret.
Response
Nmbr creates one summary row per company, month, and event type. Events with no usage may still appear with a count of 0.

​
Reconcile a summary with usage records

Use GET /usage_records to inspect the records that feed a summary. Filter by the same company and the recorded date range for the month you are reconciling.
Response
A payroll with a May pay date has a May recorded_at on its paid usage records and contributes to the May summary, whatever pay period it covers.

​
Practical reconciliation flow

  1. Fetch GET /usage_summaries for the company and month you want to invoice.
  2. Group the returned rows by event.
  3. Use employee_paid plus contractor_paid for per-pay-run billing.
  4. Use employee_paid_unique plus contractor_paid_unique for per-month billing.
  5. Use disbursement_failure to count failed payments to employees and contractors.
  6. If a count is unexpected, fetch GET /usage_records for the same company and recorded month, then inspect the event, record, and recorded_at values.