Skip to content
DashboardGet API key

Get balance

View .md
GET

Get balance for the API key's team. If the API key belongs to a sub-account, also includes the sub-account's total spending and credit limit. Also reports the team's app-message allowance, whether it is paused and why, pay as you go and the spend cap, and how many incoming messages are held: the way to learn that customers are writing without sending anything.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Responses

200Balance details.
  • balanceintegerrequired

    Team balance in cents. All charges are billed to the parent team.

  • currencystringrequired
  • creditLimitintegernullable

    Spending cap in cents (only for sub-accounts).

  • totalSpentintegernullable

    Total amount spent by this sub-account in cents (only for sub-accounts).

  • isSubAccountboolean

    Whether this API key belongs to a sub-account.

  • payAsYouGobooleanrequired

    Whether the team is on Free and has added funds, so app messages past the allowance are billed in blocks from the balance instead of stopping.

  • spendCapintegerrequirednullable

    The monthly usage spend cap in cents, set in the dashboard's Billing. Null means no cap. The first deposit on Free sets $50 when none was chosen.

  • spentThisMonthintegerrequired

    Usage taken from the balance this calendar month (UTC), in cents: what the spend cap is measured against. Renewals are not counted.

  • appMessagesobjectrequired

    This month's WhatsApp, Telegram, Instagram and Messenger messages, sent and received.

    3 properties
    • usedintegerrequired

      Messages counted this month, in both directions.

    • includedintegerrequirednullable

      Messages the plan includes this month. Null on a paid plan, which does not cap them.

    • pausedstringrequirednullable

      Why app messages are stopped right now, or null. allowance: Free without funds at its allowance. balance: pay as you go and the balance cannot cover the next block. spend_cap: pay as you go and the spend cap leaves no room for it. While paused, sends answer 429 a2p_limit_exceeded and incoming messages are held.

      One ofallowancebalancespend_cap
  • heldInboundobjectrequirednullable

    Incoming messages held at the allowance, or null when none are. Counts and a date only, never content or senders. They are delivered once the team pays; see POST /v1/messages.

    3 properties
    • countintegerrequired
    • maxintegerrequired

      How many the team can have held at once (1,000). Past it new ones are refused.

    • nextExpiresAtstring<date-time>requirednullable

      When the oldest held message expires and is dropped.

401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject