Skip to main content

Initial AI quota (qontakchat_ai_credit) stops resetting monthly (Billing V1 & V3)

Jira: TBD — to be minted as a Story under Epic BIF-8695 · Epic: BIF-8695

Overview​

  • Before: The monthly reset job overwrites each package's initial AI quota (qontakchat_ai_credit, the credit field) back to InitialChatbotAiPackage.credit (e.g. 1000) on the 1st of every month, discarding the prior month's running balance. A customer who used only 300 is topped back to 1000; unused quota never carries.
  • After: For billing V1 and V3, the monthly reset no longer touches the initial AI quota — the credit balance persists: it carries over month to month and only depletes with real usage. No monthly refill is added and no leftover is discarded. The initial quota is granted at activation/renewal (its existing lifecycle) and is not refreshed monthly.

Scope Changes​

  • Backend (moderator-be) — the monthly reset stops resetting the initial credit portion; add-on/top-up (extra) handling is untouched.

Technical notes (grounding)​

  • Reset: Core::Repositories::Billing::ChatbotAi::Reset (app/domains/core/repositories/billing/chatbot_ai/reset.rb), run by chatbot_ai_reset_monthly_task at 00:00 on the 1st, Asia/Jakarta (config/schedule.yml).
  • Today it sets package.credit = initial_package.credit - usage_gap (≈ the full initial amount on the 1st, when the gap is ~0) — this is the monthly overwrite to remove for the initial quota. package.extra (add-on/top-up, chatbot_ai_extra), the postpaid branch, the is_reset_hold minus-usage hold, and the outstanding/conversation-log handling are separate concerns that stay as-is.
  • The change targets the initial quota only (the credit field / qontakchat_ai_credit component), for billing V1 and V3.

Out of scope​

  • Add-on / top-up (extra) quota behaviour — unchanged.
  • Any component other than the initial AI quota.
  • No change to how the initial quota is first granted at activation/renewal.

8. User Stories + Acceptance Criteria​

User StoryImportanceMockup / Technical NotesAcceptance Criteria
[AIQUOTA-S01] — Initial AI quota persists instead of resetting monthly

As the billing system, I want the monthly reset to stop resetting the initial AI quota (qontakchat_ai_credit / the credit field) for billing V1 and V3, so that the initial quota balance persists — carrying over and only depleting with usage — instead of being refilled to the initial amount every month.		Should HaveReset job runs 1st of month (chatbot_ai_reset_monthly_task). Remove only the credit (initial) overwrite; keep extra / postpaid / is_reset_hold / outstanding logic. Applies to V1 and V3.— Happy Path —
• AC-1: Given a ChatbotAiPackage on billing V1 or V3 with a running credit balance, when the monthly reset runs, then package.credit (initial AI quota) is not reset or refilled — it keeps its current running balance (no monthly grant added, no leftover discarded).
• AC-2: Given the initial quota now persists, when the customer consumes AI usage during the month, then deductions reduce the persisted credit as today until it reaches 0, after which existing extra / top-up overflow behaviour applies unchanged.
— Guard-rails —
• NEG-1: Given the add-on / top-up quota (extra), when the reset runs, then its existing behaviour — postpaid handling, is_reset_hold minus-usage hold, and outstanding/conversation logs — is unchanged; only the initial credit stops resetting.
• NEG-2: Given any component other than the initial AI quota, when the reset runs, then it is unaffected.

Open questions​

  1. Grant lifecycle — the initial quota is (re)granted at subscription activation / contract renewal (suite_packages/activate, chatbots/renew_package), correct? We are removing only the monthly refresh, not the activation grant — confirm.
  2. Billing-version gating — "V1 and V3" effectively means all ChatbotAiPackages; should the code gate on a billing_version field, or does removing the monthly credit reset apply universally? Is there a V2 to consider?
  3. Rollout — hard behaviour change at the next monthly run for all packages, or behind a config/flag for staged enablement?
  4. Reset audit log — with the initial-credit reset removed, should the monthly ChatbotAiPackageLog / reset conversation log still be written for credit (now a no-op), or skipped? Preserve an audit trail either way.
  5. Negative-credit path — today the reset can spill negative credit into extra. With credit no longer overwritten, confirm the extra reconciliation still behaves correctly when credit is already 0/negative from in-month deductions.