### Install polar-sdk

Source: https://context7.com/polarsource/polar-python/llms.txt

Install the Polar SDK using pip, uv, or poetry.

```bash
# Using pip
pip install polar-sdk
```

```bash
# Using uv
uv add polar-sdk
```

```bash
# Using poetry
poetry add polar-sdk
```

--------------------------------

### Install polar-sdk with pip

Source: https://github.com/polarsource/polar-python/blob/main/README.md

Use pip, the default Python package installer, to install the polar-sdk package from PyPI.

```bash
pip install polar-sdk
```

--------------------------------

### Install polar-sdk with uv

Source: https://github.com/polarsource/polar-python/blob/main/README.md

Use uv to add the polar-sdk package to your project. uv is a fast Python package installer.

```bash
uv add polar-sdk
```

--------------------------------

### GET /v1/products/

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/products/README.md

List products with optional pagination. Requires 'products:read' or 'products:write' scope.

```APIDOC
## GET /v1/products/

### Description
List products with optional pagination.

### Method
GET

### Endpoint
/v1/products/

### Parameters
#### Query Parameters
- **organization_id** (string) - Optional - The ID of the organization to list products for.
- **page** (integer) - Optional - The page number for pagination. Defaults to 1.
- **limit** (integer) - Optional - The number of items to return per page. Defaults to 10.

### Request Example
```python
from polar_sdk import Polar


