docs(credits): the monthly refill is a floor, not an assignment - #300
Conversation
The monthly credit refill SETs remaining_credits to the plan total, so any account holding more than its plan total is cut on the next balance read (recoupable/chat#1960, 50 accounts currently in that state). The api fix makes the refill a floor. This is the contract half. - POST /api/admins/credits: replace the "A grant expires after one month" paragraph, which described the reduction as intended behaviour, and drop `expires_at` from AdminGrantCreditsResponse. A grant can no longer be reduced by a refill, so there is nothing to expire. - credits.mdx: add a "Monthly refill" subsection stating the floor rule and that the refill is lazy and read-triggered. Merge after the api refill fix, not before: until that ships, a refill still reduces balances and this page would under-promise the old behaviour.
|
Caution Review failedAn error occurred during the review process. Please try again later. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Preview verification — local Mintlify dev serverSame method as docs#299's pass: local Documented vs actual
Screenshots1.
2. Grant endpoint — the replacement paragraph, and the generated 200 example ending at
Merge order reminder — this one waitsUnlike #299, do not merge this on the back of a green preview. This PR documents behaviour the api does not have yet: prod's refill still SETs the plan total, and |
Contract half of the refill fix in recoupable/chat#1960. Row 2 of that issue's PR matrix.
checkAndResetCreditsSETsremaining_creditsto the plan total once a monthly refill is due, rather than topping up to it. Any account holding more than its plan total is therefore cut on the next balance read. Measured on prod 2026-08-17: 119 accounts hold more than the 333 free-plan total, 50 of them with a reset already pending. Because the refill is lazy and read-triggered, the loss fires on aGET, so reading a balance is what destroys it.Today's docs describe that reduction as intended behaviour and build a contract on top of it. This PR corrects the contract.
What changes
POST /api/admins/credits— the "A grant expires after one month, plan for it" paragraph is replaced. It told admins that a granted balance "is then silently overwritten on the first balance read after it" and to "grant it again" if the headroom needed to outlive a month. Once the refill cannot reduce a balance, that is false and actively causes admins to re-grant credits that do not need re-granting.AdminGrantCreditsResponse.expires_atis removed (breaking, admin-only). The field's whole purpose was to report when the refill would destroy the grant. With a floor refill, it describes an event that never happens.requireddrops from 8 fields to 7.credits.mdx— new### Monthly refillsubsection under## Subscription, stating the floor rule and that the refill is lazy and read-triggered.Verification
api-reference/openapi/accounts.jsonparses after editing;AdminGrantCreditsResponsenow reportsrequired: [status, grant_id, account_id, remaining_credits, previous_credits, reason, granted_by, granted_at]and the same 7 properties plusstatus, with noexpires_atin either.grep -n "expires_at" api-reference/openapi/accounts.jsonreturns nothing.json.load/json.dumpsround-trip:accounts.jsondoes not round-trip byte-for-byte (it stores non-ASCII as\uXXXXescapes), so a rewrite would have produced a 200-line whitespace diff.credits.mdxline 44, which docs#299 edits, so the two docs PRs merge in any order without conflict. They touch disjoint regions ofaccounts.json(card-on-file and the auto-recharge path vs. the admin grant block).Merge order
Merge this after the api refill fix reaches prod (row 5 of chat#1960), not before. It is the one place the docs-first convention inverts: until the api change ships, a refill still reduces balances, and publishing the floor rule early would document behaviour prod does not have. The
POST /api/admins/creditshalf additionally needs the api PR that stops returningexpires_at(row 6).Summary by cubic
Clarifies that the monthly credit refill is a floor, not an assignment, and updates docs to match. Previously, refills overwrote balances to the plan total on the next read and grants above the plan total were cut; now refills only top up and never reduce, so grants do not “expire.”
Rollout and migration
AdminGrantCreditsResponseremovesexpires_at(breaking, admin-only). Update admin tools and automation to stop reading or relying onexpires_at.POST /api/admins/creditsdescription now states that refills never reduce balances; the “grant expires after one month” guidance is removed.credits.mdx: adds “Monthly refill” subsection explaining the floor rule and that the refill is lazy and read-triggered.Written for commit 940e4bd. Summary will update on new commits.