Customer Management

The Customer Management system provides comprehensive tools for managing customer accounts, tracking purchase history, managing reward points, and handling customer interactions.

Customer Overview

Each customer account in OpenCart includes:

Personal Information - Name, email, telephone
Customer Group - Membership tier and pricing group
Multiple Addresses - Billing and shipping addresses
Order History - Complete purchase history
Transactions - Credit balance and transactions
Reward Points - Loyalty program points
Login History - Access tracking and security
Custom Fields - Additional customer data

Customer Filters

Find customers using comprehensive search filters:

Available Filters

$filter_data = [
    'filter_name'              => 'John Smith',
    'filter_email'             => '[email protected]',
    'filter_customer_group_id' => 1,
    'filter_status'            => 1,
    'filter_ip'                => '192.168.1.1',
    'filter_date_from'         => '2026-01-01',
    'filter_date_to'           => '2026-03-31',
    'sort'                     => 'name',
    'order'                    => 'ASC',
    'start'                    => 0,
    'limit'                    => 20
];

Use the IP filter to identify customers from the same location or detect potential fraud. The system tracks all IP addresses used for customer logins and orders.

Customer Structure

Basic Customer Information

$customer_data = [
    'customer_id'       => 0,     // Auto-generated
    'store_id'          => 0,     // Store where registered
    'language_id'       => 1,     // Preferred language
    'customer_group_id' => 1,     // Default customer group
    'firstname'         => 'John',
    'lastname'          => 'Smith',
    'email'             => '[email protected]',
    'telephone'         => '+1-555-0123',
    'custom_field'      => [],    // Additional fields
    'newsletter'        => 1,     // Newsletter subscription
    'password'          => '',    // Encrypted password
    'status'            => 1,     // 1 = active, 0 = disabled
    'safe'              => 0,     // Safe from automatic deletion
    'commenter'         => 1      // Can post reviews/comments
];

Required Fields:

Firstname (1-32 characters)
Lastname (1-32 characters)
Email (valid email format)
Telephone (3-32 characters, if telephone is required in settings)
Customer Group ID

Customer Groups

Assign customers to groups for pricing and permissions:

$customer_groups = [
    1 => 'Default',
    2 => 'Wholesale',
    3 => 'VIP',
    4 => 'Reseller'
];

Customer groups control:

Product pricing (special prices per group)
Tax class assignments
Payment method availability
Shipping method availability
Discount eligibility

Customer Group Configuration

$customer_group_config = [
    'customer_group_id' => 2,
    'approval'          => 1,  // Requires admin approval
    'sort_order'        => 1,
    'description'       => [
        1 => [
            'name'        => 'Wholesale',
            'description' => 'Wholesale customers get special pricing'
        ]
    ]
];

Customer Addresses

Manage multiple addresses per customer:

$customer_addresses = [
    [
        'address_id'    => 1,
        'firstname'     => 'John',
        'lastname'      => 'Smith',
        'company'       => 'Acme Corp',
        'address_1'     => '123 Main Street',
        'address_2'     => 'Suite 100',
        'city'          => 'New York',
        'postcode'      => '10001',
        'country_id'    => 223,
        'zone_id'       => 48,
        'custom_field'  => [],
        'default'       => 1  // Default address
    ]
];

Each customer can have unlimited addresses. One address must be marked as the default, which is used automatically at checkout.

Password Management

Password Requirements

Password validation based on store settings:

$password_requirements = [
    'min_length'  => 8,      // Minimum password length
    'uppercase'   => true,   // Require uppercase letter
    'lowercase'   => true,   // Require lowercase letter
    'number'      => true,   // Require number
    'symbol'      => false   // Require special character
];

Passwords are hashed using strong encryption. Never store or display plain-text passwords. When changing a customer’s password, always require confirmation.

Custom Fields

Add custom data fields to customer accounts:

$custom_fields = [
    [
        'custom_field_id' => 1,
        'name'            => 'Company Tax ID',
        'type'            => 'text',
        'value'           => '',
        'location'        => 'account',
        'required'        => 1,
        'status'          => 1,
        'sort_order'      => 1,
        'validation'      => '^[0-9]{9}$'  // Regex validation
    ]
];

Custom field types:

text - Single-line text input
textarea - Multi-line text input
select - Dropdown selection
radio - Radio button selection
checkbox - Checkbox selection
date - Date picker
time - Time picker
datetime - Date and time picker

Customer History

Track notes and interactions with customers:

