AdBeacon

Get Google Analytics 4 data for every GA4 property connected to the account — the same figures as the Custom Dashboard's GA4 tiles. `breakdown` decides what a row is: - a dimension (channel, source, device, landing_page, product, path, ...): one row per value, busiest first - `day`, `week` or `month`: one row per period, oldest first — a trend - `none`: ONE row of totals for the whole period — a scorecard Notes: - Call `list-ga4-reports` first. Columns depend on the report (traffic, landing_page, product, path) and filter fields depend on the breakdown. - GA4 reports its own numbers: there is no attribution model, window or customer type here. Do not compare GA4 figures with AdBeacon-attributed revenue as if they were the same thing. - `start_date` and `end_date` must be `YYYY-MM-DD`, at most 425 days apart. - Totals differ by grain: device, country, city, browser and new_vs_returning read city-level data and count more sessions and users than channel or none. Say which breakdown you used. - Results are paginated; read `pageInfo.hasNextPage` before assuming you have every row.

get-ga4-data

List all advertising accounts the authenticated user has access to. Returns account names that can be used with other tools. IMPORTANT: You must call this tool first and ask the user to select an account before using any data tools.

list-accounts

List all available advertising channels supported by AdBeacon with their breakdowns and available metrics.

list-channels

List the advertising channels that have creative data, and the exact vocabulary each one accepts. Call this BEFORE the first get-creative-* call in a conversation. It returns, per channel: which of the three creative tools the channel implements, its breakdowns (creative asset types), its selectable and sortable columns, the columns that exist only on the video breakdowns, its chart metrics, and its text- and metric-filter vocabularies. The channels differ from each other more than the Optimize channels do — a column or breakdown that is valid on one is frequently rejected on another — so do not carry a parameter set from one channel to the next without checking it here.

list-creative-channels

List the Google Analytics 4 reports and the exact vocabulary each one accepts. Call this BEFORE the first get-ga4-data call in a conversation. It returns, per report (traffic, landing_page, product, path): its breakdowns, the breakdowns that read it by default, its selectable columns, the fields each breakdown may filter on, and the column rows are ordered by. Also the filter operators, paging limits and the rules a request must follow.

list-ga4-reports

Meta ads compared against a previous period, per ad, with the creative thumbnail and the period-over-period changes already calculated. Use this for "which Meta ads are declining", "what changed week over week on Meta", or any Meta ad review that needs a before-and-after rather than a snapshot. Returns, for each ad: the current period (spend, cpm, ctr, impressions, clicks, reach, frequency, revenue, roas), the same nine for the previous period as `prev_*`, six ready-made change columns, `image_url` - the ad's actual creative thumbnail - and `media_type`. NOT A CREATIVE TOOL. A row is an AD, and ads carry images, videos and carousels, so an unfiltered result MIXES them. Any question with the word "image" or "video" in it belongs to `get-creative-data` at `breakdown: image` or `breakdown: video`, which groups by the creative ASSET - one image running in twenty ads is one row there, and twenty here. Do not build an "image ads" or "video ads" table from this tool: a real report did, and listed a 1m47s video as its top image ad because every number in the row was individually correct. `media_type` (image / video / carousel / unknown) is available as both a column and a filter for the cases where an AD-level answer really is wanted for one kind of creative. FIVE THINGS TO GET RIGHT, all of which produce confident wrong numbers if ignored: 1. `frequency` is the AVERAGE of Meta's own daily frequency, NOT impressions / reach. Reach is de-duplicated by Meta within a day, so summing it across days double-counts people. The same ad measures 1.47 one way and 1.28 the other. `reach` is a plain SUM for volume context, so impressions / reach will NOT reproduce `frequency`. Report the column as given; never recompute it. 2. `revenue` and `roas` are META-REPORTED, not AdBeacon-attributed. Label them "Meta Revenue" / "Meta ROAS". Never sum or table them alongside attributed revenue from get-channel-data. For attributed revenue per ad, use get-channel-data with breakdown: ad. 3. Every `*_change_pct` is a RATIO, not a percentage: 0.25 means +25%. Multiply by 100 before presenting. A null means the ad did not run in the previous period - report that as "no comparable figure", not as 0%. 4. Rows are ordered by `sort_by` and THEN capped at `limit` (default 50), so a ranking really is the account's top N under that ordering. When `truncated` is true, say the figures cover the top N rather than implying account-wide. 5. `media_type` is the ad's creative kind, classified the same way the Creative Dashboard classifies it. Unfiltered, every kind comes back together. The filter is applied BEFORE the row cap, so `media_type: image` with `limit: 5` is the account's five biggest image ads, not the image ads among its five biggest ads. State the filter you used, or that you used none. The comparison period defaults to the window immediately before the one you ask for, of the same length. Both windows come back in `windows` - state them.

