# `PolarExpress`
[🔗](https://github.com/jeffhuen/polar_express/blob/main/lib/polar_express.ex#L1)

Elixir SDK and client for the Polar API.

## Configuration

Add your PolarExpress credentials to your application config:

    # config/runtime.exs
    config :polar_express,
      api_key: System.fetch_env!("POLAR_ACCESS_TOKEN"),
      webhook_secret: System.fetch_env!("POLAR_WEBHOOK_SECRET")

Then create a client — it picks up your config automatically:

    client = PolarExpress.client()

    {:ok, customer} = PolarExpress.Services.CustomersService.create_customer(client, %{
      email: "jane@example.com"
    })

## Per-Client Overrides

Override any config option when creating a client:

    # Use sandbox environment
    client = PolarExpress.client(server: :sandbox)

    # Explicit key (ignores config)
    client = PolarExpress.client("pk_test_other", max_retries: 5)

## Config Precedence

Options are resolved in this order (highest wins):

  1. Explicit arguments to `client/1` or `client/2`
  2. Application config (`config :polar_express, ...`)
  3. Struct defaults (e.g. `max_retries: 2`)

## Supported Config Keys

Client options (used by `PolarExpress.client/0,1,2`):

  * `:api_key` - Polar API key (required)
  * `:server` - API environment: `:production` or `:sandbox` (default: `:production`)
  * `:max_retries` - Maximum retry attempts (default: 2)
  * `:timeout_ms` - Request timeout in ms (default: 30_000)
  * `:finch` - Custom Finch instance name (default: `PolarExpress.Finch`)

Non-client options (used by other modules):

  * `:webhook_secret` - Webhook signing secret (used by `PolarExpress.WebhookPlug`)

# `benefit_grants`

Get BenefitGrantsService module

# `benefits`

Get BenefitsService module

# `checkout_links`

Get CheckoutLinksService module

# `checkouts`

Get CheckoutsService module

# `client`

```elixir
@spec client() :: PolarExpress.Client.t()
```

Create a new PolarExpress client from application config.

Reads `:api_key` and other options from `config :polar_express`.
Raises if `:api_key` is not configured.

## Example

    # config/runtime.exs
    config :polar_express, api_key: System.fetch_env!("POLAR_ACCESS_TOKEN")

    # Then in your code:
    client = PolarExpress.client()

# `client`

```elixir
@spec client(String.t() | keyword()) :: PolarExpress.Client.t()
```

Create a new PolarExpress client with overrides.

When given a string, treated as an explicit API key.
When given a keyword list, merges with application config.

## Examples

    # Explicit API key
    client = PolarExpress.client("pk_test_...")

    # Config defaults + overrides
    client = PolarExpress.client(server: :sandbox, max_retries: 5)

# `client`

```elixir
@spec client(
  String.t(),
  keyword()
) :: PolarExpress.Client.t()
```

Create a new PolarExpress client with an explicit API key.

Application config provides defaults for all other options.

## Examples

    client = PolarExpress.client("pk_test_...")
    client = PolarExpress.client("pk_test_...", server: :sandbox, max_retries: 5)

# `custom_fields`

Get CustomFieldsService module

# `customer_meters`

Get CustomerMetersService module

# `customer_portal`

Get CustomerPortal namespace with 12 sub-services

# `customer_seats`

Get CustomerSeatsService module

# `customer_sessions`

Get CustomerSessionsService module

# `customers`

Get CustomersService module

# `discounts`

Get DiscountsService module

# `disputes`

Get DisputesService module

# `event_types`

Get EventTypesService module

# `events`

Get EventsService module

# `files`

Get FilesService module

# `license_keys`

Get LicenseKeysService module

# `member_sessions`

Get MemberSessionsService module

# `members`

Get MembersService module

# `meters`

Get MetersService module

# `metrics`

Get MetricsService module

# `oauth2`

Get Oauth2Service module

# `orders`

Get OrdersService module

# `organization_access_tokens`

Get OrganizationAccessTokensService module

# `organizations`

Get OrganizationsService module

# `payments`

Get PaymentsService module

# `products`

Get ProductsService module

# `refunds`

Get RefundsService module

# `subscriptions`

Get SubscriptionsService module

# `version`

```elixir
@spec version() :: String.t()
```

Returns the library version.

# `webhooks`

Get WebhooksService module

---

*Consult [api-reference.md](api-reference.md) for complete listing*