Home›User Management›Favourites

Favourites

Let users save restaurants as favourites. A single toggle endpoint adds or removes a favourite, and a list endpoint returns the user's saved restaurants with their address. To show only favourites on the home screen, use the favourites filter on Nearby Restaurants.

Passing userId

Tokens issued via client credentials don't identify an end user, so send your platform's userId with every favourites call: in the request body for toggle, and as a query param for list. If it's missing, the API returns 400.

Toggle Favourite

POST/ret11/api/favourites/toggle

Adds the restaurant to the user's favourites if it isn't there yet, and removes it if it is. Call it from the heart / favourite button.

Auth Required

Include a Bearer token.

Request Body

Field	Type	Required	Description
providerId	string	required	Restaurant ID, from nearby restaurants
sellerId	string	required	Seller UUID that owns the restaurant
userId	string	required	Your platform's user ID for the logged-in user

Example Request

curl -X POST "$BASE_URL/ret11/api/favourites/toggle" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "pramaan_provider_1",
    "sellerId": "019b78d7-1371-7017-a997-3f6429a2f663",
    "userId": "user-123"
  }'

Response

Field	Type	Description
providerId	string	The restaurant that was toggled
isFavourite	boolean	The new state: `true` if it was just added, `false` if it was just removed
favourite	object \| null	The saved favourite when `isFavourite` is `true`; `null` when it was removed

Response Example — added

{
  "providerId": "pramaan_provider_1",
  "isFavourite": true,
  "favourite": {
    "id": "019c1a2b-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
    "providerId": "pramaan_provider_1",
    "sellerId": "019b78d7-1371-7017-a997-3f6429a2f663",
    "restaurantName": "Pramaan Store 1",
    "restaurantImage": "https://pramaan.ondc.org/beta/preprod/mock/seller/assets/logo/store1.png",
    "createdAt": "2026-10-16T10:00:00.000Z"
  }
}

Response Example — removed

{
  "providerId": "pramaan_provider_1",
  "isFavourite": false,
  "favourite": null
}

Errors

Status	When
400	`userId` missing for a client-credentials token
404	`Seller not found` or `Provider not found` when adding a favourite

List Favourites

GET/ret11/api/favourites

Returns the user's favourite restaurants, newest first.

Auth Required

Include a Bearer token.

Query Parameters

Parameter	Type	Required	Description
userId	string	required	Your platform's user ID for the logged-in user

Example Request

curl "$BASE_URL/ret11/api/favourites?userId=user-123" \
  -H "Authorization: Bearer $JWT"

Response

Field	Type	Description
id	string	Favourite record ID
providerId	string	Restaurant ID
sellerId	string	Seller UUID
restaurantName	string	Restaurant name, saved at the time it was favourited
restaurantImage	string \| null	First restaurant image, saved at the time it was favourited
createdAt	string	When it was favourited (ISO 8601)
address	object \| null	Current restaurant address: `locality`, `street`, `city`, `areaCode`, `state`. `null` if the restaurant's location is no longer available.

Response Example

[
  {
    "id": "019c1a2b-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
    "providerId": "pramaan_provider_1",
    "sellerId": "019b78d7-1371-7017-a997-3f6429a2f663",
    "restaurantName": "Pramaan Store 1",
    "restaurantImage": "https://pramaan.ondc.org/beta/preprod/mock/seller/assets/logo/store1.png",
    "createdAt": "2026-10-16T10:00:00.000Z",
    "address": {
      "locality": "N. Caldwell",
      "street": "633 Stagtrail Rd",
      "city": "Bengaluru",
      "areaCode": "560001",
      "state": "Karnataka"
    }
  }
]

Only open, nearby favourites

This list includes every favourite, even restaurants that are closed or far away. To show only favourites that are open and can be ordered from right now, call nearby restaurants with favourites=true.