Make Billing Follow Better Auth Identity

@getruba/better-auth lets Better Auth identity become the customer key used across Ruba. Enable only the surfaces your application needs:

Surface	What the plugin adds
Identity sync	Create a Ruba customer at signup and remove it after user deletion
Checkout	Start checkout for product IDs or configured slugs
Usage	Ingest events and read the signed-in customer’s meter state
Webhooks	Verify Ruba delivery and dispatch typed callbacks
Portal	Open self-service and query customer-scoped commerce records

Install the identity bridge

Add Better Auth, the Ruba plugin, and the core SDK:

npm
yarn
pnpm
bun

Terminal

npm install better-auth @getruba/better-auth @getruba/sdk

Terminal

yarn add better-auth @getruba/better-auth @getruba/sdk

Terminal

pnpm add better-auth @getruba/better-auth @getruba/sdk

Terminal

bun add better-auth @getruba/better-auth @getruba/sdk

Establish the shared customer identity

Create a server credential

Generate an Organization Access Token in Ruba settings and keep it in the server environment.

.env

RUBA_ACCESS_TOKEN=...

Compose the server plugins

Create one Ruba SDK client, pass it to ruba(), and select the capability modules under use:

checkout starts buying flows.
portal exposes customer self-service and records.
usage sends events and reads meters.
webhooks receives signed state changes.

auth.ts

import { betterAuth } from "better-auth";
import { ruba, checkout, portal, usage, webhooks } from "@getruba/better-auth"; 
import { Ruba } from "@getruba/sdk"; 

const rubaClient = new Ruba({ 
    accessToken: process.env.RUBA_ACCESS_TOKEN, 
    // Use 'sandbox' if you're using the Ruba Sandbox environment
    // Remember that access tokens, products, etc. are completely separated between environments.
    // Access tokens obtained in Production are for instance not usable in the Sandbox environment.
    server: 'sandbox'
}); 

const auth = betterAuth({
    // ... Better Auth config
    plugins: [
        ruba({ 
            client: rubaClient, 
            createCustomerOnSignUp: true, 
            use: [ 
                checkout({ 
                    products: [ 
                        { 
                            productId: "123-456-789", // ID of Product from Ruba Dashboard
                            slug: "pro" // Custom slug for easy reference in Checkout URL, e.g. /checkout/pro
                        } 
                    ], 
                    successUrl: "/success?checkout_id={CHECKOUT_ID}", 
                    authenticatedUsersOnly: true
                }), 
                portal(), 
                usage(), 
                webhooks({ 
                    secret: process.env.RUBA_WEBHOOK_SECRET, 
                    onCustomerStateChanged: (payload) => // Triggered when anything regarding a customer changes
                    onOrderPaid: (payload) => // Triggered when an order was paid (purchase, subscription renewal, etc.)
                    ...  // Over 25 granular webhook handlers
                    onPayload: (payload) => // Catch-all for all events
                }) 
            ], 
        }) 
    ]
});

Root configuration

// ...

const auth = betterAuth({
  // ... Better Auth config
  plugins: [
    ruba({
      client: rubaClient, 
      createCustomerOnSignUp: true, 
      getCustomerCreateParams: ({ user }, request) => ({ 
        metadata: { 
          myCustomProperty: 123, 
        }, 
      }), 
      use: [ 
        // This is where you add Ruba plugins
      ], 
    }),
  ],
});

Option	Meaning
`client`	Required Ruba SDK instance
`createCustomerOnSignUp`	Creates the matching customer during signup when enabled
`getCustomerCreateParams`	Adds metadata or other create-customer fields
`use`	Capability modules enabled for this Better Auth instance

Expose typed client methods

Add rubaClient() to the browser-facing Better Auth client. Billing authority still remains in the server configuration.

auth-client.ts

import { createAuthClient } from "better-auth/react";
import { rubaClient } from "@getruba/better-auth/client"; 
import { organizationClient } from "better-auth/client/plugins"; 

// All Ruba plugins, etc. should be attached to BetterAuth server
export const authClient = createAuthClient({ 
  plugins: [rubaClient()], 
}); 

Keep user and customer lifecycle aligned

Enable createCustomerOnSignUp to create a customer with the Better Auth user ID stored as externalId. That stable key removes the need for a separate mapping table. For deletion, enable Better Auth’s deleteUser flow and remove the external Ruba customer from afterDelete:

Customer Deletion Example

const auth = betterAuth({
  user: {
    deleteUser: {
      enabled: true, 
      afterDelete: async (user, request) => {
        await ruba.customers.deleteExternal({
          externalId: user.id, 
        }); 
      }, 
    }, 
  }, 
});

Start checkout from an authenticated session

Source code Add checkout under use. Its configuration separates catalog mapping from browser behavior:

Option	Effect
`products`	Maps friendly slugs to product IDs, either statically or asynchronously
`successUrl`	Relative or absolute completion target; `{CHECKOUT_ID}` inserts the session ID
`returnUrl`	Displays a route back to your application
`authenticatedUsersOnly`	Requires a session and binds its customer when true; permits anonymous checkout when false
`theme`	Forces `light` or `dark`

