Member Credit Management & Top-Ups

Summary: Member Credit Management & Top-Ups is a per-user AI credit system that gives you precise control over how much your site members can use the AI chatbot.

When enabled, each logged-in member is allocated a monthly credit allowance based on their membership plan or WordPress user role. Every successful AI chatbot response costs one credit. When a member’s credits are exhausted, further chatbot requests are blocked until credits are renewed or topped up.

Administrators use this feature to:

• Define how many monthly AI credits each membership plan or role receives.
• View individual users’ credit balances and usage at a glance.
• Manually grant bonus credits to specific members.
• Configure purchasable top-up packages so members can buy additional credits on demand.
• Review a complete audit trail of every credit transaction per member.

---

Requirements

Requirement	Details
Antimanual License	Pro-Max plan required. The feature is not available on Free or Pro plans.
User must be logged in	Credit enforcement applies only to logged-in WordPress users. Guest/anonymous visitors are not subject to credit limits.
Membership plugin (optional)	If a supported membership plugin is active, credit rules are defined per membership plan. Without a membership plugin, credit rules map to native WordPress user roles.

Supported membership integrations (auto-detected):

• Paid Memberships Pro
• WooCommerce Memberships
• MemberPress
• Restrict Content Pro
• SureMembers
• Ultimate Member
• WordPress User Roles (default fallback)

Optional — WooCommerce (for automated top-up order fulfillment):
WooCommerce is not required to use the credit system. It is only needed if you want completed WooCommerce orders to automatically credit top-up packages to customer balances.

---

Enable Member Credit Management

Navigation: WordPress Admin → Antimanual → Member Credits → General & Webhook Settings tab

The feature is enabled by default for all Pro-Max sites once the plugin activates and creates the required database tables.

To toggle enforcement:

1. Go to Antimanual → Member Credits.
2. Click the General & Webhook Settings tab.
3. Find the Enable Member Credit Enforcement toggle.
4. Switch it on (active) or off (disabled) as needed.
5. Click Save Settings.

Note: When enforcement is disabled, logged-in members can use the chatbot without any credit limits, regardless of their balance.

---

Configure Monthly Credits

How Monthly Credits Work

Monthly credits are assigned per membership plan (or per WordPress role). Each plan gets a defined number of credits per billing cycle.

Credits are allocated automatically:

• When a logged-in member first interacts with the chatbot (lazy allocation).
• During the monthly reset process that runs on the 1st day of each calendar month.

If a member upgrades to a higher plan mid-month, the system automatically detects the plan change and grants the additional credits immediately (the difference between the old and new plan allowance is added to their available balance without waiting for the next cycle).

Configuring Monthly Credit Rules

Navigation: Antimanual → Member Credits → Membership Credit Rules tab

The Detected Membership Integration banner shows which membership system Antimanual detected on your site (e.g., Paid Memberships Pro, WordPress User Roles (Default)).

Each detected membership plan or WordPress role is listed with a numeric input field:

1. For each plan/role, enter the number of credits to grant per month (e.g., 1000).
2. Set 0 to grant no credits to members of that plan.
3. Click Save Credit Rules.

Tip: The field unit is credits / month. Entering 0 means members on that plan receive no monthly allocation.

Credit Expiration & Rollover Policy

Under Membership Credit Rules, a Credit Expiration & Rollover Policy section controls what happens to unused monthly credits at the end of each billing cycle.

Option	Label	Behavior
expire (Default)	Expire Unused Quota (Default) — Monthly allowance resets; top-ups roll over	Unused monthly included credits expire. Purchased top-up credits and bonus credits are not affected and carry forward.
rollover	Roll Over Unused Credits — Unspent included credits carry forward	Unused included monthly credits accumulate into the next month’s allowance.
reset	Strict Reset — Total available balance strictly resets to base plan allowance	All credits (including bonus and purchased top-ups) are cleared. The available balance is strictly reset to the plan’s base monthly allowance.

Select the appropriate policy from the dropdown and click Save Credit Rules.

---

Manage Credits for Individual Members

Navigation: Antimanual → Member Credits → Member Balances & Ledger tab

Finding a Member

The Member Balances & Ledger tab displays a paginated table of all WordPress users and their current credit status.

To search for a specific member:

1. Type in the Search by name, email or username… field.
2. Click Search.

To filter by membership plan or role:

1. Use the All Membership Plans dropdown.
2. Select the plan/role you want to filter by.

Understanding the Credit Balance Table

Each row in the members table shows the following columns:

