Promotions & ROI API

Before you burn the margin, simulate it.

Simulate ROI for any campaign — category, depth, duration, channel — and get expected GMV uplift, cannibalization, and net ROI back in a single call. Plus a live, programmatic read on what every tracked competitor is running right now.

Get API keys View endpoints

Endpoints

GET

/v1/promotions/calendar

Live promo calendar across all tracked competitors

POST

/v1/promotions/simulate

Simulate a candidate campaign with your ROI model parameters

GET

/v1/promotions/campaigns

Your historical campaigns with measured outcomes

Example request

curl https://api.prizeskout.qa/v1/promotions/simulate \
  -H "Authorization: Bearer sk_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "small_appliances",
    "channel": "talabat",
    "depth_pct": 15,
    "duration_days": 7
  }'

200 OK · application/json

{
  "scenario_id": "sim_01HX9P2K3M7QZ8Y4N6W5B1E2F0",
  "gmv_uplift": 142800,
  "incremental_orders": 612,
  "cannibalization_pct": 18.4,
  "net_roi": 1.87,
  "healthy": true
}

What you get

ROI simulator parameterized on your elasticity, baseline, and cannibalization model

Healthy-campaign heuristic that flags designs likely to burn net margin

Live competitor promo calendar with depth, duration, and category coverage

Replay historical campaigns to backtest new ROI parameters

Webhook events when competitors launch or extend promotions

Tie every live campaign back to the recommendation or signal that triggered it

Common integrations

Pre-launch approval gates

Require every proposed campaign to pass an ROI check before it reaches ops.

Competitive response

Ingest the promo-calendar webhook and auto-propose counter-campaigns.

Finance reconciliation

Attach measured outcomes to planned ROI for post-mortem analysis.