Skip to main content
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
CustomerExpandOption[]
Array of additional data to include in the customer response. Options include invoices, rewards, trials_used, entities, referrals, payment_method.

​
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>
  );
}

​
checkout()

Opens a checkout URL for the user to make a payment. If the payment method already exists, purchase confirmation data will be returned. If a dialog is passed in, a payment confirmation dialog (CheckoutDialog) will be opened. 
import { useCustomer } from "autumn-js/react";
import CheckoutDialog from "@/components/autumn/checkout-dialog";
// or import { CheckoutDialog } from "autumn-js/react";

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

  return (
    <button
      onClick={async () => {
        await checkout({
          productId: "pro",
          dialog: CheckoutDialog,
        });
      }}
    >
      Upgrade to Pro
    </button>
  );
}
Parameters
​
productId
string
required
The ID of the product being enabled.
​
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.
​
checkoutSessionParams
object
Pass in Stripe checkout session fields and they will be forwarded on.
​
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.

​
attach()

Enables a product for a customer and handles a payment. Typically used after the checkout function. If the payment method is not on file, this function will also return a Checkout URL. 
import { useCustomer } from "autumn-js/react";

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

  return (
    <div>
      Click to confirm your upgrade. Your card will be charged.
      <button
        onClick={async () => {
          await attach({
            productId: "ultra",
          });
        }}
      >
        Confirm Purchase
      </button>
    </div>
  );
}
Parameters
​
productId
string
required
The ID of the product to attach.
​
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.

​
check()

Check if a user has access to a specific feature or product.
This will be read from the local customer state object, so no API call to Autumn is made. This should be combined with a backend check call for security.
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 analytics.
Tracking usage client-side is not recommended, as a user in theory could stop script execution and mess with your tracking data.
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: "https://useautumn.com/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>;
}
⌘I