Replace seats

Assigns a team's seats: which member holds a standard seat and which a premium one, replacing what was assigned.

PUT /v1/billing/subscriptions/{id}/seats

Billing → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/billing/subscriptions/{id}/seats`
Method	`PUT`
Operation	`assignSeats`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Assigns a team's seats: which member holds a standard seat and which a premium one, replacing what was assigned.

A seat type is given no more members than the seats of it paid for — the fewer of the period in hand's and the next one's — and a member holds one seat; past either the request is 400 and nothing changes. Which member holds a seat moves no money and bounds no usage: a team's usage is all of its seats' together.

The team's seats are its admins' to assign, and the platform's. A member is refused with 403 and told to ask an admin. A subscription from another org, or held by a wallet the caller may not change, is not found.

A named handler, not a closure, so zipdoc can lift this prose into the registry.

Request

4 fields, body application/json (required).

Field	In	Type	Required	Description
`id`	path	string	yes
`assigned`	body	billing.SubscriptionSeat[]	—	Assigned is every seat assigned: the member, and the seat type (a plan the subscription holds seats of, "team" or "team-premium") they hold.
`assigned[].member`	body	string	—	Member is the IAM user who holds the seat, as the org's members list names them.
`assigned[].plan`	body	string	—	Plan is the seat type held: "team" (standard) or "team-premium".

Response

Status	Body	Meaning
`200`	billing.Subscription	ok
`default`	problem-details	refused

200 body — 42 fields.

Field	In	Type	Always	Description
`assigned`	body	billing.SubscriptionSeat[]	—	Assigned is which member holds which seat type, as the org's admin set it.
`assigned[].member`	body	string	—	Member is the IAM user who holds the seat, as the org's members list names them.
`assigned[].plan`	body	string	—	Plan is the seat type held: "team" (standard) or "team-premium".
`cancelAtPeriodEnd`	body	boolean	—	CancelAtPeriodEnd reports that the plan ends at CurrentPeriodEnd.
`canceledAt`	body	string	—	CanceledAt is when it was canceled; absent when it was not.
`chargedCents`	body	integer (int64)	—	ChargedCents is what the period in hand was actually paid, after any discount and net of refunds.
`coupon`	body	string	—	Coupon is the plan coupon code the first period was bought with, as commerce stores it (upper case); absent when none was.
`createdAt`	body	string	—	CreatedAt is when the row was written, RFC 3339.
`currentPeriodEnd`	body	string	—	CurrentPeriodEnd is when it ends, RFC 3339.
`currentPeriodStart`	body	string	—	CurrentPeriodStart is when the period in hand began, RFC 3339.
`customerCents`	body	integer (int64)	—	CustomerCents is the price staff agreed this subscriber pays for one seat each period, below the plan's list price; absent when none was.
`defaultPaymentMethod`	body	string	—	DefaultPaymentMethod is the saved method a renewal would use.
`endedAt`	body	string	—	EndedAt is when it ended; absent while it runs.
`held`	body	boolean	—	Held reports that this row is the subject's one paid plan: while it stands, commerce refuses a second paid sale (409).
`id`	body	string	—	ID is the subscription's own id, the one cancel and reactivate take.
`lastPaid`	body	string	—	LastPaid is when the latest payment for this subscription arrived, RFC 3339: its latest paid invoice's paid time, or, for a period recorded as collected outside commerce, which keeps no time of its own record, the start of the latest period recorded — whichever is later.
`lines`	body	billing.SubscriptionLine[]	—	Lines are a team's other seat types beside Plan (a team of standard and premium seats is Plan "team" and one line of "team-premium"), each with the seats of it the period in hand was paid for.
`lines[].name`	body	string	—	Name is the seat type's display name, e.g. "Team Premium".
`lines[].pendingQuantity`	body	integer (int64)	—	PendingQuantity is the seats of it the next period opens at, when a change waits for the renewal that charges it; absent when none does.
`lines[].plan`	body	string	—	Plan is the seat type's catalog plan, e.g. "team-premium".
`lines[].price`	body	integer (int64)	—	Price is one seat of it for the row's period, in cents.
`lines[].quantity`	body	integer (int64)	—	Quantity is the seats of it the row holds.
`lines[].seats`	body	integer (int64)	—	Seats is the seats of it the period in hand was paid for; 0 when unpaid.
`mrrCents`	body	integer (int64)	—	MRRCents is what this subscription contributes per month — commerce's own figure, interval-normalized and multiplied by its seats, so no reader re-derives it from price and interval.
`plan`	body	billing.SubscriptionPlan	—
`plan.currency`	body	string	—	Currency is the ISO code the price is in, lower-cased.
`plan.id`	body	string	—	ID is the plan row the subscription was opened on.
`plan.interval`	body	string	—	Interval is the billing period: "month" or "year".
`plan.name`	body	string	—	Name is the plan's display name, e.g. "Max 20x".
`plan.price`	body	integer (int64)	—	Price is what one period costs per seat, in cents, as the subscription snapshotted it: a later catalog price change does not move it.
`plan.slug`	body	string	—	Slug is the catalog plan it was opened on, e.g. "max-20x": what a reader matches against GET /v1/billing/plans.
`planId`	body	string	—	PlanID is the plan slug, e.g. "max-20x".
`providerType`	body	string	—	ProviderType is who collects it: a processor ("square"), "credit" for a plan bought with credits, "internal" or "bundle" for a row nobody paid for.
`quantity`	body	integer (int64)	—	Quantity is the seat count; a flat plan holds 1.
`seats`	body	integer (int64)	—	Seats is the seat count the period in hand was paid for — its paid invoice's quantity, or the quantity recorded with an external period — never the row's live Quantity, which the holder may change.
`settled`	body	string	—	Settled is how the period in hand was paid: "card" (a card paid all of it), "external:<processor>" (a payment recorded as collected outside commerce), "balance", "credit" or "mixed" (prepaid money).
`status`	body	string	—	Status is trialing, active, past_due, canceled or unpaid.
`test`	body	boolean	—	Test marks a sandbox subscription: sold while its org was in test mode, paid with sandbox money.
`trialEnd`	body	string	—	TrialEnd is when that trial ends; absent when there was none.
`trialStart`	body	string	—	TrialStart is when a trial began; absent when there was none.
`updatedAt`	body	string	—	UpdatedAt is when the row last changed, RFC 3339.
`userId`	body	string	—	UserID is the billing account that holds it: the org slug for an org's own plan, "<org>/<name>" for a member's.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo billing subscriptions seats <id>

.ts

.py

.go

.rs

.java

import { Configuration, BillingApi } from 'hanzoai';

const api = new BillingApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.assignSeats({ id: 'id', assigned: [{"member":"<member>","plan":"<plan>"}] });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import BillingApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = BillingApi(client).assign_seats(id='id', assigned=[{"member":"<member>","plan":"<plan>"}])

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.BillingAPI.AssignSeats(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, billing_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = billing_api::assign_seats(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.BillingApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new BillingApi(client).assignSeats();

curl -X PUT https://api.hanzo.ai/v1/billing/subscriptions/<id>/seats \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "assigned": [
         {
           "member": "<member>",
           "plan": "<plan>"
         }
       ]
     }'

Tool billing, op assignSeats — POST the JSON-RPC envelope to https://api.hanzo.ai/v1/mcp.

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "billing",
         "arguments": {
           "op": "assignSeats",
           "input": {
             "id": "<id>",
             "assigned": [
               {
                 "member": "<member>",
                 "plan": "<plan>"
               }
             ]
           }
         }
       }
     }'

Billing API · All Hanzo APIs · Interactive reference

Was this page useful?

Broken link or missing step? Drop it in #docs on Discord or open a PR.

PreviousCreate runs NextCancel subscriptions