---
name: set-up-cart-data-and-profit-tracking
description: >-
  Gets product-level cart data and COGS-based gross profit flowing into Google Ads so Shopping and
  PMax reports show profit per product, cost of goods sold, and average cart size instead of revenue
  alone. Reach for this when an ecommerce account wants to steer bidding by margin rather than
  revenue, when margins differ widely across the catalog, or when product-group reports show blank
  profit columns. The tag and feed work is largely human; VigilDog drives the verification loop with
  GAQL cart-data metrics. Do not use it for the base purchase tag (that is
  set-up-google-ads-conversion-tracking), for correcting values after returns
  (configure-conversion-adjustments), or for consent plumbing (configure-google-consent-mode). Once
  data is verified, hand off to set-up-value-based-bidding for profit-target bidding.
---
# Cart Data and Profit Tracking Setup

## Purpose
Wire product-level sales data (items, quantities, unit prices) and cost-of-goods-sold into the
Google Ads purchase conversion so the account can report gross profit, COGS, and cart composition
per product group. This turns Shopping and PMax reporting from a revenue view into a margin view,
which is the prerequisite for bidding toward profit instead of top-line sales.

## When to run
- An ecommerce account runs Shopping or PMax and wants profit-aware reporting or bidding.
- Product margins vary a lot across the catalog, so revenue-based ROAS hides losers.
- Product-group reports show empty gross-profit / COGS / cart-size columns.
- A migration or re-platform broke previously working cart data.

## When NOT to run
- No purchase conversion exists yet, run set-up-google-ads-conversion-tracking first.
- You need to correct conversion values after refunds/returns, configure-conversion-adjustments.
- You want new-vs-returning buyer signals on the same purchase event, set-up-new-customer-tracking.
- Conversion counts look inflated, implement-transaction-id-deduplication first; bad dedup poisons cart data too.

## Prerequisites
- Active purchase conversion action recording in Google Ads.
- Merchant Center account with a live product feed, and the Google Ads ↔ Merchant Center link in place.
- GTM container or gtag on the purchase confirmation page, plus developer access to the data layer.
- Per-unit COGS figures (exact or category-level estimates) for the catalog.

## Procedure
1. Confirm the Merchant Center link. Call `gads_run_gaql_query` against the merchant center link
   resource to check an active link exists. If none does, use `gads_link_merchant_center`, preview first (validate_only=true is the default), show the user the link that will be created,
   and commit only after explicit approval. Before this or any other Google Ads write in the
   session, consult `gads_policy_guardrail`.
2. Baseline the current state. Pull `gads_get_shopping_performance` for the last 30 days and run a
   `gads_run_gaql_query` on the shopping performance view selecting the cart-data metric family
   (gross profit, cost of goods sold, average cart size, units sold, average order value). Record
   whether these are all zero/null, that is the "before" snapshot.
3. HUMAN STEP (outside VigilDog): brief the developer to extend the purchase data-layer push with an
   items array (product id, unit price, quantity per line) plus the Merchant Center account id,
   feed country, and feed language fields. The product ids must be byte-identical to the ids the
   feed submits (watch variant/parent id conventions), an id mismatch silently breaks the join.
4. HUMAN STEP (outside VigilDog): add a cost-of-goods-sold attribute to the Merchant Center feed with
   a per-unit cost and currency for every product, re-upload, and clear any diagnostics errors in
   the Merchant Center UI. Category-level cost estimates are acceptable if exact COGS is not
   available yet, approximate margin data beats none.
5. HUMAN STEP (outside VigilDog): in GTM, enable product-level sales data on the Google Ads purchase
   conversion tag and map the items array and merchant/feed fields to data-layer variables (or add
   the equivalent parameters to the gtag snippet). Publish, then run a test purchase in GTM preview
   and confirm the parameters populate.
6. Wait 24-48 hours after the first tagged conversion, then verify arrival with VigilDog: re-run the
   step-2 GAQL query. Non-zero gross profit and cart-size values on product segments mean the join
   is working end to end.
7. Diagnose gaps mechanically with `gads_run_gaql_query`:
   - All cart metrics null → the tag is not sending item data; return to step 5.
   - Cart size populated but gross profit zero → COGS missing from the feed; return to step 4.
   - Some product ids report, others do not → partial id mismatch; list the silent ids and hand
     the list to the feed owner (step 3/4).
8. After 7 days, compute cart-data coverage: conversions carrying cart data divided by total
   purchase conversions, via `gads_run_gaql_query`. Report the percentage to the user with the
   product-level profit table from `gads_get_shopping_performance`.
9. Flag economics problems: any product whose reported gross profit is negative (COGS above selling
   price) goes in a review list for the user, that is a pricing/feed question, not a tracking bug.

## Decision rules
- Coverage ≥ 90% of purchase conversions carrying cart data after 7 days → setup is healthy;
  proceed to profit-based bidding work.
- Coverage 50-90% → usually one broken checkout path (express pay, mobile, guest); ask the user to
  test each purchase path separately before touching anything else.
- Coverage < 50% or zero → treat as not implemented; restart at step 5 debugging.
- Exact COGS unavailable → ship with category-level estimates now, refine later; do not block the
  rollout on perfect cost data.
- Cart data is worth the effort only for Shopping/PMax; a Search-only account should skip this and
  rely on standard conversion values.
- Allow a full 48 hours before declaring the implementation broken, the reporting join lags.

What the cart-data columns actually mean when reading results:
- Gross profit = attributed revenue minus feed COGS for the items sold; it inherits every feed
  error, so a suspicious profit figure is a feed question before it is a campaign question.
- Average cart size = items per attributed transaction; useful for spotting products that anchor
  large baskets even when their own margin is thin, do not exclude such products on solo margin
  alone.
- COGS column = the feed's cost values as applied to attributed sales; a zero here with non-zero
  revenue pinpoints exactly which products still lack cost data.
- Cross-product effects matter: a low-margin traffic driver that fills carts with high-margin
  attachments is profitable at the basket level; judge product groups on basket economics, not
  line-item economics.

## Common failure modes
- Data-layer product ids formatted differently from feed ids (SKU vs item_group_id): the most
  common silent failure; metrics simply stay blank. Audit ids on real products before launch.
- New products onboarded without a COGS value, so profit reporting decays over time. Ask the user
  to add COGS to their product-onboarding checklist.
- Only one checkout flow instrumented; express-pay or mobile purchases arrive without items data,
  making coverage drift down. Test every path.
- Reading reports too early and "fixing" a working setup, always respect the 24-48 h lag.
- Treating negative-margin products as tracking errors; they are usually real and belong in a
  pricing conversation.
- Feed COGS entered in the wrong currency or per-case instead of per-unit, producing plausible
  but wrong margins that nobody questions for months, spot-check a handful of known products
  after the first data lands.
- Refunds never flowing back, so reported gross profit drifts optimistic over time, pair this
  setup with configure-conversion-adjustments from the start.

## Related skills
- Run before: set-up-google-ads-conversion-tracking, configure-google-consent-mode,
  implement-transaction-id-deduplication.
- Run after: set-up-value-based-bidding (profit targets), configure-conversion-adjustments
  (returns restatement), set-up-performance-based-shopping-segmentation.