# ROAS.to — Full Reference

> Multi-tenant Facebook Ad Optimization SaaS for affiliate and DTC media buyers. $499/mo per workspace, 3-day free trial, no card required. Additional Facebook Business Managers $99/mo each beyond the first. Affiliate program pays $200 per referral's monthly payment for 12 months.

This file is the complete product corpus — every help article, every concept, every workflow — concatenated as markdown for one-shot LLM retrieval. For the curated index, see [/llms.txt](https://www.roas.to/llms.txt). For the human-browsable version, see the in-product help center at https://www.roas.to.

## Table of contents

- [Getting Started](#getting-started) — Set up your account and connect Facebook
- [Facebook Ads](#facebook-ads) — Manage campaigns, ad sets, ads, and creatives
- [On-Page A/B Tests](#snippet-testing) — A/B test your landing pages automatically
- [Multi-Page Rotation](#campaign-tracker) — Track links, split test URLs, and attribute conversions
- [Automation](#automation) — Rules, auto-scaling, and Bulk Ad Creation
- [AI Tools](#ai-tools) — Ad Copy Editor, Product Copy Generator, AI Consultant, and AI generation
- [Analytics](#analytics) — Insights, funnels, dayparting, and creative analysis
- [Conversions & Tracking](#conversions) — Conversion tracking, Everflow, Shopify, and CAPI
- [Settings](#settings) — General settings, notifications, integrations, and team
- [Billing & Account](#billing) — Plans, payments, data export, and account management


## Getting Started

Set up your account and connect Facebook

### What is ROAS.to?

_A high-level overview of the platform and what it does for Facebook media buyers._

ROAS.to is an all-in-one optimization platform built for Facebook media buyers — affiliates and DTC brands alike.

**What it does:**
- Syncs your Facebook ad accounts every minute so your data is always fresh
- Automatically pauses losing campaigns and scales winners based on rules you define
- A/B tests your landing pages with statistical rigor (Thompson Sampling)
- Clones top-performing campaigns with optional AI variations
- Generates ad copy and creatives using AI
- Tracks conversions across Facebook, Everflow, and Shopify

**How it works:**
You bring your own Facebook Developer App and system user token. ROAS.to connects to your ad accounts, syncs all your data, and gives you tools to manage, optimize, and scale — all from one dashboard.

**Pricing:**
3-day full-access trial, then $499/mo — all features included, no tiers.

---

### Creating your Facebook Developer App

_Step-by-step guide to creating the Facebook app required for connecting your accounts._

ROAS.to uses a "Bring Your Own App" model — you create your own Facebook Developer App so you get your own rate limits and full control.

**Step 1: Register as a Facebook developer**
If you haven't already, go to developers.facebook.com and click "Get Started." Follow the registration steps (takes about 2 minutes).

**Step 2: Create a new app**
1. Go to developers.facebook.com/apps/creation/
2. Choose "Business" as the app type
3. Give it a name (e.g., "ROAS.to Integration")
4. Select your Business Manager

**Step 3: Get your App ID and App Secret**
1. Go to your app's Settings > Basic
2. Copy the **App ID** (numeric)
3. Click "Show" next to App Secret and copy it (hexadecimal string)

Keep these credentials safe — you'll enter them in the next onboarding step.

**Why your own app?**
- Your own Facebook API rate limits (not shared with other users)
- Full control over your data and permissions
- Permanent system user tokens that never expire

---

### Creating a System User & generating a token

_How to create a system user in Business Manager and generate a permanent access token._

A system user is a special Facebook account that acts on behalf of your business. Unlike personal tokens, system user tokens are permanent — they never expire.

**Step 1: Go to Business Settings**
Navigate to business.facebook.com > Settings > Users > System users.

**Step 2: Create a system user**
1. Click "Add"
2. Name it (e.g., "ROAS.to Bot")
3. Set the role to **Admin**

**Step 3: Assign assets**
Click "Add Assets" and assign the following with **Full Control**:
- Ad Accounts (all accounts you want to manage)
- Pages (all pages you run ads from)
- Pixels (all conversion pixels)
- Instagram Accounts (if using Instagram placements)
- Apps (your newly created developer app)

**Step 4: Generate a token**
1. Click "Generate New Token"
2. Select your app from the dropdown
3. Check these scopes: **ads_management**, **ads_read**
4. Click "Generate Token"
5. Copy the token (starts with "EA...")

This token is permanent and will be encrypted before storage. You'll never need to refresh it.

---

### Connecting your Facebook ad accounts

_How to connect your FB credentials and select which ad accounts to sync._

Once you have your App ID, App Secret, and System User Token, you're ready to connect.

**In the onboarding wizard:**
1. Enter your App ID, App Secret, and System User Token
2. Click "Connect" — we'll validate your credentials and discover available ad accounts
3. Select which ad accounts you want to manage (you can add more later in Settings > Accounts)
4. Choose your historical sync depth (how much past data to import):
   - **30 days** (default) — initial sync takes ~2 minutes, good for getting started
   - **90 days** — initial sync takes ~5-10 minutes, more historical context
   - **Maximum** — initial sync takes ~15-30 minutes, full history going back up to 3 years

After the initial import completes, ROAS.to automatically syncs:
- All campaigns, ad sets, and ads
- Facebook Pages and Pixels
- Instagram business accounts
- Performance metrics (spend, impressions, clicks, conversions)

**Your data syncs every minute** once connected. You can also trigger a manual sync from the Insights page.

---

### Setting up conversion tracking

_How to configure postback URLs and integrate conversion data from your network or store._

ROAS.to needs to know when conversions happen so it can calculate ROAS, optimize campaigns, and promote winning A/B test variants.

**Option 1: Postback URL (Everflow, HasOffers, etc.)**
During onboarding, you'll see a postback URL formatted for your affiliate network. Copy it from **Settings → Integrations → Tracking** — it uses your custom tracking domain when one is active (e.g. `https://tracker.yourbrand.com/p/{your-postback-id}?...`), or the platform fallback `https://track.roas.to` otherwise. It should never use `https://api.roas.to` — that URL no longer accepts direct postbacks. Paste the URL from the dashboard into your network's global postback settings.

ROAS.to auto-generates network-specific URL templates for Everflow, Voluum, RedTrack, and Bemob with the correct macros. Key parameters:
- `transaction_id` — unique conversion ID (required)
- `payout` — conversion value/payout amount (required)
- `offer_id`, `offer_url_id` — Everflow offer tracking
- `sub1` through `sub5` — sub-ID tracking parameters for attribution

**Option 2: Everflow integration**
Go to Settings > Integrations > Everflow and fill in your API Key, Network ID, Everflow Network Name, Affiliate Tracking Code, and Tracking Domain. ROAS.to will auto-sync conversions.

**Option 3: Shopify integration**
Go to Settings > Integrations > Shopify and connect your store. Orders are tracked automatically via pixel.

**Option 4: Conversions API (CAPI)**
For server-side tracking, enable CAPI in Settings > Integrations. This sends conversion events back to Facebook for better attribution.

You can skip this during onboarding and set it up later — but conversion tracking is essential for most features to work properly.

---

### Making sure tracking parameters reach Shopify through every funnel

_Attribution breaks silently when tracking parameters get stripped between Facebook and Shopify. Here is how to configure each funnel shape so they arrive intact._

ROAS.to ties every sale back to the exact Facebook ad that drove it using tracking parameters (`sub1` through `sub5`) that travel in the URL from your ad all the way to Shopify. `sub1/sub2/sub3` carry the Facebook campaign / adset / ad IDs, `sub4` is a click ID that links the conversion back to the exact visitor session, and `sub5` carries the Facebook click identifier (fbclid) when your tracker doesn't forward it natively.

If these parameters arrive in the URL on the Shopify landing page, everything just works. If they get stripped at any hop between Facebook and Shopify, the sale lands with no attribution and stays invisible to the campaign dashboards.

**The universal rule**: cookies don't bridge domains. The parameters MUST arrive in the Shopify URL — there's no other mechanism that reliably survives the jump from one domain to another.

**Four common funnel shapes, and what each needs:**

**1. Ad → Shopify (direct)**
Nothing to configure. Parameters ride the ad URL straight to your Shopify page. Paste the Shopify Custom Pixel (Settings > Integrations > Shopify) and you're done.

**2. Ad → ROAS.to advertorial → Shopify**
Nothing to configure. The ROAS.to advertorial template auto-forwards the parameters to every CTA link. Paste the Shopify Custom Pixel and you're done.

**3. You route traffic through a click tracker (Everflow, Voluum, RedTrack, BeMob, HasOffers, etc.)**
Click trackers record your sub parameters when the click lands, but they only pass them to the next page if you tell them to via macros on the destination URL. In your tracker's offer/link settings, append these macros to the destination URL (replace `your-landing-page` with wherever the tracker should redirect — a Shopify page, a landing page, whatever):

`https://your-landing-page?sub1={sub1}&sub2={sub2}&sub3={sub3}&sub4={sub4}&sub5={sub5}`

Most trackers use the `{sub1}` macro syntax; a few use different names — check your tracker's macro docs if unsure. One-time edit per offer. If the destination is itself a landing page (not Shopify directly), that page still needs to forward parameters to its Shopify CTA — the ROAS.to advertorial does this automatically; custom landing pages use the code from Option 4 below.

Edge case: if you're using a click tracker as your final offer (typical affiliate setup, not routing traffic anywhere else) and your conversions fire via a server-side postback to ROAS.to, you don't need this — the postback carries subs server-side.

**4. Ad → external funnel (ClickFunnels, Kartra, Unbounce, etc.) → Shopify**
Static CTA links on a funnel page don't carry URL parameters forward to Shopify by default. You have two options:

- **Recommended**: Select "I use an external funnel" in Settings > Integrations > Shopify. You'll get a small piece of code to paste on your funnel page that only rewrites the outbound Shopify link — no cookies, no analytics, no tracking of your funnel visitors. It uses Shopify's line-item properties format (`/cart/add?id=VARIANT&quantity=1&properties[__roas_sub1]={sub1}&...`) which persists through checkout, unlike the `attributes[]` format on cart permalinks which Shopify drops.
- **Manual**: Rewrite your funnel's Shopify CTA link yourself using the same `/cart/add` format. Same end result.

**How to check if your funnel is configured correctly**: open one of your own Facebook ads in a browser, click through all the way to Shopify, and look at the final URL in the address bar. If it has `?sub1=...&sub2=...&sub3=...` in it, tracking is working. If those parameters disappear somewhere along the chain, that's the hop where you need to apply the config above.

**Server-side safety net**: if you're running both the Shopify Custom Pixel AND an Everflow postback for the same merchant, the two conversion writers dedupe on the Shopify order ID. Whichever fires second won't double-count revenue. If Everflow arrives first without attribution and Shopify arrives later with strong attribution, the Shopify webhook now upgrades the existing row in place rather than silently short-circuiting — so you don't lose attribution just because one writer happened to fire before the other.

---

### Navigating the dashboard

_A tour of the main dashboard sections and how to find what you need._

The sidebar is organized into five sections.

**The Floor** — your daily check-in
- **Overview** — your workspace home; top campaigns, recent conversions, store-direct revenue
- **Operations** — live system health, sync status, automation activity, FB token health

**The Workshop** — building and running ads
- **Ads**: Campaigns, Ad Sets, Ads, Create Ads, Launches
- **Creatives**: Creatives, Posts, Boosts, Media Library, Copy Library
- **Automation**: Rules, Auto-Scaling, Auto-Boost

**The Ledger** — the numbers
- **Analytics**: Insights, Creative Analysis, Dayparting, Funnel, Comparison, Budget Insights
- **Conversions**: Conversions, Offers

**The Lab** — testing and AI
- **Tests**: On-Page A/B Tests, Multi-Page Rotation
- **AI Studio**: AI Overview, Ad Lab, Ad Copy Editor, Product Copy Generator, Bulk Ad Creation, Account Health Check, Creative Strategist, Reports, AI Consultant. (More AI tools — Audience Analyzer, Scaling Advisor, Competitor Rewriter, Page Rewriter, and the Dayparting Optimizer — open from the AI Overview page.)

**The Back Office** — settings and account
- **Settings**: General, Accounts, Ad Defaults, Automation, Integrations, Domains, Team, MCP Tokens, MCP Connections, Notifications, Billing, Activity

Your Attention inbox (items waiting on your decision) and Admin Console (admins only) round things out.

**Tips:**
- Pin frequently used pages by hovering over a nav item and clicking the pin icon
- Collapse sections you don't use often by clicking the section header
- Use the theme toggle in the top of the sidebar to switch between dark and light mode

---

### Troubleshooting: Data not syncing

_What to do when your Facebook data stops updating._

If your data appears stale or isn't updating:

**Check the sync status indicator:**
Look at the sync badge on the Insights page. If it shows "Stale," there may be a sync issue.

**Common causes:**

1. **Token expired or revoked**
System user tokens are permanent, but they can be revoked if:
- The system user was removed from Business Manager
- The app was deleted or deactivated
- Business Manager access was changed
Fix: Re-create the system user token and update it in Settings > Accounts

2. **Rate limiting**
Facebook has API rate limits per app. If you're making too many requests:
- Wait 15-30 minutes for limits to reset
- Consider reducing the number of connected accounts

3. **Facebook API issues**
Occasionally, the Facebook API has outages or degraded performance. Check Facebook's status page.

4. **Account deactivated**
If a Facebook ad account is deactivated by Facebook, ROAS.to can't sync its data.

**Manual sync:**
Try triggering a manual sync from the Insights page. If that fails, check the error message for specifics.

**Still stuck?**
Contact support — we can check your sync logs and identify the issue.

---

### Tips and keyboard shortcuts

_Useful tips for navigating and using the platform efficiently._

**Navigation tips:**
- **Pin pages** — hover over any nav item and click the pin to add it to your Pinned section
- **Collapse sections** — click any section header to collapse/expand it
- **Theme toggle** — switch between dark and light mode from the sidebar header

**Dashboard tips:**
- Use date range filters consistently across pages for meaningful comparisons
- The "Attention" page surfaces items that need your review — check it daily
- Set up Slack or Telegram notifications so you don't have to watch the dashboard constantly

**Testing tips:**
- Start with single-element tests before trying multivariate
- Let tests run until they reach your confidence threshold before promoting
- Deploy after every change — changes don't take effect until deployed

**Automation tips:**
- Start with conservative rules (high thresholds, long time windows)
- Use quiet hours to prevent overnight actions
- Monitor the execution log regularly to verify rules are behaving as expected
- The kill switch is your emergency brake — don't hesitate to use it

**Performance tips:**
- If the dashboard feels slow, check that you're not loading massive date ranges
- Use account filters to focus on specific accounts instead of loading all data
- The sync indicator tells you when data was last refreshed


## Facebook Ads

Manage campaigns, ad sets, ads, and creatives

### Managing campaigns

_How to view, filter, and manage your Facebook campaigns._

Go to **Ads Manager > Campaigns** to see all your Facebook campaigns.

**Filtering:**
- Filter by account (if you have multiple ad accounts connected)
- Filter by status: Active, Paused, or Archived
- Search by campaign name
- Select a date range for performance metrics

**Campaign details:**
Click any campaign to see its detail page with:
- Performance metrics (spend, impressions, clicks, CTR, CPC, conversions, ROAS)
- Ad sets within the campaign
- Linked automation rules
- Quick actions (pause, activate, duplicate)

**Bulk actions:**
Select multiple campaigns using checkboxes, then use the bulk action menu to:
- Pause all selected
- Activate all selected
- Update budgets in bulk

**Data freshness:**
Your campaign data syncs every minute. The sync status indicator in the top-right shows when the last sync completed. You can trigger a manual sync from the Insights page if needed.

---

### Managing ad sets

_How to view, edit, and bulk-update ad sets._

Go to **Ads Manager > Ad Sets** to view all your ad sets across campaigns.

**Viewing ad sets:**
- Filter by campaign, status, or search by name
- Click any ad set to see its performance metrics and the ads within it

**Bulk operations:**
- **Bulk Update Bid** — select multiple ad sets and change their bid amounts at once
- **Bulk Update Budget** — change daily or lifetime budgets for multiple ad sets simultaneously

**Ad set details:**
The detail page shows:
- Performance breakdown (spend, impressions, clicks, conversions, CPC, CPM, ROAS)
- Individual ads within the ad set
- Status and budget information
- Targeting summary

---

### Managing ads

_How to view, duplicate, and manage individual ads._

Go to **Ads Manager > Ads** to see all your ads across all campaigns.

**Filtering and search:**
- Filter by ad set, status, or campaign
- Search by ad name
- Select date range for performance data

**Ad actions:**
- **Duplicate** — clone an existing ad (creates a copy in the same ad set)
- **Pause / Activate** — toggle ad status
- **View creative** — see the ad's image, headline, body text, and CTA

**Bulk actions:**
Select multiple ads to pause, activate, or update budgets in batch.

**Creating new ads:**
Use **Ads Manager > Create Ads** for the full creation wizard, which walks you through selecting a campaign, ad set, creative, and launch settings.

---

### Managing creatives

_How to use the creative asset library to manage images and ad creatives._

Go to **Ads Manager > Creatives** to manage your ad creatives.

**What's here:**
- All your Facebook ad creatives synced from your accounts
- Images and media you've uploaded
- Performance data per creative

**Uploading images:**
You can upload images directly from this page or from the Create Ads wizard. Images are stored in your ROAS.to account and can be pushed to Facebook when creating ads.

**Dual upload:**
When creating ads, you can upload two images at once (e.g., for A/B testing different visuals).

---

### Creating new ads

_How to use the ad creation wizard to launch new Facebook ads._

Go to **Ads Manager > Create Ads** to launch new ads.

**The creation wizard walks you through:**
1. Select or create a campaign
2. Choose your ad set (audience, placement, budget)
3. Upload or select a creative (image/video)
4. Write your ad copy (headline, body text, CTA)
5. Set your tracking URL and parameters
6. Review and launch

**Tips:**
- Use the AI headline generator (sparkle icon) to generate multiple headline variations
- The AI Ad Copy Editor can refine your body copy with instructions like "make it more urgent"
- Set your default ad settings in Settings > Ad Defaults to pre-fill common values
- ROAS.to automatically opts out of Facebook's AI creative enhancements when creating creatives, giving you full control over what's shown

**From variant:**
You can also create an ad directly from a winning page test variant — the "Create from Variant" flow pre-fills your ad with the winning page URL and copy.

---

### Shopping Ads and product catalogs

_How to launch Meta catalog ads from ROAS.to using synced catalogs and product sets._

Shopping Ads use a Meta product catalog instead of uploaded ad images. ROAS.to creates a regular **OUTCOME_SALES** campaign with a catalog-aware ad set, then Meta renders each product card from your feed.

**What you need first**
- A Meta product catalog connected to the same Business Manager as your ad account
- At least one non-empty product set
- A pixel selected in the create-ads form
- Catalog advertising permission for the connected ad account and user/system user
- An allowed destination host for the product URLs. Shopify catalogs get this automatically; other catalogs need the host added in Settings > Integrations > Catalogs.
- Product IDs that use letters, numbers, dots, underscores, or hyphens only. ROAS.to accepts catalog `retailer_id` values up to 128 characters for Shopping Ad click attribution.

ROAS.to syncs catalogs, product sets, and product audiences in the background. You can review them in **Settings > Integrations > Catalogs**.

Catalogs can be visible before they are usable for ads. If a catalog says permission is not checked or missing, open **Meta Business Settings > Data Sources > Catalogs**, select the catalog, and assign the connected ad account plus the user/system user with catalog advertising access. Then return to ROAS.to and click **Check permission**.

**Launching a Shopping Ad**
1. Go to **Ads Manager > Create Ads**.
2. Choose **Catalog** (next to the **Page Test** and **Link Group** options).
3. Pick the ad account, page, pixel, catalog, and product set.
4. Choose a creative format: Single product, Carousel, Collection, or Dynamic voice.
5. Write headline/body templates. Product macros like `{{product.name}}` can be used in copy.
6. Run the pixel check. ROAS.to compares recent ViewContent `content_ids` against catalog `retailer_id` values.
7. Pick Prospecting, Retargeting, or Custom targeting and launch.

**How clicks are tracked**
Shopping Ads route through `/pc/{shoppingLinkId}` on your tracking domain. Meta expands the destination from the product feed, ROAS.to validates the destination host, stamps `_pid` with the product `retailer_id`, and adds a catalog-shaped `sub4` click bond. This preserves per-product attribution in conversions and product-click reporting.

The host allowlist is a safety control. If a product feed URL points to a host that is not allowed for that catalog, ROAS.to blocks the redirect instead of sending shoppers to an unexpected domain.

**Why product images are hidden in the form**
Catalog ads do not use uploaded ROAS.to images. Meta supplies product images from your catalog feed, so the image upload section is intentionally hidden for Shopping campaigns.

Shopping Ads launch using the same launch controls as other campaigns. ROAS.to does not force Shopping Ads to start paused; choose the launch state you want in the review step.

---

### Shopify catalogs for Shopping Ads

_How Shopify-source catalogs work, what ROAS.to detects automatically, and how product IDs must line up._

Shopify catalogs get a smoother setup path because ROAS.to can usually detect the shop domain from Meta catalog metadata.

**Automatic Shopify handling**
When a synced catalog looks Shopify-backed, ROAS.to:
- Shows a Shopify badge in the catalog picker and Settings > Integrations > Catalogs
- Auto-populates the allowed destination host from the shop domain
- Keeps that host read-only so product click redirects cannot be pointed elsewhere
- Uses product feed URLs from Meta when building Shopping Ad click URLs

**Product ID matching**
For deterministic product attribution, the catalog's `product.retailer_id` must match the product IDs sent by your pixel or Shopify order payload. ROAS.to sends that value through the click URL as `_pid` and stores it on conversions as `fb_product_id` when it matches the order line items.

If `_pid` does not match an order line item, ROAS.to logs the mismatch and does not write `fb_product_id`. Campaign attribution is still preserved when the Facebook campaign/ad set/ad IDs or catalog `sub4` are valid; the mismatch only prevents revenue from being assigned to the wrong product.

ROAS.to accepts `retailer_id` values containing letters, numbers, dots, underscores, and hyphens. If your Shopify catalog uses a different identifier shape, update the feed or pixel mapping before launch so the catalog ID and purchase payload match.

**Non-Shopify catalogs**
WooCommerce, BigCommerce, Magento, manual feeds, and custom catalogs work too. Add the destination host your products use in **Settings > Integrations > Catalogs** before launching. ROAS.to only redirects Shopping Ad clicks to hosts on that allowlist.

**Before launch**
Run the pixel check in the Create Ads Shopping section. A healthy result means recent ViewContent events and the selected product set share product IDs. If it reports no data or mismatch, verify your Meta Pixel / Shopify Custom Pixel installation before spending.

---

### Product retargeting audiences

_How Product audiences work for Shopping Ads retargeting and when to create one._

Shopping Ads support prospecting and retargeting.

**Prospecting**
Use Prospecting when you want Meta to find new buyers from broad targeting or Advantage+ Audience style inputs. The ad set still carries the selected product set, so Meta can render product-specific ads.

**Retargeting**
Use Retargeting when you want to reach people who viewed or engaged with products. Product audiences are Meta custom audiences with subtype `PRODUCT`.

In the Shopping section:
1. Choose **Retargeting**.
2. Pick an existing Product audience for the selected product set, or click **Create audience**.
3. Choose the retention window.

ROAS.to stores the audience with its product set ID, so future launches only show audiences relevant to the selected set.

Retargeting Shopping Ads require a Product audience. If you remove the audience in Meta, choose or create a new Product audience before cloning or launching a retargeting Shopping campaign.

**Common blockers**
- Product set is empty: add products in Commerce Manager or adjust the product set filter.
- Catalog permission is not checked or missing: in Meta Business Settings, assign the catalog to the connected ad account and user/system user, then click Check permission in ROAS.to.
- Pixel check fails: make sure ViewContent events send `content_ids` that match catalog `retailer_id` values.

---

### App advertising setup

_How to prepare Meta, pick your app, choose AEM or SKAdNetwork attribution, and launch App Promotion campaigns from ROAS.to._

Use **Ads Manager > Create Ads** and choose **App Promotion** when you want Facebook to drive installs for an iOS or Android app.

**What ROAS.to creates**
ROAS.to creates a Meta **OUTCOME_APP_PROMOTION** campaign. For app campaigns, the promoted object is the app itself, not a pixel. The campaign links directly to the Apple App Store or Google Play store URL synced from Meta.

For iOS campaigns, ROAS.to also creates the iOS 14+ campaign and ad set fields Meta expects:
- Campaign-level app promoted object
- iOS 14+ campaign flag
- App ad set promoted object
- 1-day click attribution window
- iOS device targeting for iPhone, iPad, and iPod
- App install state set to people who have not installed the app
- Your selected iOS attribution method: Meta AEM or Apple SKAdNetwork

**Meta prerequisites**
Before the app appears in ROAS.to, set it up in Meta:
1. Add the app in Meta Events Manager / Business Settings.
2. Connect the app to the ad account you will use.
3. Assign the app asset to the same system user token you connected to ROAS.to.
4. Give the system user full control for the app, ad account, page, and any Instagram account you plan to use.
5. Configure install tracking for the app in Meta Events Manager using the Facebook SDK or an MMP integration.
6. For iOS AEM, make sure the app is eligible for Aggregated Event Measurement in Meta Events Manager.

ROAS.to filters the app picker to apps where Meta reports install tracking is configured. If an app has the same App Store URL but is a duplicate Facebook App without install tracking, ROAS.to hides or rejects it because Meta will reject campaign creation.

**Syncing apps into ROAS.to**
ROAS.to syncs advertisable Facebook apps from Meta in the background. If you just added or fixed an app in Meta, wait for the next app sync. The App Promotion objective appears once ROAS.to has at least one eligible app.

If the App Promotion option is missing:
- Confirm the app is assigned to the connected ad account.
- Confirm the app is assigned to the system user used by ROAS.to.
- Confirm install tracking is configured in Events Manager.
- Confirm you are using the right ad account in the Create Ads form.
- Wait for the app sync to run after changing Meta settings.

**Creating an App Promotion campaign**
In **Ads Manager > Create Ads**:
1. Choose the Facebook ad account.
2. Choose the Facebook Page and Instagram account if needed.
3. Set **Campaign Objective** to **App Promotion**.
4. Pick the app and platform from the **App** dropdown.
5. For iOS apps, choose **Attribution**.
6. Upload/select creative and write ad copy.
7. Set budget, targeting, placements, and launch mode.
8. Submit the campaign.

The app dropdown fills the Facebook App ID, store URL, and platform automatically. ROAS.to re-checks those values on the server and uses the canonical store URL from Meta, so the browser cannot accidentally submit the wrong app URL.

**Choosing iOS attribution**
For iOS apps, ROAS.to shows two options:
- **Meta attribution for iOS 14+ (AEM)** — default. Use this when the app is configured for Meta Aggregated Event Measurement. This is the best default for most advertisers who want near real-time Meta reporting for iOS 14+ app campaigns.
- **Apple SKAdNetwork** — use this only when you intentionally want Apple SKAdNetwork attribution/reporting for the ad set.

ROAS.to sets the ad set's attribution to match your choice — Meta AEM or Apple SKAdNetwork. It's the same selector you'd set by hand in Meta Ads Manager under the ad set's **Attribution** section.

**Tracking and attribution differences from web campaigns**
App Promotion campaigns do not behave like web campaigns:
- The ad click goes directly to the app store.
- Meta ignores normal creative tracking links for app ads.
- ROAS.to does not stamp `sub1/sub2/sub3` tracking parameters onto app ad URLs.
- Clicks do not pass through your ROAS.to tracking worker.
- Reporting comes from Meta's app campaign/ad set/ad insights and the app attribution method you selected.

Because there is no ROAS.to click redirect for app ads, app campaign reporting depends on Meta, your app install tracking setup, and any MMP/SDK events connected to Meta.

**Value per install and activation**
The App Promotion form lets you set optional values for:
- Value per install
- Value per activation

Use these when you want ROAS.to to estimate revenue, ROAS, and profit for app campaigns. You can save the values as defaults for that app so future campaigns pre-fill them.

**Budgeting and bid strategy**
ROAS.to forces app campaigns to optimize for **App Installs**. If a duplicated campaign carried an incompatible web setting, ROAS.to adjusts it before sending to Meta.

Important limits:
- App Promotion is not compatible with boost-post mode.
- ROAS floor / minimum ROAS bidding is not used for install campaigns unless the app has the needed value-event setup.
- If a copied campaign had a minimum-ROAS strategy, ROAS.to changes it to lowest cost for App Promotion.

**Duplicating and cloning app campaigns**
When you duplicate, clone, auto-scale, or use automation on an app campaign, ROAS.to preserves:
- Facebook App ID
- App store URL
- Platform
- iOS attribution choice (AEM or SKAdNetwork)

This prevents clones from silently changing an Apple SKAdNetwork campaign back to AEM or an AEM campaign back to SKAdNetwork.

**Post-launch verification**
After creating a test campaign, check the ad set in Meta Ads Manager:
- Objective should be App Promotion.
- Optimization should be App Installs.
- The app should match the intended Facebook App ID and store listing.
- For iOS, the ad set Attribution selector should match your ROAS.to choice.
- For AEM, it should show Meta attribution for iOS 14+ / Aggregated Event Measurement.
- For Apple, it should show Apple's SKAdNetwork.

If the campaign creates but shows the wrong attribution method, create a paused test campaign from ROAS.to and compare the ad set's Attribution selector in Meta before spending.

---

### Pages and Pixels

_How Facebook Pages and Pixels are synced and used._

ROAS.to syncs your Facebook Pages and Pixels during onboarding and keeps them updated.

**Facebook Pages:**
Your pages are used when creating ads (each ad must be associated with a page). Go to any ad creation flow to select which page to use.

To re-sync pages: Go to Settings > Accounts and trigger a sync, or they'll update automatically.

**Facebook Pixels:**
Pixels are used for conversion tracking and optimization. ROAS.to syncs your pixel list so you can select which pixel to use for tracking in your campaigns.

To re-sync pixels: Same as pages — go to Settings > Accounts or wait for the automatic sync.

**Instagram accounts:**
If you assigned Instagram accounts to your system user, they'll be synced too. This lets you run ads on Instagram placements.

---

### How data syncing works

_Understanding the automatic sync schedule and how to trigger manual syncs._

ROAS.to runs a background sync service that keeps your Facebook data fresh.

**Sync schedule:**
- **Every minute** — campaigns, ad sets, ads, today's performance metrics, and automation rule execution. How often each account is actually refreshed scales with its spend: top spenders refresh every minute, lower-spend accounts every 5–15 minutes, and accounts with no recent spend are checked less often to save on rate limits.
- **Before 6 AM ET** — yesterday's data re-synced every 15 minutes while metrics settle
- **After 6 AM ET** — yesterday's data re-synced hourly
- **Finalization** — once yesterday's spend stabilizes across consecutive unchanged checks, the data is marked final
- **On demand** — click **Refresh** on the Campaigns or Insights page. It shows the latest synced data instantly and queues a fresh pull from Facebook in the background

**What gets synced:**
- Campaign/ad set/ad status and configuration
- Spend, impressions, clicks, CTR, CPC, CPM
- Conversions, revenue, ROAS
- Creative assets and images
- Pages, pixels, and Instagram accounts

**Sync status indicator:**
The Campaigns page header shows when the data in view was last updated, plus the refresh cadence for the accounts you're looking at:
- **"Spend data syncs every minute"** — actively spending accounts (Meta's own reporting can still lag a few minutes)
- **"about every 5 minutes" / "about every 15 minutes"** — lower-spend accounts
- **"This account isn't actively spending"** — dormant accounts; spend data may be hours old until spend resumes

**Historical sync:**
During onboarding, you chose how much historical data to sync. You can request additional historical data from Settings > Accounts.

---

### Advantage+ Creative features (the 40+ AI toggles)

_The 40+ Meta AI creative enhancement toggles — what each one does, which ones to enable, and which ones can wreck your ad._

Advantage+ Creative is Meta's bucket of AI toggles that auto-modify your creative at delivery time — generating image variants, animating statics, translating copy, adding music, re-cropping for placements, and more. Some are quiet wins. Others rewrite your ad in ways your brand voice doesn't approve of.

ROAS.to gives you per-toggle control instead of Meta's all-or-nothing "Standard Enhancements" switch.

**The form structure**

In **Ads Manager > Create Ads**, the Creative & Text section has one master checkbox:

> **"Enable AI-powered creative enhancements"**

When OFF, ROAS.to tells Meta to apply no enhancements, and your creative is delivered untouched.

When ON, two groups of per-feature toggles appear underneath:

**1. Named toggles** — the main grid

Each is an individual checkbox, defaulting to ON when the master is enabled:

- Text Optimizations
- Image Touch-ups
- Image Templates
- Inline Comments
- Video Auto-Crop
- Translate Text
- Add Animation
- Product Extensions
- Product Tags
- Business AI
- Enhance Media Text
- Show Summaries
- Reveal Details Over Time
- Show Spotlights
- Enhance CTA
- Brightness & Contrast
- Music Generation

**2. Additional enhancements**

Below the named grid, an "Additional enhancements" section lists every other toggle Meta currently offers that isn't already covered above — things like image uncrop, video uncrop, AI background generation, AI music alternatives, voiceover translation, profile cards, local store extension, and more. Each is a checkbox; "All on" and "Reset" quick-action links sit at the top of the grid.

Whatever you toggle is saved with the ad and travels with clones and duplicates.

**Which ones we recommend turning ON**

Safe additive (almost always wins):
- Image Touch-ups, Brightness & Contrast, Video Auto-Crop

Conditional (depends on your account):
- **Translate Text** — turn ON for multi-country campaigns
- **Music Generation** — turn ON for video ads when you don't have your own audio track
- **Add Animation** — turn ON if your creative is mostly statics and you want motion in video placements
- **Image Templates** — turn ON for catalog/DPA campaigns

**Which ones we recommend keeping OFF**

- **Enhance Media Text** — Meta can rewrite text overlaid on your creative. If your brand is precise about claims, this can swap them for less-compliant variants.
- **Text Optimizations** — Meta rewrites your primary text on the fly. Often fine. Sometimes catastrophic for tight-DR copy with specific hooks.
- **Enhance CTA** — overrides your chosen CTA button text. Test before trusting.
- **Business AI** — embeds a chatbot in your ad. Only enable if you've actually configured the agent's responses; otherwise Meta will improvise and the improv may not match your brand.

**The catalog-gated extras**
Several entries in the "Additional enhancements" grid (product-tag overlays, AI background generation, hide-price, customize-product-recommendation, media-type-automation, etc.) only function when the ad set is connected to a Meta product catalog. They appear in the form but are filtered out at send time when the campaign isn't catalog-capable.

**Keeping up with Meta**
Meta occasionally adds new toggles or renames existing ones. ROAS.to keeps its list in sync and flags anything new it doesn't recognize yet. If a toggle you expect is missing, let us know and we'll add it.

**Persistence**
Your toggles are saved with each ad batch. When you clone or duplicate a campaign, the toggles travel with it. Edit them on the batch before cloning if you want different behavior on the clones.

---

### Boost Post mode: promoting organic posts

_How to convert an organic Facebook or Instagram post into a paid campaign — what is different from a normal ad, when to use it._

Boost Post mode promotes an existing organic post as a paid ad instead of creating a brand-new creative. You keep all the organic likes/comments/shares the post already accumulated (the social proof rides along) and Meta delivers it to a paid audience.

**When to use Boost Post mode**

- Your organic post is taking off (engagement spiking) and you want to throw paid behind the momentum
- You want the social proof from organic engagement (1,200 likes, 200 comments) to render on the paid ad
- You're testing a content piece (article, video, reel) before committing to a polished ad version
- You want to drive engagement / awareness rather than direct conversions

**How it's different from a normal ad**

| | Normal ad | Boost Post |
|---|---|---|
| Creative | You upload an image/video + write copy | Promotes an existing post — copy is locked |
| Sub-ID stamping | sub1/sub2/sub3 stamped on outbound URL | Same — works on link posts |
| Objective | Sales / Leads / Traffic / etc. | Engagement (most common); Sales possible |
| Edits after launch | Headline + body editable | Locked — you can't edit the post copy from inside the ad |

**Launching a Boost Post**

You launch boosts from the Posts page:

1. Go to **Ads > Creatives > Posts**.
2. Filter by source (Facebook or Instagram), sort, and find the post you want to boost.
3. Click the Boost action on the tile.
4. The Create Ads form opens with the post bound — the creative-upload section is replaced by a preview card of the original post, and the form runs in boost mode for the rest of the flow.

**Settings that DO carry over**

- Targeting (geo, age, gender, interests, custom audiences, lookalikes — same as any other ad)
- Budget + schedule + bid strategy
- Placements (Advantage+ or manual)
- CAPI / pixel selection
- Tracking domain + sub-ID stamping (for posts with outbound URLs)

**Settings that DON'T apply to boost mode**

- App Promotion is incompatible with boost mode
- Most Advantage+ creative toggles are no-ops (the creative is fixed)
- Some objectives lock to Engagement when boosting (Sales requires the original post have a tracked URL)

**Auto-boost: doing this automatically**

If you want ROAS.to to boost organic posts FOR you when they cross an engagement threshold, see the **Auto-Boost organic posts** article. Set a rule once ("any post crossing 100 likes in 24h, boost at $20/day with these targeting settings") and walk away.

---

### Posts page and finding your boosts

_Browse your synced organic Facebook and Instagram posts, see engagement metrics, and launch boost campaigns from the post directly._

Go to **Ads > Creatives > Posts** to see every organic post synced from your connected Facebook pages and Instagram accounts. Use it to find boost candidates and launch boosts in one click.

**What gets synced**
- Posts from your connected Facebook pages
- Posts from connected Instagram business accounts
- Engagement metrics (likes, comments, shares, reactions)
- Post text, media type, published timestamp

**Filtering**
Three tabs at the top — **All**, **Facebook (N)**, **Instagram (N)** — with live counts of each source. Click to scope the grid.

A search input filters by post message text.

**Sorting**
Two modes:
- **Most recent** (default)
- **Most engagement** (sums likes + comments + shares)

**Sync Posts button**
Top-right of the page. Triggers an immediate sync from Meta — toast shows the count synced.

**Per-post actions**
Each post tile has a **Boost** action. Clicking it opens **Create Ads** with the post bound — the creative-upload section is replaced by a preview card, and the form runs in boost mode. See **Boost Post mode: promoting organic posts**.

**Finding your boosts**
Boost campaigns live on the **Campaigns** page — pick **Boosts** in the Type filter (or scan for the ⚡Boost tag on a row). You'll see every boost you've launched — both manual boosts and auto-boosts — each with Pause / Activate and Delete controls. The Type filter only appears once you have boosts. Boost spend is reported via Facebook attribution and is rolled into your headline spend totals, since boosted posts can't carry our tracking parameters.

**Workflow patterns**
- **Daily review** — sort Posts by "Most engagement," boost any post that's clearly outperforming
- **Auto-boost rules** — if you do the daily review every day, automate it via **Automation > Auto-Boost** (see the Auto-Boost article)
- **Performance audit** — filter Campaigns to Boosts to compare which boosted posts actually paid off

---

### Media Library

_Centralized media library with tagging, AI refinement, crop tool, and performance badges. Every image and video used in your ads, in one place._

Go to **Ads > Creatives > Media Library** (`/media`) to manage every image and video in your workspace. Each asset carries its own performance history derived from the ads using it.

**Library view**

Virtualized grid with infinite scroll. Each tile shows:
- Thumbnail
- Filename
- Type badge (Ad Creative, Ad Video, Video Thumbnail, Product, Header, Advertorial, Icon, Background)
- File size
- Tag badges
- Performance badge (spend + ROAS over the selected window) when the asset has actually spent money

**Library / Trash toggle**
Top of the page. Library shows your live assets; Trash shows deleted assets still in their 30-day recovery window, with per-tile and bulk Restore actions. After 30 days the asset is permanently removed and can't be recovered.

**Filters**
- Search by filename, tag, or hash
- Type filter (All Types, Ad Creatives, Ad Videos, Video Thumbnails, Product Media, Header Media, Advertorial Media, Icons, Backgrounds)
- Active tag chips with AND semantics (asset must carry every active tag) — click any tag badge on a tile to add it as a filter
- Performance window: All time / 7d / 14d / 30d
- Sort: Most recent / Highest spend / Highest ROAS
- Min ROAS threshold

When you switch to a non-recent sort or set a Min ROAS, pagination is suspended (ranking is limited to the loaded set, capped at 200 for usage data). The toolbar shows "X of Y shown" so you know.

**Selection + bulk actions**
- Click a tile's checkbox (or any tile when something is already selected) to select
- Shift-click for inclusive range selection in current sort order
- "Select all visible" picks up the whole filtered set
- Bulk Rename / Tag / Untag / Delete in Library mode; bulk Restore in Trash mode
- Selection clears automatically whenever you change filter, sort, or view (prevents accidentally nuking off-screen rows)

**AI Refine modal**
Click the wand icon on any image tile. Opens the refinement panel for prompt-driven edits. Variants save back to the library tagged `ai-refined`. Uses AI credits (see **AI credits and usage**). Not available on video tiles — the wand icon is hidden there.

**Crop modal**
Pure client-side cropper. Saves cropped output back to the library with the `cropped` tag.

**Lightbox**
Click any tile (when nothing is selected) to open the lightbox. Inline-edit filename and tags, navigate with ←/→, close with Esc. Refine and Crop buttons delegate to the modals above.

**Upload**
Click Upload (top-right). Drag-and-drop multiple files into the modal, or use the file picker. Uploads go straight to your ROAS.to library; the asset is sent to Facebook automatically the first time you use it in an ad.

**Delete + Undo**
Single-tile and bulk delete are reversible — the toast includes an Undo action that restores the same set. Deleted assets stay in Trash for 30 days, then are permanently removed.

**Performance badge details**
The bottom-right corner of each tile shows the asset's spend and ROAS over the selected performance window. ROAS is colored green when ≥1x, warning otherwise. Hover the badge for ad count + exact spend.


## On-Page A/B Tests

A/B test your landing pages automatically

### What are On-Page A/B Tests?

_Understanding the on-page A/B testing system and how it works._

On-Page A/B Tests let you A/B test changes on your landing pages without modifying the page itself.

**How it works:**
1. You add a small piece of install code to your page (one line of JavaScript)
2. ROAS.to intercepts page loads and injects your changes before the visitor sees the page
3. Visitors are randomly assigned to see the original (baseline) or a variant
4. ROAS.to tracks which version converts better based on real revenue data

**What you can test:**
- Headlines and subheadlines
- Call-to-action buttons (text, color, size)
- Images and hero sections
- Page layout and section order
- Body copy and descriptions
- Any DOM element on your page

**Statistical approach:**
ROAS.to uses Thompson Sampling — a proven statistical method that automatically shifts traffic toward winning variants while still exploring. This means you get results faster than traditional 50/50 splits.

**Key metric: EPV (Earnings Per Visitor)**
This is the primary metric for page tests. It measures how much revenue each visitor generates on average, accounting for both conversion rate and payout amount.

---

### Creating a Page Test

_Step-by-step guide to setting up your first A/B test._

Go to **Optimization > On-Page A/B Tests** and click "Create Test."

**The wizard walks you through 3 steps:**

**Step 1: URL & Preview**
Paste your landing page URL. ROAS.to fetches the page and uses AI to detect high-value testable elements — headlines, CTAs, images, sections, etc. Each element is tagged with an importance level (high/medium/low). You can preview the page and see what was detected.

**Step 2: AI Variants**
Select which detected elements you want to test. For each selected element, ROAS.to generates AI-powered variant suggestions with strategy labels. You can also write your own variations manually. Review the suggestions and pick the ones you want to include.

**Step 3: Install & Launch**
ROAS.to provides an install code to add to your page. Copy and install it, then deploy the test. Variants start serving immediately.

**Important:** Make sure the ROAS.to install code is on your page. The wizard includes verification to confirm it's working.

---

### Managing variants

_How to add, pause, resume, and promote test variants._

Each page test has a baseline (your original page) and one or more variants.

**Adding variants:**
From the test detail page, click "Add Variant" to create a new variation. You can define changes to any DOM element using CSS selectors.

**Variant actions:**
- **Pause** — stop showing a variant to new visitors (existing sessions keep their assignment)
- **Resume** — re-enable a paused variant
- **Promote** — make the variant the new baseline (the winning change becomes the default)
- **Promote & Pause Baseline** — promote the variant AND pause the old baseline in one step

**Variant metrics:**
For each variant, you can see:
- Views — how many visitors saw this variant
- Clicks — product/CTA clicks
- Conversions — completed conversions
- Revenue — total revenue generated
- EPV — earnings per visitor
- CTR — click-through rate
- CVR — conversion rate
- Confidence — statistical confidence that this variant's **conversion rate** beats the baseline's (Thompson-sampled beta posterior on conversions/views)
- Note: auto-promotion requires BOTH high confidence AND a positive EPV lift — a variant that lifts AOV but not conversion rate keeps running until its CVR posterior crosses the threshold
- Lift — percentage improvement over baseline

**AI variant generation:**
Click the AI button to generate new variants automatically. The AI analyzes your page and creates variations based on proven optimization strategies.

---

### Page test settings

_Configuring confidence thresholds, baseline split, and auto-promotion._

Each test has configurable settings that control how it runs.

**Confidence threshold:**
The minimum statistical confidence (conversion-rate posterior) required before a variant can be promoted. The default depends on your site's traffic volume — higher-traffic sites use a 90% threshold, while lower-traffic sites default to 95% for more reliable results. Promotion also requires EPV to be above baseline — so a variant needs to win on both conversion rate AND revenue-per-visitor before the engine promotes it. You can override this per test or globally in Settings > Automation.

**Baseline split:**
The percentage of traffic that goes to the baseline. Default is 60%. Thompson Sampling adjusts variant traffic automatically, but the baseline always gets at least this percentage.

**Auto-promotion:**
When enabled, ROAS.to automatically promotes variants that reach the confidence threshold. This is checked hourly.

**Auto-generation:**
When enabled, AI will automatically generate new variant ideas and add them to the test. Useful for continuous optimization.

**Holdout group:**
An optional control group that always sees the baseline, separate from the test. Used for measuring the true cumulative impact of all your optimizations.

**Test priorities:**
ROAS.to suggests which elements to test next based on historical win rates and estimated impact.

---

### Multivariate testing (MVT)

_How to test multiple elements simultaneously and analyze interaction effects._

Multivariate testing lets you test changes to multiple elements at the same time and understand how they interact.

**Creating an MVT:**
From a test detail page, click "Create MVT." You'll define:
- **Factors** — the elements you're testing (e.g., headline, CTA button, hero image)
- **Levels** — the variations for each factor (e.g., 3 headlines × 2 CTAs = 6 combinations)
- **CSS selectors** — how to target each element on the page

**How it works:**
ROAS.to creates all possible combinations of your factor levels and distributes traffic across them. The MVT analysis then determines:
- **Main effects** — which factor level is the best overall (e.g., headline B wins regardless of CTA)
- **Interaction effects** — which combinations work best together (e.g., headline B + CTA 1 is the winning combo)
- **Best combination** — the overall winner

**MVT analysis page:**
Shows effect sizes, statistical significance, and data quality assessment. Look for the "Best Combination" callout to see the winning combination.

**Tip:** Keep your factor count low (2-3 factors) to avoid needing too much traffic. With 3 factors × 3 levels each, you'd have 27 combinations — each needing sufficient traffic for statistical significance.

---

### Deploying and managing live tests

_How deployment works, flushing data, and archiving tests._

**Deploying a test:**
After creating your test and variants, click "Deploy" to push your test live. Deployment is near-instant — variants start serving within seconds.

**Re-deploying:**
Any time you change variants or settings, you need to re-deploy for changes to take effect. The "Deploy" button will appear when there are pending changes.

**Resetting the evaluation window:**
If you need to restart the comparison clock (e.g., after a significant page change or once a campaign goes live), click "Reset Window." All tracking data is kept — nothing is deleted. Bot traffic is automatically excluded from every count, so there's nothing to clear; only the test's start time is reset so the A/B comparison runs from a clean baseline.

**Starting evaluation:**
After deploying, click "Start Evaluation" to begin collecting performance data. This resets the evaluation period so you get clean metrics.

**Archiving tests:**
When a test is complete, archive it from the test page. Archived tests stop serving variants (all traffic goes to baseline) and move to the archived section. You can unarchive later if needed.

**Test history:**
Go to **Optimization > History** to see a timeline of all past promotions — which variants won and when they were promoted.

---

### Mapping Facebook Ads to tests

_How to link your Facebook ads to page test variants for attribution._

ROAS.to can map your Facebook ads to specific page test variants, giving you complete attribution from ad click to landing page variant to conversion.

**Auto-detection:**
When your ad's destination URL matches a page test's page URL, ROAS.to can automatically detect the mapping.

**Manual mapping:**
From the Ads Manager, click the mapping icon on any ad to manually link it to a specific test and variant.

**What mapping enables:**
- See which ad + variant combinations perform best
- Attribute Facebook spend to specific landing page variants
- Calculate true ROAS including landing page optimization lift
- The funnel view shows the complete journey: ad impression → click → variant → conversion

**Best practice:**
Use the same URL in your Facebook ads that your page tests run on. ROAS.to handles variant assignment automatically, so all traffic to that URL enters the test.

---

### Troubleshooting: Page test not working

_What to check when your A/B test variants aren't showing._

If your page test variants aren't showing to visitors:

**1. Check the install code is on your page**
Make sure the ROAS.to install code is in your page's <head>. The test creation wizard includes a verification step — use it to confirm.

**2. Check the test is deployed**
After creating variants, you must click "Deploy" to push your test live. Look for the deploy button — if it's visible, there are pending changes that haven't been deployed yet.

**3. Check the test is active**
Make sure the test status is "Active" (not paused or archived). Check each variant's status too — paused variants won't be shown.

**4. Check your browser**
- Clear your cookies (variant assignments are persisted in cookies)
- Try an incognito window to see a fresh assignment
- Check the browser console for any JavaScript errors

**5. Safari users**
Safari has strict cookie policies for third-party scripts. ROAS.to uses a fallback mechanism (IP + User-Agent hashing) for Safari, but it may behave differently than Chrome/Firefox.

**6. Check the evaluation status**
Make sure you've clicked "Start Evaluation" after deploying. Without starting evaluation, data collection doesn't begin.

**7. DNS/CDN issues**
Verify the host your test script loads from resolves correctly from your test device — that's `opt.roas.to`, or your own custom tracking domain if you've set one up. Very rarely, DNS propagation delays can make it briefly unreachable.


## Multi-Page Rotation

Track links, split test URLs, and attribute conversions

### What is Multi-Page Rotation?

_Understanding link groups, URL split testing, and conversion attribution._

Multi-Page Rotation (Optimization > Multi-Page Rotation) lets you split-test different destination URLs at the link level.

**How it's different from On-Page A/B Tests:**
- **On-Page A/B Tests** modifies elements on a single page (same URL, different content)
- **Multi-Page Rotation** rotates between entirely different URLs (different pages altogether)

**Use cases:**
- Test different landing pages against each other
- Test different offers or funnels
- Split traffic between pre-sell pages and direct-to-offer pages

**How it works:**
1. Create a "link group" — this generates a tracking URL (via your custom tracking domain, or `track.roas.to` if you haven't set one up yet)
2. Add variants — each variant points to a different destination URL
3. Use the tracking URL in your Facebook ads
4. Visitors are randomly assigned to a variant and redirected
5. ROAS.to tracks clicks, conversions, and revenue per variant

**Key metrics:**
- Clicks per variant
- Conversions and revenue
- Conversion rate
- EPV (earnings per visitor)
- Facebook ad spend (when mapped to campaigns)

---

### Creating a link group

_How to set up a new URL split test with multiple destination variants._

Go to **Optimization > Multi-Page Rotation** and click "Create Link Group."

**Steps:**
1. **Name your link group** — give it a descriptive name (e.g., "Offer A vs Offer B")
2. **Add your baseline URL** — this is the default destination
3. **Add variant URLs** — each variant is a different destination page
4. **Set traffic weights** — how much traffic each variant receives (defaults to equal split)
5. **Deploy** — generates your tracking URL

**Using your tracking URL:**
Your link group gets a URL like: `https://go.yourdomain.com/link/{linkGroupId}` (custom domain) or `https://track.roas.to/link/{linkGroupId}` (default).

Use this URL as your Facebook ad destination. When someone clicks, ROAS.to:
1. Assigns them to a variant (persisted via cookie)
2. Records the click with a unique click ID
3. Redirects them to the variant's destination URL

**Variant management:**
- **Pause** a variant to stop sending it traffic
- **Resume** to re-enable
- **Promote** to make a variant the new baseline
- **Flush** to clear all tracking data and start fresh

**Conversions:**
Conversions are attributed via the postback URL or your integration (Everflow/Shopify). The click ID connects the conversion back to the variant.

---

### External Page Click Tracker

_Track on-page clicks on external landing pages to get real CTR, EPC, and CVR._

When your Multi-Page Rotation sends traffic to an external page (not a ROAS.to On-Page A/B test), clicks on that page aren't tracked by default — because there's no ROAS.to script installed. This means CTR, EPC, and CVR stay at zero.

The **External Page Click Tracker** is a lightweight script you add to the destination page. It tracks outbound link clicks and reports them back to ROAS.to.

**How to install:**
1. Go to the campaign detail page or **Settings > Integrations > Tracking**
2. Copy the "External Page Click Tracker" code
3. Paste it before `</body>` on the destination page

**How it works:**
- When a user arrives via your Multi-Page Rotation link, the URL contains a `sub4` parameter with campaign attribution data
- The script reads this parameter automatically
- When the user clicks any outbound link on the page, a click event fires to ROAS.to
- The click is attributed to the correct campaign and variant

**What metrics it enables:**
- **CTR** (Click-Through Rate) — clicks / views
- **EPC** (Earnings Per Click) — revenue / clicks
- **CVR** (Conversion Rate) — conversions / views

**Requirements:**
- The destination page must be accessed via a Multi-Page Rotation URL (so the sub4 parameter is present)
- You need access to add a script tag to the page (WordPress, Shopify, static HTML — any site works)

**Custom selector:**
By default, all outbound `<a>` link clicks are tracked. Internal links (same hostname) are ignored. To track only specific links, add a `data-roas-track` attribute to those links and update the selector in the script.

**Where to find it:**
- Each campaign's detail page has a "Track clicks on external pages" link
- Settings > Integrations > Tracking has the generic code


## Automation

Rules, auto-scaling, and Bulk Ad Creation

### Creating automation rules

_How to set up rules that automatically pause, activate, or adjust your campaigns._

Go to **Automation > Rules** to create and manage your automation rules.

**What rules can do:**
- Pause campaigns / ad sets / ads when performance drops below thresholds
- Activate paused items when metrics improve
- Adjust budgets up or down based on ROAS
- Adjust or set ad set bid caps (Bid Cap / Cost Cap strategies) — by percentage or to an exact amount, triggered by metrics or once per day at a set time. There's no automatic revert: for a daily up/down cycle, create two rules (e.g. 6am → set $5.00, 10pm → set $3.50)
- Set Meta budget schedules (peak-hour spend boosts)
- Duplicate winning campaigns
- Send alerts when conditions are met

**Creating a rule:**
1. Click "Create Rule" — pick a template to start from, or build from scratch
2. **Name** your rule (e.g., "Pause low ROAS campaigns")
3. **Set conditions** (Section 2) — choose metrics, operators, and thresholds:
   - Metrics: ROAS (Facebook), Tracker ROI, Amount Spent, Conversions (Facebook), Conversions (Tracker), CTR, CPC, CPA
   - Operators: greater than, less than, equal to, greater/less than or equal
   - Time windows: today, yesterday, last 3 / 7 / 14 / 30 / 60 / 90 days
4. **Apply to campaigns** (Section 3) — select specific campaigns or apply to all
5. **Set schedule & execution** (Section 4) — four knobs control timing (see below)
6. **Pick the action** (Section 5) — what happens when conditions match

**The four timing knobs (Section 4):**

These work together to give you fine control without spamming Facebook.

- **Check every** — how often we look at your campaigns against this rule's conditions. Default: every 15 minutes. Pick faster for catching blowups quickly, slower for steady-state rules.

- **Then wait** — after this rule acts on a campaign, how long before it can act on that same campaign again. Default depends on the action:
  - Pause / Activate / Alert: **1 hour**
  - Change Budget: **4 hours** (give Meta time to redistribute spend)
  - Adjust / Set Bid Cap: **4 hours** (same compounding physics as budget changes)
  - Budget Schedule (HDP): **24 hours**
  - Duplicate Campaign: **24 hours**

  Set "Don't wait" if you want the rule to act every cycle conditions match. The cooldown is per-campaign — two different rules can act on the same campaign within their own windows.

- **Max actions per day (per campaign)** — safety ceiling. Leave blank for no limit. Default 3/day for clone rules. Counts only successful actions per campaign per day in your timezone.

- **If last attempt failed, wait longer** — backs off after a Facebook error. Default "Same as normal cooldown" (no extra wait). Useful for flaky integrations — set 24h here if you want a failed clone or scale attempt to wait longer before retrying than a normal successful one would.

**Assigning rules:**
- Manually assign to specific campaigns
- Or use "Assign All Active" to apply to every active campaign

**Rule execution and the Blocked badge:**
Rules run on the schedule you set. Each execution writes to the rule's history. **If your rule isn't firing**, look for a "Blocked Nx today" badge on the rule card — it tells you exactly why the rule was throttled (cooldown, daily cap, HDP guard, etc.). See the **"Why isn't my rule firing?"** article for the full troubleshooting flow.

**Safety features:**
- **Quiet hours** (Settings > Automation) — rules don't fire during these hours (default: midnight to 6 AM)
- **Weekend guard** — optionally skip rule execution on weekends
- **Kill switch** — disable all automations instantly from Settings > Automation
- **Post-failure cooldown** — see the four-knobs section above
- **Adset precision** — when a rule fires on an ad set, the cooldown is per-adset (not per-parent-campaign), so a "pause unprofitable ad sets" rule on a campaign with 5 ad sets correctly treats each ad set independently

---

### Why isn't my rule firing?

_How to diagnose a rule that looks correct but isn't taking action._

If you set up a rule, conditions look like they're matching, but you're not seeing actions — work through this checklist.

**1. Check the "Blocked Nx" badge on the rule card.**
The card lists every reason the rule was held back in the last 24 hours, with the most recent reason shown on hover. Common reasons:

- **cooldown** — the rule already acted on this campaign within the "Then wait" window. Wait it out, or shorten the window in Section 4.
- **Facebook rate limit — retried automatically** — Facebook's API budget for the ad account was running hot, so we deferred the action rather than risk Meta blocking the account. Nothing is wrong with your rule; it retries automatically on the next cycle (about a minute later) once the budget recovers.
- **post-failure cooldown** — the rule's last attempt on this campaign failed at Facebook. The next attempt waits the extended window you configured under "If last attempt failed, wait longer".
- **daily cap** — the rule hit its "Max actions per day per campaign" limit. It resets at midnight in your timezone.
- **HDP active** — a Budget Schedule (HDP) rule recently fired on this campaign, and you're trying to scale budget. We block scale + HDP from compounding on the same campaign in the same window.
- **already cloned** — for duplicate-campaign rules: this rule has already cloned this parent campaign at least once. Each parent can only be cloned once per rule.
- **same target acted this cycle** — defensive: a sibling entity under the same target already had this rule act on it earlier in this 1-minute cycle.

**2. No badge at all? Conditions probably aren't matching.**
Open the rule and check:
- **Default Data Interval** — is the lookback period correct? "Today" means today's data only.
- **Conditions** — every condition must be true (AND logic). One mis-set threshold and nothing fires.
- **Minimum Delivery** — rules require enough Facebook spend + impressions before firing, to avoid acting on statistical noise. If a campaign just launched and has barely spent, the rule waits.

**3. Day-parting or quiet hours blocking?**
- Section 4 has a **Skip Days** picker — if today is checked, the rule won't fire today
- Section 4.5 **Day Parting** restricts the rule to specific hours / days of the week
- Settings > Automation > **Quiet Hours** is a global gate (default: midnight to 6 AM)
- Settings > Automation > **Weekend Guard** (if enabled) skips Saturday and Sunday

**4. Rule is paused or not active.**
The rule card has an active/paused toggle. Make sure the rule itself is running.

**5. Account or plan issues.**
- Rules keep running through the 120-hour payment grace window after a failed charge, then stop until payment is fixed
- Rules don't fire for ad accounts that have been deactivated (e.g., token expired)
- Check **Account > Health** for token / permission issues

**6. Still stuck?**
Each rule has an execution history on its detail page. The history shows every cycle the rule was evaluated — success, skip, or error — with the exact reason. That's the ground truth.

---

### Auto-Scaling (campaign cloning)

_How to automatically clone winning campaigns with optional AI variations._

Go to **Automation > Auto-Scaling** to set up automatic campaign cloning.

**What it does:**
Auto-Scaling monitors your campaigns and clones the top performers based on rules you define. Optionally, clones can include AI-generated variations of headlines and ad copy.

**The wizard walks you through:**
1. **Basics** — name, description, data lookback period
2. **Scheduling** — trigger-based (fires when conditions match) or scheduled (fires on a cron-style cadence)
3. **Conditions** — when should cloning happen?
   - ROAS threshold (e.g., clone campaigns with ROAS > 3.0)
   - Conversion volume (e.g., at least 10 conversions today)
   - Spend level (e.g., spent at least $100)
4. **Clone Mode** — pick how clones are produced:
   - **Simple** — exact copy with the same creative
   - **AI Headlines** — same creative, AI-generated headline variations
   - **AI Scripts** — same creative, AI-generated body copy variations
   - **AI Full** — AI-generated headlines + body + optional image variations
5. **AI Settings** (only shown for AI modes) — persona, tone, prompt version, variation count
6. **Safety Limits** — three knobs control pacing:
   - **Then wait (hours)** — after a clone, how long before this rule can clone the same parent campaign again. Default 24h.
   - **Max per day per campaign** — safety ceiling. Default 3 clones / day / parent.
   - **If last clone failed, wait longer** — extended backoff after a failed Facebook clone attempt. Leave blank for "no extra wait" (use the normal cooldown). Useful if you've had transient Facebook errors on clones — set 48h here to prevent tight retry loops on a flaky integration.
7. **Campaigns** — which campaigns the rule monitors
8. **Review** — confirm and create

**Clone tracking:**
The Auto-Scaling page shows:
- Active clone rules and their status
- "Blocked Nx today" badge if the rule was throttled by cooldown / daily limit / already-cloned safeguards
- Clone history — which campaigns were cloned, when, and performance comparison
- Parent vs. clone performance (so you can see if clones outperform originals)

**Safeguards always on:**
- Each parent campaign can only be cloned **once per rule** (prevents duplicates)
- Failed clone attempts count toward the daily limit (we don't know if Facebook actually created the campaign, so we play it safe)
- A "phantom risk" filter excludes purely-local failures (bad config, no custom domain) from the daily count

ROAS.to checks your auto-scaling rules every 15 minutes and runs clones when conditions are met. See the **"Why isn't my rule firing?"** article if a rule looks correct but isn't producing clones.

---

### Bulk Ad Creation

_Bulk AI-powered ad generation to rapidly test creative variations._

Go to **Automation > Bulk Ad Creation** to generate and launch multiple ad variations at once using AI.

**What it does:**
Bulk Ad Creation creates multiple ad variations (different headlines, body copy, and optionally images) and launches them into your Facebook ad account — letting you test many angles quickly.

**Setting up a job:**
1. Select the Facebook ad account
2. Choose the page persona (which Facebook Page to post from)
3. Configure the AI generation settings:
   - Number of variations to create
   - Tone and angle instructions
   - Base copy to vary from
4. Set ad limits (how many ads to create)
5. Launch the job

**Scheduling:**
You can also schedule Bulk Ad Creation jobs to run periodically — e.g., generate 5 new ad variations every Monday morning.

**Monitoring:**
The Bulk Ad Creation dashboard shows:
- Active and completed jobs
- Job status (queued, running, completed, failed)
- Generated ads and their performance once live

**AI credit usage:**
Each AI generation uses credits from your monthly AI budget. Check Settings > AI to see your usage and budget.

---

### High-Demand Period (HDP) budget multipliers

_Use Meta budget schedules to multiply your spend during predictable peak windows — Black Friday, evening email blasts, weekly drops._

High-Demand Period (HDP) is Meta's native "budget schedule" feature: you set a multiplier (1x to 8x) and a time window, and Meta automatically scales the daily budget during that window without you touching it. ROAS.to lets you trigger HDPs as an automation rule action so you can run them on schedule or in response to performance signals.

**When to use HDP**

- **Predictable peak windows** — your email blast goes out at 8pm and your conversion rate doubles for 2 hours. Set a 2x HDP from 8-10pm daily.
- **Promo events** — Black Friday, Cyber Monday, weekly drops. Schedule a 3-5x multiplier across the event window.
- **Account-specific cycles** — your offer historically pays out heaviest from Friday-Sunday. Run a 2x weekend HDP.

**HDP vs scale-budget**

Both increase spend, but they're different tools:

| | HDP | Scale Budget |
|---|---|---|
| Mechanism | Meta-native budget multiplier | ROAS.to bumps the daily budget |
| Duration | Time-windowed (auto-rolls back) | Permanent until another rule changes it |
| Multiplier | 1x-8x for the window | Any % up to your max cap |
| Reverts on its own | Yes, at the window end | No — you'd need another rule to decrease |

**Action settings**

When you pick "Set Budget Schedule (HDP)" as a rule action:

- **Peak window length** — 3 to 24 hours
- **Budget multiplier** — 1x to 8x
- **Optional day-2 escalation** — bump the multiplier further on day 2 of an active HDP. Defaults to **2x** when escalation is enabled.
- **Optional day-3 escalation** — same for day 3. Defaults to **2.5x** when escalation is enabled.
- **Auto-delete on degradation** — if tracker ROAS drops below a floor you set during the HDP, ROAS.to deletes the schedule on Meta so you stop burning at the elevated multiplier

**Cooldown defaults**

HDP actions have a 24h cooldown by default — a campaign can only get a new HDP once per day. Daily caps and post-failure cooldowns work like every other rule action (see **Creating automation rules**).

**HDP guard**
If a rule recently fired an HDP on a campaign, a separate scale-budget rule on the same campaign is blocked for the same window (look for "HDP active" in the Blocked badge). We don't let scale + HDP compound — that's how runaway spend happens.

**Verifying it fired**

After the rule fires, open the campaign in Meta Ads Manager → Budget tab → you should see the active budget schedule with its multiplier and window. The schedule appears in your campaign's automation log too.

**Common questions**

- **Will Meta actually spend 8x?** Only if the auction has demand. HDP raises the ceiling; it doesn't force spend.
- **Can I run multiple HDPs?** Meta allows multiple non-overlapping schedules on the same campaign. ROAS.to enforces the 24h cooldown so you don't accidentally stack them.
- **What happens at the window end?** Meta reverts to the baseline daily budget. If your auto-delete-on-degradation triggered earlier, the schedule was already removed.

---

### Scheduled campaign clones (cron-style)

_Clone campaigns on a fixed cadence — daily / weekly / monthly / one-shot — instead of waiting for a performance trigger._

Scheduled clones run on a fixed time schedule instead of waiting for performance thresholds. Useful when your clone strategy is calendar-driven, not metric-driven.

**Trigger-based vs scheduled clones**

| | Trigger-based (Auto-Scaling) | Scheduled clones |
|---|---|---|
| Fires when | Performance conditions match (ROAS > X, spend > Y) | A specific datetime or recurring cadence |
| Use case | "Clone whatever is winning right now" | "Clone Campaign A every Monday 6am" |
| Where to set up | Automation > Auto-Scaling | Automation > Auto-Scaling (toggle Scheduled mode in step 2) |

**Two scheduling modes**

When you toggle scheduled mode on, you choose between:

- **One-time** — fires once at a specific date and time, then turns itself off.
- **Recurring** — fires on a repeating cadence. Pick one of three patterns:
  - **Daily** — fires at the same time every day
  - **Weekly** — fires on a specific day-of-week (Sun=0 through Sat=6)
  - **Monthly** — fires on a specific day of the month (1–31; if the month is shorter, fires on the last day)

All schedules respect your timezone — "every Monday 6am" means 6am in YOUR local time, not UTC.

**Optional conditions on scheduled clones**

You can still attach conditions to a scheduled clone — if conditions are present, the clone only fires when the schedule hits AND conditions match. Example: "Every Monday 6am, clone any campaign with ROAS > 2.5 and spend > $200 yesterday."

If you leave conditions empty, the schedule clones every matching campaign in your account at the cadence you set.

**Clone customization (same as trigger-based)**

- Clone mode: simple, AI headlines, AI scripts, AI full
- Budget override (in major units, capped at $100k)
- Name suffix with the `{date}` macro for uniqueness
- Optional page override
- Optional "start immediately" vs leave paused for review
- Copy parent's automation rules to the clone

**Safety limits**

- Per-rule daily cap (default 3 clones/day per parent campaign)
- Min hours between clones (default 24h)
- Post-failure cooldown (extended backoff after a failed Meta clone attempt)
- One-time rules auto-deactivate after their single execution
- Recurring rules advance to the next valid window after each firing

**Common patterns**

- **"Refresh my winners every Monday"** — weekly schedule, condition ROAS > 2.5 last 7 days, AI Headlines mode
- **"Black Friday warmup"** — one-time on Nov 25 09:00, clone every campaign in account X with 2x budget
- **"Daily new-angle test"** — daily at 8am, clone top spender, AI Full mode with custom persona

**Verifying schedule next-run**

The Auto-Scaling page shows each rule's next-run timestamp. If the timestamp looks wrong (e.g., a daily rule says "next run in 3 hours" but you expected tomorrow), check your timezone in Settings > General — the schedule is timezone-aware and a mismatched timezone is the usual culprit.

---

### Auto-Boost organic posts

_Set engagement thresholds and let ROAS.to automatically promote your viral organic posts the moment they hit._

Auto-Boost watches your organic Facebook and Instagram posts and converts them into paid boost campaigns the moment engagement crosses a threshold you define. Catches the viral moment instead of waking up the next morning to a flatlined curve.

**When to use it**

- You post a lot of organic content (multiple posts per page per day)
- You manually boost the winners and want to automate that
- You run a content team that posts faster than your media buyer can react

**Setting up a rule**

Go to **Automation > Auto-Boost** and click "Create Rule."

**Step 1 — Trigger conditions**

Pick which engagement metrics + thresholds trigger a boost:

- `likes_24h_delta` — like increase over the last 24 hours
- `comments_24h_delta` — comment increase
- `shares_24h_delta` — share increase
- `engagement_24h_delta` — sum of likes + comments + shares + reactions
- `engagement_72h_delta` — slower-moving signal over 3 days
- `total_engagement` — absolute total (no time delta)

Combine with operators (`>`, `>=`) and thresholds. Delta-based conditions need a baseline engagement history row, so brand-new posts are skipped until they accumulate some history.

**Step 2 — Target page or Instagram account**

Pick which page (or Instagram account) the rule monitors. One rule per page is typical, but you can run multiple rules per page with different thresholds + budgets.

**Step 3 — Template ad set (BYOA audience)**

Pick a template ad set in the same Facebook ad account. The auto-boost takes the template's targeting JSON and applies it to the new boost campaign — so the targeting you've already tested gets reused. No re-configuring per boost.

**Step 4 — Budget**

Set the daily budget for each boosted post. Boosts launch as their own campaigns (one campaign per boosted post) at this fixed daily budget.

**Step 5 — Safety limits**

- **Per-post cooldown (hours)** — same post can't be boosted twice within this window even if engagement keeps climbing
- **Daily cap per rule** — max boosts/day this rule will fire (so a content explosion doesn't blow your card)
- **Schedule** — same cadence as automation rules: every 5/15/30 min, hourly, etc. 15-30 min is the sweet spot.

**What gets created**

For each boost the rule fires:
- A new Meta campaign in boost mode (one campaign per post)
- A new ad set inheriting the template's targeting JSON
- A new ad pointing at the existing organic post (with sub-ID stamping on outbound URLs)
- An entry in your boost log with the trigger metric + value

**Stale-pending protection**

If something goes wrong mid-launch (Meta API hiccup, token expired), the pending boost sits for about two minutes, then is automatically marked failed. Your daily cap counts the failed attempt so you don't loop on a broken integration.

**Instagram requirements**

Boosting Instagram organic posts requires:
- The Instagram account is linked to your Facebook page
- The post is eligible for boosting in Meta's eyes (no music copyright issues, no policy flags)
- The connected Facebook ad account has access to the Instagram account

If the Instagram link breaks (commonly: page admin removes IG access), Auto-Boost auto-disables affected rules and notifies you. Re-link in Settings > Accounts and toggle the rule back on.

**Template ad set validation**

If you delete the template ad set in Meta, Auto-Boost auto-disables rules pointing at it. The rule card shows "template missing" — pick a new template and re-enable.


## AI Tools

Ad Copy Editor, Product Copy Generator, AI Consultant, and AI generation

### Ad Copy Editor

_How to use AI to refine and improve existing ad copy._

Go to **AI Studio > Ad Copy Editor** to refine your ad copy using AI.

**How it works:**
1. Paste your existing ad copy (headline, body text, or both)
2. Give instructions for how to change it (e.g., "make it more urgent," "add social proof," "shorten to 2 sentences")
3. Select your preferred AI model
4. Click generate — you'll get refined versions

**Use cases:**
- Freshen up stale ad copy
- Create angle variations from a proven ad
- Adapt copy for different audiences
- Test different emotional hooks (urgency, curiosity, fear, excitement)

**Tips:**
- Be specific in your instructions — "add a time-limited offer" works better than "make it better"
- Generate multiple variations and A/B test them
- Use the Bulk Ad Creation to launch tweaked variations at scale

---

### Product Copy Generator

_Generate product descriptions and ad copy from scratch with AI._

Go to **AI Studio > Product Copy Generator** to generate ad copy from scratch.

**How it works:**
1. Describe your product, offer, or service
2. Select your preferred AI model
3. Choose the type of copy (headline, description, ad body, CTA)
4. Generate — you'll get multiple options

**What it can generate:**
- Facebook ad headlines
- Ad body copy
- Product descriptions
- Call-to-action text
- Pre-sell page copy

**Prompt templates:**
Save your best prompts as templates for reuse. Go to the templates section to manage your saved prompts.

**AI credits:**
Each generation uses credits. Monitor your usage in Settings > AI.

---

### Ad Lab — ads from a URL, by named angle

_Paste a product URL, pick which angles to write, get Meta-ready ads with second-opinion scoring._

Go to **AI Studio > Ad Lab** when you want a strong starting set of ads for a product but don't have a winning ad to clone from yet.

**Three-step flow:**

**Step 1 — Brief.** Paste a product URL (Shopify product page, advertorial, sales lander — anywhere the offer is spelled out). Pick a text model (Claude Sonnet/Opus/Haiku or GPT-5.4) and optionally add extra instructions. Click **Extract brief**. In ~10 seconds you get the structured marketing brief Claude pulled from the page: benefits, audience, positioning, price, and tone. Sanity-check the extraction before spending more credits.

**Step 2 — Pick angles.** The original 5 are pre-checked: **Problem-aware**, **Benefit-led**, **Social proof**, **Direct offer**, **Curiosity**. Toggle them off, add others from the preset list (**Authority**, **Urgency**, **Scarcity**, **Storytelling**, **Before / after**, **Educational**, **Counterintuitive**), or **Add custom angle** to define your own (name + optional spec of what the angle should do). 1–10 angles per run. Click **Generate N ads**.

**Step 3 — Ads + scores.** One ad per selected angle, each with headline / primary text / description / CTA. Then a second AI pass with **Claude Opus** scores each ad on hook strength, brand fit, and clarity — independent of the model that wrote it (which is the only way to get honest scores). Cards render side-by-side for easy comparison.

**Image generation (optional):**
Each card has a "Generate image" button. Pick the image vendor at the top (Gemini or GPT Image 2). Or use **"Generate images for all N angles"** to fire them in parallel — there's a cost confirmation before it runs. Images render into a Meta-feed preview card.

**Shipping to Meta:**
- **"Use this angle"** — opens **Create Ads** pre-filled with the headline, primary text, description, and CTA from that card.
- **"Use with image"** — same plus the generated image (saved to your image library automatically, tagged `ai-generated` / `ad-lab`).

In the Create Ads form, pick the FB account, page, pixel, budget, and targeting — Ad Lab seeds the creative, you make the campaign decisions.

**History:**
Every Ad Lab run is saved. Click **History** in the top-right of the Ad Lab page to see your past runs. Click any row to re-open it — brief, angles, scores all rehydrate. Image regeneration is per-session (images live in your image library; click `ai-generated`/`ad-lab` tags to find them).

**About the scores:**
The scoring pass uses an **independent opus-tier model** — it sees the brief and the ads without seeing which model wrote which ad. That makes the scores comparable across runs (and comparable to your own gut). They're still qualitative judgments, not predicted CTR. A score of 5 means Opus thinks the ad hits hard; a 1–2 means even Opus thinks it's weak.

**Brand voice:**
If you've set a brand profile in **Settings > AI**, it's automatically applied to both the brief extraction and the angle writing. Claude won't violate your forbidden claims and adapts to your tone.

**Tips:**
- Run on the most polished URL you have — Ad Lab can only extract what's on the page. Thin pages produce thin briefs.
- Use extra instructions to nudge toward a specific framing if the defaults miss the point.
- After extracting the brief, you can regenerate angles cheaply (no re-extraction cost) — try the original 5 first, then run again with custom angles based on what scored highest.
- Custom angles work best when you describe what the angle should do, not just name it.

**AI credits:**
- Brief extraction: one text-model call
- Angle writing: one text-model call
- Scoring: one Opus-tier call
- Image generation: one image-model call per image

A full 5-angle run is ~$0.10–0.20 of AI credits. Monitor spend in **Settings > AI**.

---

### AI variant generation for tests

_How AI generates landing page variant suggestions for your A/B tests._

When creating or managing page tests, you can use AI to automatically generate variant ideas.

**How it works:**
1. ROAS.to analyzes your landing page (headlines, CTAs, images, layout)
2. AI generates alternative versions based on proven optimization strategies
3. Each suggestion comes with a strategy label (e.g., "Urgency," "Social Proof," "Curiosity")
4. You review and select which suggestions to add as test variants

**Where to use it:**
- During test creation (Step 4 of the wizard) — AI button appears next to each element
- From an existing test detail page — click "Generate AI Variants"
- With auto-generation enabled (in test settings) — AI creates variants automatically on an ongoing basis

**AI strategies used:**
- Urgency
- Social Proof
- Authority
- Curiosity
- Direct Benefit
- Emotional
- Specificity
- Fear of Missing Out
- Contrast

**Tips:**
- Let AI generate ideas, then manually refine the best ones
- Combine AI suggestions with your own domain knowledge
- The AI learns from your page context, so better pages get better suggestions

---

### AI Chat Assistant

_Using the built-in AI assistant for media buying questions._

ROAS.to includes a built-in AI chat assistant that can answer questions about media buying, your campaigns, and platform features.

**How to access:**
Click the chat bubble icon in the bottom-right corner of any page to open the chat panel.

**What it can help with:**
- Media buying strategy questions
- Campaign optimization advice
- Understanding your metrics
- Platform feature explanations
- Troubleshooting issues

**Model selection:**
Toggle between Sonnet (faster, good for most questions) and Opus (deeper reasoning for complex strategy questions) using the model toggle in the chat header.

**Tips:**
- Ask specific questions about your campaigns for more actionable advice
- Use it to brainstorm new angles or creative strategies
- Clear the conversation to start fresh on a new topic

---

### AI credits and usage

_Understanding how AI credits work, usage tracking, and budget limits._

Every AI feature in ROAS.to uses credits from your monthly AI budget.

**Default budget:** $50/month (adjustable in Settings)

**What uses credits:**
- AI headline generation
- AI CTA generation
- A/B test variant generation
- Campaign cloning with AI
- Ad Copy Editor
- Product Copy Generator
- Ad Lab (URL → brief + angles + opus-tier scoring, plus optional per-angle image gen)
- AI Chat Assistant
- Creative analysis
- Page analysis

**Tracking usage:**
Go to Settings to see:
- Cycle budget and current spend
- Credits used this cycle
- Last 50 AI generations with feature, model, tokens, and cost
- Budget resets on your billing renewal

**If you hit the limit:**
AI features will be temporarily blocked until your next billing renewal. You can purchase additional AI credits from Settings > Billing — top-ups apply to the current cycle only.

**Cost optimization:**
- Sonnet is the default model — good balance of quality and cost
- Opus costs more but provides deeper analysis for complex tasks
- Haiku is the cheapest for simple generation tasks

---

### Account Health Check (AI)

_One-click AI diagnosis of your Facebook ad account: what is broken, what is leaking spend, and what to fix first._

Go to **AI Studio > Account Health Check** to run a one-click AI diagnosis of your Facebook ad account.

**What it analyzes**
- Spend distribution across campaigns
- ROAS, CPA, and CTR trends
- Frequency / fatigue on top spenders
- Account structure (naming, pacing, budgets)
- Pixel coverage and sync gaps
- Active vs paused campaign mix

The analysis is hardcoded to **the last 7 days** of data — there is no date-window selector in the form.

**Running it**
1. (Optional) Add extra instructions in the textarea — e.g. "Ignore the testing account" or "Focus on the scaling campaigns only."
2. Click **Run health check**.
3. ~20-40 seconds for the report.

**The output**
- **Grade** — letter grade for the account (A–F)
- **Estimated weekly savings** — dollar value the analyzer thinks you'd recover by fixing the issues
- **Issues** bucketed by severity: `critical`, `warning`, `optimization`
- **Top 3 actions** — what to do first
- Each issue includes a one-sentence problem statement and a concrete fix

**When to run it**
- After a bad week (find what broke)
- Before scaling a new product (catch issues before you push budget)
- Monthly cadence as a routine audit

**Brand voice + custom prompts**
Account Health respects your brand profile and any custom prompt you've set in **Settings > AI > Prompt Library**.

**AI credits**
One text-model call per run. Cost varies with the size of the account being analyzed.

---

### Creative Strategist (AI)

_AI pattern analysis on your winning vs losing creative — what is hooking and what is dying, in plain English._

Go to **AI Studio > Creative Strategist** to find patterns across your winning and losing creative.

**What it does**
Pulls your top-performing and bottom-performing creatives in the selected window and has an AI strategist analyze them. You get:
- **Winning patterns** with example ad references
- **Losing patterns** with example ad references
- **Kill list** — specific ads worth pausing
- **Creative briefs** — recommended next angles to test
- **Top performers** and **Bottom performers** tables

**Inputs**
- **Date range** — pick `last_7d`, `last_30_days`, or `this_month` (no custom range or weekly cadence)
- **Extra instructions** — optional textarea to bias the analysis (e.g. "focus on the supplement campaigns" or "ignore the test account")

**Workflow**
- Run on a regular cadence to catch fatigue shifts before your ROAS drops
- Pipe the suggested angles into **Ad Lab** to generate the actual ads

**Brand voice**
Respects your brand profile. Custom prompt override available in Settings > AI > Prompt Library if you want to tune the strategy lens.

**AI credits**
One text-model call per run. Cost depends on how many ads land in the top/bottom buckets.

---

### Audience Analyzer (AI)

_Which targeting segments and demographics are actually driving ROI — and which are eating spend for show._

Go to **AI Studio > Audience Analyzer** to break down ad-set performance by targeting type — interests, lookalikes, custom audiences, and broad — and see which segments to scale, which to kill, and where to expand.

**What it analyzes**
Performance grouped by ad-set targeting type:
- Interests
- Lookalikes
- Custom audiences
- Broad

It does NOT break down by geography, age/gender, device, placement, or time-of-day. For those views, use the **Insights** dashboard's breakdown filters.

**Inputs**
- **Extra instructions** — optional textarea, e.g. `"Exclude retargeting"` or `"Focus on 25-44 lookalike audiences."`

**Output**
Three buckets, each as a list:

- **Scale** — ad sets that are working. Each item includes the ad-set name, the reason, and a target increase ("bump 25%", etc.).
- **Kill** — ad sets to pause. Each item includes the ad-set name, the reason, and the estimated waste per week.
- **Test** — new audience ideas worth trying. Each item includes the idea and the reasoning.

**Use cases**
- Onboarding a new account — find the high-converting targeting type fast
- Scaling beyond an initial winning audience — discover adjacent segments
- Tightening a bloated account — find what to cut

**Brand voice + prompts**
Respects brand profile and prompt overrides.

**AI credits**
One text-model call per run.

---

### Scaling Advisor (AI)

_When to push budget, when to hold, when to back off — AI-driven scaling guidance based on your account trajectory._

Go to **AI Studio > Scaling Advisor** for AI-driven guidance on whether to scale, hold, or pull back, based on your last 30 days of performance.

The advisor runs at the **account level** — it returns one strategy for the whole account, not per-campaign recommendations.

**What it analyzes**
- 30-day ROAS, spend, and trajectory
- Diversity across campaigns/ad sets
- Concentration risk (one campaign carrying the account)
- Marginal ROAS by spend quintile

**Inputs**
- **Extra instructions** — optional textarea (e.g. focus on a specific account or campaign set)

**Output — one of four account-level strategies**
- **Horizontal Scale** — launch more variants / audiences / lookalike sources rather than pushing existing winners
- **Vertical Scale** — push budget into existing winners
- **Hold Steady** — performing fine, no changes recommended
- **Cut Back** — declining, recommend reducing spend or pausing weak campaigns

Each result also surfaces:
- A reason ("strategyReason") explaining the call
- A 4-week plan
- Guardrails (ROAS thresholds the strategy assumes)
- Marginal ROAS by spend quintile
- Concentration risk indicator (low / medium / high)

**When to use it**
- Once a week as a strategic check (not for tactical per-campaign moves)
- Before a big spend ramp (sanity check that the account can absorb it)
- When you can't tell if a slowdown is noise or genuine fatigue

**Constraints**
Reads from synced data — only as accurate as your sync freshness.

**AI credits**
One text-model call per run.

---

### Competitor Rewriter (AI)

_Paste a competitor ad, get an adapted version that follows the same winning framework but in your brand voice._

Go to **AI Studio > Competitor Rewriter** to reverse-engineer a competitor's ad and adapt their winning framework to your product.

**How it works**
1. Paste the **competitor ad copy** into the first textarea (headline, body text, the whole thing). This is text-only — there is no image upload or OCR.
2. Paste your **product description** into the second textarea (product name, benefits, target demographic, offer details, price point).
3. Click to analyze and rewrite.

**Output**
- **Hook type** identified in the original
- **Framework** the original uses (problem-aware, curiosity, social proof, authority, etc.)
- **Emotional triggers** the original leans on
- **CTA strategy** the original uses
- **Strengths** and **Weaknesses** of the original
- **3-5 variations** — adapted versions in your voice, each with a confidence level

**Why this works**
Competitors do the testing for you. If their ad has been running for 30 days, the framework is validated. Borrowing the framework (not the copy) saves you the test cycle.

**Brand voice + forbidden claims**
Respects your brand profile — won't introduce claims you've marked forbidden. If a competitor's framework relies on a forbidden claim, the analyzer notes the conflict and offers a compliant alternative.

**AI credits**
One text-model call per run.

---

### Page Rewriter (AI)

_Rewrite landing page sections with AI and live-A/B-test the rewrites against your original._

Go to **AI Studio > Page Rewriter** to rewrite advertorial page sections with AI for higher conversion.

**How it works**
1. Enter your advertorial page URL.
2. Click to fetch — ROAS.to pulls the page HTML and shows the content in the editor. You can also paste the content manually if the URL can't be fetched.
3. (Optional) Add extra instructions, e.g. `"Make the headline more urgent"`, `"Focus on social proof"`, `"Target women 45+"`.
4. Click to run.
5. The output shows the original page section + a rewritten version side-by-side, labeled by technique (`headline`, `intro`, `cta`, `testimonial`, `body`, etc.).

**Shipping the rewrites**
There are two copy actions on each rewrite card:
- **Copy rewritten content** — copies just the new text for manual paste-in
- **Copy as A/B test config for On-Page A/B Tests** — copies a JSON config you can paste into the **On-Page A/B Tests** tool when creating a new test

Page Rewriter does **NOT** auto-deploy an A/B test. You take the rewrite into the On-Page A/B Tests tool manually. See **Creating a Page Test** for the test setup.

**Iterating**
After running for a few days, promote winning variants from the test detail page. Re-run Page Rewriter to generate fresh rewrites against the new baseline.

**AI credits**
One text-model call per run, scaled by the page length.

---

### AI Reports

_Generate markdown performance reports for clients, partners, or your own records — with AI commentary on what the numbers mean._

Go to **AI Studio > Reports** to generate AI-written performance reports.

**What it generates**
A markdown-formatted report covering:
- Header summary (period, total spend, total revenue, ROAS, profit, conversion count)
- Top performers by spend, by ROAS, by volume
- Bottom performers (and why)
- Trend analysis vs the previous period
- Creative-level insights (top images, top headlines)
- AI commentary on what the numbers mean and what to do next

**Inputs**
- **Period** — pick one of `last_7d`, `last_30_days`, or `this_month` (no 14d, no MTD, no custom range)
- Optional custom instructions in a textarea (e.g. "focus on iOS performance," "compare Black Friday to Cyber Monday")

**Output formats**
- View in-app (rendered markdown)
- Copy as markdown (for pasting into Notion, Slack, email)
- Download as `.md` file

**Use cases**
- **Client reports** — generate a weekly client deliverable in 30 seconds
- **Partner reports** — share account-level numbers with your media buyer / consultant
- **Personal log** — generate a monthly snapshot for your own records
- **Board updates** — high-level commentary your CFO can read

**Brand voice + custom prompts**
Respects brand profile. Override the report system prompt if you want a specific report style (executive summary vs detailed breakdown vs creative-focused).

**Sharing**
Reports are private to your workspace by default. Copy the markdown if you want to share externally.

**AI credits**
One Opus-tier call per report. Cost depends on data volume; typical ~$0.10-0.30.

---

### Dayparting Optimizer (AI)

_AI analysis of your most profitable hours, with concrete recommendations for hourly schedules or HDP windows._

Go to **AI Studio > Dayparting** for AI-driven analysis of when your ads make money and when they burn it — find your most profitable hours and eliminate overnight waste.

**What it analyzes**
- Hourly profit / ROI across the selected period
- Peak hours (concentrate budget here)
- Dead hours (you're burning money)
- Weekly and monthly waste estimates

**Inputs**
- **Date range** — `last_7d`, `last_30_days`, or `this_month`
- Optional extra instructions

**Output**
- **24-hour profit heatmap** — average daily profit per hour in your timezone; green = profitable, red = burning money
- **Peak hours** — when to concentrate budget
- **Dead hours** — when to pause delivery
- **Daily waste** estimate, plus rolled-up weekly and monthly waste

**Difference from the Analytics dayparting view**
The **Analytics > Dayparting** page shows the raw heatmap. **AI Studio > Dayparting** does the analysis for you and surfaces specific hours plus a waste estimate. The analytics page is the report; this is the read of the report.

**Note on applying recommendations**
Dayparting Optimizer does **not** auto-create an automation rule. To act on the recommendations, go to **Automation > Rules** and set the Day Parting / Skip Days settings in Section 4 of the rule wizard manually.

**AI credits**
One text-model call per run.

---

### Brand Profile and Prompt Library

_Set your brand voice once and every AI tool uses it. Override per-tool system prompts for surgical control._

Every AI tool in ROAS.to (Ad Lab, Copy Editor, Product Copy, Page Rewriter, Account Health, Creative Strategist, etc.) reads your brand profile and any custom prompts you've defined. Set them once and every tool stays in your voice.

**Brand profile (Settings > AI > Brand Profile)**

- **Brand name** — your company / product / offer name
- **Niche / vertical** — what you sell, in 1-2 sentences
- **Voice description** — formal? punchy? conversational? Match what your team actually uses.
- **Forbidden claims** — claims AI must NEVER make. Critical for compliance-sensitive verticals (health, finance, supplements). Examples: "cures," "guaranteed results," "FDA approved" (unless you actually are).
- **Example winning copy** — paste 2-5 examples of your best ad copy. AI uses these as style anchors.
- **Additional context** — anything else (target customer profile, common objections, key differentiators)

Once saved, every AI tool reads the profile automatically. No need to re-paste your brand voice into every prompt.

**Prompt Library (Settings > AI > Prompt Library)**

Each AI tool has a default system prompt that controls how it operates. The Prompt Library lets you override the default per-tool. Use this when:
- The default tone is off for your account (e.g., you sell to skeptics and need a more measured tone)
- You want a specific output format (e.g., always include a 5-second elevator pitch at the top)
- You're running a multi-brand workspace and need different prompts per brand

**Editing a prompt**
1. Pick the tool from the list (Copy Editor, Ad Lab, Account Health, etc.)
2. Read the default prompt to understand what it does
3. Edit and save — your override takes effect on the next generation
4. Reset to default any time

**Model preferences**

Set your default model for your workspace:
- **Claude Opus 4.8** — deepest reasoning, best for strategic analysis (Account Health, Creative Strategist)
- **Claude Sonnet 4.6** — balanced; the default for most generation tasks
- **Claude Haiku 4.5** — fastest, cheapest, fine for simple rewrites
- **GPT-5.x** — alternative provider for diversity
- **Gemini** — image generation default

Per-tool model override available in the Prompt Library — e.g., use Opus for Account Health but Sonnet for everything else.

**AI credit monthly budget**

Set your monthly AI budget in Settings > AI. ROAS.to warns at 80% usage and blocks new generations at 100%. Top-up credits available mid-cycle. See **AI credits and usage** for the cost model.


## Analytics

Insights, funnels, dayparting, and creative analysis

### Insights dashboard

_Deep-dive into campaign performance with multi-dimensional breakdowns._

Go to **Analytics > Insights** for a comprehensive view of your Facebook ad performance.

**Features:**
- **Date range picker** — view data for any time period
- **Account filter** — focus on specific ad accounts
- **Metric breakdowns** — see performance by campaign, ad set, ad, or creative level
- **Real-time data** — metrics sync every minute

**Key metrics available:**
- Spend, impressions, reach, frequency
- Clicks, CTR, CPC, CPM
- Conversions, revenue, ROAS
- Video views and average watch time
- Link clicks and landing page views

**Manual sync:**
If you need the latest data immediately, use the "Sync Now" button to trigger an immediate sync of your performance metrics.

**Sync status:**
The indicator shows when your data was last updated — Live (< 5 min), Synced (current), or Stale (> 10 min).

---

### Creative Analysis

_Understand which headlines, images, and CTAs perform best._

Go to **Analytics > Creative Analysis** to see element-level performance breakdowns.

**Dimensions you can analyze:**
- **Images** — which images drive the best CTR and ROAS
- **Headlines** — top-performing headline text
- **Body text** — which ad copy converts best
- **URLs** — destination URL performance
- **Ads** — individual ad performance ranking
- **Hourly** — performance by hour of day
- **Launch time** — how ads perform based on when they were launched

**How to use it:**
1. Select the dimension you want to analyze
2. Filter by campaign or date range
3. Sort by the metric that matters most to you (ROAS, CTR, conversions, etc.)

**Actionable insights:**
- Identify your best-performing creative elements
- Find underperforming creatives to pause or refresh
- Discover which combinations of headline + image work best
- Use these insights to inform your next round of ad creation

---

### Dayparting analysis

_Find the best hours and days to run your ads._

Go to **Analytics > Dayparting** to see how your campaigns perform by time of day and day of week.

**What it shows:**
- Performance heatmap: hour of day (rows) × day of week (columns)
- Color-coded by the metric you choose (ROAS, CPC, CTR, etc.)
- Identifies peak and off-peak periods

**How to use it:**
1. Select your date range and account
2. Choose the metric to analyze (ROAS is most common)
3. Look for patterns — bright spots are high performers, dark spots are poor performers

**Taking action:**
Use dayparting insights to:
- Set up automation rules that increase budgets during peak hours
- Pause campaigns during consistently poor-performing hours
- Schedule ad launches during historically high-converting times
- Set quiet hours in your automation settings to prevent budget waste overnight

---

### Funnel analysis

_Visualize the complete conversion journey from impression to sale._

Go to **Analytics > Funnel** to see your end-to-end conversion funnel.

**Funnel stages:**
The dashboard shows a 3-stage funnel:
1. **Views** — landing page views (from Facebook clicks and direct traffic)
2. **Clicks** — CTA / product clicks on your landing page
3. **Conversions** — completed conversions tracked via postback, Everflow, or Shopify

Behind the scenes, ROAS.to also tracks Facebook-specific metrics (impressions, link clicks) for deeper analysis.

**Breakdowns available:**
- **By platform** — page tests vs. links vs. unknown traffic sources
- **By network** — Facebook vs. direct traffic
- **Time-to-conversion** — distribution of how long it takes from click to conversion
- **Session-level tracking** — individual user journey analysis

**Drop-off analysis:**
The funnel visualization shows the drop-off rate between each stage. High drop-offs indicate optimization opportunities:
- Low views relative to FB clicks: page load speed issue or redirect problem
- High views → low clicks: improve your landing page (use On-Page A/B Tests!)
- High clicks → low conversions: offer or checkout issue

---

### Budget Insights

_AI-powered budget analysis and optimization recommendations._

Go to **Analytics > Budget Insights** for intelligent budget analysis.

**What it analyzes:**
The analysis runs daily and identifies:

- **Scale opportunities** — campaigns with strong ROAS that could handle more budget
- **Budget reallocation** — suggestions to shift spend from underperformers to winners
- **Performance degradation** — campaigns that have suddenly dropped in performance
- **New winners** — campaigns that just turned profitable

**Alerts and recommendations:**
Each insight comes with:
- A specific, actionable recommendation
- The metrics supporting the recommendation
- Estimated impact of taking the action

**Example insights:**
- "Campaign X has 2.5x ROAS with only $200 daily budget — consider scaling to $500"
- "Campaign Y degraded 50% this week — investigate or reduce budget"
- "Shifting $300 from Campaign Z to Campaign X could yield 40% more conversions"

Budget data refreshes on a daily cycle (all times in ET):
- Hourly at :05 past — tracks spend changes for accurate hourly ROAS
- Early morning — generates the prior day's end-of-day performance snapshots
- Mid-morning — analyzes the data and surfaces the alerts you see here

---

### Offers hub

_View Everflow offer performance and best campaigns per offer._

Go to **Analytics > Offers** to see performance metrics grouped by offer.

**What it shows:**
- 7-day offer performance (conversions, revenue, payout)
- Best-performing campaigns per offer
- Network breakdown (Facebook-attributed vs. other)
- Revenue and payout tracking

**Requirements:**
This page requires the Everflow integration to be configured (Settings > Integrations > Everflow). Without it, there's no offer data to display.

**Use cases:**
- Compare offer performance to decide where to allocate budget
- Identify which campaigns drive the most conversions for each offer
- Track payout amounts and revenue trends over time

---

### Overview, Operations, and Attention pages

_Three dashboard-section views: your workspace home, live system health, and the actionable-items inbox._

Three views answer "what's going on right now," "is anything broken," and "is anything waiting on me." Overview and Operations live at the top of the sidebar; Attention is your end-of-day inbox.

**Overview**
The workspace home. When you first land here it shows welcome states based on account setup:
- "Welcome to ROAS.to! Let's get your ads optimized." — pre-onboarding
- "No Facebook ad accounts connected" — onboarding done but no Business Manager linked
- "No campaign data yet" — accounts linked, sync in progress

Once campaigns are syncing, the page shows your aggregate dashboard: top campaigns by spend, recent conversions, store-direct revenue, and so on. Store-direct revenue is sales from your store that didn't come through a tracked ROAS.to campaign (e.g. Shopify direct or organic) — it's shown separately and isn't counted in campaign ROAS.

**Operations**
System health, sync status, and automation activity for your workspace:
- **System Health banner** at the top with a status label and any active issues as badges
- Active campaigns + active automation rules counter
- Last sync timestamp (per account)
- Today's spend, conversions (platform + external), revenue
- Recent automation actions
- Recent syncs (status, duration, errors)
- FB token / sync state per account
- AI credit usage this cycle

Use Operations as your daily morning check — 30 seconds tells you if anything in your stack is broken.

**Attention**
A curated inbox of items that need your decision:
- A/B tests ready to promote (winners with statistical confidence and EPV lift)
- A/B tests needing evaluation (variants with insufficient data after N days)
- Recent wins worth reviewing (auto-promotions, big spend swings)
- FB token expiry warnings
- Catalog permission issues
- Pixel coverage drops
- Account state issues (past-due, deactivated)

Each item is one-click actionable — promote, dismiss, view details. Attention is designed for the "5 minutes at the end of the day to see if anything needs me" workflow.

**Notification routing**
Items that appear on the Attention page can also fire as Slack / Telegram / email notifications. Configure per-event toggles in **Settings > Notifications**.


## Conversions & Tracking

Conversion tracking, Everflow, Shopify, and CAPI

### Conversions dashboard

_Overview of all conversion tracking data across sources._

Go to **Analytics > Conversions** to see all your conversion data in one place.

**Data sources:**
- **Postback URL** — conversions fired via your webhook URL (affiliate networks, custom integrations)
- **Everflow** — auto-synced from your Everflow account
- **Shopify** — order data from your connected store
- **Facebook Pixel** — pixel-based conversions from FB

**Key metrics:**
- Total conversions today and over time
- Revenue and average payout
- Conversion rate (clicks to conversions)
- Source breakdown (which integration sent each conversion)

**Attribution:**
Each conversion is linked back to:
- The click ID that generated it
- The ad/campaign that drove the click
- The landing page variant the user saw (if using page tests or campaign tracker)

---

### Everflow integration

_How to connect Everflow and sync affiliate conversion data._

Go to **Settings > Integrations > Everflow** to connect your Everflow account.

**Setup:**
Fill in the five required fields, then Save:
1. **API Key**
2. **Network ID**
3. **Everflow Network Name** (your network's subdomain)
4. **Affiliate Tracking Code**
5. **Tracking Domain**

Two optional fields — **Smart Link Affiliate Code** and **Facebook Affiliate ID** — let you use the built-in link builder and pre-fill your affiliate ID in tracking links.

**What gets synced:**
- Conversion data (transaction ID, revenue, payout)
- Click data for attribution
- Offer metadata
- Daily reconciliation to catch any discrepancies

**Everflow Link Builder:**
Once connected, you can use the built-in Everflow Link Builder to construct affiliate tracking links. It lets you:
- Search and select offers
- Choose landing page variants
- Select smart links (CMP campaigns)
- Preview the complete tracking URL

**Postback setup:**
For real-time conversion tracking, also set up the ROAS.to postback URL in your Everflow network's global postback settings.

---

### Shopify integration

_How to connect Shopify and track e-commerce conversions._

Go to **Settings > Integrations > Shopify** to connect your Shopify store.

**Setup:**
Follow the connection flow to authorize ROAS.to to access your Shopify order data.

**What gets tracked:**
- Order completions
- Revenue per order
- Customer attribution (which ad/variant led to the purchase)

**Stats available:**
- Total orders tracked
- Total revenue synced
- Last event timestamp

**How it works:**
Shopify conversions are tracked via a pixel installed on your store. Orders are tagged with `shopify:` prefix in the conversions table for easy identification.

---

### Conversions API (CAPI)

_Server-side conversion tracking that bypasses iOS 14+, ad blockers, and Safari ITP. Setup, dedup, EMQ tuning, and verification._

Meta's Conversions API (CAPI) sends events directly from ROAS.to's servers to Meta — bypassing the browser entirely. Required to recover the 30-50% of conversions that browser pixels lose to iOS 14+, Safari ITP, and ad blockers.

## What CAPI fixes

When the Meta browser pixel can't fire (iOS 14+ ATT, Safari ITP, ad blockers, consent gates), Meta loses the conversion signal entirely. CAPI sidesteps the browser:

- **Without CAPI:** browser pixel fires Purchase → Meta receives ~60-70% → optimizer trains on biased data → ROAS underreported, lookalikes weak.
- **With CAPI:** browser pixel + ROAS.to server-side both fire → Meta dedupes them → coverage approaches 100% → optimizer trains on real data.

You should run **both** the browser pixel AND CAPI. Meta dedupes so there's no double-counting.

## Setup

1. Connect your Facebook ad account in **Settings > Facebook Accounts**.
2. Go to **Facebook Settings > CAPI** and toggle **Enable CAPI**.
3. (Recommended for first use) Toggle **Test Mode** on, paste your **Test Event Code** from Meta's Events Manager, and verify events appear in Test Events.
4. Toggle Test Mode off to start sending production events.

CAPI uses the pixel + access token from your connected Facebook ad account — no separate token to manage.

## Settings

**Enable CAPI** — master switch. When off, no events are sent. Any events already queued stay pending until you enable it (or expire after 7 days).

**Test Mode** — events flow to Meta's Events Manager > Test Events tab instead of production. Use this when:
- First setting up CAPI (verify events arrive correctly).
- Debugging missing events.
- Testing a new event type before turning it on for production.

**Test Event Code** — paste this from **Events Manager > your pixel > Test Events**. Without it, test-mode events go to Meta but won't be routed to your Test Events stream. Looks like `TEST12345`.

**Event types** — toggle which events to send:

- **Purchase** — fires on every conversion (Everflow postback, Shopify checkout, universal pixel `window.roas('purchase')`). Always recommended.
- **ViewContent** — fires when a visitor clicks a tracked product link on an advertorial/listicle page. Strong intent signal that helps Meta's optimizer.
- **PageView** — fires on every FB-attributed page view. Highest volume; useful when your Purchase volume is thin (<50/wk) and Meta needs more signal to optimize.

The toggles only affect outbound CAPI; nothing in your dashboard or attribution model changes when you toggle them.

## Event flow

| Source | Event | Triggered by |
|---|---|---|
| Advertorial page | PageView | Visitor lands on listicle |
| Advertorial page | ViewContent | Visitor clicks tracked product link |
| Universal pixel (`window.roas`) | PageView | Page load on merchant site |
| Universal pixel | Lead, AddToCart, InitiateCheckout | Merchant calls `window.roas('lead')` etc. |
| Universal pixel | Purchase | Merchant calls `window.roas('purchase')` |
| Shopify Custom Pixel | Purchase | `checkout_completed` event |
| Everflow sync | Purchase | Conversion appears in Everflow REST API |
| Conversion postback | Purchase | Server-to-server postback to `/p/:publicPostbackId` |

Multiple sources can fire for the same physical sale (e.g. Shopify pixel + Everflow postback). ROAS.to dedupes on the order ID and transaction ID, so each sale is sent to Meta exactly once — no double-counting.

## Browser pixel ↔ CAPI deduplication

Meta dedupes events that share the same `event_id` and `event_name`.

For Shopify and universal pixel Purchase events, ROAS.to sends `event_id = order_id` (raw, unprefixed). This matches what Meta's own pixel emits — so if you have **both** the Meta browser pixel (via Shopify's Meta channel, GTM, etc.) and ROAS.to's CAPI running, Meta will see them as the same event and count the sale once.

If you're seeing doubled Purchase counts in Ads Manager, check:
1. Both events use the same `event_id` (Meta dashboard → Events Manager → Diagnostics).
2. Both fire within Meta's dedup window (~48h).
3. Both events have matching `event_name` exactly (case-sensitive: `Purchase`, not `purchase`).

## Event Match Quality (EMQ)

Meta scores every CAPI event 0-10 on EMQ — the higher the score, the better Meta can match the event to a real user. Higher EMQ = better attribution + better optimization.

ROAS.to forwards every Advanced Matching identifier we can capture, all hashed SHA-256 client-side per Meta's spec:

- `em` (email)
- `ph` (phone, digits only)
- `fn` / `ln` (first/last name, lowercased)
- `ct` (city, lowercase, no punctuation)
- `st` (state, ISO 2-char lowercase)
- `zp` (zip, lowercase, no spaces/dashes)
- `country` (ISO 3166-1 alpha-2 lowercase)
- `external_id` (your visitor id, hashed — survives ad blockers)

We also forward:

- `fbc` — built from `fbclid` per Meta spec. Falls back to `fbp` when `fbclid` is missing.
- `fbp` — pulled from `_fbp` cookie (only sent when Meta's pixel actually set it; never fabricated).
- `client_ip_address` and `client_user_agent` — captured server-side.
- `fbc creation_time` — set to when the click was first captured (the pageview landing time), not the conversion time. Critical for delayed conversions: a Purchase 2 days after the click reports `fbc creation_time` as the actual click moment, not "now," preserving Meta's 7-day attribution window.

The Shopify Custom Pixel reads identifiers from `checkout.billingAddress` (preferred) or `checkout.shippingAddress`. The universal pixel accepts a `customer` object on every event:

```javascript
window.roas('purchase', {
  order_id: '12345',
  total: 49.99,
  customer: {
    email: 'jane@example.com',
    phone: '+1 415 555 1234',
    first_name: 'Jane',
    last_name: 'Doe',
    city: 'San Francisco',
    state: 'CA',
    zip: '94103',
    country: 'US'
  }
});
```

All hashing happens client-side before the network call — raw PII never leaves the browser.

## Sub IDs vs CAPI: how they work together

Two attribution channels run in parallel:

- **Sub IDs (`sub1`/`sub2`/`sub3`)** — deterministic. Stamped into your ad URLs at creation time. Carry through cookies and our pixel. Used for **internal attribution** in your dashboard.
- **`fbclid` + `_fbp`** — lossy (~30-40% drop). Used **only** to build the CAPI `user_data` payload for Meta's matching.

Sub IDs are the source of truth for your internal numbers. CAPI is a separate channel that informs Meta's optimizer. They don't compete — they complement each other.

## Verifying CAPI is working

1. Enable Test Mode in **Facebook Settings > CAPI**, paste your Test Event Code.
2. Trigger a real event (a test purchase, or a pageview from an FB-attributed URL).
3. Open **Events Manager > your pixel > Test Events** in Meta — events should appear within ~30 seconds.
4. Click an event to inspect the payload. Confirm:
   - `event_name` is correct (`Purchase`, `ViewContent`, `PageView`, etc.).
   - `event_id` is set.
   - `user_data` contains hashed identifiers (em, ph, fn, ln, ct, st, zp, country, fbp, fbc).
   - `custom_data.value` and `custom_data.currency` are set on Purchase events.
5. EMQ score appears in the Diagnostics tab — aim for 6+ on Purchase.

Once verified, turn Test Mode off. Production events start flowing immediately.

## Stats panel

The CAPI panel shows the last 24 hours, broken down by event type:
- **Sent** — successfully delivered to Meta.
- **Pending** — queued, waiting for the next send.
- **Failed** — Meta rejected (4xx) or our retries exhausted (3 attempts with exponential backoff).
- **Success rate** — sent / (sent + failed).
- **Revenue Sent** — sum of `custom_data.value` for sent Purchase events.

A success rate below 95% usually means one of:
- Token expired or revoked → reconnect Facebook in **Settings > Facebook Accounts**.
- Pixel ID changed → reconnect the ad account.
- Malformed customer data (very rare) → contact support and we'll check the logs.

## Multi-currency

CAPI Purchase events report the currency from the source:
- **Shopify** — uses `checkout.totalPrice.currencyCode`.
- **Everflow** — uses the offer's `currency_id` from the Everflow REST API; for postbacks, requires the `{currency}` macro in the postback URL template (defaults to USD if missing).
- **Universal pixel** — uses the `currency` field on the `window.roas('purchase')` call.

Meta uses the reported currency for ROAS calculation in Ads Manager. If you run EUR/GBP campaigns and see USD-denominated revenue in Ads Manager, your Everflow offer is likely missing the `{currency}` postback macro.

## Common issues

**Events show as 'pending' for a long time** — events normally send within seconds. If the pending count keeps climbing instead of clearing, contact support.

**EMQ score is 2-3** — you're probably only sending fbclid/fbp without an email or phone. Wire `window.roas('purchase', { customer: { email, phone } })` on the universal pixel, or verify the Shopify Custom Pixel is reading `checkout.billingAddress`.

**Doubled Purchase counts in Ads Manager** — your merchant Meta pixel is firing `Purchase` with a different `event_id` than CAPI. Confirm both use the raw order_id, no prefix.

**Purchases in wrong day** — CAPI uses the actual checkout completion time (forwarded from the browser), not when the webhook arrived. If you still see drift, check that your Everflow postback template includes `{conversion_unix_timestamp}` so Everflow-sourced purchases also use the real conversion time.

**"CAPI failed to queue event" in logs** — usually a malformed user_data identifier (non-hex hash) or invalid IP. The event is dropped; tracking is unaffected. Fix the source (your pixel / your postback) and the next event will queue correctly.

## Why CAPI matters

- **Better attribution** — recovers the 30-50% of conversions browser pixels lose.
- **Better optimization** — Meta trains its delivery algorithm on more complete data.
- **Better lookalikes** — built from real high-value customers, not the partial subset that survived browser tracking.
- **iOS 14+ resilience** — the only way to track conversions from iPhone visitors who declined ATT.
- **Required for some objectives** — Meta increasingly requires CAPI for advanced optimization signals.

---

### Installing the universal pixel on any site

_How to install the ROAS.to universal pixel on a non-Shopify site to capture pageviews, leads, and purchases server-side via CAPI._

If your funnel isn't on Shopify, the universal pixel is how you wire conversion tracking + Meta CAPI into any site you control — Webflow, WordPress, a custom landing page, a Kartra funnel, anything that lets you paste a `<script>` tag.

**What it does**
- Captures every pageview and forwards it to ROAS.to (attribution data: sub1/sub2/sub3/sub4/sub5, fbclid, fbp)
- Lets you fire `purchase`, `lead`, `addtocart`, `initiatecheckout`, `addpaymentinfo`, `completeregistration`, and `custom` events from JavaScript
- Forwards every event to Meta via the Conversions API server-side (bypasses iOS 14+, Safari ITP, ad blockers)
- Hashes any customer data you pass (email, phone, name, address) client-side before it leaves the browser

**Step 1 — Grab your pixel code**
Go to **Settings > Integrations > Tracking**. Your public pixel ID (`pk_xxx`) is shown there, along with the code to copy.

**Step 2 — Paste it before `</head>` on every page**
The pageview fires automatically on script load. Nothing else to wire if you only need pageviews.

**Step 3 — Fire events from your code**
```html
<script>
  window.roas('purchase', {
    order_id: '12345',
    total: 49.99,
    currency: 'USD',
    customer: {
      email: 'jane@example.com',
      phone: '+1 415 555 1234',
      first_name: 'Jane',
      last_name: 'Doe',
      city: 'San Francisco',
      state: 'CA',
      zip: '94103',
      country: 'US'
    }
  });
</script>
```

Supported events (call with these exact strings, lowercase, no underscores):
- `pageview` (fires automatically on script load)
- `purchase` — completed transaction, pass `order_id`, `total`, `currency`, `customer`
- `lead` — captured contact info
- `addtocart` — pass `value`, `currency`
- `initiatecheckout` — pass `value`, `currency`
- `addpaymentinfo` — pass `value`, `currency`
- `completeregistration`
- `custom` — any custom event with arbitrary payload

**Step 4 — Verify**
Enable CAPI Test Mode in **Facebook Settings > CAPI** with a Test Event Code from Events Manager, then trigger an event. It should appear in Meta's Test Events tab within ~30 seconds. See the **Conversions API (CAPI)** article for the full verification flow.

**Cross-subdomain cookies**
The pixel automatically writes attribution cookies on the registrable parent domain (e.g. `.shop.example.co.uk` AND `.example.co.uk`) so subs survive subdomain hops. Multi-label public suffixes like `.co.uk`, `.com.au`, `.com.br` are handled correctly.

**Failed-send retry**
If a network blip drops an event, the pixel queues it to localStorage and retries on the next pageview. Server-side dedup means a retried Purchase never double-counts.

**Common issues**
- **Events not arriving** — confirm the pixel code is in `<head>` not `<body>` (some funnels strip body scripts on certain page types).
- **No attribution on conversions** — check that the URL on the landing page actually carries `?sub1=...&sub2=...&sub3=...`. If not, the upstream tracker is stripping them — see **Making sure tracking parameters reach Shopify through every funnel** for the fix per funnel shape.
- **EMQ scores low in Meta** — pass the `customer` object on `purchase` events with as many fields as you have. Email + phone alone usually gets you to EMQ 6+.

---

### Bridge pixel: keep attribution alive across multi-domain funnels

_When your funnel hops between owned domains (landing.brand.com → offer.com → checkout.brand.com), cookies do not cross domains. The Bridge pixel rewrites outbound links to carry attribution forward._

Cookies don't cross domains. If your funnel goes `landing.brand.com → offer.com → checkout.brand.com`, the attribution cookies set on `landing.brand.com` are invisible at `offer.com`. The Bridge pixel solves this by rewriting outbound links on the funnel page so the next domain receives sub IDs + fbclid as URL parameters.

**When you need it**
Use the Bridge pixel when ALL of these are true:
- Traffic lands on Domain A (a landing page, advertorial, or quiz)
- Domain A sends visitors to Domain B (a separate offer or checkout domain)
- You want attribution preserved into Domain B's conversion events

If your funnel is single-domain or routes through Shopify directly, you don't need this — the universal pixel and Shopify Custom Pixel handle it.

**What it does**
- Reads sub1/sub2/sub3/sub4/sub5 + fbclid from the incoming URL (or cookies, as fallback)
- Persists them to cookies on the host domain (so they survive page hops within Domain A)
- Rewrites every outbound `<a>` link to an allowlisted domain so the next hop carries the parameters in its URL
- Skips same-origin links (browsers already carry cookies for those)

**Installing it**
1. Go to **Settings > Integrations > Tracking** and grab the Bridge pixel code.
2. Paste it before `</body>` on every page of the bridging domain.
3. Add the destination domains you want to forward parameters to in the allowlist. Exact match or subdomain match — `example.com` matches `example.com` and `shop.example.com` but not `example.org`.

**What's allowlisted, what's skipped**
- Only links pointing to allowlisted hosts get rewritten.
- `mailto:`, `tel:`, `javascript:`, and anchor links (`#section`) are never touched.
- Links already carrying `?sub1=...` are left alone (no double-stamping).

**Configuration**
- `sub1`/`sub2`/`sub3` — campaign / adset / ad IDs
- `sub4` — internal click ID for session binding
- `sub5` — fbclid carrier when your tracker doesn't forward it natively

**Verify it's working**
Open one of your own ads, click through to your bridging domain, then hover over a CTA link to the next domain. The status bar should show `?sub1=...&sub2=...&sub3=...&sub4=...&sub5=...`. If those parameters are missing, the destination domain isn't in your allowlist.

**Bridge vs Universal**
- **Universal pixel** captures pageviews + events and forwards to CAPI. Install on every page you want pageview/conversion tracking on.
- **Bridge pixel** rewrites outbound links to carry attribution forward. Install on bridging pages between owned domains.

You usually want both: the universal pixel for event tracking, the Bridge pixel for cross-domain hops.

---

### How attribution works: sub1 through sub5 explained

_The deterministic-first attribution chain ROAS.to uses to assign every conversion back to the exact ad that drove it._

Meta's pixel sees roughly 50-70% of conversions after iOS 14, Safari ITP, and ad blockers take their toll. ROAS.to's internal attribution is built to be deterministic — we don't ask Meta who clicked, we stamp the click ourselves at ad creation time.

**The five sub IDs**

| Sub | What it carries | Stamped by |
|---|---|---|
| `sub1` | Facebook campaign ID | Ad URL at creation time |
| `sub2` | Facebook ad set ID | Ad URL at creation time |
| `sub3` | Facebook ad ID (real numeric OR internal `ad_xxx`) | Ad URL at creation time |
| `sub4` | ROAS.to internal click ID, binds the conversion back to the EXACT pageview | Pixel at page load |
| `sub5` | fbclid carrier (only when your tracker doesn't forward `{fbclid}` natively) | Pixel at page load |

`sub1/sub2/sub3` are stamped on every ad URL when the ad is created — before the click ever happens. Meta can't strip them, iOS can't kill them, ad blockers can't block them. They just exist on the URL.

`sub4` is the strongest signal we have. The pixel generates a unique click ID on every pageview and stamps it into outbound links. When a conversion eventually fires carrying that sub4, we look up the exact pageview row — no time-window guessing, no probabilistic matching.

`sub5` exists because some trackers don't forward Meta's `fbclid` automatically. Carrying it as sub5 means the pixel can still build a clean `fbc` cookie for CAPI even when fbclid would otherwise be lost.

**The resolution chain**

When a conversion arrives, attribution resolves in priority order:

1. **`sub4` (session bond)** — exact pageview match. Strongest possible signal.
2. **`sub1`/`sub2`/`sub3` + time window** — campaign/adset/ad IDs with a recent click-to-conversion lookup.
3. **`fbclid` exact match** — falls back to Meta's click ID against the pageview table.
4. **Organic** — no paid attribution signal found.

Every conversion is tagged with how it was matched, and the dashboard groups these into confidence levels:

- **Deterministic (strongest)** — matched by the click ID (the sub4 session bond), or by sub IDs that resolve cleanly to a real Facebook ad. A certain match.
- **Strong** — matched by sub IDs (or a catalog product ID) even when one part didn't fully resolve.
- **Lossy fallback** — matched only by Meta's click or browser ID (fbclid / fbp), which iOS, Safari, and ad blockers drop 30-40% of the time.
- **Probabilistic** — no paid parameters survived, but a recent visitor session or an active campaign let ROAS.to make an educated guess.
- **Unattributed** — no signal at all, or an edge case like a boosted-post mix-up.

Your attribution health indicator (and the Attribution Wizard during setup) surfaces these so you can tell certain matches from guesses.

**Why the ad ID re-derives the hierarchy**
When sub3 resolves cleanly to a real Facebook ad ID, ROAS.to re-derives the campaign and ad set from your synced ad data — not from the URL. So even if a tracker mangled the URL and dropped sub1, we still know the right campaign as long as the ad ID survived.

**Temporary ad IDs**
In the brief gap between launching an ad and Facebook returning its real ID, ROAS.to stamps a temporary internal ID. Once Meta returns the real ID, we map it back, so attribution is never lost in that window.

**The 1-of-N rule**
If sub IDs are missing entirely and only fbclid is present, ROAS.to refuses to attribute when multiple ads map to the same landing page. Hash-picking one of N candidates looks accurate but is actually probabilistic. We'd rather show "unattributed" than lie.

**Sub IDs vs fbclid + fbp**
Sub IDs are for YOUR internal numbers — the source of truth in your ROAS.to dashboard. `fbclid` + `_fbp` are used ONLY to build the CAPI `user_data` payload so Meta can match the event to a user. They don't compete; they complement.

**fbp is never fabricated.** A missing `_fbp` cookie means the Meta pixel didn't fire on the page (often: ad blocker, consent gate, or page never loaded the pixel). We don't invent a value — fabricating one would poison Meta's own dedup.

**Verifying attribution is working**
1. Open one of your own ads in an incognito window.
2. Click through to your landing page.
3. Confirm the URL has `?sub1=...&sub2=...&sub3=...` visible.
4. Complete a test conversion (real purchase, test postback, or universal pixel call).
5. In **Conversions** (and on your attribution health indicator), the conversion should land as a deterministic match — not unattributed or inferred.

If a conversion you know came from an ad shows up unattributed, something stripped sub IDs between Facebook and the landing page. See **Making sure tracking parameters reach Shopify through every funnel** for the fix.


## Settings

General settings, notifications, integrations, and team

### General settings

_Configure your workspace name, timezone, and display preferences._

Go to **Settings > General** to configure basic workspace settings.

**Account settings:**
- **Business/Brand Name** — displayed in the dashboard header
- **Timezone** — used for scheduling automations, displaying timestamps, and reporting. Should match your Facebook ad account's timezone for accurate data

**Currency:** there is no global currency setting. Facebook ad spend, budgets, and bids always render in each ad account's own currency (synced from Meta). Tracker conversion revenue and landing-page revenue use the currency of your primary ad account as a default.

**Display preferences:**
- **Default Date Range** — what date range is pre-selected when you open analytics pages. Options: Today, Last 7 Days, Last 30 Days, Month to Date
- **Date Format** — MM/DD/YYYY or DD/MM/YYYY

**Important:** Your timezone setting affects when automation rules fire, when daily reports are generated, and how dates appear throughout the dashboard. Make sure it matches your Facebook ad account's timezone.

---

### Managing ad accounts

_Add, remove, and manage your connected Facebook ad accounts._

Go to **Settings > Accounts** to manage your connected Facebook ad accounts.

**What's shown per account:**
- Account name and ID (act_XXX)
- Currency and timezone
- Business ID (if linked)
- Active/inactive status
- Last sync timestamps (campaigns, insights)

**Adding a new account:**
Click "Add Account" to connect additional ad accounts from your business. The account must be assigned to your system user in Facebook Business Settings.

**Managing accounts:**
- **Toggle active/inactive** — inactive accounts stop syncing (saves resources)
- **Remove account** — disconnects the account from ROAS.to
- **Sync** — trigger a manual data sync for a specific account

**Multiple accounts:**
You can connect as many ad accounts as you have access to. Each account syncs independently. Filter by account throughout the dashboard to focus on specific accounts.

---

### Ad defaults

_Set default values for new ad creation to save time._

Go to **Settings > Ad Defaults** to configure default values used when creating new ads.

**Available defaults:**
- **Language** — default ad language (English, Spanish, etc.)
- **Special Ad Category** — None, Politics, Social Issues, Alcohol
- **Bid Strategy** — CPC, CPM, vCPM, oCPM
- **Optimization Event** — Link Clicks, Conversions, Landing Page Views, etc.

**How it works:**
These defaults pre-fill the ad creation wizard so you don't have to set them every time. You can always override them during creation.

**Tip:** If you always run the same type of campaigns (e.g., CBO with conversion optimization), set those as defaults to speed up your workflow.

---

### Automation settings

_Configure quiet hours, weekend guard, and the global kill switch._

Go to **Settings > Automation** to configure global automation behavior.

**Quiet hours:**
Set a time range during which automation rules won't fire. Default is midnight to 6 AM in your timezone. This prevents unwanted changes while you're sleeping and data is incomplete.

**Weekend guard:**
When enabled, automation rules are skipped on Saturday and Sunday. Useful if your campaigns behave differently on weekends and you want manual control.

**Kill switch:**
The global kill switch instantly disables ALL automation rules across your entire account. Use this in emergencies — e.g., if a rule is making unexpected changes. No rules will fire until you turn the kill switch off.

**Confidence threshold:**
The default confidence level required before A/B test variants can be auto-promoted. Default is 92%. This applies to all tests unless overridden at the test level or automatically adjusted based on your traffic volume.

**Baseline split:**
The default percentage of traffic that goes to the baseline in new tests. Default is 60%.

---

### Notification settings

_Configure Slack, Telegram, and email notifications._

Go to **Settings > Notifications** to configure how you receive alerts.

**Slack integration:**
Enter your Slack webhook URL to receive notifications in a Slack channel. You'll get alerts for:
- Automation rules firing (campaigns paused, budgets adjusted)
- Variant promotions (A/B test winners)
- Spend alerts (budget thresholds)
- Error conditions

**Telegram integration:**
1. Enter your Telegram Bot Token
2. Click "Detect" to automatically find your Chat ID
3. Enable the notification types you want

**Notification preferences:**
Toggle individual notification types on/off:
- Automation fired
- Variant promoted
- Spend alert
- Performance degradation
- Error notifications

**Email notifications:**
Transactional emails (trial expiry warnings, payment confirmations) are sent automatically to your registered email via updates@updates.roas.to.

---

### Integrations overview

_All available integrations: Everflow, Shopify, custom postback, and CAPI._

Go to **Settings > Integrations** to manage all your external integrations. There are five tabs.

**Tracking (Custom Postback)**
Your unique webhook URL for receiving conversions from any source. Copy this URL into your affiliate network, tracking platform, or custom system. This is also where you grab the universal pixel and Bridge pixel code.

**Pixel**
Your ROAS.to pixel — the script that captures pageviews and conversions on your own pages and forwards them to Facebook server-side. See **Installing the universal pixel on any site** for the full walkthrough.

**Everflow**
Connect your Everflow affiliate network account. Requires: API Key, Network ID, Everflow Network Name, Affiliate Tracking Code, and Tracking Domain. Once connected, conversions sync automatically.

**Shopify**
Connect your Shopify store for e-commerce conversion tracking. Orders are tracked via pixel and attributed back to your campaigns.

**Catalogs**
Review your Facebook product catalogs and product sets, and check catalog permissions, for running Shopping Ads. See **Shopping Ads and product catalogs**.

**Conversions API (CAPI)** sits alongside these as its own settings panel — server-side conversion tracking that sends events directly to Facebook. See the **Conversions API (CAPI)** article.

**All integrations are optional** — you can use ROAS.to with just the postback URL, or combine multiple integrations for comprehensive tracking.

---

### Team management

_Invite team members, manage roles, and control access._

Go to **Settings > Team** to manage your workspace team.

**Roles:**
- **Owner** — full control, created the account. Cannot be removed.
- **Admin** — can manage team members, edit all settings, and manage campaigns
- **Editor** — can modify campaigns and tests but cannot change settings or manage team
- **Viewer** — read-only access to all data

**Inviting members:**
1. Click "Invite Member"
2. Enter their email address
3. Select a role
4. They'll receive an email invitation with a link to join

**Managing members:**
- Change a member's role
- Remove a member from the workspace
- View pending invitations and revoke them

**Multiple workspaces:**
Team members can belong to multiple workspaces. They can switch between workspaces from their account menu.

**Leaving a workspace:**
Any non-owner member can leave a workspace from their account settings.

---

### API keys

_Generate and manage API keys for programmatic access._

Go to **Settings > API Keys** to create keys for programmatic access to the ROAS.to API.

**Creating a key:**
1. Click "Create API Key"
2. Give it a name (e.g., "Zapier Integration," "Custom Script")
3. The key is displayed once — copy it immediately (it can't be retrieved later)

**Key format:** `roas_ABC123...` (prefixed for easy identification)

**Using your key:**
Include it in the `Authorization` header of your API requests:
`Authorization: Bearer roas_ABC123...`

**Key management:**
- View all keys with their name, prefix (first 8 chars), and last used date
- Toggle keys active/inactive
- Set optional expiration dates
- Delete keys to revoke access permanently

**Security:**
- Keys are stored as SHA-256 hashes (never in plaintext)
- Only the key prefix is visible in the dashboard
- Rotate keys regularly and delete unused ones

---

### Custom tracking domains

_Run your tracking links on your own domain (track.yourbrand.com) instead of track.roas.to. Required for new ad creation._

By default, ROAS.to tracking links live on `track.roas.to` and `opt.roas.to`. You can point your own subdomain at ROAS.to so your tracking URLs look like `track.yourbrand.com` or `go.yourbrand.com` instead.

**Why use a custom domain**

- **Branded URLs in your ads** — `go.yourbrand.com/abc123` looks legit; `track.roas.to/abc123` looks like a redirector
- **Better deliverability and policy compliance** — Meta is suspicious of bulk-tracking domains; your own domain has clean reputation
- **Cookie attribution** — first-party cookies on your own domain survive Safari ITP longer than third-party (`track.roas.to`) cookies
- **Required for new ad creation** — ROAS.to refuses to create ads if no custom domain is set up, to prevent attribution leaks

**How it works**

ROAS.to handles the custom-domain setup for you. You point a CNAME from your subdomain at `cname.roas.to`, and we provision the SSL certificate automatically and route your traffic — the same infrastructure that powers `track.roas.to`.

**Setting one up**

1. Go to **Settings > Domains** and click "Add Domain."
2. Enter the subdomain you want to use (e.g., `track.yourbrand.com`, `go.yourbrand.com`, `offer.yourbrand.com`).
3. ROAS.to gives you a CNAME target — point your DNS to it.
4. Wait for status to progress: `dns_pending` → `ssl_pending` → `active`. Usually 1-2 minutes if DNS is fresh.

The status indicator polls every 3 seconds for up to 3 minutes. If it's still pending after 3 minutes, your DNS hasn't propagated yet — give it 10-30 minutes and refresh.

**Picking a subdomain**

- Use a **subdomain**, not your apex domain (`track.brand.com`, not `brand.com`)
- Short is better (`go.brand.com` beats `tracking-links.brand.com`)
- Don't reuse a subdomain that already has email, an A record, or other DNS — pick something dedicated
- Common conventions: `track`, `go`, `offer`, `link`, `tr`

**DNS setup**

| Type | Name | Value |
|---|---|---|
| CNAME | `track` (or whatever subdomain) | `cname.roas.to` |

Most DNS providers (Cloudflare, Route 53, Namecheap, GoDaddy) accept CNAME records on subdomains. If your domain provider doesn't support CNAMEs on the subdomain you want, switch to a provider that does — there's no workaround.

**Verifying it's working**

Once status reads `active`, open `https://your-subdomain/_diag` in a browser. You should see a small JSON response with `ok: true` and your host listed. If you see SSL errors instead, the certificate hasn't fully provisioned yet — wait another minute.

**What runs on your custom domain**

Once active, your subdomain serves everything ROAS.to does at the click and page level:
- **Your On-Page A/B tests** — the test script you install points at your own domain, so tests run first-party (better cookie persistence against Safari ITP)
- **Your tracking pixel** — the universal pixel loads from your domain too
- External offer redirects (shortlinks)
- Link rotation (Multi-Page Rotation)
- Catalog product clicks (Shopping Ads)
- App store attribution redirects
- A diagnostic page at `/_diag` for verifying setup

Until you set up a custom domain, all of this runs on ROAS.to's shared domains (`opt.roas.to` and `track.roas.to`) instead. Setting up a custom domain doesn't break anything that's already live — see "Active but ads still show track.roas.to" below.

**Removing a domain**

You have two options:

- **Schedule removal in 90 days** (recommended) — your domain keeps routing clicks from live ads for 90 days so nothing breaks, while new ads use your replacement domain immediately. You can add a new domain right away. Once a replacement is active, the scheduled removal can no longer be canceled, but you can still speed it up.
- **Remove now** — ROAS.to stops serving the domain within seconds. Every link using this domain (including ads already live on Facebook) breaks immediately. Can't be undone.

**Three end-states, surfaced as two buttons in Settings → Account:**

1. **Cancel Subscription** (reversible) — your subscription stops, you are signed out, but every row of your data stays intact for 90 days. Sign back in any time within 90 days, re-subscribe through Settings → Billing, and everything snaps back. No fresh trial — you go straight to paid. After 90 days with no reactivation, the whole account (domain included) is permanently deleted by the data-retention cron.
2. **Delete Account → Keep domain alive for 90 days** (recommended, default) — all your data (campaigns, conversions, Facebook tokens, settings, etc.) is permanently deleted within minutes. Your custom domain keeps routing live Facebook ads for 90 days so they don't break, then is removed on day 90. Irreversible.
3. **Delete Account → Delete domain too** — full nuke. Everything, including the custom domain, is removed within minutes (in rare cases a retry can take a few hours). Live Facebook ads using the domain break as soon as it's torn down. Irreversible. Pick this only if you are certain no live ads point at your domain.

**Trial ending without subscribing** behaves like option 1 (cancel) — your data is preserved for 90 days, and you can come back any time within that window by subscribing.

**Common issues**

- **`dns_pending` for >10 min** — your CNAME isn't visible to us yet. Check with `dig your-subdomain CNAME` from a terminal. If it doesn't return `cname.roas.to`, the DNS record isn't live.
- **`ssl_pending` for >5 min** — the SSL certificate is still being provisioned. Wait. If it stays for >30 min, contact support.
- **`error` status** — the domain is already claimed elsewhere, or the subdomain has another A record. Remove the conflict and re-add.
- **Active but ads still show `track.roas.to`** — go to **Settings > Domains** and set the new domain as your **active** tracking domain. Old ads keep their original URL until re-created.

**Domain safety**

Custom domains are tied to your account. Even if two customers try to claim the same subdomain, ROAS.to checks the host against the right account on every request — you can never see another customer's traffic through a shared hostname, and they can never see yours.

---

### Activity Log (audit trail)

_See every action taken in your workspace: who paused what, who scaled what, who deleted what — and when._

Go to **Settings > Activity** (or the Activity item in the dashboard) to see a chronological audit log of every meaningful action taken in your workspace.

**What gets logged**
- Campaign / ad set / ad created, paused, resumed, deleted, edited
- Automation rule created, edited, enabled, disabled, fired
- A/B test created, deployed, archived, variant promoted
- Settings changed (brand profile, integrations, custom domains, notification prefs)
- Team members invited, removed, role changed
- API keys created or revoked
- Admin impersonation sessions (visible to workspace owners only)

**Columns**
- Timestamp (your timezone)
- Actor (team member name + email; "Automation" for rule-driven changes; "Admin" for support impersonation)
- Action (create / update / pause / resume / archive / delete)
- Target (the entity affected, with a deep link)
- Details (what changed, with before/after when applicable)

**Filters**
- By actor
- By date range
- By action type
- By target type (campaign / rule / test / settings / member)
- Free-text search

**Export**
Export filtered results as CSV. Useful for client audits, compliance review, or post-incident analysis.

**Impersonation tracking**
When ROAS.to support impersonates your workspace for a support session, every action they take is logged with "Admin" as the actor and a session ID. Workspace owners can review impersonation sessions to confirm what support touched.

**Retention**
Activity log entries are retained indefinitely. There's no auto-purge — your full history stays queryable.


## Billing & Account

Plans, payments, data export, and account management

### Trial and pricing

_How the 3-day trial works and what the Pro plan costs._

**Trial:**
Every new account gets a 72-hour (3-day) full-access trial. No card required to start.

**During your trial:**
- A countdown banner shows at the top of the dashboard
- All features work exactly as they do on Pro
- You can connect 1 Business Manager (BM) to evaluate the platform

**When the trial expires:**
- A paywall appears blocking access to platform features
- Your data is preserved — nothing is deleted
- Upgrade to continue using the platform

**Pricing:**
- **Base plan: $499/mo** — includes your first Business Manager
- **Additional BMs: $99/mo each** — billed per extra BM beyond your first, prorated to the day

What's included with the base plan:
- 1 Business Manager (your "primary" — see "Managing multiple Business Managers")
- Unlimited ad accounts within that BM
- Unlimited page tests
- Unlimited automation rules
- AI tools (with monthly credit budget)
- Team members
- All integrations

**Payment:**
Handled securely via Dodo Payments. Monthly billing, cancel anytime. Additional BM charges prorate immediately on the day you connect or disconnect — you only pay for the time each BM was connected.

---

### Managing multiple Business Managers

_How the included primary BM works, what additional BMs cost, and how to switch your primary._

Your Pro plan includes **one Business Manager free** (your "primary"). Connecting more is supported and billed at $99/mo per extra BM, prorated to the day.

**Your primary BM:**
The first BM you connect after upgrading to Pro becomes your **primary**. It's free — included in your $499/mo base plan. You'll see it labeled clearly in **Settings → Accounts**, with a banner showing which BM owns your included slot.

**Adding additional BMs:**
Click "Add Business Manager" in Settings → Accounts and connect via OAuth or your own Facebook app (BYOA). Any BM you connect alongside an existing primary lands as **additional** at $99/mo. Click **Activate** to start billing — the prorated charge appears on your card immediately, and the full monthly amount lands on your next invoice.

**Removing an additional BM:**
Click Remove on any additional BM. Billing prorates a refund the same day. You can re-add it later at any time — same per-day billing applies.

**Switching your primary BM:**
Sometimes you need to swap your free primary slot to a different BM (e.g. you started a new agency, or your old BM was lost). The flow:

1. **Remove your existing primary** in Settings → Accounts
2. **Add the new BM** — it takes the free primary slot if you're eligible

Eligibility for a free primary swap:
- **First swap is always free** — every Pro account gets one transfer with no waiting
- **30-day cooldown after each swap** — your next free transfer unlocks 30 days after the last one
- **First 30 days of Pro: extra free transfer** — covers "I picked the wrong BM at signup" mistakes

If you try to swap during cooldown, the new BM connects as additional ($99/mo) and you keep your existing primary in place. The Settings banner shows when your next free transfer unlocks.

**The fork question:**
When you're at a real choice (your previous primary is removed and a free transfer is available), you'll see a dialog asking:
- **"Make this my new free primary"** — uses your transfer, included in $499/mo
- **"Add as additional"** — $99/mo, keeps your free transfer for later

Pick whichever makes sense for your situation. You can always email support if you're not sure.

**Reconnecting a BM (token rotation, deauthorization recovery):**
Reconnecting the **same** BM is always free, no matter what — it's not a transfer. Token expired, Facebook revoked your app, you accidentally removed and re-added it: all free, every time, no rate limit.

**If your Facebook account gets banned:**
If Meta deauthorizes your primary BM and you can't restore access within 30 days, your primary slot auto-releases — your next BM connects as the new primary, free. You don't need to wait the full cooldown for ban recovery.

**Stuck or confused?**
Email **support@roas.to**. We can release your primary slot, convert a paid BM back to free, or override any of these rules for legitimate cases.

---

### Upgrading to Pro

_How to upgrade from trial to a paid subscription._

Go to **Settings > Billing** and click "Upgrade Now."

**Process:**
1. You'll be redirected to a secure Dodo Payments checkout page
2. Enter your payment information
3. After successful payment, you're redirected back to ROAS.to
4. Your plan immediately changes to "Pro"
5. The trial banner disappears

**After upgrading:**
- Your plan badge changes to "Pro" with a checkmark
- Monthly renewal at $499/mo (your first Business Manager is included — see "Managing multiple Business Managers" if you need more than one)
- Your subscription ID is shown on the billing page
- All features continue to work without interruption
- The Business Manager you connected during trial automatically becomes your free primary

**Managing your subscription:**
From the billing page, you can:
- View your current plan status
- See payment history
- Manage your subscription (cancel, update payment method) via the payment portal

---

### Exporting your data

_How to download all your account data._

Go to **Settings > Account** to export your data.

**What's included:**
The export downloads a JSON file containing:
- All campaigns and their configurations
- All page tests and variants
- Conversion data
- Settings and preferences
- Automation rules and execution history

**File format:** `roas-to-export-{your-workspace-slug}-YYYY-MM-DD.json`

**Use cases:**
- Compliance and record-keeping
- Backing up your data before making major changes
- Migration to other tools
- Auditing your account activity

---

### Deleting your account

_How to permanently delete your account and all associated data._

Go to **Settings > Account** to delete your account.

**This action is irreversible.** Deleting your account:
- Permanently removes all your data (campaigns, tests, conversions, settings)
- Cancels your Dodo Payments subscription
- Removes all team member access
- Cannot be undone

**Process:**
1. Click "Delete Account"
2. Type "DELETE" in the confirmation field
3. Click confirm

**Recommendation:** Export your data before deleting (see "Exporting your data").

After deletion, you'll be redirected to the homepage. You can create a new account later, but none of your previous data will be recoverable.