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,
)
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.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file polar_sdk-1.0.0a19.tar.gz.
File metadata
- Download URL: polar_sdk-1.0.0a19.tar.gz
- Upload date:
- Size: 214.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","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}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
22f48dfb76a22161183a9dc9b94ac5b5f4ae8b2ee4b13af83f380986b8e76417
|
|
| MD5 |
c0e9a257d9685d34d76aa47911ffd7a4
|
|
| BLAKE2b-256 |
92f51287b3c5fe1e3dc5bebe58eaaae73c70dcf33ba05406387dad2960adb7b9
|
File details
Details for the file polar_sdk-1.0.0a19-py3-none-any.whl.
File metadata
- Download URL: polar_sdk-1.0.0a19-py3-none-any.whl
- Upload date:
- Size: 299.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","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}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
5aa8a80e935f0aa51f595dbc4a90c157bced065c53758a43e6162c128d64e4f5
|
|
| MD5 |
8ea5a51dd9ab857011a7fb60ac621a4a
|
|
| BLAKE2b-256 |
bce1aff594a19172d195bb5a5768f827b88ef0acad93b55b345056709b6944aa
|
