API Overview - Polar

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/

Official SDKs

Use our new, fully typed SDKs to integrate with the Polar API from TypeScript or Python.

The SDKs are currently in public preview. Install the pre-release explicitly to try them before the stable release.

Create an organization access token, then install the SDK and make your first request:

• TypeScript
• Python

TypeScript Example

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

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

const customerState = await polar.customers.getStateExternal("customer_external_id");
console.log(customerState);

Python Example

import os

from polar.v2026_04 import Polar

polar = Polar(os.environ["POLAR_ACCESS_TOKEN"])

customer_state = polar.customers.get_state_external("customer_external_id")
print(customer_state)

Both clients use production by default. Pass environment="sandbox" in Python or environment: "sandbox" in TypeScript to use the sandbox environment.

Base URLs

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

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

Quick Examples

Production - Core API

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

Sandbox - Core API

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

Customer Portal API

curl https://api.polar.sh/v1/customer-portal/orders/ \
  -H "Authorization: Bearer $POLAR_CUSTOMER_TOKEN" \
  -H "Accept: application/json"

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

Response Format

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

Example

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

{
  "items": [
    {
      "id": "...",
      "name": "Product 1"
    }
  ],
  "pagination": {
    "total_count": 250,
    "max_page": 3
  }
}

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 and activation 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.