useCapxulIssueRequest

Mutation hook that issues a payment request from an actor to a typed payer reference.

Issues a payment request from an actor scope to a payer — the receivable side of "send an invoice". The request appears in the actor's useCapxulRequests list and lands in the payer's Inbox, where they approve or decline it.

Import

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

Usage

"use client";

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

function IssueInvoiceButton({ payerEmail }: { payerEmail: string }) {
  const orgs = useCapxulOrgs();
  const orgId = orgs.data?.[0]?.orgId;
  const issueRequest = useCapxulIssueRequest(capxulOrgScope(orgId));

  return (
    <button
      type="button"
      disabled={orgId === undefined || issueRequest.isPending}
      onClick={() =>
        issueRequest.mutate({
          payer: { kind: "email", email: payerEmail },
          amount: { currency: "USD", value: "1250.00", decimals: 2 },
          reference: "INV-2026-041",
          memo: "April retainer",
        })
      }
    >
      {issueRequest.isPending ? "Sending…" : "Send payment request"}
    </button>
  );
}

To request money as yourself rather than as an org, call the hook with capxulAccountScope (or no argument — that is the default).

Parameters

actor

CapxulActorScope | undefined — defaults to capxulAccountScope

Which actor issues the request. An explicit undefined also falls back to the personal scope, so when scoping to an org keep the control disabled until the org id has loaded (as in the example above). See Actor scopes.

Mutation input

The mutation takes an ActorRequestIssueInput:

Prop

Type

payer must be a typed reference — a handle, email, org handle, payee id, or Capxul user id; bare EVM addresses are rejected by design. amount is a decimal money value (currency, string value, decimals). reference is the human-readable identifier shown on both sides (for example an invoice number). expiresAt is an optional expiry timestamp in epoch milliseconds.

Return type

import { type UseCapxulIssueRequestReturn } from "@capxul/sdk-react";
// UseMutationResult<ActorRequest, CapxulError, ActorRequestIssueInput>

On success, data is the created ActorRequest with its current status.

The hook returns TanStack Query's UseMutationResult. The most-used fields:

Field	Description
`mutate`	Fire the mutation (fire-and-forget; pair with `onSuccess`/`onError` callbacks).
`mutateAsync`	Fire the mutation and get a `Promise` of the result. Rejects with a `CapxulError` on failure.
`data`	The mutation result (typed per hook, shown above). `undefined` until the first success.
`error`	A `CapxulError` when the last attempt failed, otherwise `null`.
`isPending`	`true` while the mutation is in flight. Use it to disable submit buttons.
`reset`	Clear the mutation state (`data`, `error`) back to idle.

Mutations do not retry by default. The full field list is in the TanStack Query useMutation reference; see also the TanStack Query integration guide.

Cache behavior

On success this mutation invalidates, for the acting scope only: the requests list, the new request's detail query, the address book (issuing a request creates or refreshes the payer's relationship entry), and both insights queries (summary and history). The acting scope's own inbox is untouched — the request lands in the payer's inbox, not the issuer's.

Errors

Failures surface as a CapxulError on error / thrown from mutateAsync — for example when payer is not a valid typed reference.

Client method

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

useCapxulIssueRequest

On this page