> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useautumn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Convex

> Implementing the Autumn + Convex component

<Note>
  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.
</Note>

## Setup

#### 1. Install the npm packages

<CodeGroup>
  ```bash npm theme={null}
  npm install autumn-js @useautumn/convex
  ```

  ```bash pnpm theme={null}
  pnpm add autumn-js @useautumn/convex
  ```

  ```bash yarn theme={null}
  yarn add autumn-js @useautumn/convex
  ```

  ```bash bun theme={null}
  bun add autumn-js @useautumn/convex
  ```
</CodeGroup>

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

<CodeGroup>
  ```bash theme={null}
  npx convex env set AUTUMN_SECRET_KEY=am_sk_xxx
  ```
</CodeGroup>

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

Add the autumn convex component to your `convex/convex.config.ts`

```typescript convex/convex.config.ts theme={null}
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`

<CodeGroup>
  ```typescript Convex Auth theme={null}
  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();
  ```

  ```typescript Clerk / Better Auth theme={null}
  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();
  ```

  ```typescript Others theme={null}
  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();
  ```
</CodeGroup>

<Note>
  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](/documentation/customers/feature-entities).
</Note>

<Warning>
  In the `identify()` function, you may need to change `user.subject` to `user.id` depending on your auth provider.
</Warning>

#### 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`:

<CodeGroup>
  ```typescript theme={null}
  "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>
    );
  }
  ```
</CodeGroup>

<Note>
  If you're using Autumn purely on the backend, you may skip this step.
</Note>

## Using Autumn hooks and components on the frontend

`<PricingTable/>`

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

```typescript src/app/page.tsx [expandable] wrap theme={null}
import { PricingTable } from "autumn-js/react";

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

<Note>
  Our components can be downloaded as shadcn components and are fully customizable. You can learn how to do so [here](https://docs.useautumn.com/setup/shadcn)
</Note>

`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:

```typescript src/app/page.tsx [expandable] wrap theme={null}
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](/react/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

```typescript theme={null}
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

```typescript theme={null}
import { autumn } from "convex/autumn";

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

<Note>
  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](https://docs.useautumn.com/api-reference/core/checkout)
</Note>

**Congrats 🎉**

Nice! You've now integrated Autumn into your application with Convex.

{/* If you have used autumn-js before, this should be very familiar for you. The code is almost identical,
you just need to pass in some Convex-specific props to your `<AutumnProvider />`. Below are examples using Clerk and Better Auth for authentication.
You may simply copy this into your codebase. */}