CUSTOMCART

• Joomla: 5.1+ (Recommended: 5.4+ or 6+)
• PHP: 8.1+ (Recommended: 8.4+)
• MySQL: 5.7+ or MariaDB 10.3+
• YOOtheme Pro: 4+ (Recommended: 4.5+)
• Web Server: Apache 2.4+ or Nginx 1.18+
• SSL/HTTPS: Required for Stripe
• PHP Extensions: cURL, JSON, Session, MySQLi/PDO, OpenSSL, mbstring, fileinfo
• Stripe Account: Required (test mode OK for development)
• EasyPost Account: Optional (for shipping labels)

CustomCart consists of three extensions that install together as a single package:

• Component (com_customcart): Admin dashboard, order management, email templates, and all configuration settings
• System Plugin (plg_system_customcart): Frontend shopping cart functionality, Stripe integration, and AJAX handlers
• YOOtheme Plugin (plg_system_yootheme_customcart): All-in-One custom element for building products

Download the package file in your account: pkg_customcart-vX.X.X.zip

CustomCart uses a centralized configuration system where ALL settings are stored in the component. The plugins automatically read these settings - no plugin configuration needed!

• Session-based Cart: Fast, secure server-side storage
• Three-Extension Architecture: Component for admin, plugins for functionality
• Stripe API Integration: Direct cURL implementation (no SDK dependency)
• InnoDB Database: Three tables with foreign key constraints
• Multi-language Support: 14+ languages included

Before installing CustomCart:

• Verify Joomla 5.0+ is installed and running
• Confirm PHP 8.1+ with all required extensions enabled
• Install and activate YOOtheme Pro
• Configure SSL certificate (HTTPS required)
• Backup your site and database
• Create a Stripe account (test mode is fine for setup)

Follow these steps for a fresh CustomCart installation:

• Login to back-end area of your Joomla CMS site using a super administrator account
• Navigate to System → Extensions → Install → Upload Package File
• Drag and drop the file or click the green button to browse. The file name will be: pkg_customcart-vX.X.X.zip
• After installation completes, you should see: "Custom Cart has been successfully installed!"
• The package automatically installs all three extensions (component + 2 plugins)

IMPORTANT: If upgrading from a previous version, you must perform a complete uninstall first due to architectural changes.

• Backup your Stripe API keys from component settings
• Navigate to System → Manage → Extensions
• Search for "Custom Cart" and uninstall ALL three extensions:
  • Custom Cart Component (com_customcart)
  • System - Custom Shopping Cart (plg_system_customcart)
  • System - YOOtheme Custom Cart (plg_system_yootheme_customcart)
• Go to System → Clear Cache → Check All → Delete
• Proceed with fresh installation steps above

After installation, verify everything is configured correctly:

• Go to System → Plugins and find "System - Custom Shopping Cart"
• Click to open it and verify you see ONLY ONE TAB called "Plugin" with a blue info box
• If you see multiple tabs (Basic, Stripe, etc.), the installation failed - repeat uninstall steps
• Ensure both plugins are Enabled:
  • System - Custom Shopping Cart
  • System - YOOtheme Custom Cart
• Go to Components → Custom Cart to verify the component loads

Create the upload directory for product file uploads:

• Directory: images/uploads/cart/
• Permissions: 755 (writable)
• The plugin automatically creates a .htaccess file to prevent script execution

Using SSH/FTP:

To remove CustomCart completely:

• Navigate to System → Manage → Extensions → Manage
• Search for "Custom Cart"
• Select the checkbox next to the Custom Cart Package
• Click the dropdown in the Actions menu and choose Uninstall
• This will remove all three extensions automatically

Warning: Uninstalling will delete all orders, settings, and database tables. Ensure you have a backup if needed.

All CustomCart settings are centralized in the component Options panel:

• Path 1: Components → Custom Cart → Options button (toolbar)
• Path 2: System → Global Configuration → Custom Cart

The component stores all configuration - plugins read these settings automatically. No plugin configuration needed!

Currency

Default currency for transactions (USD, EUR, GBP, etc.)
Default: USD

Order Number Prefix

Prefix for order numbers (e.g., ORDER-001)
Default: ORDER

Upload Max Size

Maximum file upload size in MB
Default: 22 MB

Allowed Extensions

Comma-separated list of allowed file types
Default: jpg,jpeg,png,tif,tiff,webp

Success URL

Redirect URL after successful payment
Default: Empty

Cancel URL

Redirect URL if payment is cancelled
Default: Empty

