Bulk Line Item Operations

Asynchronous Execution

Bulk line item 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 line item — only the id and object. To retrieve full line item bodies, follow up with a list query (filtered by the returned IDs) or fetch individual entities 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 Line Items

Nmbr’s API allows you to create a line item on select pay stubs within a single payroll. This endpoint is useful when you need to create line items on one or more pay stubs in one API call, such as applying a company-wide bonus to a group of employees.

Endpoint

POST /<type>_line_items/bulk/create <type> can be one of the following types:

allowance
deduction
earning
employee_benefit
employer_benefit
reimbursement

Request

{
  "payroll_id": ULID,
  "pay_stubs": {
    "include": "all" | criteria object,
    "exclude": criteria object (optional)
  },
  "data": {
    ...type-specific line item properties...
  }
}

Request Properties

Property	Type	Required	Description
`payroll_id`	ULID	Yes	ID of the payroll containing the pay stubs
`pay_stubs.include`	criteria object or `"all"`	Yes	Criteria for selecting pay stubs to include
`pay_stubs.exclude`	criteria object	No	Criteria for selecting pay stubs to exclude
`data`	object	Yes	The properties of the line item to create

The data object contains any line item properties specific to the type of line item being created. For example, for earning line items:

Property	Description
`earning_type`	Type of earning (e.g., `"wage"`, `"bonus"`, `"overtime"`)
`business_preset_id`	ID of a business preset to use as template
`custom_amount`	Amount for the line item
`custom_hours`	Hours for the line item
`title`	Title for the line item
`expense_accounting_code_id`	ID of the expense accounting code
`liability_accounting_code_id`	ID of the liability accounting code

These properties are documented in more detail in the API reference for each line item type.

Request Criteria Objects

include and exclude can be objects with one of the following properties:

ids: Array of pay stub IDs to include
payee_type: "employee" or "contractor"

include can also be the string "all" to include all 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 line item:

{
  "id": "asnct_01KS0G8Z2YD3T9KQNFW1XEA7HB",
  "object": "async_task",
  "data": {
    "type": "bulk_create",
    "status": "completed",
    "completed_at": "2026-05-19T16:14:35Z",
    "results": [
      {
        "id": "ernli_01J8KXC9R4MQVW2FXZN7Y5H3B8",
        "object": "earning_line_item"
      },
      {
        "id": "ernli_01KBMZDVV9G7713DJRYP9RJFTP",
        "object": "earning_line_item"
      }
    ],
    "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 same line item properties will be applied to all selected pay stubs.
When using a business_preset_id, properties must either be omitted or match the preset’s values.
The operation only affects pay stubs within the specified payroll. Pay stubs in other payrolls will not be affected.
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.
The payroll’s totals are automatically recalculated after the bulk creation.
The payroll must be in draft status.

Examples

Create an earning line item on all pay stubs

POST /earning_line_items/bulk/create

{
  "payroll_id": "payrl_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "pay_stubs": {
    "include": "all"
  },
  "data": {
    "earning_type": "bonus_discretionary",
    "custom_amount": 500.0,
    "title": "Year-end Bonus"
  }
}

Create earning line items using a business preset

POST /earning_line_items/bulk/create

{
  "payroll_id": "payrl_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "pay_stubs": {
    "include": "all"
  },
  "data": {
    "business_preset_id": "rps_01J8KXD3M7RQWN2FXZV9Y4H6B1",
    "custom_amount": 100.0
  }
}

Create earning line items for specific pay stubs

POST /earning_line_items/bulk/create

{
  "payroll_id": "payrl_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "pay_stubs": {
    "include": {
      "ids": [
        "payst_01J8KXB4N6RQWM2FVZH9Y3T5C8",
        "payst_01J8KXB7P2MQVW4RXZN6Y8H3F1",
        "payst_01J8KXBA3TWQNM7FXZR9Y2V5C4"
      ]
    }
  },
  "data": {
    "earning_type": "wage",
    "custom_amount": 1000.0,
    "title": "Special Assignment Pay"
  }
}

Create earning line items on all employee pay stubs, excluding specific pay stubs (and implicitly excluding contractor pay stubs)

POST /earning_line_items/bulk/create

{
  "payroll_id": "payrl_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "pay_stubs": {
    "include": {
      "payee_type": "employee"
    },
    "exclude": {
      "ids": ["payst_01J8KXB4N6RQWM2FVZH9Y3T5C8"]
    }
  },
  "data": {
    "earning_type": "bonus_discretionary",
    "custom_amount": 250.0,
    "title": "Appreciation Bonus",
    "expense_accounting_code_id": "accod_01J8KXF2N4MQRW3VXZH7Y9B5C8",
    "liability_accounting_code_id": "accod_01J8KXF5P6RQNW4MXZV8Y2H7F1"
  }
}