Column	Description
Member	Display name and email address
Plan	The member’s active membership plan or WordPress role
Monthly Included	Credits allocated from their plan’s monthly allowance for this cycle
Bonus	Manually granted bonus credits currently in their account
Purchased (Top-Up)	Credits purchased via top-up packages currently in their account
Used (This Month)	Credits consumed so far in the current billing cycle
Available Balance	Total remaining credits the member can use right now

Available Actions per Member

Each member row has two action buttons:

• Ledger — Opens the Credit Audit Ledger modal showing the member’s full transaction history.
• Bonus — Opens the Grant Bonus Credits modal.

---

Add Bonus Credits

Bonus credits are a manual credit award. They are added on top of a member’s regular monthly allocation and are independent of the billing cycle.

To grant bonus credits to a member:

1. Go to Antimanual → Member Credits → Member Balances & Ledger tab.
2. Locate the member in the table (search by name, email, or username if needed).
3. Click the Bonus button in that member’s row.
4. In the Grant Bonus Credits modal:
   • Bonus Credit Amount — Enter the number of credits to grant (must be a positive integer; minimum 1).
   • Reason / Note — Optionally enter a note (e.g., Promotional reward, Support compensation). This note is stored in the transaction ledger.
5. Click Grant Credits.

The credits are added to the member’s account immediately. A bonus_credit entry is recorded in the transaction history.

Important:

• Bonus credits are persistent — they do not expire at the end of the monthly billing cycle (unless the Strict Reset expiration policy is active, which clears all credits including bonuses).
• The amount must be a positive integer. The amount field defaults to 500 and can be adjusted in increments of 50.

---

Credit Usage

When is a Credit Consumed?

One credit is consumed for each successful AI chatbot response delivered to a logged-in member.

Credits are deducted in the following priority order:

1. Monthly included credits (from plan allowance) are consumed first.
2. Bonus credits are consumed next, once the monthly quota is depleted.
3. Purchased top-up credits are consumed last.

Technical note: 1 Credit ≈ 25 AI tokens. The system estimates or reads actual token usage from the AI provider’s response to calculate the number of credits to deduct.

What Happens When Credits Are Exhausted

If a member has 0 available credits, their chatbot request is rejected before any AI call is made. The member receives the following error message:

“You have used all of your available AI credits. Please wait for your monthly credits to renew or purchase additional credits to continue.”

If the pre-flight estimate shows a request would require more credits than the member currently has, the request is also rejected with a message indicating how many credits are needed versus how many are available.

Note: Credit enforcement only applies to logged-in users. Anonymous/guest visitors are not subject to credit checks.

---

Credit Top-Ups

Top-up packages allow members to purchase additional AI credits when their monthly allocation is exhausted. Purchased credits are added to the member’s balance on top of their monthly included credits.

Purchased Top-Up Credits Behavior

• Purchased credits are persistent — they carry over across monthly billing cycles (except under the Strict Reset expiration policy, which clears all credits).
• They are consumed after the monthly included quota and bonus credits are depleted.

Configuring Top-Up Packages (Administrator)

Navigation: Antimanual → Member Credits → Top-Up Packages tab

The Purchasable Top-Up Packages tab lists all available packages. By default, four packages are pre-configured:

Package	Credits	Price
50 AI Credits	50	USD 2.50
100 AI Credits	100	USD 5.00
500 AI Credits	500	USD 20.00
1,000 AI Credits	1,000	USD 35.00

To add a new package:

1. Click Add Package.
2. Fill in the fields:
   • Package Name — Display name shown to members.
   • Credits Granted — Number of credits the package provides (minimum 10).
   • Price ($) — Package price (for display/reference; actual payment is handled by WooCommerce or your payment gateway).
   • Status — Set to Active to display the package, or Disabled to hide it.
   • WooCommerce Product (if WooCommerce is active) — Link the package to an existing WooCommerce product, or use Auto-Create to have Antimanual automatically create a new WooCommerce product for this package.
3. Click Save Top-Up Packages.

To remove a package:

Click the trash (delete) icon on the package card. Click Save Top-Up Packages to confirm.

WooCommerce Integration (Automated Fulfillment)

If WooCommerce is active on your site:

• Link each top-up package to a WooCommerce product via the WooCommerce Product dropdown on the Packages tab.
• When a customer completes an order containing that product, Antimanual automatically credits the purchased package to their account upon payment completion.
• This is fully idempotent: the same order cannot be credited more than once.

If WooCommerce is not installed or active, a banner on the Packages tab provides links to install or activate WooCommerce.

Custom Payment Webhook (Advanced)

If you use a payment gateway other than WooCommerce (e.g., Stripe, LemonSqueezy, or a custom solution), you can use the webhook integration to credit top-ups automatically.

Navigation: Antimanual → Member Credits → General & Webhook Settings tab → Top-Up Payment Webhook Integration section