Debug Mode

Enable detailed logging to administrator/logs/customcart.log
Default: No

Cart Position

Position of floating cart icon (Top Right, Top Left, Bottom Right, Bottom Left)
Default: Top Right

Cart Display Mode

How cart opens: Modal, Offcanvas, or Responsive (auto-switches on mobile)
Default: Modal

Cart Button Text

Text on checkout button
Default: Checkout

Auto Open Cart

Automatically open cart when item is added
Default: Yes

Show Item Images

Display product images in cart
Default: Yes

Empty Cart Message

Message shown when cart has no items
Default: Your cart is empty

Require Terms

Show terms & conditions checkbox before checkout
Default: No

CRITICAL: Configure your Stripe API keys to enable payment processing.

Stripe Mode

Switch between Test and Live mode. Both sets of keys are saved separately.
Default: Test

Test Publishable Key

Your Stripe test publishable key (starts with pk_test_)
Required for test mode

Test Secret Key

Your Stripe test secret key (starts with sk_test_)
Required for test mode

Test Webhook Secret

Webhook signing secret for test mode (starts with whsec_)
Required for order creation

Live Keys

Same fields for live mode. CAUTION: Live mode processes real payments!
Use only when ready for production

Allow Promotion Codes

Enable discount codes at checkout
Default: No

Note: You must also configure webhooks in your Stripe Dashboard. See Troubleshooting section for webhook setup guide.

Collect Billing Address

Address collection at checkout (Required, Optional, Auto)
Default: Required

Collect Shipping Address

Shipping address collection (Required, Optional)
Default: Optional

Collect Phone Number

Request customer phone number
Default: No

Payment Methods

Allowed payment methods (multi-select): Card, PayPal, Klarna, and more
Default: Card

Allowed Countries

Restrict shipping to specific countries
Default: All countries

Enable Customer Email

Send order confirmation to customers
Default: Yes

Enable Admin Email

Send new order notification to admin
Default: Yes

Admin Email Address

Where to send admin notifications
Default: Site admin email

From Email / From Name

Sender information for emails
Default: Site settings

Email Logo URL

Logo image URL for email header
Default: Empty

Edit email templates at: Components → Custom Cart → Emails

Available placeholders: {order_number}, {customer_name}, {customer_email}, {order_total}, {order_items}, {billing_address}, {shipping_address}, {tracking_code}

Optional: Only configure if you need shipping label creation via EasyPost.

EasyPost Mode

Test or Production mode
Default: Test

Test/Production API Keys

Your EasyPost API keys for each mode
Required for shipping labels

Ship-From Address

Your default shipping origin (company name, address, city, state, ZIP, country, phone)
Required for label creation

Default Weight

Default package weight in ounces
Default: 16 oz

Default Package

Choose from 16 predefined package types or use custom dimensions
Default: Custom

CustomCart provides a custom All-in-One YOOtheme Pro element for building product pages. The element is found in the Modern Designs element group.

• CC Product: Main product container with title, price, image, quantity selector, and add-to-cart button
• CC Product Field: Custom input fields for product personalization (10+ field types)
• CC Product Option: Price variations and options (size, color, etc.)

Simply drag the element into your YOOtheme Pro layout to create product pages.

The CC Product element is the parent container for product displays:

Product ID

Unique identifier for the product (required)
Example: poster-001

Product Name

Product title displayed to customers
Example: Custom Poster

Base Price

Starting price without options or quantity discounts
Example: 25.00

Product Image

Main product image (supports zoom on hover)
Recommended: High resolution

Description

Rich text editor for product details
Supports HTML formatting

Quantity Pricing (9 Tiers)

Set different prices based on quantity ranges
Example: 1-5 = $25, 6-10 = $22, 11+ = $20

Add to Cart Button

Customizable text, icon, and style
Default: Add to Cart

Add custom input fields to your products (is a child of CC Product element):

Available Field Types:

• Text Input (with min/max length validation)
• Text Area (for longer text)
• Dropdown (single choice)
• Checkboxes (yes/no or agreement)
• Radio Buttons (visual selection)
• Toggle (yes/no or agreement)
• Color Picker (provide color swatch options)
• Date/Time Picker (collect time and date)
• Upload File (images, documents with size/type validation)
• Display Text (Read-only html or plain text)
• Sublayout (Add any additional elements)

Conditional Visibility: Show/hide fields based on other field values. Example: Show "Frame Color" field only if "Add Frame" is checked.

Add options that modify the product price (is a child of CC Product element):

