Billing API

Orbit is pay-as-you-go. There are no plan tiers or recurring subscriptions. Each organization has a single prepaid USD wallet; top it up via one-time Stripe Checkout sessions, and per-send / per-call / per-token charges are deducted in real time from the wallet against an append-only credit_transactions ledger. For the full endpoint reference (status, balance, top-up, auto-top-up, transactions, usage analytics, invoices, refunds) see Billing API. This page is the multi-language code-sample companion for the most common operations. Base path: /api/v1/billing

Get Wallet Balance

GET /api/v1/billing/balance (alias: GET /api/v1/billing/credits) Returns the current wallet balance in USD cents plus the outbound-pause flag.

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-sdk'

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": 150.00,
    "balance_cents": 15000,
    "credits": 15000,
    "outbound_paused": false,
    "outbound_block_reason": null
  },
  "meta": {
    "request_id": "req_balance_001",
    "timestamp": "2026-05-16T12:00:00Z"
  }
}

Create Top-Up Session

POST /api/v1/billing/balance/top-up (alias: POST /api/v1/billing/credits/purchase) Creates a Stripe Checkout session (mode: payment — one-time charge) for adding USD credits to the wallet. The Idempotency-Key header is required (8-255 chars); re-submitting the same key returns the original Checkout URL.

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": 10000,
  "currency": "usd",
  "successUrl": "https://orbit.devotel.io/billing?topup=ok",
  "cancelUrl": "https://orbit.devotel.io/billing?topup=cancelled"
}'

