---

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

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.

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:

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

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

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

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

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:

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:

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
• Dodo Payments Better Auth package
• Dodo Payments SDK