​

@polar-sh/better-auth

A Better Auth plugin for integrating Polar payments and subscriptions into your authentication flow.

​

Features

• Automatic Customer creation on signup
• Reference System to associate purchases with organizations
• Checkout Integration
• Event Ingestion & Customer Meters for flexible Usage Based Billing
• Handle Polar Webhooks securely with signature verification
• Customer Portal

​

Installation

npm install better-auth @polar-sh/better-auth @polar-sh/sdk

npm install better-auth @polar-sh/better-auth @polar-sh/sdk

yarn add better-auth @polar-sh/better-auth @polar-sh/sdk

pnpm add better-auth @polar-sh/better-auth @polar-sh/sdk

​

Integrate Polar with BetterAuth

POLAR_ACCESS_TOKEN=...

import { betterAuth } from "better-auth";
import { polar, checkout, portal, usage, webhooks } from "@polar-sh/better-auth"; 
import { Polar } from "@polar-sh/sdk"; 

const polarClient = new Polar({ 
    accessToken: process.env.POLAR_ACCESS_TOKEN, 
    // Use 'sandbox' if you're using the Polar 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: [
        polar({ 
            client: polarClient, 
            createCustomerOnSignUp: true, 
            use: [ 
                checkout({ 
                    products: [ 
                        { 
                            productId: "123-456-789", // ID of Product from Polar 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.POLAR_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
                }) 
            ], 
        }) 
    ]
});

// ...

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

import { createAuthClient } from "better-auth/react";
import { polarClient } from "@polar-sh/better-auth"; 
import { organizationClient } from "better-auth/client/plugins"; 

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

​

Automatic Customer creation on signup

Enable the createCustomerOnSignUp Polar plugin configuration option to automatically create a new Polar Customer when a new User is added in the BetterAuth database.

All new customers are created with an associated externalId, i.e. the ID of your User in the Database. This skips any Polar to User mapping in your database.

​

Checkout Plugin

Source code

To support checkouts in your app, you would pass the checkout plugin in the use property.

The checkout plugin accepts the following configuration options:

• products (optional): An array of product mappings or a function that returns them asynchronously. Each mapping contains a productId and a slug that allows you to reference products by a friendly slug instead of their full ID.

• successUrl (optional): The relative URL where customers will be redirected after a successful checkout completion. You can use the {CHECKOUT_ID} placeholder in the URL to include the checkout session ID in the redirect.

• authenticatedUsersOnly (optional): A boolean flag that controls whether checkout sessions require user authentication. When set to true, only authenticated users can initiate checkouts and the customer information will be automatically associated with the authenticated user. When false, anonymous checkouts are allowed.

import { 
  polar,
  checkout
} from "@polar-sh/better-auth";

const auth = betterAuth({
    // ... Better Auth config
    plugins: [
        polar({
            ...
            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 URL to return to when checkout is successfully completed
                    successUrl: "/success?checkout_id={CHECKOUT_ID}", 
                    // Wheather you want to allow unauthenticated checkout sessions or not
                    authenticatedUsersOnly: true
                }) 
            ],
        })
    ]
});

await authClient.checkout({
  // Polar 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",
});

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

await authClient.checkout({
    // Any Polar 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
});

​

Usage Plugin

Source code

A plugin for Usage Based Billing that allows you to ingest events from your application and list the authenticated user’s Usage Meter.

To enable usage based billing in your app, you would pass the usage plugin in the use property.

import {
  polar, checkout, portal,
  usage
} from "@polar-sh/better-auth";

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

​

1. Event Ingestion

Polar’s Usage Based Billing builds entirely on event ingestion. Ingest events from your application, create Meters to represent that usage, and add metered prices to Products to charge for it.

The ingestion method of the usage plugin accepts the following parameters:

• event (string): The name of the event to ingest. For example, ai_usage, video_streamed or file_uploaded.

• metadata (object): A record containing key-value pairs that provide additional context about the event. Values can be strings, numbers, or booleans. This is useful for storing information that can be used to filter the events or compute the actual usage. For example, you can store the duration of the video streamed or the size of the file uploaded.

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

​

2. Customer Meters

A method to list the authenticated user’s Usage Meters (aka Customer Meters). A Customer Meter contains all the information about their consumption on your defined meters.

