Usage Charges

Usage charges let you bill merchants based on actual consumption. The charge amount is calculated as quantity * unit_price, making it ideal for metered billing models.

Create a Usage Charge

POST /api/apps/v1/billing/usage-charges
Authorization: Bearer sx_at_...
Content-Type: application/json
 
{
  "description": "SMS sent to +8801712345678",
  "quantity": 1,
  "unit_price": 2.50,
  "metadata": { "sms_id": "msg-123", "recipient": "+8801712345678" }
}

Parameters:

Field	Type	Required	Description
`description`	string	Yes	Human-readable description of what was consumed
`quantity`	number	Yes	Number of units consumed
`unit_price`	number	Yes	Price per unit in BDT
`metadata`	object	No	Arbitrary key-value data for your records

Response:

{
  "usage_charge_id": 12,
  "description": "SMS sent to +8801712345678",
  "quantity": 1,
  "unit_price": 2.50,
  "amount": 2.50,
  "currency": "BDT",
  "platform_amount": 0.25,
  "developer_amount": 2.25,
  "status": "pending",
  "created_at": "2026-02-28T10:30:00.000Z"
}

Amount Calculation

Usage charges are always developer-pays with no gateway fee (they are direct platform debits, not EPS-processed payments). Only the 10% platform commission applies:

amount           = quantity * unit_price
platform_amount  = amount * 0.10
developer_amount = amount - platform_amount

Example:

quantity = 5, unit_price = 2.50
amount           = 5 * 2.50 = 12.50 BDT
platform_amount  = 12.50 * 0.10 = 1.25 BDT
developer_amount = 12.50 - 1.25 = 11.25 BDT

List Usage Charges

Retrieve usage charges for the current store with pagination:

GET /api/apps/v1/billing/usage-charges?page=1&limit=20
Authorization: Bearer sx_at_...

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Results per page (max 100)

Response:

{
  "data": [
    {
      "usage_charge_id": 12,
      "description": "SMS sent to +8801712345678",
      "quantity": 1,
      "unit_price": 2.50,
      "amount": 2.50,
      "status": "pending",
      "created_at": "2026-02-28T10:30:00.000Z"
    },
    {
      "usage_charge_id": 11,
      "description": "SMS sent to +8801798765432",
      "quantity": 1,
      "unit_price": 2.50,
      "amount": 2.50,
      "status": "pending",
      "created_at": "2026-02-28T10:25:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 47
  }
}

Use Cases

Usage charges work well for any consumption-based billing:

Use Case	Description	Example
Per-SMS billing	Charge for each SMS sent through your app	`quantity: 1, unit_price: 2.50`
Per-API-call billing	Charge for external API calls made on behalf of the merchant	`quantity: 100, unit_price: 0.10`
Storage usage	Charge for file storage consumed	`quantity: 5, unit_price: 10.00` (5 GB)
Per-transaction fees	Charge a fee for each processed transaction	`quantity: 1, unit_price: 5.00`

Usage Charges vs. Wallet

Both usage charges and the wallet system support metered billing, but they work differently:

Feature	Usage Charges	Wallet
Payment timing	Billed after consumption	Pre-paid before consumption
Merchant approval	Required for each billing cycle	Only for top-ups
Real-time deduction	No	Yes
Best for	Periodic billing summaries	High-frequency micro-transactions

When to use usage charges: You want to bill periodically for accumulated usage and are okay with the merchant approving each billing cycle.

When to use the wallet: You need instant deductions (e.g., per-SMS) without waiting for merchant approval each time.

Code Example

Track SMS usage and create charges with a helper function:

const API_URL = "https://api.selorax.io/api/apps/v1/billing";
 
async function recordUsage(token, description, quantity, unitPrice, metadata = {}) {
  const response = await fetch(`${API_URL}/usage-charges`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      description,
      quantity,
      unit_price: unitPrice,
      metadata,
    }),
  });
 
  const result = await response.json();
  if (response.ok) {
    console.log(`Usage recorded: ${result.amount} BDT (dev: ${result.developer_amount})`);
  }
  return result;
}
 
// Record a single SMS
await recordUsage(token, "SMS to +8801712345678", 1, 2.50, { sms_id: "msg-456" });
 
// Batch 50 SMS sends into one charge
await recordUsage(token, "SMS batch - March 2026", 50, 2.50, { batch_id: "batch-789" });

Python Example

import requests
 
def record_usage(token, description, quantity, unit_price, metadata=None):
    response = requests.post(
        "https://api.selorax.io/api/apps/v1/billing/usage-charges",
        headers={"Authorization": f"Bearer {token}"},
        json={
            "description": description,
            "quantity": quantity,
            "unit_price": unit_price,
            "metadata": metadata or {},
        },
    )
    return response.json()
 
result = record_usage(token, "SMS to +8801712345678", 1, 2.50)
print(f"Charged: {result['amount']} BDT")

Best Practices

Include descriptive metadata with each usage charge so both you and the merchant can audit what was consumed.
Batch where possible. If a merchant triggers 50 SMS sends in quick succession, consider batching them into a single usage charge with quantity: 50 rather than creating 50 individual charges.
Use the description field to give merchants clear visibility into what they are being charged for. Vague descriptions lead to disputes.