docs(credits): web search 5→1 credit + auto top-up opt-out contract by sweetmantech · Pull Request #270 · recoupable/docs

sweetmantech · 2026-07-08T17:08:45Z

Summary

Reprices POST /api/research/web from 5 credits to 1 credit per call in the billed-endpoints table (provider cost is $0.005/request flat; the 5-credit fee overpriced generic web search ~10x).
Documents the new auto top-up opt-out: GET + PATCH /api/accounts/{id}/auto-recharge (OpenAPI blocks, two frontmatter-only reference pages, Billing nav entries), plus an Opting out section in credits.mdx and the opted-out branch in the auto top-up decision tree.

Contract highlights

enabled: true is the default for every account; the setting lives on the account's Stripe customer record and is read live.
Opting out never removes the saved card — manual checkout top-ups keep working; re-enabling requires no card re-entry.
While opted out, billed requests that exceed the balance return the existing 402 + checkoutUrl shape — no new error envelope.

Merge order

This is the contract PR for recoupable/chat#1861: docs (this) → api → chat. The api PR implements exactly this spec.

OpenAPI diff is purely additive (206 insertions, 0 deletions); both docs.json and accounts.json re-validated as parseable.

🤖 Generated with Claude Code

Summary by cubic

Repriced POST /api/research/web from 5 to 1 credit and added an auto top-up opt-out API so accounts can disable off-session charges without removing their saved card.

New Features
- Auto top-up opt-out: GET/PATCH /api/accounts/{id}/auto-recharge (default enabled: true, stored on the account’s Stripe customer). When enabled: false, requests that exceed balance return 402 with checkoutUrl; no new error shape. Docs include new reference pages and an “Opting out” section with the decision tree update.
- Web search repricing: POST /api/research/web now costs 1 credit per call. Billed-endpoints table updated.
Bug Fixes
- Updated the opt-out curl example to use $ACCOUNT_ID.

^{Written for commit 940211b. Summary will update on new commits.}

Summary by CodeRabbit

New Features
- Added API reference docs for viewing and updating an account’s auto top-up setting.
- Expanded billing documentation to explain opt-out behavior, 402 responses, and how the setting persists across card changes.
Bug Fixes
- Clarified that auto top-up will not trigger when an account has opted out.
- Updated the listed credit cost for the web research endpoint.
Documentation
- Added the new auto top-up pages to the Accounts billing documentation navigation.

…p opt-out contract Web-search research now costs 1 credit per call (provider cost is $0.005/request flat). Adds GET/PATCH /api/accounts/{id}/auto-recharge to the accounts OpenAPI: the opt-out lives on the account's Stripe customer record, disabling never removes the saved card, and opted-out accounts fail closed to the existing 402 + checkoutUrl manual-checkout path. Contract for recoupable/chat#1861 (merge first: docs → api → chat). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

cursor · 2026-07-08T17:10:23Z

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

coderabbitai · 2026-07-08T17:11:54Z

📝 Walkthrough

Walkthrough

Adds a new auto top-up (auto-recharge) API surface with GET/PATCH OpenAPI endpoints and schemas, corresponding MDX reference pages wired into docs navigation, and updates credits.mdx to document opt-out behavior for the automatic top-up charge and a revised per-call credit cost for the research web endpoint.

Changes

Auto Top-Up Feature Docs

Layer / File(s)	Summary
OpenAPI spec for auto-recharge endpoints and schemas `api-reference/openapi/accounts.json`	Adds `GET`/`PATCH /api/accounts/{id}/auto-recharge` paths with auth and error responses, plus new `AccountAutoRechargeResponse`, `AccountAutoRechargeUpdateRequest`, and `AccountAutoRechargeErrorResponse` schemas.
MDX reference pages and navigation `api-reference/accounts/auto-recharge-get.mdx`, `api-reference/accounts/auto-recharge-update.mdx`, `docs.json`	Adds "Get Auto Top-Up Setting" and "Update Auto Top-Up Setting" pages linked to the OpenAPI operations, and registers both pages under Accounts → Billing navigation.
Credits documentation updates for opt-out behavior and pricing `credits.mdx`	Documents that opted-out accounts skip silent off-session charges, expands the "Opting out" section with 402 response and PATCH disable instructions, and updates `POST /api/research/web` cost from 5 to 1 credit.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related issues

