Recommendations¶

GET /api/v1/listings/<id>/recommendations/

Scope: listings:read
Description: List base-price recommendations for a listing

Try it out

Explore schemas and make live requests in the Swagger UI.

List Recommendations¶

Returns recommendations for a listing owned by the authenticated application, newest first.

Recommendations are generated periodically using the newest data available for the listing and its market. They are designed to suggest pricing updates as market conditions change over time. The endpoint currently returns base price recommendations only (category is always base_price).

By default, Beyond accepts base price changes automatically. Partners can use this endpoint to review the latest recommendation state and understand whether a base price recommendation is pending, approved, rejected, expired, or already applied automatically. When no recommendations exist for the listing, the response is an empty collection.

Request¶

GET /api/v1/listings/123/recommendations/

Parameter	Description
`page[number]`, `page[size]`	Standard pagination. Default page size 25, maximum 100. Entries are ordered newest first.

Response¶

{
  "data": [
    {
      "type": "recommendations",
      "id": "9001",
      "attributes": {
        "listing-id": 123,
        "listing-title": "Sunny 2BR near the beach",
        "status": "suggestion_completed",
        "approved-at": null,
        "rejected-at": null,
        "expired-at": null,
        "suggested-base-price": 175,
        "suggested-min-price": 120,
        "suggested-seasonal-min-price-pct": -10.5,
        "initial-base-price": 150,
        "initial-min-price": 100,
        "recommendations": "Raise the base price before the next weekend.",
        "category": "base_price",
        "created-at": "2026-03-25T12:00:00Z"
      }
    }
  ],
  "meta": {
    "pagination": {"page": 1, "pages": 1, "count": 1}
  }
}

Fields¶

All prices are in the listing's currency (the one the listing resource reports), in the same units as the listing's base-price.

Field	Description
`listing-id`, `listing-title`	The listing the recommendation belongs to.
`status`	Lifecycle status. See Status values.
`approved-at`, `rejected-at`, `expired-at`	When the recommendation reached that terminal state; `null` otherwise.
`suggested-base-price`	Suggested nightly base price derived from the latest listing and market data.
`suggested-min-price`	Suggested minimum nightly price, when the recommendation carries one; `null` otherwise.
`suggested-seasonal-min-price-pct`	Suggested seasonal minimum-price adjustment, as a percentage (`-10.5` means -10.5%); `null` when not suggested.
`initial-base-price`, `initial-min-price`	The base and minimum price recorded when the recommendation was created — the baseline the suggestion moves from.
`recommendations`	Free-text explanation of the recommendation, when one was written.
`category`	Recommendation category. Currently always `base_price`.
`created-at`	When the recommendation record was created.

Status values¶

Value	Meaning
`suggested`	Drafted, not yet delivered to the end user.
`suggestion_completed`	Delivered and awaiting a decision — the actionable state.
`approved`	The end user accepted the suggestion.
`rejected`	The end user declined the suggestion.
`expired`	No action was taken and the suggestion expired automatically.
`canceled`	Withdrawn before a decision.
`outdated`	Superseded by newer data before a decision.

Use cases¶

Surface pending suggestions. Show recommendations with status: suggestion_completed to the property manager, with suggested-base-price next to initial-base-price so the size of the change is visible.
Track outcomes. Read the terminal timestamps (approved-at, rejected-at, expired-at) to report how recommendations were handled.
Detect applied changes. After an approval, confirm the listing's base-price on the listings endpoint and watch the listing.base_price_changed webhook rather than polling.

Errors¶

Status	Cause
`401`	Missing or invalid bearer token.
`403`	Token does not have the `listings:read` scope.
`404`	No listing with that id is visible to your application.
`429`	Rate limit exceeded. See Rate Limiting.