Implement Member-Based Seat Billing

​

Before you build

• Ruba organization with seat-based pricing enabled
• Ruba SDK installed (npm install @getruba/sdk or pip install ruba-sdk), make sure it’s the latest version
• Basic grasp of Ruba products and subscriptions

​

Build sequence

​

Step 1: Create a seat-based product

​

Step 2: Checkout

const checkout = await ruba.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 strip 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 ruba.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/ruba', async (req, res) => {
  // Verify webhook signature first — see webhook docs
  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 ruba.subscriptions.update({
  id: subscriptionId,
  seats: newTotal  // Cannot be less than currently assigned seats (pending + claimed)
});

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

​

Operating rules

• 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 about seat assignment: if using the default Ruba confirmation page, their seat is auto-claimed; if using a custom success URL, they’ll need to assign themselves a seat through the portal

​

Understanding the model

​

Customer, Member, and CustomerSeat

• A Customer is the billing entity, who pays. They own subscriptions, orders, and payment methods. On the first seat-based purchase, the customer is permanently upgraded to type: "team", which turns on 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 product is created as an owner member. Both owner and billing_manager roles can manage seats, update or cancel the subscription, and manage payment methods. The owner role may pick up additional management capabilities down the road.
• 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 — purchaser, type: "team")
  ├── Member: Jane (role: owner)          → manages team, can self-assign a seat for 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 split 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. (Exception: when using the default Ruba confirmation page, the buyer’s seat is auto-claimed.)

Purchase → Assign seats → Members claim → Benefits granted

​

Member sessions and portal

const session = await ruba.customerSessions.create({
  customer_id: "cust_123",
  member_id: "mem_789"
});
// Redirect to session.customer_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

​

Subscriptions vs one-time purchases

​

Current boundaries

• 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

​

Diagnose the integration

​

Continue the build

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