Billing

Move a running subscription to another self-serve plan

Swaps the price of the workspace's running Stripe subscription (Stripe prorates the difference). Self-serve plans only; a workspace without a running subscription gets 409 and subscribes through /billing/checkout. Requires billing:manage.

post/billing/change-plan

Request

  • Base URL: https://api.customdomain.ai/v1
  • URL: https://api.customdomain.ai/v1/billing/change-plan
  • Auth: HTTP bearer

Request body

plan'starter' | 'startup' | 'growth' | 'premium' | 'enterprise' | 'free' required

free is retired: legacy workspaces still carry it until they subscribe, and it cannot be bought or assigned.

Response

The new billing status

tenant_idstring
state'trialing' | 'active' | 'past_due' | 'grace' | 'blocked' | 'comped' | 'canceled' | 'legacy_free'

A workspace's billing state, evaluated from its record and the clock. trialing and active are a running Stripe subscription; past_due is a failed payment Stripe is still retrying (nothing is refused); grace is a legacy Free workspace (or an operator extension) inside its grace period; legacy_free is a Free workspace whose grace has not started; comped is an operator comp; blocked and canceled refuse new connections (402 billing_required) while live domains keep working. A new workspace (blocked, reason setup_required) is refused only once its first domain is connected: see first_domain_free.

reasonstring
restrictedboolean
first_domain_freeboolean

Present only when true: a new workspace on the first domain free rule (see GET /billing/notice).

free_domainsinteger

Present with first_domain_free: how many domains the workspace may connect before it has a subscription.

attentionboolean
setup_requiredboolean
days_leftinteger
price_centsinteger

What the workspace pays per month (the Stripe amount, else the catalog price).

currencystring
trial_ends_atstring date-time nullable
grace_started_atstring date-time nullable
grace_ends_atstring date-time nullable
current_period_endstring date-time nullable
cancel_at_period_endboolean
ended_atstring date-time nullable
compedboolean
comped_untilstring date-time nullable
payment_failedboolean
payment_failed_atstring date-time nullable
has_billing_accountboolean
portal_availableboolean
can_change_planboolean
mode'test' | 'live' | ''

Changes

No recorded changes to this operation across all 1 revision of this API.