The webhook settings provide:

Field	Description
Webhook Endpoint URL	The URL your payment gateway should POST to on successful payment. Copy this URL and configure it in your payment provider’s webhook settings.
Webhook Secret Signature (X-Antimanual-Webhook-Secret)	A server-generated secret key. Include this as a header in webhook requests for signature verification. Click Regenerate to create a new secret (invalidates the old one).

Member-Facing Top-Up Display (Frontend Shortcode)

Members can view their credit balance and purchase top-up packages from your site’s frontend using the shortcode:

[antimanual_member_credits]

Add this shortcode to a page such as your account page, member profile, or membership dashboard. Logged-in members will see:

• Their current available credit balance (prominently displayed).
• A breakdown showing Monthly Included, Bonus Credits, Purchased Top-Up, and Used This Month credits.
• A grid of all active top-up packages.
  • If a package is linked to a WooCommerce product, a Purchase Top-Up button links directly to the WooCommerce checkout for that product.
  • If no WooCommerce product is linked, a Contact Admin label is shown instead.

Non-logged-in visitors see a message: “Please log in to view your AI member credits.”

To copy the shortcode: Go to Antimanual → Member Credits → General & Webhook Settings tab → Frontend Member Balance Shortcode section.

---

Credit Transactions / Audit History

Every credit change for every member is recorded in a dedicated audit ledger. Administrators can review the complete transaction history for any individual member.

To view a member’s transaction history:

1. Go to Antimanual → Member Credits → Member Balances & Ledger tab.
2. Find the member and click Ledger.
3. The Credit Audit Ledger modal opens, showing:
   • A balance summary at the top (Monthly Included, Bonus Credits, Purchased Top-Up, Available Balance).
   • A Transaction History table showing the latest 100 entries.

Transaction History Table Columns

Column	Description
Date	Timestamp of the transaction
Type	Transaction type (see below)
Amount	Credits added (positive) or consumed (negative)
Balance After	Member’s available balance immediately after this transaction
Description	Human-readable explanation of the transaction

Transaction Types

Type	What It Represents
monthly_allocation	Monthly credit grant at the start of a new billing cycle
plan_upgrade	Additional credits granted mid-cycle when a member upgrades to a higher plan
bonus_credit	Manual bonus credit granted by an administrator
topup_purchase	Credits added from a purchased top-up package
credit_usage	Credits deducted for a successful AI chatbot response

---

Credit Reset Behavior

Monthly Reset Schedule

Member credits reset once per calendar month. The reset is triggered when a logged-in member first interacts with the chatbot after a new month begins — the system detects the new period and reallocates credits accordingly.

Note: Credits are allocated on first use in the new period (lazy allocation), not at a fixed UTC time via WP-Cron. There is no specific scheduled cron job running at 00:05 UTC; allocation happens on-demand when a member’s balance is accessed in a new month.

What Resets vs. What Persists

The behavior at the monthly boundary depends on the Credit Expiration & Rollover Policy configured in the Membership Credit Rules tab:

Policy	Monthly Included Credits	Bonus Credits	Purchased Top-Up Credits
Expire Unused Quota (Default)	Resets to plan allowance; unused quota is lost	Carry over	Carry over
Roll Over Unused Credits	Unspent credits carry forward and add to new month’s allowance	Carry over	Carry over
Strict Reset	Resets to plan allowance	Cleared to 0	Cleared to 0

---

Important Notes & Limitations

• Pro-Max license required. The Member Credits page is not visible and the feature is non-functional on Free or Pro licenses.
• Logged-in users only. Credit enforcement applies exclusively to logged-in WordPress users. Anonymous visitors are not credit-checked and can use the chatbot freely (subject to other access control settings).
• Credit tracking applies to the chatbot feature. Credits are currently deducted only for AI chatbot responses. Other Antimanual AI features (e.g., content generation tools) are not subject to member credit enforcement.
• Bonus credits persist by default. Bonus credits do not expire at month-end unless the Strict Reset policy is active.
• Purchased top-up credits persist by default. Purchased credits carry over across months unless the Strict Reset policy is active.
• WooCommerce fulfillment is idempotent. Each order/payment reference can only credit a top-up once, preventing duplicate crediting.
• Plan upgrades take effect immediately. If a member upgrades to a higher plan mid-cycle, the additional credits are granted right away; they do not wait for the next month.
• Plan downgrades do not immediately reduce credits. The current cycle’s allocated credits are not removed when a member downgrades. The lower allowance takes effect at the next monthly reset.
• The credit balance is always non-negative. Credits can never go below zero. If a request consumes more credits than available, only the remaining balance is deducted, and the request is still processed if any credits were available.