Change an organization's plan (internal)

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL


        
          
            https://docs.usehearsay.com/mcp

Standard setup for AI tools providing an mcp.json file

{
  "integrations MCP server": {
    "url": "https://docs.usehearsay.com/mcp"
  }
}

POST /admin/orgs/{orgId}/plan

Access token

Sets the organization's self-serve tier and cadence (pay as you go), with the same proration as the customer flow, or assigns its first plan when it has none. Cadence defaults to monthly; an annual-only tier is always annual and returns 400 for any other cadence. Returns the plan, the proration in cents and whether the organization still has to add a card, which staff cannot do here. Super admin only.

Path parameters

orgId string Required

Id of the organization

application/json

Body Required

tier string Required

Values are public, solo, firm, or firm-plus.
cadence string

Values are monthly or annual.

Responses

200 application/json
Hide response attributes Show response attributes object
- data object Required
  
  Hide data attributes Show data attributes object
  
  plan object Required
  
  Hide plan attributes Show plan attributes object
  
  tier string Required
  
  Values are public, solo, firm, or firm-plus.
  
  cadence string Required
  
  Values are monthly or annual.
  
  billingMode string Required
  
  Values are payg, per-source, or flat-case.
  
  prorationCents number Required
  
  Net cents charged (positive) or credited (negative) now to reconcile the base fee on a plan change; 0 on a first-time plan assignment.
  
  paymentRequired boolean Required
  
  Informational only: true if the org's (new) tier is paid and it has no card on file yet. Staff cannot capture a card here — the org must add one via its own self-serve flow.
- statusCode number Required
- timestamp string(date-time) Required

POST /admin/orgs/{orgId}/plan

curl \
 --request POST 'http://api.example.com/admin/orgs/{orgId}/plan' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{
  "tier": "public",
  "cadence": "monthly"
}'

Request examples

{
  "tier": "public",
  "cadence": "monthly"
}

Response examples (200)

{
  "data": {
    "plan": {
      "tier": "firm",
      "cadence": "monthly",
      "billingMode": "payg"
    },
    "prorationCents": 0,
    "paymentRequired": false
  },
  "statusCode": 200,
  "timestamp": "2026-01-15T10:15:00.000Z"
}