Start a payroll cycle for a client

Who does this: Payroll Executive · Payroll Lead · Platform Admin When: At the start of the client's payroll month, or to recover a cycle the scheduler missed Result: A new cycle row, status REQUESTED, with the monthly request email sent to every contact who can submit.

Most cycles start themselves — the platform fires automatically at the client's local 09:00 on the day-of-month set on the client record. You only need this runbook when:

• The schedule day is in the future and you want to start now (e.g. an early month-end close)
• The scheduler missed the slot because the client was misconfigured at the time
• You're processing a one-off correction cycle for a specific month
• You're doing the client's first-ever cycle and want to step them through it

If the client's cycle already exists for the month you want, don't start another — the unique constraint on (client, cycle month) will refuse a duplicate. Open the existing one instead.

Before you start

• [ ] The client exists and has at least one active contact who can submit (canSubmit = true).
• [ ] The client has an auth policy configured (typically magic link).
• [ ] The client has document rules for the change types they expect (joiner / change / leaver bundles).
• [ ] The client has an active export template of kind UPLOAD.
• [ ] You know which cycle month you're processing, in YYYY-MM format.

If any of these are missing, the cycle initiator will refuse with a specific error. Open the client record, fill the gap, then come back here.

TIP

The Setup health panel on the client detail page goes green only when all four are configured. If anything is red there, fix it first.

Steps

1. Open Clients in the staff dashboard sidebar.
2. Find your client. Use the search box if your portfolio is long; the list is filterable by name, code, and product.
3. Click into the client to open the client detail page.
4. On the top right, click Start cycle.
5. In the dialog:
   • Cycle month: the month you're processing (e.g. for May 2026 payroll, enter 2026-05).
   • Reason (optional): a short note for the audit log — useful when you're starting a cycle off-schedule. Examples: "Early start — client cutoff moved up by 3 days" or "Recovery — scheduler missed because contact was inactive yesterday."
6. Click Start cycle.

The dialog closes with a confirmation toast. The cycle list now shows a new row for the month, status Requested.

How to know it worked

Three places to verify, in order of confidence:

1. The cycle status badge flips from no row → REQUESTED immediately.
2. The Outbox (Outbox in the sidebar) shows one row per submitter contact, kind cycle-request, with Dispatched populated within ~30 seconds of you clicking Start cycle. (Inside the platform, an outbox event is created synchronously when the cycle is initiated; a background dispatcher delivers it to email within ~30 s.)
3. The audit log (cycle detail → Audit tab) shows two events: cycle.initiated and cycle.requested, both attributed to you.

If any one of these doesn't appear within a minute, see Why isn't my cycle showing?.

What the client sees

For every active contact with Can submit intake ticked, the platform sends an email:

• Subject: Payroll data request for {YYYY-MM} — {client legal name}
• From: BreezyCorp <noreply@…> (or whatever your tenant's "from" address is)
• Body: A brief note, then two buttons:
  • Yes, I have changes — opens the intake wizard
  • No changes this month — auto-submits a zero-item intake

The link inside the email expires in 48 hours. After that, the client gets a fresh-token reminder on day 2, day 5, and day 7 if they still haven't acted.

NOTE

Contacts marked Can approve but not Can submit are not invited to the cycle initiation email. They'll receive a separate approval email later in the cycle, after the export is generated.

Common situations

If you see…	It means…	What to do
Start cycle button is disabled	Client has missing config (red on the Setup health panel)	Open client detail, fix what's red
Dialog rejects with "Cycle for {month} already exists"	A cycle row exists for that client + month	Open the existing cycle from the cycle list
Toast: "No active submitter contact"	Every contact with canSubmit=true has been deactivated, or none exists	Open client → Contacts and add or reactivate one
Toast: "No active UPLOAD template"	Client has never uploaded an Infotech import template, or the active one has been deactivated	Open client → Templates and activate one
Cycle is created but Outbox shows no rows after a minute	Outbox dispatcher is stuck	See Outbox stuck runbook

Related runbooks

• Verify an email was sent
• Why isn't my cycle showing?
• When does each scheduled action fire? — for understanding the auto-initiation schedule
• Validation rules reference — the eight blocking rules a submission has to pass
• Payroll cycle status machine — the 16-state lifecycle this cycle now lives in