Polar Knowledge Patch

Polar Knowledge Patch

Use this skill when implementing or reviewing Polar SDK usage, API authentication, products, checkouts, subscriptions, customer access, benefits, events, meters, billing operations, webhooks, or integrations.

Reference index

Preview SDK setup

The typed 2026-04 clients are prereleases. Install and import the TypeScript client with:

npm install @polar-sh/sdk@next

import { createPolar } from "@polar-sh/sdk/2026-04";

For Python, install and import the client with:

pip install --pre polar-sdk

from polar.v2026_04 import Polar

Both clients target production by default. Select the isolated sandbox by setting environment: "sandbox" in TypeScript or environment="sandbox" in Python. Sandbox credentials and data do not cross into production.

import { createPolar } from "@polar-sh/sdk/2026-04";

const polar = createPolar({
  accessToken: process.env.POLAR_ACCESS_TOKEN!,
  environment: "sandbox",
});

Keep Core and customer access separate

• Authenticate backend Core API requests with an Organization Access Token.
• Send Core API requests to https://api.polar.sh/v1 or the sandbox base URL.
• For customer-facing code, create a Customer Access Token through /v1/customer-sessions/.
• Use that token only with the restricted /v1/customer-portal/ surface.
• A Customer Access Token is customer-scoped. It cannot create products, issue refunds, or perform other organization-level operations.

Migrate deprecated product and checkout fields

Treat a variant as a separate product and offer the related products together in one checkout.

• Do not combine monthly and yearly pricing on a new product. Existing combinations continue to work.
• Use products instead of deprecated checkout fields product_id and product_price_id.
• Set recurrence on Product; ProductPrice.type and ProductPrice.recurring_interval are deprecated.
• Select requested Metrics API values with metrics; focus_metrics has been removed.

Choose checkout and pricing behavior

Products support amounts in multiple currencies and an organization-level default presentment currency. Fixed discounts can carry currency-specific amounts. Subscription intervals can be daily, weekly, or use a custom interval count.

Other supported pricing paths include:

• tax-inclusive prices;
• seat-based one-time products; and
• API-created checkouts using fixed, free, or custom ad-hoc price overrides.

For eligible one-time EUR purchases, checkout automatically exposes Bancontact, BLIK, EPS, iDEAL/Wero, Przelewy24, and Bizum. UPI supports one-time INR purchases and recurring INR subscriptions. Polar does not calculate tax for free or other zero-amount orders.

Apply checkout controls

• Set return_url on Checkout sessions and Customer Portal sessions.
• Dashboard-created static Checkout Links can also set return_url.
• Checkout Links persist reference_id and standard UTM query parameters into Checkout metadata.
• Use min_seats and max_seats to constrain seat checkouts.
• The business-purchase option requires a business billing name and full address.

Adding any host under Settings → Preferences → Embedding changes the configured host list into an allowlist. Organizations created from August 4, 2026 must configure hosts before embedding. Older organizations remain unrestricted until their first host is added.

Control discount reuse and trials

Set max_redemptions_per_customer when creating or updating a discount. Repeat use is recognized through customer ID, plus-alias-normalized email, or payment card.

Configure trials on subscription products. Organization-level abuse prevention uses normalized email and card fingerprints. Set Checkout's allow_trial to force a purchase without the trial normally configured on the product.

Mutate subscriptions safely

Subscriptions can be created directly through the API without Checkout. For an existing subscription:

• move from an archived price to the current price of the same product with proration;
• add, change, or remove its discount; and
• change the current billing-period end unless the subscription is already canceled.

Use the next_period proration behavior to schedule product, price, or seat changes. The pending change appears on subscription objects and webhooks.

Pausing takes effect at period end, stops billing, and revokes benefits without deleting the subscription or payment method. Resuming begins a new period and charges immediately. An automatic resume date is optional. These transitions emit subscription.paused and subscription.resumed.

Work with members and seats

GET /v1/members is paginated and supports customer filtering. Polar creates an owner member automatically. Member roles are owner, billing_manager, and member; transferring ownership demotes the former owner to billing manager.

• Member-session tokens use the polar_mst_ prefix.
• Benefits can be member-specific.
• Events accept member_id or external_member_id.
• Assign seats through the API.
• Customer seat changes are automatically prorated.

Preserve entitlement and event semantics

The Feature Flag benefit exposes entitlement state through APIs and webhooks, but customers cannot see its JSON metadata. Subscription cancellation automatically revokes benefits. Failed-payment revocation may be immediate or may follow the payment-retry grace window.

Use parent_id to form event hierarchies and external_id as an idempotency key. Event names create event types. Event types support display names and a statistics endpoint, and events can include cost metadata.

Handle operational boundaries

• List endpoints use one-based page and limit values. Defaults are page 1 and limit 10; the maximum limit is 100.
• Read pagination.total_count and pagination.max_page from list responses.
• Production allows 500 requests per minute and sandbox allows 100 per minute, per organization, customer, or OAuth2 client.
• Unauthenticated license validation, activation, and deactivation allow three requests per second. A 429 response includes Retry-After.
• A webhook endpoint is disabled after 10 consecutive failures by default. Organization members are notified, and the endpoint must be manually re-enabled after its receiver is fixed.

Consult the topic references before changing behavior whose details are not in this quick reference.