Skip to main content
Bulk pay stub operations create, update, or delete many pay stubs in one API call. They apply only to payrolls that accept manual pay stub management: once-off, historical, correction, and custom-schedule payrolls in draft status. Regular scheduled payrolls generate their pay stubs automatically, so you can’t bulk-create on them. Selection differs between create and update/delete:
  • Create selects work assignments on the payroll’s pay schedule and creates one pay stub per work assignment.
  • Update and delete select pay stubs that already exist on the payroll.

​
Asynchronous Execution

Bulk pay stub operations are asynchronous. Every bulk endpoint returns an async_task handle that you use to track completion and retrieve the affected entities. The task may or may not have completed by the time you receive the response. data.status could be processing or completed. Partners must always check data.status and not assume the work has finished. You have two ways to observe completion:
  • Poll the URL in links.self on the response until data.status is completed (or error).
  • Subscribe to the async_task_completed webhook event, which fires when the task finishes.
data.results contains one entry per affected pay stub, with only the id and object. To retrieve full pay stub bodies, follow up with a list query (filtered by the returned IDs) or fetch individual pay stubs by ID. Note: scope endpoints (/bulk/*/scope) are previews with no side effects and are synchronous - they return 200 OK with the inline list of matched entities.

​
Bulk Create Pay Stubs

Nmbr’s API allows you to create a pay stub for select work assignments on a single payroll. This endpoint is useful when you need to add a group of employees or contractors to an off-cycle or historical payroll in one API call. Create selects work assignments rather than pay stubs, because the pay stubs don’t exist yet. The work assignments come from the payroll’s pay schedule.

​
Endpoint

POST /pay_stubs/bulk/create

​
Request

{
  "payroll_id": ULID,
  "work_assignments": {
    "include": "all" | criteria object,
    "exclude": criteria object (optional)
  },
  "data": {
    ...pay stub properties...
  }
}

​
Request Properties

PropertyTypeRequiredDescription
payroll_idULIDYesID of the payroll to create the pay stubs under
work_assignments.includecriteria object or "all"YesCriteria for selecting work assignments to include
work_assignments.excludecriteria objectNoCriteria for selecting work assignments to exclude
dataobjectNoThe properties to apply to each created pay stub

​
Work Assignment Criteria Objects

include and exclude can be objects with one or more of the following properties:
  • ids: Array of work assignment IDs to include or exclude
  • payee_type: "employee" or "contractor"
  • pay_schedule_id: ID of the pay schedule to include or exclude
  • archived: true to select archived work assignments, false (default) to select active ones
  • payee_names: Name search (partial match)
When you combine properties, they apply together. include can also be the string "all" to include all work assignments on the payroll’s pay schedule.

​
Data Properties

The data object contains the pay stub properties to apply to each created pay stub:
PropertyDescription
payment_methodPayment method for the pay stub. Must match the business entity’s locked payment method, if set
noteA note on the pay stub
external_refYour external identifier for the pay stub
The payroll and work assignment for each pay stub come from your selection. Don’t set payroll_id or work_assignment_id in data. These properties are documented in more detail in the API reference for pay stubs.

​
Response

On success, the operation returns 202 Accepted with an async_task handle. See Asynchronous Execution for how to track completion. ⚠️ Partners must treat any 200-level response as success. ⚠️ For example, the response might look like: 
{
  "id": "asnct_01KS0G8Z2YD3T9KQNFW1XEA7HB",
  "object": "async_task",
  "data": {
    "type": "bulk_create",
    "status": "processing",
    "completed_at": null,
    "results": [],
    "created_at": "2026-05-19T16:14:32Z",
    "updated_at": "2026-05-19T16:14:32Z"
  },
  "links": {
    "self": "/async_tasks/asnct_01KS0G8Z2YD3T9KQNFW1XEA7HB"
  }
}
Once the task completes, data.results will contain one entry per created pay stub: 
{
  "id": "asnct_01KS0G8Z2YD3T9KQNFW1XEA7HB",
  "object": "async_task",
  "data": {
    "type": "bulk_create",
    "status": "completed",
    "completed_at": "2026-05-19T16:14:35Z",
    "results": [
      { "id": "payst_01J8KXC9R4MQVW2FXZN7Y5H3B8", "object": "pay_stub" },
      { "id": "payst_01KBMZDVV9G7713DJRYP9RJFTP", "object": "pay_stub" }
    ],
    "created_at": "2026-05-19T16:14:32Z",
    "updated_at": "2026-05-19T16:14:35Z"
  },
  "links": {
    "self": "/async_tasks/asnct_01KS0G8Z2YD3T9KQNFW1XEA7HB"
  }
}
On failure, the operation will return 422 Unprocessable Entity with standard validation messages.

​
Notes

  • The payroll must be a once-off, historical, correction, or custom-schedule payroll in draft status. Regular scheduled payrolls are rejected.
  • The same pay stub properties are applied to every created pay stub.
  • Work assignments that already have a pay stub on the payroll are skipped. There is one pay stub per work assignment per payroll. Skipped work assignments won’t appear in data.results.
  • Each created pay stub’s totals are recalculated after creation, populating any managed line items the work assignment’s configuration produces.
  • Validation runs against every selected work assignment before any pay stub is created. If validation fails, no pay stubs are created.
  • Invalid work assignment IDs in the include.ids or exclude.ids arrays are silently ignored and won’t cause an error.
  • When both include and exclude criteria are provided, exclusions are applied after inclusions.

​
Examples

​
Create a pay stub for every work assignment on the payroll’s pay schedule

POST /pay_stubs/bulk/create 
{
  "payroll_id": "payrl_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "work_assignments": {
    "include": "all"
  }
}

​
Create pay stubs for specific work assignments with a note

POST /pay_stubs/bulk/create 
{
  "payroll_id": "payrl_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "work_assignments": {
    "include": {
      "ids": [
        "wrkas_01J8KXB4N6RQWM2FVZH9Y3T5C8",
        "wrkas_01J8KXB7P2MQVW4RXZN6Y8H3F1"
      ]
    }
  },
  "data": {
    "note": "Q4 bonus run"
  }
}

​
Create pay stubs for all employees, excluding contractors

POST /pay_stubs/bulk/create 
{
  "payroll_id": "payrl_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "work_assignments": {
    "include": "all",
    "exclude": {
      "payee_type": "contractor"
    }
  }
}

​
Bulk Create Pay Stubs Scope

The create scope endpoint previews which work assignments will receive a new pay stub from a bulk create operation. It accepts the same request body as the bulk create endpoint, but instead of creating pay stubs, it returns the work assignments that match the criteria. Because the pay stubs don’t exist yet, this endpoint returns work assignments, not pay stubs. Work assignments that already have a pay stub on the payroll are excluded, matching the create behavior. This is useful for confirming which work assignments a bulk create will affect before executing it.

​
Endpoint

POST /pay_stubs/bulk/create/scope

​
Request

The request body is the same as the bulk create endpoint.

​
Response

On success, the operation will return 200 OK with an array of the work assignments that the bulk create would create pay stubs for: 
{
  "data": [
    {
      "id": "wrkas_01J8KXB4N6RQWM2FVZH9Y3T5C8",
      "data": {
        ...work assignment properties...
      }
    },
    ...
  ]
}

​
Bulk Update Pay Stubs

Nmbr’s API allows you to update select pay stubs within a single payroll. This endpoint is useful when you need to set the same property on a group of pay stubs in one API call, such as adding a note or changing the payment method.

​
Endpoint

POST /pay_stubs/bulk/update

​
Request

{
  "payroll_id": ULID,
  "pay_stubs": {
    "include": "all" | criteria object,
    "exclude": criteria object (optional)
  },
  "data": {
    ...properties to update...
  }
}

​
Request Properties

PropertyTypeRequiredDescription
payroll_idULIDYesID of the payroll containing the pay stubs
pay_stubs.includecriteria object or "all"YesCriteria for selecting pay stubs to include
pay_stubs.excludecriteria objectNoCriteria for selecting pay stubs to exclude
dataobjectYesThe properties to update on the matching pay stubs

​
Pay Stub Criteria Objects

include and exclude can be objects with one or more of the following properties:
  • ids: Array of pay stub IDs to include or exclude
  • work_assignment_ids: Array of work assignment IDs. Selects the pay stubs for those work assignments
  • payee_type: "employee" or "contractor"
include can also be the string "all" to include all pay stubs on the payroll.

​
Data Properties

The data object contains the pay stub properties to update:
PropertyDescription
payment_methodPayment method for the pay stub. Must match the business entity’s locked payment method, if set
noteA note on the pay stub
external_refYour external identifier for the pay stub

​
Response

On success, the operation returns 202 Accepted with an async_task handle whose data.results enumerates the updated pay stubs. See Asynchronous Execution for how to track completion and Bulk Create Pay Stubs › Response for an example response shape. data.type will be bulk_update. ⚠️ Partners must treat any 200-level response as success. ⚠️ On failure, the operation will return 422 Unprocessable Entity with standard validation messages. If any matched pay stub fails per-model validation, the entire request fails and no pay stubs are updated.

​
Notes

  • The payroll must be a once-off, historical, correction, or custom-schedule payroll in draft status. Regular scheduled payrolls are rejected.
  • The same update properties are applied to all selected pay stubs.
  • The operation only affects pay stubs within the specified payroll.
  • Invalid pay stub IDs in the include.ids or exclude.ids arrays are silently ignored and won’t cause an error.
  • When both include and exclude criteria are provided, exclusions are applied after inclusions.

​
Examples

​
Add a note to every pay stub in a payroll

POST /pay_stubs/bulk/update 
{
  "payroll_id": "payrl_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "pay_stubs": {
    "include": "all"
  },
  "data": {
    "note": "Reviewed by payroll admin"
  }
}

​
Update the pay stubs for specific work assignments

POST /pay_stubs/bulk/update 
{
  "payroll_id": "payrl_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "pay_stubs": {
    "include": {
      "work_assignment_ids": ["wrkas_01J8KXB4N6RQWM2FVZH9Y3T5C8"]
    }
  },
  "data": {
    "external_ref": "run-2026-04-offcycle"
  }
}

​
Bulk Update Pay Stubs Scope

The update scope endpoint previews which pay stubs will be updated by a bulk update operation. It accepts the same request body as the bulk update endpoint, but instead of updating pay stubs, it returns the pay stubs that match the criteria.

​
Endpoint

POST /pay_stubs/bulk/update/scope

​
Request

The request body is the same as the bulk update endpoint.

​
Response

On success, the operation will return 200 OK with an array of the pay stubs that would be updated: 
{
  "data": [
    {
      "id": "payst_01J8KXC9R4MQVW2FXZN7Y5H3B8",
      "data": {
        ...pay stub properties...
      }
    },
    ...
  ]
}

​
Bulk Delete Pay Stubs

Nmbr’s API allows you to delete select pay stubs within a single payroll. This endpoint is useful when you need to remove a group of pay stubs from an off-cycle or historical payroll in one API call.

​
Endpoint

POST /pay_stubs/bulk/delete

​
Request

{
  "payroll_id": ULID,
  "pay_stubs": {
    "include": "all" | criteria object,
    "exclude": criteria object (optional)
  }
}

​
Request Properties

PropertyTypeRequiredDescription
payroll_idULIDYesID of the payroll containing the pay stubs
pay_stubs.includecriteria object or "all"YesCriteria for selecting pay stubs to include
pay_stubs.excludecriteria objectNoCriteria for selecting pay stubs to exclude

​
Pay Stub Criteria Objects

include and exclude can be objects with one or more of the following properties:
  • ids: Array of pay stub IDs to include or exclude
  • work_assignment_ids: Array of work assignment IDs. Selects the pay stubs for those work assignments
  • payee_type: "employee" or "contractor"
include can also be the string "all" to include all pay stubs on the payroll.

​
Response

On success, the operation returns 202 Accepted with an async_task handle whose data.results enumerates the deleted pay stubs (still surfaced by ID - the records soft-delete and remain queryable). See Asynchronous Execution for how to track completion and Bulk Create Pay Stubs › Response for an example response shape. data.type will be bulk_delete. ⚠️ Partners must treat any 200-level response as success. ⚠️ On failure, the operation will return 422 Unprocessable Entity with standard validation messages.

​
Notes

  • The payroll must be a once-off, historical, correction, or custom-schedule payroll in draft status. Regular scheduled payrolls are rejected.
  • The operation only affects pay stubs within the specified payroll.
  • Invalid pay stub IDs in the include.ids or exclude.ids arrays are silently ignored and won’t cause an error.
  • When both include and exclude criteria are provided, exclusions are applied after inclusions.

​
Examples

​
Delete every pay stub in a payroll

POST /pay_stubs/bulk/delete 
{
  "payroll_id": "payrl_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "pay_stubs": {
    "include": "all"
  }
}

​
Delete pay stubs for specific work assignments

POST /pay_stubs/bulk/delete 
{
  "payroll_id": "payrl_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "pay_stubs": {
    "include": {
      "work_assignment_ids": [
        "wrkas_01J8KXB4N6RQWM2FVZH9Y3T5C8",
        "wrkas_01J8KXB7P2MQVW4RXZN6Y8H3F1"
      ]
    }
  }
}

​
Bulk Delete Pay Stubs Scope

The delete scope endpoint previews which pay stubs will be deleted by a bulk delete operation. It accepts the same request body as the bulk delete endpoint, but instead of deleting pay stubs, it returns the pay stubs that match the criteria.

​
Endpoint

POST /pay_stubs/bulk/delete/scope

​
Request

The request body is the same as the bulk delete endpoint.

​
Response

On success, the operation will return 200 OK with an array of the pay stubs that would be deleted: 
{
  "data": [
    {
      "id": "payst_01J8KXC9R4MQVW2FXZN7Y5H3B8",
      "data": {
        ...pay stub properties...
      }
    },
    ...
  ]
}