Subscriptions
June 12, 2026 ยท View on GitHub
(subscriptions)
Overview
Available Operations
- list - List Subscriptions
- create - Create Subscription
- export - Export Subscriptions
- get - Get Subscription
- update - Update Subscription
- revoke - Revoke Subscription
list
List subscriptions.
Scopes: subscriptions:read subscriptions:write
Example Usage
from polar_sdk import Polar
with Polar(
access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:
res = polar.subscriptions.list(organization_id="1dbfc517-0bbf-4301-9ba8-555ca42b9737", page=1, limit=10)
while res is not None:
# Handle items
res = res.next()
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
organization_id | OptionalNullable[models.OrganizationIDFilter] | :heavy_minus_sign: | Filter by organization ID. |
product_id | OptionalNullable[models.ProductIDFilter] | :heavy_minus_sign: | Filter by product ID. |
customer_id | OptionalNullable[models.CustomerIDFilter] | :heavy_minus_sign: | Filter by customer ID. |
external_customer_id | OptionalNullable[models.ExternalCustomerIDFilter] | :heavy_minus_sign: | Filter by customer external ID. |
discount_id | OptionalNullable[models.DiscountIDFilter] | :heavy_minus_sign: | Filter by discount ID. |
active | OptionalNullable[bool] | :heavy_minus_sign: | : warning: ** DEPRECATED **: This will be removed in a future release, please migrate away from it as soon as possible. Filter by active or inactive subscription. |
status | OptionalNullable[models.StatusFilter] | :heavy_minus_sign: | Filter by subscription status. |
cancel_at_period_end | OptionalNullable[bool] | :heavy_minus_sign: | Filter by subscriptions that are set to cancel at period end. |
customer_cancellation_reason | OptionalNullable[models.CustomerCancellationReasonFilter] | :heavy_minus_sign: | Filter by customer cancellation reason. |
canceled_at_after | date | :heavy_minus_sign: | Filter by cancellation date (after or equal to). |
canceled_at_before | date | :heavy_minus_sign: | Filter by cancellation date (before or equal to). |
page | Optional[int] | :heavy_minus_sign: | Page number, defaults to 1. |
limit | Optional[int] | :heavy_minus_sign: | Size of a page, defaults to 10. Maximum is 100. |
sorting | List[models.SubscriptionSortProperty] | :heavy_minus_sign: | Sorting criterion. Several criteria can be used simultaneously and will be applied in order. Add a minus sign - before the criteria name to sort by descending order. |
metadata | Dict[str, models.MetadataQuery] | :heavy_minus_sign: | Filter by metadata key-value pairs. It uses the deepObject style, e.g. ?metadata[key]=value. |
retries | Optional[utils.RetryConfig] | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. |
Response
models.SubscriptionsListResponse
Errors
| Error Type | Status Code | Content Type |
|---|---|---|
| models.HTTPValidationError | 422 | application/json |
| models.SDKError | 4XX, 5XX | */* |
create
Create a subscription programmatically.
This endpoint only allows to create subscription on free products. For paid products, use the checkout flow.
No initial order will be created and no confirmation email will be sent.
Scopes: subscriptions:write
Example Usage
from polar_sdk import Polar
with Polar(
access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:
res = polar.subscriptions.create(request={
"product_id": "d8dd2de1-21b7-4a41-8bc3-ce909c0cfe23",
"customer_id": "992fae2a-2a17-4b7a-8d9e-e287cf90131b",
})
# Handle response
print(res)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
request | models.SubscriptionsCreateSubscriptionCreate | :heavy_check_mark: | The request object to use for the request. |
retries | Optional[utils.RetryConfig] | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. |
Response
Errors
| Error Type | Status Code | Content Type |
|---|---|---|
| models.HTTPValidationError | 422 | application/json |
| models.SDKError | 4XX, 5XX | */* |
export
Export subscriptions as a CSV file.
Scopes: subscriptions:read subscriptions:write
Example Usage
from polar_sdk import Polar
with Polar(
access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:
res = polar.subscriptions.export(organization_id="1dbfc517-0bbf-4301-9ba8-555ca42b9737")
# Handle response
print(res)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
organization_id | OptionalNullable[models.OrganizationID] | :heavy_minus_sign: | Filter by organization ID. |
retries | Optional[utils.RetryConfig] | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. |
Response
models.SubscriptionsExportResponse
Errors
| Error Type | Status Code | Content Type |
|---|---|---|
| models.HTTPValidationError | 422 | application/json |
| models.SDKError | 4XX, 5XX | */* |
get
Get a subscription by ID.
Scopes: subscriptions:read subscriptions:write
Example Usage
from polar_sdk import Polar
with Polar(
access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:
res = polar.subscriptions.get(id="<value>")
# Handle response
print(res)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | str | :heavy_check_mark: | The subscription ID. |
retries | Optional[utils.RetryConfig] | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. |
Response
Errors
| Error Type | Status Code | Content Type |
|---|---|---|
| models.ResourceNotFound | 404 | application/json |
| models.HTTPValidationError | 422 | application/json |
| models.SDKError | 4XX, 5XX | */* |
update
Update a subscription.
Scopes: subscriptions:write
Example Usage
from polar_sdk import Polar
with Polar(
access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:
res = polar.subscriptions.update(id="<value>", subscription_update={
"product_id": "<value>",
})
# Handle response
print(res)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | str | :heavy_check_mark: | The subscription ID. |
subscription_update | models.SubscriptionUpdate | :heavy_check_mark: | N/A |
retries | Optional[utils.RetryConfig] | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. |
Response
Errors
| Error Type | Status Code | Content Type |
|---|---|---|
| models.PaymentFailed | 402 | application/json |
| models.AlreadyCanceledSubscription | 403 | application/json |
| models.ResourceNotFound | 404 | application/json |
| models.SubscriptionLocked | 409 | application/json |
| models.HTTPValidationError | 422 | application/json |
| models.SDKError | 4XX, 5XX | */* |
revoke
Revoke a subscription, i.e cancel immediately.
Scopes: subscriptions:write
Example Usage
from polar_sdk import Polar
with Polar(
access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:
res = polar.subscriptions.revoke(id="<value>")
# Handle response
print(res)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | str | :heavy_check_mark: | The subscription ID. |
retries | Optional[utils.RetryConfig] | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. |
Response
Errors
| Error Type | Status Code | Content Type |
|---|---|---|
| models.AlreadyCanceledSubscription | 403 | application/json |
| models.ResourceNotFound | 404 | application/json |
| models.SubscriptionLocked | 409 | application/json |
| models.HTTPValidationError | 422 | application/json |
| models.SDKError | 4XX, 5XX | */* |