API Overview

Base URLs, authentication, pagination, rate limits, and the difference between the Core API and the Customer Portal API

Production Base URL

https://api.polar.sh/v1

Sandbox Base URL

https://sandbox-api.polar.sh/v1

Auth (Organization)

Use an Organization Access Token (OAT) in the Authorization: Bearer header

Auth (Customer Portal)

Use a Customer Access Token created via /v1/customer-sessions/

Base URLs

Environment	Base URL	Purpose
Production	https://api.polar.sh/v1	Real customers & live payments
Sandbox	https://sandbox-api.polar.sh/v1	Safe testing & integration work

The sandbox environment is fully isolated—data, users, tokens, and organizations created there do not affect production. Create separate tokens in each environment.

Read more: Sandbox Environment

Authentication

Organization Access Tokens (OAT)

Use an OAT to act on behalf of your organization (manage products, prices, checkouts, orders, subscriptions, benefits, etc.).

Authorization: Bearer polar_oat_xxxxxxxxxxxxxxxxx

Create OATs in your organization settings. See: Organization Access Tokens

Never expose an OAT in client-side code, public repos, or logs. If leaked, it will be revoked automatically by our secret scanning integrations.

Customer Access Tokens

Do not use OATs in the browser. For customer-facing flows, generate a Customer Session server-side, then use the returned customer access token with the Customer Portal API to let a signed-in customer view their own orders, subscriptions, and benefits.

Core API vs Customer Portal API

Aspect	Core API	Customer Portal API
Audience	Your server / backend	One of your customer
Auth Type	Organization Access Token (OAT)	Customer Access Token
Scope	Full org resources (products, orders, subscriptions, benefits, checkout)	Only the authenticated customer’s data
Typical Use	Admin dashboards, internal tools, automation, provisioning	Building a custom customer portal or gated app
Token Creation	Via dashboard (manual)	Via /v1/customer-sessions/ (server-side)
Sensitive Operations	Yes (create/update products, issue refunds, etc.)	No (read/update only what the customer owns)

The Customer Portal API is a restricted surface designed for safe exposure in user-facing contexts (after exchanging a session). It cannot perform privileged org-level mutations like creating products or issuing refunds.

Quick Examples

curl (Production - Core API)

curl https://api.polar.sh/v1/products/ \
  -H "Authorization: Bearer $POLAR_OAT" \
  -H "Accept: application/json"

Using SDKs

All official SDKs accept a server parameter for sandbox usage:

TypeScript

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

const polar = new Polar({
accessToken: process.env.POLAR_ACCESS_TOKEN!,
server: "sandbox", // omit or use 'production' for live
});

Pagination

List endpoints in the Polar API support pagination to help you efficiently retrieve large datasets. Use the page and limit query parameters to control pagination.

Query Parameters

Parameter	Type	Default	Max	Description
page	integer	1	-	Page number, starting from 1
limit	integer	10	100	Number of items to return per page (window size)

The page parameter works as a window offset. For example, page=2&limit=10 means the API will skip the first 10 elements and return the next 10.

Response Format

All paginated responses include a pagination object with metadata about the current page and total results:

Field	Type	Description
total_count	integer	Total number of items matching your query across all pages
max_page	integer	Total number of pages available, given the current limit value

Example

Let’s say you want to fetch products with a limit of 100 items per page:

Request

curl https://api.polar.sh/v1/products/?page=1&limit=100 \
  -H "Authorization: Bearer $POLAR_OAT" \
  -H "Accept: application/json"

In this example:

• total_count=250 indicates there are 250 total products
• limit=100 means each page contains up to 100 products
• max_page=3 means you need to make 3 requests to retrieve all products (pages 1, 2, and 3)

To retrieve all pages, increment the page parameter from 1 to max_page. Our SDKs provide built-in pagination helpers to automatically iterate through all pages.

Rate Limits

Polar API has rate limits to ensure fair usage and maintain performance. The limits are as follows:

• 300 requests per minute per organization/customer or OAuth2 Client.
• 3 requests per second for unauthenticated license key validation, activation, and deactivation endpoints.

If you exceed the rate limit, you will receive a 429 Too Many Requests response. The response will include a Retry-After header indicating how long you should wait before making another request.

Organizations requiring higher rate limits for production workloads may contact our support team to discuss elevated limits.