--- title: "Billing" description: "The prepaid balance, what a keyword-day and a mention cost, and the wallet and ledger endpoints." canonical: https://docs.mentio.dev/billing markdown: https://docs.mentio.dev/billing.mdx --- # Billing The prepaid balance, what a keyword-day and a mention cost, and the wallet and ledger endpoints. Mentio bills by usage from a prepaid balance: what you track, and what the pipeline actually finds for you. There are no seats, no tiers, no subscription and no packs. You add any amount, and the balance goes down a little every day while keywords are tracked and mentions are found. Money in the API is always integer USD cents (`500` is $5.00). The dashboard does the formatting. ## How it works | Line | Price | How it accrues | | -------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------- | | Keywords | 5 USD per keyword per month | Deducted per day: 5/30 USD per keyword-day. A keyword tracked for 12 days costs 12/30 of the monthly price | | Mentions | 0.008 USD per matched mention | Every mention the pipeline matches to one of your keywords, relevant or not. Keywords bundle no mentions | A mention counts when the pipeline finds a post matching one of your keywords, whether the classifier scores it relevant or filters it as noise. Both numbers are shown in the dashboard, so the balance never disagrees with what you can see in the feed. Mentions the classifier could not score (a `failed` classification) are never charged: an outage on our side costs you nothing. Deductions settle once per UTC day. Between settlements, mentions matched since the last one are priced and shown as `pendingCents`, and the balance the stop rule and the keyword gate look at is `balanceCents - pendingCents`. For a script or an agent, [`GET /v1/usage`](/api/usage/get-usage) answers the money question in one read: the balance (ledger, pending, effective), the daily burn and the days it buys, the keywords running and paused, the matches recorded today and over 30 days, and whether tracking is stopped or the balance is low. The dashboard's own wallet and breakdown routes stay out of the reference. ## The welcome credit Every new workspace starts with $5.80 of free credit: one keyword-month plus 100 mentions. It is granted once per user (a second workspace of the same user gets none), and no card is needed to use it. `GET /v1/billing/wallet` reports it under `signupCredit`. ## Adding funds A card can also be added on its own, without a top-up: **Add a card** under Payment method opens Polar's hosted page, which keeps the card for later top-ups and for auto recharge. The dashboard's **Add funds** button opens a hosted Polar checkout with the amount prefilled ($20 by default); the customer can type any other amount from $20 to $5,000 per top-up. Polar is the merchant of record, so tax is added at checkout, and the balance is credited as soon as the order is paid. The endpoint behind the button is dashboard plumbing and is left out of the reference. Top-ups are non-refundable except where the law requires it; a refund Polar does issue is taken back off the balance. ## Your card There is no separate step to add a card. The first top-up checkout takes the card and the billing address, and Polar keeps them on the workspace's customer record for the next top-ups. The billing page shows the cards on file (brand, last four digits, expiry) under **Payment method**, and the **Manage cards** button opens Polar's hosted portal, where cards can be added or removed, billing details changed and receipts downloaded. Every top-up checkout also accepts a different card, so paying with a new one is another way to change it. ## Auto recharge With a card on file, a workspace can top itself up: set a threshold and an amount under **Auto recharge** on the billing page. Whenever the effective balance drops under the threshold, or under what one day of the running keywords costs, the saved card is charged the amount and the balance credited, the same way a manual top-up is; a paused workspace with auto recharge on is refilled the same way. Some rules keep it predictable: * At most one automatic charge per workspace per UTC day, whatever happens to the balance afterwards. A noisy keyword can cost at most one top-up a day. * The amount follows the same bounds as a manual top-up ($20 to $5,000); the threshold can be anything from zero up. * A failed charge (declined card, no card on file) is emailed to the workspace owners with the reason and retried the next day. The billing page shows the last automatic top-up and the last failure. * A workspace that was paused resumes as soon as the automatic top-up lands, like after a manual one. The setting appears on the billing page once the deployment can charge saved cards. `GET /v1/billing/wallet` reports it under `autoRecharge` (`available`, `enabled`, `thresholdCents`, `amountCents`, `lastRunAt`, `lastError`), and `PATCH /v1/billing/auto-recharge` with any of `enabled`, `thresholdCents`, `amountCents` changes it. ## When the balance runs out Tracking pauses in two situations. At the daily settlement, if the effective balance cannot cover the day about to be charged for the running keywords (`nextDayCents`), the workspace is paused before the charge, so a day is never charged and lost. During the day, only if matched mentions overdraw what was already paid (the effective balance drops under zero). Nothing is deleted: keywords, mentions, alerts and channels stay exactly as they were, and matched mentions already in the feed remain there. The paused keywords show up as `autoMutedKeywords`. Tracking resumes on its own, within a minute of a top-up, once the effective balance covers one day of every keyword, running and paused (`resumeCostCents`). Two emails go out along the way: one when the effective balance drops to 20 percent of the last top-up (or of the welcome credit before the first top-up), and one when tracking stops. Each is sent once per top-up. ## Keyword capacity Self-serve workspaces track up to 500 keywords; past that it is an [enterprise](https://mentio.dev/enterprise) conversation with the same rate card and volume discounts. Creating or unmuting a keyword fails with `402 insufficient_balance` when the effective balance cannot pay for one more keyword-day (add funds and retry), or with `402 keyword_limit_reached` at the 500-keyword ceiling. The check rides in the write itself, so concurrent requests cannot race past either limit. See [Errors](/errors). ## Checking your balance ```bash curl -H "Authorization: Bearer $MENTIONS_API_KEY" \ "$MENTIONS_API_URL/v1/billing/wallet" ``` ```json { "balanceCents": 1842, "pendingCents": 96, "effectiveBalanceCents": 1746, "burnPerDayCents": 131, "daysLeft": 13, "stopped": false, "activeKeywords": 5, "autoMutedKeywords": 0, "nextDayCents": 84, "resumeCostCents": 84, "signupCredit": { "amountCents": 580, "grantedAt": "2026-08-14T09:12:03.000Z" }, "lastTopUpAt": "2026-08-29T16:40:11.000Z", "billingConfigured": true, "minTopUpCents": 2000, "maxTopUpCents": 500000, "defaultTopUpCents": 2000, "currency": "USD" } ``` | Field | Meaning | | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `balanceCents` | Ledger balance: every credit minus every settled debit | | `pendingCents` | Mentions matched since the last daily settlement, priced but not yet debited | | `effectiveBalanceCents` | `balanceCents` minus `pendingCents`: what the stop rule and the keyword gate look at | | `burnPerDayCents` | Average daily deduction over the last 7 days (or since the workspace was created) | | `daysLeft` | `effectiveBalanceCents` divided by `burnPerDayCents`; `null` when nothing is burning | | `stopped` | `true` while tracking is paused for lack of balance | | `activeKeywords` | Unmuted keywords right now | | `autoMutedKeywords` | Keywords the wallet paused; a top-up resumes them | | `nextDayCents` | What one more day of the running keywords costs; tracking stops when the effective balance drops under it | | `resumeCostCents` | What one day of every keyword (running and paused) costs; a stopped workspace resumes once the effective balance covers it | | `signupCredit` | The welcome credit this workspace received (`amountCents`, `grantedAt`), or `null` | | `lastTopUpAt` | Newest paid top-up; `null` before the first | | `billingConfigured` | `false` on a deployment without Polar credentials; the dashboard hides the top-up button | | `minTopUpCents`, `maxTopUpCents`, `defaultTopUpCents` | The top-up range (2000 to 500000) and the checkout prefill (2000) | | `currency` | Always `USD` | ## The ledger Every movement of the balance is a ledger entry, newest first: ```bash curl -H "Authorization: Bearer $MENTIONS_API_KEY" \ "$MENTIONS_API_URL/v1/billing/ledger?limit=50" ``` ```json { "data": [ { "id": "led_4f1c9a2e7b3d4c8e9a0b1c2d3e4f5a6b", "kind": "debit_mentions", "amountCents": -96, "day": "2026-09-06", "units": 1730, "note": null, "polarOrderId": null, "createdAt": "2026-09-07T00:05:12.000Z" }, { "id": "led_9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a", "kind": "debit_keyword_days", "amountCents": -83, "day": "2026-09-06", "units": 118, "note": null, "polarOrderId": null, "createdAt": "2026-09-07T00:05:12.000Z" }, { "id": "led_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d", "kind": "topup", "amountCents": 2000, "day": null, "units": null, "note": null, "polarOrderId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "createdAt": "2026-08-29T16:40:11.000Z" }, { "id": "led_0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c", "kind": "signup_credit", "amountCents": 580, "day": null, "units": null, "note": "Welcome credit", "polarOrderId": null, "createdAt": "2026-08-14T09:12:03.000Z" } ], "nextCursor": null } ``` Pass `nextCursor` back as `cursor` to page. Credits are positive, debits negative. | Kind | Meaning | | -------------------- | -------------------------------------------------------------------------------------- | | `signup_credit` | The welcome credit, once per user | | `topup` | A paid Polar order; `polarOrderId` is the order | | `refund` | A refund Polar issued on a top-up, taken back off the balance | | `debit_keyword_days` | The daily keyword deduction; `units` is the cumulative keyword-days settled so far | | `debit_mentions` | The daily mention deduction; `units` is the cumulative matched mentions settled so far | | `adjustment` | A manual correction by Mentio staff, with a `note` | Debit rows carry `day` (the last UTC day the row settled) and `units`. Each debit settles the difference between the cumulative charge since the workspace was created and what was already debited, so rounding never drifts: 30 keyword-days are exactly $5.00 (`500` cents) and 100 mentions are exactly $0.80, whatever the day-by-day split. Deductions are computed so that an error can only ever under-count, never over-charge. If a deployment has no billing credentials configured, the top-up endpoints return `503 billing_not_configured`, `billingConfigured` is `false`, and everything else keeps working on the balance the workspace already has. The billing endpoints are dashboard endpoints: they accept an API key, but they change with the dashboard and are left out of the generated reference. The wallet and ledger fields above are the stable part.