Create earning line items for all pay stubs except contractors

POST /earning_line_items/bulk/create

{
  "payroll_id": "payrl_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "pay_stubs": {
    "include": "all",
    "exclude": {
      "payee_type": "contractor"
    }
  },
  "data": {
    "earning_type": "bonus_discretionary",
    "custom_amount": 200.0,
    "title": "Christmas Bonus"
  }
}

Bulk Create Line Items Scope

The create scope endpoint previews which pay stubs will have new line items created on them by a bulk create operation. It accepts the same request body as the bulk create endpoint, but instead of creating line items, it returns the pay stubs that match the criteria. This is useful for confirming which pay stubs a bulk create will affect before executing it.

Endpoint

POST /<type>_line_items/bulk/create/scope <type> can be one of the following types:

allowance
deduction
earning
employee_benefit
employer_benefit
reimbursement

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 pay stubs that the bulk create would create line items on:

{
  "data": [
    {
      "id": "payst_01J8KXB4N6RQWM2FVZH9Y3T5C8",
      "data": {
        ...pay stub properties...
      }
    },
    ...
  ]
}

Bulk Update Line Items

Nmbr’s API allows you to update all line items of a single type on select pay stubs within a single payroll. This endpoint is useful when you need to update the same property on one or more line items in one API call, such as changing the amount or accounting code on a group of line items.

Endpoint

POST /<type>_line_items/bulk/update <type> can be one of the following types:

allowance
deduction
earning
employee_benefit
employer_benefit
reimbursement

Request

{
  "payroll_id": "string",
  "pay_stubs": {
    "include": "all" | criteria object,
    "exclude": criteria object (optional)
  },
  "business_presets": {
    "include": { "ids": [...] },
    "exclude": { "ids": [...] }
  },
  "expense_accounting_codes": {
    "include": { "ids": [...] },
    "exclude": { "ids": [...] }
  },
  "liability_accounting_codes": {
    "include": { "ids": [...] },
    "exclude": { "ids": [...] }
  },
  "data": {
    ...properties to update...
  }
}

Request Properties

Property	Type	Required	Description
`payroll_id`	ULID	Yes	ID of the payroll containing the pay stubs
`pay_stubs.include`	criteria object or `"all"`	Yes	Criteria for selecting pay stubs to include
`pay_stubs.exclude`	criteria object	No	Criteria for selecting pay stubs to exclude
`business_presets.include.ids`	array of ULIDs or `null`	No	Only update line items with one of these business preset IDs. Use `null` to match line items with no business preset.
`business_presets.exclude.ids`	array of ULIDs or `null`	No	Exclude line items with one of these business preset IDs. Use `null` to exclude line items with no business preset.
`expense_accounting_codes.include.ids`	array of ULIDs or `null`	No	Only update line items with one of these expense accounting code IDs. Use `null` to match line items with no expense accounting code.
`expense_accounting_codes.exclude.ids`	array of ULIDs or `null`	No	Exclude line items with one of these expense accounting code IDs. Use `null` to exclude line items with no expense accounting code.
`liability_accounting_codes.include.ids`	array of ULIDs or `null`	No	Only update line items with one of these liability accounting code IDs. Use `null` to match line items with no liability accounting code.
`liability_accounting_codes.exclude.ids`	array of ULIDs or `null`	No	Exclude line items with one of these liability accounting code IDs. Use `null` to exclude line items with no liability accounting code.
`data`	object	Yes	The properties to update on the matching line items

The data object contains any line item properties to update. These are the same properties accepted by the single-resource update endpoint for each line item type, and are documented in the API reference for each type.

Pay Stub Criteria Objects

include and exclude can be objects with one of the following properties:

ids: Array of pay stub IDs to include or exclude
payee_type: "employee" or "contractor"

include can also be the string "all" to include all pay stubs.

Response

On success, the operation returns 202 Accepted with an async_task handle whose data.results enumerates the updated line items. See Asynchronous Execution for how to track completion and Bulk Create Line Items › 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 line item fails per-model validation, the entire request fails and no line items are updated.

Notes

The same update properties will be applied to all selected line items.
The operation only affects custom line items. Managed line items will not be affected.
The payroll must be in draft status.
The payroll’s totals are automatically recalculated after the bulk update.
The pay_stubs criteria select which pay stubs to look under. The business_presets, expense_accounting_codes, and liability_accounting_codes criteria further filter which line items under those pay stubs are updated.