Option Group

Group name (e.g., "Size", "Frame Type")
Example: Size

Option Values

Add multiple values with price modifiers
Example: Small (+$0), Medium (+$5), Large (+$10)

Display Mode

Radio buttons or select dropdown
Default: Radio buttons

Example Setup:
Base Price: $25
+ Medium Size: +$5
+ Premium Frame: +$50
= Total: $80

Access the admin dashboard at: Components → Custom Cart → Dashboard

Features:

• Revenue charts (daily, weekly, monthly)
• Order count statistics
• Recent orders widget
• Quick status overview
• Date range filtering

Manage orders at: Components → Custom Cart → Orders

List View Features:

• Column visibility toggle (saved per session)
• Advanced filtering (status, payment status, date range)
• Search by order number, customer, email
• Sort by any column
• Bulk status updates
• Export to PDF via browser print

Single Order View:

• Edit all fields (customer info, addresses, products, status, notes)
• Link order to Joomla user account
• Process full refunds via Stripe API
• Create shipping labels with EasyPost (4-step wizard)
• View complete order history (audit log)

Create shipping labels directly from order edit screen:

4-Step Process:

• Select Package: Choose from 16 predefined packages or enter custom dimensions (L×W×H)
• Enter Weight: Weight in ounces (auto-calculated for common items)
• Verify Addresses: Ship-from (settings) and Ship-to (order) with EasyPost validation
• Select Rate: Compare rates from multiple carriers, select, and purchase label

After purchase, tracking code and label PDF URL are automatically saved to the order.

Checklist:

• Verify system plugin is enabled: System → Plugins → System - Custom Shopping Cart
• Clear Joomla cache: System → Clear Cache
• Clear browser cache (Ctrl+Shift+Delete)
• Check browser console for JavaScript errors (F12)
• Verify YOOtheme Pro is active and UIKit is loaded
• Check cart position setting in component Options

Test in Console:
Open browser console (F12) and type: console.log(window.CustomCart);
Should show object, not undefined.

Debug Steps:

• Open browser console (F12)
• Enable Debug Mode: Component Options → Basic → Debug: Yes
• Try adding item again
• Check console for error messages
• Check Network tab for failed AJAX requests
• Review logs at: administrator/logs/customcart.log

Common Causes:

• CSRF token missing (clear browser cache)
• Session issues (check PHP session configuration)
• Invalid product data (missing ID or price)
• Plugin disabled

CRITICAL SETUP: Webhooks are required for orders to be created. Without proper webhook configuration, payments will succeed but orders won't appear in your admin.

Step 1: Get Webhook URL

Step 2: Configure in Stripe Dashboard

• Login to Stripe Dashboard
• Go to Developers → Webhooks
• Click Add endpoint
• Paste your webhook URL
• Select events:
  • checkout.session.completed
  • checkout.session.async_payment_succeeded
  • checkout.session.async_payment_failed
• Click Add endpoint

Step 3: Copy Webhook Secret

• Click on your webhook endpoint
• Find "Signing secret" and click "Reveal"
• Copy the secret (starts with whsec_)
• Paste into: Component Options → Stripe Integration → Webhook Secret

Step 4: Test Webhook

• Place a test order in your shop and you will see the order in the back-end if setup correctly as well as get an email (if emails are setup).

Cause: Webhook not configured properly or webhook secret is incorrect.

Debug Steps:

• Verify webhook is configured in Stripe Dashboard (see above)
• Confirm webhook secret matches in component Options
• Check webhook delivery in Stripe Dashboard → Webhooks → View events
• Enable Debug Mode and check: administrator/logs/customcart.log
• Look for webhook errors in logs

Common Errors:

• "Invalid signature": Wrong webhook secret
• "Session not found": Stripe API key mismatch (test vs live)
• "Database error": Check table structure

Checklist:

• Upload directory exists: images/uploads/cart/
• Directory is writable (755 permissions)
• File size within limits (check component Options)
• File type is allowed (check component Options)
• PHP upload limits not exceeded

Create Upload Directory:

Check PHP Limits (php.ini):

Problem: Plugin shows multiple settings tabs instead of single info tab

Cause: Old plugin configuration not properly removed during upgrade

Solution:

• Go to System → Manage → Extensions
• Uninstall ALL three CustomCart extensions
• Clear Joomla cache: System → Clear Cache
• Clear browser cache (Ctrl+Shift+Delete)
• Reinstall package
• Verify plugin now shows single "Plugin" tab with blue info box