get-meta-ad-performance

The account's own monthly targets from the Goal & Pacing page: Spend, Revenue, ROAS, POAS, CAC, CPC and MER goals, set for the whole account or for one channel. Use this whenever a question compares performance with a plan, budget or target: "are we on pace", "how much of the November budget is left", "did we hit our ROAS goal". It is the ONLY tenant-entered plan on this server. Platform budgets from get-channel-data are a different thing: the ad platform's current daily or lifetime setting, not what the account planned to spend in a month. Each goal returns `name`, `level` (`account` or `channel`), `channel` (null on an account-level goal), `metric`, `condition` (equals, less_than, less_than_or_equal_to, greater_than, greater_than_or_equal_to), `deviation` (the +/- percent tolerance around the value, set only when condition is equals), `cycle_start_day`, and `months`: one entry per goal month as `YYYY-MM` with its `value` and exact `period_start` / `period_end`. GOALS ARE MONTHLY. Pass start_date and end_date to keep only the goal months that window overlaps; a window that covers part of a month still returns that month's FULL monthly value, with `days_in_window` and `days_in_period` so you can say how much of it the window covers. Never pro-rate a monthly goal silently. Goals with no month in the window are left out, and an account with no goals returns an empty list rather than an error.

get-goals

Show how each order's credit was split ACROSS every channel, one row per order. This is the cross-channel view: for each order you get the date, customer email, order total, and the fraction of that order credited to meta, tiktok, pinterest, snapchat, googleAds, bingAds, chatgptAds, direct, googleSearch, bingSearch, klaviyo_email and attentive_email — plus `others` for everything unnamed (including any other email platform, e.g. Mailchimp). Use it to answer "which channels contributed to this order?" or "how much of last week's revenue did Meta actually drive per order?". Choosing between the order tools: - `get-order-attribution` (this one) — every channel's share of each order. NOT channel-scoped. - `get-order-list` — orders attributed to ONE channel. Use when the user names a channel. - `get-order-journey` — the individual touchpoints behind ONE order. Notes: - `start_date` and `end_date` must be `YYYY-MM-DD`. - For the fractional models the channel shares plus `others` sum to 1 per order. For `full_impact` each channel counts whole orders instead, so they do NOT sum to 1 and `others` is null. - `lighthouse` is NOT available here, unlike the other order tools. - `attribution_window` does NOT accept 0/lifetime. - Results are paginated; read `pagination.has_next_page` before assuming you have them all. Every page costs the same scan, so prefer a large `limit` over many pages. - Data comes from the hourly attribution summary, so orders placed in the last hour may not appear yet. This matches the Optimize screens exactly. - An account with no connected store is refused with an explicit error rather than an empty result, so an empty `orders` array always means "no orders matched", never "this account has no store connected". FOR ANY TOTAL, READ `totals`. NEVER ADD UP `orders` YOURSELF. The response carries a `totals` object holding each channel's credit, the residual and the revenue summed across the WHOLE filtered set — every matching order, not just this page. Those figures are computed in the database and are exact. Summing the rows by hand is not: a week can hold hundreds of orders, and adding them up produces confident, wrong answers. `totals` is the whole result set regardless of `page` or `limit`, so one call answers "how did my channels do" without paging at all. Page through `orders` only when you need the individual orders themselves. DO NOT VOLUNTEER A SUMMARY OF A SUBSET. When you list some orders, present the rows and stop. Do not append a count or a value total for "these N orders" — nothing in the response provides it, so you would be adding the rows up yourself, and that is exactly the arithmetic that produces confident wrong answers. A real example: asked for 25 orders under last-click, a summary was appended whose channel counts totalled 27 and whose value was $100 out. If a total for a NARROWER slice is wanted, do not compute it — re-query with filters that describe that slice (a tighter date range, a different customerType) and read `totals` again. If that is not possible, say the figure is your own count of the rows shown rather than presenting it as data.

get-order-attribution

