# Autumn

A autumn component for Bijection.

- Package: @bijectionhq/autumn
- Category: Payments
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/autumn/tree/ae774427c30b0dd7425a0e070286146e236d4194/convex
- Upstream: https://github.com/useautumn/typescript/tree/ecadaf19293f558bea04565a19d4aff3abaebc8c/convex
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/autumn

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/autumn.git
cd autumn
git checkout ae774427c30b0dd7425a0e070286146e236d4194
cd convex
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Upstream package documentation

Recorded 2026-10-23. This describes @useautumn/convex; check the Bijection adaptation separately.

Autumn provides a complete pricing and billing system built on top of Stripe, designed specifically for Convex applications. It abstracts complex billing logic into three core functions: check for feature access, track for usage metering, and checkout for purchases. The component handles subscriptions, usage-based pricing, seat-based billing, trials, and credits while providing both backend APIs and React components for frontend integration.

### Use cases

- **Usage-based billing**: Track API calls, messages, or compute usage with `autumn.track()` and automatically bill customers based on consumption
- **Feature gating**: Use `autumn.check()` to restrict access to premium features like advanced analytics or higher rate limits based on subscription tiers
- **Self-serve upgrades**: Drop in the `<PricingTable/>` component or use `checkout()` with custom UI to let users upgrade their plans without leaving your app
- **Multi-tenant billing**: Leverage the `identify()` function to bill at the organization level while tracking individual user actions within teams
- **Freemium conversions**: Combine usage tracking with access checks to automatically prompt upgrades when users hit plan limits

### How it works

The component integrates with your Convex app through a standard component configuration in `convex.config.ts` and requires setting up an Autumn client with your Stripe credentials. The core architecture centers around an `identify()` function that maps your authentication system to Autumn's customer model, supporting various auth providers like Convex Auth, Clerk, or custom solutions.

On the backend, you use three primary functions: `autumn.check()` validates feature access before executing actions, `autumn.track()` records usage for metering, and `autumn.checkout()` initiates purchase flows. These functions integrate directly with your Convex mutations and actions, allowing you to gate features and track usage inline with your business logic.

The frontend integration uses an `<AutumnProvider/>` wrapper that connects to your Convex client, enabling React hooks like `useCustomer()` for accessing billing data and triggering upgrades. Pre-built components like `<PricingTable/>` and `<CheckoutDialog/>` provide ready-to-use UI, while the hooks allow for custom billing interfaces that fit your app's design.

### Upstream README

# Autumn + Convex

## Introduction
[Autumn](https://useautumn.com) is your pricing and customer database—an abstraction over Stripe that lets you model any pricing (subscriptions, usage-based, seats, trials, credits) and implement it in your codebase in just three functions: check for access, track for metering, and checkout for purchases.

## Setup

> Note: You’ll need Convex v1.25.0+ and `autumn-js` v0.1.24+.

#### 1) Install the packages

```bash
npm install @useautumn/convex autumn-js 
```

#### 2) Set the Autumn secret key in your Convex environment

```bash
npx convex env set AUTUMN_SECRET_KEY=am_sk_xxx
```

#### 3) Add the component to your application

Add the Autumn Convex component to `convex/convex.config.ts`:

```ts
import { defineApp } from "convex/server";
import autumn from "@useautumn/convex/convex.config";

const app = defineApp();
app.use(autumn);

export default app;
```

#### 4) Initialize the Autumn client

In `convex/autumn.ts`, add the following code:

```ts
import { components } from "./_generated/api";
import { Autumn } from "@useautumn/convex";

export const autumn = new Autumn(components.autumn, {
  secretKey: process.env.AUTUMN_SECRET_KEY ?? "",
  identify: async (ctx: any) => {
    const user = await ctx.auth.getUserIdentity();
    if (!user) return null;

    const userId = user.subject.split("|")[0];
    return {
      customerId: userId,
      customerData: {
        name: user.name as string,
        email: user.email as string,
      },
    };
  },
});

export const {
  track,
  cancel,
  query,
  attach,
  check,
  checkout,
  usage,
  setupPayment,
  createCustomer,
  listProducts,
  billingPortal,
  createReferralCode,
  redeemReferralCode,
  createEntity,
  getEntity,
} = autumn.api();
```
> The example above uses Convex auth as an example. Visit this [page](https://docs.useautumn.com/setup/convex#4-initialize-the-autumn-client) see code snippets for other providers like Clerk / Better Auth

> Note: The `identify()` function determines which customer is making the request. Customize it for your use case (e.g. use an organization ID as `customerId` for entity billing). You may need to change `user.subject` to `user.id` depending on your auth provider.

#### 5) Set up `<AutumnProvider />` on your frontend

Add `AutumnWrapper.tsx` to enable hooks and components:

```tsx
"use client";
import { AutumnProvider } from "autumn-js/react";
import { api } from "../convex/_generated/api";
import { useConvex } from "convex/react";

export function AutumnWrapper({ children }: { children: React.ReactNode }) {
  const convex = useConvex();

  return (
    <AutumnProvider convex={convex} convexApi={(api as any).autumn}>
      {children}
    </AutumnProvider>
  );
}
```

> Note: If you use Autumn only on the backend, you can skip this step.

## Using hooks and components on the frontend

The quickest way to get started is to use our `<PricingTable/>` component:

`<PricingTable/>`

```tsx
import { PricingTable } from "autumn-js/react";

export default function Home() {
  return <PricingTable />;
}
```

> Components are available as shadcn components and are fully customizable: https://docs.useautumn.com/setup/shadcn

`useCustomer`

We also provide a useCustomer hook which lets you easily access your customer data and interact with the Autumn API directly from your frontend. For example, to upgrade a user:

```tsx
import { useCustomer, CheckoutDialog } from "autumn-js/react";

export default function Home() {
  const { customer, track, check, checkout } = useCustomer();
  return (
    <button
      onClick={() =>
        checkout({
          productId: "pro",
          dialog: CheckoutDialog,
        })
      }
    >
      Upgrade to Pro
    </button>
  );
}
```

You can use all `useCustomer()` and `useEntity()` features as usual. Learn more about our react hooks [here](https://docs.useautumn.com/api-reference/hooks/useCustomer).

## Using Autumn on the backend

You will also need to use Autumn on your backend for actions such as tracking or gating usage of a feature. To do so, you can use our Autumn client:

Check feature access:

```ts
import { autumn } from "convex/autumn";

const { data, error } = await autumn.check(ctx, {
  featureId: "messages",
});

if (data.allowed) {
  // Action to perform if user is allowed messages
}
```

Track feature usage:

```ts
import { autumn } from "convex/autumn";

const { data, error } = await autumn.track(ctx, {
  featureId: "messages",
  value: 10,
});
```

These are the most common functions, but others like `checkout` and `attach` are also available. API reference: https://docs.useautumn.com/api-reference/core/checkout