Languages: every operation supports cURL, Node.js (TypeScript), Python, Go, Ruby, and PHP. The first 15 operations on this page show all six languages; the remaining 61 show cURL and TypeScript — the two most-used.

Billing API

Billing endpoints exposed by the Devotel CPaaS API Base path: /api/v1/billing Endpoint count: 76

title: “Worked billing samples” description: “Copy-pasteable request and response samples for the billing endpoints a developer actually calls first: the wallet balance and ledger, top-up checkout, plan checkout, auto top-up, and billing alerts.”

Wallet balance and ledger

GET /api/v1/billing/balance returns the prepaid wallet as dollars, whole cents, and micro-cents, alongside the outbound-pause flags billing alerts can set. Poll it before a send to check available funds.

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

GET /api/v1/billing/transactions pages through the wallet ledger — top-ups, spend debits, refunds, and adjustments — newest first, with next_cursor for paging.

{
  "data": {
    "transactions": [
      {
        "id": "txn_01H8XGJ",
        "type": "topup",
        "amount_minor": 5000,
        "reference": "stripe_checkout",
        "metadata": null,
        "created_at": "2026-08-02T12:00:00.000Z",
        "expires_at": null,
        "refunded_at": null
      },
      {
        "id": "txn_01H8XGB",
        "type": "debit",
        "amount_minor": -132,
        "reference": "sms_send",
        "metadata": null,
        "created_at": "2026-08-02T11:47:00.000Z",
        "expires_at": null,
        "refunded_at": null
      }
    ],
    "next_cursor": null,
    "has_more": false
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Top up the wallet

POST /api/v1/billing/balance/top-up returns a hosted Stripe Checkout URL in the locally-hosted checkoutUrl field; the wallet is credited once the payment settles. The Idempotency-Key header dedupes retries, so a repeated request returns the same session instead of charging twice.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/balance/top-up" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 5000,
  "currency": "usd",
  "successUrl": "https://app.example.com/billing/success",
  "cancelUrl": "https://app.example.com/billing"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/balance/top-up', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "amount": 5000,
  "currency": "usd",
  "successUrl": "https://app.example.com/billing/success",
  "cancelUrl": "https://app.example.com/billing"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/billing/balance/top-up", headers=headers, json={
  "amount": 5000,
  "currency": "usd",
  "successUrl": "https://app.example.com/billing/success",
  "cancelUrl": "https://app.example.com/billing"
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/billing/balance/top-up", bytes.NewBuffer([]byte(`{
  "amount": 5000,
  "currency": "usd",
  "successUrl": "https://app.example.com/billing/success",
  "cancelUrl": "https://app.example.com/billing"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/billing/balance/top-up')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "amount": 5000,
  "currency": "usd",
  "successUrl": "https://app.example.com/billing/success",
  "cancelUrl": "https://app.example.com/billing"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/billing/balance/top-up');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "amount": 5000,
  "currency": "usd",
  "successUrl": "https://app.example.com/billing/success",
  "cancelUrl": "https://app.example.com/billing"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_a1B2c3D4"
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Plan checkout and subscription management

POST /api/v1/billing/checkout starts a Stripe Checkout session for a subscription-plan change and returns the hosted checkoutUrl; requests are idempotent for 60 seconds per organization and plan, so a double-click returns the same session URL.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/checkout" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "planId": "pro",
  "successUrl": "https://app.example.com/billing/success",
  "cancelUrl": "https://app.example.com/billing/plans"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/checkout', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "planId": "pro",
  "successUrl": "https://app.example.com/billing/success",
  "cancelUrl": "https://app.example.com/billing/plans"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/billing/checkout", headers=headers, json={
  "planId": "pro",
  "successUrl": "https://app.example.com/billing/success",
  "cancelUrl": "https://app.example.com/billing/plans"
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/billing/checkout", bytes.NewBuffer([]byte(`{
  "planId": "pro",
  "successUrl": "https://app.example.com/billing/success",
  "cancelUrl": "https://app.example.com/billing/plans"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/billing/checkout')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "planId": "pro",
  "successUrl": "https://app.example.com/billing/success",
  "cancelUrl": "https://app.example.com/billing/plans"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/billing/checkout');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "planId": "pro",
  "successUrl": "https://app.example.com/billing/success",
  "cancelUrl": "https://app.example.com/billing/plans"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3"
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

POST /api/v1/billing/portal opens a Stripe customer-portal session so the customer can manage payment methods, subscription, and invoices. Read GET /api/v1/billing/status first and only offer this (or plan checkout above) when can_manage is true.

{
  "data": {
    "url": "https://billing.stripe.com/p/session/DYb3GT1"
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Auto top-up configuration

PUT /api/v1/billing/auto-topup charges the saved payment method off-session whenever the balance falls to the threshold. recharge_amount_minor must exceed threshold_minor.

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/billing/auto-topup" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "threshold_minor": 500,
  "recharge_amount_minor": 5000,
  "max_monthly_minor": 50000,
  "currency": "usd"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/auto-topup', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "enabled": true,
  "threshold_minor": 500,
  "recharge_amount_minor": 5000,
  "max_monthly_minor": 50000,
  "currency": "usd"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.put("https://api.orbit.devotel.io/api/v1/billing/auto-topup", headers=headers, json={
  "enabled": true,
  "threshold_minor": 500,
  "recharge_amount_minor": 5000,
  "max_monthly_minor": 50000,
  "currency": "usd"
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("PUT", "https://api.orbit.devotel.io/api/v1/billing/auto-topup", bytes.NewBuffer([]byte(`{
  "enabled": true,
  "threshold_minor": 500,
  "recharge_amount_minor": 5000,
  "max_monthly_minor": 50000,
  "currency": "usd"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/billing/auto-topup')
req = Net::HTTP::Put.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "enabled": true,
  "threshold_minor": 500,
  "recharge_amount_minor": 5000,
  "max_monthly_minor": 50000,
  "currency": "usd"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/billing/auto-topup');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "enabled": true,
  "threshold_minor": 500,
  "recharge_amount_minor": 5000,
  "max_monthly_minor": 50000,
  "currency": "usd"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "enabled": true,
    "threshold_minor": 500,
    "recharge_amount_minor": 5000,
    "max_monthly_minor": 50000,
    "currency": "USD"
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Billing alerts

POST /api/v1/billing/alerts/ creates a spend or balance threshold. At least one email or SMS recipient is required; action_on_hit can be notify, pause_outbound, or block_outbound.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/alerts/" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "80% of monthly budget",
  "threshold_type": "spend_percent",
  "threshold_value": 80,
  "currency": "USD",
  "notify_emails": [
    "billing@example.com"
  ],
  "action_on_hit": "notify",
  "cooldown_hours": 24,
  "enabled": true
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/alerts/', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "name": "80% of monthly budget",
  "threshold_type": "spend_percent",
  "threshold_value": 80,
  "currency": "USD",
  "notify_emails": [
    "billing@example.com"
  ],
  "action_on_hit": "notify",
  "cooldown_hours": 24,
  "enabled": true
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/billing/alerts/", headers=headers, json={
  "name": "80% of monthly budget",
  "threshold_type": "spend_percent",
  "threshold_value": 80,
  "currency": "USD",
  "notify_emails": [
    "billing@example.com"
  ],
  "action_on_hit": "notify",
  "cooldown_hours": 24,
  "enabled": true
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/billing/alerts/", bytes.NewBuffer([]byte(`{
  "name": "80% of monthly budget",
  "threshold_type": "spend_percent",
  "threshold_value": 80,
  "currency": "USD",
  "notify_emails": [
    "billing@example.com"
  ],
  "action_on_hit": "notify",
  "cooldown_hours": 24,
  "enabled": true
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/billing/alerts/')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "name": "80% of monthly budget",
  "threshold_type": "spend_percent",
  "threshold_value": 80,
  "currency": "USD",
  "notify_emails": [
    "billing@example.com"
  ],
  "action_on_hit": "notify",
  "cooldown_hours": 24,
  "enabled": true
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/billing/alerts/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "name": "80% of monthly budget",
  "threshold_type": "spend_percent",
  "threshold_value": 80,
  "currency": "USD",
  "notify_emails": [
    "billing@example.com"
  ],
  "action_on_hit": "notify",
  "cooldown_hours": 24,
  "enabled": true
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "alert": {
      "id": "alert_01HZY8ALERT",
      "organization_id": "org_01HZY8ORG",
      "name": "80% of monthly budget",
      "threshold_type": "spend_percent",
      "threshold_value": 80,
      "currency": "USD",
      "notify_emails": [
        "billing@example.com"
      ],
      "notify_sms_numbers": "[]",
      "action_on_hit": "notify",
      "last_triggered_at": null,
      "cooldown_hours": 24,
      "enabled": true,
      "created_by": "user_01HZY8USER",
      "created_at": "2026-08-01T09:00:00.000Z",
      "updated_at": "2026-08-01T09:00:00.000Z"
    }
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

These samples compound; the auto-generated per-operation entries below always carry the full parameter table even where a sample here already covers the op.

List billing alerts

GET /api/v1/billing/alerts

Returns the billing alerts configured for the caller’s organization, most recent first (up to 200), with the total count. Each alert defines a spend or balance threshold and the notification and action taken when it is crossed. Read-only; owner, admin, or billing role required.

string (enum: true|false)

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/alerts" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/alerts', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/billing/alerts", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/billing/alerts", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/billing/alerts')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/billing/alerts');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Get a billing alert

GET /api/v1/billing/alerts/{id}

Returns a single billing alert by id for the caller’s organization, or 404 if it does not exist. Read-only; owner, admin, or billing role required.

string

required

—

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/alerts/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/alerts/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/billing/alerts/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/billing/alerts/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/billing/alerts/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/billing/alerts/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Get auto-top-up configuration

GET /api/v1/billing/auto-topup

Returns the organization’s automatic top-up configuration: whether it is enabled, the balance threshold that triggers a charge, and the amount added when the threshold is crossed. Read-only; owner, admin, or billing role required.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/auto-topup" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/auto-topup', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/billing/auto-topup", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/billing/auto-topup", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/billing/auto-topup')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/billing/auto-topup');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Get your account balance

GET /api/v1/billing/balance

Returns the organization’s current prepaid wallet balance in USD (dollars, whole cents, and micro-cents), the wallet currency, and pause-state flags. Read-only — accepts an API key carrying the billing:read (or billing:write) scope, or an owner/admin/billing session. Poll it to display a live balance or check available funds before a send.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/balance" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/balance', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/billing/balance", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/billing/balance", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/billing/balance')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/billing/balance');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

List budget-cap

GET /api/v1/billing/budget-cap

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/budget-cap" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/budget-cap', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/billing/budget-cap", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/billing/budget-cap", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/billing/budget-cap')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/billing/budget-cap');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

List burn-rate

GET /api/v1/billing/burn-rate

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/burn-rate" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/burn-rate', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/billing/burn-rate", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/billing/burn-rate", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/billing/burn-rate')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/billing/burn-rate');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

List chargeback-rollup

GET /api/v1/billing/chargeback-rollup

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/chargeback-rollup" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/chargeback-rollup', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/billing/chargeback-rollup", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/billing/chargeback-rollup", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/billing/chargeback-rollup')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/billing/chargeback-rollup');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

List commitment

GET /api/v1/billing/commitment

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/commitment" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/commitment', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/billing/commitment", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/billing/commitment", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/billing/commitment')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/billing/commitment');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

List credits

GET /api/v1/billing/credits

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/credits" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/credits', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/billing/credits", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/billing/credits", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/billing/credits')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/billing/credits');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Check a crypto top-up status

GET /api/v1/billing/crypto-topup/{intentId}/status

Return the current status of a NOWPayments crypto top-up intent — payment status, quoted price and pay currency, and the hosted invoice URL. The dashboard polls this while its pending-top-up card shows; a throttled live reconcile against the provider self-heals a dropped IPN so the poll sees the latest state. Read-only; owner, admin, or billing role.

string

required

—

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/crypto-topup/{intentId}/status" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/crypto-topup/{intentId}/status', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/billing/crypto-topup/{intentId}/status", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/billing/crypto-topup/{intentId}/status", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/billing/crypto-topup/{intentId}/status')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/billing/crypto-topup/{intentId}/status');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

List invoices

GET /api/v1/billing/invoices

Page through the organization’s invoices — id, number, status, amounts, and hosted/self-service download links — queried from the live billing provider with a durable recorded-invoice fallback. Optional status filter and cursor pagination (limit up to 100). Read-only; owner, admin, or billing role.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/invoices" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/invoices', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/billing/invoices", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/billing/invoices", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/billing/invoices')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/billing/invoices');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Get one invoice

GET /api/v1/billing/invoices/{id}

Return a single invoice’s detail — summary fields, line items, memo, and discount — scoped to the caller’s organization. The detail includes a channel-by-country cost breakdown computed from the organization’s usage ledger over the invoice’s billing period (self-serve showback). 404 when the id does not belong to the caller’s organization. Read-only; owner, admin, or billing role.

string

required

—

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/invoices/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/invoices/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/billing/invoices/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/billing/invoices/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/billing/invoices/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/billing/invoices/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Download an invoice PDF

GET /api/v1/billing/invoices/{id}/download

Redirect to one invoice’s downloadable copy — the signed PDF URL, falling back to the hosted invoice page for a draft invoice with no PDF yet. A 302 on every request is deliberate: the billing provider’s signed URLs expire and caching the target would break. 409 when the invoice has no downloadable copy yet; 404 when the id is outside the caller’s organization.

string

required

—

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/invoices/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/download" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/invoices/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/download', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/billing/invoices/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/download", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/billing/invoices/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/download", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/billing/invoices/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/download')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/billing/invoices/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/download');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Get the in-progress invoice

GET /api/v1/billing/invoices/upcoming

Return the invoice in progress for the current billing period — the running total, due date, and line items for the subscription period still accruing usage, plus a channel-by-country cost breakdown computed from the organization’s usage ledger. invoice: null when nothing is accruing. Read-only; owner, admin, or billing role.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/invoices/upcoming" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/invoices/upcoming', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/billing/invoices/upcoming", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/billing/invoices/upcoming", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/billing/invoices/upcoming')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/billing/invoices/upcoming');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

List MCCMNC rate overrides

GET /api/v1/billing/mccmnc-overrides

Page the organization’s MCC/MNC per-operator rate overrides — the fixed per-unit prices that replace the cost-plus markup for specific mobile networks. Optional country and search filters; limit and cursor paginate. Owners and admins see only their own organization; platform super-admins may scope to another org via organization_id. Read-only; owner or admin role.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/mccmnc-overrides" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/mccmnc-overrides', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/billing/mccmnc-overrides", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/billing/mccmnc-overrides", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/billing/mccmnc-overrides')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/billing/mccmnc-overrides');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

List the MCC/MNC network catalog

GET /api/v1/billing/mccmnc-overrides/mnc-list

Return the curated top-100 MCC/MNC mobile-network catalog — MCC, MNC, combined MCC-MNC key, network name, country, and ISO code — the autocomplete list behind the MCCMNC override form. Any authenticated caller may read it; response is data-only.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/mccmnc-overrides/mnc-list" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/mccmnc-overrides/mnc-list', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Get outcome-billing configuration

GET /api/v1/billing/outcome-pricing

Returns the organization’s AI-agent outcome-charge configuration: whether pay-per-resolution is enabled, the default per-outcome rate, and any per-outcome overrides. Workspaces that have never set the config see the opt-out defaults (enabled: false, Plivo-style $0.005 per resolution), so a settings form always renders a stable shape. Owner, admin, or billing role required.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/outcome-pricing" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/outcome-pricing', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Get the default payment method

GET /api/v1/billing/payment-method

Returns the organization’s default payment method on file (card brand, last four digits, and expiry month/year) — cached for five minutes in front of Stripe. An empty data object means no payment method is saved or the billing provider is unavailable, so the dashboard card self-hides. Call it to render a payment-method summary before a checkout or auto-top-up form.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/payment-method" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/payment-method', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

List self-serve plans

GET /api/v1/billing/plans

Returns the self-serve plan catalog — the single default pay-as-you-go plan with its free-trial credit and the channels and capabilities it entitles. The catalog is static and cache-friendly (no per-org lookup), so onboarding and pricing screens can render ahead of any billing role. Call it to show a new workspace what the default plan includes before activation.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/plans" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/plans', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

List credit refunds

GET /api/v1/billing/refunds

Returns the organization’s refund requests, newest first — each with its amount, reason, provider refund id, current status, and, for a failed request, the reason it failed. Use it to render refund history or poll a refund’s progress. Owner role required.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/refunds" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/refunds', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Get a credit refund

GET /api/v1/billing/refunds/{id}

Returns a single refund request’s detail — amount, reason, provider refund id, current status (pending, approved, rejected, processed, or failed), and, when the request failed, a failure_reason explaining why (populated only when status is failed). Use it to poll one refund’s progress instead of scanning the full refund history. Returns 404 when the id is missing or belongs to another organization. Owner-role only, same as creating a refund.

string

required

Refund request id, for example refund_9f2c1a7b4e0d….

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/refunds/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/refunds/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Per-contract revenue-recognition schedule

GET /api/v1/billing/revenue-recognition/schedule

Return the ratable (straight-line, ASC 606) recognition schedule for each of the organization’s deferred-revenue contracts — the negotiated committed-use commitment plus recurring subscription invoice lines — split period by period so the per-period amounts sum exactly to the contract total. Optional as_of (YYYY-MM-DD) pins the reporting instant. Read-only; computed on demand, moves no money; billing role.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/revenue-recognition/schedule" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/revenue-recognition/schedule', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Recognized vs deferred revenue rollup

GET /api/v1/billing/revenue-recognition/summary

Roll the organization’s recognition contracts up into recognized-to-date versus remaining-deferred balances as of the optional as_of (YYYY-MM-DD) reporting date, reconciling recognized + deferred to the invoiced / committed totals — the ASC 606 deferred-revenue answer for the finance surface. Read-only; computed on demand, writes nothing; billing role.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/revenue-recognition/summary" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/revenue-recognition/summary', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Seat-tier breakdown and savings estimate

GET /api/v1/billing/seats

Return the organization’s full- versus light-seat counts (light seats are free — read-only collaborators, KB authors, managers), the per-full-seat monthly rate, the estimated monthly seat cost, and the estimated savings versus an all-full-seat plan. All amounts in USD minor units (cents). Read-only; owner, admin, or billing role.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/seats" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/seats', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Flag channels with surging spend velocity

GET /api/v1/billing/spend-anomaly

Compare each channel’s projected daily spend against the organization’s trailing baseline and flag channels whose velocity surged past the configured multiple — the proactive signal that catches a compromised account before its daily cap is exhausted. Each flag records an operator fraud-review alert per (organization, channel, day) and may arm an automatic mitigation throttle. Read-only; billing role.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/spend-anomaly" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/spend-anomaly', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Historical spend-anomaly ledger

GET /api/v1/billing/spend-anomaly/ledger

Page the organization’s historical spend-velocity anomaly insights — the fraud-review history the point-in-time GET /billing/spend-anomaly read (only currently-flagged channels) cannot show. Query knobs: from / to ISO datetimes and limit (1–500, default 100). Each row unwraps into billing-friendly top-level fields (channel, surge ratio, baseline / projected / today spend, severity, auto-mitigation) with operator-shared references pre-scrubbed. Read-only; billing role.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/spend-anomaly/ledger" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/spend-anomaly/ledger', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Daily spend series with projection and anomaly flags

GET /api/v1/billing/spend-series

Return the per-day spend series for the lookback window (query days, default 30) — the absolute spend amount per day computed from the prepaid-wallet ledger — plus a 7-day forward projection (the trailing 7-day moving average). Historical days whose spend exceeds mean + 2×stddev are flagged as anomalies (the red dots on the dashboard chart). Cached ~5 minutes; degrades to the last-known-good snapshot, then to an empty series, on a DB-availability blip rather than 503ing the always-on dashboard widget. Read-only; billing role.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/spend-series" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/spend-series', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

List monthly wallet statements

GET /api/v1/billing/statements

List the organization’s native monthly billing statements — the period aggregation of the prepaid-wallet ledger that answers a pay-as-you-go tenant’s “no invoice on the 1st” (the prepaid wallet is the billing surface; no subscription invoice is issued). Optional limit bounds the page. Read-only; owner or admin role.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/statements" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/statements', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Monthly statement detail

GET /api/v1/billing/statements/{period}

Return the full detail for one monthly statement — path period as YYYY-MM (e.g. /statements/2026-08): opening / closing balance, top-ups and usage totals, the per-channel usage split, and the reconciling line items that fold the period’s wallet movement. Read-only; owner or admin role.

string

required

—

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/statements/{period}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/statements/{period}', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Download a monthly statement

GET /api/v1/billing/statements/{period}/download

Download one monthly statement — path period as YYYY-MM — as RFC-4180 CSV (default) or JSON via query format=csv|json. Returns a Content-Disposition attachment statement-<period>.<ext> with Cache-Control: private, no-store, e.g. statement-2026-08.csv. Read-only; owner or admin role.

string

required

—

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/statements/{period}/download" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/statements/{period}/download', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Billing provider configuration status

GET /api/v1/billing/status

Report whether the billing provider is configured and whether the organization has a provider customer yet — the gate the dashboard billing surface polls before offering top-up / checkout / portal actions. can_checkout tracks provider-config alone (checkout auto-provisions the customer); can_manage requires a linked customer; lookup_degraded flags a failed customer lookup so the UI never treats a degraded read as authoritative. Read-only; billing role.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/status" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/status', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Live snapshot of the organization’s subscription

GET /api/v1/billing/subscription

Return the organization’s live subscription state — status, cancel-at-period-end flag, and current period end — for the dashboard’s self-service cancel / reactivate surface. Pay-as-you-go-only tenants (no active subscription) get all-null fields so the UI self-hides. Read-only; owner, admin, or billing role.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/subscription" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/subscription', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

List wallet ledger transactions

GET /api/v1/billing/transactions

Page through the organization’s prepaid-wallet ledger — the credit / debit / adjustment rows backing the transaction history in settings → billing. Query knobs: limit (page size), cursor_ts + cursor_id (composite key-set pagination), and type to filter one transaction kind. Read-only; billing role.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/transactions" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/transactions', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Check trial-credit grant status

GET /api/v1/billing/trial-credits/status

Report whether the one-time promotional trial credit has already been granted for the caller’s own organization, plus whether the trial-credit program is currently enabled platform-wide. Drives the dashboard’s claim-control visibility — poll before rendering the claim button; always scoped to the caller’s tenant. Read-only; owner or admin role.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/trial-credits/status" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/trial-credits/status', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Get current-period usage metrics

GET /api/v1/billing/usage

Fetch the organization’s current-period usage metrics (billed-message counters) for the period the billing service is tracking. An upstream billing-provider outage degrades the response to an empty period + zero metrics instead of failing the dashboard usage card. Read-only; billing role.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/usage" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/usage', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Usage cost and volume by channel

GET /api/v1/billing/usage-by-channel

Break the period’s outbound usage down by channel (default), or by country, campaign, sender, or cost-center tag via group_by, over a days window — the canonical cost-and-volume split behind the dashboard usage charts, sourced from the organization’s actual billed charges rather than estimates. Read-only; billing role.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/usage-by-channel" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/usage-by-channel', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Preview volume-discount pricing

GET /api/v1/billing/volume-tier-preview

Estimate the per-unit price, projected monthly spend, and savings versus the rack rate at a projected monthly volume for a channel (sms / whatsapp / voice / email / rcs), optionally country-pinned via country_code. Applies the organization’s own negotiated tiers first, then the platform defaults. Read-only; moves no money; billing role.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/volume-tier-preview" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/volume-tier-preview', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

List volume-discount tiers

GET /api/v1/billing/volume-tiers

List volume-discount pricing tiers — the volume bands that cut the per-unit price as monthly send volumes grow. Filter by channel, organization_id, or scope (platform defaults, one org, or all orgs). Non-super-admins are always pinned to their own organization; cross-org and all-org listing is super-admin only. Read-only; owner or admin role.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/billing/volume-tiers" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/volume-tiers', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Report AI agent usage

POST /api/v1/billing/agent-usage

Internal service-to-service endpoint (agent-runtime to billing) that meters an AI-agent invocation against the tenant’s prepaid wallet. Authenticated with a signed internal token, not a developer API key, so it is not callable with public credentials. Resolves the X-Tenant-Id header against the organization record, reserves and deducts balance for the reported usage, and writes a per-debit audit entry.

string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/agent-usage" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/agent-usage', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Preview aiaas-usage-pricing

POST /api/v1/billing/aiaas-usage-pricing/preview

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/aiaas-usage-pricing/preview" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/aiaas-usage-pricing/preview', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Create a billing alert

POST /api/v1/billing/alerts

Creates a billing alert for the organization: a spend or balance threshold, the email and SMS recipients to notify, the action to take when it is hit, and a cooldown. Owner, admin, or billing role required.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/alerts" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/alerts', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Test-fire a billing alert

POST /api/v1/billing/alerts/{id}/test-fire

Runs a dry-run evaluation of a billing alert against the current spend and balance and reports whether it would trigger, without sending any notifications or taking the configured action. Useful for validating threshold and recipient configuration. Owner, admin, or billing role required.

string

required

—

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/alerts/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/test-fire" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/alerts/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/test-fire', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Reset outbound pause and block flags

POST /api/v1/billing/alerts/reset-outbound

Clears the organization’s outbound_paused and outbound_blocked flags that a billing alert set when a spend threshold was crossed, re-enabling outbound sending. Restricted to owner and admin roles.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/alerts/reset-outbound" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/alerts/reset-outbound', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Top up your prepaid balance

POST /api/v1/billing/balance/top-up

Starts a prepaid-wallet top-up for the organization and returns the payment session needed to complete the charge. Requires an owner, admin, or billing role and is rate-limited as a money-moving operation. The wallet is credited once the payment settles.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/balance/top-up" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/balance/top-up', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Top-up-crypto balance

POST /api/v1/billing/balance/top-up-crypto

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/balance/top-up-crypto" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/balance/top-up-crypto', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Checkout billing

POST /api/v1/billing/checkout

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/checkout" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/checkout', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Confirm credits

POST /api/v1/billing/credits/confirm

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/credits/confirm" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/credits/confirm', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Purchase credits

POST /api/v1/billing/credits/purchase

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/credits/purchase" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/credits/purchase', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Create cancel

POST /api/v1/billing/crypto-topup/{intentId}/cancel

string

required

—

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/crypto-topup/{intentId}/cancel" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/crypto-topup/{intentId}/cancel', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Preview the reseller margin rollup

POST /api/v1/billing/margin-rollup/preview

Roll reseller profitability lines up into net margin per sub-account, channel, and region. The body carries lines (each subaccount_id, channel, optional region, currency, revenue_minor, cost_minor, optional quantity), an optional forced currency, and an optional revenue_share block (partner_id, partner_revenue_share_bps, period bounds) that also returns the partner’s periodic revenue-share statement from the same rollup. Pure estimate — no money moves, no row is written. Owner, admin, or billing role.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/margin-rollup/preview" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/margin-rollup/preview', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

POST /api/v1/billing/marketplace-rev-share/preview

Estimate the agent/tool marketplace rev-share split for a posted set of billable invocations: the body carries invocations (each listingId, builderOrgId, optional consumerOrgId) and pricingByListing (per-listing enabled, perCallPriceMicroCents, and platformFeeBps, 0–9000), plus an optional minPayoutMicroCents payout threshold. Returns the gross charge, the Orbit platform fee, and each builder’s net payout. Pure estimate — no money moves, no row is written. Owner, admin, or billing role.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/marketplace-rev-share/preview" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/marketplace-rev-share/preview', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Create an MCCMNC rate override

POST /api/v1/billing/mccmnc-overrides

Register a fixed per-unit price for one mobile network — body carries mcc + mnc (combined as MCC + MNC zero-padded), rate_per_unit as a decimal string, optional currency (ISO-4217, defaults to USD), and optional organization_id (/mnc-list feeds the autocomplete). The rate must clear the organization’s active wholesale cost, and owners/admins may only target their own organization. 409 when the (organization, network) pair is already overridden — PATCH that row instead. Owner or admin role.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/mccmnc-overrides" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/mccmnc-overrides', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Create a pay-by-link request-to-pay

POST /api/v1/billing/pay-by-link

Mints a hosted checkout link for a one-off customer payment, picks the highest-priority delivery channel the contact is reachable on, and renders the request-to-pay message for that channel (SMS, RCS, WhatsApp, email, or voice). Nothing is sent here; the host carries the returned URL and rendered message into its own send pipeline. Payment settlement lands asynchronously on the checkout webhook. Owner, admin, or billing role required; the call is audit-logged. Returns 422 when the amount is below the provider’s minimum or no preferred channel is reachable.

string

string (enum: true|false)

integer

required

Charge amount in the currency’s minor units (e.g. cents). Minimum 50 — the payment provider’s universal per-currency floor.

string

required

Three-letter ISO 4217 currency code.

string

required

What the payment is for; rendered into the request-to-pay message.

string (enum: sms|rcs|whatsapp|email|voice)[]

required

Delivery channels in descending priority order (cross-channel fallback).

string (enum: sms|rcs|whatsapp|email|voice)[]

required

Channels the contact is currently reachable on.

string

required

Post-payment redirect URL (trusted Orbit origin).

string

required

Redirect URL when the payment is abandoned (trusted Orbit origin).

string

Optional conversation id that links the payment back to a thread.

string

Optional contact id of the payer.

string

Optional merchant name rendered into the message (defaults to the org name).

string

Optional BCP-47 locale for the rendered message.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/pay-by-link" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "amountMinor": 0,
  "currency": "string",
  "description": "string",
  "preferredChannels": [],
  "reachableChannels": [],
  "successUrl": "string",
  "cancelUrl": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/pay-by-link', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "amountMinor": 0,
  "currency": "string",
  "description": "string",
  "preferredChannels": [],
  "reachableChannels": [],
  "successUrl": "string",
  "cancelUrl": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Preview a pay-by-link message

POST /api/v1/billing/pay-by-link/preview

Renders the request-to-pay message for an already-known payment URL without minting anything — pure channel-select + render so the dashboard can show the exact SMS/RCS/WhatsApp/email/voice body before any checkout link is created. Read-only: no money moves, no link is minted, and billing role is not required. Returns 422 when no preferred channel is reachable.

string

string (enum: true|false)

string

required

The payment URL rendered into the message.

integer

required

Charge amount in minor units (same minimum as the mint endpoint).

string

required

Three-letter ISO 4217 currency code.

string

required

What the payment is for.

string (enum: sms|rcs|whatsapp|email|voice)[]

required

Delivery channels in descending priority order.

string (enum: sms|rcs|whatsapp|email|voice)[]

required

Channels the contact is currently reachable on.

string

Optional merchant name rendered into the message.

string

Optional BCP-47 locale for the rendered message.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/pay-by-link/preview" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "string",
  "amountMinor": 0,
  "currency": "string",
  "description": "string",
  "preferredChannels": [],
  "reachableChannels": []
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/pay-by-link/preview', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "url": "string",
  "amountMinor": 0,
  "currency": "string",
  "description": "string",
  "preferredChannels": [],
  "reachableChannels": []
}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Preview a partner payout ledger

POST /api/v1/billing/payout-ledger/preview

Folds a partner’s accrual, payout, and adjustment entries into a single ordered running balance, and optionally cuts a period statement (opening balance → period activity → closing balance). An entry’s optional rail label is informational only; the ledger math never branches on it. Use it to show a reseller or white-label partner what a program owes them across every period. Pure and read-only: no money moves and no payment provider is called; the ledger entries come in the POST body.

string

string (enum: true|false)

string

Partner id to force on the ledger (default: the first entry’s partnerId).

string

Three-letter ISO 4217 ledger currency (default: the first entry’s currency).

object[]

required

The accrual / payout / adjustment entries to fold (one to many).

object

Optional — also cut a period statement from the computed ledger.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/payout-ledger/preview" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "entries": []
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/payout-ledger/preview', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "entries": []
}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Create a billing portal session

POST /api/v1/billing/portal

Creates a Stripe Customer Portal session and returns its hosted URL, so the customer can update cards, download invoices, and manage their subscription on Stripe’s hosted page. The supplied returnUrl must point at a trusted Orbit origin. Owner, admin, or billing role required; rate-limited as a money-moving operation and audit-logged. Redirect the browser to the returned URL.

string

string (enum: true|false)

string

required

URL to return to when the customer exits the portal. Must use a trusted Orbit origin (orbit.devotel.io).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/portal" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "returnUrl": "https://example.com"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/portal', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "returnUrl": "https://example.com"
}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Create a credit refund

POST /api/v1/billing/refunds

Creates a refund against a specific prepaid-credit purchase. Only the unused portion of a credit lot bought within the last 30 days is refundable; the refund is issued against the original charge, the organization wallet is debited by the refunded amount on success, and a retry on the same credit returns the existing request instead of a duplicate. Owner role required. Use the list endpoint to track processing afterwards.

string

string (enum: true|false)

string

required

Id of the credit purchase to refund (from the transaction history).

integer

required

Amount to refund in cents; at most the unused portion of the lot.

string

Optional free-text reason recorded on the refund.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/refunds" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "credit_transaction_id": "string",
  "amount_cents": 0
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/refunds', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "credit_transaction_id": "string",
  "amount_cents": 0
}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Preview resolution-usage billing

POST /api/v1/billing/resolution-usage-meter/preview

Projects confirmed AI resolutions into idempotent usage events, a per-period meter rollup, and the pay-per-resolution invoice line descriptors they would produce under the supplied (or default) outcome-pricing config. Use it to forecast what resolution billing would charge before enabling it. Pure and read-only: no money, no database row, no usage event is emitted; the POST body supplies the resolutions.

string

string (enum: true|false)

object[]

required

The confirmed resolutions to project (each with outcomeKey, conversationId, optional agentId).

object

Optional outcome-pricing config; omitted → the opt-out defaults (billing disabled, so no invoice lines).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/resolution-usage-meter/preview" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "resolutions": []
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/resolution-usage-meter/preview', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "resolutions": []
}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Wire a spend anomaly into on-call escalation

POST /api/v1/billing/spend-anomaly/escalation

Bridge spend-velocity alerts into the on-call escalation pipeline. Re-evaluates the organization’s spend velocity right now through the same evaluator GET /billing/spend-anomaly uses and, when an anomaly is flagged, assembles the escalation plane for it: the incident snapshot anchored to the caller-supplied policy (the on-call rotation policy — members or rotations, channels, ACK / pause windows), the flattened escalation plan, and the first due page to drive through the incident tick and transition endpoints. Pure compute — nothing is sent from this route; the caller owns incident persistence and paging. 422 on an invalid body; detected: false with no incident plane when nothing is worth paging. Billing role.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/spend-anomaly/escalation" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/spend-anomaly/escalation', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Cancel, reactivate, or change the subscription

POST /api/v1/billing/subscription

Manage the organization’s subscription: cancel, reactivate, or switch the plan / price. The JSON body carries the action (cancel | reactivate | change_plan), an optional plan_id, a price_id identifying the provider price to swap onto for change_plan, and an optional free-text reason recorded on the financial audit trail alongside the before / after plan and status snapshot. Owner, admin, or billing role.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/subscription" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/subscription', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Grant the one-time trial credit

POST /api/v1/billing/trial-credits

Grant the one-time promotional trial credit to the caller’s organization. Self-service grants are disabled: the calling session must be a platform super-admin (a customer-success gesture), and the platform trial-credit kill-switch must also be on — otherwise 403. The grant is one-time per organization; subsequent calls no-op. Owner or admin role required.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/trial-credits" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/trial-credits', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Create a volume-discount tier

POST /api/v1/billing/volume-tiers

Create a volume-discount pricing tier — a monthly volume band (min_volume, max_volume; null max = open-ended) that buys the channel’s per-unit price down to price_cents_per_unit, optionally pinned to a country_code. Owners and admins may only create tiers for their own organization; super-admins may target any org or pass organization_id null for a platform-default tier. Audit-logged; 422 (VALIDATION_ERROR) when the band bounds or enums are invalid.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/volume-tiers" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/volume-tiers', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Receive NOWPayments crypto top-up IPNs

POST /api/v1/billing/webhooks/nowpayments

Instant Payment Notification (IPN) receiver for NOWPayments crypto top-ups. Verifies the x-nowpayments-sig header (HMAC-SHA512 over the raw body) before the payment status is trusted; a finished or confirmed status credits the corresponding top-up intent on the organization’s prepaid wallet. A composite payment-id + status dedup key means re-sent IPNs return 200 without re-crediting. Called by NOWPayments, never by your integration; no API key required.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/webhooks/nowpayments" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/webhooks/nowpayments', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Receive Orb usage-billing webhooks

POST /api/v1/billing/webhooks/orb

Webhook receiver for Orb usage-billing events — invoice issued, payment settled, or a subscription state flipped. Verifies the HMAC signature header over the raw body, validates the event payload shape before anything is billed, and records each event id so a redelivered event never replays a credit or a subscription mutation. A processing failure is acknowledged with 200 and reprocessed internally so Orb’s retry loop stays quiet. Called by Orb, never by your integration.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/webhooks/orb" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/webhooks/orb', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Receive Stripe billing webhooks

POST /api/v1/billing/webhooks/stripe

Webhook receiver for Stripe billing events (a payment completing, a subscription changing state, an invoice finalizing, or a charge being reversed). Verifies the Stripe-Signature header against the exact raw request body before the payload is processed, dedupes event ids so Stripe’s own redelivery is safe, and always returns 200 on a well-formed event so Stripe does not retry. Called by Stripe, never by your integration; no API key required.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/webhooks/stripe" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/webhooks/stripe', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Replay real usage against a candidate rate card

POST /api/v1/billing/whatif-pricing/preview

Back-test a proposed rate card against the caller’s OWN recent traffic: the request body carries candidate_card (rows of channel, country_code or *, direction mt/mo, optional sub_type, and rate_per_unit, with optional markup_bps + markup_fixed_cents and an optional human label), plus an optional window_days lookback (1–90, default 30). Every recorded usage lane in the window is priced under both the current live rates and the candidate card, and the per-lane plus total cost difference is returned. Read-only simulation — no money moves, no row is written, no billing event fires. Use it to evaluate a quoted rate swap or a new volume tier before switching. Owner, admin, or billing role.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/billing/whatif-pricing/preview" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/whatif-pricing/preview', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Update auto-top-up configuration

PUT /api/v1/billing/auto-topup

Creates or updates the organization’s automatic top-up rule: the balance threshold at which the saved payment method is charged off-session and the amount to add. Owner, admin, or billing role required. The charge itself is fired by the scheduled worker when the balance crosses the threshold.

string

string (enum: true|false)

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/billing/auto-topup" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/auto-topup', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Update outcome-billing configuration

PUT /api/v1/billing/outcome-pricing

Enables or disables AI-agent pay-per-resolution billing and sets the default and per-outcome rates (integer micro-cents, bounded to a $10/outcome safety ceiling). No money moves on this call; charges fire downstream when an agent rubric marks a conversation as passed. Owner, admin, or billing role required; the change is audit-logged and the re-read persisted state is returned.

string

string (enum: true|false)

boolean

Whether confirmed conversation resolutions are billable (defaults to false).

integer

Default per-resolution rate in micro-cents (100 micro-cents = $0.0001).

object

Per-outcome rate overrides keyed by outcome key (same micro-cent units).

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/billing/outcome-pricing" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/outcome-pricing', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Update a billing alert

PATCH /api/v1/billing/alerts/{id}

Updates the mutable fields of a billing alert (threshold, recipients, action, cooldown, enabled state) for the caller’s organization. Owner, admin, or billing role required.

string

required

—

string (enum: true|false)

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/billing/alerts/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/alerts/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Update an MCCMNC rate override

PATCH /api/v1/billing/mccmnc-overrides/{id}

Patch one MCCMNC rate override — the mutable fields are rate_per_unit, currency, effective_from/effective_to, and notes (the change-control justification the form requires). The write is scoped to the caller’s organization and re-checked against the active wholesale cost, so a rate below cost cannot save. 404 when the override does not exist or belongs to another organization. Owner or admin role.

string

required

—

string (enum: true|false)

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/billing/mccmnc-overrides/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/mccmnc-overrides/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Flip a user between full and light seats

PATCH /api/v1/billing/seats/{userId}

Change one organization member’s seat tier — body { seat_type: "full" | "light" }. Light seats are free (read-only + KB authoring + reporting); full seats are billable. Tenant-bounded by the caller’s organization: an unknown or cross-org userId returns 404 — never a cross-tenant write. The change is audit-logged (previous and new seat type). Owner or admin role required.

string

required

—

string (enum: true|false)

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/billing/seats/{userId}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/seats/{userId}', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Update a volume tier

PATCH /api/v1/billing/volume-tiers/{id}

Patch the mutable fields of one volume-discount tier — country_code, min_volume, max_volume, price_cents_per_unit — at least one required (422 otherwise). Owners and admins may only patch their own organization’s tiers; super-admins may set platform_default: true to target platform-default rows. Audit-logged; 404 when the tier is unknown or out of scope.

string

required

—

string (enum: true|false)

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/billing/volume-tiers/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/volume-tiers/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Delete a billing alert

DELETE /api/v1/billing/alerts/{id}

Permanently deletes a billing alert by id for the caller’s organization. Owner, admin, or billing role required.

string

required

—

string (enum: true|false)

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/billing/alerts/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/alerts/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Disable auto-top-up

DELETE /api/v1/billing/auto-topup

Disables automatic top-up for the organization and clears its saved configuration, so the balance is no longer topped up off-session. Owner, admin, or billing role required.

string (enum: true|false)

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/billing/auto-topup" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/auto-topup', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Delete an MCCMNC rate override

DELETE /api/v1/billing/mccmnc-overrides/{id}

Remove one MCCMNC rate override by id. Deletes silently revert the operator to the platform default rate; owners/admins may only touch their own organization’s rows (cross-org ids return 404 to avoid probing existence). The reverted-from rate and currency are retained on the audit trail for change-control review. Owner or admin role.

string

required

—

string (enum: true|false)

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/billing/mccmnc-overrides/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/mccmnc-overrides/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

Delete a volume tier

DELETE /api/v1/billing/volume-tiers/{id}

Remove one volume-discount tier by id. Tenant owners and admins may only delete their own organization’s tiers; mutating platform-default rows requires super-admin plus platform_default=true. The deletion is audit-logged. 404 when the tier does not exist or is outside the caller’s scope.

string

required

—

string (enum: true|false)

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/billing/volume-tiers/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/volume-tiers/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "balance_usd": 42.5,
    "balance_cents": 4250,
    "balance_micro_cents": 4250000000,
    "credits": 4250,
    "currency": "USD",
    "outbound_paused": false,
    "outbound_block_reason": null,
    "payment_failure_count": 0
  },
  "meta": {
    "request_id": "req_01HZY8EXAMPLE",
    "timestamp": "2026-08-02T12:00:00.000Z"
  }
}

​Billing API

​title: “Worked billing samples” description: “Copy-pasteable request and response samples for the billing endpoints a developer actually calls first: the wallet balance and ledger, top-up checkout, plan checkout, auto top-up, and billing alerts.”

​Wallet balance and ledger

​Top up the wallet

​Plan checkout and subscription management

​Auto top-up configuration

​Billing alerts

​List billing alerts

​Get a billing alert

​Get auto-top-up configuration

​Get your account balance

​List budget-cap

​List burn-rate

​List chargeback-rollup

​List commitment

​List credits

​Check a crypto top-up status

​List invoices

​Get one invoice

​Download an invoice PDF

​Get the in-progress invoice

​List MCCMNC rate overrides

​List the MCC/MNC network catalog

​Get outcome-billing configuration

​Get the default payment method

​List self-serve plans

​List credit refunds

​Get a credit refund

​Per-contract revenue-recognition schedule

​Recognized vs deferred revenue rollup

​Seat-tier breakdown and savings estimate

​Flag channels with surging spend velocity

​Historical spend-anomaly ledger

​Daily spend series with projection and anomaly flags

​List monthly wallet statements

​Monthly statement detail

​Download a monthly statement

​Billing provider configuration status

​Live snapshot of the organization’s subscription

​List wallet ledger transactions

​Check trial-credit grant status

​Get current-period usage metrics

​Usage cost and volume by channel

​Preview volume-discount pricing

​List volume-discount tiers

​Report AI agent usage

​Preview aiaas-usage-pricing

​Create a billing alert

​Test-fire a billing alert

​Reset outbound pause and block flags

​Top up your prepaid balance

​Top-up-crypto balance

​Checkout billing

​Confirm credits

​Purchase credits

​Create cancel

​Preview the reseller margin rollup

​Preview the marketplace rev-share split

​Create an MCCMNC rate override

​Create a pay-by-link request-to-pay

​Preview a pay-by-link message

​Preview a partner payout ledger

​Create a billing portal session

​Create a credit refund

​Preview resolution-usage billing

​Wire a spend anomaly into on-call escalation

​Cancel, reactivate, or change the subscription

​Grant the one-time trial credit

​Create a volume-discount tier

​Receive NOWPayments crypto top-up IPNs

​Receive Orb usage-billing webhooks

​Receive Stripe billing webhooks

​Replay real usage against a candidate rate card

​Update auto-top-up configuration

​Update outcome-billing configuration

​Update a billing alert

​Update an MCCMNC rate override

​Flip a user between full and light seats

​Update a volume tier

​Delete a billing alert

Billing API

title: “Worked billing samples” description: “Copy-pasteable request and response samples for the billing endpoints a developer actually calls first: the wallet balance and ledger, top-up checkout, plan checkout, auto top-up, and billing alerts.”

Wallet balance and ledger

Top up the wallet

Plan checkout and subscription management

Auto top-up configuration

Billing alerts

List billing alerts

Get a billing alert

Get auto-top-up configuration

Get your account balance

List budget-cap

List burn-rate

List chargeback-rollup

List commitment

List credits

Check a crypto top-up status

List invoices

Get one invoice

Download an invoice PDF

Get the in-progress invoice

List MCCMNC rate overrides

List the MCC/MNC network catalog

Get outcome-billing configuration

Get the default payment method

List self-serve plans

List credit refunds

Get a credit refund

Per-contract revenue-recognition schedule

Recognized vs deferred revenue rollup

Seat-tier breakdown and savings estimate

Flag channels with surging spend velocity

Historical spend-anomaly ledger

Daily spend series with projection and anomaly flags

List monthly wallet statements

Monthly statement detail

Download a monthly statement

Billing provider configuration status

Live snapshot of the organization’s subscription

List wallet ledger transactions

Check trial-credit grant status

Get current-period usage metrics

Usage cost and volume by channel

Preview volume-discount pricing

List volume-discount tiers

Report AI agent usage

Preview aiaas-usage-pricing

Create a billing alert

Test-fire a billing alert

Reset outbound pause and block flags

Top up your prepaid balance

Top-up-crypto balance

Checkout billing

Confirm credits

Purchase credits

Create cancel

Preview the reseller margin rollup

Preview the marketplace rev-share split

Create an MCCMNC rate override

Create a pay-by-link request-to-pay

Preview a pay-by-link message

Preview a partner payout ledger

Create a billing portal session

Create a credit refund

Preview resolution-usage billing

Wire a spend anomaly into on-call escalation

Cancel, reactivate, or change the subscription

Grant the one-time trial credit

Create a volume-discount tier

Receive NOWPayments crypto top-up IPNs

Receive Orb usage-billing webhooks

Receive Stripe billing webhooks

Replay real usage against a candidate rate card

Update auto-top-up configuration

Update outcome-billing configuration

Update a billing alert

Update an MCCMNC rate override

Flip a user between full and light seats

Update a volume tier

Delete a billing alert