Allocate Seat

POST

api

public

capacity

allocate

curl -X POST "https://app.crovver.com/api/public/capacity/allocate" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "requestingEntityId": "workspace_123",
    "externalUserId": "user_456",
    "email": "user@acme.com",
    "name": "Jane Smith"
  }'

{
  "success": true,
  "data": {
    "success": true,
    "message": "Seat allocation recorded successfully",
    "capacity": {
      "activeCount": 6,
      "capacityUnits": 10,
      "exceeded": false
    }
  }
}

{
  "success": true,
  "data": {
    "requiresProration": true,
    "proration": {
      "amount": 1.75,
      "currency": "USD",
      "description": "Prorated charge for 1 additional seat",
      "daysRemaining": 17,
      "totalDaysInPeriod": 30,
      "currentSeats": 10,
      "newSeats": 11
    },
    "message": "Adding this user will exceed your current capacity. Confirm to upgrade and charge the prorated amount."
  }
}

{
  "success": true,
  "data": {
    "requiresCheckout": true,
    "message": "Capacity upgrade requires payment. Use the proration-checkout endpoint to create checkout session.",
    "newCapacity": 11
  }
}

Records a seat allocation in Crovver when a user is added to a workspace. This is a lightweight audit operation — it does not trigger billing automatically. If the tenant is already at capacity, returns proration info for confirmation. If confirmProration: true is passed and capacity would be exceeded on a seat-based plan, returns a checkout URL to pay for the additional seat. The call is idempotent per externalUserId — re-allocating the same user updates their record rather than creating a duplicate.

Request Body

string

required

The external tenant ID from your application

string

required

Your application’s user ID for the seat being allocated. Must be unique within the tenant’s subscription. The call is idempotent — reallocating the same ID updates the record rather than creating a duplicate.

string

The user’s email address (stored for audit purposes)

string

The user’s display name

boolean

Pass true to confirm an over-capacity allocation and proceed to checkout.

object

Optional context stored on the allocation record.

Authentication

Requires a secret key (Authorization: Bearer sk_live_...) or service key (x-service-key).

curl -X POST "https://app.crovver.com/api/public/capacity/allocate" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "requestingEntityId": "workspace_123",
    "externalUserId": "user_456",
    "email": "user@acme.com",
    "name": "Jane Smith"
  }'

{
  "success": true,
  "data": {
    "success": true,
    "message": "Seat allocation recorded successfully",
    "capacity": {
      "activeCount": 6,
      "capacityUnits": 10,
      "exceeded": false
    }
  }
}

{
  "success": true,
  "data": {
    "requiresProration": true,
    "proration": {
      "amount": 1.75,
      "currency": "USD",
      "description": "Prorated charge for 1 additional seat",
      "daysRemaining": 17,
      "totalDaysInPeriod": 30,
      "currentSeats": 10,
      "newSeats": 11
    },
    "message": "Adding this user will exceed your current capacity. Confirm to upgrade and charge the prorated amount."
  }
}

{
  "success": true,
  "data": {
    "requiresCheckout": true,
    "message": "Capacity upgrade requires payment. Use the proration-checkout endpoint to create checkout session.",
    "newCapacity": 11
  }
}

Bulk Allocate SeatsAllocate up to 100 users to a tenant's subscription in one atomic operation.

curl -X POST "https://app.crovver.com/api/public/capacity/allocate" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "requestingEntityId": "workspace_123",
    "externalUserId": "user_456",
    "email": "user@acme.com",
    "name": "Jane Smith"
  }'

{
  "success": true,
  "data": {
    "success": true,
    "message": "Seat allocation recorded successfully",
    "capacity": {
      "activeCount": 6,
      "capacityUnits": 10,
      "exceeded": false
    }
  }
}

{
  "success": true,
  "data": {
    "requiresProration": true,
    "proration": {
      "amount": 1.75,
      "currency": "USD",
      "description": "Prorated charge for 1 additional seat",
      "daysRemaining": 17,
      "totalDaysInPeriod": 30,
      "currentSeats": 10,
      "newSeats": 11
    },
    "message": "Adding this user will exceed your current capacity. Confirm to upgrade and charge the prorated amount."
  }
}

{
  "success": true,
  "data": {
    "requiresCheckout": true,
    "message": "Capacity upgrade requires payment. Use the proration-checkout endpoint to create checkout session.",
    "newCapacity": 11
  }
}

Overview

Subscriptions

Checkout

Credits

Add-ons

Capacity (Seats)

Features & Usage

Plans

Tenants

Deprecated

Request Body

Authentication

​Request Body

​Authentication

Request Body

Authentication