Skip to main content
Manage customer records, track booking history, and control access through blacklisting.

​
Create Customer

Requires authentication.
Create a new customer record.
POST /api/v1/merchant/customers
curl -X POST 'https://api.example.com/api/v1/merchant/customers' \
  --cookie "session_token=your_session_token" \
  --header 'Content-Type: application/json' \
  --data '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone_number": "+1234567890",
    "birthday": "1990-05-15T00:00:00Z",
    "note": "Prefers morning appointments"
  }'
​
first_name
string
required
Customer’s first name
​
last_name
string
required
Customer’s last name
​
email
string
Email address
​
phone_number
string
Phone number
​
birthday
timestamp
Date of birth in ISO 8601 format
​
note
string
Internal notes about the customer

​
Response

Returns 201 Created on success.

​
Update Customer

Requires authentication.
Update customer information.
PUT /api/v1/merchant/customers/{id}
curl -X PUT 'https://api.example.com/api/v1/merchant/customers/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  --cookie "session_token=your_session_token" \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone_number": "+1234567890",
    "birthday": "1990-05-15T00:00:00Z",
    "note": "Updated: Prefers morning appointments, allergic to lavender"
  }'
​
id
string
required
Customer UUID
​
id
string
required
Customer UUID (must match path parameter)
Other body parameters are the same as create.

​
Delete Customer

Requires authentication.
Delete a customer record.
DELETE /api/v1/merchant/customers/{id}
curl -X DELETE 'https://api.example.com/api/v1/merchant/customers/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  --cookie "session_token=your_session_token"
​
id
string
required
Customer UUID to delete
Deleting customers with booking history may affect reporting. Consider using notes or internal flags instead.

​
Get Customer

Requires authentication.
Retrieve a customer’s basic information.
GET /api/v1/merchant/customers/{id}
curl -X GET 'https://api.example.com/api/v1/merchant/customers/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  --cookie "session_token=your_session_token"
​
id
string
required
Customer UUID
​
id
string
Customer UUID
​
first_name
string
First name
​
last_name
string
Last name
​
email
string
Email address
​
phone_number
string
Phone number
​
birthday
timestamp
Date of birth
​
note
string
Internal notes
​
is_dummy
boolean
Whether this is a placeholder customer record

​
Get Customer Statistics

Requires authentication.
Retrieve detailed statistics and booking history for a customer.
GET /api/v1/merchant/customers/{id}/stats
curl -X GET 'https://api.example.com/api/v1/merchant/customers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/stats' \
  --cookie "session_token=your_session_token"
​
id
string
required
Customer UUID
​
id
string
Customer UUID
​
first_name
string
First name
​
last_name
string
Last name
​
email
string
Email address
​
phone_number
string
Phone number
​
birthday
timestamp
Date of birth
​
note
string
Internal notes
​
is_dummy
boolean
Placeholder customer flag
​
is_blacklisted
boolean
Whether customer is blacklisted
​
blacklist_reason
string
Reason for blacklisting
​
times_booked
integer
Total number of bookings made
​
times_cancelled_by_user
integer
Number of bookings cancelled by customer
​
times_upcoming
integer
Number of upcoming bookings
​
bookings
array
Complete booking history

​
Get All Customers

Requires authentication.
Retrieve all customers with summary statistics.
GET /api/v1/merchant/customers
curl -X GET 'https://api.example.com/api/v1/merchant/customers' \
  --cookie "session_token=your_session_token"
Returns an array of customer objects:
​
id
string
Customer UUID
​
first_name
string
First name
​
last_name
string
Last name
​
email
string
Email address
​
phone_number
string
Phone number
​
birthday
timestamp
Date of birth
​
note
string
Internal notes
​
is_dummy
boolean
Placeholder customer flag
​
is_blacklisted
boolean
Blacklist status
​
blacklist_reason
string
Blacklist reason
​
times_booked
integer
Total bookings
​
times_cancelled
integer
Total cancellations

​
Blacklist Customer

Requires authentication.
Add a customer to the blacklist to prevent future bookings.
PUT /api/v1/merchant/customers/{id}/blacklist
curl -X PUT 'https://api.example.com/api/v1/merchant/customers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/blacklist' \
  --cookie "session_token=your_session_token" \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "blacklist_reason": "Multiple no-shows without notice"
  }'
​
id
string
required
Customer UUID
​
id
string
required
Customer UUID (must match path parameter)
​
blacklist_reason
string
Reason for blacklisting (internal use only)

​
Remove from Blacklist

Requires authentication.
Remove a customer from the blacklist.
DELETE /api/v1/merchant/customers/{id}/blacklist
curl -X DELETE 'https://api.example.com/api/v1/merchant/customers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/blacklist' \
  --cookie "session_token=your_session_token"
​
id
string
required
Customer UUID

​
Get Blacklisted Customers

Requires authentication.
Retrieve all blacklisted customers.
GET /api/v1/merchant/customers/blacklist
curl -X GET 'https://api.example.com/api/v1/merchant/customers/blacklist' \
  --cookie "session_token=your_session_token"
Returns an array with the same structure as Get All Customers, filtered to blacklisted customers only.

​
Transfer Bookings

Requires authentication.
Transfer all bookings from one customer to another (useful for merging duplicate records).
PUT /api/v1/merchant/customers/transfer
curl -X PUT 'https://api.example.com/api/v1/merchant/customers/transfer' \
  --cookie "session_token=your_session_token" \
  --header 'Content-Type: application/json' \
  --data '{
    "from_customer_id": "old-customer-uuid",
    "to_customer_id": "new-customer-uuid"
  }'
​
from_customer_id
string
required
UUID of source customer (bookings will be transferred from this customer)
​
to_customer_id
string
required
UUID of destination customer (bookings will be transferred to this customer)

​
Calendar Customers

Get a simplified list of customers for calendar display:
GET /api/v1/merchant/calendar/customers
curl -X GET 'https://api.example.com/api/v1/merchant/calendar/customers' \
  --cookie "session_token=your_session_token"
Returns an optimized array: 
[
  {
    "id": "uuid",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone_number": "+1234567890",
    "birthday": "1990-05-15T00:00:00Z",
    "is_dummy": false,
    "last_visited": "2026-02-15T14:30:00Z"
  }
]

​
Dummy Customers

The system automatically creates “dummy” customer records for walk-ins or bookings without full customer details. These records:
  • Have is_dummy: true
  • May have incomplete information
  • Can be converted to full customer records by updating with complete details
  • Are useful for tracking appointments without requiring full customer profiles

​
Best Practices

​
Customer Data

  1. Email or Phone Required: Collect at least one contact method for booking confirmations
  2. Notes for Context: Use the notes field for preferences, allergies, or special requirements
  3. Birthday Tracking: Collect birthdays to send special offers and reminders

​
Blacklist Usage

  1. Document Reasons: Always include a blacklist_reason for future reference
  2. Review Periodically: Regularly review blacklisted customers
  3. Clear Communication: Inform customers of policies to avoid blacklist scenarios

​
Duplicate Management

Use the transfer bookings endpoint to:
  1. Identify duplicate customer records
  2. Choose the primary record
  3. Transfer all bookings to the primary record
  4. Delete or archive the duplicate
# Example: Merge duplicate customer
PUT /api/v1/merchant/customers/transfer
{"from_customer_id": "duplicate-uuid", "to_customer_id": "primary-uuid"}

# Then delete the duplicate
DELETE /api/v1/merchant/customers/duplicate-uuid

Build docs developers (and LLMs) love

Get started for freeTalk to us