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
- Checkout Integration
- Customer Portal
- Automatic Customer creation on signup
- Event Ingestion & Customer Meters for flexible Usage Based Billing
- Handle Polar Webhooks securely with signature verification
- Reference System to associate purchases with organizations
Installation
Preparation
Go to your Polar Organization Settings, and create an Organization Access Token. Add it to your environment.
Configuring BetterAuth Server
The Polar plugin comes with a handful additional plugins which adds functionality to your stack.
- Checkout - Enables a seamless checkout integration
- Portal - Makes it possible for your customers to manage their orders, subscriptions & granted benefits
- Usage - Simple extension for listing customer meters & ingesting events for Usage Based Billing
- Webhooks - Listen for relevant Polar webhooks
Configuring BetterAuth Client
You will be using the BetterAuth Client to interact with the Polar functionalities.
Configuration Options
Required Options
client
: Polar SDK client instance
Optional Options
createCustomerOnSignUp
: Automatically create a Polar customer when a user signs upgetCustomerCreateParams
: Custom function to provide additional customer creation metadata
Customers
When createCustomerOnSignUp
is enabled, a new Polar Customer is automatically created when a new User is added in the Better-Auth Database.
All new customers are created with an associated externalId
, which is the ID of your User in the Database. This allows us to skip any Polar to User mapping in your Database.
Checkout Plugin
To support checkouts in your app, simply pass the Checkout plugin to the use-property.
When checkouts are enabled, you’re able to initialize Checkout Sessions using the checkout-method on the BetterAuth Client. This will redirect the user to the Product Checkout.
Checkouts will automatically carry the authenticated User as the customer to the checkout. Email-address will be “locked-in”.
If authenticatedUsersOnly
is false
- then it will be possible to trigger checkout sessions without any associated customer.
Organization Support
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.
Portal Plugin
A plugin which enables customer management of their purchases, orders and subscriptions.
The portal-plugin gives the BetterAuth Client a set of customer management methods, scoped under authClient.customer
.
Customer Portal Management
The following method will redirect the user to the Polar Customer Portal, where they can see orders, purchases, subscriptions, benefits, etc.
Customer State
The portal plugin also adds a convenient state-method for retrieving the general Customer State.
The customer state object contains:
- All the data about the customer.
- The list of their active subscriptions
- Note: 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.
Thus, with that single object, you have all the required information to check if you should provision access to your service or not.
You can learn more about the Polar Customer State in the Polar Docs.
Benefits, Orders & Subscriptions
The portal plugin adds 3 convenient methods for listing benefits, orders & subscriptions relevant to the authenticated user/customer.
All of these methods use the Polar CustomerPortal APIs
Benefits
This method only lists granted benefits for the authenticated user/customer.
Orders
This method lists orders like purchases and subscription renewals for the authenticated user/customer.
Subscriptions
This method lists the subscriptions associated with authenticated user/customer.
Important - Organization Support
This will not return subscriptions made by a parent organization to the authenticated user.
However, you can pass a referenceId
to this method. This will return all subscriptions associated with that referenceId instead of subscriptions associated with the user.
So in order 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.
Usage Plugin
A simple plugin for Usage Based Billing.
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.
Learn more about Usage Based Billing in the Polar Docs.
The authenticated user is automatically associated with the ingested event.
Customer Meters
A simple method for listing the authenticated user’s Usage Meters, or as we call them, Customer Meters.
Customer Meter’s contains all information about their consumtion on your defined meters.
- Customer Information
- Meter Information
- Customer Meter Information
- Consumed Units
- Credited Units
- Balance
Webhooks Plugin
The Webhooks plugin can be used to capture incoming events from your Polar organization.
Configure a Webhook endpoint in your Polar Organization Settings page. Webhook endpoint is configured at /polar/webhooks.
Add the secret to your environment.
The plugin supports handlers for all Polar webhook events:
onPayload
- Catch-all handler for any incoming Webhook eventonCheckoutCreated
- Triggered when a checkout is createdonCheckoutUpdated
- Triggered when a checkout is updatedonOrderCreated
- Triggered when an order is createdonOrderPaid
- Triggered when an order is paidonOrderRefunded
- Triggered when an order is refundedonRefundCreated
- Triggered when a refund is createdonRefundUpdated
- Triggered when a refund is updatedonSubscriptionCreated
- Triggered when a subscription is createdonSubscriptionUpdated
- Triggered when a subscription is updatedonSubscriptionActive
- Triggered when a subscription becomes activeonSubscriptionCanceled
- Triggered when a subscription is canceledonSubscriptionRevoked
- Triggered when a subscription is revokedonSubscriptionUncanceled
- Triggered when a subscription cancellation is reversedonProductCreated
- Triggered when a product is createdonProductUpdated
- Triggered when a product is updatedonOrganizationUpdated
- Triggered when an organization is updatedonBenefitCreated
- Triggered when a benefit is createdonBenefitUpdated
- Triggered when a benefit is updatedonBenefitGrantCreated
- Triggered when a benefit grant is createdonBenefitGrantUpdated
- Triggered when a benefit grant is updatedonBenefitGrantRevoked
- Triggered when a benefit grant is revokedonCustomerCreated
- Triggered when a customer is createdonCustomerUpdated
- Triggered when a customer is updatedonCustomerDeleted
- Triggered when a customer is deletedonCustomerStateChanged
- Triggered when a customer is created