Where the store's orders actually ship to: cities, regions or countries ranked by revenue, each split into new and returning customers. Use this for "which cities buy the most", "where are our new customers coming from", "should we run a regional campaign", "which markets are growing", or any question naming a place. This is the ONLY tool on this server that returns a geographic dimension. No channel, creative or order tool can be grouped by location. These numbers tie out, to the cent, against the City tab of the in-app New vs Returning Customers report. Do not reconcile them against any other source. `grain` decides what a row IS: `city` (the city NAME alone, so every Portland rolls into one row and a city row has no region or country column - this is what the report does), `region` (state / province), or `country`. Ask for `region` when same-named places must stay apart. Add `country` to narrow a city or region list to one market. `revenue` is GROSS store revenue - refunds NOT deducted - in the account's reporting currency, because that is what the report prints. `net_revenue` is the same orders after refunds. The new/returning revenue split and `aov` are on the gross basis and tie to `revenue`. None of it is attributed revenue: never divide it by a channel's spend, and never put it in the same table as a get-channel-data revenue figure. COUNTS ARE ORDER-GRAIN, matching the report. `customers`, `new_customers` and `returning_customers` count order rows, so new + returning = customers and a three-time buyer counts three times. Use them for anything that must tie out, including a new-vs-returning stacked bar. `distinct_customers` and its `distinct_new_customers` / `distinct_returning_customers` siblings are true distinct-shopper counts, and the latter two do NOT sum to `distinct_customers` - a shopper whose first order and a repeat both land in the window is in both. Never add those two together, and never mix them into a table built on the headline counts. Orders with no shipping address at the requested grain are excluded, so the rows do not sum to the account total. `coverage` says how much of the period the returned rows represent. When you present a top-N of places, its KPI totals are `coverage.returned_revenue` and `coverage.returned_orders` - the totals of THESE rows. `coverage.period_revenue` and `coverage.period_orders` are the WHOLE ACCOUNT including every place not listed; use them only to state coverage, never as the headline beside a top-N table. `coverage.period_net_revenue` is that same whole-account revenue after refunds. When no order in the window has a place, `places` is empty but `coverage` still carries the period figures.

get-geography-data

List the individual orders attributed to one advertising channel over a date range. Returns one row per order — order id, order date, customer email and name, and the order total both formatted and as a raw number for arithmetic. Use it to answer questions about specific purchases; use get-summary-data instead for channel totals. Notes: - `start_date` and `end_date` must be `YYYY-MM-DD`. - `attribution_window` is in days, and `0` means lifetime (no look-back limit). - By default this lists EVERY attributed order for the channel, which on a busy account is a very large result. When the user is asking about a particular campaign, ad set or ad, pass `breakdown` + `entity_id` to scope it — that is both faster and what they meant. - `search` matches the start of an order id, and also the customer email and name — but for accounts that mask customer details it silently narrows to the order id alone, so a name or email search will legitimately return nothing on those accounts. - Results are paginated; read `pagination.has_next_page` before assuming you have them all.

get-order-list

