Skip to content
API docs
Sign inOpen app

Billing

Change the plan

POST/v1/workspaces/{workspaceId}/billing/plan

Switch a paying workspace to another plan or billing interval. Most changes apply now, prorated (what's left of the current period is credited and the billing date restarts), including monthly to yearly; yearly to monthly waits for the paid year to end. The new plan applies when the provider confirms (GET /v1/workspaces/{workspaceId}/billing then shows it). The workspace must fit the new plan, as at checkout, or it gets 409 plan_does_not_fit with issues. So downgrading means cutting back first. A plan without phone and email verification or AI-assisted fields never blocks the move; it goes ahead and stops lists what stops. It fails with 409 no_subscription when nothing is being paid, so start a checkout instead. It also fails with 409 already_on_plan, 409 yearly_unavailable, and 409 free_workspace when staff made the workspace free. Only the workspace owner can do this, and only from the app. See Owner-only and app-only.

Path parameters

  • workspaceIdstringrequired

    The workspace's id. An API key can only use its own workspace.

Body

JSON, with Content-Type: application/json.

  • planenumrequired

    The plan: business, publishers or agencies.

    One of "business", "publishers", "agencies"

  • intervalenum

    month or year. Leave it out to keep the current interval. Yearly is sold only where yearlyAvailable is true.

    One of "month", "year"

Response

  • planenumrequired

    One of "business", "publishers", "agencies"

  • intervalenumrequired

    One of "month", "year"

  • startsAtnumber or nullrequired

    When a change that waits takes effect, in milliseconds since the epoch. Yearly to monthly waits for the end of the paid year. Null when the change applies now. Until it takes effect, GET /v1/workspaces/{workspaceId}/billing shows it as subscription.scheduledChange. Picking the current plan and interval again cancels a scheduled change.

  • stopsarray of objectrequired

    Each check that stops and the published forms it stops on, as in plans[].stops of the billing state. Their leads still come in unverified, and AI autocomplete questions become plain text boxes.

    Show 4 fields
    • checkenumrequired

      One of "phoneVerification", "emailValidation", "telegramCheck", "aiAutocomplete"

    • featurestringrequired

      The plan feature the check needs.

    • formsarray of objectrequired

      The published forms that run it.

      Show 2 fields
      • idstringrequired
      • namestringrequired
    • messagestringrequired

Errors answer with a status and the error shape.