E-commerce & Retail
Promotion Optimisation API
Your last promotion increased units. Whether it increased profit, and whether the same units would have sold anyway, is usually unanswered.
- Retailers
- Marketplaces
- Direct-to-consumer brands
- Pricing software vendors
- Category management teams
What your customers would see
example interfaceMockupIllustrative mockup of the interface we would build. Figures shown are examples, not results from a live deployment.
The problem this solves
Promotional planning in most retailers is anchored on last year's calendar. The same mechanics run in the same weeks, with the depth adjusted by whoever has the strongest opinion in the meeting. Post-promotion analysis, if it happens at all, compares promoted weeks to non-promoted weeks and declares success on uplift in units.
That comparison is close to meaningless. Promotions run when demand is already seasonally high, promoted items cannibalise their own full-price siblings, and a share of the uplift is pull-forward — sales borrowed from the weeks immediately after, which then look disappointing and get promoted too. Measured properly, a meaningful fraction of promotional spend in a typical calendar is funding discounts on units that would have sold at full price.
The useful questions are specific. What was the incremental margin of this mechanic on this product at this depth? Where is the point at which deeper discounting stops paying for itself? Which items cannibalised which? Answering them needs a causal framing with a credible control group, not a before-and-after chart.
Who buys this
Retailers, Marketplaces, Direct-to-consumer brands, Pricing software vendors, Category management teams
What the API returns
What comes back
- Measured incremental units and incremental margin per past promotion
- Cannibalisation and pull-forward estimates with the affected SKUs named
- Price elasticity and promotional response curves per product group
- Recommended discount depth and mechanic given a margin or volume objective
- Forecast outcome for a planned promotion, with a prediction interval
- Mechanic comparison: percentage off, multi-buy, bundle, threshold spend, loyalty-only
- Promotional calendar conflict detection across overlapping offers
- Post-promotion reporting with the control construction made explicit and auditable
Endpoints
| Method | Path | Returns |
|---|---|---|
| POST | /v1/promotions/evaluate | Measure the incremental effect of a completed promotion |
| POST | /v1/promotions/plan | Recommend depth and mechanic for an objective |
| POST | /v1/promotions/simulate | Forecast the outcome of a planned promotion |
| GET | /v1/products/{id}/elasticity | Estimated price and promotional response curve |
| GET | /v1/calendar/conflicts | Overlapping or cannibalising planned promotions |
| POST | /v1/history/ingest | Push promotional, pricing and sales history |
Request and response
illustrativeRequest
{
"promotion": {
"id": "promo_2026_w38_kettles",
"mechanic": "percent_off",
"depth_pct": 25,
"skus": ["KT-4480-BLK", "KT-4480-SLV"],
"ran": { "from": "2026-09-14", "to": "2026-09-27" },
"locations": ["all_stores", "web"]
},
"objective": "incremental_margin",
"include": ["cannibalisation", "pull_forward", "control_detail"]
}Response
{
"promotion_id": "promo_2026_w38_kettles",
"control": {
"method": "synthetic_control_matched_stores",
"matched_units": 164,
"pre_period_fit_mape": 0.061
},
"observed": { "units": 18420, "revenue": 1104400.00, "gross_margin": 198792.00 },
"counterfactual": { "units": 12980, "revenue": 1038400.00, "gross_margin": 259600.00 },
"incremental": {
"units": 5440,
"revenue": 66000.00,
"gross_margin": -60808.00,
"margin_ci_90": [-74100.00, -47500.00]
},
"cannibalisation": [
{ "sku": "KT-5100-BLK", "units_lost": 1180, "margin_lost": 21240.00 }
],
"pull_forward": { "units": 1610, "weeks_affected": 2 },
"verdict": "volume_positive_margin_negative",
"recommendation": {
"mechanic": "multi_buy_2for",
"depth_pct": 15,
"expected_incremental_margin": 14200.00,
"expected_margin_ci_90": [6100.00, 22800.00]
}
}Where the data comes from
| Your sales and promotional history | Transaction-level sales with the promotion, mechanic and depth that applied — the core input, and often the messiest |
| Price and cost history | Selling price and cost of goods over time, because a margin answer is impossible without both |
| Promotional funding and supplier contributions | Supplier-funded promotions have completely different economics and are routinely omitted from analysis |
| Stock and availability history | A promotion that sold out mid-week is not a promotion that underperformed, and the two look identical without this |
| Calendar, competitor and weather context | The confounders that make naive before-and-after comparisons wrong |
| Marketing activity records | Where a promotion ran alongside media spend, attribution between them has to be handled rather than ignored |
The intelligence layer
The difference between a demo and a service is mostly in this section. These are the parts that keep the answer trustworthy once real traffic is hitting it.
- Causal effect estimation with synthetic or matched control groups, with the pre-period fit reported so the control can be judged rather than trusted
- Difference-in-differences and Bayesian structural time series as cross-checks, because agreement between methods is the practical evidence of validity
- Cannibalisation estimation across the affinity group, not only within the promoted SKUs
- Pull-forward measurement over the post-promotion window, subtracted from the incremental figure rather than reported separately and forgotten
- Elasticity estimated per product group with hierarchical shrinkage, since individual SKUs rarely have enough promotional observations
- Margin-aware optimisation over depth and mechanic, constrained by your minimum-margin and brand rules
- Prediction intervals on every recommendation, because a point estimate of incremental margin invites false confidence
- Backtesting of recommendations against subsequently observed outcomes, and monitoring for elasticity drift as the market moves
What it changes for the business
Promotional spend redirected
Mechanics that reliably lose margin can be identified and stopped with evidence behind the decision.
Shallower discounts, similar volume
Response curves usually show the point where extra depth stops buying extra units.
Cannibalisation made visible
Planning stops promoting an item that simply moves demand off its full-price sibling.
Defensible negotiation
Measured incremental effect is a stronger basis for supplier funding conversations than reported uplift.
How it fits into your product
How it embeds
- Batch evaluation endpoints that run against your promotional history as a backfill, then per-promotion as each one closes
- Planning endpoints a category manager calls from your existing promotional planning tool
- Scenario simulation fast enough to be used interactively during a planning session
- Write-back of recommended depth and mechanic into your promotion management system
- Warehouse and file ingestion where sales history lives in a data platform rather than an API
- Audit output that exposes the control construction, so finance can scrutinise the numbers
Included in every build
- Authentication, scoped API keys and per-customer rate limiting
- Input validation with predictable, documented error responses
- Versioned endpoints so your integration never breaks without notice
- Request and response logging for audit and dispute resolution
- Latency, error-rate and usage monitoring with alerting
- OpenAPI specification, sandbox environment and client examples
- Backups, failover design and a documented recovery procedure
- An agreed support arrangement once the service is live
How we would build it
about 20 weeksDiscovery and feasibility
Weeks 1–3
This one depends heavily on data access, so we start by proving the sources exist, can be licensed for your use, and actually carry the signal the model needs. If they do not, you find out here.
Architecture and baseline model
Weeks 4–6
A written architecture and a baseline model measured against a holdout period, so you know what accuracy you are buying before the full build starts.
Production build
Weeks 7–16
Data pipelines, model training and serving, historical archive, validation harness, API, security, monitoring and documentation.
Validation and integration
Weeks 17–20
Backtesting against held-out history, accuracy reporting your team can audit, integration support and an agreed retraining cadence.
Commercial models
There is no fixed price list, because the cost is driven by data complexity, integration count, model requirements, request volume and the support level you need. Scope is agreed in writing before development starts.
Fixed-scope prototype
A defined slice of the service, built and priced as one piece of work. The usual first step when the business case needs proving internally.
Fixed-price build
An agreed scope against a written architecture, delivered for an agreed price. Best when the requirements are already clear.
Build then retainer
We build the service, then operate and improve it under a monthly agreement covering monitoring, updates and model maintenance.
White-label product
The service runs under your brand, your domain and your pricing, with MLPivot invisible to your customers.
Questions buyers ask
How do you know what would have happened anyway?
We construct a control — matched locations, matched products, or a synthetic composite — and report how well it tracked the promoted units before the promotion started. If that pre-period fit is poor, the incremental estimate is unreliable and the API says so rather than publishing a number. This is the part most promotional reporting skips entirely.
Will it tell us to stop promoting?
Sometimes, and we would not soften it. Plenty of recurring promotions are margin-negative once cannibalisation and pull-forward are subtracted. Whether to keep them for traffic, competitive or supplier-relationship reasons is a business decision; the point is to make it knowingly rather than on an uplift chart.
What if everything is always on promotion?
Then measurement gets genuinely hard, because there is no clean control period and the base price has stopped being a real reference point. We would say so during discovery. Categories with permanent discounting need a different framing — usually a price-architecture review before any promotional analysis is worth running.
How much history is needed?
At least two years, covering several repetitions of the mechanics you care about. Elasticity estimated from three promotional events is not an elasticity, and hierarchical pooling across product groups only partly compensates. The API reports the observation count behind every curve.
Can it account for competitor activity?
Partly, and only where the data is available and permitted. Competitor price observations improve the control construction, but what may be collected and used is governed by each source's terms, and in many cases we work without it and widen the intervals instead.
Related blueprints
Demand Forecasting API
SKU-level demand forecasts by location and period, with prediction intervals your replenishment and planning tools can order against.
Competitor Price Monitoring API
Competitor prices, discounts and stock status for your catalogue, delivered as a change feed your pricing tools can act on.
Product Matching API
Decide whether two listings are the same product despite different titles, SKUs and images, with a confidence score and the evidence behind it.
Want this built for your platform?
Tell us what your product does today and what you want another system to be able to ask it. We will come back with an approach, a scope and a price.