---
title: "Assign Seat"
method: POST
path: "/v1/customer-seats"
tags: ["customer-seats", "public"]
---

# Assign Seat

`POST /v1/customer-seats`

**Scopes**: `customer_seats:write`

## Request body

- SeatAssign
  - `subscription_id` string, uuid, nullable — Subscription ID. Required if neither order_id nor checkout_id is provided.
  - `order_id` string, uuid, nullable — Order ID for one-time purchases. Required if subscription_id is not provided.
  - `email` string, email, nullable — Email of the customer to assign the seat to
  - `external_customer_id` string, nullable — External customer ID for the seat assignment
  - `customer_id` string, uuid, nullable — Customer ID for the seat assignment
  - `external_member_id` string, nullable — External member ID for the seat assignment. Can be used alone (lookup existing member) or with email (create/validate member).
  - `member_id` string, uuid, nullable — Member ID for the seat assignment.
  - `metadata` object, nullable — Additional metadata for the seat (max 10 keys, 1KB total)
  - `immediate_claim` boolean — If true, the seat will be immediately claimed without sending an invitation email. API-only feature.

## Response `200`

Successful Response

- CustomerSeat
  - `created_at` string, date-time, required — Creation timestamp of the object.
  - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object.
  - `id` string, uuid, required — The seat ID
  - `subscription_id` string, uuid, nullable, required — The subscription ID (for recurring seats)
  - `order_id` string, uuid, nullable, required — The order ID (for one-time purchase seats)
  - `status` 'pending' | 'claimed' | 'revoked', required
  - `customer_id` string, uuid, nullable, required — The customer ID. When member_model_enabled is true, this is the billing customer (purchaser). When false, this is the seat member customer.
  - `member_id` string, uuid, nullable, required — The member ID of the seat occupant
  - `member` Member, required — A member of a customer.
    - `id` string, uuid4, required — The ID of the member.
    - `created_at` string, date-time, required — Creation timestamp of the object.
    - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object.
    - `customer_id` string, uuid4, required — The ID of the customer this member belongs to.
    - `email` string, required — The email address of the member.
    - `name` string, nullable, required — The name of the member.
    - `external_id` string, nullable, required — The ID of the member in your system. This must be unique within the customer.
    - `role` 'owner' | 'billing_manager' | 'member', required
  - `email` string, nullable, required — Email of the seat member (set when member_model_enabled is true)
  - `customer_email` string, nullable, required — The assigned customer email
  - `invitation_token_expires_at` string, date-time, nullable, required — When the invitation token expires
  - `claimed_at` string, date-time, nullable, required — When the seat was claimed
  - `revoked_at` string, date-time, nullable, required — When the seat was revoked
  - `seat_metadata` object, nullable, required — Additional metadata for the seat

## Other responses

- `400` — No available seats or customer already has a seat
- `401` — Authentication required
- `403` — Not permitted or seat-based pricing not enabled
- `404` — Subscription, order, or customer not found
- `422` — Validation Error

---

[API](https://skmtc.net/polar/apis/polar-api.md) · [All operations](https://skmtc.net/polar/apis/polar-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/polar/polar-api/revisions/1ee4b8be5abd/schema)