BetterAuth

Payments and Checkouts made dead simple with BetterAuth

@polar-sh/better-auth

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

Features

• Automatic Customer creation on signup
• Sync customer deletion
• 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 the BetterAuth and Polar required libraries using the following command:

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

Integrate Polar with BetterAuth

1. Configure Polar Access Token

   Go to your Polar Organization Settings, create an Organization Access Token, and add it to the environment variables of your application.

   .env

   POLAR_ACCESS_TOKEN=...
   

2. Configure BetterAuth Server

   The Polar plugin comes with it’s own set of plugins to add functionality to your stack:

   • checkout - Enable seamless checkout integration
   • portal - Make it possible for your customers to manage their orders, subscriptions & benefits
   • usage - List customer meters & ingest events for Usage Based Billing
   • webhooks - Listen for relevant Polar webhooks

   BetterAuth Server with Polar Example

   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
                   }) 
               ], 
           }) 
       ]
   });
   

   Polar Plugin Configuration Options

   // ...
   
   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
         ], 
       }),
     ],
   });
   

   • client (required): Polar SDK client instance
   • createCustomerOnSignUp (optional): Automatically create a Polar customer when a user signs up
   • getCustomerCreateParams (optional): Custom function to provide additional customer creation metadata
   • use (optional): Array of Polar plugins to enable specific functionality (checkout, portal, usage, and webhooks)
3. Configure BetterAuth Client

   You will be using the BetterAuth Client to interact with the Polar functionalities.

   BetterAuth Client with Polar Example

   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.

Sync Customer deletion

To add user deletion logic with external Polar customer deletion in BetterAuth, extend the user config of your betterAuth setup with the deleteUser option and an afterDelete hook. Here’s how to integrate this alongside your Polar plugin and automatic customer creation:

Customer Deletion Example

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

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.
• theme (optional): A string that can be used to enforce the theme of the checkout page. Can be either light or dark.

1. Use Checkout Plugin

   Update the use property of the Polar plugin for BetterAuth client to have the checkout plugin.

   Checkout Plugin Example

   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
                   }) 
               ],
           })
       ]
   });
   

2. Create checkouts using BetterAuth client

   When the checkout plugin is passed, you are then able to initialize Checkout Sessions using the checkout method on the BetterAuth client. This will redirect the user to the product’s checkout link.

   The checkout method accepts the following properties:

   • products (optional): An array of Polar Product IDs.
   • slug (optional): A string that can be used as a reference to the products defined in the Checkout config
   • referenceId (optional): An identifier that will be saved in the metadata of the checkout, order & subscription object

   BetterAuth Checkout with Polar Example

   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",
   });
   

   This plugin supports the Organization plugin. If you pass the organization ID to the Checkout referenceId, you will be able to keep track of purchases made from organization members.

   BetterAuth Checkout with Polar Organization Example

   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.

Usage Plugin Example

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.

The authenticated user is automatically associated with the ingested event.

Event Ingestion with Usage Plugin Example

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.

Customer Meters with Usage Plugin Example

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:

1. Configure Webhook Endpoints in Polar

   Configure a Webhook endpoint in your Polar Organization Settings page by following this guide. Webhook endpoint is configured at /api/auth/polar/webhooks.

2. Add the Webhook Secret

   Add the obtained webhook secret to your application environment as an environment variable (to be used as process.env.POLAR_WEBHOOK_SECRET):

   .env

   POLAR_WEBHOOK_SECRET="..."
   

3. Use Webhooks Plugin in BetterAuth client

   Pass the webhooks plugin in the use property.

   Webhooks Plugin Example

   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 state changes

Portal Plugin

Source code

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

Portal Plugin Example

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.

Open Customer Portal Example

await authClient.customer.portal();

2. Customer State

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

Retrieve Customer State Example

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.

List User Benefits Example

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.

List User Orders Example

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.

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

3.3 Subscriptions

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

List User Subscriptions Example

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

This will not return subscriptions made by a parent organization to the authenticated user.