Checkout

Two hooks bracket a checkout: useCheckoutPreview shows what the customer owes today and what changes before anything is charged, and useCheckoutSession polls a hosted-form session until the PSP confirms. Both are scoped to the portal customer. Every hook returns isLoading: boolean and error: Error | null (see Introduction); the sections below list each hook’s specific returns.

useCheckoutPreview

Returns a server-computed preview of a checkout action — amount due today, the upcoming schedule, credit impact, line items, and warnings — before anything is charged. It calls POST /v1/checkout/sessions/preview with a discriminated input. Pass null to disable (e.g. while inputs are still being assembled). customerId is filled from context — callers omit it.

For plan-change previews, use useSubscription(id).previewChange() instead — it returns a richer shape (proration, entitlement diffs, direction/timing).

Parameters

CheckoutPreviewInput | null

required

The action to preview, a discriminated union on purpose. Pass null to hold the query inert.

Show purpose variants

{ purpose: 'subscription'; planId: string; subscriptionId?: string; amountCents?: number }

Preview subscribing to (or starting) a plan.

{ purpose: 'addon_purchase'; planId: string; subscriptionId: string }

Preview attaching an addon plan to an existing subscription.

{ purpose: 'credit_package'; creditPackageId: string }

Preview buying a fixed credit package.

{ purpose: 'credit_topup'; creditCurrencyId: string; amountCents: number }

Preview a custom-amount credit top-up into one wallet.

{ purpose: 'invoice_payment'; invoiceId: string }

Preview paying an outstanding invoice.

{ purpose: 'payment_method_update' }

Preview a payment-method update (no charge).

Returns

preview — the CheckoutPreviewResult, or null while loading / when disabled. It extends the shared base shape with the per-purpose details payload:

DueToday

Discriminated by kind: charge_now (cents, currency), invoice_later (cents, netDays, estimatedDate), or no_charge.

PreviewLineItem[]

{ description, unitAmount, quantity, subtotal, muted? } rows.

number

Money breakdown in minor units.

PreviewSchedule

Optional { date, amountCents? } for the next charge.

CreditImpact

Optional wallet delta — { currencyName, denomination, minorUnitScale, currentBalance, delta, afterBalance, … }.

PreviewWarning[]

{ code, params? } — e.g. trial_requires_payment_method, customer_has_no_payment_method.

Echoes the purpose; details is the per-purpose payload (e.g. details.subscription, details.creditTopup).

refresh() — () => Promise<void> — refetch the preview (e.g. after the customer edits the amount).

import { useCheckoutPreview } from '@unitpay/react';

export default function TopUpPreview({ creditCurrencyId }: { creditCurrencyId: string }) {
  const { preview, isLoading, error, refresh } = useCheckoutPreview({
    purpose: 'credit_topup',
    creditCurrencyId,
    amountCents: 2000,
  });

  if (isLoading) return <div>Calculating…</div>;
  if (error || !preview) return <div>Couldn’t preview.</div>;

  return (
    <div>
      {preview.dueToday.kind === 'charge_now' && (
        <div>Due today: {preview.dueToday.cents / 100} {preview.dueToday.currency}</div>
      )}
      {preview.creditImpact && (
        <div>New balance: {preview.creditImpact.afterBalance}</div>
      )}
      {preview.warnings.map((w) => <div key={w.code}>⚠ {w.code}</div>)}
      <button onClick={() => refresh()}>Recalculate</button>
    </div>
  );
}

useCheckoutSession

Polls GET /v1/checkout/sessions/:id/status and reports when a hosted-form payment resolves. Use it to await the result of a requires_form SettleOutcome — after the Elements form submits, the webhook completer flips the session to completed once the PSP confirms. Polling is tiered: ~1s for the first 30s (hot phase), then ~5s, then it stops and synthesizes expired at maxWaitMs. Parameters

string | null

required

The session to poll. Pass null to leave the hook idle (e.g. before the form step is reached). Changing the id resets the timeout.

boolean

default:"true"

Gate polling without unmounting the hook. Set false to hold the query inert (e.g. before the modal advances to its confirming step).

number

default:"90000"

Wall-clock cap on the pending window. After this elapses the hook stops polling and surfaces status: 'expired' even if the server row is still pending.

Returns

status — 'idle' | 'pending' | 'completed' | 'expired':
- 'idle' — no checkoutSessionId, or enabled is false.
- 'pending' — polling; defaults to this until the first fetch resolves.
- 'completed' — the PSP confirmed and the session row finalized.
- 'expired' — terminal server status, or the client-side maxWaitMs timeout fired.
data — the CheckoutSessionStatus row, or null before the first response: { id, status, completedAt, subscriptionId, invoiceId }.

import { useCheckoutSession } from '@unitpay/react';
import { useEffect } from 'react';

export default function ConfirmingStep({
  sessionId,
  onDone,
}: {
  sessionId: string;
  onDone: (subscriptionId: string | null) => void;
}) {
  const { status, data } = useCheckoutSession(sessionId, { maxWaitMs: 30_000 });

  useEffect(() => {
    if (status === 'completed') onDone(data?.subscriptionId ?? null);
  }, [status, data, onDone]);

  if (status === 'completed') return <div>All set ✓</div>;
  if (status === 'expired') return <div>Payment successful — provisioning is taking longer than usual.</div>;
  return <div>Confirming your payment…</div>;
}

Pair this with a requires_form outcome: render the <PaymentForm> Elements step, then mount useCheckoutSession(session.id) to await provisioning.

Catalog & pricing

The plans and packages a checkout starts from.

Settlement model

Every SettleOutcome kind and its callback, including requires_form.

Credits & wallets

Top-up and package purchases that feed the preview.

Overview

Building blocks

useCheckoutPreview

useCheckoutSession

See also

Catalog & pricing

Settlement model

Credits & wallets

​useCheckoutPreview

​useCheckoutSession

​See also

Catalog & pricing

Settlement model

Credits & wallets

useCheckoutPreview

useCheckoutSession

See also