Skip to main content

Spend Controls

Spend controls protect outbound workflows from exceeding configured limits. When a spend-control check blocks a call, your application should pause the affected workflow and display the returned error.

Billing information in the public MiniVoice API is customer-facing reporting and enforcement data. Your integration can create calls, read call objects, receive lifecycle webhooks, and query /v1/usage for settled totals. It should not depend on internal adjustment or administration workflows.

Real Request​

curl -sS 'https://api.minivoice.eu/v1/usage?from=2026-05-01T00:00:00Z&to=2026-06-01T00:00:00Z' \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY'

Real Response​

{
  "application_id": "app_123",
  "from": "2026-05-01T00:00:00Z",
  "to": "2026-06-01T00:00:00Z",
  "summary": {
    "calls": 42,
    "billsec_seconds": 3600,
    "cost_amount": "12.50",
    "cost_currency": "EUR"
  }
}

Real Webhook Example​

{
  "event": "call.completed",
  "created_at": "2026-05-29T12:10:00Z",
  "call": {
    "id": "call_123",
    "customer_id": "cust_123",
    "application_id": "app_123",
    "status": "completed",
    "direction": "outbound",
    "from": "+15551230001",
    "to": "+15551230002"
  },
  "variables": {},
  "data": {}
}

Common Use Case​

Use billing data to build an account dashboard that shows calls, billed seconds, and cost for a selected UTC time window. For outbound workflows, store the call ID as soon as MiniVoice accepts a call, then reconcile final totals after call.completed and usage settlement.

Common Failure Case​

{
  "error": {
    "code": "spend_control_exceeded",
    "message": "outbound spend limit exceeded"
  }
}

Financial and routing failures should stop the current workflow instead of starting a blind retry loop. Show the error code in your dashboard, keep the original request body for support, and resume only after balance, rating, routing, or limit state has changed.

Implementation pattern

For a campaign, check your own budget before sending calls, create calls one at a time or in controlled batches, and store accepted call IDs. For reporting, use /v1/usage for summary totals and call reads for per-call detail. Treat missing cost fields on in-progress calls as normal until the call has completed and billing has settled.

Dashboard fields

For customer-facing dashboards, keep billing display separate from call control. Show the MiniVoice call ID, direction, destination, final status, billed seconds, cost amount, and currency when those values are available. For summary cards, use the usage endpoint instead of summing only the calls currently visible in the browser. That avoids pagination mistakes and keeps reporting consistent across users.

When an outbound request is rejected before call acceptance, store it as an attempted request with the returned error code. Do not mix rejected attempts into completed-call cost totals. This distinction is especially important for campaigns, where a rejected request should be eligible for later review without looking like a charged call.

Testing​

Run one short successful outbound call, wait for the completed webhook, then query usage for a window that includes the call. Also test the failure case for this page and confirm your integration marks the attempt as rejected, not completed.