useCapxulRemovePayrollRosterLine

Removes a line from an organization's payroll roster. The employee drops out of future runs; payments already created by earlier runs are unaffected. Read the roster with useCapxulPayrollRoster — removed lines no longer appear in it.

Import

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

Usage

"use client";

import { useCapxulRemovePayrollRosterLine } from "@capxul/sdk-react";
import type { OrgId } from "@capxul/sdk";

function RemoveLineButton({ orgId, rosterLineId }: { orgId: OrgId; rosterLineId: string }) {
  const removeLine = useCapxulRemovePayrollRosterLine(orgId);

  return (
    <button
      type="button"
      disabled={removeLine.isPending}
      onClick={() => removeLine.mutate(rosterLineId)}
    >
      {removeLine.isPending ? "Removing…" : "Remove from payroll"}
    </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 input is the roster line id:

Field	Type	Description
(input)	`string`	The `id` of the `PayrollRosterLine` to remove.

Return type

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

On success, data is the removed PayrollRosterLine with status: "ended" — useful for an undo-style confirmation UI.

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. Removing a line 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 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.remove(rosterLineId) — the entity-scoped org bundle on the core SDK.

useCapxulRemovePayrollRosterLine

On this page