Credits: reprice POST /api/research/web 5→1 credit + self-serve auto top-up opt-out chat#1861: Addresses the same auto top-up/auto-recharge feature with matching GET/PATCH endpoint documentation.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the two main changes: web search repricing and the auto top-up opt-out documentation contract.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/1861-web-reprice-auto-recharge-optout

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.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

credits.mdx (1)
118-124: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Decision tree doesn't cover the opted-out case.

Line 118 adds "and the account hasn't opted out" as a precondition for the silent charge, but the decision tree at lines 122–124 doesn't mention opted-out accounts. An opted-out account with a valid saved card and a small shortfall doesn't match any of the three listed branches, yet should fall through to HTTP 402. Consider adding the opted-out condition to step 3 or adding a new step.
💚 Proposed update to the decision tree
 3. **No card on file, *or* opted out of auto top-up, *or* Stripe declined the card, *or* request needs more than 500 credits?** → Request returns **HTTP 402** with a recovery URL (see below).
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@credits.mdx` around lines 118 - 124, The decision tree in credits.mdx omits
the opted-out path, leaving the behavior unclear for accounts that have a saved
card but have opted out of silent top-ups. Update the decision tree so the
branching in the section with the credit gate matches the precondition described
above, using the same “opted out” concept and the existing “Opting out”
reference. Either fold opted-out accounts into the HTTP 402 branch or add a
separate branch before the off-session charge step so the flow clearly shows
they do not get auto-charged.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@credits.mdx`:
- Around line 118-124: The decision tree in credits.mdx omits the opted-out
path, leaving the behavior unclear for accounts that have a saved card but have
opted out of silent top-ups. Update the decision tree so the branching in the
section with the credit gate matches the precondition described above, using the
same “opted out” concept and the existing “Opting out” reference. Either fold
opted-out accounts into the HTTP 402 branch or add a separate branch before the
off-session charge step so the flow clearly shows they do not get auto-charged.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f0d2902b-6d52-4693-b317-8eb820441f18

📥 Commits

Reviewing files that changed from the base of the PR and between f441eca and 95b5f4d.

📒 Files selected for processing (5)

api-reference/accounts/auto-recharge-get.mdx
api-reference/accounts/auto-recharge-update.mdx
api-reference/openapi/accounts.json
credits.mdx
docs.json

cubic-dev-ai

All reported issues were addressed across 5 files

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

cursor · 2026-07-08T17:43:52Z

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

coderabbitai Bot reviewed Jul 8, 2026

View reviewed changes

cubic-dev-ai Bot reviewed Jul 8, 2026

View reviewed changes

Comment thread credits.mdx Outdated

This was referenced Jul 8, 2026

feat(credits): /research/web → 1 credit + auto top-up opt-out via Stripe customer metadata recoupable/api#769

Open

Credits: reprice POST /api/research/web 5→1 credit + self-serve auto top-up opt-out recoupable/chat#1861

Open

docs(credits): use $ACCOUNT_ID in the opt-out curl example (cubic P3)

940211b

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

sweetmantech mentioned this pull request Jul 8, 2026

feat(billing): Automatic top-up toggle in profile settings recoupable/chat#1862

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(credits): web search 5→1 credit + auto top-up opt-out contract#270

docs(credits): web search 5→1 credit + auto top-up opt-out contract#270
sweetmantech wants to merge 2 commits into
mainfrom
feat/1861-web-reprice-auto-recharge-optout

sweetmantech commented Jul 8, 2026 •

edited by cubic-dev-ai Bot

Loading

Uh oh!

cursor Bot commented Jul 8, 2026

Uh oh!

coderabbitai Bot commented Jul 8, 2026 •

edited

Loading

Walkthrough

Changes

Uh oh!

coderabbitai Bot left a comment

Uh oh!

cubic-dev-ai Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

cursor Bot commented Jul 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

sweetmantech commented Jul 8, 2026 • edited by cubic-dev-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Contract highlights

Merge order

Summary by cubic

Summary by CodeRabbit

Uh oh!

cursor Bot commented Jul 8, 2026

Uh oh!

coderabbitai Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot commented Jul 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

sweetmantech commented Jul 8, 2026 •

edited by cubic-dev-ai Bot

Loading

coderabbitai Bot commented Jul 8, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading