This release is a pre-release and may not be stable for production use.
Polar Python SDK
The official Python client for the Polar API.
Installation
The SDK requires Python 3.11 or later.
The SDK is currently available as a pre-release. To install it with uv:
uv add polar-sdk --prerelease allow
or, with pip:
pip install --pre polar-sdk
Quick Start
Create an organization access token and use the client for the current API version:
from polar.v2026_04 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_04 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_04 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_04 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_04.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_04.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.0a21
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.0a21.tar.gz | 219.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| polar_sdk-1.0.0a21-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 524.2 kB
Release files / polar_sdk-1.0.0a21.tar.gz
| Download URL | polar_sdk-1.0.0a21.tar.gz |
|---|---|
| Size | 219.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
562902fef28b3bb315ac5c3fae05996c07de6ca019020e5220538a29fa1bdd43
|
|
BLAKE2b-256 checksum How to use checksums |
28e8a0a4f4cd7517cd6f27df1c1d467992888a160b991b0be85ce0d178da7c80
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","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.0a21-py3-none-any.whl
| Download URL | polar_sdk-1.0.0a21-py3-none-any.whl |
|---|---|
| Size | 304.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5162d011f31cf049a087b3d6d7d0bf3951d9c90b5a48939d7cee8da70c1eaf70
|
|
BLAKE2b-256 checksum How to use checksums |
3e1b5776e11ba6059e9b1fb5bf0074fff0f0af191d2f1f3038c4ee1d399b8c5f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","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}
|
