The useCustomer hook provides access to customer data and related operations. You can use it from your frontend to retrieve customer information, manage loading states, and create entities.
To use Autumn’s React hooks, you should set up the autumnHandler in your backend and the <AutumnProvider /> in your frontend, as described in the quickstart guide. This gives the hooks access to the customerId making the request.

​
Parameters

​
expand
string[]
Array of additional data to include in the customer response. Options may include invoices, trials_used or rewards.

​
customer

The customer object containing all customer data. 
import { useCustomer } from "autumn-js/react";

export default function CustomerProfile() {
  const { customer } = useCustomer({ expand: ["invoices"] });

  return (
    <div>
      <h2>Customer Profile</h2>
      <p>Name: {customer?.name}</p>
      <p>Email: {customer?.email}</p>
      <p>Balance: {customer?.features.chat_messages?.balance}</p>
    </div>
  );
}

​
attach()

Opens a checkout URL for the user to make a payment. If the payment method already exists, a payment confirmation dialog (AttachDialog) will be opened. You can override the default dialog by passing in a dialog prop, or disable it by passing in disableDialog: true into <AutumnProvider />.
Check out the billing flows page to see how to handle upgrade/downgrade confirmation flows.
import { useCustomer } from "autumn-js/react";

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

  return (
    <button
      onClick={async () => {
        await attach({
          productId: "pro",
        });
      }}
    >
      Upgrade to Pro
    </button>
  );
}
Parameters
​
productId
string
required
The ID of the product to attach.
​
dialog
(data: any) => JSX.Element | React.ReactNode
A dialog that pops up to confirm the purchase (eg, for upgrades/downgrades). See the billing flows page.
​
entityId
string
The ID of the entity (eg, user seat) to attach the product to.
​
options
AttachFeatureOptions[]
Array of feature options to configure for the attachment. Each option contains featureId (string) and quantity (number).
​
productIds
string[]
Array of additional product IDs to attach simultaneously.
​
freeTrial
boolean
Whether to disable free trials for this product. Only applicable if the product has a free trial.
​
successUrl
string
URL to redirect to after successful attachment/checkout.
​
metadata
Record<string, string>
Additional metadata to pass onto Stripe.
​
forceCheckout
boolean
Whether to force the checkout flow even if the payment method already exists. Not available for upgrades/downgrades.
​
openInNewTab
boolean
default:"false"
Whether to open the checkout URL in a new tab.

​
allowed

Check if a user has access to a specific feature or product. This will be read from the customer state object on the frontend (so no API call is made). 
import { useCustomer } from "autumn-js/react";

export default function FeatureGate({ children }) {
  const { allowed } = useCustomer();

  return <div>{allowed({ featureId: "analytics" }) ? children : null}</div>;
}
Parameters
​
featureId
string
The ID of the feature to check access for.
​
productId
string
The ID of the product to check access for.

​
check()

Check if a user has access to a specific feature or product. This will make an API call to Autumn to check access. You can use this to always get the most up-to-date usage data. 
import { useCustomer } from "autumn-js/react";

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

  return (
    <button
      onClick={async () => {
        const { data, error } = await check({
          featureId: "chat-messages",
          requiredBalance: 7,
        });
      }}
    >
      Send 7 Messages
    </button>
  );
}
Parameters
​
featureId
string
The ID of the feature to check access for.
​
productId
string
The ID of the product to check access for.
​
dialog
(data: any) => JSX.Element | React.ReactNode
A dialog that pops up to act as a paywall (eg, when a feature runs out). See the billing flows page.
​
entityId
string
The ID of the entity (customer/user) to check access for.
​
requiredBalance
number
The required balance/usage amount to check against.
​
sendEvent
boolean
Whether to send an event when checking access.
​
withPreview
boolean
Return preview data to display to the user. Using this with a featureID will return paywall data, and using it with a productId will return upgrade/downgrade data.

​
track()

Track usage events for features or custom analytics. 
import { useCustomer } from "autumn-js/react";

export default function ApiCallButton() {
  const { track } = useCustomer();

  const handleApiCall = async () => {
    // Make your API call
    await makeApiCall();

    // Track the usage
    await track({
      featureId: "api-calls",
      value: 1,
      idempotencyKey: `api-call-${Date.now()}`,
    });
  };

  return <button onClick={handleApiCall}>Make API Call</button>;
}
Parameters
​
featureId
string
The ID of the feature to track usage for.
​
eventName
string
Custom event name for tracking.
​
entityId
string
The ID of the entity (customer/user) to track usage for.
​
value
number
The value/quantity to track (e.g., number of API calls, storage used).
​
idempotencyKey
string
Unique key to prevent duplicate tracking events.

​
openBillingPortal()

Open the billing portal for customers to manage their subscriptions, payment methods, and billing information. 
import { useCustomer } from "autumn-js/react";

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

  return (
    <button
      onClick={async () => {
        await openBillingPortal({
          returnUrl: "/settings/billing",
        });
      }}
    >
      Manage Billing
    </button>
  );
}
Parameters
​
returnUrl
string
URL to redirect to when the customer exits the billing portal.

​
cancel()

Cancel a product or subscription for a user/entity. 
import { useCustomer } from "autumn-js/react";

export default function CancelSubscription() {
  const { cancel } = useCustomer();

  return (
    <button
      onClick={async () => {
        await cancel({ productId: "pro" });
      }}
    >
      Cancel Subscription
    </button>
  );
}
Parameters
​
productId
string
required
The ID of the product to cancel.
​
cancelImmediately
boolean
Whether to cancel the product immediately. If false, the product will be cancelled at the end of the billing cycle.
​
entityId
string
The ID of the entity (customer/user) to cancel the product for.

​
refetch

Function to manually refetch the customer data, eg when updating a customer’s usage or balance to display. 
import { useCustomer } from "autumn-js/react";

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

  const sendMessage = async () => {
    await track({ featureId: "chat_messages" });
    await refetch();
  };

  return <button onClick={sendMessage}>Send Message</button>;
}

​
createEntity

Function to create one or more entities for the customer. 
import { useCustomer } from "autumn-js/react";

export default function CreateUserSeat() {
  const { createEntity } = useCustomer();

  const handleCreateSeat = async () => {
    const { data, error } = await createEntity({
      id: "user_abc",
      name: "John Doe",
      featureId: "seats",
    });
    console.log("Created entity:", data);
  };
}

return <button onClick={handleCreateSeat}>Create User Seat</button>;
Parameters
​
id
string
required
The ID of the entity to create.
​
name
string
Display name for the entity.
​
featureId
string
The feature ID for the entity being created. Must be a continuous_use feature.

​
isLoading

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

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

  if (isLoading) {
    return <div>Loading customer data...</div>;
  }

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

​
error

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

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

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

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

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