useCapxulReconcileRequests
Mutation hook that runs a reconciliation pass over an actor's issued payment requests and returns paid / exception entries.
Runs a reconciliation pass over the payment requests an
actor scope has issued: which receivables have
settled, and which need attention. It is exposed as a mutation because you
trigger a pass explicitly — it reads settlement state rather than moving
money. List the underlying requests with
useCapxulRequests.
Import
import { capxulAccountScope, useCapxulReconcileRequests } from "@capxul/sdk-react";Usage
"use client";
import {
capxulAccountScope,
useCapxulReconcileRequests,
} from "@capxul/sdk-react";
function ReconcilePanel() {
const reconcile = useCapxulReconcileRequests(capxulAccountScope);
return (
<div>
<button
type="button"
disabled={reconcile.isPending}
onClick={() => reconcile.mutate()}
>
{reconcile.isPending ? "Reconciling…" : "Reconcile requests"}
</button>
{reconcile.data ? (
<ul>
{reconcile.data.map((entry) => (
<li key={entry.paymentRequestId}>
{entry.reference}: {entry.status}
</li>
))}
</ul>
) : null}
{reconcile.error ? <p>{reconcile.error.message}</p> : null}
</div>
);
}To reconcile an organization's receivables, scope the hook with
capxulOrgScope(orgId) instead.
Parameters
actor
CapxulActorScope | undefined — defaults to capxulAccountScope
Which actor's issued requests to reconcile. An explicit undefined also
falls back to the personal scope — gate org-scoped controls on the org id
being loaded. See Actor scopes.
Mutation input
None — call reconcile.mutate() / reconcile.mutateAsync() with no
argument.
Return type
import { type UseCapxulReconcileRequestsReturn } from "@capxul/sdk-react";
// UseMutationResult<readonly ReconciliationEntry[], CapxulError, void>On success, data is an array of ReconciliationEntry — one row per
reconciled receivable:
Prop
Type
status is "paid" (settled, with settledPaymentId and, once collected, a
receiptDocumentHash) or "exception" (needs attention).
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, for the acting scope only: the requests
list, the address book, and both insights queries — the reconciliation
counters on useCapxulInsightsSummary
refetch after a pass.
Errors
Failures surface as a CapxulError on
error / thrown from mutateAsync.
Client method
This hook wraps client.account.requests.reconcile() for the
personal scope, or client.org(orgId).requests.reconcile()
for an org scope.