Customers

Overview

The Customers feature provides a lightweight CRM dedicated to logging individuals who shop at the store. Its primary utility is connecting transactions to specific identities and managing customer debt profiles.

Why it exists

Selling anonymously is standard, but local commerce relies heavily on recurring, trust-based relationships. This module allows the business to extend lines of credit (debt) reliably without sticky-notes and pens, improving recovery tracking.

User flow

  1. User navigates to app/dashboard/customers.
  2. The user sees a data table of all customers. They can sort by debtBalance DESC to see who owes them the most.
  3. User selects a Customer row to expand their detailed transaction history.
  4. From here, they can view every historical partial payment or log a new payment to reduce the debt.

UI walkthrough

![Customers Dashboard](../../assets/images/customers/main-view.png) ![Customer Details Modal](../../assets/images/customers/details.png)

Backend logic

When a customer profile is opened:

  • The system parallelizes Prisma queries to fetch Sales where customerId == ID AND DebtPayments where customerId == ID.
  • The frontend computes a combined timeline ledger sorting both events chronologically so the user sees:
    • Monday: Bought $50 on credit. (Balance $50)
    • Wednesday: Paid $20. (Balance $30)

Database tables involved

Tenant Schema:

  • Customer: Contact info and the aggregate debtBalance integer.
  • Sale: History of what caused the debt.
  • DebtPayment: History of payments reducing the debt.

API endpoints

  • GET /api/customers - List customers.
  • POST /api/customers - Create profile.
  • GET /api/customers/:id - Fetch timeline array.

Permissions / roles

  • Owner / Cashier: Both roles can view and mutate customer profiles during checkout flows.

Edge cases

  • If a customer pays MORE than they owe, Next.js sets their debtBalance to a negative integer, functioning locally as store credit.

Validation rules

  • Telephone numbers must match standard E.164 Zod validations for SMS notification features to function later.

Error handling

  • Next.js prevents soft-deleting a customer profile if they have a non-zero debt balance.

Screenshots placeholders

![Debt Warning UI](../../assets/images/customers/debt-warning.png)

Troubleshooting

  • "My customer's debt is wrong." --> Usually caused by a Cashier marking a sale as "Paid" instead of "Debt" in the POS. An Owner must audit the POS history.

Related features