Overview
Customers represent individuals or organizations that purchase your products. They can have subscriptions, orders, and benefits.
The Customer Object
Unique identifier for the customer
Your internal ID for this customer
Tax ID (VAT number, etc.)
Organization owning this customer
List Customers
curl -X GET "https://api.polar.sh/v1/customers" \
-H "Authorization: Bearer polar_pat_..."
Query Parameters
Search by name, email, or external ID
Get Customer
curl -X GET "https://api.polar.sh/v1/customers/{id}" \
-H "Authorization: Bearer polar_pat_..."
Path Parameters
Get Customer by External ID
curl -X GET "https://api.polar.sh/v1/customers/external/{external_id}" \
-H "Authorization: Bearer polar_pat_..."
Path Parameters
Your external customer ID
Create Customer
curl -X POST "https://api.polar.sh/v1/customers" \
-H "Authorization: Bearer polar_pat_..." \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"name": "John Doe",
"external_id": "user_12345",
"organization_id": "org_123"
}'
Request Body
Your internal customer ID
Organization ID (required unless using org token)
Update Customer
curl -X PATCH "https://api.polar.sh/v1/customers/{id}" \
-H "Authorization: Bearer polar_pat_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Doe",
"metadata": {
"tier": "premium"
}
}'
Path Parameters
Request Body
All fields optional.
Update by External ID
curl -X PATCH "https://api.polar.sh/v1/customers/external/{external_id}" \
-H "Authorization: Bearer polar_pat_..." \
-H "Content-Type: application/json" \
-d '{"name": "Jane Doe"}'
Delete Customer
curl -X DELETE "https://api.polar.sh/v1/customers/{id}" \
-H "Authorization: Bearer polar_pat_..."
This immediately cancels all active subscriptions and revokes all benefits. Customer information is retained for historical orders.
Path Parameters
Query Parameters
Also anonymize personal data for GDPR compliance
Response
Get Customer State
curl -X GET "https://api.polar.sh/v1/customers/{id}/state" \
-H "Authorization: Bearer polar_pat_..."
Path Parameters
Response
Export Customers
curl -X GET "https://api.polar.sh/v1/customers/export" \
-H "Authorization: Bearer polar_pat_..."
Response
Returns a CSV file with customer data.
Examples
Create Customer with External ID
curl -X POST "https://api.polar.sh/v1/customers" \
-H "Authorization: Bearer polar_pat_..." \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"name": "John Doe",
"external_id": "user_abc123",
"organization_id": "org_xyz",
"metadata": {
"signup_source": "website",
"plan": "trial"
}
}'
Update Customer Billing Address
curl -X PATCH "https://api.polar.sh/v1/customers/cust_123" \
-H "Authorization: Bearer polar_pat_..." \
-H "Content-Type: application/json" \
-d '{
"billing_address": {
"line1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"postal_code": "94102",
"country": "US"
}
}'
Get Customer by Your ID
curl -X GET "https://api.polar.sh/v1/customers/external/user_abc123" \
-H "Authorization: Bearer polar_pat_..."
Delete and Anonymize
curl -X DELETE "https://api.polar.sh/v1/customers/cust_123?anonymize=true" \
-H "Authorization: Bearer polar_pat_..."