$customer_histories = [
    [
        'customer_history_id' => 1,
        'comment'             => 'Customer requested wholesale pricing',
        'date_added'          => '2026-03-04 10:30:00'
    ],
    [
        'customer_history_id' => 2,
        'comment'             => 'Upgraded to VIP customer group',
        'date_added'          => '2026-03-05 14:20:00'
    ]
];

Adding Customer History

// Add note to customer account
$this->model_customer_customer->addHistory(
    $customer_id,
    'Customer called regarding shipping delay'
);

Transaction Management

Manage customer credit balance:

$transactions = [
    [
        'customer_transaction_id' => 1,
        'order_id'                => 12345,
        'description'             => 'Order #12345',
        'amount'                  => -25.00,  // Debit
        'date_added'              => '2026-03-04 10:30:00'
    ],
    [
        'customer_transaction_id' => 2,
        'order_id'                => 0,
        'description'             => 'Store credit added',
        'amount'                  => 50.00,   // Credit
        'date_added'              => '2026-03-05 11:00:00'
    ]
];

// Current balance
$balance = 25.00;

Adding Transactions

// Add credit to customer account
$this->model_customer_customer->addTransaction(
    $customer_id,
    'Refund for order #12345',
    50.00  // Positive = credit, Negative = debit
);

Transactions can be used for store credit, refunds, or custom payment adjustments. The balance is calculated from all transaction history.

Reward Points

Manage loyalty program points:

$reward_points = [
    [
        'customer_reward_id' => 1,
        'order_id'           => 12345,
        'description'        => 'Purchase - Order #12345',
        'points'             => 100,  // Points earned
        'date_added'         => '2026-03-04 10:30:00'
    ],
    [
        'customer_reward_id' => 2,
        'order_id'           => 12346,
        'description'        => 'Redeemed - Order #12346',
        'points'             => -50,  // Points spent
        'date_added'         => '2026-03-10 15:00:00'
    ]
];

// Current point balance
$reward_balance = 50;

Managing Reward Points

// Add reward points
$this->model_customer_customer->addReward(
    $customer_id,
    'Bonus points for review',
    25  // Positive = add points, Negative = deduct points
);

Reward Point Configuration

Reward points are configured per product:

$product_reward = [
    1 => ['points' => 100], // Default customer group
    2 => ['points' => 150]  // Wholesale customer group
];

Customers earn different point amounts based on their customer group.

IP Address Tracking

Monitor customer activity and detect fraud:

$customer_ips = [
    [
        'customer_ip_id' => 1,
        'customer_id'    => 100,
        'store_id'       => 0,
        'ip'             => '192.168.1.100',
        'date_added'     => '2026-03-04 10:30:00'
    ]
];

// Count customers using same IP
$total_accounts = $this->model_customer_customer->getTotalCustomersByIp('192.168.1.100');

Multiple accounts from the same IP address may indicate:

Shared household/office network
Potential fraud or abuse
VPN or proxy usage

Investigate suspicious patterns before taking action.

Track and limit failed login attempts:

$login_attempts = [
    'email'       => '[email protected]',
    'ip'          => '192.168.1.100',
    'total'       => 5,
    'date_added'  => '2026-03-04 10:30:00'
];

// Check if account is locked
$max_attempts = 5;  // Configurable in settings
if ($login_attempts['total'] >= $max_attempts) {
    // Account locked - display unlock option
}

Unlocking Accounts

// Unlock customer account
$this->model_customer_customer->deleteLoginAttempts('[email protected]');

Login attempt tracking helps prevent brute force attacks. Administrators can unlock accounts from the customer management page.

Authorization Tokens

Manage customer authentication tokens:

$authorizations = [
    [
        'customer_authorize_id' => 1,
        'token'                 => 'abc123...',
        'ip'                    => '192.168.1.100',
        'user_agent'            => 'Mozilla/5.0...',
        'status'                => 1,
        'date_added'            => '2026-03-04 10:30:00',
        'date_expire'           => '2026-03-11 10:30:00'
    ]
];

Tokens are used for:

Remember me functionality
Email verification
Password reset links
Single sign-on

// Generate login token
$token = oc_token(32);
$this->model_customer_customer->addToken($customer_id, 'login', $token);

// Redirect to storefront with token
$login_url = HTTP_CATALOG . 'index.php?route=account/login.token'
    . '&email=' . urlencode($customer_email)
    . '&code=' . $token;

Admin-initiated logins create audit trails. Use this feature only when necessary for customer support and with customer permission.

Manage newsletter subscriptions:

$customer['newsletter'] = 1;  // 1 = subscribed, 0 = unsubscribed

Newsletter subscription status is stored per customer. Use this for email marketing campaigns and updates.

Customer Status Flags

Status Field

$customer['status'] = 1;  // 1 = enabled, 0 = disabled

