Skip to main content
skill CX Codex

better-auth-integration — Claude Code skill: setup guide

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

MIT 192 installs ★ 14 updated 2026-10-20

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add dodopayments/skills --skill better-auth-integration -a claude-code
Open on GitHub

What better-auth-integration 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.

What it helps with

  • 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 for the agent

  • 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.

How to install better-auth-integration

1Skills CLI (Vercel)

npx skills add dodopayments/skills --skill better-auth-integration -a claude-code

2Manually: put the files in place

~/.claude/skills/better-auth-integration/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/better-auth-integration/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about better-auth-integration

How do I install better-auth-integration in Claude Code?

Run npx skills add dodopayments/skills --skill better-auth-integration -a claude-code. Then check ~/.claude/skills/better-auth-integration/SKILL.md.

What does better-auth-integration do?

It helps wire Better Auth to Dodo Payments for signup customer sync, authenticated checkout, the customer portal, subscription and payment data, usage ingestion, and verified webhooks.

Which dependencies and Better Auth version are required?

Install @dodopayments/better-auth, dodopayments, better-auth, and zod. The integration requires Better Auth 1.4 or a later release in the 1.x line.

Source text

SKILL.md · MIT
---
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) => ({
        metadata: { better_auth_user_id: user.id },
      }),
      use: [
        checkout({
          products: [
            { productId: "pdt_premium", slug: "premium-plan" },
          ],
          successUrl: "https://app.example.com/billing/success",
          authenticatedUsersOnly: true,
        }),
        portal(),
        usage(),
        webhooks({
          webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
          onPayload: async (payload) => {
            console.log("Verified Dodo webhook:", payload.type);
          },
        }),
      ],
    }),
  ],
});
```

`products` maps an application slug to a Dodo product ID. `authenticatedUsersOnly: true` requires a Better Auth session for checkout. `getCustomerParams` adds application metadata when customer synchronization runs.

The plugin adds a `dodoCustomerId` field to the Better Auth `user` table. After adding the plugin, update your database schema with the [Better Auth CLI](https://www.better-auth.com/docs/concepts/cli):

```bash
npx auth generate   # generate the ORM schema or SQL migration, then apply it yourself
npx auth migrate    # or apply it directly (built-in Kysely adapter only)
```

## Browser client setup

```typescript
import { createAuthClient } from "better-auth/react";
import { dodopaymentsClient } from "@dodopayments/better-auth/client";

export const authClient = createAuthClient({
  plugins: [dodopaymentsClient()],
});
```

These are browser methods. They send the Better Auth session cookie automatically; do not pass `request.headers` to them.

## Create a checkout session

```typescript
import { authClient } from "@/lib/auth-client";

async function startCheckout() {
  const { data: session, error } = await authClient.dodopayments.checkoutSession({
    slug: "premium-plan",
    referenceId: "order_123",
  });

  if (error) {
    console.error("Checkout error:", error);
    return;
  }

  if (session) {
    window.location.href = session.url;
  }
}
```

`slug` must match a product configured in `checkout({ products: [...] })`. `referenceId` is optional reconciliation metadata.

## Open the customer portal

```typescript
const { data: portalSession, error } =
  await authClient.dodopayments.customer.portal();

if (error) {
  console.error("Portal error:", error);
} else if (portalSession?.redirect) {
  window.location.href = portalSession.url;
}
```

The portal endpoint requires a signed-in, verified user and resolves that user's synchronized Dodo customer.

## List subscriptions and payments

```typescript
const { data: subscriptions, error: subscriptionsError } =
  await authClient.dodopayments.customer.subscriptions.list({
    query: { page: 1, limit: 10, status: "active" },
  });

const { data: payments, error: paymentsError } =
  await authClient.dodopayments.customer.payments.list({
    query: { page: 1, limit: 10, status: "succeeded" },
  });

if (subscriptionsError || paymentsError) {
  console.error("Could not load billing history");
} else {
  console.log("Subscriptions:", subscriptions?.items);
  console.log("Payments:", payments?.items);
}
```

Both list responses use an `items` envelope. Subscription filters accept `page`, `limit`, and `status`; payment filters use the same pagination fields and payment statuses.

## Ingest metered usage

Enable `usage()` on the server, then submit an event for the signed-in customer:

```typescript
const { data, error } = await authClient.dodopayments.usage.ingest({
  event_id: "evt_usage_123",
  event_name: "api_calls",
  metadata: { requests: 100 },
  timestamp: new Date(),
});

