Skip to main content
Customer Seats allow you to assign and manage individual seats within team subscriptions. Each seat can be claimed by a team member to access the benefits.

​
Base URL

https://api.polar.sh/v1/customer-seats

​
Authentication

Customer seat endpoints require authentication with an Organization Access Token or Personal Access Token.

​
Assign Seat

Assign a seat to a customer email address. This creates an invitation that the recipient can claim. 
curl -X POST "https://api.polar.sh/v1/customer-seats" \
  -H "Authorization: Bearer polar_oat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_...",
    "subscription_id": "sub_...",
    "email": "[email protected]"
  }'

​
Request Body

​
customer_id
string
required
ID of the customer (team owner)
​
subscription_id
string
required
ID of the seat-based subscription
​
email
string
required
Email address to assign the seat to

​
Response

​
id
string
Unique seat assignment ID
​
customer_id
string
Customer who owns the subscription
​
subscription_id
string
Associated subscription ID
​
email
string
Email address of the assigned seat
​
status
string
Seat status: pending, claimed, revoked
​
invitation_token
string
Token for claiming the seat (only for pending seats)
​
claimed_at
string | null
Timestamp when the seat was claimed
​
claimed_by_customer_id
string | null
Customer ID who claimed the seat

​
List Customer Seats

List all seat assignments for a subscription.
cURL
curl -X GET "https://api.polar.sh/v1/customer-seats?subscription_id=sub_..." \
  -H "Authorization: Bearer polar_oat_..."

​
Query Parameters

​
subscription_id
string
required
Filter by subscription ID
​
customer_id
string
Filter by customer ID
​
status
string
Filter by status: pending, claimed, revoked
​
page
integer
default:1
Page number
​
limit
integer
default:10
Results per page

​
Response

Returns a paginated list of seat assignments with their status.

​
Revoke Seat

Revoke a seat assignment. This removes access for the seat holder.
cURL
curl -X DELETE "https://api.polar.sh/v1/customer-seats/{id}" \
  -H "Authorization: Bearer polar_oat_..."

​
Path Parameters

​
id
string
required
The seat assignment ID to revoke

​
Response

Returns the revoked seat object with status revoked.
Revoking a seat immediately removes the benefit grants for that seat holder.

​
Resend Invitation

Resend the invitation email for a pending seat.
cURL
curl -X POST "https://api.polar.sh/v1/customer-seats/{id}/resend" \
  -H "Authorization: Bearer polar_oat_..."

​
Path Parameters

​
id
string
required
The seat assignment ID

​
Response

Returns 200 OK if the invitation was resent successfully.

​
Get Claim Information

Get information about a seat invitation using the invitation token (public endpoint).
cURL
curl -X GET "https://api.polar.sh/v1/customer-seats/claim/{token}"

​
Path Parameters

​
token
string
required
The invitation token

​
Response

Returns seat information without requiring authentication.

​
Claim Seat

Claim a seat using the invitation token (requires customer authentication).
cURL
curl -X POST "https://api.polar.sh/v1/customer-seats/claim/{token}" \
  -H "Authorization: Bearer customer_session_..."

​
Path Parameters

​
token
string
required
The invitation token from the email

​
Response

Returns the claimed seat with status claimed and grants the associated benefits.

​
Seat Lifecycle

┌─────────────┐
│   pending   │  Created when seat is assigned
└──────┬──────┘
       │
       │ User clicks invitation link
       ▼
┌─────────────┐
│   claimed   │  User gains access to benefits
└──────┬──────┘
       │
       │ Admin revokes seat
       ▼
┌─────────────┐
│   revoked   │  Benefits removed
└─────────────┘

​
Webhooks

Subscribe to seat events:
  • customer_seat.assigned - Seat assigned to email
  • customer_seat.claimed - Seat claimed by user
  • customer_seat.revoked - Seat access revoked
// Webhook payload example
{
  "type": "customer_seat.claimed",
  "data": {
    "id": "seat_...",
    "customer_id": "cust_...",
    "subscription_id": "sub_...",
    "email": "[email protected]",
    "status": "claimed",
    "claimed_at": "2024-03-15T10:30:00Z",
    "claimed_by_customer_id": "cust_member_..."
  }
}

​
Use Cases

​
Team Onboarding

// Assign seats to all team members
const teamEmails = [
  '[email protected]',
  '[email protected]',
  '[email protected]'
];

for (const email of teamEmails) {
  await polar.customerSeats.assign({
    customerId: teamCustomerId,
    subscriptionId: subscriptionId,
    email: email
  });
}

​
Self-Service Management

Allow team admins to manage their own seats: 
// List current seats
const seats = await polar.customerSeats.list({
  subscriptionId: subscriptionId
});

// Revoke a seat
await polar.customerSeats.revoke(seatId);

// Add a new seat (if available)
await polar.customerSeats.assign({
  customerId: customerId,
  subscriptionId: subscriptionId,
  email: '[email protected]'
});

​
Seat Usage Monitoring

const seats = await polar.customerSeats.list({
  subscriptionId: subscriptionId
});

const total = seats.pagination.total_count;
const claimed = seats.items.filter(s => s.status === 'claimed').length;
const pending = seats.items.filter(s => s.status === 'pending').length;

console.log(`Seats: ${claimed}/${total} claimed, ${pending} pending`);

Build docs developers (and LLMs) love

Get started for freeTalk to us