AutoCom Docs

Customers Module

The Customers module maintains unified customer profiles that merge data from multiple sources—store platforms, communication channels, and manual entries.

Overview

Customer profiles in Auto Commerce:

  • Unified: Merge customer data from Shopify, WooCommerce, WhatsApp, etc.
  • Multi-channel: Track interactions across stores, support, and marketing
  • Analytics-rich: Lifetime value, purchase patterns, engagement metrics
  • Privacy-focused: Each tenant's customer data is completely isolated

Data Model

Core Customer Fields

id: UUID
external_ids: JSON ({"shopify": "123", "whatsapp": "+91..."})
email: string
phone: string
first_name: string
last_name: string
accepts_marketing: boolean
total_orders: integer
total_spent: decimal
avg_order_value: decimal
first_order_at: timestamp
last_order_at: timestamp
tags: array

Customer Identity Merging

Auto Commerce automatically merges customer records from different sources:

  1. Primary match: Email or phone number
  2. Secondary match: Name + similar contact info
  3. Manual merge: Admin can merge duplicate profiles

Example:

{
  "id": "uuid-123",
  "email": "customer@example.com",
  "external_ids": {
    "shopify": "cust_shopify_456",
    "woocommerce": "789",
    "whatsapp": "+919876543210"
  }
}

Customer Addresses

id: UUID
customer_id: UUID
type: 'billing' | 'shipping'
is_default: boolean
first_name: string
last_name: string
company: string
address1: string
address2: string
city: string
state: string
pincode: string
country: string
phone: string

Customer Metadata

Modules can store additional data:

id: UUID
customer_id: UUID
key: string
value: string
module_source: string

API Endpoints

List Customers

GET /api/v1/customers

Query Parameters:

  • page: Page number
  • per_page: Items per page
  • search: Search by name, email, or phone
  • tags: Filter by tags
  • source_module: Filter by source

Response:

{
  "data": [
    {
      "id": "uuid",
      "email": "customer@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "total_orders": 5,
      "total_spent": 25000.00,
      "tags": ["vip", "repeat-customer"]
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 10,
    "total_items": 200
  }
}

Get Customer

GET /api/v1/customers/{id}

Includes:

  • Customer profile
  • All addresses
  • Order history
  • Communication history
  • Custom metadata

Create Customer

POST /api/v1/customers

Request Body:

{
  "email": "customer@example.com",
  "phone": "+919876543210",
  "first_name": "John",
  "last_name": "Doe",
  "accepts_marketing": true,
  "tags": ["new-customer"]
}

Update Customer

PATCH /api/v1/customers/{id}

Get Customer Orders

GET /api/v1/customers/{id}/orders

Customer Segmentation

Tags

Apply tags for segmentation:

  • vip - High-value customers
  • repeat-customer - Multiple purchases
  • at-risk - Haven't ordered recently
  • abandoned-cart - Left items in cart

Smart Segments

Auto-generated segments based on behavior:

High-Value Customers:

  • Total spent > ₹50,000
  • Average order value > ₹5,000

At-Risk Customers:

  • Last order > 90 days ago
  • Previously active (5+ orders)

New Customers:

  • First order within last 30 days
  • Total orders = 1

Customer Analytics

Lifetime Value (LTV)

LTV = Average Order Value × Purchase Frequency × Customer Lifespan

Tracked automatically for each customer.

Purchase Patterns

  • Average days between orders
  • Preferred product categories
  • Typical order value range
  • Best communication channel

Engagement Metrics

  • Email open rate
  • WhatsApp response rate
  • Support ticket count
  • Review/feedback submissions

Privacy & Compliance

Data Export

Customers can request their data:

GET /api/v1/customers/{id}/export

Returns all data in JSON format.

Data Deletion

GDPR-compliant deletion:

DELETE /api/v1/customers/{id}

Options:

  • Hard delete: Completely remove customer
  • Anonymize: Keep order history but remove personal info

Module Integration

Customer Events

Event::listen(CustomerCreated::class, function ($event) {
    // Send welcome email
    // Add to marketing list
});

Event::listen(CustomerUpdated::class, function ($event) {
    // Sync to external CRM
});

Adding Customer Data

CustomerService::addMetadata($customerId, 'loyalty_points', '1250', 'loyalty-module');

Best Practices

  1. Always capture email or phone: Required for customer identification
  2. Enable marketing opt-in: Respect customer preferences
  3. Use tags effectively: Segment customers for targeted campaigns
  4. Monitor customer health: Track at-risk and high-value customers
  5. Regular data hygiene: Merge duplicates and clean invalid data

Next Steps