Convex

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

pnpm add autumn-js @useautumn/convex

yarn add autumn-js @useautumn/convex

bun add 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:'am_sk_42424242',
	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();

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

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

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

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

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

		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.

Getting Started

Configure Pricing

Billing & Subscriptions

Customers

Additional Resources

Lakehouse

Setup

1. Install the npm packages

2. Set the Autumn secret key in your convex environment

3. Add the component to your application

4. Initialize the Autumn client

5. Setting up <AutumnProvider/> on your frontend

Using Autumn hooks and components on the frontend

Using Autumn on the backend

Check feature access

Track feature usage

​Setup

​1. Install the npm packages

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

​3. Add the component to your application

​4. Initialize the Autumn client

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

​Using Autumn hooks and components on the frontend

​Using Autumn on the backend

​Check feature access

​Track feature usage

Setup

1. Install the npm packages

2. Set the Autumn secret key in your convex environment

3. Add the component to your application

4. Initialize the Autumn client

5. Setting up <AutumnProvider/> on your frontend

Using Autumn hooks and components on the frontend

Using Autumn on the backend

Check feature access

Track feature usage