mmm allocate, apply and applications

Invocation#

echo-cli mmm allocate --fit <fit-id> --weekly-total <n>
echo-cli mmm apply --fit <fit-id> --weekly-total <n> --by <who>
echo-cli mmm applications

Inputs and output#

allocate writes fit_id, fitted_at, currency, outcome_event, weekly_total, channels (per channel, the most funded first: channel, coefficient, weekly_spend, modelled_outcome, marginal_return and points — each panel week's spend on the channel and the week's outcome) and left_out (channel, coefficient, reason). apply writes the stored application: id, fit_id, weekly_total, currency, applied_by, applied_at, campaigns (per campaign: campaign_id, name, channel, budget_before, budget_after — the daily budget set, null when refused — and refusal) and unplaced (each funded channel with no running campaign to take its weekly_spend). applications writes every application, newest first.

State effect#

allocate calls Echo Web's authenticated /api/analytics/mmm/allocate and apply and applications /api/analytics/mmm/allocate/applications, with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the Budget split across channels section of the tracking screen and of Echo Desktop's GEO screen split, apply (**Apply to campaign budgets**, naming who applies) and list the same, and echo-mcp runs echo_mmm_allocate and lists echo_mmm_allocation_applications but does not apply. The fit (echo-cli mmm fit) models a week's outcome as a baseline plus each channel's coefficient times log(1 + its adstock); a steady weekly spend x builds an adstock of x / (1 - the fit's carry-over), so a channel's marginal return at x is its coefficient over 1 - carry-over + x. The split maximises the summed modelled outcome for --weekly-total in the fit's currency: every funded channel ends at the same marginal return, a channel whose return at no spend is below that gets nothing, and a channel the fit gives no positive coefficient is left out. apply computes the same split now and, for each funded channel, takes the synced campaigns of that platform whose ad account declares the fit's currency, that are not PAUSED and hold a daily budget; the channel's weekly spend is shared among them in proportion to the daily budgets they hold, and each one's daily budget is set to its share over the seven days of a week through Stado's paid-ads integration, as budget rules change budgets (only platforms it can change: meta and appleads). A campaign the platform refuses, or on an inactive account, keeps its budget with the reason. Every application is stored in ad_allocation_applications; allocate stores nothing.

Refusals#

• A wrong invocation is refused before anything is sent: "mmm <verb> does not take <flag>; it takes …", "<flag> needs a value" and "mmm <verb> needs <flag>" for --fit, --weekly-total and, for apply, --by.
• Echo Web answers a bad request with "fit_id is required: the stored marketing mix fit whose curves split the budget, as echo-cli mmm list shows it", "weekly_total must be a positive number: the weekly spend to split, in the fit's currency; got <value>", "fit <id> gives no channel a positive return, so there is nothing to allocate to; refit on more weeks or another outcome", "applied_by is required: …" or "no funded channel of fit <id> has a running campaign with a daily budget in <currency>, so nothing was applied; <channels> would need one"; not found with "no marketing mix fit has id <id>; echo-cli mmm list lists them"; and fails with "the budgets of fit <id> were changed but the application could not be recorded: <cause>". The command prints Echo Web's sentence and exits 1.