E-commerce & Retail
Return Probability API
Returns are usually treated as a cost to process. A large share of them were predictable at the moment the basket was created.
- Online retailers
- Fashion and apparel brands
- Marketplaces
- Logistics software vendors
- Commerce platforms
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
In apparel and footwear, returns routinely run between a fifth and a half of units shipped, and every one carries outbound shipping, inbound shipping, handling, inspection, repackaging and often a markdown. The operational response is to make returns efficient. The cheaper response is to ship fewer orders that were always going to come back.
The predictive signal is unusually strong because the behaviour is structured. Multiple sizes of the same style in one basket is a fitting-room order. A customer with a history of returning a specific brand will probably do it again. A product whose reviews consistently say it runs small generates size-related returns at a rate the listing could have prevented.
What makes this delicate is what you do with the score. Refusing to serve customers, or quietly degrading their experience, based on a model output is both commercially short-sighted and in several jurisdictions legally exposed. The defensible interventions are informational and operational — better sizing guidance, fixing the listing, choosing a different fulfilment route — not punitive.
Who buys this
Online retailers, Fashion and apparel brands, Marketplaces, Logistics software vendors, Commerce platforms
What the API returns
What comes back
- Return probability per order line, with the drivers that produced the score
- Probable return reason distribution: size, fit, quality, not-as-described, changed mind, damage
- Basket-level diagnostics such as detected multi-size fitting-room behaviour
- Product-level return propensity against the category baseline
- Customer-cohort return behaviour, as aggregate cohorts rather than individual labels
- Expected return cost in your own currency, given your handling and shipping economics
- Recommended intervention per line, ranked by expected value
- Score explanations written for display to a merchandiser or a service agent
Endpoints
| Method | Path | Returns |
|---|---|---|
| POST | /v1/score/order | Score the lines of an order before dispatch |
| POST | /v1/score/basket | Score a live basket for pre-checkout intervention |
| GET | /v1/products/{id}/propensity | Return propensity and reason mix for a product |
| GET | /v1/cohorts/{id}/behaviour | Aggregate return behaviour for a customer cohort |
| POST | /v1/outcomes | Report actual return outcomes to close the training loop |
| GET | /v1/accuracy | Calibration and accuracy by category and horizon |
Request and response
illustrativeRequest
{
"order_id": "ord_5512093",
"lines": [
{ "sku": "JKT-NORD-2210-M", "qty": 1, "price": 129.00 },
{ "sku": "JKT-NORD-2210-L", "qty": 1, "price": 129.00 }
],
"customer_cohort": "repeat_apparel_12m",
"channel": "web",
"include": ["reasons", "interventions", "explanations"]
}Response
{
"order_id": "ord_5512093",
"basket_flags": [
{ "flag": "multi_size_same_style", "styles": ["JKT-NORD-2210"], "sizes": ["M", "L"] }
],
"lines": [
{
"sku": "JKT-NORD-2210-M",
"return_probability": 0.61,
"calibration_band": "well_calibrated",
"reasons": [
{ "reason": "size_too_small", "share": 0.52 },
{ "reason": "changed_mind", "share": 0.21 },
{ "reason": "quality", "share": 0.14 }
],
"drivers": [
{ "driver": "multi_size_basket", "contribution": 0.28 },
{ "driver": "product_runs_small_reviews", "contribution": 0.17 },
{ "driver": "cohort_apparel_return_rate", "contribution": 0.11 }
],
"expected_return_cost": 18.40,
"interventions": [
{ "action": "show_fit_guidance_pre_checkout", "expected_value": 6.10 },
{ "action": "consolidate_shipment", "expected_value": 2.90 }
],
"explanation": "Two sizes of one style ordered together; reviews for this product report small sizing."
}
],
"model_version": "rp-2026-10"
}Where the data comes from
| Your order and return history | Order lines paired with actual return outcomes and reasons — without the outcome labels there is nothing to train on |
| Product attributes and sizing data | Measured garment dimensions and size charts, which carry far more signal than a size label alone |
| Review and support text | Sizing and quality complaints, which predict the corresponding return reasons well before return volume shows it |
| Aggregate customer behaviour | Cohort-level return patterns, handled as cohorts rather than individual profiles |
| Fulfilment and logistics data | Carrier, transit time and damage history, since a share of returns are logistics outcomes rather than product ones |
| Your cost inputs | Shipping, handling, inspection and markdown costs, which are what convert a probability into a decision |
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.
- Gradient-boosted models on order-line features for the core prediction, with calibration checked explicitly — an uncalibrated probability cannot be multiplied by a cost
- Separate reason-classification head, because the intervention depends on why the item comes back, not just whether
- Basket-level feature engineering for fitting-room patterns, which a line-level model cannot see
- Product sizing deviation estimated from measured dimensions and review text combined
- Cohort-level rather than individual customer scoring by default, to keep the system away from decisions about identified people
- Fairness review on the features used, excluding proxies for protected characteristics and documenting what was excluded and why
- Backtesting on held-out periods with calibration curves and expected-value evaluation, not accuracy alone
- Drift monitoring on return rate by category, since an assortment or supplier change moves the base rate quickly
What it changes for the business
Fewer avoidable returns
Sizing guidance and listing fixes stop the returns whose cause was informational.
Cheaper fulfilment
High-risk orders can be routed, consolidated or packaged for easy return handling before they ship.
Assortment evidence
Persistent product-level return propensity is a quantified case for fixing or dropping a line.
Clearer margin picture
Expected return cost per line turns gross margin into something closer to the truth.
How it fits into your product
How it embeds
- Synchronous scoring at basket and checkout for pre-purchase guidance, with a strict latency budget
- Pre-dispatch batch scoring inside your warehouse management workflow
- Webhooks pushing high-risk lines into merchandising and quality queues
- Outcome feedback endpoint so actual returns continuously retrain the model
- Deployment inside your environment where order and customer data cannot leave
- Platform connectors for the common commerce and OMS stacks, or a plain JSON contract
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 12 weeksDiscovery and data review
Weeks 1–2
We agree the exact question the API answers, review the sources you already hold, check what has to be licensed, and write down the response contract your developers will code against.
Architecture and prototype
Weeks 3–4
You get a written architecture plus a working endpoint on real data — narrow, but genuinely callable — so integration can be tested against something concrete rather than a document.
Production build
Weeks 5–10
Pipelines, models, storage, authentication, rate limiting, logging, tests and documentation. Security and observability are part of this phase, not a later one.
Integration and handover
Weeks 11–12
We support your engineers through their integration, run load tests at your expected volume, and agree how the service is monitored and supported once it is live.
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
Can we refuse orders or charge high-risk customers more?
We would not build that, and we would push back if asked. Differential treatment of identified customers on a model score invites both regulatory exposure and the loss of your best shoppers — frequent returners are often frequent buyers. The interventions we design are informational and operational: better fit guidance, listing corrections, fulfilment routing.
How accurate is the prediction?
In apparel, where returns are common and structured, it is genuinely useful. In categories with a low base rate it is much weaker, because there is little to learn from. We report calibration curves by category rather than a single accuracy figure, since a probability you intend to multiply by a cost must be calibrated, not merely ranked correctly.
Do you profile individual customers?
By default no. The model uses cohort-level behavioural features rather than individual customer histories, which keeps it away from decisions about identified people and simplifies your data protection position. Individual-level features are technically possible and we would want a clear lawful basis and a specific use case before including them.
What data do you need to start?
At minimum, a year of order lines with actual return outcomes and reasons. Reason codes are often messy or free-text; cleaning them is usually the first piece of real work, and the quality of the reason classification is capped by how well they were recorded.
Will this reduce our return rate?
It can reduce the avoidable portion — sizing errors, listing misunderstandings, multi-size ordering. It will not reduce returns that are simply how customers shop in your category, and treating that part as a target leads to interventions that cost more in lost sales than they save in handling.
Related blueprints
Review Sentiment API
Topic-level sentiment, complaint trends and product quality signals extracted from reviews and support text, as an API your merchandising tools can query.
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.
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.