---
title: "Create a payroll cancellation batch"
method: POST
path: "/v1/payroll_batches"
tags: ["Payroll Cancellations"]
---

# Create a payroll cancellation batch

`POST /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](https://docs.gusto.com/embedded-payroll/docs/system-access)

scope: `payroll_batches:write`

## Headers

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

## Request body

- object
  - `idempotency_key` string, 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.
  - `batch` object[], required — Array of payrolls to cancel. Maximum 100 payrolls per request.
    - `entity_type` 'payroll', required — The type of entity to act on.
    - `uuid` string, 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.
    - `company_uuid` string, uuid, required — The UUID of the company that owns the payroll. The partner must be mapped to this company.

## Response `201`

created

- PayrollBatch — A payroll cancellation batch request.
  - `uuid` string, uuid, required — The unique identifier of the payroll cancellation batch.
  - `idempotency_key` string, 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.

## Other responses

- `409` — conflict - idempotency key already used by this partner
- `422` — unprocessable entity - validation errors

---

[API](https://skmtc.net/gusto/apis/gusto-api.md) · [All operations](https://skmtc.net/gusto/apis/gusto-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gusto/gusto-api/revisions/826dfa57fb3b/schema)