Sign in
admin

Update Org

Edit an enterprise organization's billing profile (admin only).

Covers seat price, per-user usage cap, overage toggle/ceiling, API markup, org name, and billing email. Seat-price changes create a new per-org Stripe Price and swap the subscription item with proration. Name/email changes are mirrored to the Stripe Customer so invoices stay aligned. An append-only billing_events row captures {before, after, reason}.

patch/api/admin/organizations/{org_id}

Path parameters

org_idinteger required

Request body

namestring nullable
billing_emailstring nullable
seat_price_centsinteger nullable
usage_limit_per_user_usdnumber nullable
overage_enabledboolean nullable
overage_limit_per_user_usdinteger nullable
api_markup_ratenumber nullable
billing_mode'free_pilot'

Why an organization is in the billing state it is in.

Recorded on organizations.settings["billing_mode"]. Absence means "ordinary paid org" — the overwhelming majority — so only deliberate exceptions carry a value.

FREE_PILOT records intent. The gating itself comes from the absence of payment_method_status: every reader compares it to "pending" exactly, so an absent key passes both usage gates while leaving the setup-link path open (regenerate_enterprise_setup_session refuses only on "active"). Absence alone cannot distinguish a deliberate free pilot from an org whose payment state was never stamped, which is what this key is for.

reasonstring nullable

Response

Successful Response

idinteger required
namestring required
slugstring required
stripe_customer_idstring nullable required
billing_emailstring nullable required
api_markup_ratenumber nullable required
archived_atstring nullable required
created_atstring required
updated_atstring required
member_countinteger nullable
payment_method_statusstring nullable
billing_modestring nullable
next_stepsstring nullable
stripe_customer_urlstring nullable
stripe_subscription_urlstring nullable
workos_organization_idstring nullable

Changes

Changed in 1 of the 16 revisions of this API.2

  • f2518d4943262See the full diff
    • ○

      added the new optional request property billing_mode

      new-optional-request-property

    • ○

      added the optional property billing_mode to the response with the 200 status

      response-optional-property-added