Customers Module

Features

API Endpoints

# List customers with filtering
GET /api/v1/customers?search=john&tags=vip&accepts_marketing=true

# Create a customer
POST /api/v1/customers
{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "+919876543210",
  "accepts_marketing": true,
  "tags": ["vip", "wholesale"],
  "addresses": [
    {
      "type": "shipping",
      "is_default": true,
      "address1": "123 Main St",
      "city": "Mumbai",
      "state": "Maharashtra",
      "pincode": "400001"
    }
  ]
}

# Get a customer
GET /api/v1/customers/{id}

# Update a customer
PATCH /api/v1/customers/{id}

# Delete a customer
DELETE /api/v1/customers/{id}

# Search customers
GET /api/v1/customers/search?q=keyword

# Get VIP customers
GET /api/v1/customers/vip

# Get customer segments
GET /api/v1/customers/segments

# Get customer orders
GET /api/v1/customers/{id}/orders

# Merge customers
POST /api/v1/customers/merge
{
  "primary_id": "uuid-to-keep",
  "secondary_id": "uuid-to-merge"
}

# Bulk add tags
POST /api/v1/customers/bulk/tags
{
  "customer_ids": ["uuid-1", "uuid-2"],
  "tags": ["summer-sale", "newsletter"]
}

# Address management
GET /api/v1/customers/{id}/addresses
POST /api/v1/customers/{id}/addresses
PATCH /api/v1/customers/{id}/addresses/{addressId}
DELETE /api/v1/customers/{id}/addresses/{addressId}
POST /api/v1/customers/{id}/addresses/{addressId}/default

TypeScript Types

interface Customer {
  id: string;
  email: string | null;
  phone: string | null;
  first_name: string;
  last_name: string | null;
  full_name: string;

  // Marketing
  accepts_marketing: boolean;

  // Order statistics (auto-calculated)
  total_orders: number;
  total_spent: number;
  avg_order_value: number | null;
  first_order_at: string | null;
  last_order_at: string | null;

  // VIP status
  is_vip: boolean;

  // Metadata
  tags: string[];
  notes: string | null;
  external_ids: Record<string, string>;

  // Addresses
  addresses?: CustomerAddress[];
  default_address?: CustomerAddress | null;

  created_at: string;
  updated_at: string;
}

interface CustomerAddress {
  id: string;
  type: 'billing' | 'shipping';
  is_default: boolean;
  first_name: string | null;
  last_name: string | null;
  company: string | null;
  address1: string;
  address2: string | null;
  city: string;
  state: string;
  pincode: string;
  country: string | null;
  phone: string | null;
}

interface CustomerSegments {
  new: { label: string; count: number };
  returning: { label: string; count: number };
  loyal: { label: string; count: number };
  vip: { label: string; count: number };
  at_risk: { label: string; count: number };
  total: { label: string; count: number };
}

Configuration

The Customers module can be configured via environment variables:

# VIP thresholds (customers with 10+ orders OR 50,000+ spend)
CUSTOMERS_VIP_ORDER_THRESHOLD=10
CUSTOMERS_VIP_SPEND_THRESHOLD=50000

# Pagination
CUSTOMERS_PER_PAGE=20
CUSTOMERS_MAX_PER_PAGE=100

# Marketing consent
CUSTOMERS_ENABLE_MARKETING_CONSENT=true