Usage

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 are based on when a usage record was recorded, not on the payroll period the payroll represents. For payroll-related usage, this means the count lands in the month when the payroll activity is processed and recorded by Nmbr. If you process historical or backdated payrolls in May, the resulting usage records are counted in May, even if those payrolls represent work from March or April. Example:

On May 7, you process an April payroll for 15 employees.
Nmbr records the paid employee usage on May 7.
The employee_paid count appears in the May usage summary.
It does not appear in the April usage summary.

This timing rule is the same reason usage records include recorded_at: if a summary count looks unexpected, inspect the underlying records and compare their recorded_at timestamps.

Usage event types

Each usage summary has an event and a count. These are the usage event types Nmbr currently returns:

Event	What it counts
`employee_paid`	Employee pay stubs paid during the usage month.
`contractor_paid`	Contractor pay stubs paid during the usage month.
`employee_paid_unique`	Unique employees paid during the usage month.
`contractor_paid_unique`	Unique contractors paid during the usage month.
`funding_failure`	Billable funding failures recorded during the usage month.
`payroll_expedited`	Expedited payrolls paid during the usage month.
`kyb_attempt`	Business verification attempts recorded during the usage month.
`business_launched`	Businesses that launched during the usage month.

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.

curl --request GET \
     --url "https://sandbox.nmbr.co/services/payroll/usage_summaries?company_id=cmp_123&period_start=2025-05-01&period_end=2025-05-31" \
     --header 'Authorization: Bearer <partner_secret>' \
     --header 'accept: application/json'

Response

{
  "object": "list",
  "data": [
    {
      "id": "usum_123",
      "object": "usage_summary",
      "data": {
        "company": {
          "id": "cmp_123",
          "object": "company",
          "links": {
            "self": "/companies/cmp_123"
          }
        },
        "event": "employee_paid",
        "count": 15,
        "period_start": "2025-05-01",
        "period_end": "2025-05-31",
        "created_at": "2025-05-07T20:11:32.000000Z",
        "updated_at": "2025-05-07T20:11:32.000000Z"
      },
      "links": {
        "self": "/usage_summaries/usum_123"
      }
    },
    {
      "id": "usum_456",
      "object": "usage_summary",
      "data": {
        "company": {
          "id": "cmp_123",
          "object": "company",
          "links": {
            "self": "/companies/cmp_123"
          }
        },
        "event": "contractor_paid_unique",
        "count": 8,
        "period_start": "2025-05-01",
        "period_end": "2025-05-31",
        "created_at": "2025-05-07T20:11:32.000000Z",
        "updated_at": "2025-05-07T20:11:32.000000Z"
      },
      "links": {
        "self": "/usage_summaries/usum_456"
      }
    }
  ]
}

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.

curl --request GET \
     --url "https://sandbox.nmbr.co/services/payroll/usage_records?company_id=cmp_123&recorded_at%5Bgte%5D=2025-05-01&recorded_at%5Blt%5D=2025-06-01" \
     --header 'Authorization: Bearer <partner_secret>' \
     --header 'accept: application/json'

Response

{
  "object": "list",
  "data": [
    {
      "id": "urec_123",
      "object": "usage_record",
      "data": {
        "company": {
          "id": "cmp_123",
          "object": "company",
          "links": {
            "self": "/companies/cmp_123"
          }
        },
        "event": "employee_paid",
        "record": {
          "id": "pay_stub_123",
          "object": "pay_stub",
          "links": {
            "self": "/pay_stubs/pay_stub_123"
          }
        },
        "recorded_at": "2025-05-07 20:11:32",
        "created_at": "2025-05-07T20:11:32.000000Z",
        "updated_at": "2025-05-07T20:11:32.000000Z"
      },
      "links": {
        "self": "/usage_records/urec_123"
      }
    }
  ]
}

If a payroll was processed in May for an April pay period, the usage record still has a May recorded_at timestamp and contributes to the May summary.

Practical reconciliation flow

Fetch GET /usage_summaries for the company and month you want to invoice.
Group the returned rows by event.
Use employee_paid plus contractor_paid for per-pay-run billing.
Use employee_paid_unique plus contractor_paid_unique for per-month billing.
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.

Getting Started

Payroll Fundamentals

Canadian Payroll

Advanced Concepts

Usage & Billing

How usage is counted

Usage event types

Get monthly usage summaries

Reconcile a summary with usage records

Practical reconciliation flow

​How usage is counted

​Usage event types

​Get monthly usage summaries

​Reconcile a summary with usage records

​Practical reconciliation flow

How usage is counted

Usage event types

Get monthly usage summaries

Reconcile a summary with usage records

Practical reconciliation flow