useCapxulInsightsHistory

Query hook for an actor's payment history — the Payment records behind the insights summary.

Reads the payment history of an actor scope — the Payment records whose aggregates useCapxulInsightsSummary reports.

Import

import { capxulOrgScope, useCapxulInsightsHistory } from "@capxul/sdk-react";

Usage

"use client";

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

function OrgPaymentHistory() {
  const orgs = useCapxulOrgs();
  const history = useCapxulInsightsHistory(
    capxulOrgScope(orgs.data?.[0]?.orgId),
  );

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

  return (
    <ul>
      {history.data.map((payment) => (
        <li key={payment.id}>
          {payment.recipient.label}: {payment.amount.value}{" "}
          {payment.amount.currency} — {payment.status}
        </li>
      ))}
    </ul>
  );
}

For the signed-in user's own history, scope with capxulAccountScope instead.

Parameters

actor

CapxulActorScope | undefined

The actor scope whose history to read. The query stays disabled while the scope is undefined, so an org id from useCapxulOrgs can be passed directly (as above).

options

{ enabled?: boolean } | undefined

Set enabled: false to hold the query even when the scope is ready.

Return type

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

data is an array of Payment records: each has an id, status, amount (a decimal money value), paymentType, a labeled recipient, a timing clause (instant, scheduled, or stream), attached documents, and createdAt / updatedAt timestamps.

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", "actor", "account", "insights", "history"]      // personal scope
["capxul", "actor", "org", orgId, "insights", "history"]   // org scope

("pending" replaces the actor segment while the scope is undefined.) Invalidated — for the same scope only — by every payment-requests and inbox mutation, and by money mutations (useCapxulPay, payouts, withdrawals, payroll runs) through the shared money-state invalidation.

Client method

This hook wraps client.account.insights.history() for the personal scope, or client.org(orgId).insights.history() for an org scope.

useCapxulInsightsHistory

On this page