Skip to main content

​
Import

import { useSettlement } from '@keystoneos/react';

​
Usage

function SettlementView({ settlementId }) {
  const { settlement, isLoading, error, refetch } = useSettlement(settlementId);

  if (isLoading) return <Spinner />;
  if (error) return <Error message={error} />;
  if (!settlement) return <NotFound />;

  return (
    <div>
      <h2>{settlement.external_reference}</h2>
      <p>State: {settlement.state}</p>
      <p>Parties: {settlement.parties.length}</p>
      <p>Legs: {settlement.legs.length}</p>
    </div>
  );
}

​
Parameters

ParameterTypeRequiredDescription
settlementIdstring | nullYesThe settlement UUID. Pass null to skip fetching.

​
Return Type

interface UseSettlementResult {
  settlement: Settlement | null;
  isLoading: boolean;
  error: string | null;
  refetch: () => Promise<void>;
}
PropertyTypeDescription
settlementSettlement | nullThe settlement data, or null if not loaded.
isLoadingbooleantrue during the initial fetch.
errorstring | nullError message if the fetch failed.
refetch() => Promise<void>Manually trigger a re-fetch.

​
Behavior

  • Fetches the settlement on mount and whenever settlementId changes.
  • Subscribes to real-time updates via the event bus (polling in Phase 1, SSE in Phase 2).
  • When a state_changed event is received, the settlement object updates automatically.
  • Passing null as settlementId clears the settlement and stops subscriptions.

​
Settlement Object

The returned settlement includes parties and legs: 
interface Settlement {
  id: string;
  state: string;
  template_slug?: string;
  external_reference?: string;
  idempotency_key: string;
  timeout_at: string;
  created_at: string;
  updated_at: string;
  parties: SettlementParty[];
  legs: SettlementLeg[];
}
See Types for the full type definitions.