Skip to main content

​
Overview

Subscriptions represent recurring billing relationships with customers. They automatically renew at specified intervals until canceled.

​
The Subscription Object

​
id
string
required
Unique identifier for the subscription
​
status
enum
required
Status: incomplete, incomplete_expired, trialing, active, past_due, canceled, or unpaid
​
active
boolean
required
Whether the subscription is currently active
​
customer_id
string
required
ID of the customer
​
product_id
string
required
ID of the product
​
price_id
string
required
ID of the price
​
amount
integer
required
Subscription amount in cents
​
currency
string
required
Three-letter ISO currency code
​
recurring_interval
enum
required
Billing interval: month or year
​
current_period_start
string
required
Start of current billing period
​
current_period_end
string
required
End of current billing period
​
cancel_at_period_end
boolean
required
Whether subscription will cancel at period end
​
canceled_at
string
When the subscription was canceled
​
ended_at
string
When the subscription ended
​
trial_start
string
Trial start date
​
trial_end
string
Trial end date
​
discount_id
string
Applied discount ID
​
metadata
object
Custom metadata
​
created_at
string
required
Creation timestamp

​
List Subscriptions

cURL
curl -X GET "https://api.polar.sh/v1/subscriptions" \
  -H "Authorization: Bearer polar_pat_..."

​
Query Parameters

​
organization_id
string
Filter by organization
​
product_id
string
Filter by product
​
customer_id
string
Filter by customer
​
external_customer_id
string
Filter by external customer ID
​
discount_id
string
Filter by discount
​
active
boolean
Filter by active status
​
cancel_at_period_end
boolean
Filter subscriptions set to cancel
​
metadata
object
Filter by metadata

​
Get Subscription

cURL
curl -X GET "https://api.polar.sh/v1/subscriptions/{id}" \
  -H "Authorization: Bearer polar_pat_..."

​
Path Parameters

​
id
string
required
Subscription ID

​
Create Subscription

cURL
curl -X POST "https://api.polar.sh/v1/subscriptions" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_123",
    "product_id": "prod_456",
    "product_price_id": "price_789"
  }'
This endpoint only creates subscriptions for free products. For paid products, use the checkout flow.

​
Request Body

​
customer_id
string
required
Customer ID
​
product_id
string
required
Product ID (must be free)
​
product_price_id
string
required
Price ID
​
metadata
object
Custom metadata

​
Update Subscription

cURL
curl -X PATCH "https://api.polar.sh/v1/subscriptions/{id}" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product_price_id": "price_new"
  }'

​
Path Parameters

​
id
string
required
Subscription ID

​
Request Body

​
product_price_id
string
Change to a different price of the same product
​
metadata
object
Update metadata

​
Errors

​
409
Conflict
Subscription is locked (pending update)

​
Cancel Subscription

cURL
curl -X DELETE "https://api.polar.sh/v1/subscriptions/{id}" \
  -H "Authorization: Bearer polar_pat_..."

​
Path Parameters

​
id
string
required
Subscription ID
This revokes the subscription immediately. The customer loses access right away and no refund is issued.

​
Export Subscriptions

cURL
curl -X GET "https://api.polar.sh/v1/subscriptions/export" \
  -H "Authorization: Bearer polar_pat_..."

​
Query Parameters

​
organization_id
string
Filter by organization

​
Response

Returns a CSV file with subscription data.

​
Get Charge Preview

cURL
curl -X GET "https://api.polar.sh/v1/subscriptions/{id}/charge-preview" \
  -H "Authorization: Bearer polar_pat_..."
Get a preview of the next charge for an active subscription, including:
  • Base subscription amount
  • Metered usage charges
  • Applied discounts
  • Calculated taxes
  • Total amount

​
Path Parameters

​
id
string
required
Subscription ID

​
Response

​
amount
integer
Total amount in cents
​
tax_amount
integer
Tax amount in cents
​
subscription_amount
integer
Base subscription amount
​
metered_amounts
array
Usage-based charges
​
discount_amount
integer
Discount amount

​
Examples

​
Create Free Subscription

curl -X POST "https://api.polar.sh/v1/subscriptions" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_abc123",
    "product_id": "prod_free_tier",
    "product_price_id": "price_free",
    "metadata": {
      "source": "referral"
    }
  }'

​
Change Subscription Plan

curl -X PATCH "https://api.polar.sh/v1/subscriptions/sub_123" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product_price_id": "price_pro_annual"
  }'

​
Cancel Immediately

curl -X DELETE "https://api.polar.sh/v1/subscriptions/sub_123" \
  -H "Authorization: Bearer polar_pat_..."

Build docs developers (and LLMs) love

Get started for freeTalk to us