Store-wide product performance with profitability and a new-vs-returning customer split: units, orders, customers, gross and net revenue, gross margin, COGS, discounts, tax, refunds and inventory - per product, variant, SKU, category, product type or collection. Use this for "which products make us money", "what are our best sellers", "which products do new customers buy", or any catalogue, margin or inventory question. THIS IS STORE-WIDE, NOT CHANNEL-ATTRIBUTED. It counts every order however the customer arrived. `get-product-list` is scoped to ONE ad channel's attributed orders and answers a different question - the two will not tie out, and dividing this revenue by a channel's ad spend produces a ROAS that means nothing. Always say which tool a product figure came from. THE COHORT IS THE ORDER'S CUSTOMER TYPE. "New" means that order was the shopper's first ever with this store. The split has an asymmetry you must not "fix": - The ORDER counts partition exactly. `new_customer_orders` / `returning_customer_orders` are ORDER counts and sum to `orders`. - The CUSTOMER counts do NOT partition. `new_customers` / `returning_customers` are DISTINCT customers and do NOT sum to `customers` - a shopper who bought the product as a first-timer and again later is in both. That is not double counting and must not be reconciled; never add those two together. Use the ORDER counts when two numbers have to add up. `new_customer_order_share` is the acquisition signal: a high share means the product recruits, a low one means it sells to people who already shop here. GRAINS. `grain` is `product` (default), `variant`, `sku`, `category_name`, `product_type` or `collections`. At `category_name` and `product_type` a product with no value is grouped under "(none)". At `collections` a product in two collections is counted in both rows, so those rows sum to more than the catalogue, and a product in no collection is grouped under "(none)". MONEY COLUMNS: `gross_revenue` is the pre-discount, tax-exclusive LINE subtotal - it is NOT a charged order total and will not reconcile against an order-level figure from any other tool. `net_revenue` takes off the line discount and this product's pro-rata share of the order's refund, and it is the headline. `gross_margin` is a PERCENTAGE of net revenue, not an amount, and is null when net revenue is zero or negative - report null as "no margin can be calculated", never as 0%. `cost` comes from the Shopify variant cost, so margin is overstated for any variant with no cost recorded. ORDER COUNTS DO NOT ADD UP ACROSS ROWS: one order holding three products is counted once on each of those three rows. `coverage` therefore reports period totals only for items sold and revenue, which do partition, and no period order count at all. SHARES ARE NET: `revenue_share` is this row's net revenue / the period's net revenue, and `coverage.returned_net_revenue_share` is the returned rows' share of net revenue. Label both "of net revenue" - never "of gross revenue", and never print one beside a gross revenue figure as if it were that figure's share. COHORT REVENUE: each product row also carries `new_customer_revenue` / `returning_customer_revenue` (split of gross revenue), `new_customer_net_revenue` / `returning_customer_net_revenue` (split of net revenue) and `new_customer_aov` / `returning_customer_aov` (cohort revenue / cohort orders, 0 when the cohort has no orders). An order with no recorded customer type is in neither cohort, so each pair sums to at most the total. The AOVs are this product's line value per order that contained it, not a whole-basket AOV. The four revenue splits are sortable. All of this is store basis - the attribution model does not apply. Only products with at least one order come back by default. Set `include_zero_sales` to true to see unsold catalogue rows - that plus `sort_by=inventory_quantity` is the dead-stock question. Shopify stores only. Ranking is applied across the whole catalogue before the row cap, so a top-N really is the account's top N; `truncated` says whether the cap was reached. An empty result is NOT automatically "no catalogue": read `empty_result_note` - only a `coverage.period_products` of 0 means the account has no Shopify catalogue; otherwise nothing matched the window or the search.

get-product-cohort-performance

List the products sold in the orders attributed to one advertising channel over a date range. Returns one row per product variant — name, product id, SKU, units sold, order count, distinct customers, average units per order, and revenue both formatted and as a raw number for arithmetic. Use it to answer "what did this channel actually sell"; use get-order-list for the individual orders behind those totals. Columns: - `revenue` / `revenue_numeric`: basket value of orders the channel touched — the raw product basket, not a re-weighted attribution share, so it will not tie out to the channel's attributed revenue. - `attributed_revenue`: channel's attributed credit for the product — each order's credit for this channel under the chosen model/window, split across its lines by line value. Only touchpoints on the channel's connected ad accounts count, as in get-summary-data, so summed over all products it ties to the channel's AdBeacon-attributed revenue; an order touched only by another account's ads is listed with no attributed revenue. - `attributed_share`: the product's share (0–1) of the channel's attributed revenue. With `customer_type` new/old the denominator is the channel's ALL-customer attributed revenue, so the shares sum to the cohort's share of the channel, not to 1. - `allocated_spend`: estimate: channel spend split by attributed revenue share — not platform product spend (no per-product spend source exists). Uses the channel's whole spend for the date range, the same figure get-summary-data reports. Null with `customer_type` new/old: spend can't be split by customer cohort, so take allocated spend from the customer_type=all call. - There is no product ROAS: `attributed_revenue ÷ allocated_spend` is the channel's ROAS on every row, so never rank or compare products by it. - The three attribution columns are only filled under fractional models (linear, paid_linear, linear_exclude_direct, first_click, last_click); under lighthouse and full_impact they are null — see `notes`. `allocated_spend` is also null when the list is scoped with `breakdown` + `entity_id`. Notes: - `start_date` and `end_date` must be `YYYY-MM-DD`. - `attribution_window` is in days, and `0` means lifetime (no look-back limit). - There is deliberately no search parameter — filter the returned rows instead. - By default this covers EVERY attributed order for the channel. When the user is asking about a particular campaign, ad set or ad, pass `breakdown` + `entity_id` to scope it. - Results are paginated; read `pagination.has_next_page` before assuming you have them all.

get-product-list

