Skip to main content

​
Billing API

Access your subscription plan, track real-time usage, initiate plan changes, and download invoices. Powered by Stripe for payments and Orb for usage metering. Base path: /v1/billing

​
List Plans

GET /v1/billing/plans Retrieve all available pricing plans. 
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,
        "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,
        "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",
        "support": "dedicated"
      }
    }
  ],
  "meta": {
    "request_id": "req_plans_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

​
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 the Stripe-hosted payment page.
​
priceId
string
required
Stripe price ID of the target plan (from the plans list)
​
successUrl
string
required
URL to redirect to after successful payment
​
cancelUrl
string
required
URL to redirect to 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"
  }
}

​
Get Current Usage

GET /v1/billing/usage Retrieve your current billing period usage metrics from Orb. Includes per-channel message counts, voice minutes, and agent invocations. 
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"
  }
}

​
List Invoices

GET /v1/billing/invoices Retrieve past invoices for your organization 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"
    },
    {
      "id": "inv_def456",
      "number": "INV-2026-002",
      "amount": 19900,
      "currency": "usd",
      "status": "paid",
      "period_start": "2026-01-01T00:00:00Z",
      "period_end": "2026-01-31T23:59:59Z",
      "pdf_url": "https://pay.stripe.com/invoice/acct_xxx/inv_def456/pdf",
      "created_at": "2026-02-01T00:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_inv_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}
Invoice amounts are in the smallest currency unit (e.g., cents for USD). Divide by 100 for display.