Request a payslip bundle
Resolve all payruns for the given pay groups and pay-date window, validate them, and enqueue an async ZIP bundle job. Returns 202 immediately; poll GET with the bundle_id until status is READY.
The window matches each payrun’s payment date: a supplementary payrun’s own pay date, a main payrun’s deposit date. A supplementary run paying outside its pay calendar’s period therefore belongs to the window that paid it. Cancelled payruns are ignored, and an approved payrun with no payslips contributes nothing rather than failing the request; if no matched payrun has any payslips the request is refused as if the window matched nothing.
Bundles cover approved payruns (APPROVED or PAID) only, whose payslip PDFs are already stored. A matched DRAFT payrun blocks the request (409); download a draft payslip one employee at a time instead. A PROCESSING payrun blocks the request (409), as does an approved payrun whose stored PDFs are not all ready.
A bundle is identified by its window and its pay-group selection, so the same window bundled for different pay groups gives separate bundles that coexist. Re-requesting one selection returns the existing bundle, or replaces it when the payruns it covers have changed.
For a paginated JSON view of individual payslips, use GET /payrolls/{payroll_status_id}/payslips (the Link: rel=bundles response header on that endpoint points back here).
ZIP entry names use the employee’s external_ref when set; employees with no external_ref are identified by their UUID, which can be resolved via GET /employees. An entry from a supplementary payrun is suffixed -SUPP, and where an employee is paid by more than one payrun on one date — a main and a supplementary run, or two runs after a pay-group move — the later entries are numbered, so every file keeps the employee’s identifier.
Body
POST body for requesting a payslip bundle.
Response
Successful Response
POST 202 and GET 200 response.
download_url is a presigned GCS link; it is None until status reaches
READY. The client polls GET with the bundle_id it received from POST.