V1
API v1•Balance & Ledger

Balance & Ledger

Inspect your organization's active token balance, upcoming bucket expirations, and cursor-paginated transaction ledger directly over the API.

Overview

Tokens on Emess are held in FIFO Token Buckets belonging to your billing organization. When SMS messages or verifications are sent, tokens are deducted from the active bucket with the earliest expiration date (expiresAt ASC NULLS LAST).

GET/api/v1/balance

Returns the sum of remaining tokens across all ACTIVE buckets (with remaining > 0) for the billable organization, along with the earliest expiring bucket. Exhausted and expired buckets are excluded.

Response (200 OK)

GET /api/v1/balance
{
  "organizationId": "org_uuid",
  "totalTokens": 1250,
  "activeBuckets": 2,
  "nextExpiry": {
    "expiresAt": "2026-11-20T00:00:00.000Z",
    "tokens": 400
  },
  "buckets": [
    {
      "id": "bucket_uuid_1",
      "remaining": 400,
      "initial": 1000,
      "status": "ACTIVE",
      "expiresAt": "2026-11-20T00:00:00.000Z"
    },
    {
      "id": "bucket_uuid_2",
      "remaining": 850,
      "initial": 1000,
      "status": "ACTIVE",
      "expiresAt": null
    }
  ]
}

If the organization has no active buckets, totalTokens is 0, nextExpiry is null, and buckets is [].

GET/api/v1/ledger

Returns a cursor-paginated list of token ledger entries for your organization, ordered newest first (createdAt desc, id desc).

Query Parameters

ParameterTypeDescription
typestringSingle LedgerType or comma-separated list (e.g. USAGE_DEBIT,USAGE_REFUND). Invalid values return 422 VALIDATION_ERROR.
appIdstringFilter ledger entries originating from a specific application.
batchIdstringFilter ledger entries linked to a specific message batch UUID.
from / toISO 8601Date or datetime bounds (from inclusive, to exclusive).
limit / cursorpaginationPage size (default 25, max 100) and opaque cursor ID from pagination.nextCursor.

Ledger Entry Types

  • PURCHASE_DEPOSIT — One-time token pack purchase credit.
  • SUBSCRIPTION_DEPOSIT — Recurring subscription cycle token credit.
  • USAGE_DEBIT — Token deduction when sending an SMS or batch (negative amount).
  • USAGE_REFUND — Automatic refund when a message fails or expires before dispatch.
  • USAGE_SURCHARGE — Additional usage adjustment.
  • DEFICIT_DEDUCTION — Settlement of a prior negative balance against a new deposit.

Response (200 OK)

GET /api/v1/ledger
{
  "data": [
    {
      "id": "ledger_uuid",
      "type": "USAGE_DEBIT",
      "amount": -2,
      "createdAt": "2026-10-25T14:22:01.000Z",
      "bucketId": "bucket_uuid",
      "messageId": null,
      "batchId": "batch_uuid",
      "appId": "app_uuid"
    }
  ],
  "pagination": {
    "limit": 25,
    "nextCursor": null,
    "hasMore": false
  }
}
TemplatesWebhooks