Calculating usage for your customers

To grow your payroll business, understanding customer usage of payroll features is essential for determining billable costs for each employer. The Usage API provides aggregated usage metrics for employers, offering detailed counts across various dimensions of the Salsa platform.

You can retrieve metrics for a specific employer or all employers within a chosen date range. Available metrics include:

Metric Name	Description
`PAYROLL_RUN`	The number of payroll runs that were confirmed.
`WORKER_PAYMENT`	The number of worker payments that were made.
`WORKER_PAID`	The distinct number of workers that were paid.
`WORKER_ANNUAL_TAX_FILING_SENT`	The number of worker tax filings that were sent.
`EMPLOYER_FUNDING_RETURN`	The number of employer funding debits that were returned.
`EMPLOYER_SUBSCRIBER`	Whether or not the employer had an active subscription in the period (1 for `true`, 0 for `false`).

REST API Endpoints

Each endpoint requires a date range, and both the start and end dates are inclusive. For example, to retrieve usage metrics for November 2024, specify a start date of 2024-11-01 and an end date of 2024-11-30. If you need metrics for a single day, use the same date for both the start and end date parameters.

Retrieve usage metrics for an employer

You can retrieve the metrics for a specific employer via this endpoint. See the reference document for this endpoint.

Here is an example response that you may expect to receive:

{
  "employerId": "er_66d541ff-8e82-4038-9b6e-20fec15f3905",
  "startDate": "2024-11-01",
  "endDate": "2024-11-30",
  "metrics": [
    {
      "name": "EMPLOYER_SUBSCRIBER",
      "count": 1
    },
    {
      "metric": "PAYROLL_RUN",
      "count": 5
    },
    {
      "metric": "WORKER_PAYMENT",
      "count": 48
    },
    {
      "metric": "WORKER_PAID",
      "count": 10
    },
    {
      "metric": "EMPLOYER_FUNDING_RETURN",
      "count": 2
    },
    {
      "metric": "WORKER_ANNUAL_TAX_FILING_SENT",
      "count": 0
    }
  ]
}

Retrieve all employers' usage metrics

You can retrieve the metrics for all of your employers via this endpoint. See the reference document for this endpoint. Given that this list can grow to be quite large, this endpoint returns the data paginated.

Example Response:

[
  {
    "employerId": "er_7d02984d-06e4-432a-a66b-c14ad939a3f0",
    "periodStart": "2024-11-01",
    "periodEnd": "2024-11-30",
    "metrics": [
      {
        "name": "EMPLOYER_SUBSCRIBER",
        "count": 1
      },
      {
        "metric": "PAYROLL_RUN",
        "count": 3
      },
      {
        "metric": "WORKER_PAYMENT",
        "count": 15
      },
      {
        "metric": "WORKER_PAID",
        "count": 5
      },
      {
        "metric": "EMPLOYER_FUNDING_RETURN",
        "count": 0
      },
      {
        "metric": "WORKER_ANNUAL_TAX_FILING_SENT",
        "count": 0
      }
    ]
  },
  {
    "employerId": "er_7171b9d1-26ce-45b7-bad1-28b6cfe34396",
    "periodStart": "2024-11-01",
    "periodEnd": "2024-11-30",
    "metrics": [
      {
        "name": "EMPLOYER_SUBSCRIBER",
        "count": 1
      },
      {
        "metric": "PAYROLL_RUN",
        "count": 9
      },
      {
        "metric": "WORKER_PAYMENT",
        "count": 47
      },
      {
        "metric": "WORKER_PAID",
        "count": 21
      },
      {
        "metric": "EMPLOYER_FUNDING_RETURN",
        "count": 1
      },
      {
        "metric": "WORKER_ANNUAL_TAX_FILING_SENT",
        "count": 0
      }
    ]
  }
]