Place the configured checkout() module in the root Ruba plugin’s use array.

Checkout Plugin Example

import {
  ruba,
  checkout
} from "@getruba/better-auth";

const auth = betterAuth({
    // ... Better Auth config
    plugins: [
        ruba({
            ...
            use: [
                checkout({ 
                    // Optional field - will make it possible to pass a slug to checkout instead of Product ID
                    products: [ { productId: "123-456-789", slug: "pro" } ], 
                    // Relative path or absolute URL to redirect to when checkout is successfully completed
                    successUrl: "/success?checkout_id={CHECKOUT_ID}", 
                    // Whether you want to allow unauthenticated checkout sessions or not
                    authenticatedUsersOnly: true, 
                    // An optional URL which renders a back-button in the Checkout
                    returnUrl: "https://myapp.com"
                }) 
            ],
        })
    ]
});

Invoke it from the client

Call authClient.checkout() with product IDs or one configured slug. referenceId is copied into checkout, order, and subscription metadata.

BetterAuth Checkout with Ruba Example

await authClient.checkout({
  // Ruba Product IDs
  products: ["e651f46d-ac20-4f26-b769-ad088b123df2"], 
  // OR
  // if "products" in passed in the checkout plugin's config, you may pass the slug
  // slug: "pro",
});

With Better Auth Organizations, use the organization ID as referenceId to associate the resulting commerce records with that team rather than only the individual session.

BetterAuth Checkout with Ruba Organization Example

const organizationId = (await authClient.organization.list())?.data?.[0]?.id,

await authClient.checkout({
    // Any Ruba Product ID can be passed here
    products: ["e651f46d-ac20-4f26-b769-ad088b123df2"],
    // Or, if you setup "products" in the Checkout Config, you can pass the slug
    slug: 'pro',
    // Reference ID will be saved as `referenceId` in the metadata of the checkout, order & subscription object
    referenceId: organizationId
});

Connect authenticated usage to meters

Source code The usage module adds event ingestion and customer-meter reads. Register it in use after the application’s usage model exists.

Usage Plugin Example

import {
  ruba, checkout, portal,
  usage
} from "@getruba/better-auth";

const auth = betterAuth({
    // ... Better Auth config
    plugins: [
        ruba({
            ...
            use: [
                checkout(...),
                portal(),
                usage() 
            ],
        })
    ]
});

Record authoritative activity

Billable events belong on the server route that performs the work. A browser can forge or skip its own usage claims.

With signup sync enabled, session.user.id is already the customer’s externalId. Reuse the configured SDK client inside the protected work route:

app/api/ai/video/route.ts (Next.js App Router)

import { auth } from "@/lib/auth";
import { rubaClient } from "@/lib/ruba";
import { headers } from "next/headers";

export async function POST(request: Request) {
  const session = await auth.api.getSession({ headers: await headers() });

  if (!session) {
    return new Response("Unauthorized", { status: 401 });
  }

  // Run the metered work on the server
  const { video, tokensConsumed } = await makeNewVideo(request);

  // Ingest the resulting usage against the authenticated user
  await rubaClient.events.ingest({
    events: [
      {
        name: "ai-video",
        externalCustomerId: session.user.id,
        metadata: {
          tokensConsumed,
        },
      },
    ],
  });

  return Response.json({ video });
}

Each event needs a name, the Better Auth user ID as externalCustomerId, and optional string, number, or boolean metadata used by filters and aggregations.

Non-authoritative browser signals

authClient.usage.ingestion(...) sends through the Better Auth server and attaches the signed-in user automatically:

auth-client.ts

const { data: ingested } = await authClient.usage.ingestion({
  event: "file-uploads",
  metadata: {
    uploadedFiles: 12,
  },
});

Treat this endpoint like analytics input. The user controls its payload, so it must not determine a bill or protected quota.

Read the user’s meter position

authClient.usage.meters() lists Customer Meters for the active session. page starts at 1 and limit caps each page.

Customer Meters with Usage Plugin Example

const { data: customerMeters } = await authClient.usage.meters.list({
  query: {
    page: 1,
    limit: 10,
  },
});

The response combines customer identity, meter definition, consumed units, credited units, and the remaining balance between them.

Bring asynchronous changes into Better Auth

Source code The webhook module owns /api/auth/ruba/webhooks, verifies delivery, and routes events to your callbacks.

In Ruba webhook settings, create an endpoint ending in /api/auth/ruba/webhooks.

Store its secret

Save the issued value as RUBA_WEBHOOK_SECRET in the server environment.

.env

RUBA_WEBHOOK_SECRET="..."

Bind callbacks

Add webhooks() under use, pass the secret, and implement the events your application consumes.

Webhooks Plugin Example

import {
  ruba,
  webhooks
} from "@getruba/better-auth";

const auth = betterAuth({
    // ... Better Auth config
    plugins: [
        ruba({
            ...
            use: [
                webhooks({ 
                    secret: process.env.RUBA_WEBHOOK_SECRET, 
                    onCustomerStateChanged: (payload) => // Triggered when anything regarding a customer changes
                    onOrderPaid: (payload) => // Triggered when an order was paid (purchase, subscription renewal, etc.)
                    ...  // Over 25 granular webhook handlers
                    onPayload: (payload) => // Catch-all for all events
                }) 
            ],
        })
    ]
});

