Imperative API

The typed mutation hooks (useChangePlan, useTopUp, useAttachAddon, …) cover the common flows and integrate with React Query cache / loading / error state. useBilling is the escape hatch for everything else — imperative calls from event handlers, async flows, and non-render contexts. Every hook returns isLoading: boolean and error: Error | null (see Introduction); the section below lists this hook’s specific returns.

useBilling

Returns the underlying UnitPayClient bound to the active portal token. Use it for ad-hoc imperative calls and non-render contexts — event handlers, async flows, anything not tied to the render lifecycle. For form submissions and anything that should integrate with React Query cache / loading / error state, prefer the dedicated mutation hooks where they exist. Parameters — none.

useBilling throws if no portalToken is set on <UnitPayProvider>. This surfaces the misconfiguration at first use rather than letting calls silently no-op. Only call it under a provider configured with a portal token.

Returns

UnitPayClient — the imperative client instance. It exposes resource accessors (e.g. billing.subscription(id), billing.usage) plus settlement helpers like handleSettlement.

import { useBilling } from '@unitpay/react';
import { useRouter } from 'next/navigation';

export default function ChangePlanButton({ subId, newPlanId }: { subId: string; newPlanId: string }) {
  const billing = useBilling();
  const router = useRouter();

  async function handleChange() {
    const result = await billing.subscription(subId).change({ newPlanId });
    billing.handleSettlement(result, {
      onChargedInline: () => router.push('/billing'),
    });
  }

  return <button onClick={handleChange}>Switch plan</button>;
}

Reach for a dedicated hook first — useBilling is the escape hatch for flows the typed hooks don’t cover.

Settlement model

The handleSettlement outcome kinds and their callbacks.

Provider

Configure the portalToken useBilling binds to.

Overview

Building blocks

useBilling

See also

Settlement model

Provider

​useBilling

​See also

Settlement model

Provider

useBilling

See also