How to run your first Meta Robyn model, step by step

To run Meta Robyn, you usually install the R package and its Python helper, Nevergrad, then build one table with a row per week. Describe it in robyn_inputs(), set hyperparameter ranges, fit with robyn_run() and pick one model from the shortlist. Then ask robyn_allocator() for a budget split. Expect weeks of data work first.

Step by step

1. Install Robyn in R. Run install.packages("Robyn") for the stable CRAN version, or install the dev version from GitHub with remotes. The CRAN package needs R 4.0.0 or newer. Path: Robyn docs, Getting Started > Installation.
2. Install Nevergrad once. Robyn needs a one-time install of the Python library Nevergrad, through the R package reticulate. If Python errors appear, the README points to a step-by-step guide. Path: demo.R, Step 0: Setup environment.
3. Run the demo on Meta's simulated data. Load data("dt_simulated_weekly") and data("dt_prophet_holidays"), then run demo.R from top to bottom. If it runs, your setup works, and you have seen every output before your own data arrives. Path: demo.R, Step 1: Load data.
4. Pull weekly net sales from Shopify. Go to Analytics > Reports, open Total sales over time and pick week as the time unit in the configuration panel's Dimensions menu. Add Net sales from the Metrics menu if it is missing, then export the report. Shopify's net sales are gross sales minus discounts and sales reversals, so tax and shipping stay out of your KPI. Path: Analytics > Reports > Total sales over time > Export.
5. Pull weekly spend and impressions from Meta. In Ads Manager, open the Reports drop-down and choose Create custom report. Break it down by Week under Time, add impressions and amount spent, then select the report and click Export for a.csv file. Meta caps the reporting window at 37 months from the date of your request. Path: Ads Manager > Reports > Create custom report > Export.
6. Do the same for Google Ads. Open the Campaigns table, click the segment icon and choose Time, then Week, with cost and impressions showing. Path: Campaigns > segment icon > Time > Week.
7. Build one table, one row per week. Put dates in one column, written year-month-day as the demo asks, and net sales in the next. Add one spend column and one exposure column per paid channel, plus a column for each newsletter or other unpaid activity. Robyn calls these dep_var, paid_media_spends, paid_media_vars and organic_vars. Path: Key Features > Model Inputs.
8. Add holidays and your own events. Robyn's holiday table takes your own events too, such as Black Friday, Cyber Monday or a school break. Give a promotion its own context_vars column if you want its effect measured separately. Path: Analyst's Guide > Feature Engineering > Customize holiday & event information.
9. Set hyperparameter ranges. Run hyper_names() to get the exact names, then give each channel a theta, alpha and gamma range. Meta's anecdotal rule of thumb for weekly theta is c(0, 0.3) for digital, c(0.1, 0.4) for OOH, print and radio, and c(0.3, 0.8) for TV. Check the curve shapes with plot_adstock() and plot_saturation(). Path: demo.R, Step 2a-2.
10. Fit the model. Call robyn_run() with at least 2000 iterations and 5 trials, the minimum Meta's docs recommend. Then open the convergence plots before you trust any result. Path: demo.R, Step 3: Build initial model.
11. Export the shortlist and choose one model. The robyn_outputs() function exports a one-pager for each Pareto-optimal model into your plot folder. Pick the one that matches what you know about your business, then save it with robyn_write(). Path: demo.R, Steps 3 and 4.
12. Calibrate with a lift test, if you ran one. Feed robyn_inputs() a calibration table with each test's start date, end date, incremental result and spend. Robyn accepts only a point estimate per test, not a range. Path: demo.R, Step 2a-5.
13. Ask the allocator, then refresh. Run robyn_allocator(): the max_response scenario suggests a split for a given budget, and target_efficiency finds the spend for a target ROAS. Add new weeks later with robyn_refresh(), and rebuild instead when more than half the data is new. Path: demo.R, Steps 5 and 6.

A worked example

Robyn's one-pager gives each paid channel a return figure. Meta's guide defines it as the incremental revenue a channel drove, divided by what you spent on it. To use it, you need a bar.