Node.js

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

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": 10000,
  "currency": "usd",
  "successUrl": "https://orbit.devotel.io/billing?topup=ok",
  "cancelUrl": "https://orbit.devotel.io/billing?topup=cancelled"
}),
})
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": 10000,
  "currency": "usd",
  "successUrl": "https://orbit.devotel.io/billing?topup=ok",
  "cancelUrl": "https://orbit.devotel.io/billing?topup=cancelled"
})
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": 10000,
  "currency": "usd",
  "successUrl": "https://orbit.devotel.io/billing?topup=ok",
  "cancelUrl": "https://orbit.devotel.io/billing?topup=cancelled"
}`)))
	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": 10000,
  "currency": "usd",
  "successUrl": "https://orbit.devotel.io/billing?topup=ok",
  "cancelUrl": "https://orbit.devotel.io/billing?topup=cancelled"
}.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": 10000,
  "currency": "usd",
  "successUrl": "https://orbit.devotel.io/billing?topup=ok",
  "cancelUrl": "https://orbit.devotel.io/billing?topup=cancelled"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_live_abc123..."
  },
  "meta": {
    "request_id": "req_topup_001",
    "timestamp": "2026-05-16T12:00:00Z"
  }
}

Configure Auto-Top-Up

PUT /api/v1/billing/auto-topup Keep the wallet funded automatically: when the balance falls below a threshold you set, Orbit charges the org’s saved off-session payment method to lift it back above the trigger — no manual recharge needed. Read the current config with GET /api/v1/billing/auto-topup and disable it with DELETE /api/v1/billing/auto-topup.

The enabled, threshold_minor, and recharge_amount_minor parameters — plus a full request example — are documented in the Billing API reference.

List Transactions

GET /api/v1/billing/transactions?limit=30 Cursor-paginated read of public.credit_transactions. Negative amount_minor values are spends; positive values are top-ups and refunds.

cURL

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

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/billing/transactions?limit=30', {
  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/transactions?limit=30", 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/transactions?limit=30", 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/transactions?limit=30')
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/transactions?limit=30');
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": {
    "transactions": [
      {
        "id": "ct_2vXq7p9yzAbCdEf",
        "type": "credit_purchase",
        "amount_minor": 10000,
        "reference": "stripe_session:cs_live_abc123",
        "metadata": { "currency": "usd", "fx_rate": 1.0 },
        "created_at": "2026-05-16T11:22:33.444Z",
        "expires_at": null,
        "refunded_at": null
      },
      {
        "id": "ct_2vXq7p9yzAbCdEe",
        "type": "debit",
        "amount_minor": -42,
        "reference": "charge:sms_msg_01J9KP3R5W8YEQ4DXG6N7H2VKZ",
        "metadata": { "channel": "sms", "country": "1" },
        "created_at": "2026-05-16T11:21:18.901Z",
        "expires_at": null,
        "refunded_at": null
      }
    ],
    "next_cursor": {
      "cursor_ts": "2026-05-16T11:21:18.901Z",
      "cursor_id": "ct_2vXq7p9yzAbCdEe"
    },
    "has_more": true
  },
  "meta": {
    "request_id": "req_tx_001",
    "timestamp": "2026-05-16T12:00:00Z"
  }
}

Get Per-Channel Usage

GET /api/v1/billing/usage-by-channel?days=30 Per-channel spend + volume breakdown sourced from credit_transactions. Powers the dashboard usage card.

cURL

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

Node.js

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

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?days=30', {
  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/usage-by-channel?days=30", 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/usage-by-channel?days=30", 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/usage-by-channel?days=30')
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/usage-by-channel?days=30');
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": [
    {
      "key": "sms",
      "channel": "sms",
      "total_messages": 3420,
      "delivered": 3380,
      "failed": 12,
      "total_cost_minor": 27360,
      "total_cost": 273.6000
    },
    {
      "key": "voice",
      "channel": "voice",
      "total_messages": 84,
      "delivered": 78,
      "failed": 6,
      "total_cost_minor": 11280,
      "total_cost": 112.8000
    }
  ],
  "meta": {
    "request_id": "req_usage_001",
    "timestamp": "2026-05-16T12:00:00Z"
  }
}

Get Budget Cap

GET /api/v1/billing/budget-cap Returns the organization’s monthly budget cap (when configured), the current calendar-month period boundaries in UTC, and month-to-date spend — so you can warn a user before an action pushes spend past the cap. All monetary fields are in minor units (cents).

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

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 (
	"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": {
    "cap_cents": 500000,
    "period_start": "2026-07-01T00:00:00.000Z",
    "period_end": "2026-08-01T00:00:00.000Z",
    "current_spend_cents": 128450
  },
  "meta": {
    "request_id": "req_budget_cap_001",
    "timestamp": "2026-07-03T12:00:00Z"
  }
}

cap_cents is null when no monthly cap is configured. period_end is exclusive (the first instant of next month).

Detect Spend Anomalies

GET /api/v1/billing/spend-anomaly Flags channels whose current spend velocity has surged past the organization’s trailing baseline — catching a compromised account before the hard daily caps are exhausted. All monetary fields are in minor units (cents).

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

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())

Python

import os, requests

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

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/billing/spend-anomaly", 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/spend-anomaly')
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/spend-anomaly');
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": {
    "anomalies": [
      {
        "channel": "sms",
        "baseline_daily_minor": 4200,
        "today_spend_minor": 96000,
        "projected_daily_minor": 288000,
        "surge_ratio": 68.6,
        "severity": "critical"
      }
    ],
    "detected": true,
    "baseline_days": 14,
    "surge_multiplier": 10,
    "min_projected_daily_minor": 25000,
    "day_fraction_elapsed": 0.333
  },
  "meta": {
    "request_id": "req_spend_anomaly_001",
    "timestamp": "2026-07-03T08:00:00Z"
  }
}

surge_ratio is projected_daily_minor ÷ baseline_daily_minor, or null for a channel with no prior spend (a cold-start surge). severity is high or critical. See the full Billing API reference for every field.

List Invoices

GET /api/v1/billing/invoices Retrieve the org’s invoices, newest first. Results are cursor-paginated.

string

Filter by lifecycle status. One of draft, issued, paid, void, synced.

string

Opaque pagination cursor. Pass the next_cursor value from the previous page to fetch the next one.

integer

default:"25"

Maximum number of invoices to return. Minimum 1, maximum 100.

cURL

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

Node.js

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

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": {
    "invoices": [
      {
        "id": "kix7Gsf7nYNitX4",
        "invoice_number": "INV-2026-003",
        "status": "paid",
        "currency": "USD",
        "amount_due": "0.00",
        "total": "100.00",
        "subtotal": "100.00",
        "invoice_date": "2026-05-16T11:22:33Z",
        "due_date": "2026-05-31T23:59:59Z",
        "period_start": "2026-05-01T00:00:00Z",
        "period_end": "2026-05-31T23:59:59Z",
        "hosted_invoice_url": "https://my.withorb.com/view/kix7Gsf7nYNitX4",
        "invoice_pdf": "https://my.withorb.com/invoices/kix7Gsf7nYNitX4.pdf",
        "issued_at": "2026-05-16T11:22:33Z",
        "paid_at": "2026-05-16T12:00:00Z"
      }
    ],
    "has_more": true,
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0xNiJ9"
  },
  "meta": {
    "request_id": "req_inv_001",
    "timestamp": "2026-05-16T12:00:00Z"
  }
}

Monetary fields (amount_due, total, subtotal) are decimal strings in the major currency unit (e.g. "100.00" is $100.00) — no division required. next_cursor is null and has_more is false on the final page.

Refunds (owner only)

POST /api/v1/billing/refunds Issue a Stripe refund against a specific top-up credit_transaction lot, within 30 days of the original purchase. GET /api/v1/billing/refunds lists the org’s refund history. Both endpoints are restricted to the org owner role — unexpected refunds against a prepaid wallet are high-impact and hard to reverse.

See Refunds in the full Billing API reference for the complete description.

API Reference

All Endpoints

Billing API

Billing API

Get Wallet Balance

Create Top-Up Session

Configure Auto-Top-Up

List Transactions

Get Per-Channel Usage

Get Budget Cap

Detect Spend Anomalies

List Invoices

Refunds (owner only)

​Billing API

​Get Wallet Balance

​Create Top-Up Session

​Configure Auto-Top-Up

​List Transactions

​Get Per-Channel Usage

​Get Budget Cap

​Detect Spend Anomalies

​List Invoices

​Refunds (owner only)

Billing API

Get Wallet Balance

Create Top-Up Session

Configure Auto-Top-Up

List Transactions

Get Per-Channel Usage

Get Budget Cap

Detect Spend Anomalies

List Invoices

Refunds (owner only)