Skip to main content

​
Create Customer

Create a new customer or find existing customer by phone number.

​
Endpoint

POST /loyalty/customers

​
Request Body

​
name
string
required
Customer name (1-255 characters)
​
email
string
Email address (must be valid email format)
​
phone
string
Phone number (max 20 characters). If provided, searches for existing customer with this phone
​
birthDate
string
Birth date in ISO 8601 format (YYYY-MM-DD)

​
Behavior

  • If phone is provided and matches an existing customer, returns that customer (not a 409 conflict)
  • Automatically enrolls new customers in the active loyalty program
  • Sets initial tier to Bronze (0 points)

​
Response

​
success
boolean
Request success status
​
data
object
​
id
string
Customer UUID
​
organization_id
string
Organization UUID
​
name
string
Customer name
​
email
string
Email address
​
phone
string
Phone number
​
birth_date
string
Birth date
​
created_at
string
Creation timestamp
​
loyalty
object
Loyalty enrollment details
​
id
string
Loyalty record UUID
​
program_id
string
Program UUID
​
points_balance
number
Current points
​
total_points_earned
number
Lifetime points earned
​
tier_id
string
Current tier UUID

​
Example Request

curl -X POST https://api.restai.app/v1/loyalty/customers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "María García",
    "email": "[email protected]",
    "phone": "+51987654321",
    "birthDate": "1990-05-15"
  }'

​
List Customers

Retrieve customers with optional search and pagination.

​
Endpoint

GET /loyalty/customers

​
Query Parameters

​
search
string
Search in name, email, or phone (partial match)
​
page
number
default:"1"
Page number (minimum: 1)
​
limit
number
default:"20"
Items per page (1-100)

​
Response

​
success
boolean
Request success status
​
data
object
​
customers
array
Array of customer records with loyalty info
​
id
string
Customer UUID
​
name
string
Customer name
​
email
string
Email
​
phone
string
Phone
​
birth_date
string
Birth date
​
created_at
string
Registration date
​
points_balance
number
Current points
​
total_points_earned
number
Lifetime points
​
tier_name
string
Current tier name
​
pagination
object
​
page
number
Current page
​
limit
number
Items per page
​
total
number
Total customers
​
totalPages
number
Total pages

​
Example Request

curl "https://api.restai.app/v1/loyalty/customers?search=maria&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Get Customer Details

Retrieve a customer’s full profile including loyalty info and recent transactions.

​
Endpoint

GET /loyalty/customers/:id

​
Path Parameters

​
id
string
required
Customer UUID

​
Response

Includes customer profile, loyalty enrollment, and last 10 transactions.

​
Example Request

curl https://api.restai.app/v1/loyalty/customers/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Get Customer Transactions

Retrieve paginated transaction history for a customer.

​
Endpoint

GET /loyalty/customers/:id/transactions

​
Path Parameters

​
id
string
required
Customer UUID

​
Query Parameters

​
page
number
default:"1"
Page number
​
limit
number
default:"20"
Items per page (1-100)

​
Example Request

curl "https://api.restai.app/v1/loyalty/customers/550e8400-e29b-41d4-a716-446655440000/transactions?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Delete Customer

Permanently delete a customer and all related loyalty data.

​
Endpoint

DELETE /loyalty/customers/:id

​
Path Parameters

​
id
string
required
Customer UUID

​
Behavior

  • Cascades to delete loyalty enrollment, transactions, and coupon assignments
  • Cannot be undone

​
Example Request

curl -X DELETE https://api.restai.app/v1/loyalty/customers/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Get Loyalty Statistics

Get aggregate loyalty program statistics.

​
Endpoint

GET /loyalty/stats

​
Response

​
success
boolean
Request success status
​
data
object
​
totalCustomers
number
Total customers in organization
​
totalPointsBalance
number
Total unredeemed points across all customers
​
totalPointsEarned
number
Total points earned all-time
​
totalRedemptions
number
Number of reward redemptions
​
activeProgram
object
Currently active program details (if any)
​
id
string
Program UUID
​
name
string
Program name

​
Example Request

curl https://api.restai.app/v1/loyalty/stats \
  -H "Authorization: Bearer YOUR_TOKEN"

Build docs developers (and LLMs) love

Get started for freeTalk to us