Assign Seat

POST

customer-portal

seats

Python

from polar.v2027_01 import Polar

polar = Polar("polar_oat_xxx")

response = polar.customer_portal.seats.assign_seat(
    immediate_claim=False,
)
print(response)

import { createPolar } from "@polar-sh/sdk/2027-01";

const polar = createPolar({
  accessToken: "polar_oat_xxx",
});

const response = await polar.customerPortal.seats.assignSeat(
  {
    "immediate_claim": false
  },
);
console.log(response);

curl --request POST \
  --url https://api.polar.sh/v1/customer-portal/seats \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "subscription_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "email": "[email protected]",
  "external_customer_id": "<string>",
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "external_member_id": "<string>",
  "member_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "metadata": {},
  "immediate_claim": false,
  "checkout_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    subscription_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    order_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    email: '[email protected]',
    external_customer_id: '<string>',
    customer_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    external_member_id: '<string>',
    member_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    metadata: {},
    immediate_claim: false,
    checkout_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  })
};

fetch('https://api.polar.sh/v1/customer-portal/seats', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.polar.sh/v1/customer-portal/seats",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'subscription_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'order_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'email' => '[email protected]',
    'external_customer_id' => '<string>',
    'customer_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'external_member_id' => '<string>',
    'member_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'metadata' => [
        
    ],
    'immediate_claim' => false,
    'checkout_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.polar.sh/v1/customer-portal/seats"

	payload := strings.NewReader("{\n  \"subscription_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"order_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"email\": \"[email protected]\",\n  \"external_customer_id\": \"<string>\",\n  \"customer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"external_member_id\": \"<string>\",\n  \"member_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"metadata\": {},\n  \"immediate_claim\": false,\n  \"checkout_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.polar.sh/v1/customer-portal/seats")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"subscription_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"order_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"email\": \"[email protected]\",\n  \"external_customer_id\": \"<string>\",\n  \"customer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"external_member_id\": \"<string>\",\n  \"member_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"metadata\": {},\n  \"immediate_claim\": false,\n  \"checkout_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.polar.sh/v1/customer-portal/seats")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"subscription_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"order_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"email\": \"[email protected]\",\n  \"external_customer_id\": \"<string>\",\n  \"customer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"external_member_id\": \"<string>\",\n  \"member_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"metadata\": {},\n  \"immediate_claim\": false,\n  \"checkout_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"

response = http.request(request)
puts response.read_body

