integrations

Update an organization's billing profile (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

mcp.json 
{
  "integrations MCP server": {
    "url": "https://docs.usehearsay.com/mcp"
  }
}
Close
PATCH /admin/orgs/{orgId}/billing-profile
Access token

Changes the tier, billing mode, billing email, card-on-file flag, charge trigger or price overrides of an organization already on case billing. Only the fields sent change; overrides merge into the existing ones, and a null SKU price removes that override. Returns the saved profile with warnings, for example when an override will bill a SKU the tier normally includes. Returns 404 when the organization has no billing profile and 400 for an invalid tier, mode and cadence combination or any change of cadence. Super admin only.

Path parameters

  • orgId string Required

    Id of the organization

application/json

Body Required

  • tier string

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

  • billingMode string

    Values are payg, per-source, or flat-case.

  • cadence string

    Values are monthly or annual.

  • billingEmail string
  • paymentMethodOnFile boolean
  • chargeTrigger string | null

    When this org's phone collections are charged. null clears the override and returns the org to the platform-wide flag; import PINS it to import-time charging even after that flag flips.

    Values are backup or import.

  • overrides object
    Hide overrides attributes Show overrides attributes object
    • storageIncludedGB number
    • skuUnitAmountCents object

      SKU key -> cents. 0 = free for this org; null = remove the override and fall back to the catalog/tier price.

    • perCaseSourceCap number

      Provisioned only — NOT enforced in v1 (spec locked decision); enforcement is a later phase

  • reason string Required

    Required audit reason — persisted on the BillingEvent

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • data object Required
      Hide data attributes Show data attributes object
      • organization string Required
      • tier string Required

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

      • billingMode string Required

        Values are payg, per-source, or flat-case.

      • cadence string Required

        Values are monthly or annual.

      • billingEmail string | null Required
      • paymentMethodOnFile boolean Required
      • chargeTrigger string | null Required

        When this org's phone collections are charged. null means it follows the platform-wide flag rather than pinning a value.

        Values are backup or import.

      • overrides object | null Required
      • warnings array[string] Required

        Non-blocking notices, e.g. a per-SKU override the tier/mode already includes

    • statusCode number Required
    • timestamp string(date-time) Required
PATCH /admin/orgs/{orgId}/billing-profile 
curl \
 --request PATCH 'http://api.example.com/admin/orgs/{orgId}/billing-profile' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{
  "tier": "public",
  "billingMode": "payg",
  "cadence": "monthly",
  "billingEmail": "string",
  "paymentMethodOnFile": true,
  "chargeTrigger": "backup",
  "overrides": {
    "storageIncludedGB": 42.0,
    "skuUnitAmountCents": {},
    "perCaseSourceCap": 42.0
  },
  "reason": "string"
}'
Request examples 
{
  "tier": "public",
  "billingMode": "payg",
  "cadence": "monthly",
  "billingEmail": "string",
  "paymentMethodOnFile": true,
  "chargeTrigger": "backup",
  "overrides": {
    "storageIncludedGB": 42.0,
    "skuUnitAmountCents": {},
    "perCaseSourceCap": 42.0
  },
  "reason": "string"
}
Response examples (200) 
{
  "data": {
    "organization": "65a1b2c3d4e5f6a7b8c9d0e3",
    "tier": "firm",
    "billingMode": "payg",
    "cadence": "monthly",
    "billingEmail": "billing@example.com",
    "paymentMethodOnFile": true,
    "chargeTrigger": "backup",
    "overrides": {
      "storageIncludedGB": 100,
      "skuUnitAmountCents": {
        "collection.phone": 10000
      }
    },
    "warnings": [
      "string"
    ]
  },
  "statusCode": 200,
  "timestamp": "2026-01-15T10:15:00.000Z"
}