Skip to content

by Startups.Studio

Finance Pay Run

PayRun.prepare

POST /{namespace}/pay-runs/prepare

Prepare computes one pay period’s gross pay, withholding, deductions and employer taxes for each employee, and holds the Pay Run for approval.

Noun: Pay Run
Mode: do
Event: PayRun.prepared

You, to your agent

Prepare the latest pay run with a company.

curl -X POST https://api.sb/tutorloop.com/pay-runs/prepare \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company":"company_1","periodStart":"2026-10-22","periodEnd":"2026-10-22","payDate":"2026-10-22"}'

import { $ } from 'startup-builder'

const payRun = await $.PayRun.prepare({ company: 'company_1', periodStart: '2026-10-22', periodEnd: '2026-10-22', payDate: '2026-10-22' })

npx startup-builder do PayRun.prepare --json '{"company":"company_1","periodStart":"2026-10-22","periodEnd":"2026-10-22","payDate":"2026-10-22"}'

{
  "name": "do",
  "arguments": {
    "code": "return await $.PayRun.prepare({ company: 'company_1', periodStart: '2026-10-22', periodEnd: '2026-10-22', payDate: '2026-10-22' })"
  }
}

Inputs

Input	Type	Required	Description
`company`	Company	required	The employer Company.
`periodStart`	`date`	required	The first day of the pay period.
`periodEnd`	`date`	required	The last day of the pay period.
`payDate`	`date`	required	The day net pay should land.
`kind`	`string`		Defaults to `regular`; `offCycle` pays outside the schedule.
`humans`	list of Human		Only these employees. Defaults to every employee of the Company.

Outputs

Output	Type	Required	Description
`payRun`	Pay Run	required	The prepared Pay Run, with every amount per employee.

Effects

Emits PayRun.prepared.
Performed by the Payroll Specialist.
Two-way: it runs at once, in the try, send and do modes.
Reads each employee’s pay rate from their employment Agreement and withholds for the state where they work.
Adds the Benefits deductions each employee elected.
Opens a Task for the Payroll Specialist when a rate, a tax setup or a bank account is missing.

Refuses when

Check	Error	Fix	Then call
The key is valid, but its scopes do not allow this operation.	`forbidden`	Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them.	PayRun.prepare

When it waits

Gate	Default
Decision class	Low: two-way, nothing at stake
Delay window	None: it runs once review passes.
Limit	The call Limit of the Permission it runs under.
Over the Limit	It waits `pending` for an Approval from the Founder. Approved, it runs; refused, it ends `refused` with `limit-exceeded`; unanswered by its deadline, it ends `canceled`.

PayRun.pay

Previous Page

PayRun.void

Next Page