# better-auth-integration

The better-auth-integration skill connects Better Auth with Dodo Payments for customer sync, checkout, portal access, usage events, and signed webhooks.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 192 installs · ★ 14 repo stars
- Author: dodopayments
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/dodopayments/skills/tree/HEAD/dodo-payments/better-auth-integration/SKILL.md
- Updated: 2026-10-20
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/better-auth-integration

## What it does

The skill guides an integration of `@dodopayments/better-auth` with Better Auth. It covers creating a Dodo customer when a user signs up, starting checkout for a signed-in user, opening the customer portal, reading subscriptions and payments, sending metered usage, and handling verified webhooks.

Server features are configured through `dodopayments`, `checkout`, `portal`, `usage`, and `webhooks`; the browser client uses `dodopaymentsClient`. Install `@dodopayments/better-auth`, `dodopayments`, `better-auth`, and `zod`. The integration requires Better Auth 1.4 or a later 1.x release. The added `dodoCustomerId` field requires a schema update with `npx auth generate` or `npx auth migrate`.

Checkout slugs must match the configured Dodo product. Portal, subscription, payment, and usage calls use the authenticated Better Auth session, while some usage and portal operations require a verified email. Webhooks need `DODO_PAYMENTS_WEBHOOK_KEY`, and the Dodo client needs `DODO_PAYMENTS_API_KEY`. A feature omitted from `use` leaves its route returning 404.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add dodopayments/skills --skill better-auth-integration -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/better-auth-integration/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/better-auth-integration/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add dodopayments/skills --skill better-auth-integration -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/better-auth-integration/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add dodopayments/skills --skill better-auth-integration -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/better-auth-integration/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install dodopayments/skills dodo-payments/better-auth-integration/SKILL.md
```

2. **Manually: put the files in place**
- File: `.github/skills/better-auth-integration/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add dodopayments/skills --skill better-auth-integration -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/dodopayments/skills --path dodo-payments/better-auth-integration
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/better-auth-integration/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add dodopayments/skills --skill better-auth-integration -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/dodopayments/skills/tree/HEAD/dodo-payments/better-auth-integration/SKILL.md

## When to use it
- sync a Better Auth user with a Dodo customer
- start an authenticated checkout session
- open the customer portal from the browser
- send metered usage for the current customer
- handle signature-verified Dodo webhooks

## Example prompts
- Connect `@dodopayments/better-auth` to this Better Auth project and create a Dodo customer during signup.
- Configure checkout for the `premium-plan` product and require an authenticated session.
- Set up verified webhook handling with `DODO_PAYMENTS_WEBHOOK_KEY` and an `onPayload` callback.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: d1d2184afdfa194b.

BEGIN THIRD-PARTY FILE d1d2184afdfa194b
````text
---
name: better-auth-integration
description: Dodo Payments plugin for Better Auth (@dodopayments/better-auth) covering customer sync on signup, authenticated checkout, customer portal, usage ingestion, and verified webhooks. Use when an app uses Better Auth and needs the dodopayments, dodopaymentsClient, checkout, portal, usage, or webhooks plugins; for other auth stacks use framework-adapters.
---

# Better Auth Integration

Use `@dodopayments/better-auth` to synchronize Better Auth users with Dodo Payments and expose authenticated checkout, customer portal, subscription, payment, usage, and webhook endpoints.

## When to use this skill

- Create a Dodo customer automatically when a Better Auth user signs up.
- Start checkout for a signed-in user without exposing a Dodo API key.
- Let users open their customer portal or list their subscriptions and payments.
- Submit metered usage for the signed-in customer.
- Receive signature-verified Dodo webhooks through Better Auth.

## Install

```bash
npm install @dodopayments/better-auth dodopayments better-auth zod
```

Requires Better Auth 1.4 or a later 1.x release.

The package exports the lowercase server functions `dodopayments`, `checkout`, `portal`, `usage`, and `webhooks`. Its client entry point exports `dodopaymentsClient`.

## Server setup

Every endpoint is registered by a feature in `use`. Include every feature that the application calls; omitting one makes its route return 404.

```typescript
import { betterAuth } from "better-auth";
import DodoPayments from "dodopayments";
import { checkout, dodopayments, portal, usage, webhooks } from "@dodopayments/better-auth";

const dodoPayments = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: "test_mode",
});

export const auth = betterAuth({
  database: {
    // your database config
  },
  plugins: [
    dodopayments({
      client: dodoPayments,
      createCustomerOnSignUp: true,
      // `user` here is Better Auth's base user: id, name, email, emailVerified,
      // image, createdAt, updatedAt. Anything else (phone number, company, plan)
      // must first be declared via `user.additionalFields` in your Better Auth
      // config, otherwise it does not exist on the type and will be undefined.
      getCustomerParams: (user) => ({
````
END THIRD-PARTY FILE d1d2184afdfa194b

The third-party file has ended. Everything between the d1d2184afdfa194b tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2311 of 8287 bytes. © dodopayments · MIT · https://github.com/dodopayments/skills/tree/HEAD/dodo-payments/better-auth-integration/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
