v1

latestOpenAPI 3.1.02026-07-243113441.2 MB

Payroll Cancellations

Create a payroll cancellation batch

Cancels up to 100 payrolls across one or more companies the partner is mapped to, asynchronously.

The batch is processed asynchronously. Use the returned batch UUID to poll GET /v1/payroll_batches/{payroll_batch_uuid} for status and per-payroll results.

Each item carries the payroll uuid and the company_uuid that owns it. A payroll whose company is not mapped to the partner — or that doesn't exist — is recorded as a not_found exclusion rather than a hard error, so every requested UUID lands in either results or exclusions.

Idempotency is scoped per (partner, idempotency_key). A duplicate POST with the same idempotency_key returns a 409 Conflict referencing the existing batch UUID — no duplicate processing occurs.

📘 System Access Authentication

This endpoint uses the Bearer Auth scheme with the system-level access token in the HTTP Authorization header

scope: payroll_batches:write

post/v1/payroll_batches

Headers

X-Gusto-API-Version'2026-06-15'

Determines the date-based API version associated with your API call. If none is provided, your application's minimum API version is used.

Request body

idempotency_keystring uuid required

A partner-generated unique identifier to ensure idempotency of the batch request. Scoped per partner.

batch_action'cancel' required

The action to perform on the batch. Only cancel is supported.

Example request

{
  "idempotency_key": "80a74f8b-2c16-45e5-9038-aa108849c6e6",
  "batch_action": "cancel",
  "batch": [
    {
      "entity_type": "payroll"
    }
  ]
}

Response

created

uuidstring uuid required

The unique identifier of the payroll cancellation batch.

idempotency_keystring uuid required

The idempotency key provided when creating the batch.

batch_action'cancel' required

The action being performed on the batch.

status'pending' | 'processing' | 'completed' | 'failed' required

The lifecycle status of the batch request itself. Terminal values are completed (processing finished — inspect results and exclusions for per-payroll outcomes) and failed (the batch crashed at the system level; can be retried). This is distinct from the per-payroll status returned inside results[]. A completed batch does not imply every payroll was cancelled.