GuidesAPI ReferenceChangelogAPI StatusAPI PolicyGusto Security
API Reference

Create a payroll cancellation batch

post
https://api.gusto-demo.com/v1/payroll_batches

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

Body Params
uuid
required

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

string
enum
required

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

Allowed:
batch
array of objects
required
length between 1 and 100

Array of payrolls to cancel. Maximum 100 payrolls per request.

batch*
string
enum
required

The type of entity to act on.

Allowed:
uuid
required

The UUID of the payroll to cancel. Payrolls the partner is not authorized to access, or that do not exist, appear in the response's exclusions array.

uuid
required

The UUID of the company that owns the payroll. The partner must be mapped to this company.

Headers
string
enum
Defaults to 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.

Allowed:
Responses

Updated 8 days ago

Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 8 days ago