Phoca Cart – Subscription Feature User Manual

Welcome to the comprehensive user manual for the Phoca Cart Subscription Feature. This guide details how to configure subscription products, manage user group access control (ACL), configure automated expiration and notification tasks, customize email templates, administer subscriptions in the backend, and execute complete end-to-end verification tests.

Introduction & Core Architecture
Plugin Configuration
Creating Subscription Products (Step-by-Step)
Pricing, Discounts & Renewal Scenarios
Mail Templates & Email Notifications
Customer Frontend Experience
Order Status Synchronization & Lifecycle
Administering Subscriptions in Backend
Step-by-Step Testing & Verification Guide
Troubleshooting & FAQ

1. Introduction & Core Architecture

The Phoca Cart Subscription feature enables recurring memberships, digital service access, software licenses, and paywalled content within Joomla.

Key Characteristics

Product Type 6: Subscriptions are identified by product type 6 in #__phocacart_products.
Automated Access Control (ACL): Customers are automatically added to designated Joomla user groups upon activation, and removed upon expiration or cancellation.
Dynamic Pricing Engine: Automatically handles one-time signup fees, renewal discounts, and grace period rules.
Audit Logging: Full history logs are maintained for status changes (#__phocacart_subscription_history) and user group modifications (#__phocacart_subscription_acl).

Database Architecture

Table	Description
`#__phocacart_products`	Stores subscription settings (period, unit, signup fee, discount, groups)
`#__phocacart_subscriptions`	Active and historical subscription instances per user/product
`#__phocacart_order_subscriptions`	Snapshot of subscription configuration captured at order checkout
`#__phocacart_subscription_history`	Timestamped audit log of all status transitions and events
`#__phocacart_subscription_acl`	Log of user group additions and removals

2. Plugin Configuration

The subscription system is driven by two plugins:

System Plugin: plg_system_phocacartsubscription
Task Plugin: plg_task_phocacartsubscription (Joomla Scheduled Tasks)

2.1 System Plugin: System - Phoca Cart Subscription

Navigate to System → Plugins → search for Phoca Cart Subscription. Ensure System - Phoca Cart Subscription is published and enabled.

Basic Settings Tab

Activation Status: Select which Phoca Cart Order Statuses activate the subscription and grant user groups (e.g. Confirmed, Completed).
Deactivation Status: Select which Order Statuses deactivate the subscription and revoke user groups (e.g. Cancelled, Refunded, Failed, Denied).
Subscription Renewal Mode:
- Append to Existing End Date (Recommended): If an active subscriber renews early, the new period is added onto the current expiration date.
- From Now (Reset Expiration): The subscription period resets immediately from today.
Display Period Price Options: Toggle whether the period and unit (e.g. "per month") are displayed alongside the product price on product pages, category lists, or cart items.
Charge Expired Signup Fee:
- Yes: If an expired subscription is renewed after the grace period has elapsed, the initial signup fee is charged again.
- No: The signup fee is only ever charged on the first purchase.
Notification Days Before: Number of days prior to expiration when the "Expiring Soon" notice is triggered (default: 7 days).
Subscription Description (Account View): Custom text or HTML instructions shown to customers above their subscription table in My Account.

Email Tab

Each email event can be toggled Yes or No:

Send Email on Subscription Activated (Default: Yes)
Send Email on Subscription Renewed (Default: Yes)
Send Email on Expiring Soon (Default: Yes)
Send Email on Subscription Expired (Default: Yes)
Send Email on Subscription Canceled (Default: Yes)
Send Email on Status Changed (Default: No — general administrative changes)

2.2 Task Plugin: Phoca Cart Subscription Scheduled Tasks

Automated expiration and expiration warning emails are handled via Joomla's native Task Scheduler.

Navigate to System → Plugins and verify Task - Phoca Cart Subscription is Enabled.
Navigate to System → Scheduled Tasks.
Create two scheduled tasks:

Task 1: Subscription Expiration Processor

Title: Phoca Cart: Process Subscription Expirations
Task: Select Phoca Cart Subscription - Expiration (phocacart.subscription.expiration)
Execution Rule: E.g. Every hour (0 * * * *) or daily at midnight (0 0 * * *).
Function: Scans for active subscriptions whose end_date is in the past. Automatically transitions status to Expired, revokes assigned Joomla user groups, logs audit history, and sends the expiration notification email.

Task 2: Expiration Warning Notifications

Title: Phoca Cart: Send Subscription Expiration Warnings
Task: Select Phoca Cart Subscription - Notifications (phocacart.subscription.notifications)
Execution Rule: Daily at 08:00 (0 8 * * *).
Function: Finds active subscriptions expiring within the configured threshold (e.g. 7 days) that have not yet received an alert, and dispatches the "Expiring Soon" email.

2.3 Store-Wide Shipping Configuration

Subscriptions are virtual/digital products that do not require physical shipping:

Navigate to Phoca Cart → Configuration → Shipping tab.
Set Skip Shipping Method to:
- Option 1: Yes (all products are downloadable or gift vouchers or subscriptions or bookings).
Click Save & Close.

3. Creating Subscription Products (Step-by-Step)

3.1 Product Details & Type Selection

Navigate to Components → Phoca Cart → Products → click New.
In the General tab:
- Title: E.g. VIP Club Membership (Annual).
- Price: Enter base subscription price (e.g. 120.00).
- Type: Select Subscription (Product Type 6).
Click Save (the Subscription Options tab will appear).

3.2 Subscription Parameters Explained

Open the Subscription Options tab:

Field	Description	Example
Period	Number of units for the subscription validity.	`1`, `6`, `12`
Unit	Time unit: `Day`, `Week`, `Month`, `Year`.	`Month` (with Period 12 = 1 year)
Signup Fee	One-time initial setup fee added to the first order.	`25.00`
Renewal Discount	Discount given to customers renewing their subscription.	`10.00`
Renewal Discount Type	`Fixed Amount` or `Percentage`.	`Percentage` (`10%`)
Grace Period (Days)	Number of days after expiration during which renewal discount still applies and signup fee is waived.	`14` (days)

3.3 Access Control (ACL) & Joomla User Groups

In the Subscription Options tab:

User Groups to Add: Select one or more Joomla user groups assigned to the user when the subscription becomes Active (e.g. VIP Member, Subscriber).
User Groups to Remove: Select groups removed when active (e.g. Trial User or Free Member).
Automatic Reversal: When a subscription Expires, is Cancelled, or Refunded, the system automatically reverses the group assignment:
- Added groups are removed from the user profile.
- Removed groups are restored.
- The operation is safely logged in #__phocacart_subscription_acl.

4. Pricing, Discounts & Renewal Scenarios

Phoca Cart calculates subscription prices dynamically based on the customer's previous history:

                              [Customer Views Product / Adds to Cart]
                                                 │
                                                 ▼
                                     Has Existing Subscription?
                                     ┌───────────┴───────────┐
                                    NO                       YES
                                     │                        │
                                     ▼                        ▼
                               [Scenario 1]            Is Sub Active?
                               New Purchase            ┌──────┴──────┐
                            Base + Signup Fee         YES            NO
                                                       │              │
                                                       ▼              ▼
                                                 [Scenario 2]   [Scenario 3]
                                                Active Renewal  Expired Renewal
                                                Base - Discount Within Grace Period?
                                                Append Period   ┌─────┴─────┐
                                                               YES          NO
                                                                │            │
                                                                ▼            ▼
                                                          Base - Discount  Base + Signup Fee
                                                          No Signup Fee    No Discount

Scenario 1: First-Time Purchase (New Subscription)

Customer has no existing subscription for this product.
Price Calculation: Total = Base Price + Signup Fee.
Duration: Start Date = Today, End Date = Today + Period.

Scenario 2: Active Early Renewal

Customer currently holds an Active subscription and renews before expiration.
Price Calculation: Total = Base Price - Renewal Discount (Signup fee is skipped).
Duration (Renewal Mode = Append): Start Date = Original Start Date, End Date = Current End Date + Period.

Scenario 3: Expired Renewal & Grace Period

Customer held a subscription that has expired.
Within Grace Period (e.g. expired 5 days ago, grace period is 14 days):
- Renewal discount is preserved.
- Signup fee is waived.
- Total = Base Price - Renewal Discount.
- Period starts from the current checkout date.
Outside Grace Period (e.g. expired 30 days ago):
- Renewal discount is revoked.
- Initial signup fee is re-applied (if plugin option Charge Expired Signup Fee is enabled).
- Total = Base Price + Signup Fee.

5. Mail Templates & Email Notifications

5.1 Email Event Triggers

Event	Trigger Condition	Template Key
Activated	Order confirmed/completed, subscription becomes Active	`com_phocacart.subscription.activated`
Renewed	Existing subscription renewed and end date extended	`com_phocacart.subscription.renewed`
Expiring Soon	Scheduled task detects subscription expiring in X days	`com_phocacart.subscription.expiring_soon`
Expired	Scheduled task or admin marks subscription as Expired	`com_phocacart.subscription.expired`
Canceled	Order refunded/cancelled, subscription terminated	`com_phocacart.subscription.canceled`
Status Changed	Manual administrative status modification	`com_phocacart.subscription.status_changed`

5.2 Customizing Mail Templates in Joomla

Navigate to System → Mail Templates.
Find templates under the com_phocacart component prefixed with 📦 Phoca Cart: Subscription...
Edit subject, plain text body, or HTML template.
The {HTML.DOCUMENT} tag renders the structured HTML email layout:
- Header with store logo and personalized greeting.
- Subscription details card with product title and status badge.
- Start date, end date, and days remaining summary.
- Action buttons (e.g. Renew Now or View My Account).

5.3 Dynamic Template Tags

The following tags are dynamically replaced during email dispatch:

{USER_NAME}, {USER_USERNAME}, {USER_EMAIL}: Customer details.
{PRODUCT_NAME}, {PRODUCT_TITLE}, {PRODUCT_SKU}, {PRODUCT_LINK}: Product details.
{SUBSCRIPTION_ID}, {SUBSCRIPTION_STATUS}: Subscription record info.
{START_DATE}, {END_DATE}, {DAYS_REMAINING}: Validity dates and remaining days counter.
{RENEWAL_COUNT}: Number of times this subscription has been renewed.
{RENEWAL_URL}, {RESUBSCRIBE_URL}: Direct checkout renewal link.
{ACCOUNT_URL}: Link to the customer's account page.
{SITE_NAME}, {SITE_URL}: Website details.

6. Customer Frontend Experience

6.1 Product Page & Pricing Display

Subscription products clearly display the subscription period and renewal terms.
If a customer is logged in and already owns an active subscription, the page automatically reflects their renewal price (displaying the applied renewal discount).

6.2 Shopping Cart & Checkout

Cart and checkout summaries itemize the base price, signup fee (if applicable), and renewal discount.
Physical shipping selection is bypassed.
An immutable snapshot is stored in #__phocacart_order_subscriptions upon order placement.

6.3 Customer Account ("My Subscriptions")

When a customer logs in and visits My Account (index.php?option=com_phocacart&view=account):

A dedicated My Subscriptions section displays:
- Product Title with link.
- Current Status badge (Active, Pending, Expired, On-Hold).
- Start Date and Expiration Date.
- Direct Renew link for fast renewal checkout.
- Optional guidance text configured in plugin settings.

7. Order Status Synchronization & Lifecycle

Subscriptions are synchronized with Phoca Cart's order processing:

[Customer Checkout]
       │
       ▼
Order Created ─────────► Subscription Record created with "Pending" Status
       │
[Payment Processed / Order Status = Confirmed or Completed]
       │
       ▼
Plugin Event: onPhocaCartAfterOrderStatusUpdate
       ├── Subscription Status updated to "Active"
       ├── User added to configured Joomla User Groups
       ├── Group changes logged in #__phocacart_subscription_acl
       ├── Audit entry logged in #__phocacart_subscription_history
       └── "Subscription Activated" email sent to customer
       │
[Scheduled Task: Expiration Check]
       │
       ▼
Subscription Passes End Date
       ├── Status updated to "Expired"
       ├── User removed from assigned User Groups
       └── "Subscription Expired" email sent to customer
       │
[Order Cancelled / Refunded by Admin]
       │
       ▼
Plugin Event: onPhocaCartAfterOrderStatusUpdate
       ├── Status updated to "Canceled"
       ├── User removed from assigned User Groups
       └── "Subscription Canceled" email sent to customer

8. Administering Subscriptions in Backend

8.1 Subscriptions List View

Navigate to Components → Phoca Cart → Subscriptions (phocacartsubscriptions):

Browse all subscriptions with customer name, product, status badge, start date, and end date.
Search and filter by status, product, user, or date range.

8.2 Subscription Edit Screen & Manual Status Changes

Click any subscription ID to open the edit screen:

User & Product: View linked user and product.
Status Selection: Manually adjust status (Active, Expired, On-Hold, Canceled).
Dates: Adjust start date or expiration date manually if customer requires an extension.

8.3 Audit History & ACL Change Logs

History Tab: Displays every recorded status transition, who triggered it (order, payment, scheduled task, admin), and notification status.
ACL History Tab: Displays an audit log of every user group added or removed for this user with exact timestamps.

9. Step-by-Step Testing & Verification Guide

Follow this step-by-step checklist to test the entire subscription workflow:

Test Scenario A: New Subscription Purchase & User Group Grant

Setup:
- In Joomla Users → Groups, create a test group: VIP Subscribers.
- In Products, create a subscription product:
  - Title: Annual VIP Access.
  - Price: €100.00.
  - Period: 1, Unit: Year.
  - Signup Fee: €20.00.
  - User Group to Add: VIP Subscribers.
Purchase:
- Log in on frontend as a standard registered customer.
- Verify that your user is NOT in the VIP Subscribers group (Users → Manage in admin).
- Add Annual VIP Access to the cart.
- Verify cart shows Subtotal €100 + Signup Fee €20 = €120.00.
- Complete checkout.
Verify Activation:
- If order status is set to Confirmed or Completed:
  - In Subscriptions (phocacartsubscriptions), check that a new record is created with status Active.
  - Check customer profile in Users → Manage: customer is now assigned to VIP Subscribers.
  - Open the subscription in admin and check the ACL History tab: confirm entry Group added: VIP Subscribers.
  - Verify the customer received the 📦 Subscription Activated email.

Test Scenario B: Early Active Renewal & Period Append

Setup:
- In plugin settings (System - Phoca Cart Subscription), ensure Subscription Renewal Mode is set to Append to Existing End Date.
- In the test product, set Renewal Discount to 10.00 (Fixed Amount).
Renewal:
- As the same customer from Scenario A, visit the product page or click Renew in My Account.
- Verify that the price reflects the renewal discount: €90.00 (€100 - €10 discount, no signup fee).
- Complete the checkout.
Verify Appended Validity:
- Open Subscriptions in admin.
- Verify Renewal Count is now 1.
- Verify that the End Date has been extended by exactly 1 additional year beyond the previous end date.
- Verify customer received the 🔄 Subscription Renewed email.

Test Scenario C: Expiration Processing via Joomla Task Scheduler

Setup:
- In Subscriptions in admin, edit the test subscription: change End Date to yesterday's date.
Run Task:
- In Joomla admin, navigate to System → Scheduled Tasks.
- Find Phoca Cart: Process Subscription Expirations and click Run Now (or execute via CLI: php joomla.php task:run phocacart.subscription.expiration).
Verify Expiration:
- In Subscriptions, status has changed to Expired.
- In Users → Manage, verify the user has been removed from VIP Subscribers.
- In subscription edit, check the ACL History tab: confirm entry Group removed: VIP Subscribers.
- Customer receives the ❌ Subscription Expired email.

Grace Period Test:
- Set product Grace Period (Days) = 7.
- Ensure the subscription expired 2 days ago (within grace period).
- Customer logs in and adds product to cart:
  - Verify renewal discount is still applied (€90.00).
  - Signup fee is NOT charged.
Post-Grace Period Test:
- In plugin settings, ensure Charge Expired Signup Fee is Yes.
- In the database or admin, adjust subscription expiration date to 30 days ago (outside grace period).
- Customer adds product to cart:
  - Verify renewal discount is NOT applied.
  - Signup fee (€20.00) IS charged again.
  - Total price is €120.00.

Test Scenario E: Order Status Synchronization (Cancellation & Refund)

Place a test order for a subscription product so that it becomes Active.
In admin Orders, edit the order and set Order Status to Cancelled or Refunded.
Verify:
- Subscription status changes to Canceled.
- User group VIP Subscribers is removed from customer.
- Cancellation audit entry is logged in #__phocacart_subscription_history.
- Customer receives the 🚫 Subscription Canceled email.

Test Scenario F: Email Notifications Verification

Open System → Mail Templates.
Inspect the 6 subscription templates. Customize the subject line of com_phocacart.subscription.activated (e.g. add [TEST VIP]).
Place an order and verify that the delivered email reflects the modified subject line and contains populated values for {USER_NAME}, {PRODUCT_NAME}, {START_DATE}, and {END_DATE}.

10. Troubleshooting & FAQ

Q: Why was a customer not added to the configured user group after purchasing?
A: Check the following:

Verify that System - Phoca Cart Subscription plugin is published and enabled.
Check your plugin's Activation Status parameter: the order must reach one of the statuses specified in this list (e.g. Confirmed or Completed).
If payment was made via an offline method (e.g. Cash on Delivery, Bank Transfer), the order remains Pending until an administrator manually changes the order status to Confirmed.

Q: How do I test the expiration task on my local development environment?
A: You can manually trigger the task without waiting for a cron job:

Navigate to System → Scheduled Tasks → click the Run Now button on the Expiration task, or
Run the Joomla CLI command from terminal:
php /var/www/phoca84.test/J62/cli/joomla.php task:run phocacart.subscription.expiration

Q: What happens if an expired subscriber renews? Do they keep their previous subscription record?
A: Yes. The system detects their existing record, updates the status back to Active, increments the renewal_count, sets the new validity dates, and re-adds the user group.

Q: Can I set up a trial period for subscriptions?
A: Trial options can be configured within Phoca Cart product parameters or via dedicated trial promotional coupons.

Q: Where can I see which user groups were added or removed for a customer?
A: In the administrator panel, navigate to Components → Phoca Cart → Subscriptions, open the customer's subscription, and switch to the ACL History tab.