--- updatedAt: 2026-11-04T17:24:05.000Z agentTools: projectIndex: https://docs.checkhq.com/llms.txt --- # Correcting Pay History Processing voids and historical pay adds over the API ## Overview Mistakes happen in payroll. An employee is paid after their termination date, a benefit is set up with the wrong amount, or pay history is imported incorrectly during a company's initial setup. The **Corrections API** lets you fix pay history programmatically. It supports two building block operations, which can be combined freely: * **Void payrolls** — Creating a payroll that exactly zero out an existing payroll item or contractor payment, canceling its wages and tax liabilities. * **Add payrolls** — Adding new (either managed or external) payrolls with a backdated payday. These are grouped onto a **correction**, which represents a bundle of changes to a company's pay history that is previewed, approved, and fulfilled as a single unit. Because everything on a correction is processed together, Check offsets the resulting tax liabilities against each other — taxes recovered by a void can fund the taxes owed on its replacement, so nothing is double-collected. This unlocks three (3) common workflows: 1. **Standalone voids** — canceling pay that should never have been processed (e.g., accidentally paying a terminated employee on a payroll). 2. **Void and replace** — void a mistake on a payroll and replace it with corrected pay history, as either a managed replacement payroll or an external payroll. 3. **Add missing backdated payrolls** — uploading a payroll that was missed during setup or run manually outside of Check. ## The Correction lifecycle A [correction](https://docs.checkhq.com/reference/the-correction-object) moves through the following states: 1. `draft` — the correction is editable, and new payrolls or void payrolls can be attached to it. 2. `pending` — the correction has been approved. Its money movement is scheduled to process on the correction's `settlement_date`. A `pending` correction can be [reopened](https://docs.checkhq.com/reference/reopen-a-correction) until its `reopen_deadline` to make further changes, which returns it to `draft` and deletes its fulfillment. 3. `processing` — fulfillment has begun processing, and the correction can no longer be reopened. 4. `settled` — fulfillment has been processed and the correction is reflected in the company's pay history. 5. `failed` — the fulfillment could not be processed, and must be retried. Check sends `created`, `updated`, and `deleted` webhooks with the `correction` topic, so you can track lifecycle changes (like preview completion, approval, and status changes) without polling the API. See [Corrections webhooks](https://docs.checkhq.com/reference/corrections#webhooks) for when each event is sent. ## Example: voiding and replacing a payroll The example below corrects a payroll item that was processed with the wrong amounts by voiding it and replacing it with corrected values. ### 1. Create a correction ```json POST /corrections { "company": "com_sx3svU6K8c5ZkSFlOh5p", "year": 2026, "settlement_date": "2026-07-15", "description": "Void and replace 3/31 payroll for J. Smith" } ``` The correction is created in `draft`. `company` and `year` are required — all payrolls attached to the correction must belong to the correction's tax year. The other fields are optional: * `settlement_date` — the banking day on which any resulting debit or refund will be processed. Must be a banking day between the earliest date ACH can reach and 7 days from today; any other date returns `settlement_date_invalid`, and approval checks the date again. Required before approval if the correction will debit or refund the employer. If no money moves, it can be left out and a date is set at approval. * `bank_account` — the [bank account](https://docs.checkhq.com/reference/the-bank-account-object) to debit or credit at fulfillment. If omitted, Check stamps the company's current default bank account. ### 2. Void the erroneous payroll item Use [Void a payroll](https://docs.checkhq.com/reference/void-a-payroll) to create a void payroll and attach it to the correction. By default all items on the payroll are voided; pass a `subset` object to void only specific payroll items or contractor payments. ```json POST /payrolls/pay_Z26PNMC7Ky1wfFQzVqfF/void { "correction": "cor_Bw6EkMDmxCPeVQ2eYzLu", "subset": { "payroll_items": ["itm_Ue75kUcWex5JRGTRuqux"] } } ``` The response is a draft payroll with `is_void: true` whose amounts are the exact negation of the original item. Void payrolls are not previewed or approved through the Payroll API — they are processed with the correction. ### 3. Add the corrected payroll item Create a replacement payroll attached to the same correction via the `correction` body parameter. This should be done either using the External Payroll API or the Payroll API, depending on whether the payday of the payroll being added is before or after the company's start date. * **If the payday is before the company's start date: **The payroll is **external (non-managed)**, meaning that the tax calculation for the payroll was performed by a prior provider and must be entered on the payroll. Create the payroll using the External Payroll API and the [Create an external payroll](https://docs.checkhq.com/reference/create-an-external-payroll) endpoint. * **If the payday is on or after the company's start date:** The payroll is **managed** by Check, and Check will calculate taxes for the payroll. Create the payroll using the regular Payroll API and the [Create a payroll](https://docs.checkhq.com/reference/create-payroll) endpoint. ```json POST /payrolls?include_items=true { "company": "com_sx3svU6K8c5ZkSFlOh5p", "correction": "cor_Bw6EkMDmxCPeVQ2eYzLu", "period_start": "2026-03-14", "period_end": "2026-03-27", "payday": "2026-03-31", "items": [ { "employee": "emp_zGGp6wYcxAeu1Ng8IA7v", "payment_method": "manual", "earnings": ["..."] } ] } ``` When creating a managed payroll (with a payday after the company's start date), you will not be able to preview the payroll directly with the Payroll API. Rather, the payroll will be previewed as part of previewing the correction, as shown below. ### 4. Preview the correction Once you have added all of the voids and/or backdated payrolls to the correction, the next step is to preview the correction. ``` POST /corrections/cor_Bw6EkMDmxCPeVQ2eYzLu/preview ``` [Previewing](https://docs.checkhq.com/reference/preview-a-correction) a correction is asynchronous, and does several things: * **It previews any managed payrolls attached to the correction.** * **It computes the **`totals`** of the correction,** which indicates the expected money movement for the correction. This includes the amount that will be directly debited from or refunded to the employer (the `cash_requirement`), and any tax funds that were already remitted and are refundable from the agency (`agency_refundable`). * **It rebalances any impacted closed quarters**, which get added to the list of operations on the correction as shown below. These new payrolls get fulfilled alongside the other payrolls on the correction, in a single transaction. For more on how balancing and fulfillments work generally, see [Balancing Payrolls & Fulfillment Receipts](https://docs.checkhq.com/docs/balancing-payrolls-fulfillment-guide). ```json Correction payrolls after preview { ..., "operations": [ { "operation": "balance_quarter", "creates": "pay_Vg3RvNwqLpTz8oYaGdQE", // Balancing adjustment from correction "corrects": "pay_Jd9nWuBqOxSz5eKmCvhT" // Original balancing payroll }, ... ] } ``` The preview is invalidated if payrolls are added to or removed from the correction. ### 5. Approve the correction ``` POST /corrections/cor_Bw6EkMDmxCPeVQ2eYzLu/approve ``` Like preview, [approving](https://docs.checkhq.com/reference/approve-a-correction) is asynchronous. The endpoint returns `202 Accepted`, and Check recalculates the correction's money movement and compares it against the last preview. There are a variety of reasons why the required money movement may change between preview and approval, such as tax payments being remitted or additional payrolls outside of the correction being approved. Monitor the approval via the `approval` object on the correction, by listening for the correction `updated` webhook, or by polling [Get a correction](https://docs.checkhq.com/reference/get-a-correction). * **If the approval succeeds**, the correction moves to `pending`, and its money movement is scheduled to process on the `settlement_date`. * **If the approval fails**, `approval.status` is `failed`, the correction remains in `draft`, and `approval.error_code` says why: * `fulfillment_changed` — the amounts changed since the preview, for example because the company's pay history changed after the preview was run. `totals` is refreshed to reflect the updated amounts. Review the new totals, re-run [Preview a correction](https://docs.checkhq.com/reference/preview-a-correction) if needed, and then approve again. * `balancing_changed` — the balancing payrolls for an impacted closed quarter changed since the preview. The refreshed balancing payrolls are on the correction. When both the amounts and the balancing changed, this code is the one reported. * `payroll_item_already_voided` — a void of the same payroll item on another correction was approved first. [Delete](https://docs.checkhq.com/reference/delete-a-payroll) the conflicting void payroll from this correction, then preview and approve again. * `approval_failed` — the approval failed for any other reason. ```json Fulfillment changed error { "status": "draft", "approval": { "status": "failed", "started_at": "2026-06-25T12:24:23.441459Z", "error_code": "fulfillment_changed" } } ``` A correction cannot be approved if it has no payrolls attached, if its preview is stale or has not been run, or if it moves money and has no `settlement_date`. See [Approve a correction](https://docs.checkhq.com/reference/approve-a-correction) for every error the request can return. While an approval is in progress, the correction cannot be edited, deleted, or previewed. Once the correction is `pending`, if something needs to change, [reopen the correction](https://docs.checkhq.com/reference/reopen-a-correction) to return it to `draft`. Reopening is possible until the correction's `reopen_deadline`, after which fulfillment begins processing.