useCustomer

The useCustomer hook fetches customer profile data and feature access in one request. If the customer does not exist yet, PriceOS will create it automatically.

Setup first: see the React integration guide.

Typed
Untyped

const result = useCustomer<MyFeatures>(options?)

const result = useCustomer(options?)

Parameters

boolean

Enable or disable fetching. Defaults to true.

boolean

When true, a 404 is surfaced as an error instead of returning null. Defaults to false.

SWRConfiguration<PriceOSCustomer<MyFeatures> | null, Error>

Optional SWR config for caching/revalidation behavior.

Returns

PriceOSCustomer<MyFeatures> | null

Customer data including profile fields and featureAccess.

boolean

Whether data is currently loading.

Error | null

Error from the latest request.

() => Promise<void>

Manually revalidate customer data.

(body) => Promise<TrackUsageResponse>

Tracks usage and revalidates customer and feature-access caches.

(body) => Promise<CreateCheckoutResponse>

Creates a checkout session and redirects to Stripe Checkout.

(body?) => Promise<CreateCustomerPortalResponse>

Creates a customer portal session and redirects to Stripe Customer Portal.

`trackUsage` body

string

required

Feature key to track usage for (typed to your tracked limit feature keys when using generated types).

number

Usage amount to record. Defaults to 1.

string

Stable event key for retries and deduplication.

number

Unix timestamp in milliseconds for when the event happened.

Record<string, string>

Optional string key/value metadata attached to the usage event.

When using built-in Next.js handlers (priceos/next), client hook calls must use a positive amount. For negative adjustments, track usage on your backend with the Node.js SDK or REST API.

Examples

Typed Example
Untyped Example

import { useCustomer } from "priceos/react";
import type { MyFeatures } from "./priceos.types";

export function CustomerCard() {
  const { customer, isLoading, error, refetch, trackUsage, checkout, openCustomerPortal } = useCustomer<MyFeatures>();

  const customerName = customer?.name ?? "Unknown";
  const hasBlogAccess = customer?.featureAccess?.blogs?.hasAccess;

  async function onAddSeat() {
    await trackUsage({
      featureKey: "team_seats",
      amount: 1,
      eventKey: `add_team_seat_${Date.now()}`,
    });
  }

  async function onUpgrade() {
    await checkout({
      productKey: "starter_monthly",
      successUrl: "https://app.acme.com/settings/billing?checkout=success",
      cancelUrl: "https://app.acme.com/settings/billing?checkout=canceled",
    });
  }

  async function onManageBilling() {
    await openCustomerPortal();
  }

  if (isLoading) return <div>Loading...</div>;
  if (error) return <button onClick={refetch}>Retry</button>;

  return (
    <div>
      <h3>{customerName}</h3>
      <p>Blog access: {hasBlogAccess ? "Yes" : "No"}</p>
      <button onClick={onAddSeat}>Add teammate</button>
      <button onClick={onUpgrade}>Upgrade</button>
      <button onClick={onManageBilling}>Manage billing</button>
    </div>
  );
}

import { useCustomer } from "priceos/react";

export function CustomerCard() {
  const { customer, isLoading, error, refetch, trackUsage, checkout, openCustomerPortal } = useCustomer();

  const customerName = customer?.name ?? "Unknown";
  const hasBlogAccess = customer?.featureAccess?.blogs?.hasAccess;

  async function onAddSeat() {
    await trackUsage({
      featureKey: "team_seats",
      amount: 1,
      eventKey: `add_team_seat_${Date.now()}`,
    });
  }

  async function onUpgrade() {
    await checkout({
      productKey: "starter_monthly",
      successUrl: "https://app.acme.com/settings/billing?checkout=success",
      cancelUrl: "https://app.acme.com/settings/billing?checkout=canceled",
    });
  }

  async function onManageBilling() {
    await openCustomerPortal();
  }

  if (isLoading) return <div>Loading...</div>;
  if (error) return <button onClick={refetch}>Retry</button>;

  return (
    <div>
      <h3>{customerName}</h3>
      <p>Blog access: {hasBlogAccess ? "Yes" : "No"}</p>
      <button onClick={onAddSeat}>Add teammate</button>
      <button onClick={onUpgrade}>Upgrade</button>
      <button onClick={onManageBilling}>Manage billing</button>
    </div>
  );
}

Components

React Hooks

Misc

Parameters

Returns

`trackUsage` body

Examples

​Parameters

​Returns

​trackUsage body

​Examples

Parameters

Returns

`trackUsage` body

Examples