## 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](/content/docs/integrate/oat/index.html), then install the SDK and make your first request:

- TypeScript
- Python

### TypeScript Example

```typescript
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

```python
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](/content/docs/integrate/sandbox/index.html).

## 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](/content/docs/integrate/sandbox/index.html)

## 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](/content/docs/integrate/oat/index.html)

### Customer Access Tokens

Do **not** use OATs in the browser. For customer-facing flows, [generate a **Customer Session**](/content/docs/api-reference/2026-04/customer-sessions/create-customer-session/index.html) 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)

## Quick Examples

**Production - Core API**

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

**Sandbox - Core API**

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

**Customer Portal API**

```bash
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

| 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) |

### 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

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

```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](/content/docs/api-reference/2026-04/customer_portal/validate-license-key/index.html) and [activation](/content/docs/api-reference/2026-04/customer_portal/activate-license-key/index.html) 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.