Favorites & Wishlist
6 API calls in this section.
Get User Favorites
/storefront/favorites?page=1&limit=20&market_id={{market_id}}Retrieves the authenticated user's favorite products with pagination support. Shows comprehensive product details including current pricing and availability. Note: Search and category filtering have been removed from this API for performance optimization (avoiding JOIN table queries). For advanced filtering, consider implementing client-side filtering after fetching the data. Authentication: - Required: Valid Bearer token for user identification Query Parameters: - page (optional): Page number for pagination (default: 1) - limit (optional): Items per page (default: 20, max: 100) - market_id (optional): Filter favorites by specific market Performance Optimization: - Removed Features: Search by product name and category filtering to avoid expensive JOIN operations - Recommendation: Implement search and category filtering on the client side after fetching favorites data - Benefits: Faster query execution and reduced database load Features: - Paginated results for large wishlist management - Real-time product availability status - Current pricing information - Product images and details - Multi-language product information - Market-specific filtering - Favorite date tracking - Optimized query performance Response Data: - Complete favorite items with product details - Current product pricing and availability - Favorite creation timestamps - Pagination metadata - Product categories and descriptions - Stock availability indicators Client-Side Filtering Suggestions: - Filter by product name using JavaScript array methods - Group favorites by category after fetching - Implement local search functionality - Cache favorites data for better performance Use Cases: - Wishlist page rendering - Favorite products management - Price tracking for saved items - Cross-market favorite comparison - Mobile app favorites sync
1curl --request GET "$ONDI_BASE_URL/storefront/favorites?page=1&limit=20&market_id={{market_id}}" \2 --header "Authorization: Bearer {{access_token}}"Query parameters
pageOptional1
Page number for pagination (default: 1)
limitOptional20
Items per page (default: 20, max: 100)
market_idOptional{{market_id}}
Filter favorites by specific market (optional)
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for authenticated users (required)
Responses
1{2 "success": true,3 "favorites": [4 {5 "id": "favorite-uuid-1",6 "user_id": "user-uuid-456",7 "variant_id": "variant-uuid-123",8 "variant_slug": "iphone-15-pro-natural-titanium",9 "product_id": "product-uuid-abc",10 "product_slug": "iphone-15-pro",11 "has_variant": true,12 "created_at": "2023-12-01T10:00:00Z",13 "updated_at": null,14 "catalog_item": {15 "id": "variant-uuid-123",16 "slug": "iphone-15-pro-natural-titanium",17 "product_id": "product-uuid-abc",18 "name": {19 "en": "iPhone 15 Pro",20 "ar": "آيفون 15 برو",21 "ku": "ئایفۆن 15 پرۆ"22 },23 "description": {24 "en": "Latest iPhone with advanced camera system"25 },26 "price": 999.99,27 "images": [28 "https://example.com/iphone15-pro-1.jpg"29 ],30 "is_active": true31 },32 "is_available": true,33 "current_price": 999.99,34 "availability_status": "available"35 },36 {37 "id": "favorite-uuid-2",38 "user_id": "user-uuid-456",39 "variant_id": "variant-uuid-789",40 "variant_slug": "premium-cotton-tshirt-white",41 "product_id": "product-uuid-def",42 "product_slug": "premium-cotton-tshirt",43 "has_variant": false,44 "created_at": "2023-11-28T15:30:00Z",45 "updated_at": null,46 "catalog_item": {47 "id": "variant-uuid-789",48 "slug": "premium-cotton-tshirt-white",49 "product_id": "product-uuid-def",50 "name": {51 "en": "Premium Cotton T-Shirt"52 },53 "price": 89.99,54 "images": [55 "https://example.com/tshirt-1.jpg"56 ],57 "is_active": false58 },59 "is_available": false,60 "current_price": 89.99,61 "availability_status": "inactive"62 }63 ],64 "pagination": {65 "page": 1,66 "limit": 20,67 "total": 2,68 "totalPages": 169 }70}1{2 "success": true,3 "data": {4 "favorites": [],5 "pagination": {6 "page": 1,7 "limit": 20,8 "total": 0,9 "totalPages": 010 }11 }12}1{2 "success": false,3 "message": "Authentication required"4}Add to Favorites
/storefront/favoritesAdds a product to the user's favorites/wishlist. Prevents duplicate entries and provides detailed product information in response. Authentication: - Required: Valid Bearer token for user identification Request Body: - variant_id (required): UUID of the product to add to favorites Features: - Duplicate prevention (product can only be favorited once) - Product validation (ensures product exists and is accessible) - Immediate product details in response - Cross-market favorite support - Favorite timestamp recording Business Rules: - User must be authenticated - Product must exist and be accessible - Cannot add the same product to favorites twice - Product can be from any market the user has access to Response Data: - Created favorite item with ID - Complete product details - Current pricing and availability - Market information - Creation timestamp Use Cases: - Product page "Add to Wishlist" action - Quick favoriting from product listings - Cross-market product saving - Price tracking setup - Mobile app wishlist sync
1curl --request POST "$ONDI_BASE_URL/storefront/favorites" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json" \4 --header "Content-Type: application/json" \5 --data '{6 "variant_id": "variant-uuid-123"7}'1{2 "variant_id": "variant-uuid-123"3}Request body fields
variant_idExampleExample field from the request body.
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for authenticated users (required)
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "favorite": {4 "id": "favorite-uuid-new",5 "user_id": "user-uuid-456",6 "variant_id": "variant-uuid-123",7 "variant_slug": "macbook-pro-14-space-black",8 "product_id": "product-uuid-abc",9 "product_slug": "macbook-pro-14",10 "has_variant": true,11 "created_at": "2023-12-01T18:00:00Z",12 "updated_at": null,13 "catalog_item": {14 "id": "variant-uuid-123",15 "slug": "macbook-pro-14-space-black",16 "product_id": "product-uuid-abc",17 "name": {18 "en": "MacBook Pro 14-inch",19 "ar": "ماك بوك برو 14 بوصة"20 },21 "description": {22 "en": "Powerful laptop with M3 Pro chip"23 },24 "price": 1999.99,25 "images": [26 "https://example.com/macbook-pro-1.jpg"27 ],28 "is_active": true29 },30 "is_available": true,31 "current_price": 1999.99,32 "availability_status": "available"33 },34 "message": "Added to favorites"35}1{2 "success": false,3 "message": "Product is already in your favorites"4}1{2 "success": false,3 "message": "Product not found or not accessible"4}1{2 "success": false,3 "message": "Validation failed",4 "errors": [5 {6 "field": "variant_id",7 "message": "Field is required"8 }9 ]10}Remove from Favorites
/storefront/favorites/:favorite_idRemoves a specific item from the user's favorites/wishlist by favorite ID. Authentication: - Required: Valid Bearer token for user identification Path Parameters: - favorite_id (required): UUID of the favorite item to remove Features: - Safe removal with ownership validation - Immediate confirmation - Clean database cleanup - No cascade effects on product data Business Rules: - User must be authenticated - User can only remove their own favorites - Favorite must exist - Removal is immediate and permanent Response Data: - Success confirmation message - Removal timestamp Use Cases: - Wishlist management - "Remove from Favorites" button action - Favorites cleanup - Wishlist organization
1curl --request DELETE "$ONDI_BASE_URL/storefront/favorites/:favorite_id" \2 --header "Authorization: Bearer {{access_token}}"Path parameters
favorite_idRequiredfavorite-uuid-123
UUID of the favorite item to remove
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for authenticated users (required)
Responses
1{2 "success": true,3 "data": {4 "message": "Product removed from favorites successfully",5 "removed_at": "2023-12-01T18:30:00Z"6 }7}1{2 "success": false,3 "message": "Favorite item not found"4}1{2 "success": false,3 "message": "Unauthorized to access this favorite item"4}Check Favorite Status
/storefront/products/:product_id/favorite-statusChecks whether a specific product is in the user's favorites list. Useful for UI state management on product pages. Authentication: - Required: Valid Bearer token for user identification Path Parameters: - product_id (required): UUID of the product to check Features: - Quick favorite status lookup - Favorite ID return for easy removal - UI state management support - Fast response for real-time updates Response Data: - Boolean favorite status - Favorite ID if favorited - Favorite creation date if favorited Use Cases: - Product page heart/favorite icon state - Product listing favorite indicators - UI component state management - Mobile app synchronization - Batch favorite status checking
1curl --request GET "$ONDI_BASE_URL/storefront/products/:product_id/favorite-status" \2 --header "Authorization: Bearer {{access_token}}"Path parameters
product_idRequiredproduct-uuid-123
UUID of the product to check favorite status
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for authenticated users (required)
Responses
1{2 "success": true,3 "data": {4 "is_favorited": true,5 "favorite_id": "favorite-uuid-456",6 "favorited_at": "2023-12-01T10:00:00Z"7 }8}1{2 "success": true,3 "data": {4 "is_favorited": false,5 "favorite_id": null,6 "favorited_at": null7 }8}1{2 "success": false,3 "message": "Product not found"4}Get Favorite Updates
/storefront/favorites/updatesRetrieves favorites with availability and pricing updates. Useful for notifying users about changes to their wishlist items. Authentication: - Required: Valid Bearer token for user identification Features: - Tracks newly available products - Monitors price changes (increases and decreases) - Identifies out-of-stock items - Provides update summaries - Supports notification systems Update Categories: - Newly Available: Products that were out of stock and are now available - Price Changed: Products with price modifications - Out of Stock: Products that became unavailable Response Data: - Categorized favorite updates - Detailed change information - Update summaries and counts - Product details for each update Use Cases: - Wishlist notification system - Price drop alerts - Stock availability notifications - Email/push notification content - Dashboard activity feeds
1curl --request GET "$ONDI_BASE_URL/storefront/favorites/updates" \2 --header "Authorization: Bearer {{access_token}}"Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for authenticated users (required)
Responses
1{2 "success": true,3 "data": {4 "newly_available": [5 {6 "id": "favorite-uuid-1",7 "variant_id": "variant-uuid-123",8 "variant": {9 "id": "variant-uuid-123",10 "market_id": "market-uuid-abc",11 "name": {12 "en": "Gaming Laptop",13 "ar": "لابتوب الألعاب",14 "ku": "لاپتۆپی یاری"15 },16 "price": 1299.99,17 "stock_available": 5,18 "images": [19 "https://example.com/gaming-laptop.jpg"20 ]21 },22 "became_available_at": "2023-12-01T14:00:00Z"23 }24 ],25 "price_changed": [26 {27 "id": "favorite-uuid-2",28 "variant_id": "variant-uuid-456",29 "variant": {30 "id": "variant-uuid-456",31 "market_id": "market-uuid-def",32 "name": {33 "en": "Wireless Headphones",34 "ar": "سماعات لاسلكية",35 "ku": "هێدفۆنی بێ تەل"36 },37 "price": 199.99,38 "images": [39 "https://example.com/headphones.jpg"40 ]41 },42 "price_change": {43 "old_price": 249.99,44 "new_price": 199.99,45 "change_amount": -50,46 "change_percentage": -20,47 "changed_at": "2023-12-01T16:00:00Z"48 }49 }50 ],51 "out_of_stock": [52 {53 "id": "favorite-uuid-3",54 "variant_id": "variant-uuid-789",55 "variant": {56 "id": "variant-uuid-789",57 "market_id": "market-uuid-ghi",58 "name": {59 "en": "Smart Watch",60 "ar": "ساعة ذكية",61 "ku": "کاتژمێری زیرەک"62 },63 "price": 299.99,64 "stock_available": 0,65 "images": [66 "https://example.com/smartwatch.jpg"67 ]68 },69 "became_unavailable_at": "2023-12-01T12:00:00Z"70 }71 ],72 "summary": {73 "newly_available_count": 1,74 "price_changed_count": 1,75 "out_of_stock_count": 1,76 "total_updates": 377 }78 }79}1{2 "success": true,3 "data": {4 "newly_available": [],5 "price_changed": [],6 "out_of_stock": [],7 "summary": {8 "newly_available_count": 0,9 "price_changed_count": 0,10 "out_of_stock_count": 0,11 "total_updates": 012 }13 }14}Get Favorites Count
/storefront/favorites/countRetrieves the total count of items in the user's favorites list. Useful for UI badges and quick statistics. Authentication: - Required: Valid Bearer token for user identification Features: - Fast count retrieval - No pagination overhead - Perfect for UI badges - Minimal data transfer Response Data: - Total favorites count - Last update timestamp Use Cases: - Navigation badge numbers - Dashboard statistics - Quick UI updates - Mobile app synchronization - Performance monitoring
1curl --request GET "$ONDI_BASE_URL/storefront/favorites/count" \2 --header "Authorization: Bearer {{access_token}}"Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for authenticated users (required)
Responses
1{2 "success": true,3 "data": {4 "count": 15,5 "last_updated": "2023-12-01T18:00:00Z"6 }7}1{2 "success": true,3 "data": {4 "count": 0,5 "last_updated": null6 }7}