Billing

Apply a promotion code to the running subscription

Applies a promotion code, as a customer types it, to the workspace's running subscription (a new subscription takes a code as promotion_code on POST /billing/checkout). A code is accepted only when it belongs to this deployment, because a Stripe account can be shared with other products: it was created through the operator console, or its coupon is limited to this deployment's Stripe products. An unknown, inactive or foreign code is a 404. Requires billing:manage.

post/billing/promotion-code

Request

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

Request body

codestring required

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.