with Polar(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.products.list(organization_id=None, page=1, limit=10)

    while res is not None:
        # Handle items

        res = res.next()
```

### Response
#### Success Response (200)
- **items** (list) - A list of product objects.
- **next_page** (integer) - The next page number, or null if there are no more pages.

#### Response Example
```json
{
  "items": [
    {
      "id": "prod_123",
      "name": "Pro Subscription",
      "description": "Monthly subscription for Pro features.",
      "type": "subscription",
      "price_currency": "USD",
      "price_amount": 1000,
      "created_at": "2023-10-27T10:00:00Z",
      "updated_at": "2023-10-27T10:00:00Z"
    }
  ],
  "next_page": 2
}
```
```

--------------------------------

### Install polar-sdk with poetry

Source: https://github.com/polarsource/polar-python/blob/main/README.md

Use poetry, a dependency management tool, to add the polar-sdk package to your project.

```bash
poetry add polar-sdk
```

--------------------------------

### GET /products

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/products/README.md

Retrieves a list of products, with options to filter the results.

```APIDOC
## GET /products

### Description
Retrieves a list of products, with options to filter the results.

### Method
GET

### Endpoint
/products

### Parameters
#### Query Parameters
- **id** (OptionalNullable[models.QueryParamProductIDFilter]) - Optional - Filter by product ID.
- **organization_id** (OptionalNullable[models.ProductsListQueryParamOrganizationIDFilter]) - Optional - Filter by organization ID.
- **query** (OptionalNullable[str]) - Optional - Filter by product name.
- **is_archived** (OptionalNullable[bool]) - Optional - Filter on archived products.
- **is_recurring** (OptionalNullable[bool]) - Optional - Filter on recurring products. If `true`, only subscriptions tiers are returned. If `false`, only one-time purchase products are returned.
```

--------------------------------

### ProductPriceSeatBasedCreate Example

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/checkoutcreateprices.md

Use this model for pricing based on the number of seats or users. Replace '/* values here */' with the seat-based pricing configuration.

```python
value: models.ProductPriceSeatBasedCreate = /* values here */
```

--------------------------------

### Get an Organization by ID - Python

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/organizations/README.md

Retrieve an organization's details using its unique ID. This requires `organizations:read` or `organizations:write` scopes. The provided ID is an example; use the actual organization ID.

```python
from polar_sdk import Polar


with Polar(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.organizations.get(id="1dbfc517-0bbf-4301-9ba8-555ca42b9737")

    # Handle response
    print(res)
```

--------------------------------

### Initialize SDK with httpx.Client and Custom Headers

Source: https://github.com/polarsource/polar-python/blob/main/README.md

Pass an instance of `httpx.Client` to the `client` parameter to configure low-level HTTP settings like custom headers for all SDK requests. Ensure the `httpx` library is installed.

```python
from polar_sdk import Polar
import httpx

http_client = httpx.Client(headers={"x-custom-header": "someValue"})
s = Polar(client=http_client)

```

--------------------------------

### SubscriptionUpdatedProductMetadata Example

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/subscriptionupdatedeventmetadata.md

Represents metadata for a subscription product update. Use this when the product details of a subscription have changed.

```python
value: models.SubscriptionUpdatedProductMetadata = /* values here */
```

--------------------------------

### GET /v1/customer-portal/wallets/{id}

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/wallets/README.md

Get a wallet by ID for the authenticated customer.

```APIDOC
## GET /v1/customer-portal/wallets/{id}

### Description
Get a wallet by ID for the authenticated customer.

### Method
GET

### Endpoint
/v1/customer-portal/wallets/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - The wallet ID.

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```python
import polar_sdk
from polar_sdk import Polar


with Polar() as polar:

    res = polar.customer_portal.wallets.get(security=polar_sdk.CustomerPortalWalletsGetSecurity(
        customer_session="<YOUR_BEARER_TOKEN_HERE>",
    ), id="<value>")

    # Handle response
    print(res)
```

### Response
#### Success Response (200)
- **response** (models.CustomerWallet) - Description of the wallet object.

#### Response Example
```json
{
  "example": "response body"
}
```

### Errors
- **models.ResourceNotFound** (404) - application/json
- **models.HTTPValidationError** (422) - application/json
- **models.SDKError** (4XX, 5XX) - */*
```

--------------------------------

### POST /v1/products/

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/products/README.md

Create a product with the specified details. Requires `products:write` scope.

```APIDOC
## POST /v1/products/

### Description
Create a product.

### Method
POST

### Endpoint
/v1/products/

### Parameters
#### Request Body
- **request** (models.ProductCreate) - Required - The request object to use for the request.
- **retries** (Optional[utils.RetryConfig]) - Optional - Configuration to override the default retry behavior of the client.

### Request Example
```python
from polar_sdk import Polar


with Polar(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.products.create(request={
        "name": "<value>",
        "prices": [],
        "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
        "recurring_interval": "year",
    })

    # Handle response
    print(res)
```

### Response
#### Success Response (200)
- **product** (models.Product) - Description of the created product.

#### Response Example
```json
{
  "example": "response body"
}
```

### Errors
- **models.HTTPValidationError** - Status Code: 422, Content Type: application/json
- **models.SDKError** - Status Code: 4XX, 5XX, Content Type: */*
```

--------------------------------

### ProductPriceCustomCreate Example

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/checkoutcreateprices.md

Use this model to define custom pricing for products. Replace '/* values here */' with your specific pricing details.

```python
value: models.ProductPriceCustomCreate = /* values here */
```

--------------------------------

### GET /v1/subscriptions/{id}

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/subscriptions/README.md

Get a subscription by ID. Requires `subscriptions:read` and `subscriptions:write` scopes.

```APIDOC
## GET /v1/subscriptions/{id}

### Description
Get a subscription by ID.

### Method
GET

### Endpoint
/v1/subscriptions/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - The subscription ID.
#### Query Parameters
- **retries** (Optional[utils.RetryConfig]) - Optional - Configuration to override the default retry behavior of the client.

### Request Example
```python
from polar_sdk import Polar


with Polar(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.subscriptions.get(id="<value>")

    # Handle response
    print(res)
```

### Response
#### Success Response (200)
- **[models.Subscription](../../models/subscription.md)**

### Errors
- **models.ResourceNotFound** (404) - application/json
- **models.HTTPValidationError** (422) - application/json
- **models.SDKError** (4XX, 5XX) - */*
```

--------------------------------

### SubscriptionUpdatedTrialMetadata Example

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/subscriptionupdatedeventmetadata.md

Represents metadata for a subscription trial update. Use this when trial period details for a subscription have changed.

```python
value: models.SubscriptionUpdatedTrialMetadata = /* values here */
```

--------------------------------

### GET /v1/customer-seats/claim-info - Get Claim Info

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/customerseats/README.md

Retrieves information about a seat claim. Requires `customer_seats:read` scope.

```APIDOC
## GET /v1/customer-seats/claim-info

### Description
Retrieves information about a seat claim.

### Method
GET

### Endpoint
/v1/customer-seats/claim-info

### Parameters
#### Query Parameters
- **claim_id** (str) - Required - The ID of the claim.
- **retries** (Optional[utils.RetryConfig]) - Optional - Configuration to override the default retry behavior of the client.

### Response
#### Success Response (200)
- **response** (models.SeatClaimInfo) - Information about the seat claim.

#### Response Example
```json
{
  "example": "response body"
}
```

### Errors
- **models.HTTPValidationError** (422) - application/json
- **models.SDKError** (4XX, 5XX) - */*
```

--------------------------------

### ProductPriceFreeCreate Example

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/checkoutcreateprices.md

Use this model when a product is offered for free. No specific values are typically needed beyond indicating it's free.

```python
value: models.ProductPriceFreeCreate = /* values here */
```

--------------------------------

### PaymentNotReady Example

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/checkoutforbiddenerror.md

Example of how to represent a PaymentNotReady error. This indicates that the payment system is not yet ready to process the transaction.

```python
value: models.PaymentNotReady = /* values here */
```

--------------------------------

### ProductMediaFileCreate Model

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/filecreate.md

Use this model to create product media files. Replace /* values here */ with your media data.

```python
value: models.ProductMediaFileCreate = /* values here */
```

--------------------------------

### AlreadyActiveSubscriptionError Example

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/checkoutforbiddenerror.md

Example of how to represent an AlreadyActiveSubscriptionError. This error typically indicates that a subscription is already active for the given context.

```python
value: models.AlreadyActiveSubscriptionError = /* values here */
```

--------------------------------

### ProductPriceMeteredUnitCreate Example

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/checkoutcreateprices.md

Use this model for metered pricing based on units consumed. Replace '/* values here */' with the relevant metered unit pricing details.

```python
value: models.ProductPriceMeteredUnitCreate = /* values here */
```

--------------------------------

### Initialize and Use Polar Client

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/metricssdk/README.md

Demonstrates how to initialize the Polar client with an access token and make a request to the metrics limits endpoint. Ensure you replace '<YOUR_BEARER_TOKEN_HERE>' with your actual token.

```python
from polar_sdk import Polar


with Polar(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.metrics.limits()

    # Handle response
    print(res)
```

--------------------------------

### Initialize SDK with Production Server

Source: https://github.com/polarsource/polar-python/blob/main/README.md

Use the `server` parameter with 'production' to set the default API endpoint to the production environment. This is useful for live operations.

```python
from polar_sdk import Polar


with Polar(
    server="production",
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.organizations.list(page=1, limit=10)

    while res is not None:
        # Handle items

        res = res.next()

```

--------------------------------

### GET /v1/members/{id}

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/members/README.md

Get a member by ID. The authenticated user or organization must have access to the member's organization.

```APIDOC
## GET /v1/members/{id}

### Description
Get a member by ID. The authenticated user or organization must have access to the member's organization.

### Method
GET

### Endpoint
/v1/members/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the member to retrieve.

#### Query Parameters
- **sorting** (List[models.MemberSortProperty]) - Optional - Sorting criterion. Several criteria can be used simultaneously and will be applied in order. Add a minus sign `-` before the criteria name to sort by descending order.
- **retries** (Optional[utils.RetryConfig]) - Optional - Configuration to override the default retry behavior of the client.

### Request Example
```python
from polar_sdk import Polar


with Polar(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.members.get_member(id="572bebad-ee17-4d04-a50f-6596a7d92cf3")

    # Handle response
    print(res)
```

### Response
#### Success Response (200)
- **member** (models.Member) - Description of the member.

#### Response Example
```json
{
  "example": "response body"
}
```

### Errors
- models.HTTPValidationError (422)
- models.SDKError (4XX, 5XX)
```

--------------------------------

### ProductPriceFixedCreate Example

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/checkoutcreateprices.md

Use this model for products with a fixed price. Replace '/* values here */' with the fixed price details.

```python
value: models.ProductPriceFixedCreate = /* values here */
```

--------------------------------

### NotOpenCheckout Example

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/checkoutforbiddenerror.md

Example of how to represent a NotOpenCheckout error. This error signifies that a checkout operation cannot proceed because the checkout is not in an open state.

```python
value: models.NotOpenCheckout = /* values here */
```

--------------------------------

### Synchronous SDK Usage Example

Source: https://github.com/polarsource/polar-python/blob/main/README.md

Demonstrates how to initialize and use the Polar SDK for synchronous API calls, including iterating through paginated results.

```python
# Synchronous Example
from polar_sdk import Polar


with Polar(
  access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.organizations.list(page=1, limit=10)

    while res is not None:
        # Handle items

        res = res.next()

```

--------------------------------

### TrialAlreadyRedeemed Example

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/checkoutforbiddenerror.md

Example of how to represent a TrialAlreadyRedeemed error. This error occurs when a user attempts to redeem a trial offer that has already been used.

```python
value: models.TrialAlreadyRedeemed = /* values here */
```

--------------------------------

### Create a Subscription

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/subscriptions/README.md

Use this function to create a subscription for a free product. Ensure you have the necessary 'subscriptions:write' scope. This method does not create an initial order or send a confirmation email.

```python
from polar_sdk import Polar


with Polar(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.subscriptions.create(request={
        "product_id": "d8dd2de1-21b7-4a41-8bc3-ce909c0cfe23",
        "customer_id": "992fae2a-2a17-4b7a-8d9e-e287cf90131b",
    })

    # Handle response
    print(res)
```

--------------------------------

### Get Authenticated User API

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/customersessionsdk/README.md

Get information about the currently authenticated portal user. Requires customer_portal:read and customer_portal:write scopes.

```APIDOC
## GET /v1/customer-portal/customer-session/user

### Description
Get information about the currently authenticated portal user.

### Method
GET

### Endpoint
/v1/customer-portal/customer-session/user

### Parameters
#### Query Parameters
- **security** (models.CustomerPortalCustomerSessionGetAuthenticatedUserSecurity) - Required - The security requirements to use for the request.
- **retries** (Optional[utils.RetryConfig]) - Optional - Configuration to override the default retry behavior of the client.

### Request Example
```python
import polar_sdk
from polar_sdk import Polar


with Polar() as polar:

    res = polar.customer_portal.customer_session.get_authenticated_user(security=polar_sdk.CustomerPortalCustomerSessionGetAuthenticatedUserSecurity(
        customer_session="<YOUR_BEARER_TOKEN_HERE>",
    ))

    # Handle response
    print(res)
```

### Response
#### Success Response (200)
- **authenticated_user** (models.User) - Description of the authenticated user.

#### Response Example
```json
{
  "example": "response body"
}
```

### Errors
- **models.SDKError** - 4XX, 5XX - */*
```

--------------------------------

### Get Customer State by External ID

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/customers/README.md

Retrieve a customer's state using their external identifier. This is useful for getting a comprehensive overview of a customer's status, including subscriptions and benefits. Requires appropriate scopes.

```python
from polar_sdk import Polar


with Polar(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.customers.get_state_external(external_id="<id>")

    # Handle response
    print(res)
```

--------------------------------

### Get Authenticated Portal User

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/customersessionsdk/README.md

Use this to get information about the currently authenticated portal user. Requires customer_portal:read or customer_portal:write scopes. The security parameter must include a valid customer session bearer token.

```python
import polar_sdk
from polar_sdk import Polar


with Polar() as polar:

    res = polar.customer_portal.customer_session.get_authenticated_user(security=polar_sdk.CustomerPortalCustomerSessionGetAuthenticatedUserSecurity(
        customer_session="<YOUR_BEARER_TOKEN_HERE>",
    ))

    # Handle response
    print(res)
```

--------------------------------

### POST /v1/license-keys/activate

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/licensekeys/README.md

Activates a license key instance. Requires `license_keys:write` scope.

```APIDOC
## POST /v1/license-keys/activate

### Description
Activate a license key instance.

### Method
POST

### Endpoint
/v1/license-keys/activate

### Parameters
#### Request Body
- **request** (models.LicenseKeyActivate) - Required - The request object to use for the request.
- **retries** (Optional[utils.RetryConfig]) - Optional - Configuration to override the default retry behavior of the client.

### Request Example
```python
{
  "key": "<key>",
  "organization_id": "<value>",
  "label": "<value>"
}
```

### Response
#### Success Response (200)
- **(models.LicenseKeyActivationRead)**

#### Response Example
```json
{
  "example": "response body"
}
```

### Errors
- models.NotPermitted (403) - application/json
- models.ResourceNotFound (404) - application/json
- models.HTTPValidationError (422) - application/json
- models.SDKError (4XX, 5XX) - */*
```

--------------------------------

### SubscriptionsGetRequest

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/subscriptionsgetrequest.md

Represents a request to get subscription details.

```APIDOC
## GET /subscriptions/{id}

### Description
Retrieves details for a specific subscription using its ID.

### Method
GET

### Endpoint
/subscriptions/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - The subscription ID.

### Response
#### Success Response (200)
- **id** (str) - The subscription ID.

### Request Example
```json
{
  "id": "sub_123abc"
}
```

### Response Example
```json
{
  "id": "sub_123abc"
}
```
```

--------------------------------

### CustomFieldsGetRequest

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/customfieldsgetrequest.md

Represents a request to get custom field details.

```APIDOC
## CustomFieldsGetRequest

### Description
This object defines the parameters for a request to retrieve custom field information.

### Method
POST

### Endpoint
/api/v1/custom_fields/get

### Parameters
#### Request Body
- **id** (string) - Required - The custom field ID.
```

--------------------------------

### POST /v1/files/

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/files/README.md

Creates a new file entry in the system. This is the first step in uploading a file.

```APIDOC
## POST /v1/files/

### Description
Creates a new file entry in the system. This is the first step in uploading a file.

### Method
POST

### Endpoint
/v1/files/

### Parameters
#### Request Body
- **request** (models.FileCreate) - Required - The request object to use for the request.
- **retries** (Optional[utils.RetryConfig]) - Optional - Configuration to override the default retry behavior of the client.

### Request Example
```python
{
  "name": "<value>",
  "mime_type": "<value>",
  "size": 612128,
  "upload": {
    "parts": []
  },
  "service": "downloadable"
}
```

### Response
#### Success Response (200)
- **file_upload** (models.FileUpload) - Description of the created file upload object.

#### Response Example
```json
{
  "id": "string",
  "name": "string",
  "mime_type": "string",
  "size": 0,
  "created_at": "string",
  "uploaded_at": "string",
  "urls": {
    "get": "string",
    "upload": "string"
  },
  "upload": {
    "id": "string",
    "url": "string",
    "expires_at": "string",
    "parts": [
      {
        "number": 0,
        "url": "string",
        "expires_at": "string"
      }
    ]
  },
  "service": "string"
}
```

### Errors
- models.HTTPValidationError (422)
- models.SDKError (4XX, 5XX)
```

--------------------------------

### Initialize SDK with Custom AsyncHttpClient Wrapper

Source: https://github.com/polarsource/polar-python/blob/main/README.md

Wrap `httpx.AsyncClient` with a custom class implementing `AsyncHttpClient` to add logic like custom headers to every asynchronous request. This requires defining a `send` and `build_request` method.

```python
from polar_sdk import Polar
from polar_sdk.httpclient import AsyncHttpClient
import httpx

class CustomClient(AsyncHttpClient):
    client: AsyncHttpClient

    def __init__(self, client: AsyncHttpClient):
        self.client = client

    async def send(
        self,
        request: httpx.Request,
        *, 
        stream: bool = False,
        auth: Union[
            httpx._types.AuthTypes, httpx._client.UseClientDefault, None
        ] = httpx.USE_CLIENT_DEFAULT,
        follow_redirects: Union[
            bool, httpx._client.UseClientDefault
        ] = httpx.USE_CLIENT_DEFAULT,
    ) -> httpx.Response:
        request.headers["Client-Level-Header"] = "added by client"

        return await self.client.send(
            request, stream=stream, auth=auth, follow_redirects=follow_redirects
        )

    def build_request(
        self,
        method: str,
        url: httpx._types.URLTypes,
        *,
        content: Optional[httpx._types.RequestContent] = None,
        data: Optional[httpx._types.RequestData] = None,
        files: Optional[httpx._types.RequestFiles] = None,
        json: Optional[Any] = None,
        params: Optional[httpx._types.QueryParamTypes] = None,
        headers: Optional[httpx._types.HeaderTypes] = None,
        cookies: Optional[httpx._types.CookieTypes] = None,
        timeout: Union[
            httpx._types.TimeoutTypes, httpx._client.UseClientDefault
        ] = httpx.USE_CLIENT_DEFAULT,
        extensions: Optional[httpx._types.RequestExtensions] = None,
    ) -> httpx.Request:
        return self.client.build_request(
            method,
            url,
            content=content,
            data=data,
            files=files,
            json=json,
            params=params,
            headers=headers,
            cookies=cookies,
            timeout=timeout,
            extensions=extensions,
        )

s = Polar(async_client=CustomClient(httpx.AsyncClient()))

```

--------------------------------

### Get Order Invoice

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/polarorders/README.md

Retrieves the invoice data for a specific order.

```APIDOC
## GET /v1/customer-portal/orders/{id}/invoice

### Description
Get an order's invoice data.

### Method
GET

### Endpoint
/v1/customer-portal/orders/{id}/invoice

### Parameters
#### Path Parameters
- **id** (str) - Required - The order ID.

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **Any** (Any) - The invoice data.

#### Response Example
N/A

### Errors
- **models.MissingInvoiceBillingDetails** (422) - application/json
- **models.NotPaidOrder** (422) - application/json
- **models.SDKError** (4XX, 5XX) - */*
```

--------------------------------

### Initialize SDK with Custom Server URL

Source: https://github.com/polarsource/polar-python/blob/main/README.md

Override the default server by providing a specific URL to the `server_url` parameter during SDK client initialization. This allows targeting any compatible API endpoint.

```python
from polar_sdk import Polar


with Polar(
    server_url="https://api.polar.sh",
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.organizations.list(page=1, limit=10)

    while res is not None:
        # Handle items

        res = res.next()

```

--------------------------------

### Get License Key

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/polarlicensekeys/README.md

Retrieves a specific license key by its ID.

```APIDOC
## GET /v1/customer-portal/license-keys/{license_key_id}/

### Description
Retrieves a specific license key using its unique identifier.

### Method
GET

### Endpoint
/v1/customer-portal/license-keys/{license_key_id}/

### Parameters
#### Path Parameters
- **license_key_id** (str) - Required - The unique identifier of the license key.

#### Query Parameters
- **retries** (Optional[utils.RetryConfig]) - Optional - Configuration to override the default retry behavior of the client.

#### Security
- **security** (models.CustomerPortalLicenseKeysGetSecurity) - Required - Authentication token.

### Response
#### Success Response (200)
- **models.LicenseKey** - The response contains the details of the requested license key.

#### Error Response
- **models.Unauthorized** (401) - If the request is not authenticated.
- **models.ResourceNotFound** (404) - If the license key is not found.
- **models.HTTPValidationError** (422) - If the request parameters are invalid.
- **models.SDKError** (4XX, 5XX) - For any other SDK-related errors.
```

--------------------------------

### GET /organizations

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/organizationslistrequest.md

Retrieves a list of organizations with optional filtering and sorting.

```APIDOC
## GET /organizations

### Description
Retrieves a list of organizations. You can filter by slug, paginate the results, and specify sorting criteria.

### Method
GET

### Endpoint
/organizations

### Parameters
#### Query Parameters
- **slug** (string) - Optional - Filter by slug.
- **page** (int) - Optional - Page number, defaults to 1.
- **limit** (int) - Optional - Size of a page, defaults to 10. Maximum is 100.
- **sorting** (List[models.OrganizationSortProperty]) - Optional - Sorting criterion. Several criteria can be used simultaneously and will be applied in order. Add a minus sign `-` before the criteria name to sort by descending order.

### Response
#### Success Response (200)
- **organizations** (List[models.Organization]) - A list of organization objects.
- **pagination** (models.Pagination) - Pagination information for the results.

#### Response Example
```json
{
  "organizations": [
    {
      "id": "org_123",
      "name": "Example Organization",
      "slug": "example-org"
    }
  ],
  "pagination": {
    "total_items": 100,
    "total_pages": 10,
    "current_page": 1,
    "page_size": 10
  }
}
```
```

--------------------------------

### POST /v1/customers/

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/customers/README.md

Creates a new customer with the provided details. Requires `customers:write` scope.

```APIDOC
## POST /v1/customers/

### Description
Create a customer.

### Method
POST

### Endpoint
/v1/customers/

### Parameters
#### Request Body
- **request** (models.CustomerCreate) - Required - The request object to use for the request.
- **retries** (Optional[utils.RetryConfig]) - Optional - Configuration to override the default retry behavior of the client.

### Request Example
```python
import polar_sdk
from polar_sdk import Polar


with Polar(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.customers.create(request={
        "external_id": "usr_1337",
        "name": "John Doe",
        "billing_address": {
            "country": polar_sdk.AddressInputCountryAlpha2Input.US,
        },
        "locale": "en",
        "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
        "owner": {
            "email": "member@example.com",
            "name": "Jane Doe",
            "external_id": "usr_1337",
        },
        "type": "individual",
        "email": "customer@example.com",
    })

    # Handle response
    print(res)
```

### Response
#### Success Response (200)
- **response** (models.Customer) - Description of the customer created.

#### Response Example
```json
{
  "id": "cus_abc123",
  "external_id": "usr_1337",
  "name": "John Doe",
  "email": "customer@example.com",
  "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
  "created_at": "2023-10-27T10:00:00Z",
  "balance": 0,
  "currency": "USD",
  "tax_withholding": null,
  "is_tax_enabled": false,
  "tax_id": null,
  "tax_country": null,
  "tax_address": null,
  "billing_address": {
    "id": "adr_xyz789",
    "attention_name": null,
    "city": null,
    "country": "US",
    "postal_code": null,
    "state": null,
    "street_address1": null,
    "street_address2": null,
    "street_address3": null,
    "first_name": null,
    "last_name": null,
    "phone_number": null
  },
  "locale": "en",
  "type": "individual",
  "owner": {
    "id": "usr_owner123",
    "email": "member@example.com",
    "name": "Jane Doe",
    "external_id": "usr_1337"
  }
}
```

### Errors
- **models.HTTPValidationError** - Status Code: 422, Content Type: application/json
- **models.SDKError** - Status Code: 4XX, 5XX, Content Type: */*
```

--------------------------------

### GET /orders

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/orderslistrequest.md

Retrieve a list of orders with optional filtering capabilities.

```APIDOC
## GET /orders

### Description
Retrieve a list of orders with optional filtering capabilities.

### Method
GET

### Endpoint
/orders

### Query Parameters
- **organization_id** (OptionalNullable[models.OrdersListQueryParamOrganizationIDFilter]) - Optional - Filter by organization ID.
- **product_id** (OptionalNullable[models.OrdersListQueryParamProductIDFilter]) - Optional - Filter by product ID.
- **product_billing_type** (OptionalNullable[models.ProductBillingTypeFilter]) - Optional - Filter by product billing type. `recurring` will filter data corresponding to subscriptions creations or renewals. `one_time` will filter data corresponding to one-time purchases.
- **discount_id** (OptionalNullable[models.QueryParamDiscountIDFilter]) - Optional - Filter by discount ID.
```

--------------------------------

### Per-Operation Security Scheme Initialization

Source: https://github.com/polarsource/polar-python/blob/main/README.md

This example shows how to specify security schemes at the request level for specific operations. It's used when an operation requires a different security context than the global setting.

```python
import polar_sdk
from polar_sdk import Polar


with Polar() as polar:

    res = polar.customer_portal.benefit_grants.list(security=polar_sdk.CustomerPortalBenefitGrantsListSecurity(

    ), page=1, limit=10)

    while res is not None:
        # Handle items

        res = res.next()

```

--------------------------------

### List License Keys

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/polarlicensekeys/README.md

Use this to list license keys. You can filter by benefit ID and paginate results. Requires customer session authentication.

```python
import polar_sdk
from polar_sdk import Polar


with Polar() as polar:

    res = polar.customer_portal.license_keys.list(security=polar_sdk.CustomerPortalLicenseKeysListSecurity(
        customer_session="<YOUR_BEARER_TOKEN_HERE>",
    ), page=1, limit=10)

    while res is not None:
        # Handle items

        res = res.next()

```

--------------------------------

### GET /metrics

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/metricsgetrequest.md

Retrieves metric data with optional filtering capabilities.

```APIDOC
## GET /metrics

### Description
Retrieves metric data. Allows filtering by product ID, billing type, customer ID, and specific metrics.

### Method
GET

### Endpoint
/metrics

### Parameters
#### Query Parameters
- **product_id** (OptionalNullable[models.MetricsGetQueryParamProductIDFilter]) - Optional - Filter by product ID.
- **billing_type** (OptionalNullable[models.QueryParamProductBillingTypeFilter]) - Optional - Filter by billing type. `recurring` filters subscription creations or renewals. `one_time` filters one-time purchases.
- **customer_id** (OptionalNullable[models.MetricsGetQueryParamCustomerIDFilter]) - Optional - Filter by customer ID.
- **metrics** (List[str]) - Optional - List of metric slugs to focus on. If provided, only necessary queries are executed for performance. If not provided, all metrics are returned.

### Response
#### Success Response (200)
- **metrics_data** (object) - The retrieved metric data.

#### Response Example
{
  "metrics_data": {
    "example_metric_1": 123,
    "example_metric_2": 45.67
  }
}
```

--------------------------------

### Product Configuration Parameters

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/discountproduct.md

Details on the parameters used to configure a product, including trial settings, name, description, visibility, and recurring subscription intervals.

```APIDOC
## Product Configuration Parameters

### Description
This section outlines the parameters available for defining and configuring products. These include settings for trial periods, product identification, descriptive information, visibility settings, and subscription recurrence.

### Parameters
#### Request Body Fields
- **trial_interval** (Nullable[models.TrialInterval]) - Required - The interval unit for the trial period.
- **trial_interval_count** (Nullable[int]) - Required - The number of interval units for the trial period.
- **name** (str) - Required - The name of the product.
- **description** (Nullable[str]) - Optional - The description of the product.
- **visibility** (models.ProductVisibility) - Required - Visibility settings for the product.
- **recurring_interval** (Nullable[models.SubscriptionRecurringInterval]) - Optional - The recurring interval of the product. If `None`, the product is a one-time purchase.

### Request Example
```json
{
  "trial_interval": "month",
  "trial_interval_count": 1,
  "name": "Premium Subscription",
  "description": "Access to all premium features.",
  "visibility": "public",
  "recurring_interval": "month"
}
```

### Response
#### Success Response (200)
- **trial_interval** (Nullable[models.TrialInterval]) - The interval unit for the trial period.
- **trial_interval_count** (Nullable[int]) - The number of interval units for the trial period.
- **name** (str) - The name of the product.
- **description** (Nullable[str]) - The description of the product.
- **visibility** (models.ProductVisibility) - Visibility settings for the product.
- **recurring_interval** (Nullable[models.SubscriptionRecurringInterval]) - The recurring interval of the product. If `None`, the product is a one-time purchase.

#### Response Example
```json
{
  "trial_interval": "month",
  "trial_interval_count": 1,
  "name": "Premium Subscription",
  "description": "Access to all premium features.",
  "visibility": "public",
  "recurring_interval": "month"
}
```
```

--------------------------------

### MetricsGetDashboardRequest Structure

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/metricsgetdashboardrequest.md

Defines the structure for a request to get a metric dashboard.

```APIDOC
## MetricsGetDashboardRequest

### Description
Represents a request to retrieve a specific metric dashboard.

### Fields
#### Request Body
- **id** (string) - Required - The metric dashboard ID.
```

--------------------------------

### GET /events

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/eventtypeslistrequest.md

Retrieves a list of events with optional filtering and pagination.

```APIDOC
## GET /events

### Description
Retrieves a list of events. Supports filtering by parent event ID, event source, and pagination.

### Method
GET

### Endpoint
/events

### Parameters
#### Query Parameters
- **parent_id** (Optional[Nullable[str]]) - Optional - Filter by specific parent event ID.
- **source** (Optional[Nullable[models.EventSource]]) - Optional - Filter by event source (system or user).
- **page** (Optional[int]) - Optional - Page number, defaults to 1.
- **limit** (Optional[int]) - Optional - Size of a page, defaults to 10. Maximum is 100.
- **sorting** (List[models.EventTypesSortProperty]) - Optional - Sorting criterion. Several criteria can be used simultaneously and will be applied in order. Add a minus sign `-` before the criteria name to sort by descending order.

### Response
#### Success Response (200)
- **events** (List[models.Event]) - A list of event objects.
- **next_page_token** (str) - A token to retrieve the next page of results, if available.

#### Response Example
{
  "events": [
    {
      "event_id": "evt_abc123",
      "timestamp": "2023-10-27T10:00:00Z",
      "event_type": "issue_created",
      "metadata": {
        "issue_id": "iss_xyz789"
      }
    }
  ],
  "next_page_token": "token_def456"
}
```

--------------------------------

### DiscountPercentageRepeatDurationCreate Model

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/discountcreate.md

Use this model to create a percentage-based discount that applies repeatedly for a defined duration. Replace /* values here */ with the actual discount configuration.

```python
value: models.DiscountPercentageRepeatDurationCreate = /* values here */
```

--------------------------------

### GET /customer/portal/benefit_grants

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/customerportalbenefitgrantslistrequest.md

Retrieves a list of benefit grants with optional filters.

```APIDOC
## GET /customer/portal/benefit_grants

### Description
Retrieves a list of benefit grants. This endpoint supports filtering by benefit description, type, ID, checkout ID, and order ID.

### Method
GET

### Endpoint
/customer/portal/benefit_grants

### Query Parameters
- **query** (Optional[str]) - Optional - Filter by benefit description.
- **type_filter** (Optional[models.QueryParamBenefitTypeFilter]) - Optional - Filter by benefit type.
- **benefit_id** (Optional[models.CustomerPortalBenefitGrantsListQueryParamBenefitIDFilter]) - Optional - Filter by benefit ID.
- **checkout_id** (Optional[models.QueryParamCheckoutIDFilter]) - Optional - Filter by checkout ID.
- **order_id** (Optional[models.CustomerPortalBenefitGrantsListQueryParamOrderIDFilter]) - Optional - Filter by order ID.

### Response
#### Success Response (200)
- **[Response fields will be detailed here based on the API's actual response structure]**

#### Response Example
```json
{
  "example": "[Example response body]"
}
```
```

--------------------------------

### Create Custom Benefit

Source: https://context7.com/polarsource/polar-python/llms.txt

Create a new benefit of type 'custom'. This example sets up a 'Premium Support Access' benefit with a contact note.

```python
custom_benefit = polar.benefits.create(request={
    "type": "custom",
    "description": "Premium Support Access",
    "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
    "properties": {
        "note": "Contact support@example.com for priority assistance",
    },
})
```

--------------------------------

### GET /benefit_grants

Source: https://github.com/polarsource/polar-python/blob/main/docs/models/benefitgrantslistrequest.md

Retrieves a list of benefit grants with optional filtering.

```APIDOC
## GET /benefit_grants

### Description
Retrieves a list of benefit grants, allowing filtering by organization, customer, external customer ID, grant status, and pagination.

### Method
GET

### Endpoint
/benefit_grants

### Query Parameters
- **organization_id** (OptionalNullable[models.BenefitGrantsListQueryParamOrganizationIDFilter]) - Optional - Filter by organization ID.
- **customer_id** (OptionalNullable[models.BenefitGrantsListQueryParamCustomerIDFilter]) - Optional - Filter by customer ID.
- **external_customer_id** (OptionalNullable[models.QueryParamExternalCustomerIDFilter]) - Optional - Filter by customer external ID.
- **is_granted** (OptionalNullable[bool]) - Optional - Filter by granted status. If `true`, only granted benefits will be returned. If `false`, only revoked benefits will be returned.
- **page** (Optional[int]) - Optional - Page number, defaults to 1.

### Response
#### Success Response (200)
- **body** (object) - A list of benefit grants matching the query criteria.

#### Response Example
{
  "example": "[List of benefit grant objects]"
}
```

--------------------------------

### List Products with Polar Python SDK

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/products/README.md

Use this snippet to list products. Ensure you have initialized the Polar SDK with your access token. The `organization_id` can be set to `None` to list across all organizations you have access to. Pagination is handled by calling `.next()` on the result.

```python
from polar_sdk import Polar


with Polar(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.products.list(organization_id=None, page=1, limit=10)

    while res is not None:
        # Handle items

        res = res.next()
```

--------------------------------

### GET /meters/quantities

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/meters/README.md

Retrieves meter quantities based on specified filters and aggregation.

```APIDOC
## GET /meters/quantities

### Description
Retrieves meter quantities, with options to filter by customer ID, external customer ID, and metadata. It also supports customer aggregation functions.

### Method
GET

### Endpoint
/meters/quantities

### Parameters
#### Query Parameters
- **customer_id** (OptionalNullable[models.MetersQuantitiesQueryParamCustomerIDFilter]) - Optional - Filter by customer ID.
- **external_customer_id** (OptionalNullable[models.MetersQuantitiesQueryParamExternalCustomerIDFilter]) - Optional - Filter by external customer ID.
- **customer_aggregation_function** (OptionalNullable[models.AggregationFunction]) - Optional - If set, will first compute the quantities per customer before aggregating them using the given function. If not set, the quantities will be aggregated across all events.
- **metadata** (Dict[str, models.MetadataQuery]) - Optional - Filter by metadata key-value pairs. It uses the `deepObject` style, e.g. `?metadata[key]=value`.
- **retries** (Optional[utils.RetryConfig]) - Optional - Configuration to override the default retry behavior of the client.

### Response
#### Success Response (200)
- **response** (models.MeterQuantities) - The meter quantities.

#### Response Example
```json
{
  "example": "response body"
}
```

### Errors
- **models.ResourceNotFound** - Status Code: 404, Content Type: application/json
- **models.HTTPValidationError** - Status Code: 422, Content Type: application/json
- **models.SDKError** - Status Code: 4XX, 5XX, Content Type: */*
```

--------------------------------

### List License Keys

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/licensekeys/README.md

Use this to list license keys connected to an organization. Handles pagination automatically.

```python
from polar_sdk import Polar


with Polar(
    access_token="<YOUR_BEARER_TOKEN_HERE>",
) as polar:

    res = polar.license_keys.list(organization_id="1dbfc517-0bbf-4301-9ba8-555ca42b9737", page=1, limit=10)

    while res is not None:
        # Handle items

        res = res.next()
```

--------------------------------

### Get Organization

Source: https://github.com/polarsource/polar-python/blob/main/docs/sdks/polarorganizations/README.md

Retrieves a customer portal's organization by its unique slug.

```APIDOC
## GET /v1/customer-portal/organizations/{slug}

### Description
Get a customer portal's organization by slug.

### Method
GET

### Endpoint
/v1/customer-portal/organizations/{slug}

### Parameters
#### Path Parameters
- **slug** (string) - Required - The organization slug.
#### Query Parameters
- **retries** (Optional[utils.RetryConfig]) - Optional - Configuration to override the default retry behavior of the client.

### Request Example
```python
from polar_sdk import Polar


with Polar() as polar:

    res = polar.customer_portal.organizations.get(slug="<value>")

    # Handle response
    print(res)
```

### Response
#### Success Response (200)
- **(models.CustomerOrganizationData)** - Description of the organization data.

#### Error Response
- **models.ResourceNotFound** - Status Code: 404, Content Type: application/json
- **models.HTTPValidationError** - Status Code: 422, Content Type: application/json
- **models.SDKError** - Status Code: 4XX, 5XX, Content Type: */*
```

--------------------------------

### Asynchronous SDK Usage Example

Source: https://github.com/polarsource/polar-python/blob/main/README.md

Shows how to use the Polar SDK for asynchronous API calls using asyncio, including handling paginated results.

```python
# Asynchronous Example
import asyncio
from polar_sdk import Polar

async def main():

    async with Polar(
        access_token="<YOUR_BEARER_TOKEN_HERE>",
    ) as polar:

        res = await polar.organizations.list_async(page=1, limit=10)

        while res is not None:
            # Handle items

            res = res.next()

asyncio.run(main())

```