Shared Services Overview
The Loyalteez Shared Services provide a unified API layer for streak tracking, leaderboards, achievements, and perks across all platform integrations. This ensures consistent behavior and enables cross-platform features.
Architecture
Base URL
All shared services are available at:
https://services.loyalteez.app
Services
| Service | Purpose | Endpoints |
|---|---|---|
| Streak Service | Track daily check-ins and activity streaks | /streak/record-activity, /streak/claim-milestone, /streak/status/:brandId/:userIdentifier |
| Leaderboard Service | Generate rankings by various metrics | /leaderboard/:brandId, /leaderboard/update-stats |
| Achievement Service | Track and unlock achievements | /achievements/:brandId/:userIdentifier, /achievements/update-progress |
| Perks Service | Browse and redeem perks | /perks/:brandId, /perks/redeem |
User Identification
All services use platform-agnostic user identifiers in the format:
{platform}_{userId}@loyalteez.app
Examples:
- Discord:
[email protected] - Telegram:
[email protected] - Twitter:
[email protected] - Farcaster:
[email protected] - Shopify:
[email protected]@loyalteez.app(or direct email) - WordPress:
[email protected]@loyalteez.app(or direct email)
Authentication
Shared services use CORS headers and can be called from any platform integration. No authentication is required for public endpoints, but all requests should include proper Content-Type: application/json headers.
Response Format
All endpoints return JSON responses in this format:
{
"success": true,
"data": { ... },
"error": null
}
Error responses:
{
"success": false,
"error": "Error message",
"data": null
}
CORS Support
All endpoints support CORS preflight requests. Include appropriate headers in your requests:
const response = await fetch('https://services.loyalteez.app/streak/record-activity', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
brandId: '0x...',
userIdentifier: '[email protected]',
platform: 'discord',
streakType: 'daily'
})
});
Health Check
Check service health:
GET https://services.loyalteez.app/health
Response:
{
"status": "healthy",
"service": "shared-services",
"timestamp": "2026-01-15T10:30:00.000Z"
}
Platform Integration
Each platform integration should:
- Call shared services for streak, leaderboard, achievement, and perks data
- Use consistent user identifiers following the platform pattern
- Handle errors gracefully with fallback behavior
- Cache responses when appropriate to reduce API calls