Billing usage and settings

Use an admin-scoped API key for these endpoints. Agent-scoped keys receive 403. You can also manage billing in the Inkbox Console.

Read current usage

GET /api/v1/billing/usage

Returns usage for your organization’s current billing cycle. Included SMS/MMS and call-minute allowances, and the listed overage rates, cover U.S. and Canadian numbers. International texting and calling use international lines with pricing by country. See Plans and pricing, or contact us to arrange an international line.

cURL

curl "https://inkbox.ai/api/v1/billing/usage" \
  -H "X-API-Key: YOUR_ADMIN_API_KEY"

Response (200)

Field	Type	Description
`cycle_start`, `cycle_end`	integer, integer \| null	Billing-cycle boundaries in Unix seconds
`plan`	string	Current plan
`channels`	object[]	Organization-wide usage by channel
`identities`	object[]	Usage and allowances by identity
`sms_allowance_per_identity`	integer	Included SMS units per phone-enabled identity per cycle
`voice_sec_allowance_per_identity`	integer	Included call seconds per phone-enabled identity per cycle
`overage_cap_cents`	integer \| null	Configured SMS and voice overage limit; `null` means no limit
`overage_spend_cents`	integer	Estimated SMS and voice overage cost this cycle, in cents
`imessage_shared_messages`	integer	Shared-service iMessage messages in both directions
`imessage_dedicated_messages`	integer	Dedicated-line iMessage messages in both directions
`imessage_unique_recipients`	integer	Unique recipients using the shared iMessage service
`identities_used`, `identities_included`	integer	Active identities and the number included in your plan

Each entry in channels contains:

Field	Type	Description
`event_type`	string	Channel, such as `sms_outbound`
`count`	integer	Message count or call seconds this cycle
`overage`	integer	Units beyond the included allowance
`est_overage_cents`	integer \| null	Estimated overage cost; `null` when no estimate is available
`own_campaign_count`	integer \| null	SMS units carried through your own 10DLC campaign; `null` for other channels

Each entry in identities contains nullable identity_id, handle, and display_name, plus a channels array of event_type, count, and own_campaign_count. Its nullable sms_used, sms_limit, voice_sec_used, and voice_sec_limit fields report usage and allowances. A null identity ID represents unattributed usage.

Read billing settings

GET /api/v1/billing/settings

cURL

curl "https://inkbox.ai/api/v1/billing/settings" \
  -H "X-API-Key: YOUR_ADMIN_API_KEY"

Response (200)

{
  "overage_cap_cents": null,
  "remove_branding_footer": false
}

Update billing settings

PUT /api/v1/billing/settings

Omitted fields stay unchanged. The response returns both current settings.

Field	Type	Description
`overage_cap_cents`	integer \| null	SMS and voice overage limit in cents, from `0` to `10000000`. `null` removes the limit. `0` prevents new sends and calls that incur overage
`remove_branding_footer`	boolean \| null	`true` removes the Sent via Inkbox email footer on paid plans. `false` restores it. Omit or send `null` to leave it unchanged

This example sets a $25 overage limit:

cURL

curl -X PUT "https://inkbox.ai/api/v1/billing/settings" \
  -H "X-API-Key: YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"overage_cap_cents": 2500}'

When estimated overage spending reaches the limit, new sends and calls that would incur overage return 402 until the cycle resets or you raise the limit. Included usage remains available. Inbound and in-progress usage can exceed the limit, so this setting is not a strict invoice ceiling. Setting remove_branding_footer to true on the Free plan returns 403. The footer always appears on Free, even if you enabled its removal while on a paid plan.

Agent signup API

Agent identity API

Agent2Agent API

Mail API

Phone API

iMessage API

Webhooks API

Tunnels API

Contacts API

Notes API

Vault API

Billing API

Billing usage and settings

Read current usage

Response (200)

Read billing settings

Response (200)

Update billing settings

​Read current usage

​Response (200)

​Read billing settings

​Response (200)

​Update billing settings

​Related

Read current usage

Response (200)

Read billing settings

Response (200)

Update billing settings

Related