Skip to main content

​
Introduction

The Polar API allows you to programmatically manage your payment infrastructure, including products, subscriptions, customers, orders, and more.

​
Base URL

All API requests should be made to: 
https://api.polar.sh/v1

​
Authentication

Polar supports multiple authentication methods:

​
Personal Access Tokens

Create a Personal Access Token (PAT) from your Polar dashboard and include it in the Authorization header: 
curl https://api.polar.sh/v1/products \
  -H "Authorization: Bearer polar_pat_..."

​
Organization Access Tokens

For organization-scoped operations, use an Organization Access Token: 
curl https://api.polar.sh/v1/products \
  -H "Authorization: Bearer polar_oat_..."

​
OAuth 2.0

Polar supports OAuth 2.0 for third-party integrations. See our OAuth documentation for details.

​
Request Format

​
Content Type

All POST, PATCH, and PUT requests should use JSON: 
curl -X POST https://api.polar.sh/v1/products \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Premium Plan"}'

​
Query Parameters

GET requests use query parameters for filtering: 
curl "https://api.polar.sh/v1/products?organization_id=abc123&is_archived=false" \
  -H "Authorization: Bearer polar_pat_..."

​
Response Format

​
Success Responses

Successful responses return JSON with the requested data: 
{
  "id": "prod_123",
  "name": "Premium Plan",
  "created_at": "2024-01-15T10:30:00Z"
}

​
List Responses

List endpoints return paginated results: 
{
  "items": [
    {"id": "prod_123", "name": "Premium Plan"},
    {"id": "prod_456", "name": "Basic Plan"}
  ],
  "pagination": {
    "total_count": 42,
    "page": 1,
    "page_size": 20
  }
}

​
Pagination

List endpoints support pagination via query parameters:
​
page
integer
default:"1"
Page number (1-indexed)
​
limit
integer
default:"20"
Number of items per page (max 100)
Example: 
curl "https://api.polar.sh/v1/products?page=2&limit=50" \
  -H "Authorization: Bearer polar_pat_..."

​
Sorting

Many list endpoints support sorting:
​
sorting
array
Array of sort criteria. Prefix with - for descending order.
Example: 
# Sort by created_at descending, then name ascending
curl "https://api.polar.sh/v1/products?sorting=-created_at&sorting=name" \
  -H "Authorization: Bearer polar_pat_..."

​
Filtering

List endpoints support various filters specific to each resource. Common filters include:
  • organization_id - Filter by organization
  • query - Text search
  • is_archived - Include/exclude archived items

​
Metadata

Many resources support custom metadata for storing additional key-value pairs: 
{
  "name": "Premium Plan",
  "metadata": {
    "internal_id": "plan-001",
    "tier": "premium"
  }
}
Filter by metadata using dot notation: 
curl "https://api.polar.sh/v1/products?metadata.tier=premium" \
  -H "Authorization: Bearer polar_pat_..."

​
Error Responses

Errors return appropriate HTTP status codes and a JSON response: 
{
  "type": "ResourceNotFound",
  "detail": "Product not found."
}

​
Common Status Codes

​
200
OK
Request successful
​
201
Created
Resource created successfully
​
204
No Content
Request successful, no content returned
​
400
Bad Request
Invalid request parameters
​
401
Unauthorized
Missing or invalid authentication
​
403
Forbidden
Insufficient permissions
​
404
Not Found
Resource not found
​
409
Conflict
Resource conflict (e.g., duplicate)
​
422
Unprocessable Entity
Validation error
​
429
Too Many Requests
Rate limit exceeded
​
500
Internal Server Error
Server error

​
Rate Limiting

The Polar API implements rate limiting to ensure fair usage. Rate limit information is included in response headers:
  • X-RateLimit-Limit - Maximum requests allowed
  • X-RateLimit-Remaining - Requests remaining
  • X-RateLimit-Reset - Time when limit resets (Unix timestamp)
When rate limited, you’ll receive a 429 response. Implement exponential backoff in your applications.

​
Idempotency

For safe retries of mutating requests (POST, PATCH, DELETE), use the Idempotency-Key header: 
curl -X POST https://api.polar.sh/v1/products \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Idempotency-Key: unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{"name": "Premium Plan"}'
Requests with the same idempotency key will return the same result.

​
Webhooks

Polar can send webhook notifications for important events. See the Webhooks documentation for setup and event types.

​
SDKs

Official SDKs are available for popular languages:
  • Python: pip install polar-sdk
  • TypeScript/JavaScript: npm install @polar-sh/sdk
  • Go: go get github.com/polarsource/polar-go
See the SDK documentation for usage examples.

​
OpenAPI Specification

The complete OpenAPI specification is available at: 
https://api.polar.sh/v1/openapi.json
Use this to generate clients, explore the API, or import into tools like Postman.

​
Support

For API support:

Build docs developers (and LLMs) love

Get started for freeTalk to us