{"id":10050,"library":"polar-sdk","title":"Polar SDK","description":"The `polar-sdk` is the official Python client for the Polar API, designed to help developers integrate subscription and monetization features into their applications. It provides access to resources like products, subscriptions, and webhooks. As of version 0.31.3, it offers both synchronous and asynchronous interfaces and is actively maintained with frequent updates.","status":"active","version":"0.31.3","language":"en","source_language":"en","source_url":"https://github.com/polarsource/polar-python.git","tags":["API client","cloud","payment","subscription","monetization","webhook"],"install":[{"cmd":"pip install polar-sdk","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The top-level package is `polar`, not `polar_sdk`.","wrong":"from polar_sdk import Polar","symbol":"Polar","correct":"from polar import Polar"},{"note":"Exception classes are located in the `polar.exceptions` submodule.","wrong":"from polar import PolarError","symbol":"PolarError","correct":"from polar.exceptions import PolarError"}],"quickstart":{"code":"import os\nfrom polar import Polar\nfrom polar.exceptions import PolarError\n\n# Initialize the Polar client. It automatically uses the POLAR_API_KEY\n# environment variable if set. Otherwise, you can pass it directly.\n# For testing, you might use a dummy key if not interacting with a live API.\nclient = Polar(auth=os.environ.get(\"POLAR_API_KEY\", \"sk_test_..._your_key\"))\n\nasync def main():\n    try:\n        # Example: List subscriptions (using the async client)\n        print(\"Attempting to list subscriptions...\")\n        subscriptions_page = await client.subscriptions.list(limit=5)\n\n        if subscriptions_page.items:\n            print(f\"Found {len(subscriptions_page.items)} subscriptions:\")\n            for sub in subscriptions_page.items:\n                print(f\"  - ID: {sub.id}, Status: {sub.status}, Product ID: {sub.product_id}\")\n        else:\n            print(\"No subscriptions found.\")\n\n    except PolarError as e:\n        print(f\"Polar API Error: {e.status_code} - {e.body}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n\nif __name__ == \"__main__\":\n    # For running async code in a sync context (e.g., top-level script)\n    import asyncio\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure `export POLAR_API_KEY='your_secret_key'` is set in your shell, or initialize with `client = Polar(auth='your_secret_key')`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Wrap API calls in a `try...except PolarError as e:` block to handle API responses gracefully.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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`).","message":"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.","severity":"breaking","affected_versions":"<0.1.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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')`.","cause":"The Polar client was initialized without an API key, and the `POLAR_API_KEY` environment variable was not set.","error":"polar.exceptions.PolarError: Missing authentication."},{"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.","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.","error":"TypeError: object async_client.products is not awaitable"},{"fix":"First, create a client instance: `client = Polar(...)`. Then, access resources via the client: `client.webhooks.receive(...)` or `client.subscriptions.list(...)`.","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.","error":"AttributeError: module 'polar' has no attribute 'api'"}]}