Pricing Rules by AI (Rapidcanvas)

AI-Driven Pricing uses the RapidCanvas external recommendation API to suggest price adjustments based on a restaurant’s revenue target and historical performance metrics.

Architecture

┌─────────────────────┐
│ pricing-engine      │  Rails 8 API
│ (this service)      │
│                     │
│  AiRecommendation   │  ─── stores target_sale + target_sale_period
│  Recommendation::   │  ─── orchestrates fetch + adapter + modifier creation
│    FetchForRule     │
│  RapidCanvas::Client│  ─── HTTP client (initial / refresh / predicted_revenue)
│  RapidCanvas::*     │  ─── typed errors (timeout, network, upstream, etc.)
└──────────┬──────────┘
           │ HTTPS (x-api-key)
           ▼
┌─────────────────────┐
│ RapidCanvas API     │
│ /api/recommendations/initial
│ /api/recommendations/refresh
│ /api/restaurants/:id/predicted_revenue
└─────────────────────┘

Implementation references:

• Model: pricing-engine/app/models/ai_recommendation.rb
• HTTP client: pricing-engine/app/services/rapid_canvas/client.rb
• Orchestrator: pricing-engine/app/services/recommendation/fetch_for_rule.rb
• Response adapter: pricing-engine/app/services/recommendation/rapid_canvas/response_adapter.rb
• Global cap builder: pricing-engine/app/services/recommendation/rapid_canvas/global_cap_builder.rb

Rule Configuration

A PricingRule with rule_type = "ai_driven" stores its AI-specific inputs on an associated AiRecommendation record.

AI Input Metrics (passed to RapidCanvas)

The orchestrator builds a payload that RapidCanvas uses for forecasting:

Window days by period (Recommendation::FetchForRule::WINDOW_DAYS):

• daily → 0 days (same-day window)
• weekly → 7 days
• monthly → 30 days

Approval & Flow

Recommendation Lifecycle

User creates rule (target_sale + period)
        │
        ▼
Job runs Recommendation::FetchForRule
        │
        ├─ If no prior recommendation_id → :initial call
        │      → POST /api/recommendations/initial
        │
        └─ If recommendation_id exists → :refresh call
               → POST /api/recommendations/refresh
        │
        ▼
ResponseAdapter normalizes RapidCanvas response
        │
        ▼
PriceModifier::CreateFromRecommendation creates modifiers
        │
        ▼
Admin approves/rejects → modifiers activate/deactivate

The orchestrator’s request_id format:

recommendation-fetch-job:{operation}:{pricing_rule_id}:{target_date}

AI Strategy Matrix

The RapidCanvas model uses a semilog/exponential prediction. The pricing-engine forwards the user’s target_sale and lets RapidCanvas decide direction.

Validation: Target Sale can be lower, equal, or higher than Organic Projection.

UI Components

Edge Cases

Time in Advance (Yield Horizon)

Restrict AI from adjusting prices too far into the future.

Backend Filter (Action Engine)

IF target_date > (current_date + time_in_advance_limit)
  THEN ignore_ai_suggestion AND use_base_price

AI may still predict 30 days out for strategy, but the Action Engine filters before publishing to client.

Variance Threshold (Notification Sensitivity)

Prevent alert fatigue from minor daily AI adjustments.

Options

Backend Logic

• Baseline: Compare against Last Accepted Price (not previous ignored recommendation)
• Default: Trigger alert only if Variance > 1.0%
• Custom: Use user’s percentage instead of 1.0%

AI Recommendation Title Format

Split Heading 1 / Heading 2:

• Title (Bold): Your Data: Price down X% to gain ~Y% bookings — Template: [Type]: [Price_Action] [Tradeoff]
• Subtitle (Muted): Based on your past booking response to price changes — Template: [Basis]

Package Composition Disclaimer

AI recommends prices for the exact package as it exists today. If price drops 50% (e.g., ฿1,000 to ฿500), booking volume drops, invalidating AI math.

Demand Ceiling (Unachievable Targets)

Block mathematically impossible targets.

Forecast Transparency

Provide context around “Organic Projection” to build trust.

Audit Log & Global Pricing Limits

Strict paper trail to measure if AI’s original recommendation was effective or if user altered it.

Logged Data Points

• AI Recommendation: Exact % change suggested by RapidCanvas
• User Action: What user Approved, Rejected, or Edited (e.g., AI 10%, user 5%)
• Timestamps: Recommendation generation, user approval/rejection, scheduled effective date
• Auto Reject: Auto-reject when effective date has passed

RapidCanvas Endpoints

All endpoints require x-api-key header (from RAPIDCANVAS_API_KEY).

HTTP client behavior

RapidCanvas::Client (pricing-engine/app/services/rapid_canvas/client.rb):

• 3 retry attempts with exponential backoff for 429 / 5xx (Http::RetryWithBackoff)
• 20s request timeout, 10s open timeout
• Typed errors: TimeoutError, NetworkError, UpstreamError, ConfigurationError, UnexpectedResponseError
• submit_recommendation_decision is a no-op (returns blank) when neither RAPIDCANVAS_RECOMMENDATION_DECISION_PATH nor RAPIDCANVAS_BASE_URL is configured

Open Questions / Future Work

• Time-in-Advance (Yield Horizon) — backend filter implementation status pending; verify in recommendation/generate_initial_recommendation.rb whether time_in_advance_limit is currently applied to the AI output
• Variance Threshold — UI exists in PRD but no NotificationSensitivity model in pricing-engine yet; tracked as a separate feature
• Confidence Score — RapidCanvas response field name and mapping to forecast_confidence not yet finalized in response_adapter.rb

Related

• Customer-facing flow (HH Pegasus): Dynamic Pricings 2.0 — Customer Booking Flow
• HH Server integration: Dynamic Pricings 2.0 — HH Server Integration
• pricing-engine customer API: Customer Booking API
• Engineering spec: PricingEngine/015-PRICING-RECOMMENDATION-API.md
• Source models / services: pricing-engine/app/models/ai_recommendation.rb, pricing-engine/app/services/recommendation/, pricing-engine/app/services/rapid_canvas/
• Sibling PRDs: Capacity & Demand, Date & Time