@foreach ($user->orders as $order)
| {{ $order->ordered_at->toFormattedDateString() }} |
{{ $order->polar_id }} |
{{ $order->amount }} |
{{ $order->tax_amount }} |
{{ $order->refunded_amount }} |
{{ $order->refunded_tax_amount }} |
{{ $order->currency }} |
@endforeach
```
#### Check order status
You can check the status of an order by using the `status` attribute:
```php
$order->status;
```
Or you can use some of the helper methods offers by the `Order` model:
```php
$order->paid();
```
Aside from that, you can run two other checks: refunded, and partially refunded. If the order is refunded, you can utilize the refunded\_at timestamp:
```blade
@if ($order->refunded())
Order {{ $order->polar_id }} was refunded on {{ $order->refunded_at->toFormattedDateString() }}
@endif
```
You may also see if an order was for a certain product:
```php
if ($order->hasProduct('product_id_123')) {
// ...
}
```
Or for an specific price:
```php
if ($order->hasPrice('price_id_123')) {
// ...
}
```
Furthermore, you can check if a consumer has purchased a specific product:
```php
if ($user->hasPurchasedProduct('product_id_123')) {
// ...
}
```
Or for an specific price:
```php
if ($user->hasPurchasedPrice('price_id_123')) {
// ...
}
```
### Subscriptions
#### Creating Subscriptions
Starting a subscription is simple. For this, we require our product's variant id. Copy the product id and start a new subscription checkout using your billable model:
```php
use Illuminate\Http\Request;
Route::get('/subscribe', function (Request $request) {
return $request->user()->subscribe('product_id_123');
});
```
When a customer completes their checkout, the incoming `SubscriptionCreated` event webhook connects it to your billable model in the database. You may then get the subscription from your billable model:
```php
$subscription = $user->subscription();
```
#### Checking Subscription Status
Once a consumer has subscribed to your services, you can use a variety of methods to check on the status of their subscription. The most basic example is to check if a customer has a valid subscription.
```php
if ($user->subscribed()) {
// ...
}
```
You can utilize this in a variety of locations in your app, such as middleware, rules, and so on, to provide services. To determine whether an individual subscription is valid, you can use the `valid` method:
```php
if ($user->subscription()->valid()) {
// ...
}
```
This method, like the subscribed method, returns true if your membership is active, on trial, past due, or cancelled during its grace period.
You may also check if a subscription is for a certain product:
```php
if ($user->subscription()->hasProduct('product_id_123')) {
// ...
}
```
Or for a certain price:
```php
if ($user->subscription()->hasPrice('price_id_123')) {
// ...
}
```
If you wish to check if a subscription is on a specific price while being valid, you can use:
```php
if ($user->subscribedToPrice('price_id_123')) {
// ...
}
```
Alternatively, if you use different [subscription types](#multiple-subscriptions), you can pass a type as an additional parameter:
```php
if ($user->subscribed('swimming')) {
// ...
}
if ($user->subscribedToPrice('price_id_123', 'swimming')) {
// ...
}
```
#### Cancelled Status
To see if a user has cancelled their subscription, you can use the cancelled method:
```php
if ($user->subscription()->cancelled()) {
// ...
}
```
When they are in their grace period, you can utilize the `onGracePeriod` check.
```php
if ($user->subscription()->onGracePeriod()) {
// ...
}
```
#### Past Due Status
If a recurring payment fails, the subscription will become past due. This indicates that the subscription is still valid, but your customer's payments will be retried in two weeks.
```php
if ($user->subscription()->pastDue()) {
// ...
}
```
#### Subscription Scopes
There are several subscription scopes available for querying subscriptions in specific states:
```php
// Get all active subscriptions...
$subscriptions = Subscription::query()->active()->get();
// Get all of the cancelled subscriptions for a specific user...
$subscriptions = $user->subscriptions()->cancelled()->get();
```
Here's all available scopes:
```php
Subscription::query()->incomplete();
Subscription::query()->incompleteExpired();
Subscription::query()->onTrial();
Subscription::query()->active();
Subscription::query()->pastDue();
Subscription::query()->unpaid();
Subscription::query()->cancelled();
```
#### Changing Plans
When a consumer is on a monthly plan, they may desire to upgrade to a better plan, alter their payments to an annual plan, or drop to a lower-cost plan. In these cases, you can allow them to swap plans by giving a different product id to the `swap` method:
```php
use App\Models\User;
$user = User::find(1);
$user->subscription()->swap('product_id_123');
```
This will change the customer's subscription plan, however billing will not occur until the next payment cycle. If you want to immediately invoice the customer, you can use the `swapAndInvoice` method instead.
```php
$user = User::find(1);
$user->subscription()->swapAndInvoice('product_id_123');
```
#### Multiple Subscriptions
In certain situations, you may wish to allow your consumer to subscribe to numerous subscription kinds. For example, a gym may provide a swimming and weight lifting subscription. You can let your customers subscribe to one or both.
To handle the various subscriptions, you can offer a type of subscription as the second argument when creating a new one:
```php
$user = User::find(1);
$checkout = $user->subscribe('product_id_123', 'swimming');
```
You can now always refer to this specific subscription type by passing the type argument when getting it:
```php
$user = User::find(1);
// Retrieve the swimming subscription type...
$subscription = $user->subscription('swimming');
// Swap plans for the gym subscription type...
$user->subscription('gym')->swap('product_id_123');
// Cancel the swimming subscription...
$user->subscription('swimming')->cancel();
```
#### Cancelling Subscriptions
To cancel a subscription, call the `cancel` method.
```php
$user = User::find(1);
$user->subscription()->cancel();
```
This will cause your subscription to be cancelled. If you cancel your subscription in the middle of the cycle, it will enter a grace period, and the ends\_at column will be updated. The customer will continue to have access to the services offered for the duration of the period. You may check the grace period by calling the `onGracePeriod` method:
```php
if ($user->subscription()->onGracePeriod()) {
// ...
}
```
Polar does not offer immediate cancellation. To resume a subscription while it is still in its grace period, use the resume method.
```php
$user->subscription()->resume();
```
When a cancelled subscription approaches the end of its grace period, it becomes expired and cannot be resumed.
#### Subscription Trials
> \[!NOTE]
> Coming soon.
### Handling Webhooks
Polar can send webhooks to your app, allowing you to react. By default, this package handles the majority of the work for you. If you have properly configured webhooks, it will listen for incoming events and update your database accordingly. We recommend activating all event kinds so you may easily upgrade in the future.
#### Webhook Events
* `Danestves\LaravelPolar\Events\BenefitGrantCreated`
* `Danestves\LaravelPolar\Events\BenefitGrantUpdated`
* `Danestves\LaravelPolar\Events\BenefitGrantRevoked`
* `Danestves\LaravelPolar\Events\OrderCreated`
* `Danestves\LaravelPolar\Events\OrderRefunded`
* `Danestves\LaravelPolar\Events\SubscriptionActive`
* `Danestves\LaravelPolar\Events\SubscriptionCanceled`
* `Danestves\LaravelPolar\Events\SubscriptionCreated`
* `Danestves\LaravelPolar\Events\SubscriptionRevoked`
* `Danestves\LaravelPolar\Events\SubscriptionUpdated`
Each of these events has a billable `$model` object and an event `$payload`. The subscription events also include the `$subscription` object. These can be accessed via the public properties.
If you wish to respond to these events, you must establish listeners for them. For example, you may wish to react when a subscription is updated.
```php
payload['type'] === 'subscription.updated') {
// Handle the incoming event...
}
}
}
```
The [Polar documentation](https://docs.polar.sh/integrate/webhooks/events) includes an example payload.
Laravel v11 and up will automatically discover the listener. If you're using Laravel v10 or lower, you should configure it in your app's `EventServiceProvider`:
```php
[
PolarEventListener::class,
],
];
}
```
## Roadmap
* [ ] Add support for trials
Polar itself doesn't support trials, but we can manage them by ourselves.
## Testing
```bash
composer test
```
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
## Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
## Security Vulnerabilities
Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
## Credits
* [laravel/cashier (Stripe)](https://github.com/laravel/cashier-stripe)
* [laravel/cashier (Paddle)](https://github.com/laravel/cashier-paddle)
* [lemonsqueezy/laravel](https://github.com/lmsqueezy/laravel)
* [All Contributors](../../contributors)
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
# NextJS
Source: https://docs.polar.sh/integrate/sdk/adapters/nextjs
Payments and Checkouts made dead simple with NextJS
```bash
pnpm install @polar-sh/nextjs zod
```
## Checkout
Create a Checkout handler which takes care of redirections.
```typescript
// checkout/route.ts
import { Checkout } from "@polar-sh/nextjs";
export const GET = Checkout({
accessToken: process.env.POLAR_ACCESS_TOKEN,
successUrl: process.env.SUCCESS_URL,
server: "sandbox", // Use sandbox if you're testing Polar - omit the parameter or pass 'production' otherwise
});
```
### Query Params
Pass query params to this route.
* products `?products=123`
* customerId (optional) `?products=123&customerId=xxx`
* customerExternalId (optional) `?products=123&customerExternalId=xxx`
* customerEmail (optional) `?products=123&customerEmail=janedoe@gmail.com`
* customerName (optional) `?products=123&customerName=Jane`
* metadata (optional) `URL-Encoded JSON string`
## Customer Portal
Create a customer portal where your customer can view orders and subscriptions.
```typescript
// portal/route.ts
import { CustomerPortal } from "@polar-sh/nextjs";
export const GET = CustomerPortal({
accessToken: process.env.POLAR_ACCESS_TOKEN,
getCustomerId: (req: NextRequest) => "", // Function to resolve a Polar Customer ID
server: "sandbox", // Use sandbox if you're testing Polar - omit the parameter or pass 'production' otherwise
});
```
## Webhooks
A simple utility which resolves incoming webhook payloads by signing the webhook secret properly.
```typescript
// api/webhook/polar/route.ts
import { Webhooks } from "@polar-sh/nextjs";
export const POST = Webhooks({
webhookSecret: process.env.POLAR_WEBHOOK_SECRET!,
onPayload: async (payload) => {
// Handle the payload
// No need to return an acknowledge response
},
});
```
### Payload Handlers
The Webhook handler also supports granular handlers for easy integration.
* onCheckoutCreated: (payload) =>
* onCheckoutUpdated: (payload) =>
* onOrderCreated: (payload) =>
* onSubscriptionCreated: (payload) =>
* onSubscriptionUpdated: (payload) =>
* onSubscriptionActive: (payload) =>
* onSubscriptionCanceled: (payload) =>
* onSubscriptionRevoked: (payload) =>
* onProductCreated: (payload) =>
* onProductUpdated: (payload) =>
* onOrganizationUpdated: (payload) =>
* onBenefitCreated: (payload) =>
* onBenefitUpdated: (payload) =>
* onBenefitGrantCreated: (payload) =>
* onBenefitGrantUpdated: (payload) =>
* onBenefitGrantRevoked: (payload) =>
* onCustomerCreated: (payload) =>
* onCustomerUpdated: (payload) =>
* onCustomerDeleted: (payload) =>
* onCustomerStateChanged: (payload) =>
# Nuxt
Source: https://docs.polar.sh/integrate/sdk/adapters/nuxt
Payments and Checkouts made dead simple with Nuxt
## Installation
Choose your preferred package manager to install the module:
`pnpm add @polar-sh/nuxt`
### Register the module
Add the module to your `nuxt.config.ts`:
```typescript
export default defineNuxtConfig({
modules: ["@polar-sh/nuxt"],
});
```
## Checkout
Create a Checkout handler which takes care of redirections.
```typescript
// server/routes/api/checkout.post.ts
export default defineEventHandler((event) => {
const {
private: { polarAccessToken, polarCheckoutSuccessUrl, polarServer },
} = useRuntimeConfig();
const checkoutHandler = Checkout({
accessToken: polarAccessToken,
successUrl: polarCheckoutSuccessUrl,
server: polarServer as "sandbox" | "production",
});
return checkoutHandler(event);
});
```
### Query Params
Pass query params to this route.
* products `?products=123`
* customerId (optional) `?products=123&customerId=xxx`
* customerExternalId (optional) `?products=123&customerExternalId=xxx`
* customerEmail (optional) `?products=123&customerEmail=janedoe@gmail.com`
* customerName (optional) `?products=123&customerName=Jane`
* metadata (optional) `URL-Encoded JSON string`
## Customer Portal
Create a customer portal where your customer can view orders and subscriptions.
```typescript
// server/routes/api/portal.get.ts
export default defineEventHandler((event) => {
const {
private: { polarAccessToken, polarCheckoutSuccessUrl, polarServer },
} = useRuntimeConfig();
const customerPortalHandler = CustomerPortal({
accessToken: polarAccessToken,
server: polarServer as "sandbox" | "production",
getCustomerId: (event) => {
// Use your own logic to get the customer ID - from a database, session, etc.
return Promise.resolve("9d89909b-216d-475e-8005-053dba7cff07");
},
});
return customerPortalHandler(event);
});
```
## Webhooks
A simple utility which resolves incoming webhook payloads by signing the webhook secret properly.
```typescript
// server/routes/webhook/polar.post.ts
export default defineEventHandler((event) => {
const {
private: { polarWebhookSecret },
} = useRuntimeConfig();
const webhooksHandler = Webhooks({
webhookSecret: polarWebhookSecret,
onPayload: async (payload) => {
// Handle the payload
// No need to return an acknowledge response
},
});
return webhooksHandler(event);
});
```
### Payload Handlers
The Webhook handler also supports granular handlers for easy integration.
* onCheckoutCreated: (payload) =>
* onCheckoutUpdated: (payload) =>
* onOrderCreated: (payload) =>
* onSubscriptionCreated: (payload) =>
* onSubscriptionUpdated: (payload) =>
* onSubscriptionActive: (payload) =>
* onSubscriptionCanceled: (payload) =>
* onSubscriptionRevoked: (payload) =>
* onProductCreated: (payload) =>
* onProductUpdated: (payload) =>
* onOrganizationUpdated: (payload) =>
* onBenefitCreated: (payload) =>
* onBenefitUpdated: (payload) =>
* onBenefitGrantCreated: (payload) =>
* onBenefitGrantUpdated: (payload) =>
* onBenefitGrantRevoked: (payload) =>
* onCustomerCreated: (payload) =>
* onCustomerUpdated: (payload) =>
* onCustomerDeleted: (payload) =>
* onCustomerStateChanged: (payload) =>
# Remix
Source: https://docs.polar.sh/integrate/sdk/adapters/remix
Payments and Checkouts made dead simple with Remix
```bash
pnpm install @polar-sh/remix zod
```
## Checkout
Create a Checkout handler which takes care of redirections.
```typescript
import { Checkout } from "@polar-sh/remix";
export const loader = Checkout({
accessToken: "xxx", // Or set an environment variable to POLAR_ACCESS_TOKEN
successUrl: process.env.SUCCESS_URL,
server: "sandbox", // Use sandbox if you're testing Polar - omit the parameter or pass 'production' otherwise
});
```
### Query Params
Pass query params to this route.
* products `?products=123`
* customerId (optional) `?products=123&customerId=xxx`
* customerExternalId (optional) `?products=123&customerExternalId=xxx`
* customerEmail (optional) `?products=123&customerEmail=janedoe@gmail.com`
* customerName (optional) `?products=123&customerName=Jane`
* metadata (optional) `URL-Encoded JSON string`
## Customer Portal
Create a customer portal where your customer can view orders and subscriptions.
```typescript
import { CustomerPortal } from "@polar-sh/remix";
export const loader = CustomerPortal({
accessToken: "xxx", // Or set an environment variable to POLAR_ACCESS_TOKEN
getCustomerId: (event) => "", // Function to resolve a Polar Customer ID
server: "sandbox", // Use sandbox if you're testing Polar - omit the parameter or pass 'production' otherwise
});
```
## Webhooks
A simple utility which resolves incoming webhook payloads by signing the webhook secret properly.
```typescript
import { Webhooks } from "@polar-sh/remix";
export const action = Webhooks({
webhookSecret: process.env.POLAR_WEBHOOK_SECRET!,
onPayload: async (payload) => /** Handle payload */,
})
```
### Payload Handlers
The Webhook handler also supports granular handlers for easy integration.
* onCheckoutCreated: (payload) =>
* onCheckoutUpdated: (payload) =>
* onOrderCreated: (payload) =>
* onSubscriptionCreated: (payload) =>
* onSubscriptionUpdated: (payload) =>
* onSubscriptionActive: (payload) =>
* onSubscriptionCanceled: (payload) =>
* onSubscriptionRevoked: (payload) =>
* onProductCreated: (payload) =>
* onProductUpdated: (payload) =>
* onOrganizationUpdated: (payload) =>
* onBenefitCreated: (payload) =>
* onBenefitUpdated: (payload) =>
* onBenefitGrantCreated: (payload) =>
* onBenefitGrantUpdated: (payload) =>
* onBenefitGrantRevoked: (payload) =>
* onCustomerCreated: (payload) =>
* onCustomerUpdated: (payload) =>
* onCustomerDeleted: (payload) =>
* onCustomerStateChanged: (payload) =>
# Sveltekit
Source: https://docs.polar.sh/integrate/sdk/adapters/sveltekit
Payments and Checkouts made dead simple with Sveltekit
```bash
pnpm install @polar-sh/sveltekit zod
```
## Checkout
Create a Checkout handler which takes care of redirections.
```typescript
// /api/checkout/+server.ts
import { Checkout } from "@polar-sh/sveltekit";
export const GET = Checkout({
accessToken: process.env.POLAR_ACCESS_TOKEN,
successUrl: process.env.SUCCESS_URL,
server: "sandbox", // Use sandbox if you're testing Polar - omit the parameter or pass 'production' otherwise
});
```
### Query Params
Pass query params to this route.
* products `?products=123`
* customerId (optional) `?products=123&customerId=xxx`
* customerExternalId (optional) `?products=123&customerExternalId=xxx`
* customerEmail (optional) `?products=123&customerEmail=janedoe@gmail.com`
* customerName (optional) `?products=123&customerName=Jane`
* metadata (optional) `URL-Encoded JSON string`
## Customer Portal
Create a customer portal where your customer can view orders and subscriptions.
```typescript
// /api/portal/+server.ts
import { CustomerPortal } from "@polar-sh/sveltekit";
export const GET = CustomerPortal({
accessToken: process.env.POLAR_ACCESS_TOKEN,
getCustomerId: (event) => "", // Function to resolve a Polar Customer ID
server: "sandbox", // Use sandbox if you're testing Polar - omit the parameter or pass 'production' otherwise
});
```
## Webhooks
A simple utility which resolves incoming webhook payloads by signing the webhook secret properly.
```typescript
// api/webhook/polar/route.ts
import { Webhooks } from "@polar-sh/sveltekit";
export const POST = Webhooks({
webhookSecret: process.env.POLAR_WEBHOOK_SECRET!,
onPayload: async (payload) => {
// Handle the payload
},
});
```
### Payload Handlers
The Webhook handler also supports granular handlers for easy integration.
* onCheckoutCreated: (payload) =>
* onCheckoutUpdated: (payload) =>
* onOrderCreated: (payload) =>
* onSubscriptionCreated: (payload) =>
* onSubscriptionUpdated: (payload) =>
* onSubscriptionActive: (payload) =>
* onSubscriptionCanceled: (payload) =>
* onSubscriptionRevoked: (payload) =>
* onProductCreated: (payload) =>
* onProductUpdated: (payload) =>
* onOrganizationUpdated: (payload) =>
* onBenefitCreated: (payload) =>
* onBenefitUpdated: (payload) =>
* onBenefitGrantCreated: (payload) =>
* onBenefitGrantUpdated: (payload) =>
* onBenefitGrantRevoked: (payload) =>
* onCustomerCreated: (payload) =>
* onCustomerUpdated: (payload) =>
* onCustomerDeleted: (payload) =>
* onCustomerStateChanged: (payload) =>
# TanStack Start
Source: https://docs.polar.sh/integrate/sdk/adapters/tanstack-start
Payments and Checkouts made dead simple with TanStack Start
`pnpm install @polar-sh/tanstack-start zod`
## Checkout
Create a Checkout handler which takes care of redirections.
```typescript
// routes/api/checkout.ts
import { Checkout } from "@polar-sh/tanstack-start";
import { createAPIFileRoute } from "@tanstack/react-start/api";
export const APIRoute = createAPIFileRoute("/api/checkout")({
GET: Checkout({
accessToken: process.env.POLAR_ACCESS_TOKEN,
successUrl: process.env.SUCCESS_URL,
server: "sandbox", // Use sandbox if you're testing Polar - omit the parameter or pass 'production' otherwise
}),
});
```
### Query Params
Pass query params to this route.
* products `?products=123`
* customerId (optional) `?products=123&customerId=xxx`
* customerExternalId (optional) `?products=123&customerExternalId=xxx`
* customerEmail (optional) `?products=123&customerEmail=janedoe@gmail.com`
* customerName (optional) `?products=123&customerName=Jane`
* metadata (optional) `URL-Encoded JSON string`
## Customer Portal
Create a customer portal where your customer can view orders and subscriptions.
```typescript
// routes/api/portal.ts
import { CustomerPortal } from "@polar-sh/tanstack-start";
import { createAPIFileRoute } from "@tanstack/react-start/api";
import { getSupabaseServerClient } from "~/servers/supabase-server";
export const APIRoute = createAPIFileRoute("/api/portal")({
GET: CustomerPortal({
accessToken: process.env.POLAR_ACCESS_TOKEN,
getCustomerId: async (request: Request) => "", // Function to resolve a Polar Customer ID
server: "sandbox", // Use sandbox if you're testing Polar - omit the parameter or pass 'production' otherwise
}),
});
```
## Webhooks
A simple utility which resolves incoming webhook payloads by signing the webhook secret properly.
```typescript
// api/webhook/polar.ts
import { Webhooks } from "@polar-sh/tanstack-start";
import { createAPIFileRoute } from "@tanstack/react-start/api";
export const APIRoute = createAPIFileRoute("/api/webhook/polar")({
POST: Webhooks({
webhookSecret: process.env.POLAR_WEBHOOK_SECRET!,
onPayload: async (payload) => {
// Handle the payload
// No need to return an acknowledge response
},
}),
});
```
#### Payload Handlers
The Webhook handler also supports granular handlers for easy integration.
* onCheckoutCreated: (payload) =>
* onCheckoutUpdated: (payload) =>
* onOrderCreated: (payload) =>
* onOrderUpdated: (payload) =>
* onOrderPaid: (payload) =>
* onSubscriptionCreated: (payload) =>
* onSubscriptionUpdated: (payload) =>
* onSubscriptionActive: (payload) =>
* onSubscriptionCanceled: (payload) =>
* onSubscriptionRevoked: (payload) =>
* onProductCreated: (payload) =>
* onProductUpdated: (payload) =>
* onOrganizationUpdated: (payload) =>
* onBenefitCreated: (payload) =>
* onBenefitUpdated: (payload) =>
* onBenefitGrantCreated: (payload) =>
* onBenefitGrantUpdated: (payload) =>
* onBenefitGrantRevoked: (payload) =>
* onCustomerCreated: (payload) =>
* onCustomerUpdated: (payload) =>
* onCustomerDeleted: (payload) =>
* onCustomerStateChanged: (payload) =>
# Go SDK
Source: https://docs.polar.sh/integrate/sdk/golang
Documentation coming soon.
# PHP SDK
Source: https://docs.polar.sh/integrate/sdk/php
Documentation coming soon.
# Python SDK
Source: https://docs.polar.sh/integrate/sdk/python
Fully type-hinted and allows both synchronous and asynchronous usage, thanks to [HTTPX](https://www.python-httpx.org/).
Under the hood, schemas are validated by [Pydantic](https://docs.pydantic.dev/latest/).
### Quickstart
```bash
pip install polar-sdk
```
```python
# Synchronous Example
from polar_sdk import Polar
s = Polar(
access_token="
The payment attempts information is also available on each order.
Besides, we've also added new analytics around checkouts: total number of checkouts, successful checkouts, and conversion rate.
[Better Auth](https://www.better-auth.com/) is an open source authentication framework for
TypeScript that is quickly becoming a favorite amongst developers. Today, we're
thrilled to have shipped a Polar plugin for Better Auth - in collaboration with them.
Checkout our [integration guide](/integrate/sdk/adapters/better-auth).
This is available right now using the [Checkout Session API](/features/checkout/session) and [Checkout Links](/features/checkout/links).
### Depreciations
* Products can no longer have both a monthly and yearly pricing. Existing products still work, but you'll see a warning like this when trying to edit their pricing:
{" "}
### API changes
* The `product_id` and `product_price_id` fields are deprecated in the [Checkout Session API](/api-reference/checkouts/create-session). You should now use the `products` field to specify the products you want to include in the checkout.
* The `type` and `recurring_interval` fields on `ProductPrice` are deprecated. `recurring_interval` is now set directly on `Product`.
**Missing any metrics?** [Let us know so we can add it.](https://github.com/orgs/polarsource/discussions/categories/feature-requests)
### Filters
You can easily slice and dice metrics with the filters below.
### Period
Change the time period in the X-axis to one of:
* Yearly
* Monthly
* Weekly
* Daily
* Hourly
### Timeframe
You can choose a date range to view all metrics for.
### Product
By default metrics reflect the total across all products. However, you can specify individual products or subscription tiers to filter metrics by.
## Metrics
### Revenue
How much revenue you've earned before fees.
### Orders
How many product sales and subscription payments have been made.
### Average Order Value (AOV)
The average earning per order, i.e revenue / orders.
### One-Time Products
Amount of products sold.
### One-Time Products Revenue
Amount of revenue earned from products.
### New Subscriptions
Amount of new subscriptions.
### New Subscription Revenue
Amount of revenue earned from new subscriptions.
### Renewed Subscriptions
Amount of renewed subscriptions.
### Renewed Subscription Revenue
Amount of revenue earned from renewed subscriptions.
### Active Subscriptions
Amount of active subscriptions (new + renewed)
### Monthly Recurring Revenue (MRR)
Amount of revenue earned from active subscriptions.
### Checkouts
Number of created checkouts.
### Succeeded Checkouts
Number of successful checkouts, i.e. checkouts that lead to a new order or subscription.
### Checkouts Conversion Rate
The percentage of successful checkouts out of all created checkouts.
# Credits Benefit
Source: https://docs.polar.sh/features/benefits/credits
Create your own Credits benefit
The Credits benefit allows you to credit a customer's Usage Meter balance.
## Crediting Usage Meter Balance
The Credits benefit will credit a customer's Usage Meter balance at different points in time depending on the type of product purchased.
### Subscription Products
The customer will be credited the amount of units specified in the benefit at the beginning of every subscription cycle period โ monthly or yearly.
### One-Time Products
The customer will be credited the amount of units specified in the benefit once at the time of purchase.
## Rollover unused credits
You can choose to rollover unused credits to the next billing cycle. This means that if a customer doesn't use all of their credits in a given billing cycle, the remaining credits will be added to their balance for the next billing cycle. To enable this feature, check the "Rollover unused credits" checkbox when creating or editing the Credits benefit.
Automating Discord server invites and roles for customers or subscribers is super easy and powerful with Polar.
* Fully automated Discord server invitations
* You can even setup multiple Discord servers, or...
* Offer different roles for different subscription tiers or products
## Create Discord Benefit
Click on `Connect your Discord server`. You'll be redirected to Discord where you can grant the Polar App for your desired server.
Next, you'll be prompted to approve the permissions our app requires to function. It needs all of them.
### **Manage Roles**
Access to your Discord roles. You'll be able to select which ones to grant to your customers later.
### **Kick Members**
Ability to kick members who have this benefit and connected Discord with Polar.
### **Create Invite**
Ability to invite members who purchase a product or subscribes to a tier with this benefit.
You're now redirected back to Polar and can finish setting up the Discord benefit on our end.
### **Connected Discord server**
The Discord server you connected cannot be changed. However, you can create multiple benefits and connect more Discord servers if you want.
### **Granted role**
Which Discord role do you want to grant as part of this benefit?
## Adding Benefit to Product
Head over to the product you want to associate this new Discord benefit with. You should be able to toggle the benefit in the bottom of the Edit Product form.
# Automate Customer File Downloads
Source: https://docs.polar.sh/features/benefits/file-downloads
Offer digital file downloads with ease
## Sell Digital Products
You can easily offer customers and subscribers access to downloadable files with Polar.
* Up to 10GB per file
* Upload any type of file - from ebooks to full-fledged applications
* SHA-256 checksum validation throughout for you and your customers (if desired)
* Customers get a signed & personal downloadable URL
## Create Downloadable Benefit
1. Go to `Benefits` in the Dashboard sidebar
2. Click `+ Add Benefit` to create a new benefit
3. Choose `File Downloads` as the `Type`
You can now upload the files you want to offer as downloadables for customers.
1. Drag & drop files to the dropzone (`Feed me some bytes`)
2. Or click on that area to open a file browser
### Change filename
Click on the filename to change it inline.
### Change order of files
You can drag and drop the files in the order you want.
### Review SHA-256 checksum
Click on the contextual menu dots and then `Copy SHA-256 Checksum`
### Delete a file
Click on the contextual menu dots and then `Delete` in the menu.
**Active subscribers & customers will lose access too!**
Deleting a file permanently deletes it from Polar and our S3 buckets except for the metadata. Disable the file instead if you don't want it permanently deleted.
### Disable & Enable Files
You can disable files at any point to prevent new customers getting access to it.
**Existing customers retain their access**
Customers who purchased before the file was disabled will still have access to legacy files. Only new customers will be impacted.
**Enabling or adding files grants access retroactively**
In case you add more files or re-enable existing ones, all current customers and subscribers with the benefit will be granted access.
# Automate Private GitHub Repo(s) Access
Source: https://docs.polar.sh/features/benefits/github-access
Sell premium GitHub repository access with ease
## Sell GitHub Repository Access
With Polar you can seamlessly offer your customers and subscribers automated access to private GitHub repositories.
* Fully automated collaborator invites
* Unlimited repositories (via multiple benefits) from your organization(s)
* Users get access upon subscribing & removed on cancellation
* Or get lifetime access upon paying a one-time price (product)
### **Use cases**
* Sponsorware
* Access to private GitHub discussions & issues for sponsors
* Early access to new feature development before upstream push
* Premium educational materials & code
* Self-hosting products
* Courses, starter kits, open core software & more...
## Create GitHub Repository Benefit
1. Go to `Benefits` in the sidebar
2. Click `+ New Benefit` to create a new benefit
3. Choose `GitHub Repository Access` as the `Type`
You first need to `Connect your GitHub Account` and install a dedicated Polar App for this benefit across the repositories you want to use it with.
* Click `Connect your GitHub Account`
You can easily sell software license keys with Polar without having to deal with sales tax or hosting an API to validate them in real-time. License keys with Polar come with a lot of powerful features built-in.
* Brandable prefixes, e.g `POLAR_*****`
* Automatic expiration after `N` days, months or years
* Limited number of user activations, e.g devices
* Custom validation conditions
* Usage quotas per license key
* Automatic revokation upon cancelled subscriptions
## Create License Key Benefit
1. Go to `Benefits` in the sidebar
2. Click `+ New Benefit` to create a new benefit
3. Choose `License Keys` as the `Type`
### Custom Branding
Make your license keys standout with brandable prefixes, e.g `MYAPP_
You can either copy and paste our code snippet to get up and running in a second or use our JavaScript library for more advanced integrations. Our embedded checkout allows you to provide a seamless purchasing experience without redirecting users away from your site.
## Code Snippet
The code snippet can be used on any website or CMS that allows you to insert HTML.
First, create a [Checkout Link](/features/checkout/links) as described in the previous section. The code snippet can directly be copied from there by clicking on `Copy Embed Code`.
The snippet looks like this:
```typescript
Purchase
```
This will display a `Purchase` link which will open an inline checkout when clicked.
You can style the trigger element any way you want, as long as you keep the `data-polar-checkout` attribute.
## Import Library
If you have a more advanced project in JavaScript, like a React app, adding the `
```
Replace `YOUR_AFFONSO_PROGRAM_ID` with the unique program ID provided by Affonso.
This script should be placed on all pages of your website, including:
* Your main marketing website
* Your application domain
* Any subdomains where users might land or make purchases
### 4. Track User Signups (Optional)
For better conversion insights, you can track when users sign up through an affiliate link:
```javascript
// After successful registration
window.Affonso.signup(userEmail);
```
### 5. Pass Referral Data to Polar Checkout
To ensure proper commission attribution, pass the referral data when creating checkout sessions:
```javascript
// Get the referral ID from the Affonso global variable
const referralId = window.affonso_referral;
// Create checkout session with Polar
const checkout = await polar.checkouts.create({
products: ["your_product_id"],
success_url: "https://your-site.com/success",
metadata: {
affonso_referral: referralId, // Include referral ID from Affonso
}
});
// Redirect to checkout
window.location.href = checkout.url;
```
## How It Works
1. When a user visits your site through an affiliate link, Affonso's script stores a unique identifier in a cookie
2. If you've implemented signup tracking, Affonso records when the user creates an account
3. When the user makes a purchase, the referral ID is passed to Polar as metadata
4. Polar's webhook notifies Affonso about the purchase
5. Affonso attributes the sale to the correct affiliate and calculates the commission
## Benefits of the Integration
* **Automated Tracking**: No manual work required to track affiliate-driven sales
* **Real-Time Analytics**: Both you and your affiliates get immediate insights into performance
* **Seamless User Experience**: The integration works behind the scenes without affecting your checkout flow
* **Flexible Commission Structures**: Set up complex commission rules based on product, subscription duration, etc.
## Getting Help
More details about the integration: [Polar Affiliate Program](https://affonso.io/polar-affiliate-program)
If you need assistance with your Affonso integration, contact Affonso's support team:
* Email: [hello@affonso.io](mailto:hello@affonso.io)
* Live chat: Available directly in the Affonso dashboard
# Polar Integration in Fernand
Source: https://docs.polar.sh/features/integrations/fernand
Learn how to sync customer and payment data from Polar to Fernand.
## What is Fernand?
[Fernand](https://getfernand.com/) is a modern customer support tool designed for SaaS โ itโs fast, calm, and built to reduce the anxiety of answering support requests.
## How it works
After connecting your [Polar](https://polar.sh/) account to Fernand, youโll be able to see customer payment information and product access details directly within each customer conversation.
This enables you to:
* Instantly verify if someone is an active customer
* Prioritize conversations from high-tier plans
* View product purchases and payment history in context
***
## How to connect Fernand with Polar
1. Open [Integrations](https://app.getfernand.com/settings/organization/integrations) in your Fernand organization settings.
2. Click on **Connect Polar**.
3. You'll be redirected to Polar to authorize the connection.
4. Once approved, Fernand will begin syncing customer data automatically.
Thatโs it! Youโll now see Polar customer info directly in Fernand's conversation list and sidebar.
***
## How to automate your inbox with Polar data
Once Polar is connected, you can create automation rules in Fernand based on Polar data.
Letโs walk through a basic example: auto-replying to all customers on your `Pro` plan.
### Create a new rule
### Grant ParityDeals Access (OAuth 2.0)
No need to create API access keys and share them externally. Just connect securely and grant the necessary permissions using Polar OAuth 2.0.
### Choose Products
Now, let's select the Polar products you want to offer deals for.
### Configure Deals
Let's configure our deal settings.
* Enter your website URL (requires your own site vs. Polar storefront)
* Enter a targeted URL path, e.g `/pricing` to only show deals on that page
Now we can configure the deals for different countries. ParityDeals offers great defaults, but you can of course change them.
### Configure Banner
You can then customize the ParityDeals banner to suit your site and design.
### Embed Banner
Finally, we're all setup over at ParityDeals. Just copy the script to their banner and embed it on your site. You're now done ๐๐ผ
## Questions & Help
Checkout the [ParityDeals documentation](https://www.paritydeals.com/docs/) for more guides and information.
# Polar for Raycast
Source: https://docs.polar.sh/features/integrations/raycast
The fastest way to access Polar from your keyboard
## Install Extension
[Head over to Polar on the Raycast Store, and install it from there.](https://www.raycast.com/emilwidlund/polar)
### View Orders
Easily view orders across organizations.
### View Subscriptions
View all active subscriptions across your organizations.
### View Customers
Keep track of all your customers.
# Polar for Zapier
Source: https://docs.polar.sh/features/integrations/zapier
Connect Polar to hundreds of other apps with Zapier
export const ZapierEmbed = () => {
if (typeof document === "undefined") {
return null;
} else {
setTimeout(() => {
const script = document.createElement("script");
script.type = "module";
script.src = "https://cdn.zapier.com/packages/partner-sdk/v0/zapier-elements/zapier-elements.esm.js";
document.head.appendChild(script);
const stylesheet = document.createElement("link");
stylesheet.rel = "stylesheet";
stylesheet.href = "https://cdn.zapier.com/packages/partner-sdk/v0/zapier-elements/zapier-elements.css";
document.head.appendChild(stylesheet);
const element = document.createElement("zapier-workflow");
element.clientId = "Zci4gpfx7Co47mBoFOYm0m8bmnzB5UPcw7eGhpSR";
element.theme = document.querySelector("html").classList.contains("dark") ? "dark" : "light";
element.introCopyDisplay = "hide";
element.manageZapsDisplay = "hide";
element.guessZapDisplay = "hide";
const container = document.querySelector("#zapier-container") || document.body;
container.appendChild(element);
}, 1);
return ;
}
};
[Zapier](https://zapier.com/apps/polar/integrations) lets you connect Polar to 2,000+ other web services. Automated connections called Zaps, set up in minutes with no coding, can automate your day-to-day tasks and build workflows between apps that otherwise wouldn't be possible.
Each Zap has one app as the **Trigger**, where your information comes from and which causes one or more **Actions** in other apps, where your data gets sent automatically.
The sales view shows you all sales in a paginated list.
## Order & Subscription Details
Each sale has metadata attached to it. Common properties like
* Amount
* Tax Amount
* Invoices
* Customer
* Basic Customer Details
* Past Orders
## Checkouts
You can also have an overview of all checkout sessions. You can filter them by customer email, status and product.
A checkout can be in the following states:
* Open: The checkout session is open and waiting for the customer to complete the payment.
* Confirmed: The customer clicked the **Pay** or **Subscribe** button and the payment is being processed.
* Succeeded: The payment was successful and the order was created.
* Expired: The checkout session expired and the customer can no longer complete it. A new checkout session must be created.
If you click on a Checkout, you can have more details on the **payment attempts**, in particular, why a payment has failed or has been declined.
## Create a product
### Name & Description
Starting off with the basic.
* **Name** The title of your product.
* **Description** Markdown is supported here too.
### Pricing
Determine how you want to charge your customers for this product.
Fields are managed from your organization settings, and you can choose which fields to show on a per-product basis, and set if they are required or not. We support the following field types:
* Text
* Number
* Date
* Checkbox
* Select
**Amount**
Specify the amount to refund. By default itโs the full order amount, but you can reduce this to issue a partial refund instead.
Optionally, you can set a **cap**. The customer will be charged the cap amount if they exceed it, regardless of the usage.
### Monthly Invoicing
If a customer has a subscription with a monthly billing period, usage is aggregated monthly and invoiced at the end of the month with the rest of the subscription.
### Yearly Invoicing
If a customer has a subscription with a yearly billing period, usage is aggregated yearly and invoiced at the end of the year with the rest of the subscription.
# Credits
Source: https://docs.polar.sh/features/usage-based-billing/credits
Crediting customers for Usage Based Billing
Credits is the way to pre-pay for usage in Polar. It allows you to give your customers the ability to pre-pay for usage instead of risk getting a hefty bill at the end of the month.
## How Credits Work
When you ingest events into a Usage Meter, customers will be charged for the usage based on the product's pricing model.
However, sometimes you may want to give your customers the ability to pre-pay for usage instead of risk getting a hefty bill at the end of the month.
When you issue Credits to a customer, we first deduct the Credits from their Usage Meter balance. If the Usage Meter balance reaches 0, the customer will be charged for the overage.
### Credits-only spending
To avoid any overage charges, don't create any Metered price on your product. This way, billing won't be triggered at all for the meter
## Issuing Credits with the Credits Benefit
### Clauses
A clause is a condition that an event must meet to be included in the meter.
#### Property
Properties are the properties of the event that you want to filter on.
If you want to match on a metadata field, you can use the metadata key directly. No need to include a `metadata.` prefix.
#### Operator
Operators are the operators that you want to use to filter the events.
* **Equals**
* **Not equals**
* **Greater Than**
* **Greater Than or Equals**
* **Less Than**
* **Less Than or Equals**
* **Contains**
* **Does Not Contain**
#### Value
Values are automatically parsed in the filter builder. They're parsed in the following order:
1. Number โ Tries to parse the value as number
2. Boolean โ Checks if value is "true" or "false"
3. String โ Treats value as string as fallback
### Conjunctions
A conjunction is a logical operator that combines two or more clauses.
* **and** โ All clauses must be true for the event to be included.
* **or** โ At least one clause must be true for the event to be included.
## Aggregation
The aggregation is the function that is used to aggregate the events that match the filter.
For example, if you want to count the number of events that match the filter, you can use the **Count** aggregation. If you want to sum the value of a metadata field, you can use the **Sum** aggregation.
* **Count** โ Counts the number of events that match the filter.
* **Sum** โ Sums the value of a property.
* **Average** โ Computes the average value of a property.
* **Minimum** โ Computes the minimum value of a property.
* **Maximum** โ Computes the maximum value of a property.
Consider following this guide while using the Polar Sandbox Environment. This will allow you to test your integration without affecting your production data.
## Polar Laravel Example App
We've created a simple example Laravel application that you can use as a reference.
[View Code on GitHub](https://github.com/polarsource/polar-laravel)
## Setting up environment variables
### Polar API Key
To authenticate with Polar, you need to create an access token, and supply it to Laravel using a `POLAR_API_KEY` environment variable.
You can create an organization access token from your organization settings.
## Fetching Polar Products for display
### Creating the Products Controller
Go ahead and add the following entry in your `routes/web.php` file:
```php
// routes/web.php
Route::get('/products', [ProductsController::class, 'handle']);
```
Next up, create the `ProductsController` class in the `app/Http/Controllers` directory:
```php
// app/Http/Controllers/ProductsController.php
api.polar.sh when ready to go live
// And don't forget to update the .env file with the correct POLAR_ORGANIZATION_ID and POLAR_WEBHOOK_SECRET
$data = Http::get('https://sandbox-api.polar.sh/v1/products', [
'is_archived' => false,
]);
$products = $data->json();
return view('products', ['products' => $products['items']]);
}
}
```
## Displaying Products
Finally, create the `products` view in the `resources/views` directory:
```php
// resources/views/products.blade.php
@foreach ($products as $product)
Supercharge your AI Agents with Polar as a Model Context Protocol (MCP) server.
## What is MCP?
MCP is a protocol for integrating tools with AI Agents. It can greatly enhance the capabilities of your AI Agents by providing them with real-time data and context.
Polar has MCP support built into the Polar TypeScript SDK.
## How does it work?
You need a MCP-capable Agent environment to use Polar as an MCP server. A few of them are Claude and Cursor.
## Using Polar as an MCP server
### Claude
Add the following server definition to your claude\_desktop\_config.json file:
```json
{
"mcpServers": {
"Polar": {
"command": "npx",
"args": [
"-y",
"--package",
"@polar-sh/sdk",
"--",
"mcp",
"start",
"--access-token",
"..."
]
}
}
}
```
### Cursor
Go to Cursor Settings > Features > MCP Servers > Add new MCP server and use the following settings:
* Name: Polar
* Type: command
* Command:
```bash
npx -y --package @polar-sh/sdk -- mcp start --access-token ...
```
### Help
For a full list of server arguments, run:
```bash
npx -y --package @polar-sh/sdk -- mcp start --help
```
# OAuth 2.0 Connect
Source: https://docs.polar.sh/integrate/oauth2/connect
## Authorize
To start the authorization flow you need to redirect the user to the authorization URL. It looks like this:
```
https://polar.sh/oauth2/authorize?
response_type=code
&client_id=CLIENT_ID
&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback
&scope=openid%20email
```
The parameters are the one described in the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). The most important ones are:
If they allow it, they'll be redirected to your `redirect_uri` with a `code` parameter in the query string. This code is a one-time code that you can exchange for an access token.
#### Exchange code token
Once you have the authorization code, you can exchange it for an access token. To do so, you'll need to make a `POST` request to the token endpoint. This call needs to be authenticated with the Client ID and Client Secret you got when creating the OAuth2 client.
Here is an example with cURL:
```bash
curl -X POST https://api.polar.sh/v1/oauth2/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=authorization_code&code=AUTHORIZATION_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=https://example.com/callback'
```
You should get the following response:
```json
{
"token_type": "Bearer",
"access_token": "polar_at_XXX",
"expires_in": 864000,
"refresh_token": "polar_rt_XXX",
"scope": "openid email",
"id_token": "ID_TOKEN"
}
```
The `access_token` will allow you to make authenticated API requests on behalf of the user. The `refresh_token` is a long-lived token that you can use to get new access tokens when the current one expires. The `id_token` is a signed JWT token containing information about the user, as per the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#IDToken).
#### User vs Organization Access Tokens
We support the concept of access tokens at **organization level**. Contrary to the standard access tokens, those tokens are not tied to a user but to an organization. They can be used to make requests operating only on a specific organization data, improving privacy and security.
To ask for an organization access token, you need to add the parameter `sub_type=organization` to the authorization URL:
```
https://polar.sh/oauth2/authorize?response_type=code&client_id=polar_ci_j3X95_MgfdSCeCd2qkFnUw&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=openid%20email&sub_type=organization
```
At this point, the user will be prompted to select one of their organization before allowing access to their data.
The rest of the flow remains unchanged. The access token you'll get will be tied to the selected organization.
Bear in mind that some endpoints might not support organization access tokens.
Typically, user-specific endpoints like `/v1/users/benefit` will not work with
organization access tokens.
#### Public Clients
Public clients are clients where the Client Secret can't be kept safe, as it would be accessible by the final user. This is the case for SPA, mobile applications, or any client running on the user's device.
In this case, **and only if the client is configured as a Public Client**, the request to the token endpoint won't require the `client_secret` parameter. However, the [PKCE](https://oauth.net/2/pkce/) method will be required to maximize security.
### Make authenticated requests
Once you have an access token, either from a Personal Access Token or from the OpenID Connect flow, you can make authenticated requests to the API. Here is a simple example with cURL:
```bash
curl -X GET https://api.polar.sh/v1/oauth2/userinfo \
-H 'Authorization: Bearer polar_at_XXX'
```
# Introduction
Source: https://docs.polar.sh/integrate/oauth2/introduction
For partners building services and extensions for Polar customers
### OpenID Connect (OAuth2)
Only use our **OpenID Connect** in case you want to act on the behalf of other users via our API, e.g building an app/service for Polar customers. Otherwise, always use an **Organization Access Token (OAT)** to integrate Polar for your own service.
Polar implements the [OpenID Connect specification](https://openid.net/developers/how-connect-works/) to enable third-party authentication. It's a layer on top of the OAuth2 framework aiming at making integration more standard and predictable.
In particular, it comes with a **discovery endpoint** allowing compatible clients to automatically work with the OpenID Connect server. Here is Polar's one:
[OpenID Configuration](https://api.polar.sh/.well-known/openid-configuration)
# Create an OAuth 2.0 Client
Source: https://docs.polar.sh/integrate/oauth2/setup
Before being able to make authentication requests, you'll need an **OAuth2 Client**. It's the entity that'll identify you, as a third-party developer, between Polar and the final user.
You can manage them from your [User Settings](https://polar.sh/settings#oauth)
Here are the required fields:
* *Application Name*: the name of the application that'll be shown to the final users.
* *Client Type*: the type of client you are creating. [Read more](#public-clients)
* *Redirect URIs*: for security reasons, you need to declare your application URL where the users will be redirected after granting access to their data. **HTTPS URL are required unless the hostname is** `localhost`.
* *Scopes*: the list of scopes your app will be able to ask for. To improve privacy and security, select only the scopes you really need for your application.
* *Homepage URL*: the URL of your application. It'll be shown to the final users on the authorization page.
Optionally, you can also add a **logo**, **terms of service** and **privacy policy** URL. They'll all be shown to the final users on the authorization page.
Once your client is created, you'll get a **Client ID** and a **Client Secret**. You'll need those values to make authentication requests.
Those values are super sensitive and should be kept secret. They allow making authentication requests on Polar!
# Sandbox Environment
Source: https://docs.polar.sh/integrate/sandbox
A separate environment, isolated from your production data
To test Polar or work on your integration without worrying about actual money processing or breaking your live organization, you can use our [sandbox environment](https://sandbox.polar.sh/start).
It's a dedicated server, completely isolated from the production instance where you can do all the experiments you want.
Once a webhook endpoint is setup you will have access to the delivery overview
page. Here you can:
* See historic deliveries
* Review payload sent
* Trigger redelivery in case of failure
Now, let's integrate our endpoint route to validate, parse & handle incoming webhooks.
## Validate & parse webhooks
You now need to setup a route handler for the endpoint registered on Polar to
receive, validate and parse webhooks before handling them according to your
needs.
### Using our SDKs
Our TypeScript & Python SDKs come with a built-in helper function to easily
validate and parse the webhook event - see full examples below.
If you paste a Discord or Slack Webhook URL, the format will be automatically selected.
Polar is purpose-built for developers, designers and startups to monetize their
digital products and software with ease.
**Highlighted Features**
Offer a powerful and custom branded checkout in minutes.
* [Checkout Links](/features/checkout/links)
* [Embedded Checkout](/features/checkout/embed) on your site
* [Checkout API](/features/checkout/embed) to programmatically create
dynamic sessions
[Sign up](https://polar.sh/signup) to Polar easily using GitHub, Google or email. Create an organization for your products, customers and checkouts.
## Using the Polar SDK
Polar comes in the form of an SDK, and is designed to be used in your existing backend infrastructure. We currently have SDKs for:
* [JavaScript/TypeScript](/integrate/sdk/typescript)
* [Python](/integrate/sdk/python)
* [Go](/integrate/sdk/golang)
* [PHP](/integrate/sdk/php)
Navigate to the relevant SDK page to learn more about the SDK and how to use it. In this particular guide, we'll focus on using the JavaScript/TypeScript SDK.
## Using a Polar Adapter
Polar's Adapters are small framework-specific utilities which makes it super-easy to integrate Polar.
They can be used to:
* Create Checkout Sessions
* Create a Customer Portal
* Listen for Polar Webhooks (e.g. for events like a customer being created, a subscription being updated, etc.)
We currently have adapters for the most popular frameworks:
* [Next.js](/integrate/sdk/adapters/nextjs)
* [BetterAuth](/integrate/sdk/adapters/better-auth)
* [Express](/integrate/sdk/adapters/express)
* [Fastify](/integrate/sdk/adapters/fastify)
* [Hono](/integrate/sdk/adapters/hono)
* [Deno](/integrate/sdk/adapters/deno)
* [Nuxt](/integrate/sdk/adapters/nuxt)
* [Remix](/integrate/sdk/adapters/remix)
* [SvelteKit](/integrate/sdk/adapters/sveltekit)
* [Tanstack Start](/integrate/sdk/adapters/tanstack-start)
* [Elysia](/integrate/sdk/adapters/elysia)
* [Astro](/integrate/sdk/adapters/astro)
* [Laravel](/integrate/sdk/adapters/laravel)
# null
Source: https://docs.polar.sh/merchant-of-record/acceptable-use
As your Merchant of Record (MoR), we are the reseller of all digital goods and
services and focus exclusively on digital products. Therefore we cannot support
physical goods or entirely human services, e.g consultation or support. In
addition to not accepting the sale of anything illegal, harmful, abusive,
deceptive or sketchy.
## Acceptable Products & Businesses
* Software & SaaS
* Digital products: Templates, eBooks, PDFs, code, icons, fonts, design assets, photos, videos, audio etc
* Premium content & access: Discord server, GitHub repositories, courses and content requiring a subscription.
**General rule of acceptable services**
Digital goods, software or services that can be fulfilled byโฆ
1. Polar on your behalf (License Keys, File Downloads, GitHub- or Discord invites or private links, e.g premium YouTube videos etc)
2. Your site/service using our APIs to grant immediate access to digital assets
or services for customers with a one-time purchase or subscriptions
Combined with being something youโd proudly boast about in public, i.e nothing illegal, unfair, deceptive, abusive, harmful or shady.
Donโt hesitate to [reach out to us](/support) in advance in case youโre unsure if your use case would be approved.
## Prohibited Businesses
Stripe and other Payment Service Providers (PSPs) offer an accessible and convenient abstraction to faciliate transactions on top of underlying credit card networks & banks.
* โ
Powerful, flexibile & low-level APIs to facilitate transactions
* โ
Can be used to power all business- and pricing models under the sun.
* โ You are responsible for all liabilities associated with transactions, e.g international taxes
* โ Low-level APIs require more development even for common use cases
**Merchants of Record (MoRs)**
Merchants of Record offer yet another layer of convenient abstraction to facilitate digital orders on top of the underlying PSPs and transactions. E.g Polar is built on Stripe (+ more PSPs in the future).
* โ
Higher-level Dashboard, APIs & SDKs to better facilitate digital products, services & orders beyond the underlying transactions
* โ
The platform (Polar) handles international taxes by being a reseller of your digital goods & services. Of course, without being in the way of your relationship with your customers.
* โ Less flexibility & control in terms of advanced business- and pricing models.
* โ Higher fees per payment
**What should you choose?**
**Ship with what you feel comfortable with vs. others tell you to**
Just like in programming, abstractions are super helpful to ship faster with fewer low-level concerns, but in exchange for reduced flexibility and higher costs. So what's the right level of abstraction for you? As always, it depends (tm).
**Go with Stripe (PSP) if...**
* You've already integrated it? Just ship already - we salute builders however they ship
* You're comfortable with the Stripe API and prefer absolute control with low-level APIs.
* You're looking for the lowest fees possible.
* You're fine with handling international taxes yourself (you absolutely can).
**Go with Polar (MoR) if...**
* You want product-, customer-, order- and subscription management via an intuitive and easy dashboard
* You want to offer file downloads, license keys, Discord- and/or private GitHub repository invites with ease - with more built-in automations to come.
* You prefer a more high-level API optimized for making monetization easier. We're only getting started here and have some big things coming
* You want us to handle international taxes for you
### Polar MoR
**tl;dr We take on the liability of international sales taxes globally for you. So you can focus on building your passion. Leaving billing infrastructure and sales tax headaches to us.**
So how does Polar offer a Merchant of Record (MoR) service and handle international sale taxes? All other Merchants of Record simply state they handle it internationally - don't worry about it. We do too.
But we believe in transparency and don't want to scare customers into thinking it's impossible to manage it themselves. So below we'll share how exactly we go about doing this.
#### International Sales Taxes
Most countries, states and jurisdictions globally impose sales taxes on digital goods and services (VAT, GST, US Sales Tax etc). Regardless of whether the merchant (seller) is a resident there or not - they're doing business there.
For example, a \$10/month subscription should cost \$12.5/month for a Swedish (25% VAT) consumer, but \$10/month for a Swedish business with VAT registration (reverse charge).
Merchants are responsible for 1) capturing & 2) remitting sales taxes to the local tax authorities. What does that mean in our example?
1. **Capturing**. Charging the Swedish consumer \$12.5/month and saving \$2.5/month for the Swedish tax authorities. Stripe Tax is an excellent service to automate this and the one Polar uses today.
2. **Remitting**. Filing & paying the captured sales taxes with the tax authorities on time. Stripe Tax does not do this, i.e the merchant is liable to register, file and pay taxes to local tax authorities.
Many jurisdictions, however, don't require this until you reach a certain threshold in terms of sales volume. But others require registration even before the first sale - or after a very low threshold. In addition to having different rates and rules on which goods are taxable and whether they're deductable or not for business customers.
For example, United Kingdom and EU countries require upfront registration for international companies, but Texas (United States) does not until you've sold for more than \$500,000 ๐บ๐ธ๐ฆ
In short: It's complex and hard. Even large and well-known businesses don't do it perfectly. Arguably, it's almost impossible and at least highly impracticle and expensive to comply perfectly upfront. Many companies even delay compliance as a calculated risk, i.e focus on validating & growing their business with the risk of paying back taxes + penalities later.
**PSP (Stripe)**
* โ
Your volume alone is what counts towards international thresholds vs. the MoR platform, i.e customers might not need to pay sales taxes with you, but would via a MoR.
* โ
You can deduct inbound VAT against purchases your business does with VAT
* โ You're liable for capturing & remitting international sales taxes
* โ Stripe Tax is great to monitor & automate capturing, but registration and remittance is up to you.
**MoR (Polar)**
* โ
We are liable for all of the above as your reseller, i.e we have to worry about it vs. you.
* โ
Offer EU VAT for B2B sales (expected and desired within EU for businesses) without having to register, capture and remit it yourself.
* โ Sales taxes would be added for more customers vs. with you selling directly
* โ You cannot leverage inbound VAT towards VAT expense deductions yourself
Merchants of Record (MoR) handles sales taxes, e.g US Sales Tax, EU VAT,
Canadian GST etc. **However, you're always responsible for your own
income/revenue tax** in your country of residency.
#### Polar Coverage
**tl;dr We support global payments and are liable for all international sales taxes. We continuously monitor and work with our accounting firms to expand registrations as needed on our end.**
**Global Payments & Tax Liabilities**
As your Merchant of Record, Polar is liable for tax compliance globally on all sales internationally via our platform, hosted- or embedded checkoutsfrom payments anywhere in the world.
**Current Polar Tax Registrations**
1. Polar Software Inc. is incorporated as a US Delaware C Corp and will register for US State Sales Taxes upon reaching thresholds
2. EU VAT (Irish OSS VAT)
3. UK VAT
No Merchant of Record (MoR) or business registers upfront in all global jurisdictions. Since it would be 1) unnecessary in case of thresholds & 2) incredibly expensive with uncertain return on investment (ROI) in all markets.
We work with global accounting firms specialized in registering, filing and remitting taxes in all countries. So we can easily scale registrations and remittance as needed. Below is our process and evaluation for expanding registrations.
**Expanding Registrations**
Below are the fees the global acounting firms we work with charge us - on average per market:
* \~\$500 upfront for registration
* \~\$300 per filing and remittance (\~quarterly)
* *Excluding consultations (billed hourly) and our internal efforts and automations to transform Stripe Tax reports into correct output for the accounting firms.*
So on average $1,700 in year one and $1,200 therafter for each market at a minimum. Businesses (and you if you handle this yourself) therefore need to ask themselves: Do I anticipate more in sales from a given market vs. costs of operating there?
Let's imagine a country with 20% sales tax.
1. At $6,000+ the tax liability start outgrowing the accounting costs for you standalone ($1,200/20%)
2. Polar with a 1.1% premium vs. Stripe would need to help facilitate $109,090 in sales for the given market in order for it to cover our accounting costs ($1,200/1.1%)
Our customers are selling mostly in the US, UK & EU. Given US thresholds and our current registrations, it's therefore a non-issue.
In markets we're not registered, we still have the liability and take it on (#1) to assess the potential for our customers and us long-term. In addition to being comfortable betting on markets a lot earlier than it becomes profitable for us (#2).
However, in case of neither we reserve the right to block payments from such countries in the short-term until the opportunity for our customers and us changes in the given market.
**Want to do this yourself?**
Selling a lot and want to handle this yourself, i.e worth the ongoing costs? Feel free to reach out and we'd be happy to introduce you to our contacts at the accounting firms we use.
We consider MoR a key value-add to Polar, but not the sole reason for Polar to exist. Our ambition is to be the easiest way to monetize for developers. However, we're never going to be the right solution for all use cases. But we'll always salute and help anyone who ships software - regardless of billing platform.
# null
Source: https://docs.polar.sh/merchant-of-record/supported-countries
### Payments & Merchant of Record
We support payments globally except from countries with US sanctions.
As your Merchant of Record (MoR) we take on the liability for international sales taxes - [read more here](/merchant-of-record/introduction).
### Payouts
Polar uses Stripe Connect Express to issue payouts to residents or businesses in any of the countries below.