useCustomer - Autumn

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

Show Customer object

{
  "id": "user_123",
  "name": "John Doe",
  "email": "john@example.com",
  "createdAt": 1771409161016,
  "fingerprint": null,
  "stripeId": "cus_stripe123",
  "env": "sandbox",
  "metadata": {},
  "sendEmailReceipts": false,
  "subscriptions": [
    {
      "planId": "pro_plan",
      "autoEnable": false,
      "addOn": false,
      "status": "active",
      "pastDue": false,
      "canceledAt": null,
      "expiresAt": null,
      "trialEndsAt": null,
      "startedAt": 1771431921437,
      "currentPeriodStart": 1771431921437,
      "currentPeriodEnd": 1771999921437,
      "quantity": 1
    }
  ],
  "purchases": [],
  "balances": {
    "messages": {
      "featureId": "messages",
      "granted": 100,
      "remaining": 72,
      "usage": 28,
      "unlimited": false,
      "overageAllowed": false,
      "maxPurchase": null,
      "nextResetAt": 1773851121437
    }
  }
}

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

​Parameters

​Returns

​data

​attach()

​check()

​openCustomerPortal()

​isLoading

​error

​refetch()

Parameters

Returns

`data`

`attach()`

`check()`

`openCustomerPortal()`

`isLoading`

`error`

`refetch()`