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.
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.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| polar_sdk-1.0.0.tar.gz | 323.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| polar_sdk-1.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 777.5 kB
Release files / polar_sdk-1.0.0.tar.gz
| Download URL | polar_sdk-1.0.0.tar.gz |
|---|---|
| Size | 323.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0b7ae907bb70dcae9b07973cd03aa5394df7b7801561799e6ff71feac31d95d6
|
|
BLAKE2b-256 checksum How to use checksums |
114073696ba0215dede23a53db7646d8b9cf8fef8cc24927492c0eaae149298c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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.0-py3-none-any.whl
| Download URL | polar_sdk-1.0.0-py3-none-any.whl |
|---|---|
| Size | 454.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
07360839a142995ec97d0ed95630d83c1c103375b75c29faf83204a405b63686
|
|
BLAKE2b-256 checksum How to use checksums |
2b83b10fd1beefa4e5a8bb7fea1f3f5318c39154d881aa4c6be83cba1d5b6c2b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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}
|
