Balance and billing · Ready Docs

#Balance and billing

For your balance and rates in code, use GET /v1/account.

Details

The /billing endpoints power the dashboard: they aren't versioned, and fields not listed here can change.

How a text is priced

Cost of one text = segments × (sms_rate_usd_per_segment + carrier_fee_usd_per_segment + compliance_per_segment).

Details

sms_rate_usd_per_segment and carrier_fee_usd_per_segment come from GET /v1/account. Typical rates are 0.05 before your campaign is submitted and 0.02 after, or your negotiated rate.
compliance_per_segment is $0.005 for number validation (on by default), plus $0.005 if TCPA scrubbing is on. Read it from GET /billing/balance.
A text with an image is one flat MMS charge, whatever its length: $0.0625 by default, or your negotiated rate, plus the compliance charge once. GET /billing/balance returns it as mms_cost_per_message.
Replies you receive are billed too, the same way as texts you send: segments × (sms_rate + carrier_fee).

Example: a 2-segment text at $0.02 with validation on costs 2 × (0.02 + 0.0045 + 0.005) = $0.059.

#Get balance and rates

GET/v1/account

Your balance and the exact rates you're billed at, including any negotiated rate.

Cost Free

Returns

data.balance_usdnumber: Your balance, rounded to cents. Use balance_cents for exact math.
data.balance_centsinteger: Your balance in cents.
data.sms_rate_usd_per_segmentnumber: Your per-segment rate.
data.carrier_fee_usd_per_segmentnumber: The carrier fee per segment.
data.plannull: A legacy field. Don't rely on it: pricing is pay as you go from your balance.

Errors

HTTP	Code	When
500	`internal_error`	Read failed. Retry.

GET /v1/account

curl "https://api.tryready.com/v1/account" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/account', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/account",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": {
    "balance_usd": 481.25,
    "balance_cents": 48125,
    "plan": null,
    "sms_rate_usd_per_segment": 0.02,
    "carrier_fee_usd_per_segment": 0.0045
  }
}

Billing

#Get balance details

GET/billing/balance

Your balance, prices and usage, as the dashboard shows them.

Cost Free

Important. balance and estimated_segments are a count of 1-segment texts your balance buys, not money. Your money balance is balance_usd.

Returns

data.balance_usd, balance_centsnumber, integer: Your balance. Read live.
data.rate, carrier_fee_per_segment, compliance_per_segmentnumber: Your per-segment prices in USD.
data.mms_cost_per_messagenumber: Your price for a text with an image.
data.number_price_centsinteger: Monthly price per number.
data.monthly_spendnumber: USD spent this calendar month.
data.monthly_messagesinteger: Texts sent in the last 30 days (not this calendar month).
data.daily_avg_send, estimated_days_leftnumber: Forecast. Usage and forecast fields can lag by up to a minute.

Errors

HTTP	Code	When
500	no code	The balance couldn't be loaded. Retry.

GET /billing/balance

curl "https://api.tryready.com/billing/balance" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/billing/balance', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/billing/balance",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": {
    "balance": 6070,
    "balance_usd": 57.67,
    "estimated_segments": 6070,
    "balance_cents": 5767,
    "rate": 0.005,
    "carrier_fee_per_segment": 0.0045,
    "compliance_per_segment": 0,
    "mms_cost_per_message": 0.0625,
    "number_price_cents": 500,
    "daily_avg_send": 17,
    "estimated_days_left": 357,
    "monthly_spend": 0,
    "monthly_messages": 514,
    "…": "…"
  }
}

#List billing history

GET/billing/transactions

Top-ups, credits, refunds and card charges one by one, and usage summed per day.

Auth API key with view_billing
Cost Free

Query parameters

from, toYYYY-MM-DDOptional: UTC dates, inclusive.
Details
Without from you get the last 90 days. Any other format is ignored, not rejected: check summary.from and summary.to to confirm your filter applied.
limitintegerOptionalDefault 20Max 200: Page size.
Details
Negative or non-numeric values fall back to 20, but 0 returns an empty page.
offsetintegerOptionalDefault 0: Rows to skip.

Returns

data[]object[]: Rows: row_type, id, type, cost_usd, description, created_at.
Details
row_type is transaction, daily_usage or stripe_charge. id is a string or an integer: treat it as an opaque string. Usage rows carry the end of their day in created_at.
data[].cost_usdnumber: Always positive, whether money came in or went out. Use type for the direction (table below).
Details
Ignore amount: it's a legacy count, not money.
totalinteger: Rows in the range.
summaryobject: spend_usd (money charged to your card in the range), count, from, to.

Details

Direction	`type`
Into your balance	`purchase`, `auto_rebill`, `carrier_auto_rebill`, `carrier_deposit`, `bonus`, `credit`, `survey_completion_credit`, `onboarding_welcome_credit`, `admin_grant`, `card_verification_credit`, `refund`
Out of your balance	`daily_sms`, `daily_inbound`, `daily_other` and other `daily_*`, `campaign_hold`, `tcpa_scrub_fee`, `data_purchase`, `fine`, `admin_deduction`
Card charge that doesn't touch the balance	`stripe_charge` (for example a brand registration)

Usage isn't itemized per text: it's one row per day per category.

Details

For per-message cost, use cost_usd on GET /v1/messages. At most the 200 newest top-up and credit rows are returned per range, so narrow from and to to see older ones. Results can lag up to 30 seconds.

Errors

HTTP	Code	When
403	`permission_denied`	The key's user lacks `view_billing`.
503	`permission_check_unavailable`	The permission check couldn't run. Retry.
500	no code	Transactions couldn't be loaded. Retry.

GET /billing/transactions

curl "https://api.tryready.com/billing/transactions?from=2026-09-01&to=2026-09-30&limit=200" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/billing/transactions?from=2026-09-01&to=2026-09-30&limit=200', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/billing/transactions",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    params={
        "from": "2026-09-01",
        "to": "2026-09-30",
        "limit": 200
    },
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": [
    {
      "row_type": "daily_usage",
      "id": "sms-2026-09-30",
      "type": "daily_sms",
      "amount": -16,
      "cost_usd": 0.39,
      "description": "SMS: 16 messages",
      "created_at": "2026-09-30T23:59:59.000Z"
    },
    {
      "row_type": "stripe_charge",
      "id": "stripe-ch_3Q7xYz…",
      "type": "stripe_charge",
      "cost_usd": 30,
      "description": "Brand Registration: Acme Dental LLC",
      "created_at": "2026-09-12T15:03:22.410Z"
    },
    {
      "row_type": "transaction",
      "id": 24892412,
      "type": "bonus",
      "amount": 0,
      "cost_usd": 10,
      "description": "Admin added $10.00 balance",
      "created_at": "2026-09-02T18:44:09.871Z"
    }
  ],
  "total": 3,
  "summary": {
    "spend_usd": 30,
    "count": 3,
    "from": "2026-09-01",
    "to": "2026-09-30"
  }
}