One store's Break-even sheet holds the arithmetic: at a 40% margin, break-even ROAS is 2.5x, because 1 divided by 0.40 is 2.5. It is a formula, not a result from that store, and it fits any store with the same margin.

For illustration, say your margin is also 40% and Robyn shows Meta at a ROAS of 3.0 over the modeling window, comfortably above 2.5x. In this worked example, ask what the average hides: what does the next €100 do?

Step 7 of Meta's demo script shows how, with robyn_response(). Ask it for the response at your current weekly spend and again at that spend plus €100.

Say the Meta budget runs at €8,000 a week and the extra €100 brings €230 in sales. In this worked example, that is a marginal ROAS of 2.3, below the 2.5x bar.

In this worked example, each extra €100 returns €230 in sales and €92 in margin. If you add more, you lose €8 on every extra €100, even though the average still looks healthy.

Then run the allocator. If you set target_efficiency with a target value of 2.5, Robyn finds the spend at which the whole mix averages 2.5x. If your margin is 40%, a mix that averages 2.5x only breaks even overall.

Read that number as a spending ceiling, not a target. The profit-maximising point sits lower, where the next euro's marginal ROAS falls to your bar.

None of this runs on a GA4 export like Store A's, which holds no spend. Robyn needs the spend columns from steps 5 and 6.

What should I check when Robyn's output looks wrong?

• Robyn warns that spend and impressions fit poorly. Split the channel, as Meta's docs suggest for prospecting and retargeting campaigns with different costs. Use spend as the input only if splitting does not help.
• The convergence plots never settle. Run more iterations. Meta's guide says larger datasets need more iterations to reach convergence.
• The fit is loose. Meta's guide treats an R-squared below 0.8 as not ideal and above 0.9 as ideal. Add the missing driver, often a promotion or a channel worth splitting.
• The residuals form waves or clusters. Meta's docs read visible patterns in the fitted versus residual chart as a missing variable. Look for a launch, a price change or a stock-out.
• The actual line spikes and the model does not. Ask what happened that week. An event missing from your holiday table looks exactly like this.
• A refresh jumps around. Meta notes the refresh feature is not yet tested thoroughly and might give unstable results. Rebuild from scratch when more than half the data is new.

What to do this week

1. Find your margin in Shopify. Go to Analytics > Reports, click the Category filter, choose Profit Margin and open Gross profit by product. Pass: a gross margin shows for your main products. Fail: blank rows, so add a cost per item to those products first.
2. Export one Meta channel by week. In Meta Ads Manager, build a custom report with the Week breakdown, impressions and amount spent, then export it. Pass: every week of the last two years has both numbers. Fail: the report stops short of two years, which Robyn's guide calls the minimum.
3. Annotate last year's sales. In Shopify, open Total sales over time, click Annotations and add each sale with its dates. Pass: every sale week carries a marker you can copy into Robyn's events table. Fail: you cannot date last summer's sale, and the model may hand its spike to whatever channel spent most that week.

Check the homework. Your GA4 Attribution paths export already holds the evidence. Causality Engine reads that one file and shows what each channel caused next to what last-click gave it, in 1 to 2 minutes, for €99 once (excluding VAT), refundable within 30 days. Check the homework

Sources, 1 October 2026: Installation (Meta); Robyn package page (CRAN); Robyn README (Meta); Robyn demo.R (Meta); Key Features (Meta); An Analyst's Guide to MMM (Meta); Sales reports (Shopify); Setting and comparing time ranges for your reports (Shopify); Filtering and editing your reports (Shopify); Exporting reports (Shopify); Export and share reports in Meta Ads Reporting (Meta); About breakdowns, metrics and filtering in Meta Ads Reporting (Meta); Use segments in your tables (Google); Profit reports (Shopify); Annotations in your Shopify reports (Shopify)

Related answers

• All MMM & measurement questions
• What is Meta Robyn?
• Does Meta Robyn work for a food and beverage brand?
• Regression analysis, defined
• Incrementality testing, explained