Calculates the gross earning needed for an employee to receive a target net amount, and saves it on the payroll item.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Early previewGross-up is in early preview and will be released to all partners by November 19, 2026. Until then the endpoint is enabled per provider; contact your Check representative to turn it on in your sandbox. See the Gross-up Payments guide for the full workflow.
Replaces the payroll item's earnings with a single bonus or commission earning whose amount is the gross wage that nets to the requested net_amount after the employee's taxes. The saved gross is the smallest amount, to the cent, whose net is at least net_amount; because taxes are withheld in whole cents, the net may be a few cents above the target. The calculation is synchronous: a 200 response means the gross has been calculated and saved, and the payroll's current preview has been invalidated.
The payroll item must belong to a draft off-cycle payroll with apply_benefits and apply_post_tax_deductions both false. The request must contain exactly one earning, and any earnings already saved on the item are replaced. Reimbursements already saved on the item are kept and are paid in addition to the target net.
Check does not store net_amount. After a successful call the saved earning is an ordinary fixed-gross earning, and the response is the standard payroll item object. To change the target later, call this endpoint again with the new net_amount.
The item's saved supplemental_tax_calc_method and tax_overrides are used in the calculation. Set them with Update a payroll item before calling this endpoint; the request accepts only earnings and rejects any other payroll item field.
Send an X-Idempotency-Key header and reuse it only when retrying the same request after a timeout. Within the 24-hour retention window a replay returns the original outcome rather than calculating again. A new key starts a new calculation from the net_amount in that request; it never treats a previously calculated gross as a new target.
Errors
Validation failures return a validation_error with field-attributed input_errors. The item is left unchanged on any error.
| Condition | Field path |
|---|---|
Payroll is not an off-cycle payroll, or has apply_benefits or apply_post_tax_deductions enabled | payroll |
earnings is missing, empty, or contains more than one entry | earnings |
Earning type is not bonus or commission | earnings[0].type |
Earning code is not of type bonus or commission | earnings[0].earning_code |
net_amount is missing, zero, or negative | earnings[0].net_amount |
amount or earning_rate is included | earnings[0].amount or earnings[0].earning_rate |
Any field other than earnings is included, such as tax_overrides | That field |
An approved payroll returns payroll_already_approved and a payroll managed by a correction returns payroll_managed_by_correction, as on other payroll item writes. If gross-up is not enabled for your provider, the response is 404, the same as for an unknown item. If Check cannot produce a gross whose net reaches net_amount, the response is a 5xx error and the item is unchanged; this should not happen in practice.