docs(credit-usage): explain credits-used vs available-balance discrepancy

[george-dilthey]

What changed

Added a troubleshooting entry to docs/credit-usage.md explaining why the "Credits used" total on the usage dashboard tabs doesn't equal the yearly allotment minus the available balance. The new section (### Credits used total doesn't match my available balance) explains that per-tab Credits used figures reflect credit spend attributed to each category only, while the available balance is drawn from a separate credit ledger that includes all credit movements — refunds and account credits — so a small gap between the two is expected and not an error.

Why

A Checkr Enterprise customer (Emily Wellman, Intercom conversation #215475012757133) asked why the Workbooks tab showed ~443k credits used over their contract period, but their available balance implied a higher spend against their 1M yearly allotment. The support agent (Ariana) had to manually investigate and explain the discrepancy: per-tab "Credits used" figures reflect table-attributed spend only; the "Available balance" is drawn from the full workspace credit ledger (all movements: tab-level spend, refunds, account credits). Ariana also noted in the thread: "I'll also file some feedback to the team to let them know the total available balance accounting for those smaller credit consuming actions + refunds, but the total workspace usage page only looking at enrichment usage, is causing confusion here." A feedback ticket (FED-2734) was filed.

The existing docs Note about the Workbooks tab already says "Credits consumed by Signals, MCP, or API access appear on those respective tabs and are not included in the Workbooks total" — but it doesn't explain that even summing across all tabs won't always equal the allotment minus available balance, because refunds and ledger adjustments are a separate accounting layer. That's the gap filled here.

Source link(s)

• Intercom conversation: https://app.intercom.com/a/inbox/w28k1kwz/inbox/conversation/215475012757133
• Slack thread (customer question + support resolution): https://clay-hq.slack.com/archives/C0992TPL16J/p1783545184319469
• Ariana's explanation message: https://clay-hq.slack.com/archives/C0992TPL16J/p1783548122640629
• Verifier sub-agent findings:
  • Claim "enrichment only" — FAIL (code-corrected in doc text): Workbooks tab filters WHERE table_id IS NOT NULL — includes table-attributed enrichment AND trigger credits (post-Feb 2026 triggers get table_id; legacy triggers added via populateSignalCredits()). MCP, API, and non-table credits are excluded. Code: clay-base/libs/shared-backend/src/credit-usage/redshift.service.ts:76-85.
  • Claim "Available balance = full ledger" — PASS: currentCreditBalance drawn from Redis credit balance decremented by ALL credit types. Code: clay-base/apps/frontend/src/components/WorkspaceSettingsPage/Content/CreditUsageContent/TotalBalanceTab.tsx:267-274.
  • Export button → CSV — BETA (defaults ON): Gated by allow-export-limit subscription limit (clay-base/apps/frontend/src/components/WorkspaceSettingsPage/Content/CreditUsageContent/index.tsx:686). BooleanLimit defaults to allowed=true; default subscription hardcodes true. Can be restricted by specific Stripe plan config (outside repo). Already documented in current docs without plan caveats.
  • Note: The doc text uses "credit spend attributed to that specific category" (not "enrichment only"), which is accurate per the code and consistent with the Claim 1 correction.

Uncertainties

None. The core fact (per-tab spend = category-attributed; available balance = full ledger including refunds/account credits; gap is expected) is code-verified PASS. The Workbooks tab description in the doc uses "attributed to that specific category" (not "enrichment only"), consistent with the code showing table-attributed spend (enrichment + triggers). Export button already documented; no new doc text added for it.

Related observations

• The export button question (second part of the customer's question: "Is there an easy way to export the workbook usage into excel?") is already documented in the existing doc: "Click Export to download a CSV for offline analysis." No change needed there.
• A feedback ticket FED-2734 ("Clarify credit usage tab labels to resolve discrepancies") was filed by Ariana — that Linear issue is a product change request separate from this docs update.
• Export button is gated by subscription level (defaults ON, can be restricted by Stripe plan config). The existing docs don't caveat plan availability for export. If the product team restricts export to specific tiers more broadly, the docs should be updated.

Closes DOC-1090

[linear-code]

DOC-1090