Choose callback granularity

Use onPayload as a catch-all or register callbacks around the domain your application owns:

Domain	Available callbacks
Checkout	`onCheckoutCreated`, `onCheckoutUpdated`
Orders and refunds	`onOrderCreated`, `onOrderPaid`, `onOrderRefunded`, `onRefundCreated`, `onRefundUpdated`
Subscriptions	`onSubscriptionCreated`, `onSubscriptionUpdated`, `onSubscriptionActive`, `onSubscriptionCanceled`, `onSubscriptionRevoked`, `onSubscriptionUncanceled`
Catalog	`onProductCreated`, `onProductUpdated`, `onBenefitCreated`, `onBenefitUpdated`
Entitlements	`onBenefitGrantCreated`, `onBenefitGrantUpdated`, `onBenefitGrantRevoked`
Customers	`onCustomerCreated`, `onCustomerUpdated`, `onCustomerDeleted`, `onCustomerStateChanged`
Organization	`onOrganizationUpdated`

Query commerce through the signed-in customer

Source code

Portal module

import {
  ruba, checkout,
  portal
} from "@getruba/better-auth";

const auth = betterAuth({
    // ... Better Auth config
    plugins: [
        ruba({
            ...
            use: [
                checkout(...),
                portal({
                  returnUrl: "https://myapp.com", // An optional URL which renders a back-button in the Customer Portal
                }) 
            ],
        })
    ]
});

The portal module adds customer-scoped methods under authClient.customer.

Open self-service

authClient.customer.portal() redirects the user to Ruba’s portal for orders, subscriptions, and benefits.

Open Customer Portal Example

await authClient.customer.portal();

Fetch one access snapshot

authClient.customer.state() returns identity, direct active subscriptions, granted benefits, and active meters with their balances.

Retrieve Customer State Example

const { data: customerState } = await authClient.customer.state();

Use that snapshot for access decisions. It excludes subscriptions purchased by a parent organization; query subscriptions with the organization reference for that case. Understand Customer State →

List individual record types

Granted benefits

The benefits method returns grants belonging to the active customer.

List User Benefits Example

const { data: benefits } = await authClient.customer.benefits.list({
  query: {
    page: 1,
    limit: 10,
  },
});

Orders

The orders method returns that customer’s purchases and renewal records.

List User Orders Example

const { data: orders } = await authClient.customer.orders.list({
  query: {
    page: 1,
    limit: 10,
    productBillingType: "one_time", // or 'recurring'
  },
});

When a purchase belongs to a Better Auth Organization, pass its ID as referenceId and use that reference to find the organization’s subscriptions.

List Organization Subscriptions Example

const organizationId = (await authClient.organization.list())?.data?.[0]?.id,

const { data: subscriptions } = await authClient.customer.orders.list({
    query: {
	    page: 1,
		limit: 10,
		active: true,
        referenceId: organizationId
    },
});

const userShouldHaveAccess = subscriptions.some(
    sub => // Your logic to check subscription product or whatever.
)

Subscriptions

The subscriptions method returns relationships tied directly to the active customer.

List User Subscriptions Example

const { data: subscriptions } = await authClient.customer.subscriptions.list({
  query: {
    page: 1,
    limit: 10,
    active: true,
  },
});

Direct-customer listing does not include subscriptions purchased through a parent organization.

Launch Path

Shape the Offer

Run the Revenue Model

Deliver Customer Access

Build the Integration

Operate the Business

Implementation Playbooks

Make Billing Follow Better Auth Identity

Install the identity bridge

Establish the shared customer identity

Root configuration

Keep user and customer lifecycle aligned

Start checkout from an authenticated session

Connect authenticated usage to meters

Record authoritative activity

Non-authoritative browser signals

Read the user’s meter position

Bring asynchronous changes into Better Auth

Choose callback granularity

Query commerce through the signed-in customer

Open self-service

Fetch one access snapshot

List individual record types

Granted benefits

Orders

Subscriptions

​Install the identity bridge

​Establish the shared customer identity

​Root configuration

​Keep user and customer lifecycle aligned

​Start checkout from an authenticated session

​Connect authenticated usage to meters

​Record authoritative activity

​Non-authoritative browser signals

​Read the user’s meter position

​Bring asynchronous changes into Better Auth

​Choose callback granularity

​Query commerce through the signed-in customer

​Open self-service

​Fetch one access snapshot

​List individual record types

​Granted benefits

​Orders

​Subscriptions

Install the identity bridge

Establish the shared customer identity

Root configuration

Keep user and customer lifecycle aligned

Start checkout from an authenticated session

Connect authenticated usage to meters

Record authoritative activity

Non-authoritative browser signals

Read the user’s meter position

Bring asynchronous changes into Better Auth

Choose callback granularity

Query commerce through the signed-in customer

Open self-service

Fetch one access snapshot

List individual record types

Granted benefits

Orders

Subscriptions