API reference

Billing

Read the prepaid balance, the per-message prices and usage.

Retrieve the balance#

GET/v1/balanceScopebilling:read

Returns the wallet balance and the active message packages. The balance belongs to the account, so live and test keys return the same values.

Responses

200
The balance. Balance object.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/balance

curl https://api.omnimessage.co/v1/balance \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "object": "balance",
  "currency": "USD",
  "wallet_micros": 48250000,
  "packages": [
    {
      "id": "grant_5tGh2Kp9LmQ4xW7nB1cD",
      "name": "100K messages",
      "quota": 100000,
      "remaining": 81234,
      "channel_types": null,
      "expires_at": "2027-10-05T00:00:00.000Z"
    }
  ],
  "credits_remaining": 81234
}

Retrieve pricing#

GET/v1/pricingScopebilling:read

Returns the effective price of one outbound message per channel type for this account, in micro-USD. This is the amount debited from the wallet when no package credit applies.

Responses

200
Per-message prices. Pricing object.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/pricing

curl https://api.omnimessage.co/v1/pricing \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "object": "pricing",
  "currency": "USD",
  "data": [
    {
      "channel_type": "whatsapp",
      "unit_price_micros": 1000
    },
    {
      "channel_type": "telegram",
      "unit_price_micros": 300
    },
    {
      "channel_type": "sms",
      "unit_price_micros": 500
    },
    {
      "channel_type": "sms_otp",
      "unit_price_micros": 500
    },
    {
      "channel_type": "messenger",
      "unit_price_micros": 500
    },
    {
      "channel_type": "instagram",
      "unit_price_micros": 500
    },
    {
      "channel_type": "tiktok",
      "unit_price_micros": 500
    }
  ]
}

Retrieve usage#

GET/v1/usageScopebilling:read

Returns outbound message counts and spend for a date range, for the key mode. With group_by=day there is one row per UTC day and channel type; with group_by=channel_type there is one row per channel type for the whole range (period is null). Days and channel types without usage have no row. totals holds the sums over the whole range. The range may span at most 366 days.

Query parameters

fromdateOptional
First day of the range, YYYY-MM-DD (UTC, inclusive). Defaults to 29 days before to, so that the default range is the last 30 days.
todateOptional
Last day of the range, YYYY-MM-DD (UTC, inclusive). Defaults to today.
group_bystringOptional
How rows are grouped. Default day.
Possible valuesdaychannel_type

Responses

200
Usage for the range. Usage object.
400
Bad request.
parameter_invalid
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/usage

curl "https://api.omnimessage.co/v1/usage?from=2026-10-01&to=2026-10-05&group_by=day" \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "object": "usage",
  "from": "2026-10-01",
  "to": "2026-10-05",
  "group_by": "day",
  "data": [
    {
      "period": "2026-10-01",
      "channel_type": "whatsapp",
      "messages": 1200,
      "package_credits": 1000,
      "wallet_micros": 200000,
      "failed": 12,
      "refunded_micros": 2000
    },
    {
      "period": "2026-10-01",
      "channel_type": "telegram",
      "messages": 310,
      "package_credits": 310,
      "wallet_micros": 0,
      "failed": 0,
      "refunded_micros": 0
    },
    {
      "period": "2026-10-02",
      "channel_type": "whatsapp",
      "messages": 980,
      "package_credits": 980,
      "wallet_micros": 0,
      "failed": 4,
      "refunded_micros": 0
    }
  ],
  "totals": {
    "messages": 2490,
    "package_credits": 2290,
    "wallet_micros": 200000,
    "failed": 16,
    "refunded_micros": 2000
  }
}