Available now

Revenue & Yield Engine

The Revenue API provides occupancy-driven rate recommendations, daily revenue snapshots, and the yield engine that powers the Co-Pilot dashboard. Use it to automate dynamic pricing, track KPIs, and build custom revenue intelligence workflows.

Concepts

Rate Recommendation

A pending pricing suggestion generated by the yield engine. Each recommendation targets a specific room type and date with a recommended rate, confidence score, and adjustment reason.

Revenue Snapshot

A point-in-time capture of daily occupancy and revenue KPIs: RevPAR, ADR, occupancy %, total revenue, and a per-module breakdown.

Yield Engine

Rule-based engine that inspects reservation occupancy over a 30-day rolling window and generates rate recommendations based on demand surges, low occupancy, and last-minute availability.

Rate Recommendation object

idstringUnique recommendation ID.

property_idstringOwning property.

room_typestringRoom/unit type this rate applies to.

datestringTarget date in YYYY-MM-DD format.

current_ratefloatRate currently booked for this room/date.

recommended_ratefloatEngine-suggested rate.

min_ratefloatFloor rate (70% of current by default).

max_ratefloatCeiling rate (140% of current by default).

occupancy_pctfloatCurrent occupancy % for this date.

days_until_arrivalintegerDays until the check-in date.

reasonenumdemand_surge · low_occupancy · last_minute · early_bird · competitor_rate · event_premium · manual_override

confidencefloatEngine confidence score 0.0–1.0.

is_appliedbooleanWhether this recommendation has been applied.

applied_atdatetime | nullTimestamp when applied.

created_atdatetimeISO 8601 creation timestamp.

Revenue Snapshot object

idstringUnique snapshot ID.

snapshot_datestringDate this snapshot covers (YYYY-MM-DD).

total_revenuefloatTotal revenue for the snapshot date.

rooms_revenuefloatRevenue attributed to room bookings.

spa_revenuefloatRevenue attributed to spa.

fnb_revenuefloatRevenue attributed to F&B.

other_revenuefloatAll other revenue.

occupied_roomsintegerNumber of rooms occupied on this date.

total_roomsintegerTotal room inventory.

adrfloatAverage Daily Rate (total_revenue / occupied_rooms).

revparfloatRevenue Per Available Room (total_revenue / total_rooms).

occupancy_pctfloatOccupancy percentage (occupied / total × 100).

breakdownobjectArbitrary per-channel or per-source revenue breakdown.

created_atdatetimeISO 8601 creation timestamp.

Endpoints

GET/v1/revenue/snapshotsRevenue snapshots

Return daily revenue snapshots ordered by date descending.

Path / Query Parameters

daysintegerHow many days of history to return (1–365). Default 30.

bash

curl "https://api.escapelife.ai/v1/revenue/snapshots?days=7" \
  -H "X-API-Key: sk_live_xxx"

Response

{
  "data": [
    {
      "snapshot_date": "2026-03-16",
      "adr": 355.0,
      "revpar": 309.7,
      "occupancy_pct": 87.3,
      "total_revenue": 31890.0,
      "occupied_rooms": 89,
      "total_rooms": 102
    }
  ],
  "total": 1
}

POST/v1/revenue/snapshotRecord daily snapshot

Capture today's occupancy and revenue metrics as a new snapshot. Typically called once per day by a scheduled job.

Request Body

total_roomsintegerTotal room inventory for this property. Required.

bash

curl -X POST https://api.escapelife.ai/v1/revenue/snapshot \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"total_rooms": 102}'

GET/v1/revenue/recommendationsRate recommendations

Return pending yield rate recommendations. Filter by room type or include already-applied recommendations.

Path / Query Parameters

room_typestringFilter to a specific room type.

unapplied_onlybooleanWhen true (default), only return unapplied recommendations.

Response

{
  "data": [
    {
      "id": "01HXZ8K3MN...",
      "room_type": "Ocean Suite",
      "date": "2026-07-19",
      "current_rate": 355.0,
      "recommended_rate": 426.0,
      "occupancy_pct": 94.0,
      "days_until_arrival": 125,
      "reason": "demand_surge",
      "confidence": 0.75,
      "is_applied": false
    }
  ],
  "total": 1
}

POST/v1/revenue/recommendations/generateGenerate yield recommendations

Run the yield engine over the next 30 days of reservations and generate new rate recommendations. Safe to call repeatedly — only creates new records.

Request Body

total_roomsintegerTotal room inventory. Required.

bash

curl -X POST https://api.escapelife.ai/v1/revenue/recommendations/generate \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"total_rooms": 102}'

Response

{
  "generated": 3,
  "data": [ ... ]
}

POST/v1/revenue/recommendations/{rec_id}/applyApply a recommendation

Mark a rate recommendation as applied. Sets is_applied=true and applied_at timestamp. Your PMS or channel manager should then push the updated rate.

Path / Query Parameters

rec_idstringrequiredRecommendation ID.

Yield engine rules

Occupancy > 85%+20% rate adjustmentdemand_surge

Occupancy < 60%, ≤ 3 days out−12% rate adjustmentlast_minute

Occupancy < 60%−8% rate adjustmentlow_occupancy

Occupancy 60–85%No recommendation— (hold rate)

Min/max rate floors are set at 70%–140% of the current rate. Confidence is 0.75 for all rule-based recommendations.

Recommended integration pattern

Daily automation (cron or Railway Cron)

# 1. Capture today's snapshot
curl -X POST https://api.escapelife.ai/v1/revenue/snapshot \
  -H "X-API-Key: sk_live_xxx" -d '{"total_rooms": 102}'

# 2. Generate new rate recommendations
curl -X POST https://api.escapelife.ai/v1/revenue/recommendations/generate \
  -H "X-API-Key: sk_live_xxx" -d '{"total_rooms": 102}'

# 3. Fetch and review pending recommendations
curl "https://api.escapelife.ai/v1/revenue/recommendations" \
  -H "X-API-Key: sk_live_xxx"

# 4. Apply approved recommendations (push to PMS/OTA)
curl -X POST https://api.escapelife.ai/v1/revenue/recommendations/{rec_id}/apply \
  -H "X-API-Key: sk_live_xxx"

Webhooks fired by this module

revenue.snapshot_recorded

New daily snapshot created.

revenue.recommendation_created

Yield engine generated a new rate recommendation.

revenue.recommendation_applied

A rate recommendation was applied.