Introduction to Polar.sh

Before diving deeper into MonaKiosk, let’s understand Polar.sh — the payment infrastructure that powers everything.

What is Polar.sh?

Polar.sh is a monetization platform built specifically for developers and creators. Unlike generic payment processors, Polar understands the developer ecosystem and provides APIs designed for programmatic integration.

Think of it as “Stripe for developer monetization” — it handles:

• Payment processing (via Stripe under the hood)
• Product and pricing management
• Customer management and entitlements
• Checkout flows
• Tax compliance
• Downloadable file hosting

Why Polar for Content Monetization?

Feature	Benefit for Content Sites
Merchant of Record	Polar handles global tax compliance — you don’t
API-first design	Easy integration with static site generators
Product metadata	Store content IDs to link products to your content
Benefits system	Attach access rights and files to purchases
Customer portal	Users can manage their purchases
Sandbox mode	Test payments without real money
Developer focus	Built for technical products and content

Merchant of Record (MoR)

One of Polar’s most valuable features is acting as your Merchant of Record. This means Polar legally becomes the seller, taking on liability for international sales tax compliance.

What Polar handles for you:

• EU VAT — Registered through Irish One Stop Shop
• UK VAT — Full compliance
• US State Sales Taxes — Automatically triggered when thresholds are met

As a developer, you avoid:

• Tracking varying tax rates across countries
• Registration requirements in multiple jurisdictions
• Filing deadlines and remittance obligations
• Audit risks and compliance penalties

The trade-off: Slightly higher fees compared to direct Stripe integration, but this is offset by eliminated accounting overhead and zero compliance risk.

For more details, see Polar’s MoR documentation.

Framework Integrations

Polar provides official SDK adapters for popular frameworks:

Framework	Package	Use Case
Next.js	@polar-sh/nextjs	Server components, API routes
Astro	@polar-sh/astro	SSR middleware, islands
Better Auth	@polar-sh/better-auth	Sync auth users with Polar customers

MonaKiosk builds on top of @polar-sh/sdk and integrates seamlessly with Better Auth via @polar-sh/better-auth — which we’ll cover in the authentication chapter.

Polar Dashboard Overview

When you sign in to Polar, you’ll see:

Products

Products represent things customers can buy. For content sites:

• Each paywalled article = one product
• Each course = one product (covering all chapters)
• Pricing can be one-time or recurring (subscription)

Benefits

Benefits are what customers receive when they purchase. MonaKiosk uses two types:

• Custom benefit — Contains the content URL and description
• Downloadables benefit — Hosts files customers can download

Customers

People who have purchased from you. Polar manages:

• Customer sessions (authentication)
• Purchase history
• Access to benefits

Checkouts

The payment flow. Polar hosts the checkout page, handles payment, and redirects back to your site.

Sandbox vs Production

Polar provides two environments:

Environment	Use Case	Test Card
Sandbox	Development and testing	4242 4242 4242 4242
Production	Real payments	Real credit cards

Always start in sandbox mode:

POLAR_SERVER=sandbox

Switch to production when ready to accept real payments:

POLAR_SERVER=production

How MonaKiosk Uses Polar

Build time:

1. MonaKiosk scans content for price fields
2. Creates/updates Polar products with content_id metadata
3. Creates benefits linked to each product

flowchart TB
    A[Content with price] --> B[MonaKiosk sync]
    B --> C[Polar Product]
    B --> D[Custom Benefit]
    B --> E[Downloadables Benefit]

    C -.->|Linked| D
    C -.->|Linked| E

Runtime:

1. Middleware intercepts requests to paywalled content
2. Checks if user has a valid customer session
3. Validates purchase via Polar API
4. Serves full content or preview accordingly

flowchart TB
    F[User visits page] --> G[Middleware checks access]
    G --> H{Has purchased?}
    H -->|No| I[Show preview + checkout link]
    H -->|Yes| J[Show full content]
    I --> K[Polar Checkout]
    K --> L[Purchase complete]
    L --> J

Getting Your Polar Credentials

To integrate with MonaKiosk, you need three values from Polar:

1. Organization ID and Slug

1. Go to your Polar dashboard
2. Click on your organization name
3. Navigate to Settings
4. Copy the Organization ID (UUID format)
5. Note your Organization Slug (URL-friendly name)

2. Access Token

1. Go to Settings → Developers → Personal Access Tokens
2. Click Create Token
3. Select these scopes:
   • products:read and products:write
   • benefits:read and benefits:write
   • customers:read
   • files:read and files:write (if using downloads)
4. Copy the generated token (starts with polar_oat_)

3. Webhook Secret (Optional)

For real-time purchase notifications:

1. Go to Settings → Webhooks
2. Create a webhook pointing to your site
3. Copy the signing secret

Polar API Basics

MonaKiosk abstracts most Polar API calls, but understanding the basics helps:

import { Polar } from "@polar-sh/sdk";

const polar = new Polar({
  accessToken: process.env.POLAR_ACCESS_TOKEN,
  server: "sandbox",
});

// List products
const products = await polar.products.list({
  organizationId: "your-org-id",
});

// Check customer access
const grants = await polar.customerPortal.benefitGrants.list({
  customerId: "customer-id",
});

MonaKiosk provides a pre-configured client:

import { getPolarClient } from "mona-kiosk";

const polar = getPolarClient();
// Use polar.products, polar.benefits, etc.

Key Takeaways

1. Polar handles payments — You don’t touch credit cards
2. Products map to content — Via content_id metadata
3. Benefits grant access — Customers get benefits, which grant content access
4. Sandbox for testing — Always develop in sandbox mode
5. MonaKiosk abstracts complexity — You rarely call Polar API directly

Next, we’ll dive deeper into Products, Benefits, and Customers — the three pillars of Polar’s data model.