Customers

(customers)

Overview

Available Operations

list - List Customers
create - Create Customer
export - Export Customers
get - Get Customer
update - Update Customer
delete - Delete Customer
get_external - Get Customer by External ID
update_external - Update Customer by External ID
delete_external - Delete Customer by External ID
get_state - Get Customer State
get_state_external - Get Customer State by External ID

list

List customers.

Scopes: customers:read customers:write

Example Usage

from polar_sdk import Polar


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

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

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter	Type	Required	Description
`organization_id`	OptionalNullable[models.CustomersListQueryParamOrganizationIDFilter]	➖	Filter by organization ID.
`email`	OptionalNullable[str]	➖	Filter by exact email.
`query`	OptionalNullable[str]	➖	Filter by name, email, or external ID.
`page`	Optional[int]	➖	Page number, defaults to 1.
`limit`	Optional[int]	➖	Size of a page, defaults to 10. Maximum is 100.
`sorting`	List[models.CustomerSortProperty]	➖	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.
`metadata`	Dict[str, models.MetadataQuery]	➖	Filter by metadata key-value pairs. It uses the `deepObject` style, e.g. `?metadata[key]=value`.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.CustomersListResponse

Errors

Error Type	Status Code	Content Type
models.HTTPValidationError	422	application/json
models.SDKError	4XX, 5XX	/

create

Create a customer.

Scopes: customers:write

Example Usage

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)

Parameters

Parameter	Type	Required	Description
`request`	models.CustomerCreate	✔️	The request object to use for the request.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.Customer

Errors

Error Type	Status Code	Content Type
models.HTTPValidationError	422	application/json
models.SDKError	4XX, 5XX	/

export

Export customers as a CSV file.

Scopes: customers:read customers:write

Example Usage

from polar_sdk import Polar


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

    res = polar.customers.export(organization_id="1dbfc517-0bbf-4301-9ba8-555ca42b9737")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`organization_id`	OptionalNullable[models.CustomersExportQueryParamOrganizationID]	➖	Filter by organization ID.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.CustomersExportResponse

Errors

Error Type	Status Code	Content Type
models.HTTPValidationError	422	application/json
models.SDKError	4XX, 5XX	/

get

Get a customer by ID.

Scopes: customers:read customers:write

Example Usage

from polar_sdk import Polar


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

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

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`id`	str	✔️	The customer ID.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.Customer

Errors

Error Type	Status Code	Content Type
models.ResourceNotFound	404	application/json
models.HTTPValidationError	422	application/json
models.SDKError	4XX, 5XX	/

update

Update a customer.

Scopes: customers:write

Example Usage