The meters method of the usage plugin accepts the following parameters:

• page (number): The page number for pagination (starts from 1).

• limit (number): The maximum number of meters to return per page.

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

The meters method returns the following fields in the response object:

• Customer Information: Details about the authenticated customer
• Meter Information: Configuration and settings of the usage meter
• Customer Meter Information:
  • Consumed Units: Total units consumed by the customer
  • Credited Units: Total units credited to the customer
  • Balance: The balance of the meter, i.e. the difference between credited and consumed units.

​

Webhooks Plugin

Source code

The webhooks plugin can be used to capture incoming events from your Polar organization.

To set up the Polar webhooks plugin with the BetterAuth client, follow the steps below:

POLAR_WEBHOOK_SECRET="..."

import {
  polar,
  webhooks
} from "@polar-sh/better-auth";

const auth = betterAuth({
    // ... Better Auth config
    plugins: [
        polar({
            ...
            use: [
                webhooks({ 
                    secret: process.env.POLAR_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
                }) 
            ],
        })
    ]
});

The webhooks plugin allows you to invoke handlers for all Polar webhook events:

• onPayload - Catch-all handler for any incoming Webhook event
• onCheckoutCreated - Triggered when a checkout is created
• onCheckoutUpdated - Triggered when a checkout is updated
• onOrderCreated - Triggered when an order is created
• onOrderPaid - Triggered when an order is paid
• onOrderRefunded - Triggered when an order is refunded
• onRefundCreated - Triggered when a refund is created
• onRefundUpdated - Triggered when a refund is updated
• onSubscriptionCreated - Triggered when a subscription is created
• onSubscriptionUpdated - Triggered when a subscription is updated
• onSubscriptionActive - Triggered when a subscription becomes active
• onSubscriptionCanceled - Triggered when a subscription is canceled
• onSubscriptionRevoked - Triggered when a subscription is revoked
• onSubscriptionUncanceled - Triggered when a subscription cancellation is reversed
• onProductCreated - Triggered when a product is created
• onProductUpdated - Triggered when a product is updated
• onOrganizationUpdated - Triggered when an organization is updated
• onBenefitCreated - Triggered when a benefit is created
• onBenefitUpdated - Triggered when a benefit is updated
• onBenefitGrantCreated - Triggered when a benefit grant is created
• onBenefitGrantUpdated - Triggered when a benefit grant is updated
• onBenefitGrantRevoked - Triggered when a benefit grant is revoked
• onCustomerCreated - Triggered when a customer is created
• onCustomerUpdated - Triggered when a customer is updated
• onCustomerDeleted - Triggered when a customer is deleted
• onCustomerStateChanged - Triggered when a customer is created

​

Portal Plugin

Source code

A plugin which enables customer management of their purchases, orders and subscriptions.

import {
  polar, checkout,
  portal
} from "@polar-sh/better-auth";

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

The portal plugin gives the BetterAuth Client a set of customer management methods, scoped under authClient.customer object.

​

1. Customer Portal Management

The following method will redirect the user to the Polar Customer Portal, where they can see their orders, purchases, subscriptions, benefits, etc.

await authClient.customer.portal();

​

2. Customer State

The portal plugin also adds a convenient method to retrieve the Customer State.

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

The customer state object contains:

• All the data about the customer.
• The list of their active subscriptions.
  This does not include subscriptions done by a parent organization. See the subscription list-method below for more information.

• The list of their granted benefits.
• The list of their active meters, with their current balance.

Using the customer state object, you can determine whether to provision access for the user to your service.

Learn more about the Polar Customer State in the Polar Docs.

​

3. Benefits, Orders & Subscriptions

The portal plugin adds the following 3 convenient methods for listing benefits, orders & subscriptions relevant to the authenticated user/customer.

​

3.1 Benefits

This method only lists granted benefits for the authenticated user/customer.

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

​

3.2 Orders

This method lists orders like purchases and subscription renewals for the authenticated user/customer.

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

Using the Organization ID as the referenceId you can retrieve all the subscriptions associated with that organization (instead of the user).

To figure out if a user should have access, pass the user’s organization ID to see if there is an active subscription for that organization.

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

​

3.3 Subscriptions

This method lists the subscriptions associated with authenticated user/customer.

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