Skip to main content

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

EnvironmentBase URLPurpose
Productionhttps://api.polar.sh/v1Real customers & live payments
Sandboxhttps://sandbox-api.polar.sh/v1Safe 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

AspectCore APICustomer Portal API
AudienceYour server / backendOne of your customer
Auth TypeOrganization Access Token (OAT)Customer Access Token
ScopeFull org resources (products, orders, subscriptions, benefits, checkout)Only the authenticated customer’s data
Typical UseAdmin dashboards, internal tools, automation, provisioningBuilding a custom customer portal or gated app
Token CreationVia dashboard (manual)Via /v1/customer-sessions/ (server-side)
Sensitive OperationsYes (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 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: 
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

ParameterTypeDefaultMaxDescription
pageinteger1-Page number, starting from 1
limitinteger10100Number 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:
FieldTypeDescription
total_countintegerTotal number of items matching your query across all pages
max_pageintegerTotal 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: 
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. Limits differ between the Sandbox and Production environments.

​
Production

  • 500 requests per minute per organization/customer or OAuth2 Client.

​
Sandbox

  • 100 requests per minute per organization/customer or OAuth2 Client.
Unauthenticated validation, activation, and deactivation endpoints are limited to 3 requests per second in both environments. 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.