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

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');
});

BYOK Cost Considerations

When using BYOK (Bring Your Own Key):

• You pay HMS Sovereign €0.07/minute for platform usage
• You pay providers directly for their API usage
• Provider costs vary based on your plan and usage

This gives you:

• Full control over provider costs
• Access to your provider's features and models
• Separate billing for transparency

Related

• Usage API
• Account API
• BYOK Setup