class

Polar::Api::Customers

Inherits Reference < Object

API client for customers operations

Constants

Log = ::Log.for(self)

Constructors

new(client : Client)

Creates a new Customers instance

@param client [Client] The Polar API client instance

Source

Instance methods

create(body : Polar::Models::CustomerCreate) : Polar::Models::Customer

Create Customer

Create a customer.

Scopes: customers:write

Endpoint: POST /v1/customers/

Parameters:

body (required): Request body as Polar::Models::CustomerCreate

Returns: Polar::Models::Customer

Raises:

ResourceNotFoundError on 404
NotPermittedError on 403
HTTPValidationError on 422
PolarError on other errors

Source

delete(id : String)

Delete Customer

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.

Scopes: customers:write

Endpoint: DELETE /v1/customers/{id}

Parameters:

id (required): The customer ID.

Returns: JSON response string

Raises:

ResourceNotFoundError on 404
NotPermittedError on 403
HTTPValidationError on 422
PolarError on other errors

Source

delete_external(external_id : String)

Delete Customer by External ID

Delete a customer by external ID.

Immediately cancels any active subscriptions and revokes any active benefits.

Scopes: customers:write

Endpoint: DELETE /v1/customers/external/{external_id}

Parameters:

external_id (required): The customer external ID.

Returns: JSON response string

Raises:

ResourceNotFoundError on 404
NotPermittedError on 403
HTTPValidationError on 422
PolarError on other errors

Source

export(organization_id : String | Nil = nil)

Export Customers

Export customers as a CSV file.

Scopes: customers:read customers:write

Endpoint: GET /v1/customers/export

Parameters:

organization_id (optional): Filter by organization ID.

Returns: JSON response string

Raises:

ResourceNotFoundError on 404
NotPermittedError on 403
HTTPValidationError on 422
PolarError on other errors

Source

get(id : String) : Polar::Models::Customer

Get Customer

Get a customer by ID.

Scopes: customers:read customers:write

Endpoint: GET /v1/customers/{id}

Parameters:

id (required): The customer ID.

Returns: Polar::Models::Customer

Raises:

ResourceNotFoundError on 404
NotPermittedError on 403
HTTPValidationError on 422
PolarError on other errors

Source

get_balance(id : String) : Polar::Models::CustomerBalance

Get Customer Balance

Get customer balance information.

Scopes: customers:read customers:write

Endpoint: GET /v1/customers/{id}/balance

Parameters:

id (required): The customer ID.

Returns: Polar::Models::CustomerBalance

Raises:

ResourceNotFoundError on 404
NotPermittedError on 403
HTTPValidationError on 422
PolarError on other errors

Source

get_external(external_id : String) : Polar::Models::Customer

Get Customer by External ID

Get a customer by external ID.

Scopes: customers:read customers:write

Endpoint: GET /v1/customers/external/{external_id}

Parameters:

external_id (required): The customer external ID.

Returns: Polar::Models::Customer

Raises:

ResourceNotFoundError on 404
NotPermittedError on 403
HTTPValidationError on 422
PolarError on other errors

Source

get_state(id : String) : Polar::Models::CustomerState

Get Customer 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

Endpoint: GET /v1/customers/{id}/state

Parameters:

id (required): The customer ID.

Returns: Polar::Models::CustomerState

Raises:

ResourceNotFoundError on 404
NotPermittedError on 403
HTTPValidationError on 422
PolarError on other errors

Source

get_state_external(external_id : String) : Polar::Models::CustomerState

Get Customer State by External ID

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

Endpoint: GET /v1/customers/external/{external_id}/state

Parameters:

external_id (required): The customer external ID.

Returns: Polar::Models::CustomerState

Raises:

ResourceNotFoundError on 404
NotPermittedError on 403
HTTPValidationError on 422
PolarError on other errors

Source

List Customers

List customers.

Scopes: customers:read customers:write

Endpoint: GET /v1/customers/

Parameters:

organization_id (optional): Filter by organization ID.
email (optional): Filter by exact email.
query (optional): Filter by name, email, or external ID.
page (optional): Page number, defaults to 1.
limit (optional): Size of a page, defaults to 10. Maximum is 100.
sorting (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.
metadata (optional): Filter by metadata key-value pairs. It uses the deepObject style, e.g. ?metadata[key]=value.