useCapxulPayrollRoster

Query hook for an organization's payroll roster — the employee lines a payroll run pays.

Reads an organization's payroll roster: the standing list of employees, amounts, and timing that a payroll run pays. Payroll is an organization paying many people at once — each run settles as real Payments. Manage lines with useCapxulAddPayrollRosterLine, useCapxulUpdatePayrollRosterLine, and useCapxulRemovePayrollRosterLine; execute a run with useCapxulRunPayroll.

SDK-ready

Payroll is graded SDK-ready: the roster and run primitives are published and tested, but the scheduling / streaming payroll product experience is not SDK-complete yet. See Capability status.

Import

import { useCapxulPayrollRoster } from "@capxul/sdk-react";

Usage

"use client";

import { useCapxulOrgs, useCapxulPayrollRoster } from "@capxul/sdk-react";

function RosterList() {
  const orgs = useCapxulOrgs();
  const orgId = orgs.data?.[0]?.id;
  const roster = useCapxulPayrollRoster(orgId);

  if (roster.isLoading) return <p>Loading roster…</p>;
  if (roster.error) return <p>{roster.error.message}</p>;

  return (
    <ul>
      {roster.data.map((line) => (
        <li key={line.id}>
          {line.amount.value} {line.amount.currency} — {line.status}
        </li>
      ))}
    </ul>
  );
}

Parameters

orgId

OrgId | undefined

The organization whose roster to read. The query stays disabled while orgId is undefined, so you can pass the result of another query directly — no manual gating needed.

options

{ enabled?: boolean } | undefined

Pass enabled: false to pause the query even when orgId is set.

Return type

import { type UseCapxulPayrollRosterReturn } from "@capxul/sdk-react";
// UseQueryResult<readonly PayrollRosterLine[], CapxulError>

data is an array of PayrollRosterLine:

Prop

Type

employee is a validated recipient Ref (handle, email, orgHandle, capxulUserId, or payeeId — never a raw address). Removed lines drop out of this list; a run pays only lines whose status is "active".

The hook returns TanStack Query's UseQueryResult. The most-used fields:

Field	Description
`data`	The query data (typed per hook, shown above). `undefined` until the first success.
`error`	A `CapxulError` when the last fetch failed, otherwise `null`.
`status`	`'pending'` \| `'error'` \| `'success'`.
`isLoading`	`true` during the first fetch (no data yet).
`isFetching`	`true` whenever a fetch is in flight, including background refetches.
`refetch`	Manually refetch the query.

Capxul query hooks stay pending until the provider finishes bootstrapping — you do not need to gate them on useCapxul() yourself. The full field list is in the TanStack Query useQuery reference; see also the TanStack Query integration guide.

Query key

["capxul", "org", orgId, "payroll", "roster"] — org-scoped, and invalidated automatically by the four payroll mutations for that org (add / update / remove roster line, and useCapxulRunPayroll) without touching other orgs.

Client method

This hook wraps client.org(orgId).payroll.roster.list() — the entity-scoped org bundle on the core SDK.

useCapxulPayrollRoster

On this page