Polar SDK

Common errors

• polar.exceptions.PolarError: Missing authentication.

  cause The Polar client was initialized without an API key, and the `POLAR_API_KEY` environment variable was not set.
  fix Set the `POLAR_API_KEY` environment variable (e.g., `export POLAR_API_KEY='sk_test_...'`) or pass the key directly during client initialization: `client = Polar(auth='your_api_key')`.

• TypeError: object async_client.products is not awaitable

  cause You are trying to call an `async` method without using the `await` keyword, or you initialized a synchronous client but are treating its methods as awaitable.
  fix If using an `async` client (`Polar(is_async=True)`), ensure all method calls are prefixed with `await`. If using a synchronous client (default `Polar()`), remove `await` and ensure your code is not in an `async` context.

• AttributeError: module 'polar' has no attribute 'api'

  cause You are attempting to access API resources (like `webhooks` or `subscriptions`) directly from the `polar` module instead of through an initialized `Polar` client instance.
  fix First, create a client instance: `client = Polar(...)`. Then, access resources via the client: `client.webhooks.receive(...)` or `client.subscriptions.list(...)`.

Warnings

• gotcha The SDK provides both synchronous and asynchronous clients. The default `Polar()` initialization returns a synchronous client. If you intend to use `await` with methods like `client.subscriptions.list()`, you must explicitly use `Polar(is_async=True)` and run it within an `async` function.
  Fix: For async usage: `client = Polar(auth=..., is_async=True)` and call methods with `await`. For sync usage: `client = Polar(auth=...)` (default) and call methods directly without `await`.
• gotcha Authentication is mandatory for most API calls. The client attempts to read `POLAR_API_KEY` from environment variables. If it's not set, or you need to use a different key, you must pass it via the `auth` parameter during client initialization.
  Fix: Ensure `export POLAR_API_KEY='your_secret_key'` is set in your shell, or initialize with `client = Polar(auth='your_secret_key')`.
• gotcha Error handling for API-specific issues should explicitly catch `polar.exceptions.PolarError`. This allows you to differentiate between network issues, bad requests, or other API-reported problems based on `status_code` and `body` attributes.
  Fix: Wrap API calls in a `try...except PolarError as e:` block to handle API responses gracefully.
• breaking Prior to version 0.1.0, the SDK had a different structure and import paths. The 0.1.0 release introduced a complete rewrite to a modern API client generation, making it incompatible with older versions.
  Fix: Upgrade to the latest version (`pip install --upgrade polar-sdk`) and refactor code according to the new client structure and import paths (e.g., `from polar import Polar`).

Install

• pip install polar-sdk Install stable version

Imports

• Polar
  wrong:

  from polar_sdk import Polar

  correct:

  from polar import Polar

  The top-level package is `polar`, not `polar_sdk`.
• PolarError
  wrong:

  from polar import PolarError

  correct:

  from polar.exceptions import PolarError

  Exception classes are located in the `polar.exceptions` submodule.

Quickstart

This quickstart demonstrates how to initialize the `Polar` client, fetch a list of subscriptions, and handle potential API errors. It uses an asynchronous client, which is recommended for modern Python applications. Ensure you have `POLAR_API_KEY` set in your environment or replace the placeholder with your actual API key.

import os
from polar import Polar
from polar.exceptions import PolarError

# Initialize the Polar client. It automatically uses the POLAR_API_KEY
# environment variable if set. Otherwise, you can pass it directly.
# For testing, you might use a dummy key if not interacting with a live API.
client = Polar(auth=os.environ.get("POLAR_API_KEY", "sk_test_..._your_key"))

async def main():
    try:
        # Example: List subscriptions (using the async client)
        print("Attempting to list subscriptions...")
        subscriptions_page = await client.subscriptions.list(limit=5)

        if subscriptions_page.items:
            print(f"Found {len(subscriptions_page.items)} subscriptions:")
            for sub in subscriptions_page.items:
                print(f"  - ID: {sub.id}, Status: {sub.status}, Product ID: {sub.product_id}")
        else:
            print("No subscriptions found.")

    except PolarError as e:
        print(f"Polar API Error: {e.status_code} - {e.body}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

if __name__ == "__main__":
    # For running async code in a sync context (e.g., top-level script)
    import asyncio
    asyncio.run(main())