Customers API

API for managing customer data

GET /customers

Get all customers

Query Parameters

Parameter	Type	Description	Default
page	number	Current page	1
limit	number	Items per page	20
search	string	Search by name/email/phone	-
group	string	Filter by group	-

Response

{
  "success": true,
  "data": [
    {
      "id": "cust_123456",
      "name": "John Doe",
      "email": "john@email.com",
      "phone": "081-234-5678",
      "group": "VIP",
      "totalBookings": 15,
      "totalSpent": 4500,
      "lastBooking": "2024-01-10T10:00:00Z",
      "createdAt": "2023-06-15T08:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 250,
    "totalPages": 13
  }
}

---

GET /customers/:id

Get customer details by ID

Path Parameters

Parameter	Type	Description
id	string	Customer ID (e.g., cust_123456)

Response

{
  "success": true,
  "data": {
    "id": "cust_123456",
    "name": "John Doe",
    "email": "john@email.com",
    "phone": "081-234-5678",
    "group": "VIP",
    "notes": "Regular customer",
    "preferences": {
      "preferredStaff": "staff_789",
      "preferredServices": ["svc_456", "svc_789"]
    },
    "stats": {
      "totalBookings": 15,
      "completedBookings": 14,
      "cancelledBookings": 1,
      "totalSpent": 4500,
      "averageRating": 4.8
    },
    "bookings": [
      {
        "id": "bk_123456",
        "dateTime": "2024-01-10T10:00:00Z",
        "service": "Haircut",
        "status": "completed"
      }
    ],
    "createdAt": "2023-06-15T08:30:00Z",
    "updatedAt": "2024-01-10T12:00:00Z"
  }
}

---

POST /customers

Create a new customer

Request Body

{
  "name": "John Doe",
  "email": "john@email.com",
  "phone": "081-234-5678",
  "group": "VIP",
  "notes": "Regular customer",
  "preferences": {
    "preferredStaff": "staff_789"
  }
}

Field	Type	Required	Description
name	string	✅	Full name
email	string	✅	Email (must be unique)
phone	string	❌	Phone number
group	string	❌	Customer group
notes	string	❌	Notes
preferences	object	❌	Customer preferences

Response

{
  "success": true,
  "data": {
    "id": "cust_789012",
    "name": "John Doe",
    "email": "john@email.com",
    "phone": "081-234-5678",
    "group": "VIP",
    "createdAt": "2024-01-15T09:00:00Z"
  },
  "message": "Customer created successfully"
}

---

PATCH /customers/:id

Update customer information

Request Body

{
  "name": "John Smith",
  "phone": "089-123-4567",
  "group": "VVIP",
  "notes": "Updated notes"
}

Response

{
  "success": true,
  "data": {
    "id": "cust_123456",
    "name": "John Smith",
    "phone": "089-123-4567",
    "group": "VVIP",
    "updatedAt": "2024-01-15T09:30:00Z"
  },
  "message": "Customer updated successfully"
}

---

DELETE /customers/:id

Delete a customer (Soft delete)

Query Parameters

Parameter	Type	Required	Description
transferBookings	boolean	❌	Transfer bookings to another customer

Response

{
  "success": true,
  "message": "Customer deleted successfully"
}

---

Example Code

Search Customers

async function searchCustomers(query: string) {
  const response = await fetch(
    `https://api.booking-platform.com/v1/customers?search=${encodeURIComponent(query)}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
      },
    }
  );

  const { data } = await response.json();
  return data;
}

// Usage
const customers = await searchCustomers('John');

Create a New Customer with Validation

async function createCustomer(customerData: {
  name: string;
  email: string;
  phone?: string;
}) {
  // Check if email already exists
  const checkResponse = await fetch(
    `https://api.booking-platform.com/v1/customers?search=${customerData.email}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
      },
    }
  );

  const { data: existingCustomers } = await checkResponse.json();
  
  if (existingCustomers.length > 0) {
    throw new Error('This email already exists');
  }

  // Create new customer
  const response = await fetch('https://api.booking-platform.com/v1/customers', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(customerData),
  });

  return response.json();
}

Get Customer History

async function getCustomerHistory(customerId: string) {
  const response = await fetch(
    `https://api.booking-platform.com/v1/customers/${customerId}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
      },
    }
  );

  const { data } = await response.json();
  
  return {
    totalBookings: data.stats.totalBookings,
    totalSpent: data.stats.totalSpent,
    recentBookings: data.bookings.slice(0, 5),
  };
}

---

Next Steps

• Bookings API — View booking details
• API Tester — Test API directly