Stoke Pricing API · v1

Defensible pricing, from any console.

The API returns a deterministic next-price recommendation and the evidence needed to explain it: decision thresholds, resolved demand bounds, a worst-case profit guarantee, assumptions, and warnings.

Quickstart

Send an API key as a bearer token or in x-api-key. Authentication is skipped only during local development when no keys are configured.

curl https://YOUR_STOKE_HOST/api/v1/recommendations \
  -H "Authorization: Bearer $STOKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currentPrice": 99,
    "currentVolume": 1200,
    "currency": "USD",
    "volumePeriod": "month",
    "bounds": {
      "mode": "elasticity",
      "epsSteep": -2.5,
      "epsFlat": -0.5
    }
  }'

Example response

{
  "object": "pricing_recommendation",
  "recommendation": {
    "currentPrice": 99,
    "recommendedPrice": 99,
    "direction": "hold",
    "percentChange": 0,
    "currency": "USD"
  },
  "explanation": {
    "decision": {
      "branch": "hold",
      "observedVolume": 1200,
      "lowerThreshold": 600,
      "upperThreshold": 3000,
      "comparison": "volume_between_thresholds",
      "activeSlope": null,
      "formulaId": "sigma_lin_hold"
    },
    "guarantee": {
      "captureFraction": 0.5556,
      "interpretation": "worst_case_profit_floor",
      "strength": "moderate"
    }
  }
}

Values are returned at full precision; round only at presentation time. Every response includes an x-request-id header for tracing.

Choosing inputs

Every request needs the current price, sales volume for one consistent period, and a credible range for how demand changes with price.

Elasticity bounds
Consultants with an industry or research-backed elasticity range.
Supply epsSteep and epsFlat, both negative. Stoke converts them to demand slopes at the current observation.
Historical observations
Teams with comparable price and volume observations.
Supply at least two distinct prices. Stoke derives all pairwise slopes and rejects observations that violate non-increasing demand.
Direct slope bounds
Pricing specialists with calibrated units-per-currency slopes.
Supply tauLo (steepest) and tauHi (flattest), where tauLo ≤ tauHi < 0.

Interpreting outputs

recommendation
The next price, direction, and decimal percentage change. This is the algorithmic output; it is not an instruction to deploy without checking excluded business constraints.
explanation.decision
Shows the observed volume, lower and upper thresholds, comparison, active slope, and formula branch. These fields answer “why did the algorithm move—or hold—the price?” without relying on an AI-generated rationale.
captureFraction
The worst-case share of long-run informed monopoly profit guaranteed under the model assumptions. For example, 0.56 means at least 56% in the theoretical worst case. It is not confidence, probability, forecast accuracy, or expected uplift.
strength
A product label for the profit floor: strong at 80% or more, moderate from 50% to under 80%, and weak below 50%.
interpretation
Human-readable text paired with stable codes, suitable for a console, agent, or client-facing draft. Numeric claims should still be read from the structured fields.
diagnostics
Present in history mode. Includes empirical slopes, padding, and a high-spread flag so users can assess the quality of the derived bounds.

How the algorithm works

Let p be the current price, q current volume, and τlo ≤ τhi < 0 the resolved demand-slope bounds. Stoke compares volume with two thresholds:

raise when q > |τlo|p
hold when |τhi|p ≤ q ≤ |τlo|p
lower when q < |τhi|p

In a raise branch, the next price is p/2 + q/(2|τlo|). In a lower branch it is p/2 + q/(2|τhi|). The hold branch returns p. The profit-capture floor is 4|τlo||τhi| / (|τlo| + |τhi|)².

The strategy is based on Malladi, Guarantees in Price Experimentation (Kellogg MEDS, March 2026). The API exposes the implemented branch and thresholds so the calculation can be reproduced independently.

Assumptions and limitations

  • Demand is non-increasing and the supplied bounds hold across the relevant price range, not only locally.
  • One request represents one product and one coherent customer segment.
  • The model does not include strategic competitor reactions.
  • The objective does not incorporate marginal cost, capacity, regulation, contracts, or operational constraints.
  • Historical association is not automatically causal demand evidence; promotions, seasonality, and mix shifts can bias derived slopes.
Use Stoke as a defensible pricing input. Before implementation, combine the result with excluded constraints and—especially when the capture floor is moderate or weak—validate it through tighter demand research or a controlled price test.