Polar Python SDK

The official Python client for the Polar API.

Installation

The SDK requires Python 3.11 or later.

To install it with uv:

uv add polar-sdk

or, with pip:

pip install polar-sdk

Quick Start

Create an organization access token and use the client for the current API version:

from polar.v2026_10 import Polar

polar = Polar("polar_oat_xxx")

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

Async Client

Use PolarAsync in asynchronous applications:

import asyncio

from polar.v2026_10 import PolarAsync


async def main() -> None:
    polar = PolarAsync("polar_oat_xxx")
    customer_state = await polar.customers.get_state_external("customer_external_id")
    print(customer_state)


asyncio.run(main())

Context Managers

Both clients support context managers to close their HTTP connections automatically when the block exits.

For synchronous applications, use Polar with with:

from polar.v2026_10 import Polar

with Polar("polar_oat_xxx") as polar:
    customer_state = polar.customers.get_state_external("customer_external_id")
    print(customer_state)

For asynchronous applications, use PolarAsync with async with:

import asyncio

from polar.v2026_10 import PolarAsync


async def main() -> None:
    async with PolarAsync("polar_oat_xxx") as polar:
        customer_state = await polar.customers.get_state_external(
            "customer_external_id"
        )
        print(customer_state)


asyncio.run(main())

The client uses the production environment by default. To use the sandbox, pass environment="sandbox" when creating the client. Sandbox and production access tokens are separate.

Keep organization access tokens on the server and never expose them in browser or client-side code.

Request Timeouts

Set the default timeout for all requests when creating the client. Timeout values are expressed in seconds:

polar = Polar("polar_oat_xxx", timeout=30)

Override the timeout for an individual request with request_timeout:

customer_state = polar.customers.get_state_external(
    "customer_external_id",
    request_timeout=60,
)

Override the access token for an individual request with request_access_token:

customer_state = polar.customers.get_state_external(
    "customer_external_id",
    request_access_token="polar_at_u_override",
)

Pass an httpx.Timeout instance to configure connect, read, write, and pool timeouts separately.

Organizations

OAuth access tokens and personal access tokens can reach every organization the user belongs to. Pass organization_id to get a client that acts on a single organization. It sends the Polar-Organization header, so the API only returns and changes that organization's data:

acme = Polar("polar_at_u_xxx", organization_id="acme_organization_id")
customers = acme.customers.list()

Organization access tokens already act on their own organization and don't need it.

Deserializing Data

Use deserialize to convert arbitrary data into a generated SDK model or union type:

from polar import deserialize
from polar.v2026_10.outputs import Customer

customer = deserialize(data, Customer)

Webhooks

Use validate_event to verify that a webhook was sent by Polar and parse it into a typed payload for the selected API version. Pass the raw request body, the request headers, and your webhook signing secret:

import os

from fastapi import FastAPI, HTTPException, Request

from polar.v2026_10.webhooks import (
    PolarWebhookError,
    PolarWebhookVerificationError,
    validate_event,
)

app = FastAPI()
webhook_secret = os.environ["POLAR_WEBHOOK_SECRET"]


@app.post("/webhooks/polar")
async def polar_webhook(request: Request) -> dict[str, bool]:
    try:
        event = validate_event(
            await request.body(),
            dict(request.headers),
            webhook_secret,
        )
    except PolarWebhookVerificationError as exc:
        raise HTTPException(
            status_code=403, detail="Invalid webhook signature"
        ) from exc
    except PolarWebhookError as exc:
        raise HTTPException(status_code=400, detail="Invalid webhook payload") from exc

    if event.type == "order.created":
        print(event.data.id)

    return {"received": True}

The signature is checked before the body is parsed. Verification accepts Polar's original HMAC key (UTF-8 bytes of the full secret, including whsec_) and the Standard Webhooks key (base64-decode of the remainder after whsec_). validate_event raises PolarWebhookVerificationError for invalid signatures and PolarWebhookUnknownTypeError when the event is not supported by the selected API version. Both inherit from PolarWebhookError.

Metadata

Release files for polar-sdk 1.0.3a3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for polar-sdk 1.0.3a3
File	Size	Uploaded
polar_sdk-1.0.3a3.tar.gz	348.7 kB	Oct 15, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for polar-sdk 1.0.3a3
File	Interpreter	ABI	Platform	Reset
polar_sdk-1.0.3a3-py3-none-any.whl 468.5 kB Oct 15, 2026	Python 3	none	any	Details

Total release size: 817.1 kB

Release files / polar_sdk-1.0.3a3.tar.gz

Download URL	polar_sdk-1.0.3a3.tar.gz
Size	348.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`a8671a46d647e0a6c0574181a6a29cfcb1a19d454c988e823980ca065f3acdc2`
BLAKE2b-256 checksum How to use checksums	`287826b1b98424dd1f59c06efe53a5602981601f916a4860ab316ebf2b6a12bd`
Upload date	Oct 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / polar_sdk-1.0.3a3-py3-none-any.whl

Download URL	polar_sdk-1.0.3a3-py3-none-any.whl
Size	468.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`925b7bcec16c58cb5212901941ce2dedc574225828354fd4c97429bdba3a3f98`
BLAKE2b-256 checksum How to use checksums	`e4f83259cdb59db39bfbaeba2464d0ca5320eae4e1b022322f6814fdcf9980cd`
Upload date	Oct 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`