Skip to main content
As a prerequisite, you will require Convex version 1.25.0 or higher. Additionally, if you already have autumn-js installed, it will need to be version 0.1.24 or higher.

​
Setup

​
1. Install the npm packages

npm install autumn-js @useautumn/convex

​
2. Set the Autumn secret key in your convex environment

npx convex env set AUTUMN_SECRET_KEY=am_sk_xxx

​
3. Add the component to your application

Add the autumn convex component to your convex/convex.config.ts
convex/convex.config.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

Paste the following code into convex/autumn.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: user.subject as string,
			customerData: {
				name: user.name as string,
				email: user.email as string,
			},
		};
	},
});

/**
 * These exports are required for our react hooks and components
 */

export const {
  track,
  cancel,
  query,
  attach,
  check,
  checkout,
  usage,
  setupPayment,
  createCustomer,
  listProducts,
  billingPortal,
  createReferralCode,
  redeemReferralCode,
  createEntity,
  getEntity,
} = autumn.api();
The identify() function determines which customer is making the request. You may customise it based on your use case. For example, if organizations are your customers, you should return an organization ID as customerId. This can help you with entity billing.
In the identify() function, you may need to change user.subject to user.id depending on your auth provider.

​
5. Setting up <AutumnProvider/> on your frontend

This allows your React app to make use of our hooks and components. To do this, add the following to a file AutumnWrapper.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>
  );
}
If you’re using Autumn purely on the backend, you may skip this step.

​
Using Autumn hooks and components on the frontend

<PricingTable/> The quickest way to get started is to use our <PricingTable/> component:
src/app/page.tsx
import { PricingTable } from "autumn-js/react";

export default function Home() {
  return (
    <PricingTable/>
  );
}
Our components can be downloaded as shadcn components and are fully customizable. You can learn how to do so here
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:
src/app/page.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 of the useCustomer() and useEntity() features as you would normally. If you aren’t familiar with these, you can read more about them here.

​
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

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

import { autumn } from "convex/autumn";

const { data, error } = await autumn.track(ctx, {
	featureId: "messages",
	value: 10
});
These are the most common functions you’ll be using, but we also export all other functions in our JS SDK / API reference, for eg:
  • checkout
  • attach And more!
Check out our API reference here
Congrats 🎉 Nice! You’ve now integrated Autumn into your application with Convex. Next steps:
  • Learn how to make credits-based pricing models with Autumn
  • Learn how to make prepaid pricing models with Autumn
⌘I