Overview

What this analysis answersCopy Anchor Link

The Forecast API projects the organization's revenue for the next 12 months. It starts from what happened in the last 30 days (funnel volume and conversion rates, repurchases, media investment, revenue and average ticket) and returns one projection: the current funnel with the changes you simulate. Without changes, the projection is the funnel as it is.

Questions you can answer:

• How much revenue do we make per month today, and how much did we make in the last 12 months?
• If we invest 20% more and improve the cart rate by 10%, how much revenue do we get in 12 months?
• How much of the revenue comes from repurchases, and how much do they add if they grow 15%?
• How much does revenue change if the average ticket rises 5%?
• How long until a change shows up in revenue, if it takes 4 months to ramp up?

Which endpoint to useCopy Anchor Link

Available endpointsCopy Anchor Link

• getGet Forecast Baseline/v1/forecast/baselineThe monthly baseline the forecast starts from, assembled from the dashboards' own reads: the acquisition funnel, the media investment and…
• postSimulate Forecast/v1/forecast/simulateProjects the 12 months starting at baseline.windowStart over the same (cached) baseline GET /v1/forecast/baseline returns: the current…

How the projection is calculatedCopy Anchor Link

Monthly revenue adds two parts, acquisition and repurchase:

1. Volume of the first stage × traffic factor. Investment follows traffic at a constant cost per unit, so it scales linearly.
2. That volume × the conversion rate of each following stage = chain orders. Only the share that is not repurchase counts as acquisition orders.
3. Repurchase orders = the repurchase orders of the last 30 days (the RETENTION stage) × (1 + the retention %).
4. (Acquisition + repurchase) × average ticket = modeled revenue.
5. Modeled revenue × calibration factor = projected revenue.

The funnel counts events summed across tools, not distinct orders, so funnel × ticket rarely matches billed revenue. The calibration factor (calibrationFactor) is real revenue ÷ modeled revenue (acquisition + repurchase): it makes the current drivers reproduce the real revenue of the last 30 days. Without real revenue, the factor is null and the model runs unscaled.

Retention (repurchase)Copy Anchor Link

The RETENTION stage counts the repurchase orders of the window: orders by a customer who had already bought in the same 30 days (Shopify, Tray and VTEX; on spreadsheets, customers with a repeat order). Those orders are already among the DECISION orders, so the projection never counts them twice: the chain scales only the acquisition share (DECISION orders minus repurchases) and the repurchases are added on their own, moved only by the retention %. The stage rate (rate) is the share of orders that are repurchases (RETENTION ÷ DECISION), the same % of previous stage the funnel shows. RETENTION is present only when it is enabled in the funnel and the chain ends in DECISION; it is always the last item of stages.

E-commerce funnelCopy Anchor Link

For online stores under the V4MOS e-commerce standard (business model vendas_online, Google Analytics 4 and an e-commerce platform connected, with the Attention, Interest, Qualification and Decision stages configured), the chain follows the store formula:

Revenue = Sessions × Cart rate × Checkout rate × Purchase rate × Average ticket

EXPOSURE (impressions) and COMMITMENT (checkout completed) are not part of this chain. The response says which formula was used in funnelKind (ecommerce or generic). Every other organization uses the generic chain: every configured stage up to the last customer-side stage, then RETENTION, with role: null.

Sector floorsCopy Anchor Link

Each stage carries in floor the market benchmark of its conversion for the organization's business model (businessModel: online_sales, inside_sales or pos), the same reference the bottleneck diagnosis uses. It is only a reference to show next to the stage: the projection never raises a conversion to the floor on its own. RETENTION has no floor. The floor of a stage is the benchmark of the transition into it (Attention, Interest, Qualification, Commitment, Decision). When the chain skips a stage, the floor multiplies the benchmarks it spans: in e-commerce, the purchase rate (orders ÷ checkouts started) is floored by Commitment × Decision. Without a known business model, businessModel and every floor are null. The model comes from the organization record when the call carries the user token; with x-client-id/x-client-secret, it comes from the organization's funnel configuration.

Simulator inputsCopy Anchor Link

Every input is a % change over the current value. It starts at the current value in month 1 and reaches the target in month rampMonths + 1 in a straight line, then stays there (rampMonths 0 applies the target from month 1).

Every % change is limited to the range -50 to 200. A % change on a stage without a measurable rate (rate null or 0) has no effect.

ResponseCopy Anchor Link

result.projection carries the 12 months (months) and the totals (totals): revenue, repurchase revenue (repurchaseRevenue), investment, orders, repurchase orders (repurchaseOrders) and ROAS. result.baselineMonthlyRevenue is the monthly revenue at the current drivers (the real revenue when calibrated), the "current" side of revenue.

Important rulesCopy Anchor Link

Status of the baselineCopy Anchor Link

POST /v1/forecast/simulate returns result: null whenever data.status is not ready.

PeriodsCopy Anchor Link

• The baseline uses the last 30 calendar days ending today, in Brasília time (America/Sao_Paulo).
• The 12-month revenue (trailingRevenue) uses the last 365 days. When that read is not available, it is the last 30 days × 365/30, with annualized: true.
• Month 1 of the projection is the current month (windowStart).
• Counts are event volume summed across tools, not distinct people.

null means "not defined", never zeroCopy Anchor Link

monthlyRevenue, trailingRevenue, rate, sourceLabel, calibrationFactor and roas can be null. Show a dash instead of a number.

ParametersCopy Anchor Link

Unknown fields return 400.

ExampleCopy Anchor Link

curl -X POST "https://data.v4mos.ai/v1/forecast/simulate" \
  -H "x-client-id: your_client_id" \
  -H "x-client-secret: your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "organization_123",
    "inputs": {
      "investmentPct": 20,
      "ticketPct": 0,
      "stagePct": { "INTEREST": 10, "RETENTION": 15 },
      "rampMonths": 4
    }
  }'

AuthenticationCopy Anchor Link

Every endpoint uses the base URL https://data.v4mos.ai and requires the x-client-id and x-client-secret headers. See Authentication.