Polar

https://polar.sh/docs/
Admin
Polar is a complete billing infrastructure and Merchant of Record solution that enables developers...
Tokens:946,609
Snippets:5,534
Trust Score:9.9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Quickstart: Create Polar client and get customer state

Source: https://polar.sh/docs/llms-full.txt

Quickstart example: create a Polar client with an organization access token stored in POLAR_ACCESS_TOKEN and fetch a customer state. The import path pins the client to the 2026-10 API version.

```python
import os

from polar.v2026_10 import Polar

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

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

--------------------------------

### Python SDK: Install and Get Customer State

Source: https://polar.sh/docs/api-reference/customers/update-customer-by-external-id

Install the Python SDK using uv or pip and make a request to get the state of a customer by external ID. Uses the production environment by default; pass `environment="sandbox"` to use the sandbox.

```bash
uv add polar-sdk

```

```bash
pip install polar-sdk

```

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

```

--------------------------------

### Checkout Handler

Source: https://polar.sh/docs/integrate/sdk/adapters/tanstack-start

Documentation for the Checkout handler in the TanStack Start adapter, including installation, handler setup, and query parameters.

```APIDOC
## [GET] /api/checkout

### Description
Creates a Polar Checkout session and redirects the user to the Polar Checkout page. Handles redirections and appends `checkout_id` to the `successUrl`.

### Method
GET

### Endpoint
/api/checkout

### Parameters
#### Query Parameters
- **products** (string) - Required - Product IDs to include in the checkout. Repeat the parameter for multiple products: `?products=123&products=456`
- **customer_id** (string) - Optional - The Polar customer ID.
- **external_customer_id** (string) - Optional - The external customer ID.
- **customer_email** (string) - Optional - The customer's email address.
- **customer_name** (string) - Optional - The customer's name.
- **customer_billing_address** (string) - Optional - URL-Encoded JSON string representing the billing address.
- **customer_tax_id** (string) - Optional - The customer's tax ID.
- **customer_ip_address** (string) - Optional - The customer's IP address.
- **customer_metadata** (string) - Optional - URL-Encoded JSON string of customer metadata.
- **allow_discount_codes** (boolean) - Optional - Whether to allow discount codes. Defaults to `true`.
- **discount_id** (string) - Optional - The discount ID to apply.
- **discount_code** (string) - Optional - The discount code to apply. Applied before redirecting. `discount_id` takes precedence when both are supplied.
- **seats** (integer) - Optional - Number of seats for seat-based products.
- **metadata** (string) - Optional - URL-Encoded JSON string of metadata.

### Request Example
```
GET /api/checkout?products=123&products=456&customer_email=janedoe@gmail.com
```

### Response
#### Success Response (302)
Redirects to the Polar Checkout page.

#### Error Responses
- **400** - Returned when `products` is missing.
- **500** - Returned when the checkout can't be created.

```

--------------------------------

### Initialize Python SDK

Source: https://polar.sh/docs/api-reference/subscriptions/update-subscription

Example of initializing the Polar client and fetching customer state in Python.

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

--------------------------------

### 200 response example

Source: https://polar.sh/docs/api-reference/2026-10/meters/get-meter-quantities

Example 200 response body for the get meter quantities endpoint.

```json
{
  "quantities": [
    {
      "timestamp": "2026-01-01T00:00:00.000000Z",
      "quantity": 10
    }
  ],
  "total": 100
}
```

--------------------------------

### Install with bun

Source: https://polar.sh/docs/integrate/sdk/adapters/tanstack-start

Install the @polar-sh/tanstack-start package using bun.

```bash
bun add @polar-sh/tanstack-start

```

--------------------------------

### Install with npm

Source: https://polar.sh/docs/integrate/sdk/adapters/tanstack-start

Install the @polar-sh/tanstack-start package using npm.

```bash
npm install @polar-sh/tanstack-start

```

--------------------------------

### 200 response example

Source: https://polar.sh/docs/api-reference/2026-10/benefits/get-benefit

