useCapxulUpdatePayrollRosterLine

Mutation hook that edits an existing payroll roster line — amount, timing, employee ref, or payslip template.

Edits a line on an organization's payroll roster. Pass only the fields that change — everything else on the line stays as it is. The change applies to future runs; payments already created by useCapxulRunPayroll are unaffected. Read the roster with useCapxulPayrollRoster.

Import

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

Usage

"use client";

import { useCapxulUpdatePayrollRosterLine } from "@capxul/sdk-react";
import type { OrgId, PayrollRosterLine } from "@capxul/sdk";

function GiveRaiseButton({ orgId, line }: { orgId: OrgId; line: PayrollRosterLine }) {
  const updateLine = useCapxulUpdatePayrollRosterLine(orgId);

  return (
    <button
      type="button"
      disabled={updateLine.isPending}
      onClick={() =>
        updateLine.mutate({
          rosterLineId: line.id,
          // Reuse the line's currency and precision, change only the value.
          input: { amount: { ...line.amount, value: "1750" } },
        })
      }
    >
      {updateLine.isPending ? "Updating…" : "Update salary"}
    </button>
  );
}

Parameters

orgId

OrgId | undefined

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

The mutation takes a UseCapxulUpdatePayrollRosterLineInput:

Prop

Type

input is a Partial<PayrollRosterAddInput> — any subset of employee, amount, timing, and payslipTemplate. Omitted fields are left unchanged. See useCapxulAddPayrollRosterLine for what each field means.

Return type

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

On success, data is the updated PayrollRosterLine.

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.

Errors

Failures surface as a CapxulError on error / thrown from mutateAsync — for example when orgId is still undefined, when the roster line does not exist in this org, when a new employee ref cannot be validated, or when the mutation fires while <CapxulProvider> is still bootstrapping.

Client method

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

useCapxulUpdatePayrollRosterLine

On this page