useCapxulRequest

Query hook for one payment request an actor has issued, by request id — null when it does not exist.

Reads a single issued payment request for an actor scope. Use it for a request detail view after listing receivables with useCapxulRequests.

Import

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

Usage

"use client";

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

function RequestDetail({ requestId }: { requestId: string }) {
  const request = useCapxulRequest(capxulAccountScope, requestId);

  if (request.isLoading) return <p>Loading request…</p>;
  if (request.error) return <p>{request.error.message}</p>;
  if (request.data === null) return <p>Request not found.</p>;

  const { reference, amount, status, expiresAt } = request.data;
  return (
    <div>
      <h2>{reference}</h2>
      <p>
        {amount.value} {amount.currency} — {status}
      </p>
      {expiresAt !== null ? (
        <p>Expires {new Date(expiresAt).toLocaleDateString()}</p>
      ) : null}
    </div>
  );
}

For an organization's request, scope with capxulOrgScope(orgId) instead.

Parameters

actor

CapxulActorScope | undefined

The actor scope that issued the request. The query stays disabled while the scope is undefined.

requestId

string | undefined

The request id, as returned by useCapxulRequests or useCapxulIssueRequest. The query stays disabled while requestId is undefined, so route params can be passed directly.

options

{ enabled?: boolean } | undefined

Set enabled: false to hold the query even when scope and id are ready.

Return type

import { type UseCapxulRequestReturn } from "@capxul/sdk-react";
// UseQueryResult<ActorRequest | null, CapxulError>

data is the ActorRequest, or null when no request with that id exists for the actor:

Prop

Type

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

("pending" fills the actor and/or requestId segment while either is undefined.) Invalidated alongside the requests list whenever a requests/inbox mutation for the same scope names this request id — for example cancelling it, or the payer approving or declining it from their inbox rendered in the same session.

Client method

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

useCapxulRequest

On this page