Example 200 response body for a successful GET /v1/benefits/{id} request.

```json
{
  "id": "<string>",
  "created_at": "2026-01-01T00:00:00.000000Z",
  "modified_at": "2026-01-01T00:00:00.000000Z",
  "type": "custom",
  "description": "<string>",
  "selectable": true,
  "deletable": true,
  "is_deleted": true,
  "organization_id": "<string>",
  "metadata": {},
  "visibility": "draft",
  "properties": {
    "note": "<string>"
  },
  "visibility_configurable": true
}
```

--------------------------------

### Get Checkout Session

Source: https://polar.sh/docs/api-reference/2026-10/checkouts/get-checkout-session

Retrieve a checkout session by its ID. The Python and TypeScript examples use the Polar SDK with an access token and the checkout ID. The curl example sends a GET request to the API endpoint with an Authorization header.

```python
from polar.v2026_10 import Polar

polar = Polar("polar_oat_xxx")

response = polar.checkouts.get(
    '00000000-0000-4000-8000-000000000000',
)
print(response)
```

```typescript
import { createPolar } from "@polar-sh/sdk/2026-10";

const polar = createPolar({
  accessToken: "polar_oat_xxx",
});

const response = await polar.checkouts.get(
  "00000000-0000-4000-8000-000000000000",
);
console.log(response);
```

```bash
curl --request GET \
  --url https://api.polar.sh/v1/checkouts/{id} \
  --header 'Authorization: Bearer <token>'
```

--------------------------------

### Install with yarn

Source: https://polar.sh/docs/integrate/sdk/adapters/tanstack-start

Install the @polar-sh/tanstack-start package using yarn.

```bash
yarn add @polar-sh/tanstack-start

```

--------------------------------

### Quick-start script: npx polar-init

Source: https://polar.sh/docs/guides/nextjs

Run inside a new Next.js project to quickly scaffold Polar integration.

```bash
# Inside a new Next.js project
npx polar-init

```

--------------------------------

### Get meter quantities

Source: https://polar.sh/docs/integrate/cli/reference/meters

Command to get quantities of a meter over a time period. Requires start and end timestamps and an interval.

```bash
polar meters quantities [flags] <id>
```

--------------------------------

### Install Python SDK with uv or pip

Source: https://polar.sh/docs/llms-full.txt

Install the Python SDK using either uv or pip. Requires Python 3.11 or later.

```bash
uv add polar-sdk
```

```bash
pip install polar-sdk
```

--------------------------------

### TypeScript SDK: Install and Get Customer State

Source: https://polar.sh/docs/api-reference/customers/update-customer-by-external-id

Install the TypeScript SDK and make a request to get the state of a customer by external ID. Uses the production environment by default; pass `environment: "sandbox"` to use the sandbox.

```bash
npm install @polar-sh/sdk

```

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

