Add Seat
Add a seat (user) to a subscription. Accepts either organization_id (preferred) or user_id as the billing owner and adds a new seat user. Emits a seat_added event, applies idempotency, copies entitlements/credits, and can bill immediate seat overages based on the plan's per-unit components.
Authorization
bearerAuth Use your secret API key as the bearer token
In: header
Request Body
application/json
External user ID of the billing customer (fallback when organization_id is not provided)
External organization identifier (preferred billing context)
External user ID of the seat being added
Optional metadata about the seat user
Additional properties stored on the seat events
Unique key to avoid duplicate seat creation
UTC timestamp for the seat event (must end with Z)
Z$date-timeResponse Body
application/json
application/json
application/json
curl -X POST "https://api.getlumen.dev/v1/seats/add" \ -H "Content-Type: application/json" \ -d '{ "organization_id": "acme-billing-org", "created_user_id": "user-2313", "created_user_info": { "name": "New hire", "email": "newhire@example.com" }, "metadata": { "role": "analyst" }, "idempotency_key": "seat_add_user-2313_2025-02-21T18:00:00Z", "timestamp": "2025-02-21T18:00:00Z" }'{
"message": "Seat added successfully",
"user_id": "user-4811",
"organization_id": "acme-billing-org",
"created_user_id": "user-2313",
"subscription_id": "sub_int_Z2e7iq9Y3m1RpAJcGxK8bB",
"idempotency_key": "seat_add_user-2313_2025-02-21T18:00:00Z"
}{
"error": "Organization not found: acme-billing-org"
}{
"error": "Failed to add seat"
}