Skip to main content

​
Billing API

Access subscription plans, create checkout sessions, manage prepaid credits, track real-time usage, and download invoices. Powered by Stripe for payments and Orb for usage metering. Base path: /v1/billing

​
Plans

​
List Plans

GET /v1/billing/plans Retrieve all available pricing plans with feature breakdowns. 
curl https://orbit-api.devotel.io/api/v1/billing/plans \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "plan_starter",
      "name": "Starter",
      "price_id": "price_abc123",
      "price_monthly": 49,
      "currency": "usd",
      "features": {
        "messages_included": 5000,
        "channels": ["sms", "email"],
        "agents": 1,
        "voice_minutes": 100,
        "support": "email"
      }
    },
    {
      "id": "plan_growth",
      "name": "Growth",
      "price_id": "price_def456",
      "price_monthly": 199,
      "currency": "usd",
      "features": {
        "messages_included": 25000,
        "channels": ["sms", "whatsapp", "email", "rcs"],
        "agents": 5,
        "voice_minutes": 500,
        "support": "priority"
      }
    },
    {
      "id": "plan_enterprise",
      "name": "Enterprise",
      "price_id": "price_ghi789",
      "price_monthly": null,
      "currency": "usd",
      "features": {
        "messages_included": "unlimited",
        "channels": ["sms", "whatsapp", "rcs", "viber", "email", "voice"],
        "agents": "unlimited",
        "voice_minutes": "unlimited",
        "support": "dedicated"
      }
    }
  ],
  "meta": {
    "request_id": "req_plans_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

​
Get Current Plan

GET /v1/billing/plan Retrieve your organization’s active subscription details. 
curl https://orbit-api.devotel.io/api/v1/billing/plan \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "plan_id": "plan_growth",
    "name": "Growth",
    "status": "active",
    "current_period_start": "2026-03-01T00:00:00Z",
    "current_period_end": "2026-03-31T23:59:59Z",
    "cancel_at_period_end": false,
    "payment_method": {
      "type": "card",
      "last4": "4242",
      "brand": "visa"
    }
  },
  "meta": {
    "request_id": "req_plan_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

​
Checkout

​
Create Checkout Session

POST /v1/billing/checkout Create a Stripe checkout session for subscribing to or upgrading a plan. Returns a URL to redirect the user to Stripe’s hosted payment page.
​
priceId
string
required
Stripe price ID of the target plan
​
successUrl
string
required
URL to redirect after successful payment
​
cancelUrl
string
required
URL to redirect if the user cancels
curl -X POST https://orbit-api.devotel.io/api/v1/billing/checkout \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "priceId": "price_def456",
    "successUrl": "https://orbit.devotel.io/settings/billing?success=true",
    "cancelUrl": "https://orbit.devotel.io/settings/billing?cancelled=true"
  }'

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

​
Credits

Prepaid credits can be used for pay-as-you-go messaging and voice usage beyond plan limits.

​
Get Credit Balance

GET /v1/billing/credits Retrieve your current prepaid credit balance. 
curl https://orbit-api.devotel.io/api/v1/billing/credits \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "balance": 15000,
    "currency": "usd",
    "auto_reload": {
      "enabled": true,
      "threshold": 5000,
      "amount": 10000
    },
    "last_topped_up_at": "2026-03-01T10:00:00Z"
  },
  "meta": {
    "request_id": "req_credits_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}
Credit amounts are in the smallest currency unit (cents for USD). 15000 = $150.00.

​
Top Up Credits

POST /v1/billing/credits/topup Add prepaid credits to your account. Payment is charged to your default payment method.
​
amount
integer
required
Amount in smallest currency unit (e.g., 10000 = $100.00 USD)
curl -X POST https://orbit-api.devotel.io/api/v1/billing/credits/topup \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 10000 }'

{
  "data": {
    "balance": 25000,
    "topped_up": 10000,
    "currency": "usd",
    "payment_id": "pi_abc123"
  },
  "meta": {
    "request_id": "req_topup_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

​
Configure Auto-Reload

PUT /v1/billing/credits/auto-reload Set up automatic credit top-ups when your balance falls below a threshold.
​
enabled
boolean
required
Enable or disable auto-reload
​
threshold
integer
Balance threshold (in smallest currency unit) that triggers a reload
​
amount
integer
Amount to reload when triggered
curl -X PUT https://orbit-api.devotel.io/api/v1/billing/credits/auto-reload \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "threshold": 5000,
    "amount": 10000
  }'

​
Usage

​
Get Current Usage

GET /v1/billing/usage Retrieve real-time usage metrics for the current billing period from Orb. 
curl https://orbit-api.devotel.io/api/v1/billing/usage \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "billing_period": {
      "start": "2026-03-01T00:00:00Z",
      "end": "2026-03-31T23:59:59Z"
    },
    "messages": {
      "sms": { "sent": 3420, "included": 25000 },
      "whatsapp": { "sent": 1580, "included": 25000 },
      "email": { "sent": 890, "included": 25000 },
      "rcs": { "sent": 120, "included": 25000 },
      "viber": { "sent": 45, "included": 25000 }
    },
    "voice": {
      "minutes_used": 142,
      "minutes_included": 500
    },
    "agents": {
      "invocations": 2340,
      "invocations_included": 10000
    }
  },
  "meta": {
    "request_id": "req_usage_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

​
Get Usage History

GET /v1/billing/usage/history Retrieve usage breakdown by day or month for a date range.
​
start_date
string
required
Start date in ISO 8601 format (e.g., 2026-01-01)
​
end_date
string
required
End date in ISO 8601 format
​
granularity
string
default:"day"
Aggregation: day or month
curl "https://orbit-api.devotel.io/api/v1/billing/usage/history?start_date=2026-03-01&end_date=2026-03-08&granularity=day" \
  -H "X-API-Key: dv_live_sk_your_key_here"

​
Invoices

​
List Invoices

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

{
  "data": [
    {
      "id": "inv_abc123",
      "number": "INV-2026-003",
      "amount": 19900,
      "currency": "usd",
      "status": "paid",
      "period_start": "2026-02-01T00:00:00Z",
      "period_end": "2026-02-28T23:59:59Z",
      "pdf_url": "https://pay.stripe.com/invoice/acct_xxx/inv_abc123/pdf",
      "created_at": "2026-03-01T00:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_inv_001",
    "timestamp": "2026-03-08T12:00:00Z",
    "pagination": {
      "cursor": "cur_inv_abc",
      "has_more": true,
      "total": 12
    }
  }
}
Invoice amounts are in the smallest currency unit (cents for USD). Divide by 100 for display.

​
Examples

​
Node.js

const orbit = new Devotel({ apiKey: 'dv_live_sk_xxxx' })

const usage = await orbit.billing.getUsage()
console.log(usage.data.messages.sms.sent)

const checkout = await orbit.billing.createCheckout({
  priceId: 'price_def456',
  successUrl: 'https://yourapp.com/billing?success=true',
  cancelUrl: 'https://yourapp.com/billing?cancelled=true',
})
// Redirect user to checkout.data.checkoutUrl

​
Python

orbit = OrbitClient(api_key="dv_live_sk_xxxx")

usage = orbit.billing.get_usage()
print(usage.data.messages.sms.sent)

checkout = orbit.billing.create_checkout(
    price_id="price_def456",
    success_url="https://yourapp.com/billing?success=true",
    cancel_url="https://yourapp.com/billing?cancelled=true",
)
# Redirect user to checkout.data.checkout_url