```

--------------------------------

### Run migrations

Source: https://polar.sh/docs/llms-full.txt

Run the migration to create the webhook calls table.

```bash
php artisan migrate
```

--------------------------------

### 200 Response: Get metrics

Source: https://polar.sh/docs/api-reference/2026-10/metrics/get-metrics

Example successful response from the GET /v1/metrics endpoint. Contains a periods array with metric values and a totals object.

```JSON
{
  "periods": [
    {
      "timestamp": "2026-01-01T00:00:00.000000Z",
      "active_subscriptions": 123,
      "committed_subscriptions": 123,
      "monthly_recurring_revenue": 123,
      "trial_monthly_recurring_revenue": 123,
      "committed_monthly_recurring_revenue": 123,
      "trial_committed_monthly_recurring_revenue": 123,
      "average_revenue_per_user": 123,
      "checkouts": 123,
      "succeeded_checkouts": 123,
      "churned_subscriptions": 123,
      "churn_rate": 123,
      "seats_total": 123,
      "seats_claimed": 123,
      "seats_pending": 123,
      "seat_customers": 123,
      "new_seat_customers": 123,
      "churned_seat_customers": 123,
      "orders": 123,
      "revenue": 123,
      "net_revenue": 123,
      "cumulative_revenue": 123,
      "net_cumulative_revenue": 123,
      "costs": 123,
      "cumulative_costs": 123,
      "average_order_value": 123,
      "net_average_order_value": 123,
      "cost_per_user": 123,
      "active_user_by_event": 123,
      "one_time_products": 123,
      "one_time_products_revenue": 123,
      "one_time_products_net_revenue": 123,
      "new_subscriptions": 123,
      "new_subscriptions_revenue": 123,
      "new_subscriptions_net_revenue": 123,
      "renewed_subscriptions": 123,
      "renewed_subscriptions_revenue": 123,
      "renewed_subscriptions_net_revenue": 123,
      "canceled_subscriptions": 123,
      "canceled_subscriptions_customer_service": 123,
      "canceled_subscriptions_low_quality": 123,
      "canceled_subscriptions_missing_features": 123,
      "canceled_subscriptions_switched_service": 123,
      "canceled_subscriptions_too_complex": 123,
      "canceled_subscriptions_too_expensive": 123,
      "canceled_subscriptions_unused": 123,
      "canceled_subscriptions_other": 123,
      "annual_recurring_revenue": 123,
      "committed_annual_recurring_revenue": 123,
      "checkouts_conversion": 123,
      "ltv": 123,
      "gross_margin": 123,
      "gross_margin_percentage": 123,
      "cashflow": 123,
      "average_seats_per_customer": 123,
      "seat_utilization_rate": 123
    }
  ],
  "totals": {
    "active_subscriptions": 123,
    "committed_subscriptions": 123,
    "monthly_recurring_revenue": 123,
    "trial_monthly_recurring_revenue": 123,
    "committed_monthly_recurring_revenue": 123,
    "trial_committed_monthly_recurring_revenue": 123,
    "average_revenue_per_user": 123,
    "checkouts": 123,
    "succeeded_checkouts": 123,
    "churned_subscriptions": 123,
    "churn_rate": 123,
    "seats_total": 123,
    "seats_claimed": 123,
    "seats_pending": 123,
    "seat_customers": 123,
    "new_seat_customers": 123,
    "churned_seat_customers": 123,
    "orders": 123,
    "revenue": 123,
    "net_revenue": 123,
    "cumulative_revenue": 123,
    "net_cumulative_revenue": 123,
    "costs": 123,
    "cumulative_costs": 123,
    "average_order_value": 123,
    "net_average_order_value": 123,
    "cost_per_user": 123,
    "active_user_by_event": 123,
    "one_time_products": 123,
    "one_time_products_revenue": 123,
    "one_time_products_net_revenue": 123,
    "new_subscriptions": 123,
    "new_subscriptions_revenue": 123,
    "new_subscriptions_net_revenue": 123,
    "renewed_subscriptions": 123,
    "renewed_subscriptions_revenue": 123,
    "renewed_subscriptions_net_revenue": 123,
    "canceled_subscriptions": 123,
    "canceled_subscriptions_customer_service": 123,
    "canceled_subscriptions_low_quality": 123,
    "canceled_subscriptions_missing_features": 123,
    "canceled_subscriptions_switched_service": 123,
    "canceled_subscriptions_too_complex": 123,
    "canceled_subscriptions_too_expensive": 123,
    "canceled_subscriptions_unused": 123,
    "canceled_subscriptions_other": 123,
    "annual_recurring_revenue": 123,
    "committed_annual_recurring_revenue": 123,
    "checkouts_conversion": 123,
    "ltv": 123,
    "gross_margin": 123,
    "gross_margin_percentage": 123,
    "cashflow": 123,
    "average_seats_per_customer": 123,
    "seat_utilization_rate": 123
  }
}
```

--------------------------------

### Install with pnpm

Source: https://polar.sh/docs/integrate/sdk/adapters/tanstack-start

Install the @polar-sh/tanstack-start package using pnpm.

```bash
pnpm add @polar-sh/tanstack-start

