Seats API

The Seats API provides endpoints for managing seat-based subscriptions. This includes adding and removing seats, and retrieving current seat usage for a subscription. This API is designed to work with plans that are configured for per-unit (seat-based) pricing.

Overview

The Seats API allows you to:

• Add a new user (seat) to a subscription.
• Remove a user (seat) from a subscription.
• Get the current seat usage for a subscription.

These operations automatically trigger the necessary billing events, such as creating prorated charges for new seats.

Authentication

All API requests require authentication via merchant credentials.

Endpoints

Add a Seat

Adds a new user to a seat-based subscription. This will also create a new customer record for the user being added if they don't already exist.

POST https://api.getlumen.dev/v1/seats/add

Request Body

{
  "organization_id": "org_123",
  "created_user_id": "new_user_ext_456",
  "created_user_info": {
    "name": "Jane Doe",
    "email": "jane.doe@example.com"
  },
  "idempotency_key": "unique_seat_add_key"
}

Request Fields

* Either organization_id or user_id must be provided.

Response

{
  "message": "Seat added successfully",
  "created_user_id": "new_user_ext_456",
  "subscription_id": "sub_123",
  "idempotency_key": "unique_seat_add_key"
}

Remove a Seat

Removes a user from a seat-based subscription. This action will also deactivate the user's entitlements and credits associated with the seat.

POST https://api.getlumen.dev/v1/seats/remove

Request Body

{
  "organization_id": "org_123",
  "removed_user_id": "user_ext_456_to_remove"
}

Request Fields

* Either organization_id or user_id must be provided.

Response

{
  "message": "Seat removed successfully",
  "removed_user_id": "user_ext_456_to_remove",
  "subscription_id": "sub_123"
}

Get Seat Usage

Retrieves the current seat usage for a customer's active subscription, including details about each seat-based component.

GET https://api.getlumen.dev/v1/seats/usage/{customerId}

Parameters

Response

{
  "customerId": "cust_123",
  "subscriptionId": "sub_456",
  "seatUsages": [
    {
      "componentId": "comp_seat",
      "componentName": "per_unit_monthly",
      "unitLabel": "seat",
      "metricId": "metric_seat_count",
      "currentUsage": 5,
      "pendingRemovals": 1,
      "unitAmountCents": 1000
    }
  ]
}