Get a payroll cancellation batch

Returns the status and per-payroll results of a payroll cancellation batch.

Poll this endpoint until the batch status reaches a terminal value (completed or failed). Once terminal, the response includes the results array (one entry per authorized payroll, each with its own per-payroll status — success or failed) and the exclusions array (one entry per payroll that could not be processed). A cancel is atomic, so a per-payroll result is only ever success or failed — never partial_success.

Note that the top-level batch status (pending / processing / completed / failed) is the request lifecycle, distinct from the per-payroll status inside results[]. A completed batch does not imply every payroll was cancelled — inspect the array for per-payroll outcomes.

Results are stored in Redis with a limited TTL after completion. If the partner polls after results have expired, this endpoint returns 410 Gone — partners should re-submit a new batch.

📘 System Access Authentication

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

scope: payroll_batches:read

payroll_batch_uuidstring required

The UUID of the payroll cancellation batch returned by POST /v1/payroll_batches.

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.

Response

successful

uuidstring uuid required

The unique identifier of the payroll cancellation batch.

idempotency_keystring uuid required

The idempotency key provided when creating 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.

submitted_atstring date-time required

The timestamp when the batch was submitted.

completed_atstring date-time nullable

The timestamp when the batch processing completed.

submitted_itemsinteger nullable

The number of payrolls submitted in the batch.

processed_itemsinteger

The number of payrolls processed (cancelled or attempted). Only present once the batch reaches a terminal status.

excluded_itemsinteger

The number of payrolls excluded from processing. Only present once the batch reaches a terminal status.

v1

Get a payroll cancellation batch

Path parameters

Headers

Response