Payroll item warnings

Note: It may be helpful to read Miscellaneous Post-Tax Deduction as context for this post.

When running a payroll, it’s not always possible to apply every miscellaneous post-tax deduction. If an employee’s net pay would be below 0, we will apply miscellaneous post-tax deductions in ascending order by the deduction’s date of creation and skip deductions that would result in a negative net pay.

To help you communicate this scenario to your users, we’ve introduced a warnings array field on the payroll item object. This will allow you to let your users know when certain deductions have been skipped and why.

For all skipped deductions in previewed or approved payrolls, there will be a corresponding element in the warnings array with a post_tax_deduction id field that references the relevant deduction, a code field that states the action Check took, and a reason field that explains why the deduction was not applied.

The following is an example of a payroll item that has one applied post-tax deduction and one skipped post-tax deduction.

    "id": "itm_gmnUT3SHlK8KGreThjk",
    "payroll": "pay_F9d8SB3dau7TdpRdEGR",
    "employee": "emp_BVbhNzwO9KuH4Ge2TIZ",
    "employee_name": "Meryl Streep",
    "workplace": "wrk_zrLXONRICx3Kf8NuCi",
    "payment_method": "direct_deposit",
    "pto_balance_hours": null,
    "sick_balance_hours": null,
    "net_pay": "1001.39",
    "earnings": [
            "amount": "1600.00",
            "hours": 40.0,
            "type": "regular",
            "code": null,
            "description": null
    "taxes": [
            "tax": "tax_8L3JLfsH4X6dp0maBWfW",
            "description": "Federal Income Tax",
            "amount": "468.61",
            "payer": "employee",
            "remittable": true
    "benefits": [],
    "post_tax_deductions": [
            "post_tax_deduction": "ptd_UI2TaCa1aPwJba6mAwIL",
            "type": "miscellaneous",
            "description": "SAG union dues"
            "amount": "130.00"
    "warnings": [
            "post_tax_deduction": "ptd_lajisjdfoiasoifio239",
            "code": "skipped_post_tax_deduction",
            "reason": "negative_net_pay"

The possible values of code and reason are enumerated in the PayrollItem API docs.