Managing Hearth credit caps for MSP sub-accounts

Overview

If your organization is an MSP parent in Hearth, you manage one shared credit pool for your entire cohort. Credit caps allow you to set a per-sub-account ceiling on that pool. A cap prevents any single sub-account from consuming the whole cohort's balance. From the same billing area, you can also purchase credit packs, assign them to a specific sub-account or to the shared pool, and track overage.

How it works

Credits are the unit that Hearth meters AI work against. Investigations, chat with Hestia, briefings, dashboards, and other generated artifacts draw from the same monthly pool. In an MSP cohort, that pool lives at the parent organization, along with the card on file. Credit caps divide that shared pool among your sub-accounts.

Each cap is a whole number of credits, from 0 to 1,000,000,000. A blank cap means pool-only. A sub-account with a blank cap draws the shared pool with no ceiling of its own.

When a sub-account uses an AI feature, Hearth checks both the shared pool and the sub-account's cap before the work runs. If the sub-account reaches its cap for the current billing period, Hearth blocks the request and displays an "out of credits" message. Hearth blocks the request even when the shared pool still has credit. This protects the cohort's balance from a single heavy consumer.

Consider the following when you plan your caps:

• Consumption resets each billing period. The period is the calendar month in UTC, and it resets at the start of each month. Each row shows the credits that a sub-account consumed during the current billing period.
• A warning appears in the app before a block occurs. As a capped sub-account approaches its cap, Hearth displays a low-balance warning.
• Caps fail open. If Hearth cannot resolve the cohort hierarchy, or if a sub-account has no cap, Hearth applies the standard shared-pool rules. A cap error never denies a run on its own.
• Purchased headroom is temporary. A credit purchase that you assign to a specific sub-account gives that sub-account extra headroom above its cap for that month.

What you can see and do

The Credit caps screen lists your cohort as editable rows. The following table describes each element:

Note: If a sub-account has purchased headroom assigned during the current month, Hearth warns you before you clear its cap. When you clear the cap, that headroom becomes inert until you set a cap again.

Setting credit caps

Only an administrator of the parent organization can view or change caps. A client-only administrator cannot.

To edit a tenant's credit cap, do the following:

1. Navigate to More (⋯) > Credit caps.
2. On a sub-account's row, type the number of credits in the cap box, and then click Save.
3. (Optional) To apply the same cap to every sub-account, click Set all sub-accounts, type the number of credits, and then click Apply.
4. (Optional) To bound your own consumption against the shared pool, type a number of credits on the This organization (parent) row, and then click Save.
5. (Optional) To return a client to pool-only, click Clear on its row. If that tenant has headroom for the current month, confirm the prompt.

Purchasing and assigning credits

To purchase more Hearth credits, do the following:

1. Navigate to Billing.
2. Verify the payment method on file or update the information.
3. (Optional) Under Assign this purchase to, select the tenant you are buying credits for.
   Note: Credits that you assign to a specific sub-account gives that sub-account extra headroom above its cap. The headroom applies during the purchase month, and it applies only while that sub-account has a cap set. The row displays an "assigned this month" note.
4. Next to the desired credit option, click Buy.

Billing notifications

Hearth sends the following email notifications to your billing contacts:

• receipts
• payment failure notices
• low-balance warnings

Troubleshooting common issues