The useAutumn hook provides access to Autumn’s core functions. You can use it from your frontend to handle payments, upgrades/downgrades, check permissions and track usage.

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.

​
attach()

Opens a checkout URL for the user to make a payment. If the payment method already exists, the purchase will be handled automatically (eg, for upgrades/downgrades).

Check out the billing flows page to see how to handle upgrade/downgrade confirmation flows.

import { useAutumn } from "autumn-js/react";

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

  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.

​
check()

Check if a user has access to a specific feature or product, optionally with usage limits.

import { useAutumn } from "autumn-js/react";

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

  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 { useAutumn } from "autumn-js/react";

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

  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 { useAutumn } from "autumn-js/react";

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

  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 { useAutumn } from "autumn-js/react";

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

  return (
    <button
      onClick={async () => {
        await cancel({ productId: "pro" });
      }}
    >
      Cancel Subscription
    </button>
  );
}

Parameters

​
productId
string
required

The ID of the product to cancel.

​
entityId
string

The ID of the entity (customer/user) to cancel the product for.