Customers and reservations

Customers are the merchant’s own records — loyalty members, account customers, delivery addresses. Reservations sit on top of them: every booking belongs to a customer.

Endpoints

Method	Path	Scope
GET	/v1/customers	customers.read
GET	/v1/customers/:id	customers.read
POST	/v1/customers	customers.write
PATCH	/v1/customers/:id	customers.write
GET	/v1/reservations	reservations.read
POST	/v1/reservations	reservations.write
PATCH	/v1/reservations/:id	reservations.write

Create a customer

curl -s "$API_BASE_URL/customers" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Priya Nair",
    "mobile": "+919845012345",
    "email": "priya@example.com",
    "loyaltyNo": "LP-004182",
    "address": "42 Church Street",
    "ZIP": "560001",
    "StoreId": 1
  }'

Field	Type	Required	Notes
name	string	yes	Up to 150 characters
mobile	string	no	Up to 40 characters. The de-facto identity key — see below
email	string	no	Validated as an email address
loyaltyNo	string	no	Loyalty card or membership number, up to 20 characters
loyaltyPoint	number	no	Opening points balance
address, landmark	string	no	Delivery address lines
ZIP	string	no	Postal code
countryId, stateId, state	number / string	no	Location, for tax and reporting
latitude, longitude	number	no	Used for delivery routing
trn	string	no	Tax registration number for B2B invoices
TaxExempt	number	no	1 suppresses tax on this customer’s sales
creditCust	number	no	1 allows sales on account
creditLimit	number	no	Maximum outstanding balance
opening	number	no	Opening balance carried in from another system
birthDate, anniversary	string	no	YYYY-MM-DD, used for campaigns
StoreId	number	no	Home store. 0 means the record is shared across stores
status	number	no	1 active (default), 0 inactive

201 Created

{
  "data": {
    "id": 5521,
    "name": "Priya Nair",
    "mobile": "+919845012345",
    "loyaltyNo": "LP-004182",
    "status": 1
  }
}

Deduplicate on mobile before creating

Merchants match customers by phone number at the till. Search before you create, or you will fragment the loyalty history that the merchant relies on.

curl -s "$API_BASE_URL/customers?mobile=%2B919845012345" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

search matches name, mobile and email; mobile and email filter exactly.

Reservations

curl -s "$API_BASE_URL/reservations" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId": 5521,
    "storeId": 1,
    "reservationDate": "2026-08-14",
    "reservationTime": "19:30",
    "partySize": 4,
    "durationMinutes": 120,
    "occasion": "Anniversary",
    "phone": "+919845012345",
    "note": "Window table if possible"
  }'

Field	Type	Required	Notes
customerId	number	yes	Create the customer first
reservationDate	string	yes	YYYY-MM-DD
reservationTime	string	yes	HH:mm or HH:mm:ss, store-local
partySize	number	yes	Number of covers
durationMinutes	number	no	15–600, default 120
status	string	no	pending (default), confirmed, seated, completed, cancelled
storeId	number	no	Required for multi-store merchants
occasion	string	no	Shown to the host — birthday, anniversary
phone, email, address	string	no	Contact for this booking
customerPreferences	string	no	Allergies, seating preferences
preOrderedFoods	array	no	{ name, quantity, price, notes } per pre-ordered dish
note	string	no	Free-text note for staff

Moving a booking through its states

curl -s -X PATCH "$API_BASE_URL/reservations/318" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "status": "confirmed" }'

pending → confirmed → seated → completed is the normal path; cancelled is terminal from any state. Patch only the fields that change — a status update should not resend the whole booking.

Listing

curl -s "$API_BASE_URL/reservations?storeId=1&fromDate=2026-08-14&toDate=2026-08-14" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Filter by storeId, status, customerId and a date window. Reservations return the customer’s name and phone inline so a host screen needs one call, not two.