Toggle a favourite listing REST API

Endpoint #

POST /wp-json/rtcl/v1/my/favourites

Description #

Add or remove a listing from the authenticated user’s favourite list.

Authentication #

Required

• Valid API authentication (JWT / nonce / API key as configured)
• User must be logged in

Required Headers #

Header	Required	Description
Authorization	✅ Yes	JWT token: Bearer <JWT_TOKEN>
X-API-KEY	✅ Yes	API key from RTCL settings
Content-Type	✅ Yes	application/json

Request Body Parameters #

Parameter	Type	Required	Description
listing_id	integer	✅ Yes	ID of the listing to add or remove from favourites

---

Example Request (cURL) #

curl -X POST "https://example.com/wp-json/rtcl/v1/my/favourites" \
-H "Authorization: Bearer DEMO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "listing_id": 123
}'

Success Response #

Status Code: 200 OK

Returns the updated list of favourite listing IDs.

[
  101,
  123,
  205
]

Response Notes #

• If the listing was not in favourites → it will be added
• If the listing already exists in favourites → it will be removed
• The response always contains the final favourite listing IDs

Error Responses #

1. Not Logged In #

Status Code: 403 Forbidden

{
  "code": "FORBIDDEN",
  "message": "You are not logged in."
}

2. Listing Not Found / Invalid #

Status Code: 400 Bad Request

{
  "status": "error",
  "error": "BADREQUEST",
  "code": "400",
  "error_message": "Listing not found."
}

3. Invalid API Key #

Status Code: 401 Unauthorized

{
  "status": "error",
  "error": "INVALID_API_KEY",
  "code": "401",
  "error_message": "Sorry, you are using invalid API Key."
}

4. Missing API Key Header #

Status Code: 401 Unauthorized

{
  "status": "error",
  "error": "MISSING_X_API_KEY_HEADER",
  "code": "401",
  "error_message": "X_API_KEY header not received. Either authorization header was not sent or it was removed by your server due to security reasons."
}