Customers

Manage your customer database, track loyalty points, and maintain ledger accounts. Customer data powers the loyalty program, personalized pricing, and reporting.

Loyalty Points

Points are automatically awarded on each purchase. Configure the earn rate and redemption value in vendor settings.

Customer Ledger

Track credit accounts for wholesale and regular customers. Support for "buy now, pay later" workflows.

GET/api/v1/customers

List all customers

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Items per page (default: 20)
search	string	Search by name, email, or phone
sort	string	Sort field: name, created_at, total_spent, loyalty_points
order	string	Sort order: ASC or DESC

Response

[
  {
    "id": "uuid",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+1234567890",
    "address": "123 Main St, City",
    "loyalty_points": 450,
    "total_spent": 125000,
    "total_orders": 28,
    "notes": "Prefers organic products",
    "tags": ["vip", "wholesale"],
    "created_at": "2025-01-15T10:00:00Z"
  }
]

GET/api/v1/customers/:id

Get a single customer with full details

Response

{
  "id": "uuid",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "+1234567890",
  "address": "123 Main St, City",
  "loyalty_points": 450,
  "total_spent": 125000,
  "total_orders": 28,
  "notes": "Prefers organic products",
  "tags": ["vip", "wholesale"],
  "recent_purchases": [
    {
      "id": "uuid",
      "receipt_number": "REC-20250518-001",
      "total": 4500,
      "created_at": "2025-05-18T14:30:00Z"
    }
  ],
  "ledger_balance": -5000,
  "created_at": "2025-01-15T10:00:00Z"
}

Includes recent purchase history and ledger balance. ledger_balance is negative when the customer owes money.

POST/api/v1/customers

Create a new customer

Request Body

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "+1234567890",
  "address": "123 Main St, City",
  "notes": "Referred by John",
  "tags": ["retail"]
}

Response

{
  "id": "uuid",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "+1234567890",
  "loyalty_points": 0,
  "total_spent": 0,
  "created_at": "2025-05-18T10:00:00Z"
}

Required field: name. Email and phone are optional but recommended for loyalty programs.

PUT/api/v1/customers/:id

Update customer details

Request Body

{
  "name": "Jane Smith",
  "phone": "+0987654321",
  "tags": ["vip", "wholesale"]
}

Response

{
  "id": "uuid",
  "name": "Jane Smith",
  "phone": "+0987654321",
  "tags": ["vip", "wholesale"],
  ...
}

Partial updates supported. Tags are replaced entirely (not merged).

DELETE/api/v1/customers/:id

Delete a customer

Response

{
  "message": "Customer deleted successfully"
}

Customers with existing sales history are anonymized rather than fully deleted to preserve transaction records.

GET/api/v1/customers/:id/ledger

Get customer ledger (credit/debit history)

Query Parameters

Parameter	Type	Description
from	date	Start date filter
to	date	End date filter

Response

[
  {
    "id": "uuid",
    "type": "credit",
    "amount": 10000,
    "balance_after": -5000,
    "description": "Payment received",
    "reference_id": "uuid",
    "created_at": "2025-05-18T10:00:00Z"
  },
  {
    "id": "uuid",
    "type": "debit",
    "amount": 15000,
    "balance_after": -15000,
    "description": "Sale REC-20250517-003",
    "reference_id": "uuid",
    "created_at": "2025-05-17T14:00:00Z"
  }
]

Returns a chronological history of credits (payments in) and debits (purchases on account). Useful for "khata" / store-credit systems.

POST/api/v1/customers/:id/loyalty/redeem

Redeem loyalty points

Request Body

{
  "points": 100,
  "sale_id": "uuid"
}

Response

{
  "redeemed": 100,
  "discount_amount": 1000,
  "remaining_points": 350
}

Default conversion: 1 point = $0.10 (configurable in vendor settings). Points are deducted and a discount is applied to the sale.