Docs
Migrating from v1Health, limits & billing

Billing summary to Plan capabilities

Returns the organization's plan, subscription status, trial dates, and usage against plan limits. Use it to warn a customer before they hit a limit.

Billing summary

Returns the organization's plan, subscription status, trial dates, and usage against plan limits. Use it to warn a customer before they hit a limit.

Old APINew API
Method + routenone - newGET /v2/workspaces/{workspaceId}/billing/summary
Key permission (scope)none - newbilling:read (key role must be Admin or higher)
Rate bucketnone - newread
Plan needednone - new-

What changed

  • This endpoint is new.
  • Billing is for the whole organization. The workspaceId in the path is only used to check the key.
  • Admin role or higher is required. An Editor or Viewer key gets 403 insufficient_scope, even with billing:read.
  • A null limit means unlimited. Never treat it as 0.
  • usage is cached for about 45 seconds. Read today's warmup sends from the DAILY_EMAILS entry in usage; warmupDaily only tells you when the daily count resets.

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyesmust be a workspace your key can accessAny workspace of the organization the key can access.-

Request body

No body.

Example request (new)

curl -X GET "$TI_BASE_URL/v2/workspaces/42/billing/summary" \
  -H "Authorization: Bearer ti_ws_your_key"

Response (new)

200 OK

New field (inside data)TypeWhat it meansOld field
planobject or nullCurrent plan: id, name. null if the organization has no plan.-
statusstringTRIALING, ACTIVE, PAUSED, CANCELED, or PAST_DUE.-
trialobject or nullstartedAt, endsAt, and daysLeft (whole days, never below 0). null when not in a trial.-
emailAccounts.usednumberConnected mailboxes in the organization.-
warmupDaily.resetsAtstringNext reset: midnight in the organization's timezone.-
scheduledChangeobject or nullA cancel or pause booked for the end of the billing period: action (cancel, pause, resume) and effectiveAt.-
scheduledResumeAtstring or nullWhen a fixed-length pause ends by itself. null for an open-ended pause or no pause.-
usagearrayOne entry per limit: code (EMAIL_ACCOUNTS or DAILY_EMAILS), used, limit, pct.-
{
  "data": {
    "plan": { "id": 2, "name": "growth" },
    "status": "ACTIVE",
    "trial": null,
    "emailAccounts": { "used": 17 },
    "warmupDaily": {
      "resetsAt": "2026-09-30T00:00:00.000Z"
    },
    "scheduledChange": null,
    "scheduledResumeAt": null,
    "usage": [
      { "code": "EMAIL_ACCOUNTS", "used": 17, "limit": 20, "pct": 85 },
      { "code": "DAILY_EMAILS", "used": 137, "limit": 500, "pct": 27 }
    ]
  },
  "meta": {
    "request_id": "req_9a7b3c21-4d5e-4f60-8b19-0c2d3e4f5a6b",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
401unauthorized / invalid_api_keyHeader missing, or key wrong or revoked.Send a valid key.
403insufficient_scopeThe key lacks billing:read, or its role is below Admin.Use an Admin-level key with billing:read.
403forbiddenThe person behind a personal key is no longer an Admin in this workspace.Use a key from a current Admin or Owner.
403workspace_forbiddenThe key cannot access this workspaceId.Use the workspace the key belongs to.
429rate_limit_exceededRead bucket or IP limit used up.Wait Retry-After seconds.

Plan capabilities

Returns the list of features the organization's plan allows, as resource/action names. Use it to hide actions the customer cannot use.

Old APINew API
Method + routenone - newGET /v2/workspaces/{workspaceId}/billing/capabilities
Key permission (scope)none - newbilling:read (key role must be Admin or higher)
Rate bucketnone - newread
Plan needednone - new-

What changed

  • This endpoint is new.
  • It returns a flat list of strings such as email-account/list. If a name is in the list, the plan allows that action.
  • The list comes from an account-level override when one exists, otherwise from the base plan.
  • Admin role or higher is required, the same as the billing summary.

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyesmust be a workspace your key can accessAny workspace of the organization the key can access.-

Request body

No body.

Example request (new)

curl -X GET "$TI_BASE_URL/v2/workspaces/42/billing/capabilities" \
  -H "Authorization: Bearer ti_ws_your_key"

Response (new)

200 OK

New field (inside data)TypeWhat it meansOld field
identifiersarray of stringsEvery resource/action the plan allows.-
{
  "data": {
    "identifiers": [
      "email-account/list",
      "reports/overview"
    ]
  },
  "meta": {
    "request_id": "req_1e2f3a4b-5c6d-4e7f-8091-a2b3c4d5e6f7",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
401unauthorized / invalid_api_keyHeader missing, or key wrong or revoked.Send a valid key.
403insufficient_scopeThe key lacks billing:read, or its role is below Admin.Use an Admin-level key with billing:read.
403forbiddenThe person behind a personal key is no longer an Admin in this workspace.Use a key from a current Admin or Owner.
403workspace_forbiddenThe key cannot access this workspaceId.Use the workspace the key belongs to.
429rate_limit_exceededRead bucket or IP limit used up.Wait Retry-After seconds.