import polar_sdk
from polar_sdk import Polar


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

    res = polar.customers.update(id="<value>", customer_update={
        "email": "customer@example.com",
        "name": "John Doe",
        "billing_address": {
            "country": polar_sdk.AddressInputCountryAlpha2Input.US,
        },
        "locale": "en",
        "external_id": "usr_1337",
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`id`	str	✔️	The customer ID.
`customer_update`	models.CustomerUpdate	✔️	N/A
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.Customer

Errors

Error Type	Status Code	Content Type
models.ResourceNotFound	404	application/json
models.HTTPValidationError	422	application/json
models.SDKError	4XX, 5XX	/

delete

Delete a customer.

This action cannot be undone and will immediately:

Cancel any active subscriptions for the customer
Revoke all their benefits
Clear any external_id

Use it only in the context of deleting a user within your own service. Otherwise, use more granular API endpoints to cancel a specific subscription or revoke certain benefits.

Note: The customers information will nonetheless be retained for historic orders and subscriptions.

Set anonymize=true to also anonymize PII for GDPR compliance.

Scopes: customers:write

Example Usage

from polar_sdk import Polar


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

    polar.customers.delete(id="<value>", anonymize=False)

    # Use the SDK ...

Parameters

Parameter	Type	Required	Description
`id`	str	✔️	The customer ID.
`anonymize`	Optional[bool]	➖	If true, also anonymize the customer's personal data for GDPR compliance. This replaces email with a hashed version, hashes name and billing name (name preserved for businesses with tax_id), clears billing address, and removes OAuth account data.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Errors

Error Type	Status Code	Content Type
models.ResourceNotFound	404	application/json
models.HTTPValidationError	422	application/json
models.SDKError	4XX, 5XX	/

get_external

Get a customer by external ID.

Scopes: customers:read customers:write

Example Usage

from polar_sdk import Polar


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

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

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`external_id`	str	✔️	The customer external ID.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.Customer

Errors

Error Type	Status Code	Content Type
models.ResourceNotFound	404	application/json
models.HTTPValidationError	422	application/json
models.SDKError	4XX, 5XX	/

update_external

Update a customer by external ID.

Scopes: customers:write

Example Usage

from polar_sdk import Polar


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

    res = polar.customers.update_external(external_id="<id>", customer_update_external_id={
        "email": "customer@example.com",
        "name": "John Doe",
        "billing_address": None,
        "locale": "en",
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`external_id`	str	✔️	The customer external ID.
`customer_update_external_id`	models.CustomerUpdateExternalID	✔️	N/A
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.Customer

Errors

Error Type	Status Code	Content Type
models.ResourceNotFound	404	application/json
models.HTTPValidationError	422	application/json
models.SDKError	4XX, 5XX	/

delete_external

Delete a customer by external ID.

Immediately cancels any active subscriptions and revokes any active benefits.

Set anonymize=true to also anonymize PII for GDPR compliance.

Scopes: customers:write

Example Usage

from polar_sdk import Polar


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

    polar.customers.delete_external(external_id="<id>", anonymize=False)

    # Use the SDK ...

Parameters

Parameter	Type	Required	Description
`external_id`	str	✔️	The customer external ID.
`anonymize`	Optional[bool]	➖	If true, also anonymize the customer's personal data for GDPR compliance.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Errors

Error Type	Status Code	Content Type
models.ResourceNotFound	404	application/json
models.HTTPValidationError	422	application/json
models.SDKError	4XX, 5XX	/

get_state

Get a customer state by ID.

The customer state includes information about the customer's active subscriptions and benefits.

It's the ideal endpoint to use when you need to get a full overview of a customer's status.

Scopes: customers:read customers:write

Example Usage

from polar_sdk import Polar


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

    res = polar.customers.get_state(id="<value>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`id`	str	✔️	The customer ID.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.CustomerState

Errors

Error Type	Status Code	Content Type
models.ResourceNotFound	404	application/json
models.HTTPValidationError	422	application/json
models.SDKError	4XX, 5XX	/

get_state_external

Get a customer state by external ID.

The customer state includes information about the customer's active subscriptions and benefits.

It's the ideal endpoint to use when you need to get a full overview of a customer's status.

Scopes: customers:read customers:write

Example Usage

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)

Parameters

Parameter	Type	Required	Description
`external_id`	str	✔️	The customer external ID.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.CustomerState

Errors

Error Type	Status Code	Content Type
models.ResourceNotFound	404	application/json
models.HTTPValidationError	422	application/json
models.SDKError	4XX, 5XX	/

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Customers

Overview

Available Operations

list

Example Usage

Parameters

Response

Errors

create

Example Usage

Parameters

Response

Errors

export

Example Usage

Parameters

Response

Errors

get

Example Usage

Parameters

Response

Errors

update

Example Usage

Parameters

Response

Errors

delete

Example Usage

Parameters

Errors

get_external

Example Usage

Parameters

Response

Errors

update_external

Example Usage

Parameters

Response

Errors

delete_external

Example Usage

Parameters

Errors

get_state

Example Usage

Parameters

Response

Errors

get_state_external

Example Usage

Parameters

Response

Errors