Skip to main content
PATCH
/
v2
/
billing
/
notifications
/
config
Upsert billing notification config
curl --request PATCH \
  --url https://api.topograph.co/v2/billing/notifications/config \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "lowBalanceEnabled": true,
  "lowBalanceEmailEnabled": true,
  "lowBalanceWebhookEnabled": true,
  "lowBalanceTiers": [
    {
      "tier": "warning",
      "cents": 100000
    }
  ],
  "globalHighUsageEnabled": false,
  "globalHighUsageEmailEnabled": true,
  "globalHighUsageWebhookEnabled": true,
  "globalHighUsagePeriodMinutes": 1440,
  "globalHighUsageTiers": [
    {
      "tier": "warning",
      "cents": 100000
    }
  ],
  "highUsageEnabled": false,
  "highUsageEmailEnabled": true,
  "highUsageWebhookEnabled": true,
  "highUsagePeriodMinutes": 1440,
  "highUsageTiers": [
    {
      "tier": "warning",
      "cents": 100000
    }
  ],
  "autoTopupNotificationsEnabled": false,
  "autoTopupEmailEnabled": true,
  "autoTopupWebhookEnabled": true
}
'
{
  "lowBalanceEnabled": false,
  "lowBalanceEmailEnabled": true,
  "lowBalanceWebhookEnabled": true,
  "lowBalanceTiers": [
    {
      "tier": "warning",
      "cents": 100000
    }
  ],
  "globalHighUsageEnabled": false,
  "globalHighUsageEmailEnabled": true,
  "globalHighUsageWebhookEnabled": true,
  "globalHighUsagePeriodMinutes": 1440,
  "globalHighUsageTiers": [
    {
      "tier": "warning",
      "cents": 100000
    }
  ],
  "highUsageEnabled": false,
  "highUsageEmailEnabled": true,
  "highUsageWebhookEnabled": true,
  "highUsagePeriodMinutes": 1440,
  "highUsageTiers": [
    {
      "tier": "warning",
      "cents": 100000
    }
  ],
  "autoTopupNotificationsEnabled": false,
  "autoTopupEmailEnabled": true,
  "autoTopupWebhookEnabled": true
}

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
lowBalanceEnabled
boolean

Master toggle for low-balance notifications. Defaults to false on new accounts (strictly opt-in).

Example:

true

​
lowBalanceEmailEnabled
boolean

Route low-balance notifications via email. Applied when lowBalanceEnabled is true.

Example:

true

​
lowBalanceWebhookEnabled
boolean

Route low-balance notifications via webhook. Applied when lowBalanceEnabled is true.

Example:

true

​
lowBalanceTiers
object[]

Ordered list of low-balance tiers. Each tier fires once when the account balance drops at or below its cents threshold. Tier names must be unique.

Required array length: 1 - 10 elements
​
globalHighUsageEnabled
boolean

Master toggle for global (account-aggregate) high-usage notifications. Defaults to false on new accounts.

Example:

false

​
globalHighUsageEmailEnabled
boolean

Route global high-usage notifications via email.

Example:

true

​
globalHighUsageWebhookEnabled
boolean

Route global high-usage notifications via webhook.

Example:

true

​
globalHighUsagePeriodMinutes
number

Rolling window, in minutes, used to sum account-aggregate spend when evaluating global high-usage tiers. Min 5 (5 minutes), max 43200 (30 days).

Required range: 5 <= x <= 43200
Example:

1440

​
globalHighUsageTiers
object[]

Global high-usage tiers. Fires when the sum of spend across ALL workspaces (plus the account-wide bucket) over the rolling window meets-or-exceeds cents.

Required array length: 1 - 5 elements
​
highUsageEnabled
boolean

Master toggle for per-workspace high-usage notifications. These thresholds are applied individually to each workspace; a workspace can override them via the workspace-override endpoint.

Example:

false

​
highUsageEmailEnabled
boolean

Route per-workspace high-usage notifications via email.

Example:

true

​
highUsageWebhookEnabled
boolean

Route per-workspace high-usage notifications via webhook.

Example:

true

​
highUsagePeriodMinutes
number

Rolling window, in minutes, used to sum per-workspace spend when evaluating high-usage tiers. Min 5, max 43200.

Required range: 5 <= x <= 43200
Example:

1440

​
highUsageTiers
object[]

Per-workspace high-usage tiers. Fires when a single workspace's spend over the rolling window meets-or-exceeds cents.

Required array length: 1 - 5 elements
​
autoTopupNotificationsEnabled
boolean

Master toggle for auto-topup outcome notifications (succeeded / failed). Distinct from Account.autoTopupEnabled, which controls the charge itself. Defaults to false on new accounts.

Example:

false

​
autoTopupEmailEnabled
boolean

Route auto-topup outcome notifications via email.

Example:

true

​
autoTopupWebhookEnabled
boolean

Route auto-topup outcome notifications via webhook.

Example:

true

Response

200 - application/json
​
lowBalanceEnabled
boolean
required

Master toggle for low-balance notifications.

Example:

false

​
lowBalanceEmailEnabled
boolean
required

Route low-balance notifications via email.

Example:

true

​
lowBalanceWebhookEnabled
boolean
required

Route low-balance notifications via webhook.

Example:

true

​
lowBalanceTiers
object[]
required

Resolved low-balance tiers.

​
globalHighUsageEnabled
boolean
required

Master toggle for global (account-aggregate) high-usage notifications.

Example:

false

​
globalHighUsageEmailEnabled
boolean
required

Route global high-usage notifications via email.

Example:

true

​
globalHighUsageWebhookEnabled
boolean
required

Route global high-usage notifications via webhook.

Example:

true

​
globalHighUsagePeriodMinutes
number
required

Rolling window, in minutes, for global high-usage evaluation.

Example:

1440

​
globalHighUsageTiers
object[]
required

Resolved global high-usage tiers.

​
highUsageEnabled
boolean
required

Master toggle for per-workspace high-usage notifications.

Example:

false

​
highUsageEmailEnabled
boolean
required

Route per-workspace high-usage notifications via email.

Example:

true

​
highUsageWebhookEnabled
boolean
required

Route per-workspace high-usage notifications via webhook.

Example:

true

​
highUsagePeriodMinutes
number
required

Rolling window, in minutes, for per-workspace high-usage evaluation.

Example:

1440

​
highUsageTiers
object[]
required

Resolved per-workspace high-usage tiers (applied as defaults to every workspace).

​
autoTopupNotificationsEnabled
boolean
required

Master toggle for auto-topup outcome notifications.

Example:

false

​
autoTopupEmailEnabled
boolean
required

Route auto-topup notifications via email.

Example:

true

​
autoTopupWebhookEnabled
boolean
required

Route auto-topup notifications via webhook.

Example:

true