Customer Management

Part of: MPAC SmartPOS Cloud Platform - Product RequirementsVersion: 2.0 Last Updated: 2026-01-28

---

Overview

The Customer Management domain provides a centralized system for managing registered customers across the merchant ecosystem. It supports personalized service delivery, digital receipt distribution, and comprehensive purchase history tracking. Customer data enables merchants to build lasting relationships with their patrons through targeted engagement.

Table of Contents

• Purpose & Responsibilities
• Customer Entity
• Customer Operations
• API Endpoints Summary

---

Purpose & Responsibilities

Customer Management handles the registration, maintenance, and retrieval of customer profiles for use across the SmartPOS platform. The system is designed to:

• Store and manage customer contact information and preferences
• Track purchase history and visit patterns
• Enable personalized receipt delivery (email, SMS, digital)
• Provide search capabilities for staff to quickly locate customer records
• Maintain customer engagement metrics for merchant analytics

Key Features:

• Multi-language support (Japanese kana names, localized preferences)
• Flexible address storage for Japanese postal conventions
• Customer lifetime value (CLV) tracking
• Privacy-compliant data management
• Integration with order history

---

Customer Entity

The Customer entity represents a registered patron of a merchant organization.

Customer Data Model

{
  "id": "cust_uuid",
  "merchant_id": 1,
  "customer_number": "CUST-000123",
  "name": "Tanaka Taro",
  "name_kana": "タナカ タロウ",
  "phone": "+81-90-1234-5678",
  "email": "tanaka@example.com",
  "date_of_birth": "1990-01-15",
  "gender": "male",
  "address": {
    "postal_code": "100-0001",
    "prefecture": "Tokyo",
    "city": "Chiyoda",
    "street": "1-1-1 Chiyoda"
  },
  "preferences": {
    "receipt_delivery": "email",
    "language": "ja"
  },
  "total_spent": 500000,
  "total_visits": 50,

  "is_active": true,
  "created_at": "2025-01-01T00:00:00Z",
  "last_visit": "2026-01-28T10:00:00Z"
}

Field Descriptions

• id - Unique customer identifier (UUID)
• merchant_id - Merchant who owns this customer record
• customer_number - Human-readable customer identifier (auto-generated)
• name - Customer's full name (romanized or native script)
• name_kana - Japanese kana representation for phonetic sorting
• phone - Contact phone number (E.164 format recommended)
• email - Email address for digital receipts and communications
• date_of_birth - Birth date (ISO 8601 format)
• gender - Gender identifier (male, female, other, prefer_not_to_say)
• address - Structured address object (Japanese postal format)
• preferences - Customer preferences object
  • receipt_delivery - Preferred receipt method (email, sms, print, none)
  • language - Interface language preference (ja, en)
• total_spent - Lifetime spending amount (in currency minor units)
• total_visits - Total number of store visits/transactions
• is_active - Account status (active/inactive)
• created_at - Registration timestamp
• last_visit - Most recent transaction timestamp

---

Customer Operations

Create/Update Customer Profile

Create New Customer:

• Collect basic contact information (phone or email required)
• Generate unique customer_number
• Initialize total_spent and total_visits counters
• Validate data format and uniqueness constraints

Update Existing Customer:

• Allow modification of contact details and preferences
• Prevent changes to merchant_id and customer_number
• Maintain audit trail of changes
• Re-validate data integrity on updates

Search Capabilities

Search by Multiple Criteria:

• Phone number (partial or exact match)
• Email address (partial or exact match)
• Customer number (exact match)
• Name (fuzzy search, supporting both name and name_kana)

Search Features:

• Case-insensitive matching
• Wildcard support for partial matches
• Pagination for large result sets
• Sorting options (name, last_visit, total_spent)

Purchase History

View Transaction History:

• List all orders associated with customer
• Filter by date range, store, or order status
• Show order totals, items purchased, and payment methods
• Link to detailed order records

Analytics Provided:

• Average order value
• Frequency of visits
• Favorite items/categories
• Spending trends over time

Receipt Delivery Preferences

Supported Delivery Methods:

• Email - Send PDF/HTML receipt to email address
• SMS - Send receipt link or summary via SMS
• Print - Traditional printed receipt
• None - Customer declines receipt

Preference Management:

• Allow customer to update preference at any time
• Support per-transaction override of default preference
• Track delivery success/failure for audit purposes

---

API Endpoints Summary

Method	Endpoint	Purpose
POST	/customers	Create new customer profile
GET	/customers	Search customers by phone/email/name/customer_number
GET	/customers/{id}	Retrieve customer details by ID
PATCH	/customers/{id}	Update customer profile information
GET	/customers/{id}/orders	List purchase history for customer

Endpoint Details

POST /customers

• Auth: Store Manager+
• Request: Customer profile data
• Response: Created customer with generated ID and customer_number
• Validation: Unique phone/email within merchant

GET /customers

• Auth: Store Manager+
• Query Params: phone, email, customer_number, name, limit, offset
• Response: Paginated list of matching customers
• Notes: At least one search parameter required

GET /customers/{id}

• Auth: Store Manager+
• Response: Complete customer profile
• Error: 404 if customer not found or belongs to different merchant

PATCH /customers/{id}

• Auth: Store Manager+
• Request: Partial customer data (only fields to update)
• Response: Updated customer profile
• Validation: Maintain data integrity constraints

GET /customers/{id}/orders

• Auth: Store Manager+
• Query Params: start_date, end_date, limit, offset
• Response: Paginated list of orders with summaries
• Sorting: Default by order_date DESC

---

See Also

Related Domains:

• Order & Bill - Order management and customer purchase tracking
• Reporting & Analytics - Customer analytics and engagement reports

Technical Implementation:

• Database Architecture - Customer data models and relationships
• Security Architecture - Data privacy and access controls

API Reference:

• API Endpoints - Complete API specification for customer endpoints

---

Navigation: ↑ Back to Domain Catalog | ← Previous: Payment Gateway | Next: Receipt & Invoice →