if (error) {
  console.error("Usage ingestion failed:", error);
} else {
  console.log("Ingested events:", data?.ingested_count);
}
```

Both `usage.ingest` and `usage.meters.list` require a signed-in user with a verified email address. The plugin derives `customer_id` from the authenticated session. `event_id` is the event's idempotency key; reuse it when retrying the same event.

## Webhook endpoint

`webhooks({ webhookKey, onPayload })` verifies and handles the request itself. With Better Auth's default `/api/auth` base path, configure this URL in the Dodo dashboard:

```text
https://app.example.com/api/auth/dodopayments/webhooks
```

Do not create a second route and do not call `auth.api.dodopayments.verifyWebhook()`; that method does not exist. The plugin reads the raw request, verifies the Standard Webhooks signature with `webhookKey`, and invokes `onPayload` plus any configured event-specific callback.

## Registered endpoints

- `POST /dodopayments/checkout`
- `POST /dodopayments/checkout-session`
- `GET /dodopayments/customer/portal`
- `GET /dodopayments/customer/subscriptions/list`
- `GET /dodopayments/customer/payments/list`
- `POST /dodopayments/usage/ingest`
- `GET /dodopayments/usage/meters/list`
- `POST /dodopayments/webhooks`

Better Auth prefixes these plugin paths with its configured API base path.

## Common mistakes

**Enabling only `portal()`.** Checkout, usage, and webhook routes do not exist unless `checkout()`, `usage()`, and `webhooks()` are also present in `use`.

**Mixing browser and server APIs.** Call `authClient.dodopayments...` in browser code without a `headers` option. Use Better Auth's server API separately when handling server requests.

**Creating duplicate customers.** When `createCustomerOnSignUp` is enabled, do not also call `client.customers.create()` for the same user.

**Granting access from browser state.** Treat verified webhook events or a server-side Dodo lookup as the source of truth for entitlements.

**Adding a custom webhook verifier.** The plugin owns `/dodopayments/webhooks`, signature verification, and callback dispatch.

## Resources

- [Better Auth Adapter](https://docs.dodopayments.com/developer-resources/better-auth-adaptor)
- [Dodo Payments Better Auth package](https://www.npmjs.com/package/@dodopayments/better-auth)
- [Dodo Payments SDK](https://github.com/dodopayments/dodopayments-typescript)

© dodopayments · MIT · dodopayments/skills

Similar skills

All skills for Backend and APIs →

From the same set17

The whole set →
testing-and-go-live testing-and-go-live runs a Dodo Payments integration through test mode: cards, declines, renewals, webhooks. Then takes it to production with a launch checklist. CX Codex +1 219installs framework-adapters framework-adapters mounts official Dodo Payments adapters across Next.js, Express, Hono, Nuxt, and more. Sets up checkout, customer portal, and webhook handlers. CX Codex +1 209installs refunds-and-disputes refunds-and-disputes teaches coding agents how to issue refunds and handle dispute lifecycles with Dodo Payments. Helps wire webhooks, issue partial line-item refunds, and manage access. CX Codex +1 208installs product-catalog-management product-catalog-management manages Dodo Payments products, subscription pricing models, add-ons, and image uploads. Designed for TypeScript SDK integrations. CX Codex +1 208installs customer-management customer-management is a Claude Code skill for managing Dodo Payments customers: create records, set up portals and payment methods, manage wallets, and link app users to billing IDs. CX Codex +1 202installs discounts-and-promotions discounts-and-promotions is a Claude Code skill for configuring Dodo Payments promo codes, checking eligibility rules, and troubleshooting codes rejected at checkout. CX Codex +1 199installs localized-pricing localized-pricing guides multi-currency setups in Dodo Payments across fixed regional prices, live Adaptive Currency conversion, and purchasing power parity (PPP) tiers. CX Codex +1 198installs mobile-checkout mobile-checkout guides integration of Dodo Payments hosted checkout into React Native, Flutter, iOS, and Android using system browsers. CX Codex +1 192installs

Project sponsors

Companies that keep this analytics open