Per-subaccount AI configuration

Every subaccount under your parent organization resolves its own AI configuration: whether AI features (agents, insights, AI-assisted messaging) are enabled, which curated model provider they run on, and whether the usage is comped. You set all three boundaries separately per child, so one subaccount’s defaults never leak into the next. This is the narrative guide for GET /api/v1/subaccounts/{id}/ai-config and PUT /api/v1/subaccounts/{id}/ai-config. Field-level reference: Subaccounts API. For the full reseller flow this plugs into, see White-label subaccounts.

What the config governs

Three controls per subaccount, stored as one settings object and resolved together:

Control	Values	Resolution
`enabled`	`true`, `false`, or `null`	`null` = inherit (AI on). Only an explicit `false` turns AI off for this child.
`provider`	`devotel`, `anthropic`, or `null`	`null` = the platform default provider. `devotel` is the free base tier; `anthropic` is the premium tier.
`comped`	`true` or `false`	`true` = you mark the child’s AI usage as free. Defaults to `false` unless you set it.

Reads return two layers side by side: stored (exactly what you recorded, nulls included) and the resolved effective values plus providerSource — stored when you pinned a provider, platform_default when the child falls through to the default. That distinction is what you audit: how many children actually carry an override versus ride the default.

Why set it per child

Isolating billing and behavior per child organization is the point of subaccounts; AI configuration follows the same rule:

A customer on a lower tier can have AI disabled while the rest stay enabled — one PUT, no plan change.
A child pinned to a specific provider keeps that choice; new subaccounts keep the platform default until you pin them.
A comped child never accumulates AI charges against your consolidated reseller statement.

Every PUT is recorded in your audit log with the resulting field values.

Read the current config

GET /api/v1/subaccounts/{id}/ai-config returns the resolved view plus the selectable provider catalog in one round trip. Owner or admin on the parent organization is required.

curl -X GET "https://api.orbit.devotel.io/api/v1/subaccounts/sub_abc123/ai-config" \
  -H "X-API-Key: dv_live_sk_your_parent_key"

Update the config

PUT the same path with all three fields — the body is full-set:

curl -X PUT "https://api.orbit.devotel.io/api/v1/subaccounts/sub_abc123/ai-config" \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "provider": "anthropic",
    "comped": false
  }'

Omitting a field returns 422; unlike branding or pricing writes, nulls here are meaningful (see Reset semantics). The response echoes the resolved view back, so your automation re-renders the effective state without a second GET.

Worked sample — disable AI and comp a child

Disable AI for a subaccount while absorbing its remaining AI usage as free:

curl -X PUT "https://api.orbit.devotel.io/api/v1/subaccounts/sub_abc123/ai-config" \
  -H "X-API-Key: dv_live_sk_your_parent_key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false,
    "provider": null,
    "comped": true
  }'

const res = await fetch(
  'https://api.orbit.devotel.io/api/v1/subaccounts/sub_abc123/ai-config',
  {
    method: 'PUT',
    headers: {
      'X-API-Key': process.env.ORBIT_API_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      enabled: false,
      provider: null,
      comped: true,
    }),
  },
)
console.log(await res.json())

200

{
  "data": {
    "stored": {
      "enabled": false,
      "provider": null,
      "comped": true
    },
    "enabled": false,
    "provider": "devotel",
    "providerSource": "platform_default",
    "comped": true
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

The response also carries a catalog array with every selectable provider — render that, never a hard-coded list.

Reset semantics

Reset is a write through the same endpoint — there is no separate reset route. When a child asks you to restore defaults, clear the override by sending nulls:

{ "enabled": null, "provider": null, "comped": false }

enabled: null clears the on/off override back to inherit — AI on again.
provider: null clears the pin back to the platform default, and providerSource flips back to platform_default.
comped: false turns the free-usage marker off. It never clears itself by passing null; send false explicitly.

The dashboard mirrors this exactly: Settings → Subaccounts → a child’s AI tab offers “Inherit (on)” and “Platform default” options that write these nulls.

When comped is appropriate

Comped is a billing statement you make on behalf of the child: their AI usage counts as free. Reach for it when:

You bundle AI into the customer’s flat subscription instead of metering it back to them.
You’re running a pilot or proof-of-concept and absorbing the AI cost during evaluation.
A service credit or goodwill adjustment is owed and you comp usage rather than refund the statement.

It is a per-child marker, so your consolidated rollup still prices the other children normally. Because the claim “usage is free” is billing-relevant, it defaults to false — set it deliberately, and unset it the same way.

Anti-patterns

Setting enabled: false to control spend — use channel budgets or a monthly spend cap for budget control; enabled gates the feature, not the wallet.
Hard-coding provider keys in your portal — render the catalog array from the GET response so your UI tracks the selectable set.
Assuming a PUT is partial-update — the body is full-set; read-modify-write with nulls preserved, or you silently clear overrides.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Per-subaccount AI configuration

Per-subaccount AI configuration

What the config governs

Why set it per child

Read the current config

Update the config

Worked sample — disable AI and comp a child

Reset semantics

When comped is appropriate

Anti-patterns

See also

​Per-subaccount AI configuration

​What the config governs

​Why set it per child

​Read the current config

​Update the config

​Worked sample — disable AI and comp a child

​Reset semantics

​When comped is appropriate

​Anti-patterns

​See also

Per-subaccount AI configuration

What the config governs

Why set it per child

Read the current config

Update the config

Worked sample — disable AI and comp a child

Reset semantics

When comped is appropriate

Anti-patterns

See also