Skip to content

README.md

Latest commit

 

History

History
299 lines (197 loc) · 24.8 KB

README.md

File metadata and controls

299 lines (197 loc) · 24.8 KB

Subscriptions

(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] ➖ Filter by organization ID.
product_id OptionalNullable[models.ProductIDFilter] ➖ Filter by product ID.
customer_id OptionalNullable[models.CustomerIDFilter] ➖ Filter by customer ID.
external_customer_id OptionalNullable[models.ExternalCustomerIDFilter] ➖ Filter by customer external ID.
discount_id OptionalNullable[models.DiscountIDFilter] ➖ Filter by discount ID.
active OptionalNullable[bool] ➖ Filter by active or inactive subscription.
cancel_at_period_end OptionalNullable[bool] ➖ Filter by subscriptions that are set to cancel at period end.
customer_cancellation_reason OptionalNullable[models.CustomerCancellationReasonFilter] ➖ Filter by customer cancellation reason.
canceled_at_after date ➖ Filter by cancellation date (after or equal to).
canceled_at_before date ➖ Filter by cancellation date (before or equal to).
page Optional[int] ➖ Page number, defaults to 1.
limit Optional[int] ➖ Size of a page, defaults to 10. Maximum is 100.
sorting List[models.SubscriptionSortProperty] ➖ 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] ➖ Filter by metadata key-value pairs. It uses the deepObject style, e.g. ?metadata[key]=value.
retries Optional[utils.RetryConfig] ➖ 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 ✔️ The request object to use for the request.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.Subscription

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] ➖ Filter by organization ID.
retries Optional[utils.RetryConfig] ➖ 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 ✔️ The subscription ID.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.Subscription

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 ✔️ The subscription ID.
subscription_update models.SubscriptionUpdate ✔️ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.Subscription

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 ✔️ The subscription ID.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.Subscription

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 */*