Billing & Credits

HMS Sovereign uses a credits-based billing system. You purchase credits upfront and they are consumed as you make and receive calls.

Pricing

By default an assistant runs on HMS Sovereign's platform keys — every supported provider works out of the box, with no API keys required. What you pay depends on which mode you run an assistant in:

1 credit = €0,07 (one minute of orchestration).

How Credits Work

1. Purchase credits - Add credits to your account via the dashboard
2. Use credits - Credits are consumed based on call duration
3. Track usage - Monitor your balance and usage in real-time

Credit Balance

Check your current balance via the API:

curl https://api.hmsovereign.com/api/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "id": "org-uuid",
  "company_name": "Your Company",
  "minutes_balance": 500,
  "monthly_usage_minutes": 120
}

Usage Tracking

View detailed usage logs:

curl "https://api.hmsovereign.com/api/v1/usage?start_date=2025-12-01&end_date=2025-12-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "usage": [
    {
      "id": "usage-uuid",
      "duration_sec": 84,
      "created_at": "2025-12-13T10:00:00.000Z",
      "number_id": "number-uuid"
    }
  ],
  "summary": {
    "total_seconds": 7200,
    "total_minutes": 120,
    "total_cost": 8.40
  }
}

Insufficient Credits

When your balance reaches zero:

Inbound calls: An error audio message is played to the caller and the call is logged as status: rejected.

Outbound calls: The API returns 402 Payment Required:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits to make outbound call. Please add credits in your billing dashboard."
  }
}

Adding Credits

Credits can be added through the dashboard:

1. Navigate to Settings > Billing
2. Click Add Credits
3. Select the amount
4. Complete payment

Payment methods accepted:

• Credit card (Visa, Mastercard, American Express)

Invoices

All credit purchases generate an invoice with:

• Invoice number
• Purchase amount
• VAT (if applicable, based on your location)
• PDF download

Access invoices in Settings > Billing > Invoices.

Tax Information

For EU businesses:

• If you provide a valid VAT ID, reverse charge applies (0% VAT)
• Without VAT ID, destination country VAT rate applies

To add billing information:

1. Go to Settings > Billing
2. Add your company name, address, and VAT ID
3. Information is synced to Stripe for invoice generation

Low Balance Notifications

Set up a webhook to monitor your balance and receive alerts:

// Check balance after each call via end-of-call-report webhook
app.post('/webhook', async (req, res) => {
  const account = await fetch('https://api.hmsovereign.com/api/v1/account', {
    headers: { 'Authorization': 'Bearer ' + API_KEY }
  }).then(r => r.json());
  
  if (account.minutes_balance < 100) {
    await sendAlert(`Low balance warning: ${account.minutes_balance} minutes remaining`);
  }
  
  res.status(200).send('OK');
});

Choosing a Pricing Mode

Every mode charges the same €0,07/min orchestration fee. The difference is who bills you for model usage:

• Platform keys (default). You don't manage any provider keys. Model usage is billed at cost through HMS Sovereign on top of the €0,07/min orchestration fee. This is what a new assistant uses out of the box.
• Vertex AI Live. A single all-in rate of €0,25/min for Google Gemini realtime, with nothing else to configure.
• Bring Your Own Key (optional). You supply your own provider keys, so your provider bills you directly for their usage and HMS Sovereign only charges the €0,07/min orchestration fee. Use this when you want full control over provider costs or want to use your own provider plan, features, and models. BYOK is never required.
• Local models (Whisper, Piper). Self-hosted models run free of model-usage charges; you pay only the €0,07/min orchestration fee.

Related

• Usage API
• Account API
• BYOK Setup