```

--------------------------------

### Get customer 200 response

Source: https://polar.sh/docs/api-reference/2026-10/customer_portal/get-customer

Example 200 response body for the GET /v1/customer-portal/customers/me endpoint. Shows the structure of the authenticated customer object.

```json
{
  "created_at": "2026-01-01T00:00:00.000000Z",
  "modified_at": "2026-01-01T00:00:00.000000Z",
  "id": "<string>",
  "email": "<string>",
  "email_verified": true,
  "name": "<string>",
  "billing_name": "<string>",
  "billing_address": {
    "country": "US",
    "line1": "<string>",
    "line2": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "state": "<string>"
  },
  "tax_id": {
    "[0]": "<string>"
  },
  "oauth_accounts": {},
  "default_payment_method_id": "<string>",
  "type": "individual",
  "locale": "<string>"
}
```

--------------------------------

### Initialize TypeScript SDK

Source: https://polar.sh/docs/api-reference/subscriptions/update-subscription

Example of initializing the Polar client and fetching customer state in TypeScript.

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

--------------------------------

### GET /v1/meters/{id}/quantities

Source: https://polar.sh/docs/api-reference/2026-10/meters/get-meter-quantities

This snippet documents the GET /v1/meters/{id}/quantities endpoint, including its parameters, request example, and response schema.

```APIDOC
## GET /v1/meters/{id}/quantities

### Description
Get meter quantities for a specific meter, optionally filtered by external customer ID and metadata, with aggregation options.

### Method
GET

### Endpoint
`/v1/meters/{id}/quantities`

### Parameters
#### Path Parameters
- **id** (string) - Required - The meter ID.

#### Query Parameters
- **start_timestamp** (string) - Required - Start timestamp for the quantities period.
- **end_timestamp** (string) - Required - End timestamp for the quantities period.
- **interval** (string) - Required - Aggregation interval (e.g., `year`).
- **timezone** (string) - Required - Timezone for the aggregation.
- **customer_id** (string | string[]) - Optional - Filter by external customer ID.
- **customer_aggregation_function** (enum<string> | null) - Optional - If set, computes quantities per customer before aggregating using the given function. Options: `count`, `sum`, `max`, `min`, `avg`, `unique`.
- **metadata** (MetadataQuery · object | null) - Optional - Filter by metadata key-value pairs using `deepObject` style, e.g. `?metadata[key]=value`.

### Request Example
```
curl --request GET \
  --url https://api.polar.sh/v1/meters/{id}/quantities \
  --header 'Authorization: Bearer <token>'
```

### Response
#### Success Response (200)
- **quantities** (MeterQuantity[] · object[]) - Required - Array of meter quantities.
- **total** (number) - Required - The total quantity for the period.

#### Response Example
```json
{
  "quantities": [
    {
      "timestamp": "2026-01-01T00:00:00.000000Z",
      "quantity": 10
    }
  ],
  "total": 100
}
```

#### Error Responses
- **404** - Resource not found.
- **422** - Validation error.

#### Error Response Examples
```json
{
  "error": "ResourceNotFound",
  "detail": "<string>"
}
```

```json
{
  "detail": [
    {
      "loc": ["<string>"],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}
```
```

--------------------------------

### Install @polar-sh/tanstack-start with npm, yarn, pnpm, or bun

Source: https://polar.sh/docs/llms-full.txt

Install the @polar-sh/tanstack-start package using your preferred package manager. Choose the command that matches your environment.

```bash
npm install @polar-sh/tanstack-start
```

```bash
yarn add @polar-sh/tanstack-start
```

```bash
pnpm add @polar-sh/tanstack-start
```

```bash
bun add @polar-sh/tanstack-start
```

--------------------------------

### polar auth login examples

Source: https://polar.sh/docs/integrate/cli/reference/auth

Examples for signing in to Polar. The first example signs in using the default environment. The second signs in to the sandbox environment. The third signs in to production again, replacing the saved session.

```bash
polar auth login

```

```bash
polar auth login --sandbox

