Billing

GET /v1/billing/balance

Get your organization's current credit balance. The response format depends on your billing type—prepaid or postpaid.

Understanding Billing Types

Verriflo offers two billing models:

Type	How it Works
Prepaid	Buy credits upfront, consume them as you use the platform
Postpaid	Use freely, get billed at the end of each billing cycle (weekly/monthly)

Credits are consumed based on participant-minutes—the total time all participants spend in your classrooms.

Request

Headers

Header	Required	Description
VF-ORG-ID	Yes	Your organization ID

Example Request

curl -X GET https://api.verriflo.com/v1/billing/balance \
  -H "VF-ORG-ID: your-organization-id"

Response: Prepaid

If your organization uses prepaid billing:

{
  "success": true,
  "message": "Balance retrieved successfully",
  "data": {
    "type": "PREPAID",
    "status": "ACTIVE",
    "remainingCredits": 5000,
    "displayCredits": 5000,
    "isOverconsumed": false,
    "creditRate": 0.5,
    "estimatedValue": 2500,
    "currency": "BDT",
    "message": "Account has 5000 credits remaining."
  }
}

Prepaid Response Fields

Field	Type	Description
type	string	Always "PREPAID"
status	string	"ACTIVE" or "OVERCONSUMED"
remainingCredits	number	Credits left (negative if overconsumed)
displayCredits	number	Absolute value for display purposes
isOverconsumed	boolean	Whether account has used more than available
creditRate	number	Cost per credit in the currency
estimatedValue	number	Monetary value of remaining credits
currency	string	Currency code (e.g., "BDT")
message	string	Human-readable status message

Overconsumed State

When a prepaid account runs out of credits:

{
  "success": true,
  "message": "Balance retrieved successfully",
  "data": {
    "type": "PREPAID",
    "status": "OVERCONSUMED",
    "remainingCredits": -250,
    "displayCredits": 250,
    "isOverconsumed": true,
    "creditRate": 0.5,
    "estimatedValue": 125,
    "currency": "BDT",
    "message": "Account has overconsumed 250 credits. Please add more credits."
  }
}

Low Balance

When isOverconsumed is true, new class creation may be blocked. Top up your balance to continue using the platform.

Response: Postpaid

If your organization uses postpaid billing:

{
  "success": true,
  "message": "Balance retrieved successfully",
  "data": {
    "type": "POSTPAID",
    "status": "CONSUMED",
    "billingFrequency": "MONTHLY",
    "cycleStartDate": "2024-01-01T00:00:00.000Z",
    "creditsConsumed": 12500,
    "creditsThisCycle": 12500,
    "creditRate": 0.5,
    "estimatedCost": 6250,
    "currency": "BDT",
    "classroomsThisCycle": 45,
    "message": "12500 credits consumed this monthly cycle."
  }
}

Postpaid Response Fields

Field	Type	Description
type	string	Always "POSTPAID"
status	string	Always "CONSUMED"
billingFrequency	string	"WEEKLY" or "MONTHLY"
cycleStartDate	string	Start of current billing cycle (ISO date)
creditsConsumed	number	Total credits used this cycle
creditsThisCycle	number	Credits consumed in this billing period
creditRate	number	Cost per credit
estimatedCost	number	Projected bill for this cycle
currency	string	Currency code
classroomsThisCycle	number	Number of classes held this cycle
message	string	Human-readable summary

Examples

JavaScript: Balance Widget

async function getBalanceDisplay() {
  const response = await fetch("https://api.verriflo.com/v1/billing/balance", {
    headers: { "VF-ORG-ID": process.env.VERRIFLO_ORG_ID },
  });

  const { data } = await response.json();

  if (data.type === "PREPAID") {
    return {
      label: "Credits Remaining",
      value: data.displayCredits.toLocaleString(),
      warning: data.isOverconsumed,
      action: data.isOverconsumed ? "Top Up Now" : null,
    };
  } else {
    return {
      label: "Credits This Cycle",
      value: data.creditsConsumed.toLocaleString(),
      subtext: `Est. bill: ${
        data.currency
      } ${data.estimatedCost.toLocaleString()}`,
    };
  }
}

Python: Low Balance Alert

import requests
import os

def check_balance_and_alert(threshold: int = 500):
    """Send alert if balance is low."""
    response = requests.get(
        'https://api.verriflo.com/v1/billing/balance',
        headers={'VF-ORG-ID': os.environ['VERRIFLO_ORG_ID']}
    )

    data = response.json()['data']

    if data['type'] == 'PREPAID':
        if data['remainingCredits'] < threshold:
            send_alert(
                f"⚠️ Low balance: {data['remainingCredits']} credits remaining. "
                f"Please top up to avoid service interruption."
            )

Errors

Status	Message	Description
401	Unauthorized	Invalid organization ID
404	Organization not found	Organization doesn't exist

---

Need to top up? Visit the Verriflo Dashboard to add credits to your account.