{
  "created_at": "2026-01-01T00:00:00.000000Z",
  "modified_at": "2026-01-01T00:00:00.000000Z",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "subscription_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "member_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "member": {
    "id": "<string>",
    "created_at": "2026-01-01T00:00:00.000000Z",
    "modified_at": "2026-01-01T00:00:00.000000Z",
    "customer_id": "<string>",
    "email": "[email protected]",
    "name": "Jane Doe",
    "external_id": "usr_1337",
    "role": "owner"
  },
  "email": "<string>",
  "customer_email": "<string>",
  "invitation_token_expires_at": "2026-01-01T00:00:00.000000Z",
  "claimed_at": "2026-01-01T00:00:00.000000Z",
  "revoked_at": "2026-01-01T00:00:00.000000Z",
  "seat_metadata": {}
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

Customer session tokens are specific tokens that are used to authenticate customers on your organization. You can create those sessions programmatically using the Create Customer Session endpoint.

Scopes

customer_portal:write

customer_session

customer_portal:write

member_session

Body

application/json

subscription_id

string<uuid> | null

Subscription ID. Required if neither order_id nor checkout_id is provided.

order_id

string<uuid> | null

Order ID for one-time purchases. Required if subscription_id is not provided.

string<email> | null

Email of the customer to assign the seat to

external_customer_id

string | null

External customer ID for the seat assignment

customer_id

string<uuid> | null

Customer ID for the seat assignment

external_member_id

string | null

External member ID for the seat assignment. Can be used alone (lookup existing member) or with email (create/validate member).

member_id

string<uuid> | null

Member ID for the seat assignment.

metadata

Metadata · object | null

Additional metadata for the seat (max 10 keys, 1KB total)

immediate_claim

boolean

default:false

If true, the seat will be immediately claimed without sending an invitation email. API-only feature.

checkout_id

string<uuid> | null

Checkout ID. Resolves to the subscription or order produced by the checkout.

Response

Successful Response

created_at

string<date-time>

required

Creation timestamp of the object.

Example:

"2026-01-01T00:00:00.000000Z"

modified_at

string<date-time> | null

required

Last modification timestamp of the object.

Example:

"2026-01-01T00:00:00.000000Z"

string<uuid>

required

The seat ID

subscription_id

string<uuid> | null

required

The subscription ID (for recurring seats)

order_id

string<uuid> | null

required

The order ID (for one-time purchase seats)

status

enum<string>

required

Status of the seat

Available options:

pending,

claimed,

revoked

customer_id

string<uuid> | null

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> | null

required

The member ID of the seat occupant

member

Member · object | null

required

The member associated with this seat

Show child attributes

string | null

required

Email of the seat member (set when member_model_enabled is true)

customer_email

string | null

required

The assigned customer email

invitation_token_expires_at

string<date-time> | null

required

When the invitation token expires

Example:

"2026-01-01T00:00:00.000000Z"

claimed_at

string<date-time> | null

required

When the seat was claimed

Example:

"2026-01-01T00:00:00.000000Z"

revoked_at

string<date-time> | null

required

When the seat was revoked

Example:

"2026-01-01T00:00:00.000000Z"

seat_metadata

Seat Metadata · object | null

required

Additional metadata for the seat

⌘I

Python

from polar.v2027_01 import Polar

polar = Polar("polar_oat_xxx")

response = polar.customer_portal.seats.assign_seat(
    immediate_claim=False,
)
print(response)

import { createPolar } from "@polar-sh/sdk/2027-01";

const polar = createPolar({
  accessToken: "polar_oat_xxx",
});

const response = await polar.customerPortal.seats.assignSeat(
  {
    "immediate_claim": false
  },
);
console.log(response);

curl --request POST \
  --url https://api.polar.sh/v1/customer-portal/seats \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "subscription_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "email": "[email protected]",
  "external_customer_id": "<string>",
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "external_member_id": "<string>",
  "member_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "metadata": {},
  "immediate_claim": false,
  "checkout_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    subscription_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    order_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    email: '[email protected]',
    external_customer_id: '<string>',
    customer_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    external_member_id: '<string>',
    member_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    metadata: {},
    immediate_claim: false,
    checkout_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  })
};

fetch('https://api.polar.sh/v1/customer-portal/seats', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.polar.sh/v1/customer-portal/seats",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'subscription_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'order_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'email' => '[email protected]',
    'external_customer_id' => '<string>',
    'customer_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'external_member_id' => '<string>',
    'member_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'metadata' => [
        
    ],
    'immediate_claim' => false,
    'checkout_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.polar.sh/v1/customer-portal/seats"

	payload := strings.NewReader("{\n  \"subscription_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"order_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"email\": \"[email protected]\",\n  \"external_customer_id\": \"<string>\",\n  \"customer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"external_member_id\": \"<string>\",\n  \"member_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"metadata\": {},\n  \"immediate_claim\": false,\n  \"checkout_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.polar.sh/v1/customer-portal/seats")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"subscription_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"order_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"email\": \"[email protected]\",\n  \"external_customer_id\": \"<string>\",\n  \"customer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"external_member_id\": \"<string>\",\n  \"member_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"metadata\": {},\n  \"immediate_claim\": false,\n  \"checkout_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.polar.sh/v1/customer-portal/seats")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"subscription_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"order_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"email\": \"[email protected]\",\n  \"external_customer_id\": \"<string>\",\n  \"customer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"external_member_id\": \"<string>\",\n  \"member_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"metadata\": {},\n  \"immediate_claim\": false,\n  \"checkout_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"

response = http.request(request)
puts response.read_body

{
  "created_at": "2026-01-01T00:00:00.000000Z",
  "modified_at": "2026-01-01T00:00:00.000000Z",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "subscription_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "member_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "member": {
    "id": "<string>",
    "created_at": "2026-01-01T00:00:00.000000Z",
    "modified_at": "2026-01-01T00:00:00.000000Z",
    "customer_id": "<string>",
    "email": "[email protected]",
    "name": "Jane Doe",
    "external_id": "usr_1337",
    "role": "owner"
  },
  "email": "<string>",
  "customer_email": "<string>",
  "invitation_token_expires_at": "2026-01-01T00:00:00.000000Z",
  "claimed_at": "2026-01-01T00:00:00.000000Z",
  "revoked_at": "2026-01-01T00:00:00.000000Z",
  "seat_metadata": {}
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

General

Core API

Customer Portal API

Webhook Events

Integrations

Authorizations

Scopes

Body

Response