Customers
Customer data and management
Cursor for pagination (before) - Firestore document ID of customer to paginate before
Cursor for pagination (after) - Firestore document ID of customer to paginate after
Number of customers per page
20Search by customer email address
Filter by customer type
Filter by customer tier ID
Filter customers updated after this date
Filter customers updated before this date
Filter customers created before this date
Sort order for results
createdAt_descPossible values: Include total count in response (may increase response time)
falseApp ID of your shop which retrieved from the Settings page
{{appKey}}Secret Key of your shop which retrieved from the Settings page
{{secretKey}}Paginated list of customers
GET /rest_api/v2/customers HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: text
X-Joy-Loyalty-Secret-Key: text
Accept: */*
Paginated list of customers
{
"success": true,
"data": [
{
"id": "b1wvKrxdDZ11U8tUlyyx",
"shopifyCustomerId": 7801029525739,
"email": "[email protected]",
"name": "John Doe",
"firstName": "John",
"lastName": "Doe",
"type": "member",
"point": 100,
"tierPoint": 100,
"totalEarnedPoints": 100,
"hasPoint": true,
"hasJoinedProgram": true,
"state": "enabled",
"acceptsMarketing": false,
"tierId": "1Fe1kqHZbE7Alx1GmFEC",
"tierName": "Bronze",
"pointsRemain": 4900,
"isCustomerB2B": false,
"earnSignUp": true,
"referralCode": "2kxRoqlDQMp",
"hasTier": true,
"totalSpentCurrencyCode": "VND",
"createdAt": "2025-04-29T10:23:05.991Z",
"updatedAt": "2025-06-16T10:20:58.663Z"
}
],
"meta": {
"pagination": {
"hasNext": true,
"hasPre": false,
"total": 1250,
"totalPage": 63
}
},
"timestamp": "2025-06-16T10:20:58.663Z"
}Internal customer ID
Customer details
Customer not found
GET /rest_api/v2/customers/{customerId} HTTP/1.1
Host: dev-api.joy.so
Accept: */*
{
"success": true,
"data": {
"id": "cust_abc123",
"shopifyCustomerId": 7891234567890,
"email": "[email protected]",
"firstName": "John",
"lastName": "Doe",
"point": 150,
"pointsRemain": 350,
"tierId": "tier_gold_123",
"tierName": "Gold",
"createdAt": "2023-07-15T10:30:00.000Z",
"updatedAt": "2023-07-28T07:27:54.123Z"
}
}Update customer information (supports birthday fields)
Internal customer ID
Date of birth in ISO 8601 format (YYYY-MM-DD)
Birthday in MM/DD format
Customer updated successfully
Invalid request data
Customer not found
PUT /rest_api/v2/customers/{customerId} HTTP/1.1
Host: dev-api.joy.so
Content-Type: application/json
Accept: */*
Content-Length: 28
{
"dateOfBirth": "1990-05-15"
}{
"success": true,
"data": {
"id": "text",
"shopifyCustomerId": "text"
},
"meta": {},
"message": "Operation completed successfully",
"timestamp": "2023-07-28T07:27:54.123Z"
}Retrieve total points earned by a customer across all programs
Customer ID (can be internal ID or Shopify customer ID)
Customer earned points summary
GET /rest_api/v2/customers/{customerId}/points/earned HTTP/1.1
Host: dev-api.joy.so
Accept: */*
Customer earned points summary
{
"success": true,
"data": {
"totalEarnedPoints": 1
},
"meta": {},
"message": "Operation completed successfully",
"timestamp": "2023-07-28T07:27:54.123Z"
}Retrieve customer information using Shopify customer ID
Shopify customer ID
Customer details
Customer not found
GET /rest_api/v2/customers/external/{shopifyCustomerId} HTTP/1.1
Host: dev-api.joy.so
Accept: */*
{
"success": true,
"data": {
"id": "cust_abc123",
"shopifyCustomerId": "7891234567890",
"email": "[email protected]",
"firstName": "John",
"lastName": "Doe",
"point": 150,
"totalEarnedPoints": 300,
"hasPoint": true,
"hasJoinedProgram": true,
"state": "enabled"
}
}Update customer information using Shopify customer ID
Shopify customer ID
Date of birth in ISO 8601 format (YYYY-MM-DD)
Birthday in MM/DD format
Customer updated successfully
PUT /rest_api/v2/customers/external/{shopifyCustomerId} HTTP/1.1
Host: dev-api.joy.so
Content-Type: application/json
Accept: */*
Content-Length: 28
{
"dateOfBirth": "1990-05-15"
}Customer updated successfully
{
"success": true,
"data": {
"id": "text",
"shopifyCustomerId": "text"
},
"meta": {},
"message": "Operation completed successfully",
"timestamp": "2023-07-28T07:27:54.123Z"
}Update customer's VIP tier with comprehensive tier processing
Internal customer ID
Target tier ID
Whether this is an initial tier assignment
falseWhether to trigger tier rewards
trueAdmin note for the tier change activity
Customer tier updated successfully
Invalid request data
Customer or tier not found
PUT /rest_api/v2/customers/{customerId}/tier HTTP/1.1
Host: dev-api.joy.so
Content-Type: application/json
Accept: */*
Content-Length: 107
{
"tierId": "tier_gold_123",
"isInitTier": false,
"triggerReward": true,
"adminNote": "Tier upgraded via REST API"
}{
"success": true,
"data": {
"id": "text",
"shopifyCustomerId": "text",
"tierId": "text",
"tierName": "text",
"tierPoint": 1,
"tierUpdatedAt": "2025-11-03T03:44:52.626Z"
},
"meta": {},
"message": "Operation completed successfully",
"timestamp": "2023-07-28T07:27:54.123Z"
}Update customer's VIP tier using Shopify customer ID
Shopify customer ID
Target tier ID
Whether this is an initial tier assignment
falseWhether to trigger tier rewards
trueAdmin note for the tier change activity
Customer tier updated successfully
PUT /rest_api/v2/customers/external/{shopifyCustomerId}/tier HTTP/1.1
Host: dev-api.joy.so
Content-Type: application/json
Accept: */*
Content-Length: 47
{
"tierId": "tier_gold_123",
"triggerReward": true
}Customer tier updated successfully
{
"success": true,
"data": {
"id": "text",
"shopifyCustomerId": "text",
"tierId": "text",
"tierName": "text",
"tierPoint": 1,
"tierUpdatedAt": "2025-11-03T03:44:52.626Z"
},
"meta": {},
"message": "Operation completed successfully",
"timestamp": "2023-07-28T07:27:54.123Z"
}