Get store profit-and-loss figures — sales, orders, refunds, cost of goods, profit, ad spend and new versus returning customers — added together across every connected store (Shopify, WooCommerce, BigCommerce, Magento, Custom Store; not Amazon). These are the figures of a Store P&L tile on the Custom Dashboard. `breakdown`: - `none`: one row for the whole period (a scorecard) - `day`, `week` or `month`: one row per period, newest first; send sort_by "date" with sort_direction "asc" for a trend, oldest first Every response also carries `totals` for the whole period, whatever page you read. A `week` or `month` row is labelled with the start of its period, so the first label can fall before `start_date` — but only days between `start_date` and `end_date` are counted, and the rows add up exactly to `totals`. Notes: - These are store figures, not attributed to any ad channel. Spend is the connected Meta, Google, TikTok, Snapchat, Reddit, Pinterest, Bing and ChatGPT Ads accounts; Amazon Ads and organic are excluded. - `customer_type` filters orders and refunds but never spend, so CAC, NCAC, ROAS, MER and POAS then compare all spend with part of the orders. - COGS is the product cost on the order date, 0 when no cost is set, and always 0 for WooCommerce, BigCommerce and Custom Store; Magento uses the cost Magento records on the order. Transaction cost is Shopify only. - `start_date` and `end_date` must be `YYYY-MM-DD`, at most 425 days apart. - Money is in the account's reporting currency; a division by zero is null. - new_customer_revenue and returning_customer_revenue are on the GROSS basis and sum to total_sales_gross - NOT to order_total or net_revenue. Request returning_customer_revenue directly; never derive it by subtracting new_customer_revenue from order_total or net_revenue. Never mix bases in one table.

get-store-data

Rank the top creatives for one channel by a single metric — the Creative Dashboard's bar chart. Returns the top N creative assets over the whole date range (not a time series), ordered by `metric` descending, each carrying its rank. Use it for "which creatives are our best/worst by X"; use `get-creative-data` when you need many metrics per row, or more rows than a chart would show. Notes: - `metric` is restricted to the metrics the chart can actually render, and the set differs by channel — Pinterest has no `thumbstop`. Check `list-creative-channels`. - The `google` channel does not implement this tool; its dashboard has no chart. Use `get-creative-data` with sort_by there instead. - `limit` is the bar count, defaulting to 8 to match the dashboard. - The rows carry `start_date` and `end_date` because a bar has no other period marker. - Not for Reddit: call `get-creative-data` for reddit with `metric` (and optionally `limit`).

get-top-creatives

The whole-account headline for a weekly or monthly marketing report: total spend across paid AND organic, store revenue net of refunds, the order-level cost basis, orders, clicks, plus ROAS and POAS - for THREE periods in a single call. Use this for "how did the business do last week", "what is our blended ROAS", "are we profitable on ad spend", or the opening summary of any performance report. Returns `current`, `previous_period` and `last_year` side by side, with the deltas between them computed server-side. Do NOT make three calls and subtract - the `change` block here is the only set of deltas you should report, and the windows used are echoed back in `windows` so you can state exactly what was compared. By default `previous_period` is the window immediately before the current one and `last_year` is the same window 364 days earlier - 364, not 365, so a weekly report lands on the same weekdays. Override any of them with the optional date parameters. REVENUE HERE IS STORE REVENUE, NOT ATTRIBUTED REVENUE. It is net of refunds processed inside the period, plus Meta and TikTok in-platform purchase value (returned separately as `in_platform_revenue`). It will NOT equal the sum of get-blended-channel-data revenue, and it should never be divided by one channel's spend. `spend`, by contrast, IS the blended total across paid (including Klaviyo) and organic, so the ROAS reported here is a blended ROAS. `paid_spend` is the ad-platform part of it alone. `clicks` counts paid (including Klaviyo) and organic clicks. `product_cost` is net of the COGS of refunded items. `orders` INCLUDES Meta and TikTok in-platform purchases, returned separately as `in_platform_orders`. For any "store revenue" or "store orders" figure use the returned `store_revenue` (revenue - in_platform_revenue) and `store_orders` (orders - in_platform_orders), and take their change from `change` like every other metric. Never subtract them yourself. POAS = (store_revenue - product_cost - transaction_cost - shipping_cost) / paid_spend. That is store profit over ad-platform spend, the same POAS as the dashboard's Store P&L. Use the returned `poas`; do not recompute it from `spend`. ROAS is null when a period had no spend and POAS is null when it had no paid spend - report null as "no ad spend in this period", never as a ratio of zero.

get-account-rollup