​
Shop API Endpoints

The Shop APIs provide comprehensive endpoints for integrating loyalty programs with e-commerce platforms, POS systems, and online stores. These endpoints offer direct shop integration capabilities for customer-facing applications.
All Shop API endpoints are automatically documented from the OpenAPI specification. The following provides an overview of available endpoint categories and their primary use cases.

​
Base URL

  • Staging: https://staging-api.loyalty.lt/{locale}/shop/
  • Production: https://api.loyalty.lt/{locale}/shop/
Where {locale} is the language code (e.g., en, lt).

​
Authentication Categories

​
Customer Authentication

  • Phone + OTP Login: Modern phone-based authentication flow
  • User Registration: New customer onboarding with phone verification
  • QR Code Login: Seamless mobile-to-desktop authentication
  • Token Management: JWT refresh and session management
  • Profile Management: User profile and preferences
Key Endpoints:
  • POST /{locale}/shop/auth/request-otp - Request OTP code
  • POST /{locale}/shop/auth/login - Login with phone + OTP
  • POST /{locale}/shop/auth/register - Register new user
  • GET /{locale}/shop/auth/me - Get current user details
  • PUT /{locale}/shop/auth/profile - Update user profile

​
Core Shop Features

​
Loyalty Cards Management

Complete loyalty card system for customer engagement and retention. Core Features:
  • Personal loyalty card creation and management
  • Third-party card integration (existing store cards)
  • Card balance tracking and history
  • Digital card scanning and validation
Key Endpoints:
  • GET /{locale}/shop/loyalty-cards - List user’s loyalty cards
  • POST /{locale}/shop/loyalty-cards - Create new loyalty card
  • GET /{locale}/shop/loyalty-cards/{id} - Get card details
  • POST /{locale}/shop/loyalty-cards/third-party - Add existing store card

​
Points System

Flexible points management system for rewards and gamification. Core Features:
  • Points earning through purchases and activities
  • Points redemption for rewards
  • Bulk operations for high-volume scenarios
  • Transaction history and balance tracking
  • Points expiration management
Key Endpoints:
  • GET /{locale}/shop/points - List point transactions
  • POST /{locale}/shop/points - Award or deduct points
  • GET /{locale}/shop/points/summary - Points balance summary
  • POST /{locale}/shop/points/bulk - Bulk points operations
  • GET /{locale}/shop/points/card/{card_id}/balance - Get card balance

​
Offers & Coupons System

Dynamic offer management with automated coupon generation. Offers Management:
  • Browse available offers by category
  • Featured offers promotion
  • Personalized offer recommendations
  • Offer claiming and validation
Coupon Management:
  • Active coupon tracking
  • Expiration notifications
  • Redemption processing
  • Usage statistics and analytics
Key Endpoints:
  • GET /{locale}/shop/offers - List available offers
  • GET /{locale}/shop/offers/featured - Get featured offers
  • POST /{locale}/shop/offers/{id}/claim - Claim offer
  • GET /{locale}/shop/coupons - List user coupons
  • POST /{locale}/shop/coupons/{id}/redeem - Redeem coupon

​
Games & Gamification

Interactive games system for customer engagement and point earning. Game Types Supported:
  • Memory Games: Card matching and memory challenges
  • Quiz Games: Knowledge-based point earning
  • Spin Wheel: Random reward games
  • Scratch Cards: Digital scratch-to-win games
  • Stamp Collection: Visit-based loyalty games
Game Features:
  • Real-time game sessions with WebSocket support
  • Progress tracking and validation
  • Reward claiming and distribution
  • Game history and statistics
  • Anti-cheat validation
Key Endpoints:
  • GET /{locale}/shop/games - List available games
  • POST /{locale}/shop/games/{id}/start - Start game session
  • POST /{locale}/shop/games/sessions/{sessionKey}/progress - Update progress
  • POST /{locale}/shop/games/sessions/{sessionKey}/claim-reward - Claim rewards
  • GET /{locale}/shop/user/games/history - Game history

​
Transaction History

Unified transaction tracking across all loyalty activities. Transaction Types:
  • Point transactions (earned/redeemed)
  • Coupon activities (claimed/redeemed)
  • Game rewards and achievements
  • Offer interactions
  • Card activities
Features:
  • Comprehensive transaction history
  • Export capabilities (CSV/JSON)
  • Statistical summaries
  • Advanced filtering and search
Key Endpoints:
  • GET /{locale}/shop/transactions - Get transaction history
  • GET /{locale}/shop/transactions/summary - Transaction summary
  • POST /{locale}/shop/transactions/export - Export data

​
Shop Management

Tools for managing multiple store locations and analytics. Management Features:
  • Multi-store support
  • Location-based services
  • Store analytics and reporting
  • Import/export capabilities
  • Performance metrics
Key Endpoints:
  • GET /{locale}/shop/shops - List shops
  • GET /{locale}/shop/shops/nearby - Find nearby shops
  • GET /{locale}/shop/shops/{id}/analytics - Shop analytics
  • POST /{locale}/shop/shops/import - Bulk import
  • POST /{locale}/shop/shops/export - Data export

​
Integration Features

​
XML Import System

Bulk data import system for migrating existing customer and transaction data. Import Capabilities:
  • Customer data migration
  • Transaction history import
  • Points balance initialization
  • Loyalty card bulk creation
  • Data validation and mapping
Key Endpoints:
  • POST /{locale}/shop/xml-import/from-url - Import from URL
  • POST /{locale}/shop/xml-import/from-file - Upload and import
  • GET /{locale}/shop/xml-import/history - Import history
  • POST /{locale}/shop/xml-import/validate - Validate XML structure

​
Common Features

​
Authentication Methods

  • API Credentials: Server-side authentication using X-API-Key and X-API-Secret headers
  • JWT Tokens: User session authentication for customer-facing operations
  • Partner Authentication: Integrated with partner API auth middleware

​
Rate Limits

  • Standard Rate: 1000 requests per hour per API key
  • Burst Allowance: Up to 100 requests per minute
  • Premium Limits: Higher limits available for enterprise customers

​
Response Format

All endpoints return consistent JSON responses: 
{
  "success": true|false,
  "message": "Operation result message",
  "data": {...},
  "code": "ERROR_CODE" // Only on errors
}

​
Error Handling

  • 400: Validation errors with detailed field information
  • 401: Authentication required or invalid credentials
  • 403: Insufficient permissions for operation
  • 404: Resource not found
  • 429: Rate limit exceeded
  • 500: Server errors with error tracking

​
Health Check

Monitor API availability:
  • GET /shop/health - Service health status
Returns operational status for all Shop API services including authentication, points system, loyalty cards, offers/coupons, games, and XML import functionality.

​
Next Steps

Authentication Guide

Learn how to authenticate requests using API credentials or JWT tokens

Error Handling

Understand error responses and implement proper error handling
All endpoint details, request/response schemas, and examples are automatically generated from the OpenAPI specification. Use the interactive API reference to test endpoints and view complete documentation.