Skip to content
StartupBuilderby Startups.Studio
Business
Changelog
Finance

Pay Run

A Pay Run is one pay period’s payroll for a Company: each employee’s gross pay, withholding, deductions and net pay, approved and paid together.

Properties

PropertyTypeRequiredDescription
companyCompanyrequiredThe employer of record for everyone it pays.
periodStartdaterequiredThe first day of the pay period.
periodEnddaterequiredThe last day of the pay period.
payDatedaterequiredThe day net pay reaches each employee’s bank.
kindstringrequiredA regular run on the pay schedule, or an offCycle run for a bonus, a correction or final pay.
humanslist of HumanThe employees it pays.
grossmoneyPay before withholding and deductions, for everyone in the run.
withheldmoneyIncome and payroll taxes withheld from employees’ pay.
deductionsmoneyBenefit and retirement deductions the employees elected.
employerTaxmoneyPayroll taxes the Company owes on top of gross pay.
netmoneyWhat reaches the employees’ banks: gross less withholding and deductions.
statusstringrequiredWhere the Pay Run stands; only an approved run is paid.

Object

JSON
{
  "$id": "https://api.sb/kilnbakery.com/pay-runs/pay_run_1",
  "$type": "PayRun",
  "company": "company_1",
  "periodStart": "2026-10-22",
  "periodEnd": "2026-10-22",
  "payDate": "2026-10-22",
  "kind": "regular",
  "humans": [
    "human_1"
  ],
  "gross": {
    "amount": 9,
    "currency": "USD"
  },
  "withheld": {
    "amount": 9,
    "currency": "USD"
  },
  "deductions": {
    "amount": 9,
    "currency": "USD"
  },
  "employerTax": {
    "amount": 9,
    "currency": "USD"
  },
  "net": {
    "amount": 9,
    "currency": "USD"
  },
  "status": "prepared"
}

Relationships

  • A Pay Run is paid by one Company: a Pay Run is paid by one Company, the employer of record for everyone in it. paidBy, inverse payRuns.
  • A Pay Run pays many Humans: a Pay Run pays the Humans the Company employs; each employee appears in one run per pay period. pays, inverse paidIn.

Lifecycle

Pay Run lifecycle: prepared, approved, paid (ends), voided (ends)prepared → approved: PayRun.approveprepared → voided: PayRun.voidapproved → paid: PayRun.paypreparedapprovedpaidvoided
StateMeaningMoves to
prepared (first)Every amount is computed and the run waits for approval; nothing is booked or paid.approved by PayRun.approve; voided by PayRun.void
approvedThe cost is booked and payment is scheduled to land on the pay date.paid by PayRun.pay
paidNet pay reached each employee, and the payroll provider holds the taxes and deductions to remit.None: it ends here.
voidedThe run was set aside before approval; nothing was booked or paid, and the record stays.None: it ends here.

Verbs

  1. getReturns one Pay Run by id.
    GET /{namespace}/pay-runs/{id}readNo Event
  2. listReturns Pay Runs, newest first, one page at a time.
    GET /{namespace}/pay-runsreadNo Event
  3. approveApprove accepts a prepared Pay Run within the approver’s Mandate, books its cost, and schedules payment to land on the pay date.
    POST /{namespace}/pay-runs/{payRun}/approvedoPayRun.approved
  4. payPay funds an approved Pay Run: net pay to each employee’s bank on the pay date, taxes and deductions to the payroll provider.
    POST /{namespace}/pay-runs/{payRun}/paydoPayRun.paid
  5. preparePrepare computes one pay period’s gross pay, withholding, deductions and employer taxes for each employee, and holds the Pay Run for approval.
    POST /{namespace}/pay-runs/preparedoPayRun.prepared
  6. voidVoid sets aside a prepared Pay Run that is wrong, so a corrected one can be prepared; the record stays.
    POST /{namespace}/pay-runs/{payRun}/voiddoPayRun.voided

A Pay Run is kept forever and never edited: it has no update or delete.

Permissions

Which Access level may call each Verb. One-way Verbs wait their delay window.

Operationowneradminmemberviewer
PayRun.getYesYesYesYes
PayRun.listYesYesYesYes
PayRun.approveYesNoNoNo
PayRun.payYesNoNoNo
PayRun.prepareYesYesYesNo
PayRun.voidYesYesYesNo

Call it

Text
Prepare the latest pay run with a company.

Example

A property-management app with four employees in two states pays on the 15th and the last day of each month. The Payroll Specialist prepares the run for the 1st to the 15th: $18,400 gross, withholding for both states, $14,050 net. It approves within its Limit, and the Treasurer funds it two days before payday.

Order.update

Previous Page

PayRun.approve

Next Page