Favorites API

Manage user favorite listings and vehicle comparisons.

Favorites Endpoints

Method	Endpoint	Description	Auth
GET	/api/favorites	List favorites	Required
GET	/api/favorites/check	Check if listings are favorited	Required
POST	/api/favorites	Toggle favorite (add/remove)	Required

Comparison Endpoints

Method	Endpoint	Description	Auth
GET	/api/comparisons	Get comparison list	Required
POST	/api/comparisons/add	Add to comparison (max 4)	Required
POST	/api/comparisons/sync	Sync guest localStorage after login	Required
DELETE	/api/comparisons	Clear all comparisons	Required
DELETE	/api/comparisons/:listingId	Remove from comparison	Required

List Favorites

Get the authenticated user's favorite listings.

Request

GET /v1/favorites
Authorization: Bearer YOUR_JWT_TOKEN

Query Parameters

Parameter	Type	Description
page	integer	Page number
limit	integer	Items per page
list_id	string	Filter by favorites list
sort	string	date_added, price, year

Response

{
  "success": true,
  "data": {
    "favorites": [
      {
        "id": "fav_123",
        "listing": {
          "id": "lst_abc123",
          "title": "2021 Volvo FH 500",
          "price": 85000,
          "currency": "EUR",
          "thumbnail": "https://cdn.menonmobility.com/thumb.jpg",
          "year": 2021,
          "mileage": 245000,
          "status": "active",
          "seller": {
            "name": "ABC Trucks",
            "verified": true
          }
        },
        "notes": "Good price, contact Monday",
        "list": {
          "id": "list_default",
          "name": "My Favorites"
        },
        "added_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 15
    }
  }
}

Add to Favorites

Add a listing to favorites.

Request

POST /v1/favorites
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

Body

{
  "listing_id": "lst_abc123",
  "list_id": "list_default",
  "notes": "Good price, contact Monday"
}

Response

{
  "success": true,
  "data": {
    "id": "fav_123",
    "listing_id": "lst_abc123",
    "list_id": "list_default",
    "notes": "Good price, contact Monday",
    "added_at": "2024-01-15T10:30:00Z"
  }
}

Remove from Favorites

Remove a listing from favorites.

Request

DELETE /v1/favorites/lst_abc123
Authorization: Bearer YOUR_JWT_TOKEN

Response

{
  "success": true,
  "data": {
    "removed": true,
    "listing_id": "lst_abc123"
  }
}

Check Favorite Status

Check if a listing is in favorites.

Request

GET /v1/favorites/check/lst_abc123
Authorization: Bearer YOUR_JWT_TOKEN

Response

{
  "success": true,
  "data": {
    "is_favorite": true,
    "favorite_id": "fav_123",
    "list_id": "list_default",
    "added_at": "2024-01-15T10:30:00Z"
  }
}

Bulk Check

Check multiple listings at once.

Request

POST /v1/favorites/check
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

Body

{
  "listing_ids": ["lst_1", "lst_2", "lst_3", "lst_4"]
}

Response

{
  "success": true,
  "data": {
    "favorites": {
      "lst_1": true,
      "lst_2": false,
      "lst_3": true,
      "lst_4": false
    }
  }
}

Favorite Lists

Create List

POST /v1/favorites/lists
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "name": "Top Choices",
  "description": "My best options"
}

Get Lists

GET /v1/favorites/lists
Authorization: Bearer YOUR_JWT_TOKEN

Response

{
  "success": true,
  "data": {
    "lists": [
      {
        "id": "list_default",
        "name": "My Favorites",
        "description": null,
        "count": 12,
        "is_default": true
      },
      {
        "id": "list_123",
        "name": "Top Choices",
        "description": "My best options",
        "count": 5,
        "is_default": false
      }
    ]
  }
}

Update List

PUT /v1/favorites/lists/list_123
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "name": "Updated Name"
}

Delete List

DELETE /v1/favorites/lists/list_123
Authorization: Bearer YOUR_JWT_TOKEN

Move to List

Move favorite to different list.

Request

PUT /v1/favorites/fav_123
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "list_id": "list_456"
}

Update Notes

Update favorite notes.

Request

PUT /v1/favorites/fav_123
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "notes": "Updated notes..."
}

Price Alerts

Enable Price Alert

POST /v1/favorites/fav_123/alert
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "enabled": true,
  "threshold": "any"
}

Threshold Options

Value	Description
any	Any price change
5	5% or more drop
10	10% or more drop
custom	Custom percentage

Export Favorites

Export as CSV

GET /v1/favorites/export?format=csv
Authorization: Bearer YOUR_JWT_TOKEN

Export as PDF

GET /v1/favorites/export?format=pdf
Authorization: Bearer YOUR_JWT_TOKEN

Share Favorites

Create Share Link

POST /v1/favorites/lists/list_123/share
Authorization: Bearer YOUR_JWT_TOKEN

Response

{
  "success": true,
  "data": {
    "share_url": "https://menonmobility.com/shared/favorites/abc123",
    "expires_at": "2024-02-15T10:30:00Z"
  }
}

Related Topics

• Listings API
• Search API