useCapxulAddPayrollRosterLine

Adds a line to an organization's payroll roster: who gets paid, how much, and with what timing. Adding a line stores the standing instruction — no money moves until useCapxulRunPayroll executes a run. Read the roster with useCapxulPayrollRoster.

Import

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

Usage

"use client";

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

function AddEmployeeButton() {
  const orgs = useCapxulOrgs();
  const org = orgs.data?.[0];
  const addLine = useCapxulAddPayrollRosterLine(org?.id);

  if (org === undefined) return null;

  return (
    <button
      type="button"
      disabled={addLine.isPending}
      onClick={() =>
        addLine.mutate({
          employee: { kind: "email", email: "sam@example.com" },
          // Reuse the treasury's currency and precision for the Money amount.
          amount: { ...org.treasury.balance, value: "1500" },
          timing: { kind: "instant" },
        })
      }
    >
      {addLine.isPending ? "Adding…" : "Add Sam to payroll"}
    </button>
  );
}

Parameters

orgId

OrgId | undefined

The organization whose roster the line is added to. Unlike a query, a mutation cannot be disabled — firing it while orgId is still undefined rejects with a CapxulError.

The mutation takes a PayrollRosterAddInput:

Prop

Type

employee is a validated recipient Ref — one of { kind: "handle" }, { kind: "email" }, { kind: "orgHandle" }, { kind: "capxulUserId" }, or { kind: "payeeId" } — never a raw address. timing is a PaymentTiming ({ kind: "instant" }, { kind: "scheduled", at }, or a stream clause). payslipTemplate optionally attaches either a simple { title, memo? } template or a full payment document envelope used for the payslip on each run.

Return type

import { type UseCapxulAddPayrollRosterLineReturn } from "@capxul/sdk-react";
// UseMutationResult<PayrollRosterLine, CapxulError, PayrollRosterAddInput>

On success, data is the created PayrollRosterLine (with its id and status: "active").

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

Field	Description
`mutate`	Fire the mutation (fire-and-forget; pair with `onSuccess`/`onError` callbacks).
`mutateAsync`	Fire the mutation and get a `Promise` of the result. Rejects with a `CapxulError` on failure.
`data`	The mutation result (typed per hook, shown above). `undefined` until the first success.
`error`	A `CapxulError` when the last attempt failed, otherwise `null`.
`isPending`	`true` while the mutation is in flight. Use it to disable submit buttons.
`reset`	Clear the mutation state (`data`, `error`) back to idle.

Mutations do not retry by default. The full field list is in the TanStack Query useMutation reference; see also the TanStack Query integration guide.

Cache behavior

On success this mutation invalidates the org's roster (["capxul", "org", orgId, "payroll", "roster"]) and the org's insights summary and history. Editing the roster moves no money, so balance and payments caches are untouched — those are invalidated by useCapxulRunPayroll.

Errors

Failures surface as a CapxulError on error / thrown from mutateAsync — for example when orgId is still undefined, when the employee ref cannot be validated, when the signed-in member lacks spend authority in the org, or when the mutation fires while <CapxulProvider> is still bootstrapping.

Client method

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

useCapxulAddPayrollRosterLine

On this page