useCapxulRequests

Query hook for the payment requests an actor has issued — its receivables, with status and expiry.

Lists the payment requests an actor scope has issued — the money it is waiting to receive. Read one request with useCapxulRequest; create, cancel, and reconcile with useCapxulIssueRequest, useCapxulCancelRequest, and useCapxulReconcileRequests. Requests issued to the actor live on the Inbox side.

Capability status

The payment-requests family is graded SDK-ready: the create / send / cancel / reconcile 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, useCapxulRequests } from "@capxul/sdk-react";

Usage

"use client";

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

function ReceivablesList() {
  const requests = useCapxulRequests(capxulAccountScope);

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

  return (
    <ul>
      {requests.data.map((request) => (
        <li key={request.id}>
          {request.reference}: {request.amount.value}{" "}
          {request.amount.currency} — {request.status}
        </li>
      ))}
    </ul>
  );
}

The same component lists an organization's receivables by swapping the scope:

const requests = useCapxulRequests(capxulOrgScope(orgId));

Parameters

actor

CapxulActorScope | undefined

The actor scope whose issued requests 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 UseCapxulRequestsReturn } from "@capxul/sdk-react";
// UseQueryResult<readonly ActorRequest[], CapxulError>

data is an array of ActorRequest:

Prop

Type

status walks draft → sent → viewed → pending_settlement → paid, or ends in declined, cancelled, or expired. amount is a decimal money value (currency, string value, decimals) — never a raw token integer.

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

("pending" replaces the actor segment while the scope is undefined.) Invalidated — for the same scope only — by every mutation in this family and by the inbox mutations (useCapxulApproveInboxRequest, useCapxulDeclineInboxRequest).

Client method

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

useCapxulRequests

On this page