Polar Documentation

The Customer Portal is a hosted, self-service destination where customers can manage their relationship with your business. It is designed to reduce support overhead by allowing customers to handle billing tasks independently.

Key capabilities for customers:

• Subscription & Purchase Management: View active subscriptions, past purchase history, and cancel subscriptions.
• Financial Documents: Download and edit invoices (adding company names, VAT numbers, etc.) and download payment receipts.
• Payment Recovery: Update default payment methods to recover from failed subscription renewals.
• Benefit Access: Access entitled benefits such as license keys, file downloads, or Discord access.
• Account Settings: Optionally change email addresses, switch subscription plans, manage seats, and view metered usage (configurable via Settings).

Polar provides built-in benefit (entitlements) automation designed for developer and designer ecosystems. These benefits allow you to automate access to various resources based on customer purchases or subscriptions.

Supported benefit types include:

• Credits: Add balance to a customer's Usage Meter.
• License Keys: Customizable software license keys.
• Feature Flags: API-driven access flags with optional metadata.
• File Downloads: Access to files up to 10GB each.
• GitHub Repository Access: Automatic invitations to private GitHub repositories.
• Discord Invite: Automated invitations and role granting.
• Shared Slack Channel: Access via Slack Connect.

Polar provides complete billing infrastructure as a Merchant of Record (MoR). Key capabilities include:

• Flexible Product Management: Support for one-time purchases, recurring subscriptions, and flexible pricing (fixed, pay-what-you-want, or free).
• Checkout Experience: Options for no-code Checkout Links, customizable Embedded Checkout, or a full Checkout API for dynamic sessions.
• Global Merchant of Record: Handles international tax compliance (VAT, GST, sales tax), EU VAT (B2B reverse charge and B2C collection), and real-time tax calculation.
• Automated Benefits: Instant delivery of license keys, files, GitHub access, and Discord roles.

The Polar recruitment process is a multi-stage evaluation focused on practical assessment and values alignment. The stages are:

1. Introduction Call (30 minutes): An initial call to discuss the candidate, Polar, and company culture.
2. Technical Assignment: A practical task involving the review and analysis of a pull request (estimated 1-2 hours).
3. Assignment Review & Technical Discussion (1 hour): A deep dive into the technical assignment to discuss decisions, trade-offs, and reasoning within a complex codebase.
4. Team Conversations (30 min): 2-3 video calls to meet future team members.
5. Offer: The formal offer stage.
6. Reference Calls: Brief conversations with previous colleagues or managers.

@polar-sh/ui is the internal UI library for the Polar project. It is built using shadcn/ui as a foundation.

Note: This is a private library intended for the Polar project and is not recommended for direct use in external projects.

Polar uses Stripe as its primary financial partner to process payments and settle funds. Stripe handles the secure transmission of transaction data, payment authorization, settlement, fraud prevention, and compliance with global card network standards.

When a customer makes a purchase:

1. Payment information is captured by Stripe at checkout.
2. Stripe transmits the transaction to card networks and issuing banks.
3. The issuing bank authorizes or declines the transaction.
4. Approved funds are settled to the Polar account on Stripe. Payouts to merchants are managed via Stripe Connect.

Polar uses a Role-Based Access Control (RBAC) system with three primary roles assigned to users within an organization:

• owner: The primary account holder. There is exactly one owner per organization. Ownership transfers are handled via specific administrative flows, not standard role updates.
• admin: Users with administrative capabilities.
• member: Standard users with base access.

Authorization Logic: Permissions are determined by the intersection of a user's assigned scopes and the permissions implied by their role. An action is allowed if the required_perm is present in both the implied(scopes) and permissions(role) sets.

Polar uses a dedicated migration module to move billing data from source platforms (like Stripe) to Polar. The architecture is built around several key components:

• MigrationJob: Represents a single migration run for an organization, tracking the source platform and current progress.
• MigrationRecord: An idempotency layer that maps source_id to target_id for every imported entity (customers, products, subscriptions, etc.).
• SourceAdapter: Responsible for reading the source provider's API and providing a generic CanonicalRecord (e.g., CanonicalProduct, CanonicalCustomer, CanonicalSubscription).
• MigrationService: The main orchestrator of the migration process.
• PanTransferStep: A checklist of steps (stored as JSONB) used to track the movement of payment cards (PAN copy or PAN import).

Polar offers a free Starter plan and three paid tiers (Pro, Growth, and Scale) that reduce variable transaction rates and provide higher support priority. You can switch between plans at any time, and rates adjust immediately.

Paid plans replace the per-transaction Merchant of Record premium with a fixed monthly fee and a lower variable rate.

Seat-based pricing separates the payer from the user through three distinct entities:

• Customer: The billing entity (the payer). On their first seat-based purchase, they are upgraded to type: "team". They own subscriptions and payment methods.
• Member: The end user (the consumer). Each member has an email, a role (owner, billing_manager, or member), and receives benefits independently. The purchaser is assigned the owner role.
• CustomerSeat: The link between a product and a member. It tracks the assignment status (pending, claimed, or revoked) and holds the invitation token.

Note: Always identify end users by their Member ID, as benefits are granted to members rather than the billing customer.

Polar automatically includes links to the Customer Portal in transactional emails sent to customers, including:

• Order confirmation emails
• Subscription renewal and subscription updated emails
• Failed payment notifications (allowing customers to update payment methods)