useCapxulInbox

Query hook for the payment requests issued to an actor — the requests waiting on the actor to pay or decline.

Lists the payment requests other actors have issued to an actor scope — the money the person or org is being asked to pay. Act on items with useCapxulApproveInboxRequest and useCapxulDeclineInboxRequest. Requests the actor has issued itself live on the Payment requests side.

Capability status

The inbox family is graded SDK-ready: the approve / decline primitives are published and tested, but a full invoice product workflow has not proven them end-to-end yet. See Capability status.

Import

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

Usage

"use client";

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

function InboxList() {
  const inbox = useCapxulInbox(capxulAccountScope);

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

  const open = inbox.data.filter((item) => item.status === "open");
  if (open.length === 0) return <p>No requests waiting on you.</p>;

  return (
    <ul>
      {open.map((item) => (
        <li key={item.id}>
          {item.reference}: {item.amount.value} {item.amount.currency}
        </li>
      ))}
    </ul>
  );
}

The same component renders an organization's inbox by swapping the scope:

const inbox = useCapxulInbox(capxulOrgScope(orgId));

Parameters

actor

CapxulActorScope | undefined

The actor scope whose inbox 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 UseCapxulInboxReturn } from "@capxul/sdk-react";
// UseQueryResult<readonly InboxItem[], CapxulError>

data is an array of InboxItem:

Prop

Type

issuer is the typed reference of whoever is asking to be paid. Only status: "open" items are actionable; the other statuses record how a request left the inbox (approved, declined, paid, cancelled, expired).

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

("pending" replaces the actor segment while the scope is undefined.) Invalidated — for the same scope only — by useCapxulApproveInboxRequest, useCapxulDeclineInboxRequest, and useCapxulCancelRequest.

Client method

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

useCapxulInbox

On this page