Free Plan: Reply Cap and Monthly Reset

This document describes how the free plan reply limit is stored, enforced, and reset.

---

Database fields (shops table)

Column	Type	Description
free_credit_limit	integer	Maximum number of AI replies allowed per month for this shop. Set when the store is created from .env FREE_PLAN_REPLIES_CAP (default 50).
free_credits_used	integer	Number of AI replies used this month. Incremented by 1 each time the shop (on free plan) receives an AI reply. Reset manually when you want to start a new period (e.g. run resetFreeCreditsUsedForAllShops or UPDATE shops SET free_credits_used = 0).

---

When values are set or updated

1. Store creation
   When a new shop is created (OAuth install), free_credit_limit is set from process.env.FREE_PLAN_REPLIES_CAP (default 50). free_credits_used is set to 0.
   See app/shopify.server.js (shop create).

2. Each AI reply (free plan only)
   After an AI reply is sent (either the canned “not enough information” message or a full LLM reply), the app increments free_credits_used by 1 for that shop.
   See app/lib/limits.server.js (incrementFreeCreditsUsed) and app/lib/rag.server.js (called after sending a reply when shop.plan === "free").

3. Monthly reset (manual)
   The app does not reset free_credits_used automatically. To reset usage for all shops (e.g. on the 1st of each month), run manually: call resetFreeCreditsUsedForAllShops(prisma) from app/lib/limits.server.js (e.g. from a script or admin-only route), or run UPDATE shops SET free_credits_used = 0 in SQL.

---

Enforcing the limit (upgrade required)

• Before generating an AI reply, the app checks the free plan limit in checkReplyLimit (in app/lib/limits.server.js).
• If free_credits_used >= free_credit_limit, the app throws REPLY_LIMIT_EXCEEDED and does not generate a reply. The API returns a 429 with a message that the monthly reply limit is exceeded and the merchant should upgrade to the paid plan.
• The Billing page shows “X of Y replies used” for free plan using free_credits_used and free_credit_limit so merchants can see usage and upgrade when needed.

---

Environment variable

• FREE_PLAN_REPLIES_CAP
  Used only when a new shop is created. Its value is stored in shops.free_credit_limit for that shop. Default if unset: 50.
  Existing shops keep their current free_credit_limit; change this env only affects new installs.

---

Migration

• Migration 20260310000000_add_free_credit_limit_and_used adds free_credit_limit (default 50) and free_credits_used (default 0) to shops.
  Existing shops get these defaults; new shops get free_credit_limit from env at create time.