Favorites & Wishlist

6 API calls in this section.

Get User Favorites

Storefront & Commerce / Favorites & Wishlist

GET/storefront/favorites

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.

• Required: Valid Bearer token for user identification

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

Query parameters

Parameter	Type	Description
pageOptional	string	Page number for pagination (default: 1) Page number for pagination (default: 1) Example: 1
limitOptional	string	Items per page (default: 20, max: 100) Items per page (default: 20, max: 100) Example: 20
market_idOptional	string	Filter favorites by specific market (optional) Filter favorites by specific market (optional) Example: {{market_id}}

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for authenticated users (required) JWT token for authenticated users (required) Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/storefront/favorites?page=1&limit=20&market_id=${MARKET_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200 · Success - Favorites List200 · Success - Empty Favorites401 · Error - Authentication Required

200OK

Response body

json

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}

Add to Favorites

Storefront & Commerce / Favorites & Wishlist

POST/storefront/favorites

Adds a product to the user's favorites/wishlist. Prevents duplicate entries and provides detailed product information in response.

• Required: Valid Bearer token for user identification

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

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for authenticated users (required) JWT token for authenticated users (required) Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
variant_idRequired	string	UUID of the product to add to favorites UUID of the product to add to favorites

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/storefront/favorites" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "variant_id": "variant-uuid-123"6}'

Response examples

201 · Success - Item Added to Favorites409 · Error - Already in Favorites404 · Error - Product Not Found400 · Error - Validation Failed

201Created

Response body

json

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}

Remove from Favorites

Storefront & Commerce / Favorites & Wishlist

DELETE/storefront/favorites/:favorite_id

Removes a specific item from the user's favorites/wishlist by favorite ID.

• Required: Valid Bearer token for user identification

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

Path parameters

Parameter	Type	Description
favorite_idRequired	string	UUID of the favorite item to remove UUID of the favorite item to remove Example: favorite-uuid-123

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for authenticated users (required) JWT token for authenticated users (required) Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request DELETE "https://staging-api.ondi.io/functions/v1/storefront/favorites/${FAVORITE_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200 · Success - Item Removed404 · Error - Favorite Not Found403 · Error - Unauthorized Access

200OK

Response body

json

1{2  "success": true,3  "data": {4    "message": "Product removed from favorites successfully",5    "removed_at": "2023-12-01T18:30:00Z"6  }7}

Check Favorite Status

Storefront & Commerce / Favorites & Wishlist

GET/storefront/products/:product_id/favorite-status

Checks whether a specific product is in the user's favorites list. Useful for UI state management on product pages.

• Required: Valid Bearer token for user identification

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

Path parameters

Parameter	Type	Description
product_idRequired	string	UUID of the product to check favorite status UUID of the product to check favorite status Example: product-uuid-123

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for authenticated users (required) JWT token for authenticated users (required) Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/storefront/products/${PRODUCT_ID}/favorite-status" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200 · Success - Is Favorited200 · Success - Not Favorited404 · Error - Product Not Found

200OK

Response body

json

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}

Get Favorite Updates

Storefront & Commerce / Favorites & Wishlist

GET/storefront/favorites/updates

Retrieves favorites with availability and pricing updates. Useful for notifying users about changes to their wishlist items.

• 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

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for authenticated users (required) JWT token for authenticated users (required) Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/storefront/favorites/updates" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200 · Success - Updates Available200 · Success - No Updates

200OK

Response body

json

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}

Get Favorites Count

Storefront & Commerce / Favorites & Wishlist

GET/storefront/favorites/count

Retrieves the total count of items in the user's favorites list. Useful for UI badges and quick statistics.

• 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

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for authenticated users (required) JWT token for authenticated users (required) Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/storefront/favorites/count" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200 · Success - Favorites Count200 · Success - Zero Favorites

200OK

Response body

json

1{2  "success": true,3  "data": {4    "count": 15,5    "last_updated": "2023-12-01T18:00:00Z"6  }7}