Implementing Seat-Based Pricing

​

Understanding the model

​

Customer, Member, and CustomerSeat

• A Customer is the billing entity — who pays. They own subscriptions, orders, and payment methods. On first seat-based purchase, the customer is permanently upgraded to type: "team", which enables members and team management.
• A Member is a person under a customer — who uses. Each member has their own email, role (owner, billing_manager, or member), and receives benefit grants independently. The person who purchases the products is created as an owner member.
• A CustomerSeat is the link between a product and a member. It tracks assignment status (pending, claimed, revoked), holds the invitation token, and carries optional metadata.

Customer (Jane — billing manager, type: "team")
  ├── Member: Jane (role: owner)          → manages team, no seat and no product benefits
  ├── Member: Alice (role: member)        → gets benefits via seat
  └── Member: Bob (role: member)          → gets benefits via seat

Subscription (Team Pro — 3 seats)
  ├── CustomerSeat → Alice (claimed)      → benefits granted
  ├── CustomerSeat → Bob (claimed)        → benefits granted
  └── CustomerSeat → unassigned           → available

​

Why this separation matters

• Members persist across products. The same member can hold seats from different subscriptions or orders under the same customer.
• Roles control portal access. Owners and billing managers see full team management. Regular members see only their own benefits.
• Benefits track to people, not purchases. Always use grant.member to identify who has access — grant.customer_id is always the billing entity, not the end user.

​

What this means for your integration

• Benefit grants reference a member, not just a customer. Always use grant.member to identify who received the benefit.
• Webhooks include a member object on seat and grant events. Use it instead of customer_id to identify the end user.
• Benefits are not granted at purchase time. Seats must be assigned and claimed before benefits are granted.

Purchase → Assign seats → Members claim → Benefits granted

​

Prerequisites

• Polar organization with seat-based pricing enabled
• Polar SDK installed (npm install @polar-sh/sdk or pip install polar-sdk) — make sure it’s the latest version
• Basic understanding of Polar products and subscriptions

​

Implementation

​

Step 1: Create a seat-based product

​

Step 2: Checkout

const checkout = await polar.checkouts.create({
  products: ["prod_123"],
  seats: 5,
  success_url: "https://your-app.com/success",
  customer_email: "billing@company.com"
});

// Redirect to checkout.url

​

Step 3: Seat management

• Assign seats to team members by email
• Revoke seats to remove access and free up seats for reassignment
• Resend invitations for pending seats
• Adjust seat count on subscriptions (add or reduce)

​

API-driven seat assignment

const seat = await polar.customerSeats.assign({
  subscription_id: subscriptionId,
  email: "engineer@company.com",
  immediate_claim: true  // Skip invitation email, grant benefits immediately
});

​

Step 4: Handle benefit grants

app.post('/webhooks/polar', async (req, res) => {
  const event = req.body;

  if (event.type === 'benefit_grant.created') {
    const grant = event.data;
    const recipient = grant.member;
    await grantAccess(recipient.id, recipient.email, grant.benefit);
  }

  if (event.type === 'benefit_grant.revoked') {
    const grant = event.data;
    await revokeAccess(grant.member.id, grant.benefit);
  }

  res.sendStatus(200);
});

​

Step 5: Scale seats

await polar.subscriptions.update({
  id: subscriptionId,
  seats: newTotal  // Cannot be less than currently assigned seats (pending + claimed)
});

const checkout = await polar.checkouts.create({
  products: [productId],
  seats: additionalSeats,
  success_url: "https://your-app.com/success"
});
// Each order has its own independent seat pool

​

Member sessions and portal

const session = await polar.memberSessions.create({
  member_id: "mem_789"
});
// Redirect to session.member_portal_url

• Billing managers (owner/billing_manager role) see full team management — assigning seats, managing members, and viewing seat utilization.
• Members see only their own benefits and account details.

​

Webhook events

​

Best practices

• Use grant.member everywhere — not grant.customer_id — to identify who has access
• Use seat metadata to store department, role, or cost center for your own tracking
• Communicate clearly to billing managers that they won’t receive benefits directly

​

Troubleshooting

​

Subscriptions vs one-time purchases

​

Limitations

• Seats must be assigned individually (use API for bulk)
• Claim links expire after 24 hours
• Maximum 1,000 seats per subscription
• Metadata limited to 10 keys and 1KB per seat

​

Next steps

• Seat-Based Pricing Feature Documentation
• Customer Seats API Reference
• Webhook setup
• Customer Portal customization