Billing and Yanola Balance

Plan and Balance are separate

A Plan is the optional Developer Platform subscription of a Yanola Account: it grants API keys, webhooks, and API and SDK sends under a monthly Message Cap. Yanola Balance is prepaid USD that pays for SaaS usage across the account: workflows, scheduled sends, AI actions, functions, and storage. Paying for one does not fund or activate the other.

Without a Plan there is no API access, while the SaaS stays usable on the Yanola Balance. API and SDK sends never spend from the Balance, and workflow or scheduler sends never count against the Message Cap.

Read the account-level Balance

Yanola Balance is shared across every Agent Project in the Yanola Account. The dashboard shows USD values for the amount currently available, lifetime purchased, lifetime used, promotional balance, and the configured low-balance and auto-top-up state.

availableAmount is the stored Balance minus any active holds. API and SDK sends create no hold.

How a Live Mode API send is recorded

A Live Mode API or SDK send is included in the Plan: it carries no Yanola fee and no Meta Fee, and it counts against the monthly Message Cap. Its usage record is finalized when the send is accepted, with totalAmount 0.000000 and nothing deducted from Yanola Balance.

Meta bills your WhatsApp Business Account directly for the messages it charges for. That amount is not stored on the usage record, so providerAmount and yanolaFee are null on an included send.

{
  "status": "finalized",
  "currency": "USD",
  "estimatedAmount": "0.000000",
  "providerAmount": null,
  "yanolaFee": null,
  "totalAmount": "0.000000"
}

GA pricing source and webhook billing

An API or SDK send within the Message Cap costs nothing beyond the Plan: totalAmount is 0.000000. The account Billing view and accepted subscription offer are authoritative for the current plan name, subscription price, Message Cap, and entitlement quantities; these commercial values are intentionally not REST or SDK constants.

A pricing or entitlement configuration change does not rewrite an existing usage record. Test Mode sends and inbound webhook processing do not consume Balance, and webhook deliveries are not separately billed in v1.

Live Mode billing lifecycle

Yanola performs the subscription, entitlement, Sender, and Message Cap checks before a send is queued, then creates its usage record at zero. A 202 response means the message was accepted, not that it was delivered. At the Message Cap a new send returns 402 plan_message_limit_reached, except replies inside the 24-hour Customer Service Window.

1. Persist the accepted message ID and request ID.
2. Observe message delivery state through retrieval, logs, or signed webhooks.
3. Use client.usage.list(...) to correlate messageId with its usage record.
4. Track accepted sends against the Message Cap in the dashboard; they do not spend Yanola Balance.

Failed-message handling

A failed API or SDK send never spends Yanola Balance. Whatever Meta reports, its usage record stays at 0.000000. Meta decides on its own whether to bill your WhatsApp Business Account.

Low and depleted Balance behavior

The Balance governs SaaS usage; API and SDK sends are never blocked by it. A low-balance warning is advisory: Balance-funded activity can still proceed when its cost fits within availableAmount, and it is blocked when it does not, even if the displayed Balance is above zero.

Handle insufficient_balance

API and SDK sends never return this code: at the Message Cap they return 402 plan_message_limit_reached. A public API action billed from the Balance that cannot be covered returns a non-retryable 402 billing_error. Log the request ID and structured details, top up the account, then retry the logical operation with the same application-owned idempotency key when applicable.

1. Do not retry in a tight loop while the Balance is unchanged.
2. Compare requiredAmount with availableAmount to choose an adequate top-up.
3. Complete the Balance purchase and wait for the dashboard to show the added funds.
4. Retry safely; do not create a new business operation merely because billing blocked the first attempt.

{
  "error": {
    "type": "billing_error",
    "code": "insufficient_balance",
    "message": "Yanola Balance is too low for this Live Mode usage reservation.",
    "requestId": "req_...",
    "retryable": false,
    "details": {
      "action": "top_up_balance",
      "availableAmount": "0.100000",
      "requiredAmount": "0.200000",
      "currency": "USD"
    }
  }
}

Top up Yanola Balance

Open the account Billing page or an Agent Project's Billing view and choose Top up balance. The current dashboard accepts a preset or custom amount from $10 through $10,000 and shows the amount paid, any promotional balance, Balance added, and Stripe-calculated tax before checkout.

A top-up is a one-time Stripe payment. Yanola adds the purchased and promotional USD value only after successful payment completion is received and applies repeated completion events at most once. Cancelled, failed, or merely opened checkout sessions do not add Balance.

1. Choose an amount that covers the blocked action plus expected near-term usage.
2. Review the estimate; tax is calculated during Stripe Checkout.
3. Optionally enable auto top-up so the payment method can be saved for future off-session charges.
4. Complete Stripe Checkout and return to Billing.
5. Confirm availableAmount reflects the completed purchase before retrying blocked Live Mode work.

Auto top-up behavior

Enable auto top-up during a manual Balance purchase. After that payment completes, Yanola stores the purchased amount as the automatic top-up amount and can charge the saved payment method off-session when available Balance reaches the configured trigger, currently 0.000000 USD.

Clearing the option during a later completed top-up turns auto top-up off. If an automatic payment fails, no Balance is added; update the payment method or complete a manual top-up before retrying blocked usage.

Reconcile and report usage

Use the account Billing views for the current Balance, purchases, adjustments, and invoices. Use the public usage API for per-message Developer Platform records; it is not a Balance ledger or subscription API.

1. Group records by providerCategory and market when reviewing API volume; Meta invoices for your WhatsApp Business Account stay the source for Meta Fees.
2. Expect totalAmount 0.000000 on included API and SDK sends.
3. Keep any reserved or needs_reconciliation record visible as unsettled activity.
4. Correlate billing questions with usage ID, message ID, and request ID.

import { WhatsAppClient } from "@yanola/whatsapp"

const apiKey = process.env.YANOLA_API_KEY

if (!apiKey) {
  throw new Error("Missing YANOLA_API_KEY")
}

const yanola = new WhatsAppClient({ apiKey })

const [settled, unresolved] = await Promise.all([
  yanola.usage.list({ status: "finalized", limit: 100 }),
  yanola.usage.list({ status: "needs_reconciliation", limit: 100 }),
])

console.log({
  settled: settled.data.map(({ messageId, totalAmount }) => ({
    messageId,
    totalAmount,
  })),
  unresolvedMessageIds: unresolved.data.map(({ messageId }) => messageId),
})