```

```bash
polar auth login --production --new-session

```

--------------------------------

### List Checkouts API Request Examples

Source: https://polar.sh/docs/api-reference/2026-10/checkouts/list-checkout-sessions

Send a GET request to the Polar API list checkouts endpoint with an Authorization header. The Go example uses the standard library, the Java example uses Unirest, and the Ruby example uses Net::HTTP with SSL enabled.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.polar.sh/v1/checkouts/?page=1&limit=10"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```java
HttpResponse<String> response = Unirest.get("https://api.polar.sh/v1/checkouts/?page=1&limit=10")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.polar.sh/v1/checkouts/?page=1&limit=10")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Query subscriptions with scopes

Source: https://polar.sh/docs/integrate/sdk/adapters/laravel

Queries subscriptions in specific states using scopes. The first example gets all active subscriptions, the second gets cancelled subscriptions for a specific user.

```php
// Get all active subscriptions...
$subscriptions = Subscription::query()->active()->get();

// Get all of the cancelled subscriptions for a specific user...
$subscriptions = $user->subscriptions()->cancelled()->get();

```

--------------------------------

### Install Python SDK with uv

Source: https://polar.sh/docs/api-reference/2026-10/introduction

Install the official Polar Python SDK using uv.

```bash
uv add polar-sdk

```

--------------------------------

### 200 response body for Get Checkout Session

Source: https://polar.sh/docs/api-reference/2026-10/checkouts/get-checkout-session

Example 200 response body for a successful GET /v1/checkouts/{id} request. Shows the full checkout session object structure.

```json
{
  "id": "<string>",
  "created_at": "2026-01-01T00:00:00.000000Z",
  "modified_at": "2026-01-01T00:00:00.000000Z",
  "payment_processor": "stripe",
  "status": "open",
  "client_secret": "<string>",
  "url": "<string>",
  "expires_at": "2026-01-01T00:00:00.000000Z",
  "success_url": "<string>",
  "return_url": "<string>",
  "embed_origin": "<string>",
  "amount": 123,
  "units": 123,
  "min_units": 123,
  "max_units": 123,
  "discount_amount": 123,
  "net_amount": 123,
  "tax_amount": 123,
  "tax_behavior": "inclusive",
  "total_amount": 123,
  "currency": "<string>",
  "allow_trial": true,
  "active_trial_interval": "day",
  "active_trial_interval_count": 123,
  "trial_end": "2026-01-01T00:00:00.000000Z",
  "organization_id": "<string>",
  "product_id": "<string>",
  "product_price_id": "<string>",
  "discount_id": "<string>",
  "allow_discount_codes": true,
  "require_billing_address": true,
  "is_discount_applicable": true,
  "is_free_product_price": true,
  "is_payment_required": true,
  "is_payment_setup_required": true,
  "is_payment_form_required": true,
  "customer_id": "<string>",
  "is_business_customer": true,
  "customer_name": "<string>",
  "customer_email": "<string>",
  "customer_ip_address": "<string>",
  "customer_billing_name": "<string>",
  "customer_billing_address": {
    "country": "US",
    "line1": "<string>",
    "line2": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "state": "<string>"
  },
  "customer_tax_id": "<string>",
  "payment_method_type": "<string>",
  "payment_processor_metadata": {},
  "billing_address_fields": {
    "country": "required",
    "state": "required",
    "city": "required",
    "postal_code": "required",
    "line1": "required",
    "line2": "required"
  },
  "trial_interval": "day",
  "trial_interval_count": 123,
  "metadata": {},
  "external_customer_id": "<string>",
  "products": [
    {
      "id": "<string>",
      "created_at": "2026-01-01T00:00:00.000000Z",
      "modified_at": "2026-01-01T00:00:00.000000Z",
      "trial_interval": "day",
      "trial_interval_count": 123,
      "name": "<string>",
      "description": "<string>",
      "visibility": "draft",
      "recurring_interval": "day",
      "recurring_interval_count": 123,
      "meter_interval": "day",
      "meter_interval_count": 123,
      "is_recurring": true,
      "is_archived": true,
      "organization_id": "<string>",
      "prices": [
        {
          "id": "<string>",
          "created_at": "2026-01-01T00:00:00.000000Z",
          "modified_at": "2026-01-01T00:00:00.000000Z",
          "amount": 123,
          "currency": "<string>",
          "type": "recurring",
          "recurring_interval": "day",
          "recurring_interval_count": 123
        }
      ]
    }
  ]
}
```

--------------------------------

### Quick Examples

Source: https://polar.sh/docs/api-reference/subscriptions/get-subscription

Quick examples for listing products and orders using the Polar API, including production, sandbox, and customer portal endpoints.

```APIDOC
## GET /v1/products/

### Description
List products from the Polar Core API. This endpoint supports pagination to efficiently retrieve large datasets.

### Method
GET

### Endpoint
https://api.polar.sh/v1/products/

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number, starting from 1. Default: 1.
- **limit** (integer) - Optional - Number of items to return per page (window size). Default: 10. Max: 100.

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

### Response
#### Success Response (200)
- **items** (array) - List of products.
- **pagination** (object) - Pagination metadata.
  - **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.

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

```APIDOC
## GET /v1/products/ (Sandbox)

### Description
List products from the Polar Core API in the sandbox environment. This endpoint supports pagination to efficiently retrieve large datasets.

### Method
GET

### Endpoint
https://sandbox-api.polar.sh/v1/products/

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number, starting from 1. Default: 1.
- **limit** (integer) - Optional - Number of items to return per page (window size). Default: 10. Max: 100.

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

### Response
#### Success Response (200)
- **items** (array) - List of products.
- **pagination** (object) - Pagination metadata.
  - **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.

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

```APIDOC
## GET /v1/customer-portal/orders/

### Description
List orders from the Polar Customer Portal API. This endpoint supports pagination to efficiently retrieve large datasets.

### Method
GET

### Endpoint
https://api.polar.sh/v1/customer-portal/orders/

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number, starting from 1. Default: 1.
- **limit** (integer) - Optional - Number of items to return per page (window size). Default: 10. Max: 100.

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

### Response
#### Success Response (200)
- **items** (array) - List of orders.
- **pagination** (object) - Pagination metadata.
  - **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.

#### Response Example
```
{
  "items": [
    {
      "id": "...",
      ...
    },
    ...
  ],
  "pagination": {
    "total_count": 250,
    "max_page": 3
  }
}
```
```

--------------------------------

### 200 response example

Source: https://polar.sh/docs/api-reference/2026-10/customer_portal/get-subscription

Example 200 response body for the GET /v1/customer-portal/subscriptions/{id} endpoint. Shows the subscription object with fields like status, amount, currency, and nested product and benefits.

