useCapxulInsightsSummary

Query hook for an actor's money-flow summary — pending requests, paid this month, drafts, and reconciliation counters.

Reads the money-flow summary of an actor scope: what is pending, what got paid this month, open drafts, and reconciliation counters. It is the dashboard-tile companion to useCapxulInsightsHistory, which returns the underlying payment records.

Capability status

The insights family is graded SDK-ready: published and tested, but not yet proven end-to-end by a product surface. See Capability status.

Import

import { capxulAccountScope, useCapxulInsightsSummary } from "@capxul/sdk-react";

Usage

"use client";

import {
  capxulAccountScope,
  useCapxulInsightsSummary,
} from "@capxul/sdk-react";

function InsightsTiles() {
  const insights = useCapxulInsightsSummary(capxulAccountScope);

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

  const { pending, paidThisMonth, reconciliation } = insights.data;
  return (
    <dl>
      <dt>Awaiting payment</dt>
      <dd>
        {pending.count} requests · {pending.total.value}{" "}
        {pending.total.currency}
      </dd>
      <dt>Paid this month</dt>
      <dd>
        {paidThisMonth.count} payments · {paidThisMonth.total.value}{" "}
        {paidThisMonth.total.currency}
      </dd>
      <dt>Reconciliation</dt>
      <dd>
        {reconciliation.open} open · {reconciliation.exceptions} exceptions
      </dd>
    </dl>
  );
}

The same tiles render for an organization by swapping the scope:

const insights = useCapxulInsightsSummary(capxulOrgScope(orgId));

Parameters

actor

CapxulActorScope | undefined

The actor scope whose summary to read. The query stays disabled while the scope is undefined.

options

{ enabled?: boolean } | undefined

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

Return type

import { type UseCapxulInsightsSummaryReturn } from "@capxul/sdk-react";
// UseQueryResult<InsightsSummary, CapxulError>

data is an InsightsSummary:

Prop

Type

The total fields are decimal money values (currency, string value, decimals). The reconciliation counters correspond to what useCapxulReconcileRequests reports per receivable.

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", "summary"]      // personal scope
["capxul", "actor", "org", orgId, "insights", "summary"]   // 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.summary() for the personal scope, or client.org(orgId).insights.summary() for an org scope.

useCapxulInsightsSummary

On this page