Seats
Remove Seat
Remove a seat (user) from a subscription. Validates that the seat was previously added, revokes seat-level credits/entitlements, soft-deletes the seat customer, and emits a seat_removed event with idempotency.
Authorization
bearerAuth AuthorizationBearer <token>
Use your secret API key as the bearer token
In: header
Request Body
application/json
user_id?string
External user ID of the billing customer (fallback when organization_id is not provided)
organization_id*string
External organization identifier (preferred billing context)
removed_user_id?string
External user ID of the seat being removed
metadata?
Additional properties stored on the seat events
idempotency_key?string
Unique key to avoid duplicate seat removal
timestamp?string
UTC timestamp for the seat removal event (must end with Z)
Match
Z$Format
date-timeResponse Body
application/json
application/json
application/json
application/json
curl -X POST "https://api.getlumen.dev/v1/seats/remove" \ -H "Content-Type: application/json" \ -d '{ "organization_id": "acme-billing-org", "removed_user_id": "user-2313", "metadata": { "reason": "Offboarding" }, "idempotency_key": "seat_remove_user-2313_2025-02-22T10:00:00Z", "timestamp": "2025-02-22T10:00:00Z" }'{
"message": "Seat removed successfully",
"organization_id": "acme-billing-org",
"removed_user_id": "user-2313",
"subscription_id": "sub_int_Z2e7iq9Y3m1RpAJcGxK8bB",
"idempotency_key": "seat_remove_user-2313_2025-02-22T10:00:00Z"
}{
"error": "User not found in active seats or already removed"
}{
"error": "string",
"details": "string"
}{
"error": "Failed to remove seat"
}