```json
{
  "created_at": "2026-01-01T00:00:00.000000Z",
  "modified_at": "2026-01-01T00:00:00.000000Z",
  "id": "<string>",
  "amount": 10000,
  "currency": "usd",
  "recurring_interval": "month",
  "recurring_interval_count": 123,
  "status": "active",
  "current_period_start": "2026-01-01T00:00:00.000000Z",
  "current_period_end": "2026-01-01T00:00:00.000000Z",
  "current_meter_period_start": "2026-01-01T00:00:00.000000Z",
  "current_meter_period_end": "2026-01-01T00:00:00.000000Z",
  "trial_start": "2026-01-01T00:00:00.000000Z",
  "trial_end": "2026-01-01T00:00:00.000000Z",
  "cancel_at_period_end": true,
  "canceled_at": "2026-01-01T00:00:00.000000Z",
  "started_at": "2026-01-01T00:00:00.000000Z",
  "ends_at": "2026-01-01T00:00:00.000000Z",
  "ended_at": "2026-01-01T00:00:00.000000Z",
  "pause_at_period_end": true,
  "paused_at": "2026-01-01T00:00:00.000000Z",
  "resumes_at": "2026-01-01T00:00:00.000000Z",
  "customer_id": "<string>",
  "product_id": "<string>",
  "discount_id": "<string>",
  "checkout_id": "<string>",
  "units": 123,
  "customer_cancellation_reason": "customer_service",
  "customer_cancellation_comment": "<string>",
  "product": {
    "id": "<string>",
    "created_at": "2026-01-01T00:00:00.000000Z",
    "modified_at": "2026-01-01T00:00:00.000000Z",
    "trial_interval": "day",
    "trial_interval_count": 123,
    "name": "<string>",
    "description": "<string>",
    "visibility": "draft",
    "recurring_interval": "day",
    "recurring_interval_count": 123,
    "meter_interval": "day",
    "meter_interval_count": 123,
    "is_recurring": true,
    "is_archived": true,
    "organization_id": "<string>",
    "prices": [
      {
        "created_at": "2026-01-01T00:00:00.000000Z",
        "modified_at": "2026-01-01T00:00:00.000000Z",
        "id": "<string>",
        "source": "catalog",
        "amount_type": "fixed",
        "price_currency": "<string>",
        "tax_behavior": "location",
        "is_archived": true,
        "product_id": "<string>",
        "type": "recurring",
        "recurring_interval": "day",
        "price_amount": 123,
        "legacy": true
      }
    ],
    "benefits": [
      {
        "id": "<string>",
```

--------------------------------

### Polar API Quick Examples (Production, Sandbox, Customer Portal)

Source: https://polar.sh/docs/llms-full.txt

Quick examples for the Polar API: production Core API, sandbox Core API, and Customer Portal API. Use the appropriate base URL and bearer token for each environment.

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

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

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

--------------------------------

### Get Customer Meter 200 Response

Source: https://polar.sh/docs/api-reference/2026-10/customer_meters/get-customer-meter

Example 200 response body for a successful get customer meter request. Shows the full customer meter object including customer and meter details.

```json
{
  "id": "<string>",
  "created_at": "2026-01-01T00:00:00.000000Z",
  "modified_at": "2026-01-01T00:00:00.000000Z",
  "customer_id": "992fae2a-2a17-4b7a-8d9e-e287cf90131b",
  "meter_id": "d498a884-e2cd-4d3e-8002-f536468a8b22",
  "consumed_units": 25,
  "credited_units": 100,
  "balance": 75,
  "customer": {
    "id": "992fae2a-2a17-4b7a-8d9e-e287cf90131b",
    "created_at": "2026-01-01T00:00:00.000000Z",
    "modified_at": "2026-01-01T00:00:00.000000Z",
    "metadata": {},
    "email": "customer@example.com",
    "email_verified": true,
    "type": "individual",
    "name": "John Doe",
    "billing_name": "John Doe",
    "billing_address": {
      "country": "US",
      "line1": "<string>",
      "line2": "<string>",
      "postal_code": "<string>",
      "city": "<string>",
      "state": "<string>"
    },
    "tax_id": {
      "[0]": "<string>"
    },
    "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
    "deleted_at": "2026-01-01T00:00:00.000000Z",
    "first_user_event_at": "2026-01-01T00:00:00.000000Z",
    "avatar_url": "https://www.gravatar.com/avatar/xxx?d=404",
    "external_id": "usr_1337",
    "locale": "<string>",
    "default_payment_method_id": "<string>"
  },
  "meter": {
    "metadata": {},
    "created_at": "2026-01-01T00:00:00.000000Z",
    "modified_at": "2026-01-01T00:00:00.000000Z",
    "id": "<string>",
    "name": "<string>",
    "unit": "scalar",
    "filter": {
      "conjunction": "and",
      "clauses": [
        {
          "property": "<string>",
          "operator": "eq",
          "value": "<string>"
        }
      ]
    },
    "aggregation": {
      "func": "count"
    },
    "organization_id": "<string>",
    "custom_label": "<string>",
    "custom_multiplier": 123,
    "archived_at": "2026-01-01T00:00:00.000000Z"
  }
}
```
Tokens:
Raw