PayrollExecutionFlow

Guided flow to configure, review, and submit a single payroll.

Remarks

This is the inner flow that powers the back half of Payroll.PayrollFlow, and it is also reused by the off-cycle, dismissal, and transition flows after they have created their respective payrolls. Render it directly when you have built your own payroll-creation step and want to hand the user off to the standard execution experience without re-implementing it. The flow ships with breadcrumb navigation and the standard wire-confirmation UX.

Example

App.tsx

import { Payroll, type EventType } from '@gusto/embedded-react-sdk'

function MyApp() {
  return (
    <Payroll.PayrollExecutionFlow
      companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365"
      payrollId="0987fcea-7b59-4907-a301-f232b5aff508"
      onEvent={(eventType: EventType) => {
        if (eventType === 'runPayroll/submitted') {
          // Payroll submitted — navigate to your next screen
        }
      }}
    />
  )
}

PayrollExecutionFlowProps

Props for PayrollExecutionFlow.

Property	Type	Description
companyId	string	The associated company identifier.
onEvent	OnEventType<EventType, unknown>	Event handler that receives the RUN_PAYROLL_* events emitted during the flow.
payrollId	string	The identifier of the payroll to execute. The payroll must already exist (e.g. created by a prior creation step or by the standard PayrollFlow selection).
ConfirmWireDetailsComponent?	ConfirmWireDetailsComponentType	Optional custom component to replace the default wire details confirmation UI.
initialPayPeriod?	PayrollPayPeriodType	Optional pay period metadata used to seed breadcrumb labels and date context.
initialState?	PayrollExecutionInitialState	Where the flow starts. Use 'overview' when you want to drop the user directly on the review screen (e.g. resuming an already-calculated payroll). Defaults to 'configuration'.
isDismissalPayroll?	boolean	When true, surfaces dismissal-specific copy and breadcrumbs (used by Payroll.DismissalFlow). Defaults to false.
withReimbursements?	boolean	Optional flag to show or hide reimbursement fields throughout the flow. Defaults to true.

Events

Event	Description	Data
runPayroll/edit	Fired when user chooses to edit payroll	—
runPayroll/calculated	Fired when payroll calculation completes	{ payrollUuid, payPeriod?, alert? }
runPayroll/employee/edit	Fired when user opens an employee row to edit	{ employeeId, firstName, lastName }
runPayroll/employee/saved	Fired when employee edits are saved	—
runPayroll/employee/cancelled	Fired when employee edits are cancelled	—
runPayroll/submitting	Fired when payroll submission begins	—
runPayroll/submitted	Fired when payroll is successfully submitted	Response from the Submit payroll endpoint
runPayroll/processed	Fired when payroll processing is completed	—
runPayroll/processingFailed	Fired when payroll processing fails	Error details
runPayroll/cancelled	Fired when a payroll is cancelled	Response from the Cancel payroll endpoint
runPayroll/receipt/get	Fired when user requests payroll receipt	{ payrollId }
runPayroll/receipt/viewed	Fired when the receipt screen is viewed	—
runPayroll/pdfPaystub/viewed	Fired when user views employee paystub PDF	{ employeeId }
runPayroll/blockers/viewAll	Fired when user opens the full blockers list	—
payroll/saveAndExit	Fired when user uses the save-and-exit CTA	—

Sub-components

Component	Description
PayrollConfiguration	Handles the configuration phase of payroll processing, allowing users to review and modify employee compensation before calculating the payroll.
PayrollOverview	Final review screen for a calculated payroll before submission, with submit, cancel, and edit controls. After submission, tracks processing status and surfaces the receipt and per-employee paystub downloads once complete.
PayrollEditEmployee	Editor for an individual employee's compensation within a payroll run.
PayrollReceipts	Displays a detailed receipt for a completed payroll, including the debited total, per-category breakdown, tax breakdown, and a per-employee summary of payment method, garnishments, reimbursements, taxes, and net pay.
PayrollBlockerList	Displays the list of blockers preventing payroll from being processed for a company.

Step flow

The execution flow centers on the configuration step (PayrollConfiguration) as a hub: from there you can edit an employee, view all blockers, or calculate the payroll to reach the overview, and each of those returns to configuration. The one spoke-to-spoke move is overview → receipts (runPayroll/receipt/get); receipts then also returns to the hub. The entry point depends on the initialState prop: 'configuration' (the default) or 'overview' (drop directly onto the review screen for an already-calculated payroll).

Edge labels are dropped for legibility (see the events table above); each spoke's events are: edit an employee (runPayroll/employee/edit, returning on runPayroll/employee/saved / runPayroll/employee/cancelled), view all blockers (runPayroll/blockers/viewAll), and calculate to reach the overview (runPayroll/calculated, returning on runPayroll/edit before submission). Overview reaches receipts on runPayroll/receipt/get.

runPayroll/submitting flips a one-way latch: runPayroll/edit returns to configuration only before submission has started, after which the configuration step is hidden and the flow stays on the overview through submission and processing.

The breadcrumb header (breadcrumb/navigate) returns to an earlier step, and Save & exit (payroll/saveAndExit, the dashed edges to the exit node) is available from every step except employee editing. Neither that event nor the status events emitted during the run (runPayroll/submitted, runPayroll/processed, runPayroll/processingFailed, runPayroll/cancelled) is handled internally — each surfaces on onEvent, with payroll/saveAndExit signalling that the flow has been exited.

Endpoints

Method	Path
GET	/v1/companies/:companyId/payrolls
GET	/v1/companies/:companyId/payrolls/:payrollId