Skip to main content
The Customer Portal API provides endpoints for authenticated customers to manage their purchases, subscriptions, payment methods, and benefits directly from your application.

​
Authentication

The Customer Portal API uses session-based authentication with magic link codes sent via email. Customers authenticate without needing a password.

​
Authentication Flow

1

Request a session code

Call POST /v1/customer-portal/customer-session/request with the customer’s email and organization ID.
curl -X POST https://api.polar.sh/v1/customer-portal/customer-session/request \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "organization_id": "your-org-id"
  }'
The customer receives an email with a 6-digit code.
2

Authenticate with the code

Exchange the code for a session token using POST /v1/customer-portal/customer-session/authenticate.
curl -X POST https://api.polar.sh/v1/customer-portal/customer-session/authenticate \
  -H "Content-Type: application/json" \
  -d '{"code": "ABC123"}'
Returns a token:
{
  "token": "polar_cst_..."
}
3

Use the token in requests

Include the token in the Authorization header for all Customer Portal API requests.
curl https://api.polar.sh/v1/customer-portal/subscriptions \
  -H "Authorization: Bearer polar_cst_..."

​
Multiple Customers with Same Email

When multiple customers share the same email address across different products, the request will return a 409 status with customer selection options: 
{
  "error": "customer_selection_required",
  "detail": "Multiple customers found for this email. Please select one.",
  "customers": [
    {"id": "customer-id-1", "name": "Acme Corp"},
    {"id": "customer-id-2", "name": "Personal Account"}
  ]
}
Retry the request with the selected customer_id: 
{
  "email": "[email protected]",
  "organization_id": "your-org-id",
  "customer_id": "customer-id-1"
}

​
Session Introspection

Retrieve information about the current session: 
GET /v1/customer-portal/customer-session/introspect
Returns session expiration and return URL.

​
Authenticated User Info

Get details about the authenticated customer or member: 
GET /v1/customer-portal/customer-session/user
Returns: 
{
  "type": "customer",
  "name": "John Doe",
  "email": "[email protected]",
  "customer_id": "...",
  "member_id": null,
  "role": null
}
For organizations with team features enabled, the type can be "member" with role information (owner, billing_manager, member).

​
Member vs Customer Sessions

Polar supports two authentication models:
  • Customer Sessions (legacy): Direct customer authentication
  • Member Sessions: For organizations with team management enabled, where multiple members can access a customer account
The API automatically handles both types. Members may have restricted permissions based on their role:
  • owner: Full access to all features
  • billing_manager: Can manage billing, subscriptions, and payment methods
  • member: Read-only access to purchases and benefits

​
Available Endpoints

The Customer Portal API provides the following resource endpoints:

Sessions

Authenticate customers and manage portal sessions

Subscriptions

View and manage customer subscriptions

Orders

Access order history and invoices

Customer

Manage customer profile and payment methods

Benefit Grants

Access granted benefits from purchases

Seats

Manage seat assignments for team subscriptions

​
Error Handling

The API uses standard HTTP status codes:
  • 200: Success
  • 201: Resource created
  • 204: Success with no content
  • 400: Bad request (validation error)
  • 401: Authentication required or invalid token
  • 403: Permission denied
  • 404: Resource not found
  • 409: Conflict (e.g., customer selection required)
  • 422: Unprocessable entity (business logic error)
Error responses include descriptive messages: 
{
  "error": "resource_not_found",
  "detail": "Subscription not found"
}

​
Rate Limiting

The Customer Portal API is subject to rate limiting to ensure service stability. Standard rate limits apply per customer session.

​
Webhooks

While the Customer Portal API is customer-facing, you can receive webhooks for customer actions:
  • subscription.updated: Customer modified their subscription
  • subscription.canceled: Customer canceled their subscription
  • order.updated: Customer updated order details
  • payment_method.created: Customer added a payment method
  • payment_method.deleted: Customer removed a payment method
See the Webhooks documentation for more details.

Build docs developers (and LLMs) love

Get started for freeTalk to us