Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/polarsource/polar/llms.txt

Use this file to discover all available pages before exploring further.

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": "member@team.com"
  }'

​
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": "member@team.com",
    "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 = [
  'alice@team.com',
  'bob@team.com',
  'charlie@team.com'
];

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: 'newmember@team.com'
});

​
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