Skip to main content
Customers can view their active and past subscriptions, update subscription plans, adjust seat counts, and cancel subscriptions through the Customer Portal API.

​
List Subscriptions

Retrieve all subscriptions for the authenticated customer. 
GET /v1/customer-portal/subscriptions

​
Query Parameters

​
product_id
string[]
Filter by product ID(s).
​
active
boolean
Filter by active (true) or cancelled (false) status.
​
query
string
Search by product or organization name.
​
limit
number
default:"10"
Number of results per page (max 100).
​
page
number
default:"1"
Page number for pagination.

​
Response

​
items
Subscription[]
Array of subscription objects.
​
pagination
object
Pagination metadata with total_count and page.

​
Example

curl https://api.polar.sh/v1/customer-portal/subscriptions?active=true \
  -H "Authorization: Bearer polar_cst_..."
Response: 
{
  "items": [
    {
      "id": "sub_1a2b3c4d",
      "status": "active",
      "started_at": "2024-01-01T00:00:00Z",
      "current_period_start": "2024-02-01T00:00:00Z",
      "current_period_end": "2024-03-01T00:00:00Z",
      "cancel_at_period_end": false,
      "ended_at": null,
      "product": {
        "id": "prod_abc123",
        "name": "Pro Plan",
        "description": "Professional features",
        "organization": {
          "id": "org_xyz",
          "name": "Acme Inc",
          "slug": "acme"
        },
        "prices": [{
          "id": "price_123",
          "amount": 2900,
          "currency": "USD",
          "recurring_interval": "month"
        }],
        "benefits": [],
        "medias": []
      },
      "prices": [{
        "id": "price_123",
        "amount": 2900,
        "currency": "USD",
        "recurring_interval": "month"
      }],
      "amount": 2900,
      "currency": "USD",
      "recurring_interval": "month",
      "seats": 1,
      "meters": []
    }
  ],
  "pagination": {
    "total_count": 1,
    "page": 1
  }
}

​
Get Subscription

Retrieve a single subscription by ID. 
GET /v1/customer-portal/subscriptions/{id}

​
Path Parameters

​
id
string
required
The subscription ID.

​
Response

Returns a subscription object with full details including product, pricing, and benefits.

​
Example

curl https://api.polar.sh/v1/customer-portal/subscriptions/sub_1a2b3c4d \
  -H "Authorization: Bearer polar_cst_..."

​
Preview Next Charge

Get a preview of the upcoming charge for an active subscription, including metered usage. 
GET /v1/customer-portal/subscriptions/{id}/charge-preview

​
Path Parameters

​
id
string
required
The subscription ID.

​
Response

​
amount
number
Total amount to be charged (in cents).
​
currency
string
Currency code (USD, EUR, etc.).
​
line_items
array
Breakdown of charges including base price and metered usage.
​
period_start
string
Start of the billing period.
​
period_end
string
End of the billing period.

​
Example

curl https://api.polar.sh/v1/customer-portal/subscriptions/sub_1a2b3c4d/charge-preview \
  -H "Authorization: Bearer polar_cst_..."
Response: 
{
  "amount": 4200,
  "currency": "USD",
  "period_start": "2024-02-01T00:00:00Z",
  "period_end": "2024-03-01T00:00:00Z",
  "line_items": [
    {
      "description": "Pro Plan",
      "amount": 2900,
      "quantity": 1
    },
    {
      "description": "API Usage (1,300 requests)",
      "amount": 1300,
      "quantity": 1300
    }
  ]
}
Charge previews are only available for active subscriptions with an upcoming renewal.

​
Update Subscription

Modify a subscription’s plan, seats, or cancellation status. 
PATCH /v1/customer-portal/subscriptions/{id}

​
Path Parameters

​
id
string
required
The subscription ID.

​
Request Body

The request body can contain one of the following update types: Switch Product:
​
product_id
string
ID of the product to switch to (upgrade/downgrade).
Update Seats:
​
seats
number
New seat count (minimum 1).
​
proration_behavior
string
How to handle prorations: create_prorations (default) or always_invoice.
Cancel Subscription:
​
cancel_at_period_end
boolean
Set to true to cancel at period end, false to uncancel.
​
cancellation_reason
string
Reason for cancellation: too_expensive, missing_features, switched_service, unused, customer_service, low_quality, too_complex, or other.
​
cancellation_comment
string
Free-form feedback about why the customer is canceling.

​
Examples

Switch to Different Product: 
curl -X PATCH https://api.polar.sh/v1/customer-portal/subscriptions/sub_1a2b3c4d \
  -H "Authorization: Bearer polar_cst_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_enterprise123"
  }'
Update Seat Count: 
curl -X PATCH https://api.polar.sh/v1/customer-portal/subscriptions/sub_1a2b3c4d \
  -H "Authorization: Bearer polar_cst_..." \
  -H "Content-Type: application/json" \
  -d '{
    "seats": 5,
    "proration_behavior": "create_prorations"
  }'
Cancel at Period End: 
curl -X PATCH https://api.polar.sh/v1/customer-portal/subscriptions/sub_1a2b3c4d \
  -H "Authorization: Bearer polar_cst_..." \
  -H "Content-Type: application/json" \
  -d '{
    "cancel_at_period_end": true,
    "cancellation_reason": "too_expensive",
    "cancellation_comment": "Need to reduce costs this quarter"
  }'
Subscription updates require the organization to enable customer-initiated changes. If disabled, you’ll receive a 403 error.

​
Cancel Subscription

Immediately cancel a subscription (alternative to setting cancel_at_period_end). 
DELETE /v1/customer-portal/subscriptions/{id}

​
Path Parameters

​
id
string
required
The subscription ID.

​
Response

Returns the updated subscription object with cancel_at_period_end set to true.

​
Example

curl -X DELETE https://api.polar.sh/v1/customer-portal/subscriptions/sub_1a2b3c4d \
  -H "Authorization: Bearer polar_cst_..."
This sets the subscription to cancel at the end of the current billing period. The customer retains access until then.

​
Permissions

Subscription management requires appropriate permissions:
  • List/Get: Any authenticated customer or member
  • Update/Cancel: Customer or member with billing_manager or owner role
Attempting to update or cancel without permission returns: 
{
  "error": "not_permitted",
  "detail": "Only owners and billing managers can access billing features."
}

​
Subscription States

Subscriptions can be in the following states:
  • active: Currently active and renewing
  • trialing: In trial period
  • canceled: Set to cancel at period end (still active)
  • past_due: Payment failed, retrying
  • unpaid: Payment failed permanently
  • incomplete: Initial payment not completed
  • incomplete_expired: Initial payment expired

​
Proration Behavior

When updating seats or switching products mid-cycle, you can control how prorations are handled:
  • create_prorations (default): Creates credit for unused time and charges for new time
  • always_invoice: Immediately invoices any additional charges
The organization’s default proration setting is used if not specified.

Build docs developers (and LLMs) love

Get started for freeTalk to us