Create a new payroll client

Who does this: Platform Admin · Payroll Lead When: A new client has signed up for payroll, or you're moving an existing client off another system onto BreezyCorp Result: A client record exists in the staff dashboard, ready to be configured with contacts, an export template, and document rules before the first cycle can run.

This is the very first step when onboarding any payroll client. After creating the shell record, you'll add at least one contact, upload an Infotech import template, and configure document rules — only then can a cycle be started for that client. This runbook only covers creating the shell.

If you're onboarding a client that also uses BreezyCorp for bookkeeping, create the shell here with payroll enabled and toggle bookkeeping on after — products are independent and configured separately.

Before you start

• [ ] You have the Platform Admin role, or Payroll Lead role with MANAGE_CLIENTS permission. (Payroll Executives cannot create clients — see the RBAC matrix.)
• [ ] You have the client's legal name as it should appear on every email and document.
• [ ] You've agreed an internal client code with your team (a short uppercase identifier — e.g. WTAN, PNCL, MASN).
• [ ] You know the client's timezone (for scheduling automated cycle initiation) and the schedule day of the month their cycle should fire.

TIP

Pick the client code carefully — it appears in URLs, audit logs, and exported workbook filenames. Renaming it later is supported but disruptive. Two-to-six uppercase letters is the convention.

Steps

1. Open Clients under Administration in the staff dashboard sidebar.
2. Top-right of the clients list, click New client.
3. Fill the Identity card:
   • Client code — your short uppercase identifier (e.g. WTAN for Walker & Tan Associates Pte Ltd).
   • Legal name — the full registered entity name. This is what appears on every client-facing email subject and the approval report.
   • Timezone — defaults to Asia/Singapore. Change this only if the client genuinely operates in another zone; cycles initiate at the client's local 09:00.
   • Default schedule day — the day of the month the monthly cycle fires (1–31). In the onboarding wizard this is Day the month opens on the Configuration step, a small calendar of days 1–31 (no month or year) defaulting to the 18th (since 29 Oct 2026; the 20th before). Beside it, Inputs due by (a calendar of the 1st to the 28th, nothing pre-filled) is chosen in the wizard too: the person onboarding decides the gap. Under both, the wizard says how many days the client has ("The client is asked on the 18th and has 5 days, until the 23rd"), and the due day must come after the opening day: earlier days are greyed out in its calendar, and a pair in the wrong order (or an opening day of the 28th or later, which leaves no due day) stops the step and is refused by the server too. The info button beside Payroll settings says, for the days chosen, what happens each month: the request at 09:00 on the opening day, the 3/5/7-day reminders with their dates and which fall after the due day, "as soon as you can" after it, changes on the link marked after the cutoff, and the follow-up task for the payroll executive after day 7. Both are saved on the company and changed later on Settings › Payroll. Under them, Remind the client picks one to three reminders counted back from the due day ("2 days before", "1 day before" and "On the due day" to start with), each shown with its date; one that would fall on or before the opening day cannot be chosen. If nothing has come by the day after the due day, the payroll executive gets a task to follow up. Settings › Payroll → Client reminders changes them later, or puts the company back on 3, 5 and 7 days after the request. This is the field payroll.cycle-initiate reads; a client with no saved timezone or schedule day is skipped rather than opened on a guessed date.
4. Click Create client.

You'll be redirected to the client detail page. The Setup health panel at the top will show four red items — that's expected. The next runbooks fix each one.

How to know it worked

• The client appears in the Clients list with the code and legal name you entered.
• The client detail page loads at /dashboard/clients/{id}.
• The Activity log for the client shows a client.created event attributed to you with a timestamp.
• The Setup health panel shows the client cannot start a cycle yet — the red items list contacts, templates, document rules, and (for payroll-only) approver coverage.

NOTE

Creating a client does not send any email. Nothing happens externally until you start the first cycle.

NOTE

Deviation from the SOP, recorded here rather than in the SOP itself. docs/sop/Payroll_Processing.md names the 17th as the standard trigger date and a data-request email carrying an SPWP link as the client's first contact. The platform instead honours the per-client Default schedule day above (default 18th since 29 Oct 2026, editable per client), and tells the client in their Chatwoot conversation — no email and no portal link at this step. See When does each scheduled action fire?.

Common situations

If you see…	It means…	What to do
New client button is missing or greyed out	Your role lacks MANAGE_CLIENTS (you're a Payroll Executive)	Ask a Payroll Lead or Platform Admin to create the shell, then take over configuration
Toast: "Client code already in use"	Another client (active or archived) already has that code	Pick a different code; codes are unique across the firm even after archival
Toast: "Legal name must be unique"	A client with this exact legal name exists already	Confirm whether this is a duplicate onboarding; if it's a genuinely separate entity, append the registration suffix to disambiguate
Timezone field rejects your value	The platform only accepts IANA timezone IDs (e.g. Asia/Singapore, Asia/Kuala_Lumpur)	Use the IANA name, not an abbreviation like SGT
Schedule day is set to 30 or 31	February and the 30-day months are shorter than the day you picked	Nothing to fix — the scheduler clamps to the month's last day (31 → 28 or 29 Feb). Pick 28 or earlier only if you want the same calendar date every month

Next runbooks

After creating the client shell, you'll typically work through these in order:

1. Add or edit client contacts — at minimum one submitter and one approver
2. Upload an Infotech import template (see the Infotech template runbook — coming soon)
3. Configure document rules per change type (coming soon)
4. Start a cycle — first month go-live

Related runbooks

• Add or edit client contacts
• Start a payroll cycle
• RBAC matrix — exactly which actions each role can take
• Payroll cycle status machine — what happens after the first cycle is initiated