Examples

Update the amount on all earning line items

POST /earning_line_items/bulk/update

{
  "payroll_id": "payrl_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "pay_stubs": {
    "include": "all"
  },
  "data": {
    "custom_amount": 500.0
  }
}

Update the accounting code on all earning line items with a specific business preset

POST /earning_line_items/bulk/update

{
  "payroll_id": "payrl_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "pay_stubs": {
    "include": "all"
  },
  "business_presets": {
    "include": {
      "ids": ["rps_01J8KXD3M7RQWN2FXZV9Y4H6B1"]
    }
  },
  "data": {
    "expense_accounting_code_id": "accod_01J8KXF2N4MQRW3VXZH7Y9B5C8"
  }
}

Update earning line items that have no business preset

POST /earning_line_items/bulk/update

{
  "payroll_id": "payrl_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "pay_stubs": {
    "include": "all"
  },
  "business_presets": {
    "include": {
      "ids": [null]
    }
  },
  "data": {
    "custom_amount": 500.0
  }
}

Bulk Update Line Items Scope

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

Endpoint

POST /<type>_line_items/bulk/update/scope <type> can be one of the following types:

allowance
deduction
earning
employee_benefit
employer_benefit
reimbursement

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 line items that would be updated:

{
  "data": [
    {
      "id": "ernli_01J8KXC9R4MQVW2FXZN7Y5H3B8",
      "data": {
        ...line item properties...
      }
    },
    ...
  ]
}

Notes

Only custom line items are returned. Managed line items are excluded, matching the behavior of the bulk update operation.

Bulk Delete Line Items

Nmbr’s API allows you to delete all line items of a single type on select pay stubs within a single payroll. This endpoint is useful when you need to remove line items on one or more pay stubs in one API call. Important: This operation deletes ALL line items of the specified type on the pay stubs, not specific line items. If you want to delete specific line items, you should use the batch delete line items endpoints instead.

Endpoint

POST /<type>_line_items/bulk/delete <type> can be one of the following types:

allowance
deduction
earning
employee_benefit
employer_benefit
reimbursement

Request

{
  "payroll_id": "string",
  "pay_stubs": {
    "include": "all" | criteria object,
    "exclude": criteria object (optional)
  },
  "business_presets": {
    "include": { "ids": [...] },
    "exclude": { "ids": [...] }
  },
  "expense_accounting_codes": {
    "include": { "ids": [...] },
    "exclude": { "ids": [...] }
  },
  "liability_accounting_codes": {
    "include": { "ids": [...] },
    "exclude": { "ids": [...] }
  }
}

Request Properties

Property	Type	Required	Description
`payroll_id`	ULID	Yes	ID of the payroll containing the pay stubs
`pay_stubs.include`	criteria object or `"all"`	Yes	Criteria for selecting pay stubs to include
`pay_stubs.exclude`	criteria object	No	Criteria for selecting pay stubs to exclude
`business_presets.include.ids`	array of ULIDs or `null`	No	Only delete line items with one of these business preset IDs. Use `null` to match line items with no business preset.
`business_presets.exclude.ids`	array of ULIDs or `null`	No	Exclude line items with one of these business preset IDs. Use `null` to exclude line items with no business preset.
`expense_accounting_codes.include.ids`	array of ULIDs or `null`	No	Only delete line items with one of these expense accounting code IDs. Use `null` to match line items with no expense accounting code.
`expense_accounting_codes.exclude.ids`	array of ULIDs or `null`	No	Exclude line items with one of these expense accounting code IDs. Use `null` to exclude line items with no expense accounting code.
`liability_accounting_codes.include.ids`	array of ULIDs or `null`	No	Only delete line items with one of these liability accounting code IDs. Use `null` to match line items with no liability accounting code.
`liability_accounting_codes.exclude.ids`	array of ULIDs or `null`	No	Exclude line items with one of these liability accounting code IDs. Use `null` to exclude line items with no liability accounting code.

Pay Stub Criteria Objects

include and exclude can be objects with one of the following properties:

ids: Array of pay stub IDs to include or exclude
payee_type: "employee" or "contractor"

include can also be the string "all" to include all pay stubs.

Response

On success, the operation returns 202 Accepted with an async_task handle whose data.results enumerates the deleted line items (still surfaced by ID — the records soft-delete and remain queryable). See Asynchronous Execution for how to track completion and Bulk Create Line Items › 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.