useCapxulRemoveDestination

Mutation hook for retiring a saved destination by id so it no longer appears in lists or accepts payouts.

Retires a saved destination by id. A removed destination stops appearing in useCapxulDestinations results and can no longer be paid out to with useCapxulPayout.

Import

import { useCapxulRemoveDestination } from "@capxul/sdk-react";

Usage

"use client";

import { useCapxulRemoveDestination } from "@capxul/sdk-react";

function RemoveDestinationButton({ destinationId }: { destinationId: string }) {
  const removeDestination = useCapxulRemoveDestination();

  return (
    <button
      disabled={removeDestination.isPending}
      onClick={() => removeDestination.mutate({ destinationId })}
    >
      {removeDestination.isPending ? "Removing…" : "Remove"}
    </button>
  );
}

Parameters

The hook itself takes no parameters. The mutation takes a DestinationRemoveInput:

Prop

Type

destinationId must name a destination belonging to the acting entity — otherwise the mutation fails with INVALID_INPUT ("destination not found"). actor scopes the removal to the personal account (default) or an organization; org actors need spend authority in that org. Removing an already-removed destination succeeds without changing anything.

Return type

import { type UseCapxulRemoveDestinationReturn } from "@capxul/sdk-react";
// UseMutationResult<{ readonly id: string }, CapxulError, DestinationRemoveInput>

On success, data is { id } — the id of the removed destination.

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 every destinations query (the ["capxul", "destinations"] prefix). It does not touch the address book — the counterparty entry recorded when the destination was added stays.

Errors

Failures surface as a CapxulError on error / thrown from mutateAsync — INVALID_INPUT when the id does not name a destination of the acting entity.

Client method

This hook wraps client.destinations.remove(input) on the core SDK.