Skip to main content
The useCustomer hook fetches customer data and provides billing actions like attaching plans and checking feature access.
Learn how to setup Autumn hooks in the Getting Started guide.

​
Parameters

​
errorOnNotFound
boolean
Whether to throw an error if the customer is not found. Defaults to false.
​
expand
CustomerExpand[]
Array of additional data to include in the response. Options: invoices, trials_used, rewards, entities, referrals, payment_method, subscriptions.plan, purchases.plan, balances.feature.
​
queryOptions
UseQueryOptions
Optional TanStack Query options to customize caching and refetching behavior.

​
Returns

​
data

The customer object containing subscriptions, purchases, and balances. 
import { useCustomer } from "autumn-js/react";

export default function CustomerProfile() {
  const { data, isLoading } = useCustomer();

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      <p>Name: {data?.name}</p>
      <p>Email: {data?.email}</p>
      <p>Messages remaining: {data?.balances?.messages?.remaining}</p>
    </div>
  );
}

​
attach()

Attaches a plan to the customer. Handles new subscriptions, upgrades, and downgrades. Automatically redirects to checkout if payment is required. 
import { useCustomer } from "autumn-js/react";

export default function UpgradeButton() {
  const { attach } = useCustomer();

  return (
    <button onClick={() => attach({ planId: "pro" })}>
      Upgrade to Pro
    </button>
  );
}
Parameters
​
planId
string
required
The ID of the plan to attach.
​
successUrl
string
URL to redirect to after successful checkout.
​
openInNewTab
boolean
Open checkout URL in a new tab instead of redirecting.
See the API reference for all available parameters.

​
check()

Checks feature access and balance for the customer locally (no API call).
This reads from the local data state. Combine with a backend check call for security.
import { useCustomer } from "autumn-js/react";

export default function SendMessageButton() {
  const { check } = useCustomer();

  const handleSend = () => {
    const result = check({ featureId: "messages" });
    
    if (!result.allowed) {
      alert("You've run out of messages!");
      return;
    }
    
    // Send the message...
  };

  return <button onClick={handleSend}>Send Message</button>;
}
Parameters
​
featureId
string
The ID of the feature to check access for.
​
entityId
string
The ID of the entity to check access for.
​
requiredBalance
number
The required balance amount to check against.

​
openCustomerPortal()

Opens the Stripe customer billing portal for managing subscriptions and payment methods. 
import { useCustomer } from "autumn-js/react";

export default function BillingSettings() {
  const { openCustomerPortal } = useCustomer();

  return (
    <button
      onClick={async () => {
        await openCustomerPortal({
          returnUrl: window.location.href,
        });
      }}
    >
      Manage Billing
    </button>
  );
}
Parameters
​
returnUrl
string
URL to redirect to when the customer exits the billing portal.
​
openInNewTab
boolean
Open portal in a new tab instead of redirecting.

​
isLoading

Boolean indicating whether the customer data is currently being fetched. 
import { useCustomer } from "autumn-js/react";

export default function CustomerLoader() {
  const { data, isLoading } = useCustomer();

  if (isLoading) return <div>Loading...</div>;

  return <div>Welcome, {data?.name}!</div>;
}

​
error

Any error that occurred while fetching customer data. 
import { useCustomer } from "autumn-js/react";

export default function CustomerWithError() {
  const { data, error, isLoading } = useCustomer();

  if (error) return <div>Error: {error.message}</div>;
  if (isLoading) return <div>Loading...</div>;

  return <div>Customer: {data?.name}</div>;
}

​
refetch()

Function to manually refetch the customer data. 
import { useCustomer } from "autumn-js/react";

export default function CustomerWithRefresh() {
  const { data, refetch } = useCustomer();

  return (
    <div>
      <p>Balance: {data?.balances?.messages?.remaining}</p>
      <button onClick={() => refetch()}>Refresh</button>
    </div>
  );
}