Disabled customers cannot:

Login to their account
Place new orders
Access customer-only content

Safe Flag

$customer['safe'] = 1;  // 1 = protected, 0 = not protected

The safe flag protects customers from:

Automatic deletion scripts
Bulk cleanup operations
Data purging

Commenter Flag

$customer['commenter'] = 1;  // 1 = can comment, 0 = cannot comment

Controls whether customer can:

Post product reviews
Comment on blog posts
Participate in discussions

Bulk Operations

Enable Customers

Activate multiple customer accounts

Disable Customers

Deactivate accounts without deletion

Delete Customers

Remove customer accounts and data

Export Customers

Export customer data for analysis

Deleting customers removes:

Customer account data
Address information
Order history references
Transaction records
Reward points

Consider disabling accounts instead of deleting them.

Best Practices

Verify Email Addresses - Ensure customers use valid email addresses
Monitor Login Attempts - Watch for suspicious login activity
Use Customer Groups - Organize customers by pricing tier
Add Notes Regularly - Document customer interactions
Manage Reward Points - Keep loyalty program balanced
Check IP Addresses - Identify potential fraud patterns
Backup Customer Data - Regular backups of customer information
Review Transactions - Monitor credit balance usage
Update Custom Fields - Keep additional data current
Protect Privacy - Follow data protection regulations

Customer Autocomplete

Search for customers in forms:

// Autocomplete search
$filter_data = [
    'filter_name'  => 'John',
    'filter_email' => 'john@',
    'start'        => 0,
    'limit'        => 5  // Config: config_autocomplete_limit
];

$results = $this->model_customer_customer->getCustomers($filter_data);

Autocomplete helps quickly find customers when creating orders, viewing details, or linking customer data.

Technical Reference

Controller

Location: /upload/admin/controller/customer/customer.php Key methods:

index() - Display customer listing
form() - Show add/edit customer form
save() - Save customer data
delete() - Delete customers
enable() / disable() - Toggle customer status
unlock() - Unlock customer account
login() - Admin-initiated customer login
addHistory() - Add customer note
addTransaction() - Add credit/debit
addReward() - Add reward points
autocomplete() - Search customers

Model

Location: /upload/admin/model/customer/customer.php Key methods:

addCustomer() - Create customer
editCustomer() - Update customer
deleteCustomer() - Remove customer
getCustomer() - Fetch customer data
getCustomers() - Get customer list
getAddresses() - Get customer addresses
getHistories() - Get customer notes
getTransactions() - Get transactions
getRewards() - Get reward points
getIps() - Get IP addresses
getTotalLoginAttempts() - Check login attempts
deleteLoginAttempts() - Unlock account

Database Tables

oc_customer - Main customer data
oc_address - Customer addresses
oc_customer_history - Customer notes
oc_customer_transaction - Credit transactions
oc_customer_reward - Reward points
oc_customer_ip - IP address tracking
oc_customer_login - Login attempts
oc_customer_authorize - Auth tokens

Order Management - Processing customer orders
Catalog Management - Products customers purchase
Product Management - Individual product details

Get Started

Store Management

Design & Layout

Extensions

Configuration

Marketing

​Customer Overview

​Customer Filters

​Available Filters

​Customer Structure

​Basic Customer Information

​Customer Groups

​Customer Addresses

​Password Management

​Password Requirements

​Custom Fields

​Customer History

​Transaction Management

​Adding Transactions

​Reward Points

​Managing Reward Points

​IP Address Tracking

​Login Security

​Login Attempts

​Unlocking Accounts

​Authorization Tokens

​Customer Login

​Admin-Initiated Login

​Newsletter Management

​Customer Status Flags

​Status Field

​Safe Flag

​Commenter Flag

​Bulk Operations

Enable Customers

Disable Customers

Delete Customers

Export Customers

​Best Practices

​Customer Autocomplete

​Technical Reference

​Controller

​Model

​Database Tables

​Related Documentation

Build docs developers (and LLMs) love

Customer Overview

Customer Filters

Available Filters

Customer Structure

Basic Customer Information

Customer Groups

Customer Addresses

Password Management

Password Requirements

Custom Fields

Customer History

Transaction Management

Adding Transactions

Reward Points

Managing Reward Points

IP Address Tracking

Login Security

Login Attempts

Unlocking Accounts

Authorization Tokens

Customer Login

Admin-Initiated Login

Newsletter Management

Customer Status Flags

Status Field

Safe Flag

Commenter Flag

Bulk Operations

Best Practices

Customer Autocomplete

Technical Reference

Controller

Model

Database Tables

Related Documentation