` | Section title. | `New Section` | | `--position top\|bottom` | Where to insert among non-pinned sections. | `bottom` | | `--after <sectionId>` | Insert immediately after this section (overrides `--position`). | | ### section rename / clone / delete ```bash theme={null} upstack dashboard view section rename 5f1e6a4f-... <section-id> --title "Renamed" upstack dashboard view section clone 5f1e6a4f-... <section-id> upstack dashboard view section delete 5f1e6a4f-... <section-id> ``` `clone` deep-copies the section's widgets with fresh ids and appends the new section directly after the source. `delete` migrates any widgets from the deleted section into the first remaining non-pinned section so widgets aren't lost. The Pinned section can't be renamed, cloned, or deleted directly — it's managed via [`pin`/`unpin`](#pins). ### section reorder Move a non-pinned section to a 0-based position among the other non-pinned sections. ```bash theme={null} upstack dashboard view section reorder 5f1e6a4f-... <section-id> --to 0 ``` ### section collapse / expand / hide / unhide Toggle the display state of a section. ```bash theme={null} upstack dashboard view section collapse 5f1e6a4f-... <section-id> upstack dashboard view section expand 5f1e6a4f-... <section-id> upstack dashboard view section hide 5f1e6a4f-... <section-id> upstack dashboard view section unhide 5f1e6a4f-... <section-id> ``` `collapse` keeps the header but hides the section's widgets. `hide` removes the entire section from rendering (config is preserved). ### section layout Set the section's layout mode. Accepted values: `auto`, `1_column`, `2_columns`, `3_columns`, `4_columns` (matches the backend enum exactly; the CLI lowercases input so capitalization in your shell is fine). ```bash theme={null} upstack dashboard view section layout 5f1e6a4f-... <section-id> --mode auto upstack dashboard view section layout 5f1e6a4f-... <section-id> --mode 2_columns ``` ### section density / pacing Per-section overrides for density (`compact` or `normal`) and pacing. Pass `inherit` (density) or `--inherit` (pacing) to clear the override and fall back to view-level `defaultSettings`. ```bash theme={null} upstack dashboard view section density 5f1e6a4f-... <section-id> --density compact upstack dashboard view section density 5f1e6a4f-... <section-id> --density inherit upstack dashboard view section pacing 5f1e6a4f-... <section-id> --enabled upstack dashboard view section pacing 5f1e6a4f-... <section-id> --disabled upstack dashboard view section pacing 5f1e6a4f-... <section-id> --inherit ``` ### section move-widget Move a widget from its current section into another non-pinned section. Use [`pin`/`unpin`](#pins) instead to move widgets in and out of the Pinned section. ```bash theme={null} upstack dashboard view section move-widget 5f1e6a4f-... <widget-id> --to <target-section-id> ``` ### section migrate Legacy views created before sections were introduced have a flat `configuration.widgets` array and no `configuration.sections`. Run `migrate` to wrap those widgets in a single `Main` section so the CLI's other section commands can operate on them. ```bash theme={null} upstack dashboard view section migrate 5f1e6a4f-... ``` Safe to call on views that already have sections (no-op). ## Pins Pinning copies a widget into a dedicated **Pinned** section that always renders first in the view (it has `ordinal: -1` and `sectionType: "PINNED"`). The Pinned section is created on the first `pin` and removed when its last widget is unpinned — you never create or delete it yourself. ```bash theme={null} # Pin: creates a fresh copy in the Pinned section with a new widget id. # The copy carries `sourceWidgetId` linking it back to the original. upstack dashboard view pin 5f1e6a4f-... <widget-id> # Unpin: accepts either the pinned copy's id, or the original widget's id. # The Pinned section is removed once its last widget is unpinned. upstack dashboard view unpin 5f1e6a4f-... <widget-id> ``` Pinning the same widget twice is rejected — call `unpin` first if you want to re-pin a modified original. # upstack dimensions Source: https://docs.upstackdata.com/cli/dimensions List the dimensions available for grouping and filtering queries. Bundled with the CLI — no network call. List the dimensions available for grouping and filtering queries. Bundled with the CLI as static data — no network call. ## Usage ```bash theme={null} upstack dimensions ``` ## Flags | Flag | Description | | ------------------- | --------------------------------------------------------------------------------------------------- | | `--search <term>` | Filter by keyword (matches the dimension key). | | `--category <name>` | Filter by category (e.g. `device`, `page`, `geo`, `traffic`, `ads`, `ecommerce`, `emq`, `session`). | | `--categories` | Print category names + counts only. | ## Examples ```bash theme={null} upstack dimensions --search utm upstack dimensions --category traffic upstack dimensions --categories ``` See [Measures & Dimensions](/data-dictionary/measures-and-dimensions) for full descriptions and example values. # upstack filters Source: https://docs.upstackdata.com/cli/filters List the filter-fields catalog from the command line. Find canonical filter field ids, value types, operators, and applicable contexts before constructing a --filter. List the catalog of filter fields available across every query endpoint. Each entry declares its operators, value type, and the contexts it applies in. Useful for finding canonical filter field ids before constructing a [query](/cli/query), [attribution query](/cli/query-attribution), [cohort analysis](/cli/query-cohort), or [channel-details listing](/cli/query-channel-details). Wraps `GET /api/filters` — see the [API reference](/api-reference/overview). ## Usage ```bash theme={null} upstack filters ``` The endpoint takes no parameters — the full catalog is returned in one call. Results are cached locally for 1 hour; pass `--no-cache` to refetch. ## Flags | Flag | Description | | ----------------- | ------------------------------------------------------------------------------------- | | `--search <term>` | Filter results by keyword (matches `field` and `label`). | | `--detail` | Include label, description, value type, supported operators, and applicable contexts. | | `--operators` | Show supported operators inline next to each field. | | `--json` | Print the raw response as JSON (one object per field). | | `--no-cache` | Bypass the local 1-hour cache and refetch. | ## Examples ```bash theme={null} upstack filters upstack filters --search utm upstack filters --detail upstack filters --operators upstack filters --json | jq '.[] | select(.applicableContexts | index("attribution"))' ``` ## Narrowing by endpoint context Every entry carries an `applicableContexts` array listing which endpoints it applies to (`query_measures`, `cohort_analysis`, `products_report`, `attribution`, `channel_details`, `emq_analytics`). Use `--detail` to see them inline, or `--json` to narrow with `jq`: ```bash theme={null} # Fields valid on POST /api/query-channel-details upstack filters --json | jq '.[] | select(.applicableContexts | index("channel_details"))' ``` # upstack history Source: https://docs.upstackdata.com/cli/history Inspect or re-run previously executed queries. Every query run is logged locally. Every query run is logged locally to `~/.upstack_history/`. The CLI doesn't send history anywhere — it's purely a convenience for you. ## Usage ```bash theme={null} upstack history # last 20 entries upstack history --show <id> # inspect a single entry upstack history --rerun <id> # re-run a previous query upstack history --clear # delete all entries ``` ## Flags | Flag | Description | | -------------- | ----------------------------------------------------------------------------------------------------- | | `--show <id>` | Print the full parameters and result for one history entry. | | `--rerun <id>` | Re-run a previous query with the same parameters. Useful for "what did yesterday look like, exactly?" | | `--clear` | Delete all history entries. No confirmation. | | `--limit <n>` | Number of recent entries to list. Default `20`. | # Install the Upstack CLI Source: https://docs.upstackdata.com/cli/install Install the upstack CLI and configure it with an API key and pixel id. The `upstack` CLI is a thin wrapper around the [Upstack API](/api-reference/overview). It handles authentication, profile management, and a few ergonomics like measure-title resolution that the raw API leaves to the caller. The CLI is designed to be both a human tool and a target for AI agents. See [AI agent workflow](/cli/ai-agent-workflow) for the intended Claude-in-your-terminal use case. ## Install ```bash theme={null} npm install -g @upstackdata/upstack-cli ``` ## Configure ```bash theme={null} upstack init ``` You'll be prompted for: * **API Key** — your Upstack key (starts with `upstack_`). Mint at **Settings → API Keys** in the dashboard. * **Pixel ID** — the pixel uuid the key is scoped to. Credentials live in `~/.upstackrc` with file mode `0600`. ## Verify ```bash theme={null} upstack whoami ``` Prints the active profile, pixel id, and masked API key. If you see your pixel id, you're set — try [`upstack measures`](/cli/measures) next. ## Multiple profiles For additional environments or pixels: ```bash theme={null} upstack init --profile staging upstack init --profile client-b ``` Then pass `--profile <name>` on any command. See [Profiles](/cli/profiles) for the full reference. # upstack measures Source: https://docs.upstackdata.com/cli/measures List the measures catalog from the command line. Find canonical measure ids before building a query or dashboard. List the measures available to your pixel. Useful for finding canonical measure ids before constructing a [query](/cli/query) or [building a dashboard](/cli/dashboard-view#build). Wraps `GET /api/measures` — see the [API reference](/api-reference/overview). ## Usage ```bash theme={null} upstack measures ``` Results are cached locally for 1 hour. Pass `--no-cache` to refetch. ## Flags | Flag | Description | | ------------------- | ------------------------------------------------------------------------------- | | `--search <term>` | Filter by keyword (matches `key`, `title`, and `shortTitle`). | | `--category <name>` | Filter by category (e.g. `Core`). | | `--categories` | Print category names + counts only (no individual measures). | | `--detail` | Include title, description, formula, category, and value type for each measure. | | `--no-cache` | Bypass the local 1-hour cache and refetch. | ## Examples ```bash theme={null} upstack measures --search "new customer roas" upstack measures --category Core upstack measures --categories upstack measures --detail --search mer ``` # upstack products Source: https://docs.upstackdata.com/cli/products Browse products and manage per-variant costs — handling fee + COGS history — from the CLI. Browse products + variants in the configured catalog and manage per-variant cost data. Wraps the `/api/products*` endpoints — see the [API reference](/api-reference/overview) under the **Products** group for full request / response shapes. Mutations fire the same per-order COGS recalculation as the web UI. ## Subcommands | Subcommand | Wraps | | --------------------------------------- | ----------------------------------------------------------- | | [`search`](#search) | `GET /api/products/search` | | [`cost`](#cost) | `GET /api/products/{productId}/{variantId}/cost` | | [`handling-fee set`](#handling-fee-set) | `PUT /api/products/{productId}/{variantId}/handling-fee` | | [`cogs add`](#cogs-add) | `POST /api/products/{productId}/{variantId}/cogs` | | [`cogs update`](#cogs-update) | `PUT /api/products/{productId}/{variantId}/cogs/{cogId}` | | [`cogs delete`](#cogs-delete) | `DELETE /api/products/{productId}/{variantId}/cogs/{cogId}` | ## search Search products by title / SKU / variant. Cursor-paginated. ```bash theme={null} upstack products search -q "shirt" upstack products search -q "shirt" --page-size 50 upstack products search --cursor "<nextCursor from previous response>" ``` `--page-size` accepts 1–100 (default 20). Pass the `nextCursor` from the response into `--cursor` to page. **Required scope:** `costs:read`. ## cost Show the resolved cost breakdown for a single variant — the per-unit effective cost, handling fee, and which configuration tier supplied it (per-variant COG line, global override, or default fallback). ```bash theme={null} upstack products cost --product-id prd_123 --variant-id var_456 ``` **Required scope:** `costs:read`. ## handling-fee set Set the per-variant handling fee. Must be `>= 0`. ```bash theme={null} upstack products handling-fee set --product-id prd_123 --variant-id var_456 --fee 2 upstack products handling-fee set --product-id prd_123 --variant-id var_456 --fee 0 --yes ``` **Required scope:** `costs:write`. ## cogs add Append a new COG line to a variant's manual cost history. The server assigns a ULID for the new line. ```bash theme={null} upstack products cogs add \ --product-id prd_123 --variant-id var_456 \ --cost 5 --start 2026-01-01 \ --description "Q1 batch" upstack products cogs add \ --product-id prd_123 --variant-id var_456 \ --cost 6 --start 2026-04-01 --end 2026-06-30 ``` `--end` is optional — omit for an open-ended interval. **Required scope:** `costs:write`. ## cogs update Update an existing COG line by its server-assigned ID. Pass any combination of `--cost`, `--start`, `--end`, `--description`. Use `--end null` to clear an end date (make the line open-ended). ```bash theme={null} upstack products cogs update \ --product-id prd_123 --variant-id var_456 --cog-id cog_abc \ --cost 7 upstack products cogs update \ --product-id prd_123 --variant-id var_456 --cog-id cog_abc \ --end null ``` **Required scope:** `costs:write`. ## cogs delete Delete a COG line by its ID. The CLI prompts for confirmation; `--yes` (or `-y`) skips it. ```bash theme={null} upstack products cogs delete \ --product-id prd_123 --variant-id var_456 --cog-id cog_abc ``` **Required scope:** `costs:write`. # Profiles Source: https://docs.upstackdata.com/cli/profiles Switch between API keys, pixels, and environments using named profiles. Profiles let you keep multiple `(API key, pixel id)` configurations side-by-side — e.g. one for production and one for staging, or one per client. ## Create a profile ```bash theme={null} upstack init --profile staging upstack init --profile client-b ``` ## Use a profile Pass `--profile <name>` on any command. Without `--profile`, the `default` profile is used. ```bash theme={null} upstack --profile staging query --measures revenue \ --date-start 2026-04-01 --date-end 2026-04-30 upstack whoami --profile staging ``` ## List profiles ```bash theme={null} upstack profiles ``` Prints all configured profile names. ## Remove a profile ```bash theme={null} upstack logout --profile staging ``` Removes credentials for the named profile from `~/.upstackrc`. If it was the last profile, the file is deleted. ## Storage All profiles live in `~/.upstackrc` (mode `0600`) under a `profiles` map: ```json theme={null} { "profiles": { "default": { "baseUrl": "...", "apiKey": "upstack_...", "pixelId": "..." }, "staging": { "baseUrl": "...", "apiKey": "upstack_...", "pixelId": "..." } } } ``` # upstack query Source: https://docs.upstackdata.com/cli/query Run a measures-and-dimensions query from the command line. Wraps POST /api/query. Run a measures-and-dimensions query against your event stream. Wraps `POST /api/query` — see the [API reference](/api-reference/overview). ## Usage ```bash theme={null} upstack query \ --measures orders.gross_revenue,tracked.purchases \ --dimensions utm_source \ --date-start 2026-04-01 \ --date-end 2026-04-30 ``` ## Required flags | Flag | Description | | ----------------------------------------------------- | --------------------------------------------------------------------------------- | | `--measures <m1,m2,...>` | Comma-separated canonical measure ids (see [`upstack measures`](/cli/measures)). | | `--granularity <g>` | `none`, `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter`, or `year`. | | `--date-start <YYYY-MM-DD>` `--date-end <YYYY-MM-DD>` | Date range. | ## Optional flags | Flag | Description | Default | | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------- | | `--dimensions <d1,d2,...>` | Comma-separated dimension ids. Max 5. | | | `--filter <json>` | Canonical [Filter](/cli/filters) as JSON. See the [Filters](#filters) section below for the shape. | | | `--compare-start <YYYY-MM-DD>` `--compare-end <YYYY-MM-DD>` | Optional comparison period. Must not overlap the primary date range. | | | `--timezone <tz>` | IANA timezone (e.g. `America/New_York`). | `UTC` | ## Shared flags All query commands ([`query`](/cli/query), [`query-attribution`](/cli/query-attribution), [`query-cohort`](/cli/query-cohort)) support these: | Flag | Description | Default | | -------------------- | ----------------------------------------------------------------------- | ------- | | `-i, --interactive` | Build the query step-by-step with prompts. | | | `--output <format>` | `json`, `table`, or `csv`. | `json` | | `--file <path>` | Write output to a file instead of stdout. | | | `--from-file <path>` | Load query parameters from a JSON file. CLI flags override file values. | | ## Examples ```bash theme={null} # Gross revenue by day, last 30 days upstack query --measures orders.gross_revenue --granularity day \ --date-start 2026-04-01 --date-end 2026-04-30 # CSV output, broken down by UTM source upstack query --measures orders.gross_revenue,tracked.purchases \ --dimensions utm_source --granularity day \ --date-start 2026-04-01 --date-end 2026-04-30 \ --output csv --file ./april-by-source.csv # Scope to web/POS orders for new customers via canonical filter upstack query --measures orders.gross_revenue --granularity day \ --date-start 2026-04-01 --date-end 2026-04-30 \ --filter '{"and":[{"field":"orders.source_name","op":"in","value":["web","pos"]},{"field":"orders.customer_type","op":"equals","value":"new_customer"}]}' # Interactive upstack query -i ``` ## Filters `--filter` takes a canonical Filter JSON object. The shape is a recursive `{ and | or | not }` group tree with leaves of the form `{ field, op, value }`: ```json theme={null} { "and": [ { "field": "orders.source_name", "op": "in", "value": ["web", "pos"] }, { "field": "orders.customer_type", "op": "equals", "value": "new_customer" } ] } ``` Field ids are namespaced (`orders.*`, `channel.*`, `attribution.*`, `emq.*`) and each one is only valid in certain contexts. Run [`upstack filters --detail`](/cli/filters) to list every field with its operators and applicable contexts before constructing a filter. ## Save a query for reuse ```bash theme={null} upstack saved create morning-report --command query --from-file ./params.json upstack saved run morning-report ``` See [`upstack saved`](/cli/saved-queries) for the full reference. # upstack query-attribution Source: https://docs.upstackdata.com/cli/query-attribution Run an attribution query from the command line. Wraps POST /api/query-attribution. Run an attribution query. Wraps `POST /api/query-attribution` — see the [API reference](/api-reference/overview). ## Usage ```bash theme={null} upstack query-attribution \ --dimension utm_source \ --model first_click \ --window 30 \ --date-start 2026-04-01 \ --date-end 2026-04-30 ``` ## Required flags | Flag | Description | | ----------------------------------------------------- | ------------------------------------------------------------------------------ | | `--dimension <d>` | Dimension to attribute by (e.g. `utm_source`, `utm_campaign`). | | `--model <m>` | `first_click`, `last_click`, or `any_click`. | | `--window <days>` | Attribution window. One of `1`, `7`, `14`, `30`, `60`, `90`, `-1` (unlimited). | | `--date-start <YYYY-MM-DD>` `--date-end <YYYY-MM-DD>` | Date range. | ## Optional flags | Flag | Description | Default | | --------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------- | | `--filter <json>` | Canonical [Filter](/cli/query#filters) as JSON. `attribution.utm_*` fields and `orders.*` fields apply here. | | | `--timezone <tz>` | IANA timezone. | `UTC` | | `--value-source <s>` | `orders` or `events`. | `orders` | | `--conversion-event <name>` | Required when `--value-source=events`. | `purchase` | See [`upstack query`](/cli/query#shared-flags) for the shared output / interactive / from-file flags. ## Examples ```bash theme={null} # First-click attribution by UTM source, last 30 days upstack query-attribution \ --dimension utm_source --model first_click --window 30 \ --date-start 2026-04-01 --date-end 2026-04-30 # Last-click, unlimited window, event-based valuation upstack query-attribution \ --dimension utm_campaign --model last_click --window -1 \ --value-source events --conversion-event signup_completed \ --date-start 2026-04-01 --date-end 2026-04-30 # Scope to one UTM source via canonical filter upstack query-attribution \ --dimension utm_campaign --model last_click --window 30 \ --date-start 2026-04-01 --date-end 2026-04-30 \ --filter '{"and":[{"field":"attribution.utm_source","op":"equals","value":"google"}]}' # Interactive upstack query-attribution -i ``` Run [`upstack filters --detail`](/cli/filters) to see every field valid in the `attribution` context with its operators. # upstack query-channel-details Source: https://docs.upstackdata.com/cli/query-channel-details List ad accounts, campaigns, ad sets, or ads with optional metrics from the command line. Wraps POST /api/query-channel-details. List ad accounts, campaigns, ad sets, or ads — with optional metric aggregation — from the ads-platform integrations connected to your pixel. Wraps `POST /api/query-channel-details` — see the [API reference](/api-reference/overview). The **grain** is controlled by `--dimensions`: * omit it for **account grain** (the default; one row per ad account across every connected platform — Facebook, Google, TikTok), * pass exactly one of `campaign`, `adset`, or `ad` for that grain. When `--date-start` / `--date-end` are omitted, the response is an entity-only listing (no metric aggregation). To scope by ad platform, use a canonical filter on `channel.resource_source` (not a dimension). ## Usage ```bash theme={null} upstack query-channel-details --granularity day ``` ## Required flags | Flag | Description | | ------------------- | ------------------------------------------ | | `--granularity <g>` | `hour`, `day`, `week`, `month`, or `year`. | ## Optional flags | Flag | Description | Default | | ----------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------- | | `--dimensions <grain>` | `campaign`, `adset`, or `ad`. Omit for account grain. | (account) | | `--date-start <YYYY-MM-DD>` `--date-end <YYYY-MM-DD>` | Date range. Required together with `--measures` (entity-list-only when absent). | | | `--measures <m1,m2,...>` | Comma-separated measure ids (e.g. `channel.spend`, `channel.impressions`, `meta.cpm`). | | | `--filter <json>` | Canonical [Filter](/cli/filters) as JSON. | | | `--timezone <tz>` | IANA timezone. | `UTC` | | `--limit <n>` | Max rows returned (1–500). | `50` | | `--offset <n>` | Skip the first N rows. | `0` | | `--sort-by <field>` | One of `sourceUpdatedAt`, `sourceCreatedAt`, `resourceName`. | `sourceUpdatedAt` | | `--sort-direction <dir>` | `asc` or `desc` (case-insensitive). | `desc` | See [`upstack query`](/cli/query#shared-flags) for the shared output / from-file flags. ## Examples ```bash theme={null} # Top 50 ad accounts across all connected platforms (listing-only) upstack query-channel-details --granularity day # Campaigns with spend + impressions for April upstack query-channel-details \ --dimensions campaign \ --granularity day \ --date-start 2026-04-01 --date-end 2026-04-30 \ --measures channel.spend,channel.impressions # Scope to one Facebook ad account via canonical filter upstack query-channel-details \ --dimensions campaign --granularity day \ --filter '{"and":[{"field":"channel.account_id","op":"equals","value":"<account_id>"}]}' # Drill from a specific campaign down to its ad sets upstack query-channel-details \ --dimensions adset --granularity day \ --filter '{"and":[{"field":"channel.campaign_id","op":"equals","value":"<campaign_id>"}]}' ``` ## See also * [`upstack filters`](/cli/filters) — discover valid filter fields, operators, and applicable contexts (every `channel.*` field is valid here). * [`upstack measures`](/cli/measures) — list measure ids available across all query endpoints. # upstack query-cohort Source: https://docs.upstackdata.com/cli/query-cohort Run a cohort analysis from the command line. Wraps POST /api/query-cohort-analysis. Run a cohort analysis — cohort an audience by acquisition period and analyze retention or LTV over time. Wraps `POST /api/query-cohort-analysis` — see the [API reference](/api-reference/overview). ## Usage ```bash theme={null} upstack query-cohort \ --measures orders.ltv_cohort_gross_revenue \ --granularity week \ --date-start 2026-01-01 \ --date-end 2026-04-30 ``` ## Required flags | Flag | Description | | ----------------------------------------------------- | ---------------------------------------- | | `--measures <m1,m2,...>` | One or more cohort-specific measure ids. | | `--granularity <g>` | `week`, `month`, or `year`. | | `--date-start <YYYY-MM-DD>` `--date-end <YYYY-MM-DD>` | Date range. | ## Cohort-only measures This endpoint only accepts these measure ids: | Measure id | What it computes | | --------------------------------- | ------------------------------------- | | `orders.ltv_cohort_gross_revenue` | Cohorted gross revenue over time. | | `orders.ltv_cohort_net_revenue` | Cohorted net revenue (after refunds). | | `orders.customers_cohort` | Customer count per cohort. | | `orders.avg_order_value_cohort` | Cohort AOV. | | `orders.cohort_retention_percent` | Retention rate per cohort. | | `orders.cohort_cm1` / `cm2` | Cohort contribution margins. | ## Optional flags | Flag | Description | Default | | ----------------- | ---------------------------------------------------------------------------------------- | ------- | | `--filter <json>` | Canonical [Filter](/cli/query#filters) as JSON. `orders.*` fields apply in this context. | | | `--timezone <tz>` | IANA timezone. | `UTC` | See [`upstack query`](/cli/query#shared-flags) for the shared output / interactive / from-file flags. ## Examples ```bash theme={null} # Weekly LTV cohort upstack query-cohort \ --measures orders.ltv_cohort_gross_revenue,orders.cohort_retention_percent \ --granularity week \ --date-start 2026-01-01 --date-end 2026-04-30 # Interactive upstack query-cohort -i ``` # upstack saved Source: https://docs.upstackdata.com/cli/saved-queries Cache query parameters locally for reuse. Run, list, inspect, and delete saved queries. Cache query parameters locally for reuse. Saved queries live in `~/.upstack_saved/`, one JSON file per query. ## Subcommands ### `create <name>` ```bash theme={null} upstack saved create morning-report --command query --from-file ./params.json ``` | Flag | Description | | ---------------------- | --------------------------------------------------------------------------------------- | | `--command <c>` | Required. One of `query`, `query-attribution`, `query-cohort`, `query-channel-details`. | | `--from-file <path>` | JSON file with the query parameters. | | `--description <text>` | Optional description for the saved query. | You can also pass query parameters inline as flags (e.g. `--measures orders.gross_revenue`, `--date-start 2026-04-01`, `--filter '{"and":[...]}'`) — they're merged with the file values; flags override file values. Run [`upstack filters --detail`](/cli/filters) to discover valid filter fields before constructing a `--filter` value. ### `list` ```bash theme={null} upstack saved list ``` ### `show <name>` Inspect a saved query without running it. ```bash theme={null} upstack saved show morning-report ``` ### `run <name>` Re-run a saved query. ```bash theme={null} upstack saved run morning-report upstack saved run morning-report --output csv --file ./today.csv # override output on the fly ``` ### `delete <name>` ```bash theme={null} upstack saved delete morning-report ``` # How Attribution Models Measure Marketing Performance Source: https://docs.upstackdata.com/concepts/attribution-and-reporting Compare attribution models in Upstack Analytics — first-touch, last-touch, and multi-touch — and see how each assigns conversion credit across marketing channels for accurate ROAS reporting. Attribution is the practice of determining which marketing touchpoints deserve credit for a conversion — and by how much. <Tip> Merchants using Upstack Analytics report finding 15–30% of their ad spend allocated to channels that appear profitable in-platform but underperform when measured with independent multi-touch attribution. </Tip> ## Why It Matters Every ad platform marks itself as the hero. Meta claims the sale. Google claims the same sale. Klaviyo takes credit too. When you add up each platform's reported revenue, the total exceeds your actual revenue by 2–3x. This is the double-counting problem — and it makes budget allocation guesswork. The root cause is that ad platforms use self-attributed, last-click models scoped to their own ecosystem. They can't see the full customer journey, so they assign full credit to their own touchpoint. A shopper who clicked a Meta ad on Monday, a Google ad on Wednesday, and a Klaviyo email on Friday appears as three separate conversions across three dashboards. Independent attribution — measured from your own first-party data — eliminates double-counting. When you own the data pipeline from click to purchase, you can apply consistent models across every channel and allocate credit based on the actual customer journey, not each platform's self-serving view. ## How It Works Upstack Analytics operates at the **Understand** stage of the data pipeline. It queries the identity-resolved, enriched event stream stored in your analytics warehouse to build a unified view of each customer's journey. **Attribution models** determine how conversion credit is distributed: * **First-touch** — 100% credit goes to the touchpoint that originally acquired the customer. Useful for measuring top-of-funnel acquisition channels. * **Last-touch** — 100% credit goes to the final touchpoint before conversion. Mirrors how most ad platforms report by default. * **Linear (multi-touch)** — Credit is split equally across all touchpoints in the journey. Surfaces mid-funnel contributors that single-touch models ignore. * **Time-decay (multi-touch)** — Touchpoints closer to conversion receive more credit. Balances recency with full journey visibility. **Lookback windows** control how far back Upstack searches for qualifying touchpoints. A 7-day window attributes purchases only to clicks within the past week. A 28-day window captures longer consideration cycles common in higher-AOV stores. **Channel credit** aggregates touchpoint-level attribution up to the channel level (Meta, Google, Klaviyo, organic, direct) so you can compare true ROAS and CPA across your entire marketing mix in a single view. ## Key Terms | Term | Definition | | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | | **Attribution model** | A rule set that determines how conversion credit is divided among marketing touchpoints. | | **First-touch attribution** | Assigns all credit to the first interaction in the customer journey. | | **Last-touch attribution** | Assigns all credit to the final interaction before conversion. | | **Multi-touch attribution (MTA)** | Distributes credit across multiple touchpoints based on a weighting rule (linear, time-decay, position-based). | | **Lookback window** | The time period within which touchpoints are eligible for attribution credit. | | **ROAS (Return on Ad Spend)** | Revenue generated per dollar of ad spend — the primary efficiency metric for paid channels. | <CardGroup> <Card title="Analytics Dashboard Guide" icon="chart-line" href="/analytics/query-guide"> Walk through the Upstack Analytics dashboard and its key reports. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> Learn how Upstack ID builds the unified customer journey that attribution depends on. </Card> </CardGroup> # How Conversion API Forwarding Improves Ad Platform Signal Quality Source: https://docs.upstackdata.com/concepts/conversion-api-forwarding Forward conversion events to Meta CAPI, TikTok, Google Ads, and other ad platforms via server-to-server delivery with strong match keys — improving EMQ scores and Smart Bidding signal. Conversion API forwarding sends your store's conversion events directly from Upstack's servers to ad platform servers — bypassing the browser entirely and delivering the identity signals that algorithms need to optimize. <Tip> Merchants forwarding through Upstack Signal consistently achieve Meta Event Match Quality (EMQ) scores of 8.0+ across all standard events, compared to the 3–5 range typical of browser pixels alone. </Tip> ## Why It Matters Ad platforms like Meta and TikTok have shifted to server-side conversion APIs as the primary signal source for their bidding algorithms. Meta's Conversions API (CAPI), TikTok's Events API, and similar endpoints now carry more weight than browser pixels in auction optimization and measurement. But sending events to these APIs is only half the problem. What matters is **signal quality** — how well each event can be matched back to a user on the ad platform. Meta quantifies this as Event Match Quality (EMQ), a 1–10 score reflecting how many match keys (hashed email, phone, IP, user agent, click ID) are present on each event. A PageView with only IP and user agent might score a 3. A Purchase with hashed email, phone, and `fbclid` scores a 9. Low EMQ means the platform can't attribute conversions to ad clicks, so your reported ROAS drops, your Custom Audiences shrink, and the algorithm loses the feedback loop it needs to find more buyers. Upstack Signal solves this by combining identity-resolved events with a full set of match keys before delivery. ## How It Works Upstack Signal operates at the **Activate** stage of the data pipeline. After events have been captured (Upstack Pixel), resolved (Upstack ID), and enriched (Upstack Enrichment), Signal formats and delivers them to each configured destination. The forwarding process follows three steps: 1. **Match key assembly** — Upstack attaches every available identifier to the event: hashed email (`em`), hashed phone (`ph`), first-party click IDs (`fbclid`, `ttclid`), IP address, user agent, and external ID. Identity resolution ensures these fields are populated even for events that were originally anonymous. 2. **Schema transformation** — Each destination has its own event schema. Upstack Signal maps your canonical events to the exact format each API expects — `Purchase` becomes a Meta `Purchase` event with `value`, `currency`, and `content_ids` in the right structure. 3. **Reliable delivery** — Events are queued via SQS with automatic retry and dead-letter handling. If Meta's API returns a transient error, the event is retried with exponential backoff. Permanent failures are logged for troubleshooting without data loss. Delivery is server-to-server. No browser tag, no JavaScript, no ad blocker risk. ## Key Terms | Term | Definition | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------- | | **Conversion API (CAPI)** | A server-to-server interface for sending conversion events to an ad platform (e.g., Meta Conversions API). | | **Event Match Quality (EMQ)** | Meta's 1–10 score reflecting how well an event's identity signals match a Facebook user profile. | | **Match keys** | Hashed identity fields (email, phone, address) attached to each event to enable ad platform matching. | | **Click ID** | A platform-specific parameter (`fbclid`, `ttclid`, `gclid`) appended to ad URLs that links a click to a conversion. | | **Dead-letter queue** | A queue where events that fail delivery after all retries are stored for inspection. | <CardGroup> <Card title="Set Up Meta CAPI" icon="meta" href="/get-started/connect-a-destination"> Connect Upstack Signal to Meta's Conversions API step by step. </Card> <Card title="Destinations Overview" icon="bullseye-arrow" href="/destinations/overview"> See all supported forwarding destinations and their configuration options. </Card> </CardGroup> # How Data Enrichment Strengthens Events and Customer Profiles Source: https://docs.upstackdata.com/concepts/data-enrichment Enrich tracking events with customer metadata, identity match keys, and contextual data to improve destination match quality, attribution accuracy, and downstream analytics. Data enrichment appends additional context — customer metadata, geographic data, and behavioral attributes — to raw events and identity profiles before they reach destinations or your analytics warehouse. <Tip> Enriched events carry more match keys, which directly raises Event Match Quality (EMQ) scores on platforms like Meta — turning a 5 into an 8 without changing your tracking setup. </Tip> ## Why It Matters A raw event captured at the edge contains the basics: URL, timestamp, IP address, user agent, and whatever identifiers the visitor volunteered. That's enough to record that *something* happened, but it's not enough for downstream systems to do their best work. Conversion APIs score events based on match key completeness. An `AddToCart` event with only an IP address and user agent will match poorly on Meta. The same event enriched with hashed email, phone number, city, and zip code matches at a significantly higher rate — improving both reported conversions and algorithm optimization. Enrichment also improves your own analytics. Customer lifetime value calculations become more accurate when events carry purchase history and order frequency. Segmentation becomes more granular when profiles include geographic and behavioral attributes. Every system downstream of enrichment — forwarding, attribution, reporting — benefits from richer input data. ## How It Works Upstack Enrichment operates at the **Enrich** stage of the data pipeline, after identity resolution and before forwarding or warehouse storage. Enrichment draws from three sources: * **Identity graph** — Once Upstack ID resolves a visitor, Enrichment pulls all known identifiers associated with that profile (email, phone, address) and attaches them to the current event. An anonymous `PageView` gains match keys from a previous checkout on another device. * **Shopify customer data** — Order history, customer tags, total spend, and order count are synced from Shopify and attached to resolved profiles. These fields feed both forwarding destinations (as customer parameters) and analytics (for cohort and LTV calculations). * **Event context** — Geographic data derived from IP (city, region, country, postal code), device classification (mobile, desktop, tablet), and referrer parsing (UTM parameters, landing page) are appended to every event at processing time. Enrichment is automatic. Once Upstack Pixel is capturing events and Upstack ID is resolving identities, every event flowing through the pipeline is enriched before it reaches any destination or warehouse table. ## Key Terms | Term | Definition | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | **Match key** | A hashed identity field (email, phone, address) used by ad platforms to link a conversion event to a user profile. | | **Customer metadata** | Attributes from Shopify (total spend, order count, customer tags) attached to a resolved identity profile. | | **Event context** | Non-identity attributes appended at processing time: geography, device type, UTM parameters, referrer. | | **Profile enrichment** | The process of augmenting an identity graph node with additional data from first-party and platform sources. | | **EMQ (Event Match Quality)** | Meta's score reflecting how well an event's identity signals can be matched to a user — directly improved by enrichment. | <CardGroup> <Card title="Conversion API Forwarding" icon="arrow-right-arrow-left" href="/concepts/conversion-api-forwarding"> See how enriched events improve signal quality when forwarded to ad platforms. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> Understand the identity layer that enrichment depends on. </Card> </CardGroup> # Destinations vs data sources: a complete guide Source: https://docs.upstackdata.com/concepts/destinations-vs-data-sources Destinations send data to ad platforms and email tools; data sources pull data from them. Configure both to power unified attribution, ROAS reporting, and event enrichment in Upstack Data. Two of the most important concepts in Upstack Data are **destinations** and **data sources** (referred to in the dashboard as **Sources**). They sound similar but serve opposite functions — and understanding the difference is essential for setting up your account correctly and getting accurate attribution data. ## The core distinction <CardGroup> <Card title="Destinations" icon="arrow-right-from-bracket" href="/destinations/overview"> Platforms Upstack **sends** event data **to**. When a customer views a product, adds to cart, or purchases, Upstack captures the event, enriches it with identity data, and pushes it to your destinations via server-side APIs. </Card> <Card title="Data sources (Sources)" icon="arrow-right-to-bracket" href="/sources/overview"> Platforms Upstack **pulls** data **from** for reporting and analytics. To show which campaigns are driving revenue and at what cost, Upstack pulls in your ad spend, impressions, and click data from each platform. </Card> </CardGroup> Think of it this way: * **Destinations** = Upstack pushing data **OUT** (events going to ad platforms and marketing tools). * **Sources** = Upstack pulling data **IN** (spend and performance data for your dashboard). ## Why the distinction matters You might wonder why these are separate. After all, Meta is both a destination (Upstack sends purchase events to it) and a source (Upstack pulls spend data from it). They're configured separately because they serve different purposes and require different permissions: * **Sending events** (destination) requires write access to a platform's conversion API — like [Meta CAPI](/destinations/meta-capi) or [Google Ads](/destinations/google-ads) offline conversions. This is about feeding the ad platform real-time conversion data for optimization. * **Pulling spend data** (source) requires read access to a platform's reporting API. This is about bringing performance data into Upstack's [attribution dashboard](/concepts/attribution-and-reporting) so you can see the full picture in one place. You can connect a platform as a destination without connecting it as a source, and vice versa. But for the complete picture — events flowing out and spend data flowing in — you'll want both. ## Available destinations Destinations receive enriched event data from Upstack via server-side APIs. Each destination gets relevant ecommerce events along with identity parameters for user matching. | Destination | API used | Events sent | Identity data sent | | -------------- | ------------------------------ | ----------------------------------------------------------------- | ---------------------------------------------------------- | | **Meta CAPI** | Conversions API | Purchase, AddToCart, ViewContent, InitiateCheckout, custom events | Hashed email, phone, name, IP, user agent, `fbclid`, `fbp` | | **Google Ads** | Offline / Enhanced Conversions | Purchase, conversion events | `gclid`, hashed email, phone | | **TikTok** | Events API | Purchase, AddToCart, ViewContent, funnel events | Hashed email, phone, IP, user agent, `ttclid` | | **Pinterest** | Conversions API | Purchase, AddToCart, ViewContent | Hashed email, click ID, IP, user agent | | **Klaviyo** | Klaviyo API | Browse, cart, purchase events for flow triggering | Email, customer properties, event metadata | | **Snapchat** | Conversions API | Purchase, conversion events | Hashed email, phone, IP, click ID | | **Omnisend** | Omnisend API | Browse, cart, purchase events | Email, customer properties, event metadata | | **Webhooks** | Custom HTTP | Any configured event | Full enriched payload | <Note> GA4 is no longer a supported destination for new connections and is being deprecated. </Note> ## Available data sources Data sources provide Upstack with the information it needs to build your attribution dashboard and calculate key metrics like ROAS. | Data source | Data pulled | Used for | | ------------------------------------------------ | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | **[Shopify](/sources/shopify)** | Orders, revenue, products, customer data, refunds | Revenue attribution, order-level reporting, customer classification (new vs returning) | | **[Facebook Ads (Meta)](/sources/facebook-ads)** | Campaign spend, impressions, clicks, campaign/ad set/ad structure | ROAS calculation, spend-to-revenue comparison, campaign-level attribution | | **[Google Ads](/sources/google-ads)** | Campaign spend, impressions, clicks, campaign structure | ROAS calculation, spend-to-revenue comparison, campaign-level attribution | | **[TikTok](/sources/tiktok)** | Campaign spend, impressions, clicks, campaign structure | ROAS calculation, spend-to-revenue comparison, campaign-level attribution | ## How they work together The real power of Upstack comes from destinations and sources working in tandem: <Steps> <Step title="Events go OUT via destinations"> A customer makes a purchase. Upstack captures the event, enriches it with identity data, and sends it to Meta via CAPI, Google via offline conversions, and any other connected destinations. </Step> <Step title="Spend data comes IN via sources"> Upstack pulls your daily ad spend, campaign structure, and performance metrics from Meta, Google, TikTok, and Shopify. </Step> <Step title="The attribution dashboard combines both"> Upstack's [Analytics](/concepts/attribution-and-reporting) matches revenue from Shopify orders (attributed through its own model) against spend data from your ad platforms. This gives you a unified view: how much you spent on each channel, how much revenue each channel drove, and your true ROAS — without relying on each platform's self-reported numbers. </Step> </Steps> Without destinations connected, your ad platforms don't receive enriched conversion data and can't optimize effectively. Without sources connected, your Upstack dashboard can't show spend or calculate ROAS. You need both for the full picture. ## Setup priority order If you're configuring Upstack for the first time, here's the recommended order: <Steps> <Step title="Phase 1 — Critical (Day 1)"> 1. **Meta as a destination** — get enriched events flowing to your highest-spend platform. 2. **Google Ads as a destination** — second-highest priority for most brands. 3. **Shopify as a source** — usually connected automatically during installation. See [Connect a destination](/get-started/connect-a-destination) for the step-by-step. </Step> <Step title="Phase 2 — Important (Day 1–2)"> 4. **Meta as a source** — pull spend data so your dashboard can calculate ROAS. 5. **Google Ads as a source** — same reason. 6. **Klaviyo as a destination** — if you use Klaviyo for email/SMS marketing. </Step> <Step title="Phase 3 — Expand (Week 1)"> 7. **TikTok, Pinterest, Snapchat, Omnisend as destinations** — connect any additional platforms you advertise on or use for marketing automation. 8. **TikTok as a source** — to see TikTok spend in your dashboard alongside Meta and Google. </Step> </Steps> ## Common confusion <AccordionGroup> <Accordion title="I connected Facebook — why don't I see spend data?"> Connecting Facebook as a **destination** ([Meta CAPI](/destinations/meta-capi)) only sets up event sending. You also need to connect [Facebook Ads as a source](/sources/facebook-ads) to pull in spend and campaign data for your attribution dashboard. </Accordion> <Accordion title="My attribution dashboard shows revenue but no ROAS"> ROAS requires both revenue data (from Shopify) and spend data (from ad platform sources). If you haven't connected your ad platforms as sources, Upstack can't calculate ROAS. See [Attribution and reporting](/concepts/attribution-and-reporting). </Accordion> <Accordion title="Do I need to connect Shopify as a destination?"> No. Shopify is a **source** — Upstack pulls order data from it. Shopify isn't a destination because you don't send tracking events to Shopify; events originate from Shopify. </Accordion> </AccordionGroup> ## Frequently asked questions <AccordionGroup> <Accordion title="Can a platform be both a destination and a source?"> Yes. Meta, Google Ads, and TikTok are all both destinations (Upstack sends events to them) and sources (Upstack pulls spend data from them). They're configured separately because they use different APIs and permissions. </Accordion> <Accordion title="What happens if I only connect destinations but not sources?"> Your ad platforms will receive enriched event data and optimize more effectively, but your Upstack attribution dashboard won't be able to show spend or calculate ROAS. You'll still see revenue attribution, but without the cost side of the equation. </Accordion> <Accordion title="What happens if I only connect sources but not destinations?"> Your Upstack dashboard will show spend data, but your ad platforms won't receive enriched server-side events from Upstack. You'd miss out on improved match quality, better optimization signals, and the core value of server-side tracking. </Accordion> <Accordion title="Do sources update in real time?"> Ad spend data is typically pulled on a regular schedule (daily or more frequently) rather than in real time. There may be a short delay between when spend occurs on the ad platform and when it appears in your Upstack dashboard. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Destinations overview" icon="arrow-right-from-bracket" href="/destinations/overview"> Every supported destination and its configuration options. </Card> <Card title="Sources overview" icon="arrow-right-to-bracket" href="/sources/overview"> Every supported data source and how each one is connected. </Card> <Card title="Connect a destination" icon="plug" href="/get-started/connect-a-destination"> Step-by-step setup for your first destination. </Card> <Card title="Attribution and reporting" icon="chart-line" href="/concepts/attribution-and-reporting"> How Upstack combines event data and spend data to attribute revenue. </Card> <Card title="What are destinations?" icon="circle-question" href="/what-are-destinations"> A focused deep-dive on destinations. </Card> <Card title="What are data sources?" icon="circle-question" href="/what-are-data-sources"> A focused deep-dive on sources. </Card> </CardGroup> # How post-purchase upsells are tracked Source: https://docs.upstackdata.com/concepts/how-post-purchase-upsells-are-tracked How Upstack Data tracks post-purchase upsells, subscription renewals, quiz and lead events, and custom events without double-counting conversions. If you use a post-purchase upsell app (AfterSell, Zipify, Funnelish, and similar), the upsell creates a separate Shopify order after the original purchase. Since the purchase event has already been sent to your ad platform, its value can't be updated. Upstack Data handles this by: 1. Sending the original purchase event with the original order value at checkout. 2. Blocking the upsell order from being sent as a second purchase event. 3. Firing a separate **Upsell Purchase** custom event with only the upsell amount. This prevents double-counting while still capturing upsell value separately. <Tip> To see total ROAS including upsells, create a custom metric in Meta Ads Manager that adds Purchase value and Upsell Purchase value together, then divides by original purchase count — giving you a blended AOV and ROAS. </Tip> <Note> **Why not send the combined value?** The purchase event fires at checkout, before the upsell offer is presented. There's no way to wait for the upsell decision without losing browser-side tracking data, and sending a second standard purchase would cause duplicates. The separate event is the cleanest approach. </Note> ## How subscription renewals are tracked For stores using subscription apps (Loop, Skio, ReCharge, Bold, and similar), Upstack separates initial purchases from renewals: * **Initial subscription purchase** — sent as a standard Purchase event, attributed normally. * **Recurring payments** — automatically excluded from ad platforms. Sending them as standard purchases would inflate reported conversions and misrepresent campaign performance. In your Upstack dashboard, total revenue includes both initial and recurring payments. The exclusion only applies to what's sent to ad platforms as an attribution signal. ## Quiz funnels and custom lead events If your store uses a quiz funnel, Upstack Data can send events at each stage: * **Quiz Question Answered** — fires for each question answered. * **Quiz Completed** — fires when the visitor finishes the quiz. * **Quiz Lead** — fires when the visitor submits their email. These events help ad platforms identify high-intent visitors and find similar audiences. You can also assign dollar values to prioritize higher-value prospects. Quiz events require your developer to implement triggers on your site. Upstack Data provides the event schema; your team wires it into the quiz flow. ## Event mapping for restricted categories For stores in restricted categories (health and wellness, CBD, supplements), Facebook may flag or restrict accounts that send certain product data. Upstack Data mitigates this by stripping sensitive information — such as product titles, URLs, and product paths — from events sent to Meta. This reduces the risk of account flags while maintaining event match quality through other identifiers (email, phone, IP, External ID). ## Do I need to rebuild my campaigns for custom events? No. Custom events are sent alongside standard events, so your campaigns can continue optimizing for Purchase. Events like NC Purchase and Upsell Purchase appear as additional Ads Manager columns for reporting. You only need a new campaign if you want to optimize toward a specific custom event. <Note> Need help setting up quiz events, understanding custom event data, or configuring upsell tracking? Reach out to our support team. </Note> ## Related guides <CardGroup> <Card title="Install Upstack on Shopify" icon="shop" href="/get-started/install-on-shopify"> Set up the Upstack Data tracking pixel on your Shopify store. </Card> <Card title="Connect a destination" icon="plug" href="/get-started/connect-a-destination"> Forward upsell and purchase events to Meta, TikTok, and other ad platforms. </Card> <Card title="Custom events" icon="bolt" href="/guides/custom-events/how-to-create-custom-event-triggers"> Learn how to send custom events like quiz completions and leads. </Card> <Card title="Event taxonomy" icon="list" href="/pixel/events/taxonomy"> Understand all standard events Upstack tracks, including Purchase and Upsell Purchase. </Card> </CardGroup> # Upstack Data Platform Architecture Source: https://docs.upstackdata.com/concepts/platform-architecture A technical overview of how Upstack Data's infrastructure processes marketing events — from Cloudflare edge capture through identity resolution, enrichment, forwarding, and analytics. Upstack Data is a five-stage pipeline that captures raw storefront events, resolves visitor identities, enriches events with customer context, forwards high-quality signals to ad platforms, and stores everything in an analytics warehouse you can query. <Tip> Understanding the pipeline architecture helps you diagnose where data quality issues originate and how each Upstack product contributes to your marketing data stack. </Tip> ## Why It Matters Most marketing data stacks are assembled from disconnected tools — a pixel here, a CAPI integration there, a separate analytics platform. Each tool operates on its own copy of the data, with its own identity model, its own event schema, and its own gaps. Upstack replaces that patchwork with a single pipeline. Every event flows through the same sequence of stages, accumulating identity and context at each step. This means your conversion APIs receive the same enriched events that your attribution models analyze — no reconciliation, no duplicate schemas, no conflicting identity logic. A unified pipeline also makes debugging straightforward. If a conversion isn't appearing in Meta, you can trace the event from capture through resolution, enrichment, and forwarding to pinpoint exactly where the signal was lost. ## How It Works The pipeline has five stages, each handled by a dedicated Upstack product. ```mermaid theme={null} flowchart LR A["🏪 Shopify\nStorefront"] --> B["⚡ Upstack Pixel\n(Cloudflare Edge)"] B --> C["🔗 Upstack ID\n(Identity Resolution)"] C --> D["📦 Upstack Enrichment\n(Data Enrichment)"] D --> E["📡 Upstack Signal / Flows\n(Forwarding)"] D --> F["📊 Upstack Analytics\n(Warehouse & Reporting)"] ``` ### 1. Capture — Upstack Pixel Shopper interactions on your Shopify storefront generate events (page views, add-to-cart, checkout, purchase). The Upstack theme extension sends these as first-party requests to **Cloudflare Workers** at the edge. Bot traffic is filtered, a durable first-party cookie is set, and events are normalized into a canonical schema. Latency is sub-50 ms with zero impact on storefront performance. ### 2. Resolve — Upstack ID Raw events enter the **AWS backend** where the identity resolution engine matches anonymous sessions to known customers. Deterministic matching (email, phone, login) creates hard links. Session stitching retroactively attributes anonymous events once a visitor identifies themselves. Cross-device linking merges profiles when the same identifier appears on multiple devices. ### 3. Enrich — Upstack Enrichment Resolved events are augmented with customer metadata from Shopify (order history, LTV, customer tags), geographic context from IP geolocation, and all available identity fields from the identity graph. After this stage, events carry the full set of match keys needed for high-quality forwarding. ### 4. Activate — Upstack Signal & Upstack Flows Enriched events are queued via **Amazon SQS** and delivered server-to-server to configured destinations: Meta CAPI, TikTok Events API, Google, Klaviyo, Pinterest, Snapchat, and others. Upstack Flows handles Klaviyo-specific flow recovery. Each destination adapter transforms events into the platform's required schema. Delivery includes automatic retry with exponential backoff and dead-letter queues for failed events. ### 5. Understand — Upstack Analytics Every event is also written to **SingleStore**, a high-performance analytics database. Upstack Analytics queries this warehouse to build attribution reports, calculate ROAS by channel, and surface customer journey insights — all from the same identity-resolved, enriched events that your destinations received. ## Infrastructure Summary | Layer | Technology | Role | | ----------------------- | ------------------- | ----------------------------------------------------------- | | **Edge** | Cloudflare Workers | Event capture, bot filtering, cookie management | | **Compute** | AWS Lambda | Identity resolution, enrichment, forwarding, API handlers | | **Queue** | Amazon SQS | Async event delivery with retry and dead-letter handling | | **Identity store** | PostgreSQL, Neptune | Identity graph storage and traversal | | **Analytics warehouse** | SingleStore | High-speed analytical queries for attribution and reporting | | **Configuration** | DynamoDB | Destination configs, account settings, subscription data | ## Key Terms | Term | Definition | | --------------------- | --------------------------------------------------------------------------------------------------------------------------- | | **Edge layer** | The Cloudflare-based infrastructure that captures events close to the visitor for low-latency, high-reliability collection. | | **Canonical schema** | The standardized event format used internally across all pipeline stages. | | **Dead-letter queue** | A holding queue for events that fail delivery after all retry attempts, preserving data for debugging. | | **Identity graph** | The data structure mapping all known identifiers to unified customer profiles. | | **Match keys** | Hashed identity fields attached to events that ad platforms use to link conversions to user profiles. | <CardGroup> <Card title="Server-Side Tracking" icon="server" href="/concepts/server-side-tracking"> Deep dive into the Capture stage. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> Deep dive into the Resolve stage. </Card> <Card title="Data Enrichment" icon="layer-plus" href="/concepts/data-enrichment"> Deep dive into the Enrich stage. </Card> <Card title="Conversion API Forwarding" icon="arrow-right-arrow-left" href="/concepts/conversion-api-forwarding"> Deep dive into the Activate stage. </Card> <Card title="Attribution & Reporting" icon="chart-mixed" href="/concepts/attribution-and-reporting"> Deep dive into the Understand stage. </Card> <Card title="Install Upstack Pixel" icon="rocket" href="/get-started/install-on-shopify"> Get started with the first pipeline stage. </Card> </CardGroup> # What Is Server-Side Tracking and Why Does It Matter? Source: https://docs.upstackdata.com/concepts/server-side-tracking Server-side tracking captures accurate marketing data despite ad blockers, iOS privacy changes, and browser restrictions — outperforming client-side pixels for ad attribution and ROAS. Server-side tracking moves data collection from the visitor's browser to a server you control, eliminating the reliability problems that plague traditional JavaScript pixels. <Tip> Stores using Upstack Pixel's server-side tracking typically recover 20–40% of events that client-side scripts miss due to ad blockers and Intelligent Tracking Prevention (ITP). </Tip> ## Why It Matters Traditional client-side pixels depend on JavaScript executing inside a visitor's browser. That model is breaking. Safari's ITP caps cookie lifetimes at 7 days (or 24 hours for link-decorated traffic). Firefox blocks known trackers by default. Ad blockers strip tracking scripts before they load. iOS 14.5+ App Tracking Transparency further limits signal availability across the Apple ecosystem. For Shopify merchants, every lost event is a lost signal — attribution gaps widen, retargeting audiences shrink, and ad platform algorithms receive incomplete conversion data. The downstream cost compounds: Meta's algorithm optimizes toward the wrong audience, ROAS reporting becomes unreliable, and you over-invest in channels that only *appear* to perform. Server-side tracking sidesteps these problems entirely. Because the data collection happens at the server layer — outside the browser sandbox — ad blockers, cookie restrictions, and JavaScript failures have no effect on data capture. ## How It Works Upstack Pixel operates at the **Capture** stage of the data pipeline. When a shopper interacts with your Shopify storefront, the Upstack theme extension fires lightweight first-party requests to Cloudflare's edge network — the same infrastructure that serves your site assets. At the edge, Upstack performs three critical steps before the event enters the pipeline: 1. **Bot filtering** — Known bot signatures and suspicious traffic patterns are stripped so only human interactions proceed. 2. **First-party cookie management** — A durable first-party cookie is set under your store's domain, immune to ITP restrictions because it is issued server-side. 3. **Event normalization** — Raw interaction data is transformed into a canonical event schema, ready for identity resolution and forwarding downstream. Because Cloudflare Workers execute in the same data center region as the visitor, latency stays under 50 ms and has zero impact on storefront performance. ## Key Terms | Term | Definition | | ----------------------------------------- | ----------------------------------------------------------------------------------------------------- | | **Client-side pixel** | A JavaScript tag running in the visitor's browser — vulnerable to blockers and cookie restrictions. | | **Server-side tracking** | Data collection handled by a server, outside the browser sandbox. | | **ITP (Intelligent Tracking Prevention)** | Apple's Safari feature that limits cookie lifetimes and blocks cross-site tracking. | | **First-party cookie** | A cookie set under your store's own domain, subject to fewer restrictions than third-party cookies. | | **Bot filtering** | Automated removal of non-human traffic before events enter your data pipeline. | | **Edge network** | A globally distributed server layer (Cloudflare) where Upstack processes events close to the visitor. | <CardGroup> <Card title="Quick Start: Install Upstack Pixel" icon="rocket" href="/get-started/install-on-shopify"> Get server-side tracking running on your Shopify store in under 10 minutes. </Card> <Card title="Events Taxonomy" icon="list-tree" href="/pixel/events/taxonomy"> See every event Upstack Pixel captures and its schema. </Card> </CardGroup> # How Timezones Work in Upstack Data Source: https://docs.upstackdata.com/concepts/timezones Learn how Upstack Data handles timezones across your dashboard, reports, and integrations — and how to configure your preferred timezone. Upstack Data uses your configured timezone to display all dates and times throughout the dashboard. This ensures your analytics, reports, and date filters align with your business hours. <Tip> During onboarding, Upstack automatically detects your timezone from your Shopify store (if connected) or your browser. You can change it anytime in Settings. </Tip> ## How Timezones Affect Your Dashboard Your timezone setting determines how dates and times appear across Upstack Data: * **Date filters** — When you select "Today" or "Last 7 Days," the boundaries are calculated in your configured timezone. * **Charts and reports** — Daily metrics roll up at midnight in your timezone, so revenue attributed to "June 1" reflects orders placed between 12:00 AM and 11:59 PM in your local time. * **Event timestamps** — Individual events display in your timezone for easier interpretation. * **Scheduled reports** — Any automated reports use your timezone for "daily" boundaries. <Note> Your data is stored internally in UTC for accuracy and consistency. The timezone setting only controls how that data is displayed to you. </Note> ## Timezone Detection When you first set up Upstack Data, the system automatically detects your timezone: | Condition | Detected Timezone | | --------------------------- | ------------------------------------- | | **Shopify store connected** | Your Shopify store's timezone setting | | **No Shopify connection** | Your browser's local timezone | This automatic detection ensures your dashboard immediately reflects your business's operating hours without manual configuration. ## Configuring Your Timezone You can view and change your timezone at any time from the dashboard settings. ### Where to Find Timezone Settings 1. Click **Settings** in the left sidebar 2. Select **Dashboard** 3. Locate the **Timezone** dropdown 4. Select your preferred timezone from the list 5. Click **Save Changes** The timezone list includes all standard IANA timezone identifiers (e.g., `America/New_York`, `Europe/London`, `Asia/Tokyo`). You can search by city name or region to quickly find your timezone. ## Ad Platform Data and Timezones When Upstack Data pulls performance data from your connected ad platforms (Meta, Google, TikTok, etc.), each platform reports metrics in the ad account's configured timezone. Upstack normalizes this data to UTC internally, then displays it in your configured timezone. This means your dashboard shows a unified view regardless of how each ad platform is configured — all metrics appear in your chosen timezone. ## Common Questions <AccordionGroup> <Accordion title="What happens if I change my timezone?"> Changing your timezone updates how existing data is displayed. The underlying data remains unchanged — only the presentation shifts. For example, if you switch from Pacific Time to Eastern Time, an event that appeared at "9:00 PM" will now show as "12:00 AM" the next day. </Accordion> <Accordion title="Should my timezone match my Shopify store?"> In most cases, yes. Matching timezones ensures your Upstack revenue reports align with Shopify's reporting, making reconciliation straightforward. If your business operates across multiple timezones, choose the timezone where most decisions are made or where your headquarters is located. </Accordion> <Accordion title="Does timezone affect attribution?"> Timezone affects when conversion windows begin and end. A 7-day attribution window starting "today" uses your configured timezone to determine the boundary. For consistency, keep your timezone setting stable once configured. </Accordion> <Accordion title="Why is my data showing a different date than expected?"> This usually happens when your Upstack timezone differs from your ad platform or Shopify timezone. An order placed at 11 PM Eastern on June 1 would appear as June 2 in a Pacific Time dashboard. Aligning your timezone setting typically resolves these discrepancies. </Accordion> </AccordionGroup> <CardGroup> <Card title="Attribution Reporting" icon="chart-line" href="/analytics/attribution-reporting"> Understand how Upstack Data attributes revenue to marketing touchpoints. </Card> <Card title="Analytics Query Guide" icon="magnifying-glass-chart" href="/analytics/query-guide"> Learn how to query and analyze your marketing data. </Card> </CardGroup> # Measures and Dimensions Reference Source: https://docs.upstackdata.com/data-dictionary/measures-and-dimensions Reference of every measure (numeric metric) and dimension (groupable attribute) in Upstack Analytics — definitions, calculation logic, valid combinations, and the events each is derived from. Measures and dimensions are the building blocks of every Upstack Analytics query. **Measures** are the numeric values you calculate (revenue, event counts, conversion rates). **Dimensions** are the categories you group by (date, traffic source, device type). <Tip> Start with a measure you care about (e.g., Revenue), add a dimension to break it down (e.g., `utm_source`), and apply filters to focus your analysis. Most useful reports use 1–2 measures and 1–2 dimensions. </Tip> ## Measures Measures are aggregate calculations across your event data. Select one or more measures in the query builder to define what you want to calculate. <Tip> Need a metric that isn't listed here? Build your own from a formula over these measures with [Custom Measures](/analytics/custom-measures). </Tip> | Name | Type | Description | Unit | | ----------------------- | ------- | ------------------------------------------------------------------------------------------ | ------------------------ | | `total_events` | measure | Total count of events matching the query filters. | count | | `unique_visitors` | measure | Count of distinct resolved identities (or anonymous session IDs for unresolved visitors). | count | | `sessions` | measure | Count of distinct browsing sessions. A session ends after 30 minutes of inactivity. | count | | `page_views` | measure | Count of PageView events. | count | | `purchases` | measure | Count of Purchase events. | count | | `revenue` | measure | Sum of `value` from Purchase events. | currency (store default) | | `conversion_rate` | measure | Ratio of sessions with at least one Purchase to total sessions. Expressed as a percentage. | percentage | | `avg_order_value` | measure | Mean `value` across Purchase events. Calculated as `revenue / purchases`. | currency (store default) | | `bounce_rate` | measure | Percentage of sessions with only a single PageView and no further interaction. | percentage | | `session_duration` | measure | Average time between the first and last event in a session. | seconds | | `add_to_cart_rate` | measure | Ratio of sessions with at least one AddToCart event to total sessions. | percentage | | `cart_abandonment_rate` | measure | Ratio of sessions with AddToCart but no Purchase to sessions with AddToCart. | percentage | | `avg_pages_per_session` | measure | Mean number of PageView events per session. | count | <Note> Currency-based measures (`revenue`, `avg_order_value`) use the currency from the Purchase event's `currency` field. If your store transacts in multiple currencies, values are reported in the original currency unless you enable currency normalization in settings. </Note> ## Dimensions Dimensions define how measures are grouped and broken down. Select one or more dimensions to segment your data. ### Time Dimensions | Name | Type | Description | Granularity | | ------------- | --------- | --------------------------------------------------------------------- | ----------- | | `date` | dimension | Calendar date of the event. | day | | `week` | dimension | ISO week of the event. | week | | `month` | dimension | Calendar month of the event. | month | | `hour_of_day` | dimension | Hour (0–23) when the event occurred. Useful for time-of-day analysis. | hour | | `day_of_week` | dimension | Day of the week (Monday–Sunday). | day | ### Traffic Dimensions | Name | Type | Description | Example Values | | -------------- | --------- | -------------------------------------------------------------- | -------------------------------------------------- | | `utm_source` | dimension | UTM source parameter from the landing page URL. | `facebook`, `google`, `klaviyo` | | `utm_medium` | dimension | UTM medium parameter. | `cpc`, `email`, `organic` | | `utm_campaign` | dimension | UTM campaign parameter. | `summer_sale_2026`, `retargeting_q1` | | `utm_content` | dimension | UTM content parameter for ad-level breakdown. | `hero_banner`, `sidebar_ad` | | `utm_term` | dimension | UTM term parameter for keyword-level analysis. | `cotton+tee`, `running+shoes` | | `referrer` | dimension | HTTP referrer domain that sent the visitor. | `google.com`, `facebook.com`, `direct` | | `channel` | dimension | Aggregated traffic channel derived from UTM and referrer data. | `Paid Social`, `Organic Search`, `Email`, `Direct` | ### Content Dimensions | Name | Type | Description | Example Values | | -------------- | --------- | ------------------------------------------------------------------ | ---------------------------------------------- | | `page_path` | dimension | URL path of the page (without domain or query string). | `/products/classic-tee`, `/collections/summer` | | `event_name` | dimension | Name of the event type. Stored in PascalCase (destination format). | `PageView`, `Purchase`, `AddToCart` | | `content_type` | dimension | Type of content involved in the event. | `product`, `product_group` | <Note> **Event name formats:** When calling the SDK, use `snake_case` (e.g., `add_to_cart`). Upstack transforms these to `PascalCase` for destinations and analytics storage. </Note> ### Visitor Dimensions | Name | Type | Description | Example Values | | -------------- | --------- | -------------------------------------------------------- | --------------------------------- | | `device_type` | dimension | Device category detected from user agent. | `mobile`, `desktop`, `tablet` | | `country` | dimension | Visitor's country, derived from IP geolocation. | `US`, `GB`, `CA`, `AU` | | `region` | dimension | Visitor's state or region. | `California`, `Ontario`, `London` | | `is_returning` | dimension | Whether the visitor has been seen in a previous session. | `true`, `false` | ### Destination Dimensions | Name | Type | Description | Example Values | | ----------------- | --------- | ---------------------------------------------------------------- | --------------------------------------- | | `destination` | dimension | The forwarding destination the event was sent to. | `meta_capi`, `tiktok`, `klaviyo`, `ga4` | | `delivery_status` | dimension | Whether the event was successfully delivered to the destination. | `delivered`, `failed`, `pending` | ## Combining Measures and Dimensions Here are practical examples of how measures and dimensions work together: | Goal | Measures | Dimensions | Result | | ----------------------------- | ----------------------------------------------- | -------------- | ---------------------------------------------------- | | Daily revenue trend | `revenue` | `date` | Line chart of revenue per day | | Channel ROAS comparison | `revenue`, `purchases` | `utm_source` | Table comparing revenue and purchase count by source | | Mobile vs. desktop conversion | `conversion_rate`, `sessions` | `device_type` | Bar chart comparing conversion rates | | Top landing pages | `page_views`, `bounce_rate` | `page_path` | Table of pages sorted by traffic with bounce rate | | Hourly traffic pattern | `sessions` | `hour_of_day` | Bar chart showing when visitors arrive | | Campaign performance | `revenue`, `conversion_rate`, `avg_order_value` | `utm_campaign` | Full campaign performance table | <CardGroup> <Card title="Query Guide" icon="magnifying-glass-chart" href="/analytics/query-guide"> Learn how to build queries, set date ranges, and apply filters. </Card> <Card title="Session & Page Analytics" icon="chart-line" href="/analytics/session-and-page-analytics"> Explore session-level and page-level metrics in detail. </Card> <Card title="Custom Measures" icon="calculator" href="/analytics/custom-measures"> Define your own metrics and KPIs from a formula over these measures. </Card> </CardGroup> # AppLovin Axon Source: https://docs.upstackdata.com/destinations/applovin Send conversion events to AppLovin's Axon Conversions API for mobile and web advertising attribution — improving campaign optimization and match quality. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does AppLovin's Axon Conversions API is the server-side counterpart to the Axon Pixel. Upstack Signal forwards storefront events — page views, product views, add-to-carts, checkouts, and purchases — directly to AppLovin's servers, bypassing browser restrictions like ad blockers, ITP, and cookie limits. Server-side delivery gives AppLovin's algorithm a fuller picture of the conversions your ads actually drove, which improves campaign optimization, audience modeling, and attribution accuracy. Match rates from server-side events are consistently higher than browser-only tracking because each event carries hashed customer data and the `aleid` click identifier when available. <Note> AppLovin uses **token-based auth** instead of OAuth. You'll paste a Pixel ID (Event Key) and a Conversions API access token into the Upstack destination — there is no OAuth handshake to step through. </Note> ## How it works Upstack runs as a dual-tracking layer alongside the Axon Pixel. The Upstack Pixel captures events in the browser and forwards each event to Upstack's edge infrastructure, where it is hashed, enriched with identity and click-ID data, and sent to the Axon Conversions API as a server-side event with a shared `dedupe_id`. AppLovin deduplicates server events against matching browser Pixel events using that `dedupe_id`, so you do not double-count conversions as long as both sources use the same Pixel ID. PII (`email`, `phone`) is auto-hashed by Axon via SHA-256, though Upstack pre-hashes for consistency. <Warning> **Critical:** The `dedupe_id` field is REQUIRED for all server-side events. Events without a `dedupe_id` are rejected by the API. Additionally, if any single event in a batch is invalid, the entire batch is dropped with HTTP 400. </Warning> ## Setup guides <CardGroup> <Card title="Onboarding guide" icon="route" href="/guides/applovin-ads/complete-how-to-guide-for-onboarding-applovin-in-upstack-data"> End-to-end walkthrough for connecting AppLovin to Upstack Data. </Card> <Card title="Configure destination" icon="sliders" href="/guides/applovin-ads/how-to-configure-applovin-destination-in-upstack-data"> Configure the AppLovin Axon destination inside Upstack Data. </Card> <Card title="Find Pixel ID" icon="magnifying-glass" href="/guides/applovin-ads/how-to-find-applovin-pixel-id"> Locate your Axon Pixel ID (Event Key) in the AppLovin dashboard. </Card> <Card title="Generate API token" icon="key" href="/guides/applovin-ads/how-to-generate-applovin-conversion-api-token"> Generate the Conversions API access token Upstack uses to send events. </Card> </CardGroup> ## Event mapping Upstack maps storefront events to AppLovin Axon standard events automatically: | Upstack event | AppLovin event | Key parameters | Notes | | ------------------ | ------------------ | ----------------------------------------------------- | ---------------------------- | | `PageView` | `page_view` | `url`, `referrer` | Every page navigation | | `ViewContent` | `view_item` | `items`, `value`, `currency` | Product detail page | | `AddToCart` | `add_to_cart` | `items`, `value`, `currency` | `quantity` required per item | | `RemoveFromCart` | `remove_from_cart` | `items`, `value`, `currency` | `quantity` required per item | | `InitiateCheckout` | `begin_checkout` | `items`, `value`, `currency` | All fields required | | `AddPaymentInfo` | `add_payment_info` | `payment_type`, `value`, `currency` | Recommended event | | `Purchase` | `purchase` | `transaction_id`, `value`, `tax`, `shipping`, `items` | All fields required | | `Search` | `search` | `search_term` | `search_term` required | | `Lead` | `generate_lead` | `value`, `currency` | Both fields required | | `SignUp` | `sign_up` | `method` | `method` recommended | | `Subscribe` | `subscribe` | `value`, `currency` | Recommended event | Every event includes user data parameters (`email`, `phone`, `client_id`) when available. AppLovin click IDs (`aleid`) captured by the Upstack Pixel are included for deterministic matching. User matching requires at least one identifier: `aleid`, `axwrt`, `client_id`, `email`, `phone`, or `user_id`. ## FAQ <AccordionGroup> <Accordion title="How do I know events are reaching AppLovin?"> Open the AppLovin Axon Dashboard, navigate to your pixel's Events section, and check for recent events. Server-side events appear within 5–10 minutes of storefront activity. Upstack also surfaces delivery status inside the destination settings. </Accordion> <Accordion title="Will I see duplicate conversions if I run both the Axon Pixel and the Conversions API?"> No — as long as the Pixel ID in Upstack matches the Pixel ID firing in your storefront's Axon browser Pixel. Upstack sends a shared `dedupe_id` on every server-side event, and AppLovin's deduplication logic matches events by `dedupe_id` and keeps only one. </Accordion> <Accordion title="What if my event match rate is low?"> AppLovin's match rate depends on how much identity data each event carries. Common causes of low match quality: * **Missing `aleid`** — AppLovin ads should link directly to your storefront so the click ID lands in the URL and is captured by the Upstack Pixel. * **Anonymous visitors** — events from visitors without email or phone have fewer keys to match against. Match rates improve as more identified customers convert. * **Missing checkout fields** — make sure your Shopify checkout collects email and phone; both are strong server-side match keys. </Accordion> <Accordion title="What permissions does the Conversions API token need?"> The AppLovin Conversions API token is generated from your Axon Dashboard under Account → General → Keys. Upstack only needs permission to send events — no management or spending permissions are required. </Accordion> <Accordion title="Why are my events returning HTTP 400?"> A 400 response means the batch was rejected. AppLovin drops the **entire batch** if any single event is invalid. Common causes: * **Missing `dedupe_id`** — this field is REQUIRED on every server-side event * **Missing user identifier** — at least one of `aleid`, `axwrt`, `client_id`, `email`, `phone`, or `user_id` must be provided * **Invalid field format** — check that `event_time` is in milliseconds, `currency` is ISO 4217, etc. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="Events not appearing in AppLovin Dashboard"> If events aren't appearing after 10 minutes of confirmed store traffic, check the basics first. **Steps to fix:** 1. Go to **Integrations → Destinations → AppLovin** 2. Verify the **Pixel ID** and **Access Token** are correct (no extra spaces or truncated characters) 3. Confirm the destination status is Active (green) 4. If the token was revoked or expired, generate a new one in the Axon Dashboard and update the destination </Accordion> <Accordion title="Batch failures (HTTP 400)"> AppLovin's batch API drops the entire batch if any single event is invalid. **Steps to fix:** 1. Check CloudWatch logs for the specific validation error message 2. Verify all events include a `dedupe_id` (REQUIRED) 3. Verify all events include at least one user identifier 4. Check for malformed field values (timestamps, currencies, item arrays) 5. If one event type consistently fails, review its field mapping </Accordion> <Accordion title="Invalid API key (HTTP 401)"> The Conversions API key was rejected. **Steps to fix:** 1. Log into the AppLovin Dashboard 2. Navigate to Account → General → Keys 3. Generate a new Conversions API key 4. Update the key in your Upstack destination settings 5. Wait 5 minutes for the new key to propagate </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond AppLovin-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack matches anonymous visitors to known customers for higher match rates. </Card> <Card title="Meta CAPI destination" icon="meta" href="/destinations/meta-capi"> Set up Meta's Conversions API as another server-side destination alongside AppLovin. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Attentive Source: https://docs.upstackdata.com/destinations/attentive Forward identity-resolved customer events and profiles to Attentive to power SMS marketing automation, abandoned cart recovery, and personalized text messaging campaigns. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> Attentive is connected through **Upstack Flows**, the product that handles event delivery to marketing automation platforms. The key value: Upstack identifies visitors that Shopify and Attentive's native integrations miss — turning anonymous browse and cart abandonment sessions into actionable SMS triggers with phone numbers and emails attached. This means more abandoned cart SMS flows fire, more browse abandonment messages send, and you recover revenue through personalized text messaging. ## How It Works When a visitor takes an action on your store, Upstack: 1. Captures the event through the Upstack Pixel and matches it to a known visitor profile using Upstack's identity resolution. 2. If the visitor is identified (email available), enriches the event with the contact's email and any other known properties. 3. Sends the event to Attentive using your API key as a custom event that can trigger SMS journeys. 4. Attentive matches the email to existing subscribers and triggers the appropriate SMS flows. The result: abandoned cart and browse abandonment SMS journeys fire for visitors that Shopify's native tracking misses. ## Event Mapping | Upstack Event | Attentive Event | Key Properties | Notes | | ------------------ | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | `PageView` | `Page Viewed - Upstackified` | `productId`, `productUrl`, `name` | Tracks page visits with product context | | `ViewContent` | `Product Viewed - Upstackified` | `productId`, `productVariantId`, `productImage`, `productUrl`, `name`, `price`, `currency` | Powers browse abandonment SMS flows | | `AddToCart` | `Product Added to Cart - Upstackified` | `productId`, `productVariantId`, `productImage`, `productUrl`, `name`, `price`, `currency`, `quantity` | Powers abandoned cart SMS flows | | `InitiateCheckout` | `Checkout Started - Upstackified` | `productId`, `productUrl`, `name`, `price`, `currency`, `quantity` | Powers checkout abandonment SMS flows | | `AddShippingInfo` | `Added Shipping Info - Upstackified` | `productId`, `productUrl`, `name`, `price`, `currency` | Tracks checkout progress | | `AddPaymentInfo` | `Added Payment Info - Upstackified` | `productId`, `productUrl`, `name`, `price`, `currency` | Tracks payment step | | `Purchase` | `Product Purchased - Upstackified` | `productId`, `productVariantId`, `productImage`, `productUrl`, `name`, `price`, `currency`, `quantity`, `brand`, `tags` | Powers post-purchase SMS and win-back flows | Upstack sends events as custom events to Attentive's API. The `- Upstackified` suffix distinguishes Upstack-enriched events from native Attentive tracking, allowing you to run parallel journeys or A/B test performance. ## Set Up Attentive ### Prerequisites * An active Attentive account with API access * An Attentive API key with permission to create custom events ### Step 1: Generate Your Attentive API Key 1. Log in to your Attentive dashboard 2. Navigate to **Settings** → **API Keys** 3. Click **Create API Key** 4. Give it a descriptive name like "Upstack Data Integration" 5. Copy the API key — you'll need it in the next step <Warning> Store your API key securely. You won't be able to view it again after creation. </Warning> ### Step 2: Add Attentive Destination in Upstack 1. Open the [Upstack Data Dashboard](https://app.upstackdata.com) 2. Navigate to **Destinations** in the sidebar 3. Click **Add Destination** and select **Attentive** 4. Paste your Attentive API key 5. Click **Save** to activate the destination ### Step 3: Verify Events Are Flowing 1. Trigger a test event on your store (view a product, add to cart) 2. In Attentive, check **Analytics** → **Events** for incoming Upstackified events 3. Verify the event contains the expected properties (product info, user email) ## Use Cases ### Abandoned Cart SMS Recovery When a visitor adds items to their cart and leaves without purchasing: 1. Upstack captures the `AddToCart` event 2. Identity resolution matches the session to a known subscriber 3. Attentive receives `Product Added to Cart - Upstackified` with the subscriber's email 4. Your Attentive abandoned cart journey triggers, sending a personalized SMS with the cart contents ### Browse Abandonment SMS When a visitor views products but doesn't add to cart: 1. Upstack captures `ViewContent` events 2. Identity resolution identifies the visitor 3. Attentive receives `Product Viewed - Upstackified` 4. Your browse abandonment journey sends a follow-up SMS featuring the viewed products ### Post-Purchase SMS Flows When a customer completes a purchase: 1. Upstack captures the `Purchase` event with full order details 2. Attentive receives `Product Purchased - Upstackified` 3. Post-purchase journeys trigger — order confirmation, shipping updates, review requests, or cross-sell recommendations ## FAQ <AccordionGroup> <Accordion title="How is this different from Attentive's native Shopify integration?"> Attentive's native Shopify integration only sees visitors that Shopify has identified — typically logged-in customers or shoppers who have entered contact information. Upstack's identity resolution matches anonymous sessions to known subscriber profiles using cookies, click IDs, and cross-session behavioral data, then sends those events to Attentive with the contact's email attached. This lets your SMS journeys fire for many more visitors. </Accordion> <Accordion title="Will I get duplicate events if I keep Attentive's native Shopify integration?"> Upstack events use the `- Upstackified` suffix to distinguish them from native Attentive events. You can run both integrations in parallel and build separate journeys that trigger on Upstackified events. Alternatively, disable overlapping events in Attentive's native integration to avoid duplicates. </Accordion> <Accordion title="What permissions does the Attentive API key need?"> The Attentive API key must have permission to create custom events. Avoid using a key with excessive permissions — Upstack only needs to send event data, not manage subscribers or campaigns. </Accordion> <Accordion title="How long does it take for events to appear in Attentive?"> Once the destination is active, events typically appear in Attentive within a few minutes. You can verify by triggering a test action on your store and checking Attentive's event analytics. </Accordion> <Accordion title="Does Upstack create new subscribers in Attentive?"> No. Upstack sends events to Attentive, which then matches them to existing subscribers by email. Attentive will only trigger journeys for visitors who are already subscribed to your SMS list. This ensures compliance with SMS opt-in requirements. </Accordion> <Accordion title="What happens if no email is found for a visitor?"> Events without an identified email are skipped. Upstack only sends events to Attentive when identity resolution has successfully matched the visitor to a known profile with an email address. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="Events not appearing in Attentive"> If events are showing in the Upstack Live Event Stream but not arriving in Attentive: **Steps to fix:** 1. Confirm the Attentive destination shows **Active** (green) in the Upstack dashboard 2. Verify your API key has the required permissions for custom events 3. Check that the visitor was identified — events without email are skipped 4. In Attentive, check **Analytics → Events** and search for events containing "Upstackified" 5. If the destination status is red, disconnect and reconnect with a fresh API key </Accordion> <Accordion title="SMS journeys not triggering"> If events are arriving in Attentive but journeys aren't firing: **Steps to fix:** 1. Verify the journey is configured to trigger on Upstackified events (e.g., `Product Added to Cart - Upstackified`) 2. Check that the subscriber exists in Attentive and is opted in to SMS 3. Review journey conditions — the subscriber may be excluded by filters or suppression rules 4. Check journey analytics for any errors or blocked sends </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond Attentive-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Data Enrichment" icon="magnifying-glass-plus" href="/concepts/data-enrichment"> How Upstack Enrichment improves visitor identification — the foundation of Flows recovery. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack ID connects anonymous sessions to known customers with email addresses. </Card> <Card title="Klaviyo Destination" icon="envelope" href="/destinations/klaviyo"> Sync events and contacts to Klaviyo using the same Upstack Flows pipeline. </Card> <Card title="Events Not Reaching Destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Microsoft Advertising Conversions API Source: https://docs.upstackdata.com/destinations/bing Send conversion events to Microsoft Advertising (Bing Ads) via the Conversions API for ad campaign optimization, audience building, and attribution — powered by Upstack Signal. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does Microsoft Advertising's Conversions API (CAPI) is the server-side counterpart to the Universal Event Tracking (UET) Tag. Upstack Signal forwards storefront events — page views, product views, add-to-carts, and purchases — directly to Microsoft's servers, bypassing browser restrictions like ad blockers, ITP, and cookie limits. Server-side delivery gives Microsoft's algorithm a fuller picture of the conversions your ads actually drove, which improves campaign optimization, audience modeling, and attribution accuracy. Match rates from server-side events are consistently higher than browser-only tracking because each event carries hashed customer data and the `msclkid` click identifier when available. <Note> Microsoft's Conversions API is currently in **pilot program**. Contact your Microsoft Advertising account manager to enroll before enabling server-side tracking in Upstack. </Note> ## How it works Upstack runs as a dual-tracking layer alongside the Microsoft UET Tag. The Upstack Pixel captures events in the browser and forwards each event to Upstack's edge infrastructure, where it is hashed, enriched with identity and click-ID data, and sent to the Microsoft Conversions API as a server-side event with a shared `eventId`. Microsoft deduplicates server events against matching browser UET Tag events using that `eventId`, so you do not double-count conversions as long as both sources use the same UET Tag ID. PII (`email`, `phone`) is hashed with SHA-256 before delivery, as required by the Conversions API. <Warning> Unlike Meta and Google, Microsoft **does not support address-level enhanced matching**. Only email and phone are accepted for identity matching. </Warning> ## Setup guides <CardGroup> <Card title="Onboarding guide" icon="route" href="/guides/microsoft-ads/complete-how-to-guide-for-onboarding-microsoft-ads"> End-to-end walkthrough for connecting Microsoft Advertising to Upstack Data. </Card> <Card title="Configure destination" icon="sliders" href="/guides/microsoft-ads/how-to-configure-microsoft-ads-destination"> Configure the Microsoft Advertising destination inside Upstack Data. </Card> <Card title="Find UET Tag ID" icon="magnifying-glass" href="/guides/microsoft-ads/how-to-find-uet-tag-id"> Locate your UET Tag ID in Microsoft Advertising. </Card> <Card title="Create Event Goals" icon="bullseye" href="/guides/microsoft-ads/how-to-create-event-goals"> Create Event Goals to track specific conversion types. </Card> <Card title="Enable CAPI" icon="server" href="/guides/microsoft-ads/how-to-enable-conversions-api"> Enroll in the CAPI pilot and generate your auth token. </Card> <Card title="Enable click ID tracking" icon="link" href="/guides/microsoft-ads/how-to-enable-msclkid-tracking"> Ensure msclkid is captured and stored for attribution. </Card> </CardGroup> ## Event mapping Upstack maps storefront events to Microsoft Advertising events automatically: | Upstack event | Microsoft event | Key match data | | ------------------ | ---------------- | ----------------------------------------------- | | `PageView` | `pageLoad` | URL, referrer, user agent | | `ViewContent` | `view_item` | `itemIds`, `value`, `currency` | | `AddToCart` | `add_to_cart` | `itemIds`, `value`, `currency` | | `InitiateCheckout` | `begin_checkout` | `value`, `currency` | | `Purchase` | `purchase` | `value`, `currency`, `transactionId`, `itemIds` | | `Lead` | `lead` | `email`, `phone` | | `Search` | `search` | `searchTerm` | | `SignUp` | `sign_up` | `email` | <Note> Microsoft uses **free-form event names** rather than predefined standard events. Event matching is done via Event Goals configured in the Microsoft Advertising UI. </Note> PII is hashed with SHA-256 before it leaves Upstack. Upstack includes every available match key on every event — hashed `email`, hashed `phone`, `msclkid` (Microsoft click ID), `ip_address`, and `user_agent` — to maximize match quality. ## FAQ <AccordionGroup> <Accordion title="What is the difference between UET Tag ID and CAPI Auth Token?"> The **UET Tag ID** identifies your Microsoft Advertising tracking tag — it's the same ID used for browser-side tracking via the UET Tag. The **CAPI Auth Token** is a Bearer token that authenticates server-side API requests. You need both: the Tag ID to identify your account, and the auth token to authorize server-side event submission. </Accordion> <Accordion title="How do I enroll in the CAPI pilot program?"> Contact your Microsoft Advertising account manager or Microsoft Advertising support to request enrollment in the Conversions API pilot. Once enrolled, the auth token option becomes available in your UET Tag settings. </Accordion> <Accordion title="How do I know events are reaching Microsoft?"> Open Microsoft Advertising → **Tools** → **UET Tags** → select your tag → **Tag Status**. Server-side events appear alongside browser events. Upstack also surfaces delivery status inside the destination settings and Event Debugger. </Accordion> <Accordion title="Will I see duplicate conversions if I run both the UET Tag and Conversions API?"> No — as long as the UET Tag ID in Upstack matches your browser UET Tag. Upstack sends a shared `eventId` on every server-side event, and Microsoft's deduplication logic matches events by `eventId` and keeps only one. </Accordion> <Accordion title="Why do events need to be within 7 days?"> Microsoft's Conversions API rejects events older than 7 days. This is stricter than other platforms (Meta allows 7 days, Google allows 90 days). Ensure your event pipeline processes events promptly. </Accordion> <Accordion title="What if my event match rate is low?"> Microsoft's match rate depends on how much identity data each event carries. Common causes of low match quality: * **Missing `msclkid`** — Microsoft ads should link directly to your storefront so the click ID lands in the URL and is captured by the Upstack Pixel. * **Anonymous visitors** — events from visitors without email have fewer keys to match against. Match rates improve as more identified customers convert. * **Missing checkout fields** — make sure your Shopify checkout collects email and phone; they're the strongest server-side match keys. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="Events not appearing in Microsoft Advertising"> **Check these in order:** 1. Verify UET Tag ID is correct in Upstack destination settings 2. Verify CAPI auth token is valid (test in Event Debugger) 3. Check event timestamp is within 7 days 4. Ensure Event Goals are configured in Microsoft Advertising UI </Accordion> <Accordion title="401 Unauthorized errors"> Your CAPI auth token is invalid or expired. Generate a new token in Microsoft Advertising UET Tag settings and update your Upstack destination configuration. </Accordion> <Accordion title="400 Validation errors"> Common validation issues: * `eventType` must be "pageLoad" or "custom" * `eventTime` must be UNIX seconds (not milliseconds) within 7 days * `em` and `ph` must be valid SHA-256 hex strings (64 characters) * `eventSourceUrl` is required for pageLoad events </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Meta Conversions API" icon="meta" href="/destinations/meta-capi"> Server-side tracking for Meta (Facebook/Instagram) ads. </Card> <Card title="Google Ads" icon="google" href="/destinations/google-ads"> Send conversion events to Google Ads for campaign optimization. </Card> <Card title="TikTok Events API" icon="tiktok" href="/destinations/tiktok"> Server-side event delivery to TikTok for attribution. </Card> <Card title="Pinterest Conversions API" icon="pinterest" href="/destinations/pinterest"> Track conversions on Pinterest campaigns with server-side events. </Card> </CardGroup> # Google Analytics 4 (deprecated) Source: https://docs.upstackdata.com/destinations/ga4 The Google Analytics 4 destination has been deprecated and is no longer available for new connections. <Warning> **This destination is deprecated.** The Google Analytics 4 connection is no longer available for new setups. Existing connections will continue to function but are not actively maintained. </Warning> ## Why this was deprecated Upstack's Google Analytics 4 destination has been deprecated. We recommend using GA4's native installation through your Shopify store or Google Tag Manager for analytics tracking. ## Alternatives For server-side conversion tracking, use the platform-specific destinations that drive ad optimization: <CardGroup> <Card title="Meta Conversions API" href="/destinations/meta-capi"> Server-side conversion delivery to Meta Ads. </Card> <Card title="Google Ads" href="/destinations/google-ads"> Server-side conversion delivery to Google Ads. </Card> <Card title="Custom Webhooks" href="/destinations/webhooks"> Build custom integrations with your own analytics pipeline. </Card> <Card title="See all destinations" href="/destinations/overview"> Browse the full list of supported destinations. </Card> </CardGroup> ## Existing connections If you have an existing GA4 destination configured in Upstack, it will continue to operate. Contact [support@upstackdata.com](mailto:support@upstackdata.com) if you need to make changes to your configuration. # Google Ads Source: https://docs.upstackdata.com/destinations/google-ads Forward purchase conversions to Google Ads via server-side API with Enhanced Conversions match keys — improving Smart Bidding signal, attribution accuracy, and Performance Max optimization. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does Google Ads relies on conversion signal to power Smart Bidding, Performance Max, and any campaign that optimizes toward purchases. Upstack Signal forwards every Shopify purchase to your Google Ads account server-side, attached to a dedicated Upstack conversion goal that Google's bidder can optimize against. Server-side delivery means conversions reach Google even when the browser-side gtag is blocked by ad blockers, ITP, or cookie restrictions. Each event carries the original click identifier (`gclid` or `gbraid`/`wbraid`) plus hashed customer data, so Google can match the conversion back to the ad interaction that drove it. The result is more complete conversion data inside Google Ads, sharper Smart Bidding decisions, and reporting that reflects the conversions your campaigns actually produced. ## How it works Google Ads uses a primary/secondary conversion goal architecture. Primary goals drive bidding — Smart Bidding optimizes toward whatever is marked primary. Secondary goals are observation-only: they appear in reports but do not influence the bidder. Upstack creates its own purchase goal in your account so you can compare it side-by-side with your existing goal before promoting it to primary. Upstack hashes customer data — `email`, `phone`, `first_name`, `last_name`, `city`, `state`, `zip`, `country` — with SHA-256 before sending it to Google's API. Google uses these match keys the same way Enhanced Conversions does, so you get equivalent match-rate uplift without enabling Enhanced Conversions on the destination itself. ## Primary vs secondary conversion rollout When Upstack creates a conversion action in your Google Ads account, don't immediately make it your primary goal. Start it as a **secondary** conversion (reporting only) and run it alongside your existing setup for **7–14 days**. Compare purchase counts during this window — Upstack should track equal or higher volume due to enhanced identity matching. Once validated, promote the Upstack conversion to **primary** and demote the old one. This protects your Smart Bidding from disruption during the transition and gives the bidder a clean signal to retrain against. <Tip> Smaller accounts may need longer than 14 days to accumulate enough conversions for Smart Bidding to retrain confidently. Wait until the Upstack goal has logged conversions across a full bidding window before promoting it. </Tip> ## Setup guides <CardGroup> <Card title="Onboarding guide" icon="route" href="/guides/google-ads/complete-how-to-guide-for-onboarding-google-ads-in-upstack-data"> End-to-end walkthrough for connecting Google Ads to Upstack Data. </Card> <Card title="Configure destination" icon="sliders" href="/guides/google-ads/how-to-configure-google-ads-destination-in-upstack-data"> Configure the Google Ads destination inside Upstack Data. </Card> <Card title="Server-side Conversions API setup" icon="server" href="/guides/google-ads/how-to-set-up-google-ads-server-side-conversions-api-in-upstack-data"> Connect Google Ads with OAuth and map events to conversion actions for server-side forwarding. </Card> <Card title="Find conversion ID and label" icon="magnifying-glass" href="/guides/google-ads/how-to-get-your-google-ads-conversion-id-and-label"> Locate the conversion ID and label values Upstack needs. </Card> <Card title="Create purchase goal" icon="bullseye" href="/guides/google-ads/how-to-create-a-new-upstack-data-purchase-goal-in-google-ads"> Create the dedicated Upstack purchase conversion goal in Google Ads. </Card> <Card title="Enable primary goal" icon="circle-check" href="/guides/google-ads/how-to-enable-the-google-ads-upstack-purchase-goal-and-switch-to-primary-optimization-goal"> Promote the Upstack goal to primary so Smart Bidding optimizes against it. </Card> <Card title="Connect Google Ads account (source)" icon="plug" href="/guides/integrations/how-to-connect-your-google-ads-account-in-upstack-data-integrations"> Connect Google Ads as a campaign data source for attribution reporting. </Card> </CardGroup> ## FAQ <AccordionGroup> <Accordion title="What's the difference between primary and secondary conversion goals?"> Primary goals drive Smart Bidding — Google optimizes toward them. Secondary goals are observation-only and appear in reports but do not influence the bidder. New Upstack goals start as secondary so you can compare their volume and quality against your existing goal before switching them to primary. </Accordion> <Accordion title="Why does Upstack create a new conversion goal instead of using my existing one?"> Pointing Upstack at your existing goal would mix Upstack's server-side conversions with whatever source is already firing into it (gtag, Shopify's native tag, GTM), which makes deduplication and quality comparison impossible. A dedicated Upstack goal keeps the data clean and lets you A/B the two goals before promoting Upstack to primary. </Accordion> <Accordion title="How do I migrate from a manual conversion goal to Upstack?"> Run both goals in parallel for at least one full conversion window. Keep your existing goal as primary and Upstack as secondary, confirm the volume and value reconcile, then follow the "Enable primary goal" guide to swap them. After the swap, demote your old goal to secondary so it stops influencing Smart Bidding. </Accordion> <Accordion title="Why doesn't Upstack support Enhanced Conversions directly?"> Upstack already sends the same hashed match keys Enhanced Conversions uses (`email`, `phone`, name, address) on every server-side event, so Google's match-rate logic applies automatically. Enabling Enhanced Conversions on top of the Upstack goal would not add data, and on the wrong goal it can cause duplicate or conflicting match logic. </Accordion> <Accordion title="When should I switch the Upstack goal to primary?"> Once the Upstack goal has logged conversions across a full bidding window (typically 7–14 days) and the volume and value reconcile within a few percent of your existing goal, it is safe to promote Upstack to primary. Smaller accounts may need longer to accumulate enough signal for Smart Bidding to retrain. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Attribution and reporting" icon="chart-line" href="/concepts/attribution-and-reporting"> How Upstack attributes conversions back to the campaigns that drove them. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Klaviyo Source: https://docs.upstackdata.com/destinations/klaviyo Forward identity-resolved customer events and profiles to Klaviyo to power email and SMS automation, recover 30-50% more abandoned cart and checkout revenue with Upstack-enhanced flows. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does Klaviyo is connected through Upstack Flows, the product that handles event delivery to marketing automation platforms. Upstack Flows sends enriched event and profile data to Klaviyo so its flows — abandoned cart, browse abandonment, checkout abandonment, post-purchase — fire on a much larger pool of visitors than Shopify and Klaviyo's native integration can identify on their own. The practical impact is more recovered revenue. Anonymous visitors that Shopify cannot match to an email get matched by Upstack's identity resolution and pushed into Klaviyo as enriched profiles, which means more abandoned cart flows fire, more browse abandonment emails send, and more SMS messages reach the inbox. ## How it works Upstack Flows posts events to Klaviyo's API as **custom metrics** and creates or updates Klaviyo **profiles** with identity data resolved by Upstack ID. When the Upstack Pixel sees an anonymous visitor add to cart, identity resolution attempts to match the session to a known customer — using cookies, click IDs, and cross-session behavioral data — and attaches the email before the event is forwarded to Klaviyo. Klaviyo then has enough information to trigger flows that would otherwise never fire. Profiles synced from Upstack include standard properties (`$first_name`, `$last_name`, `$city`, `$region`) plus custom properties from Upstack's identity resolution, so they are immediately usable for segmentation. ## How Upstack works with Klaviyo Klaviyo already knows many of your customers. Upstack builds on that: anyone who clicks a Klaviyo email gets looked up and resolved through Upstack's identity engine. * **Identity enrichment.** Upstack hooks into Klaviyo to attach resolved identity data to every event it sends. * **Re-identification.** When a returning visitor can't be identified by standard Klaviyo tracking — cookies expired, new device, different browser — Upstack re-identifies them and fires enriched events back to Klaviyo. * **Backup abandonment flows.** These enriched events trigger a second set of abandonment flows that only fire for visitors Klaviyo couldn't identify on its own. * **Result.** Roughly 40% more people flow back through your abandonment sequences. <Info> The Upstack team handles Klaviyo flow setup during onboarding. They'll request access to your Klaviyo account and configure UTM tracking, flow cloning, triggers, and exclusion filters. The setup guides above describe what gets configured so you understand the setup. </Info> ## Best practices <Tip> **Expand to 5-email sequences.** Many brands run 1–2 emails per abandonment flow. Adding more touchpoints captures revenue from slower decision-makers. </Tip> <Tip> **Reduce the re-entry window.** Drop from 14 days to roughly 5 days. If someone comes back and abandons again, put them back in the flow — they're still shopping. </Tip> <Warning> **Disable flows from previous tools.** If you previously used Elevar, Triple Whale, or another tool that created secondary Klaviyo flows, disable those flows before enabling Upstack's. Running both causes duplicate emails. </Warning> ## Setup guides <CardGroup> <Card title="Klaviyo onboarding guide" icon="route" href="/guides/klaviyo/complete-how-to-guide-for-onboarding-klaviyo-in-upstack-data"> End-to-end walkthrough for connecting Klaviyo to Upstack Data. </Card> <Card title="Configure Klaviyo destination" icon="sliders" href="/guides/klaviyo/how-to-configure-klaviyo-destination-in-upstack-data"> Configure the Klaviyo destination inside Upstack Data. </Card> <Card title="Generate Klaviyo API key" icon="key" href="/guides/klaviyo/how-to-generate-klaviyo-api-key-for-upstack-data"> Create a Klaviyo private API key with the right scopes for Upstack. </Card> <Card title="Set up abandonment flows" icon="bell" href="/guides/klaviyo-abandonment-flows/complete-guide-to-setting-up-upstack-abandonment-flows-in-klaviyo"> Build the recommended Klaviyo flows powered by Upstack-enriched events. </Card> <Card title="Clone standard flows" icon="copy" href="/guides/klaviyo-abandonment-flows/how-to-clone-your-standard-flows-in-klaviyo"> Clone Klaviyo's standard flows as a starting point for Upstack-powered versions. </Card> <Card title="Cross-flow exclusion filters" icon="filter" href="/guides/klaviyo-abandonment-flows/how-to-add-cross-flow-exclusion-filters-in-klaviyo"> Prevent the same visitor from receiving overlapping flow messages. </Card> <Card title="Enable UTM tracking" icon="link" href="/guides/klaviyo-abandonment-flows/how-to-enable-utm-tracking-in-klaviyo"> Tag Klaviyo flow links with UTMs so attribution flows back into Upstack. </Card> </CardGroup> ## Event mapping | Upstack event | Klaviyo metric | Key properties | Notes | | ------------------ | ------------------ | ------------------------------------------------------------ | --------------------------------------- | | `ViewContent` | `Viewed Product` | `ProductName`, `ProductID`, `Price`, `ImageURL` | Powers browse abandonment flows | | `AddToCart` | `Added to Cart` | `ProductName`, `ProductID`, `Price`, `Quantity`, `CartValue` | Powers abandoned cart flows | | `InitiateCheckout` | `Started Checkout` | `CartValue`, `ItemCount`, `CheckoutURL` | Powers checkout abandonment flows | | `Purchase` | `Placed Order` | `OrderID`, `Revenue`, `Items`, `DiscountCodes` | Powers post-purchase and win-back flows | Upstack also syncs profile properties (`$first_name`, `$last_name`, `$city`, `$region`) plus custom properties derived from identity resolution. These are available for Klaviyo segmentation immediately after sync. ## FAQ <AccordionGroup> <Accordion title="How does Upstack increase the number of abandoned cart flows that fire?"> Shopify can only fire Klaviyo's abandoned cart flow when it knows the visitor's email — typically because the visitor logged in or reached the email step in checkout. Upstack identifies many more visitors than that by matching anonymous sessions to known customer profiles using cookies, click IDs, and cross-session behavior. When Upstack identifies an anonymous cart with an email, it forwards an enriched `Added to Cart` event to Klaviyo, which lets the abandoned cart flow fire on visitors that Shopify could not identify. </Accordion> <Accordion title="Will I see duplicate events if Klaviyo's native Shopify integration is also active?"> You can. The recommended approach is to disable the Klaviyo metrics in Shopify's native integration that overlap with the events Upstack is forwarding (`Viewed Product`, `Added to Cart`, `Started Checkout`, `Placed Order`). Keep the native integration enabled for any events Upstack is not handling. </Accordion> <Accordion title="What permissions does the Klaviyo API key need?"> Upstack only needs three scopes on the private API key: `Events: Write`, `Profiles: Write`, and `Lists: Write`. Avoid using a full-access key — least-privilege scopes keep the integration safe. The setup guide above walks through generating the key with the correct scopes. </Accordion> <Accordion title="Are new profiles created in Klaviyo, or only existing ones updated?"> Both, by default. When Upstack identifies a visitor with an email that does not yet exist in Klaviyo, it creates a new Klaviyo profile. When the email already exists, Upstack enriches the existing profile with new properties and event history. You can disable either behavior in the destination settings. </Accordion> <Accordion title="How do I know events are arriving in Klaviyo?"> In Klaviyo, open **Analytics → Metrics**. Upstack-forwarded events appear as custom metrics (for example, `Added to Cart` from Upstack) and start populating within a few minutes of storefront activity. To trace a specific visitor, find the profile in Klaviyo and check the **Activity Feed**. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="Upstack events not appearing in Klaviyo"> If events are showing in the Upstack Live Event Stream but not arriving in Klaviyo: **Steps to fix:** 1. Confirm the Klaviyo destination shows **Active** (green) in the Upstack dashboard 2. Verify your Private API key has the required scopes (`Events: Write`, `Profiles: Write`, `Lists: Write`) — read-only keys cannot receive events 3. In Klaviyo, go to **Analytics → Metrics** and search for events containing "Upstackified" — they may be arriving under a different name than expected 4. If the destination status is red, disconnect and reconnect with a fresh API key </Accordion> <Accordion title="Duplicate abandonment emails"> Customers receiving emails from both your standard flows and Upstack flows means mutual exclusion filters are missing or misconfigured. **Steps to fix:** 1. Open both the standard and Upstack versions of the flow in Klaviyo 2. Verify each flow has a cross-flow exclusion filter: "Has received email 0 times in last 7 days where Flow = \[other flow name]" 3. If filters are in place but duplicates persist, check that the flow names in the filters match exactly (including the " - Upstack Data" suffix) 4. Disable flows from previous tools (Elevar, Triple Whale) if they are still active </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond Klaviyo-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Data enrichment" icon="magnifying-glass-plus" href="/concepts/data-enrichment"> How Upstack Enrichment improves visitor identification — the foundation of Flows recovery. </Card> <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack ID connects anonymous sessions to known customers with email addresses. </Card> <Card title="Destinations overview" icon="arrow-right-from-bracket" href="/destinations/overview"> How Upstack Signal and Upstack Flows power different types of destinations. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # LinkedIn Conversions API Source: https://docs.upstackdata.com/destinations/linkedin Send conversion events to LinkedIn's Conversions API for ad campaign optimization, audience building, and attribution — powered by Upstack Signal. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does LinkedIn's Conversions API is the server-side counterpart to the LinkedIn Insight Tag. Upstack Signal forwards storefront events — page views, product views, add-to-carts, and purchases — directly to LinkedIn's servers, bypassing browser restrictions like ad blockers, ITP, and cookie limits. Server-side delivery gives LinkedIn's algorithm a fuller picture of the conversions your ads actually drove, which improves campaign optimization, audience modeling, and attribution accuracy. Match rates from server-side events are consistently higher than browser-only tracking because each event carries hashed customer data and the `li_fat_id` click identifier when available. <Note> Unlike Meta and TikTok, LinkedIn uses **Conversion Rule IDs** to track specific conversion types. You'll need to create conversion rules in Campaign Manager and map them to event types in Upstack. </Note> ## How it works Upstack runs as a dual-tracking layer alongside the LinkedIn Insight Tag. The Upstack Pixel captures events in the browser and forwards each event to Upstack's edge infrastructure, where it is hashed, enriched with identity and click-ID data, and sent to the LinkedIn Conversions API as a server-side event with a shared `eventId`. Upstack authenticates with LinkedIn using a **Direct Access Token** that you generate inside Campaign Manager → **Data** → **Signals Manager** → **Conversions API** — no LinkedIn Developer app or OAuth setup required. The token grants the **Manage conversions** permission for the ad accounts you select and lasts until the expiry you choose (we recommend 1 year). See [How to generate a LinkedIn Conversions API token](/guides/linkedin-ads/how-to-generate-linkedin-conversion-api-token). LinkedIn deduplicates server events against matching browser Insight Tag events using that `eventId`, so you do not double-count conversions as long as both sources use the same Partner ID. PII (`email`) is hashed with SHA-256 before delivery, as required by the Conversions API. ## Setup guides <CardGroup> <Card title="Onboarding guide" icon="route" href="/guides/linkedin-ads/complete-how-to-guide-for-onboarding-linkedin-in-upstack-data"> End-to-end walkthrough for connecting LinkedIn to Upstack Data. </Card> <Card title="Configure destination" icon="sliders" href="/guides/linkedin-ads/how-to-configure-linkedin-destination-in-upstack-data"> Configure the LinkedIn destination inside Upstack Data. </Card> <Card title="Find Partner ID" icon="magnifying-glass" href="/guides/linkedin-ads/how-to-find-linkedin-partner-id"> Locate your LinkedIn Partner ID in Campaign Manager. </Card> <Card title="Create Conversion Rules" icon="bullseye" href="/guides/linkedin-ads/how-to-create-linkedin-conversion-rules"> Create conversion rules for tracking specific event types. </Card> <Card title="Generate API token" icon="key" href="/guides/linkedin-ads/how-to-generate-linkedin-conversion-api-token"> Generate the Conversions API access token Upstack uses to send events. </Card> <Card title="Enable click ID tracking" icon="link" href="/guides/linkedin-ads/how-to-enable-linkedin-click-id-tracking"> Enable enhanced conversion tracking for `li_fat_id` click IDs. </Card> </CardGroup> ## Event mapping Upstack maps storefront events to LinkedIn standard events automatically: | Upstack event | LinkedIn event | Key match data | | ---------------------- | ----------------- | ---------------------------------------------- | | `PageView` | (via Insight Tag) | URL, referrer, user agent | | `ViewContent` | `VIEW_CONTENT` | `content_ids`, `value`, `currency` | | `AddToCart` | `ADD_TO_CART` | `content_ids`, `value`, `currency` | | `InitiateCheckout` | `START_CHECKOUT` | `value`, `currency`, `num_items` | | `Purchase` | `PURCHASE` | `value`, `currency`, `order_id`, `content_ids` | | `Lead` | `LEAD` | `email`, `phone` | | `CompleteRegistration` | `SIGN_UP` | `email` | PII is hashed with SHA-256 before it leaves Upstack. Upstack includes every available match key on every event — hashed `email`, `li_fat_id` (LinkedIn click ID), `ip_address`, and `user_agent` — to maximize match quality. ## FAQ <AccordionGroup> <Accordion title="What is the difference between Partner ID and Conversion Rule ID?"> The **Partner ID** identifies your LinkedIn ad account's Insight Tag — it's the same ID used for browser-side tracking. The **Conversion Rule ID** identifies a specific conversion action you want to track (e.g., Purchase, Lead, Sign Up). You'll have one Partner ID but multiple Conversion Rule IDs, one for each event type. </Accordion> <Accordion title="How do I get my API Access Token?"> Generate a **Direct Access Token** in Campaign Manager → **Data** → **Signals Manager** → **Conversions API**, then paste it into the **API Access Token** field of your Upstack LinkedIn destination. See the step-by-step [How to generate a LinkedIn Conversions API token](/guides/linkedin-ads/how-to-generate-linkedin-conversion-api-token) guide. </Accordion> <Accordion title="How long does the token last?"> Direct Access Tokens expire based on the duration you choose when generating them. We recommend setting the expiry to **1 year** to minimize rotation. When a token expires, the destination turns Unhealthy and events return a `401` error — generate a new token with the same settings and update the destination. </Accordion> <Accordion title="What permissions does the token need?"> The token needs the **Manage conversions** permission and access to the ad account that owns your Conversion Rules. Without this permission, events return a `403` error. </Accordion> <Accordion title="How do I know events are reaching LinkedIn?"> Open LinkedIn Campaign Manager → **Data** → **Signals Manager** → **Signal Diagnostics**. Server-side events appear with status "Received" and show match quality metrics. Upstack also surfaces delivery status inside the destination settings. </Accordion> <Accordion title="Will I see duplicate conversions if I run both the Insight Tag and Conversions API?"> No — as long as the Partner ID in Upstack matches the Partner ID in your Insight Tag. Upstack sends a shared `eventId` on every server-side event, and LinkedIn's deduplication logic matches events by `eventId` and keeps only one. </Accordion> <Accordion title="Why do I need separate Conversion Rules for browser and server events?"> LinkedIn's deduplication works by matching `eventId` across browser and server events **within the same Conversion Rule**. If you use the same Conversion Rule for both sources, deduplication works automatically. However, some merchants prefer separate rules for A/B testing or validation — in that case, browser events go to one rule and server events to another. </Accordion> <Accordion title="What if my event match rate is low?"> LinkedIn's match rate depends on how much identity data each event carries. Common causes of low match quality: * **Missing `li_fat_id`** — LinkedIn ads should link directly to your storefront so the click ID lands in the URL and is captured by the Upstack Pixel. * **Anonymous visitors** — events from visitors without email have fewer keys to match against. Match rates improve as more identified customers convert. * **Missing checkout fields** — make sure your Shopify checkout collects email; it's the strongest server-side match key for LinkedIn. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="Events not appearing in LinkedIn Signal Diagnostics"> If events aren't appearing after 10 minutes of confirmed store traffic, check the basics first. **Steps to fix:** 1. Go to **Integrations → Destinations → LinkedIn** 2. Verify the **Partner ID**, **API Access Token**, and **Conversion Rule IDs** are correct (no extra spaces or truncated characters) 3. Confirm the destination status is Active (green) 4. If the token was revoked or expired, generate a new one in Campaign Manager and update the destination 5. Verify conversion rules are associated with at least one active campaign </Accordion> <Accordion title="API errors (401, 403)"> | Error Code | Meaning | Solution | | ---------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | 401 | Invalid or expired token | Generate a new Direct Access Token in Campaign Manager → Data → Signals Manager → Conversions API | | 403 | Permission denied | Ensure token has "Manage conversions" permission and access to the correct ad account | | 422 | Invalid payload | Verify conversion URN format (`urn:lla:llaPartnerConversion:{id}`), timestamp is within 90 days, and at least one user identifier is present | </Accordion> <Accordion title="Token expired"> Direct Access Tokens expire based on the duration you set during generation (default 1 year). To renew: 1. Go to Campaign Manager → Data → Signals Manager → Conversions API 2. Generate a new token with same settings 3. Update the token in Upstack Data destination settings </Accordion> <Accordion title="Low match quality scores"> LinkedIn's match quality measures how well server events match to LinkedIn users. **Common causes:** * **High anonymous traffic** — Events from visitors who haven't provided contact info have fewer matching parameters. Match quality improves as more identified customers generate events. * **Missing click IDs** — Enable enhanced conversion tracking in Insight Tag settings to capture `li_fat_id` from ad clicks. * **Incorrect Partner ID** — If the Partner ID doesn't match the one associated with your ad account, events arrive but can't be matched to campaign data. Match quality typically improves over 1–2 weeks as Upstack's identity resolution builds visitor profiles. </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond LinkedIn-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack matches anonymous visitors to known customers for higher match rates. </Card> <Card title="Meta CAPI destination" icon="meta" href="/destinations/meta-capi"> Set up Meta's Conversions API as another server-side destination alongside LinkedIn. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Loops Source: https://docs.upstackdata.com/destinations/loops Forward identity-resolved customer events to Loops to trigger email automations, transactional emails, and marketing campaigns based on real-time e-commerce activity. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> Loops is connected through **Upstack Flows**, the product that handles event delivery to marketing automation platforms. Upstack identifies visitors that standard tracking misses — turning anonymous browse and cart abandonment sessions into actionable Loops contacts with email addresses attached. This means more automated email workflows fire, more transactional messages reach the right customers, and you recover revenue that would otherwise be invisible. ## How It Works When a visitor takes an action on your store, Upstack: 1. Captures the event through the Upstack Pixel and matches it to a known visitor profile using Upstack's identity resolution. 2. If the visitor is identified (email available), enriches the event with the contact's email and any other known properties. 3. Sends the event to Loops using your Loops API key as a trackable event that can trigger automations. 4. Optionally creates or updates the contact in Loops so it can be segmented and used in campaigns. The result: email automations fire for visitors that standard tracking misses. ## Supported Events | Upstack Event | Loops Event | Key Properties | Use Case | | ------------------ | ------------------ | ------------------------------------------------------------ | -------------------- | | `ViewContent` | `Viewed Product` | `ProductName`, `ProductID`, `Price`, `ImageURL` | Browse abandonment | | `AddToCart` | `Added to Cart` | `ProductName`, `ProductID`, `Price`, `Quantity`, `CartValue` | Abandoned cart | | `InitiateCheckout` | `Started Checkout` | `CartValue`, `ItemCount`, `CheckoutURL` | Checkout abandonment | | `Purchase` | `Placed Order` | `OrderID`, `Revenue`, `Items`, `DiscountCodes` | Post-purchase flows | Upstack also syncs profile properties including name, email, and location data. These are available for Loops segmentation immediately after sync. ## Credentials | Field | Required | Description | | ------- | -------- | ------------------------------------------------------------- | | API Key | Yes | Your Loops API key for authenticating event and contact syncs | <Info> Your Loops API key can be found in your Loops account under **Settings → API**. Generate a key with write access to events and contacts. </Info> ## Set Up Loops <Steps> <Step title="Get your Loops API key"> 1. Log in to your [Loops account](https://loops.so/) 2. Navigate to **Settings → API** 3. Click **Create API Key** if you don't have one 4. Copy the API key — you'll need it in the next step </Step> <Step title="Add Loops as a destination in Upstack"> 1. In the Upstack dashboard, go to **Destinations** 2. Click **Add Destination** and select **Loops** 3. Paste your Loops API key in the **API Key** field 4. Click **Save** to enable the destination </Step> <Step title="Verify events are flowing"> 1. Trigger a test action on your store (view a product, add to cart) 2. In Loops, check **Events** to see incoming events 3. In Upstack, check the Live Event Stream to confirm events show as delivered to Loops </Step> </Steps> ## FAQ <AccordionGroup> <Accordion title="What is Loops?"> Loops is an email marketing and automation platform designed for modern SaaS and e-commerce businesses. It allows you to create automated email sequences triggered by user behavior, send transactional emails, and manage marketing campaigns — all through a simple API-first interface. </Accordion> <Accordion title="How is this different from connecting Loops directly to Shopify?"> Standard Shopify integrations only see visitors that Shopify has identified — typically logged-in customers or shoppers who have entered an email at checkout. Upstack's identity resolution matches anonymous sessions to known customer profiles using cookies, click IDs, and cross-session behavioral data, then sends those events to Loops with the contact's email attached. This lets your automated workflows fire for many more visitors. </Accordion> <Accordion title="What permissions does the Loops API key need?"> The Loops API key must have permission to write events and contacts. When creating your API key in Loops, ensure it has the scopes required to send events and create or update contacts. </Accordion> <Accordion title="How long does it take for events to appear in Loops?"> Once the destination is active, events typically appear in Loops within a few minutes. You can verify by triggering a test action on your store (such as adding a product to cart) and checking the Events section in Loops. </Accordion> <Accordion title="Can I send custom events to Loops?"> Yes. Any event tracked by the Upstack Pixel can be configured to forward to Loops. Contact support if you need to send custom events beyond the standard e-commerce events. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="Events not appearing in Loops"> If events show in the Upstack Live Event Stream but aren't arriving in Loops: **Steps to fix:** 1. Confirm the Loops destination shows **Active** (green) in the Upstack dashboard 2. Verify your API key is valid — try regenerating it in Loops if you're unsure 3. Check the Events section in Loops — events may appear under a different name than expected 4. If the destination status is red, disconnect and reconnect with a fresh API key </Accordion> <Accordion title="Contacts not being created in Loops"> If events are arriving but contacts aren't being created: **Steps to fix:** 1. Ensure the API key has permission to create contacts 2. Verify that Upstack has resolved an email address for the visitor — anonymous events without an email won't create contacts 3. Check if the contact already exists in Loops under a different email or identifier </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond Loops-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Data Enrichment" icon="magnifying-glass-plus" href="/concepts/data-enrichment"> How Upstack Enrichment improves visitor identification — the foundation of Flows recovery. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack ID connects anonymous sessions to known customers with email addresses. </Card> <Card title="Klaviyo Destination" icon="envelope" href="/destinations/klaviyo"> Sync events and contacts to Klaviyo using the same Upstack Flows pipeline. </Card> <Card title="Events Not Reaching Destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Meta Conversions API (CAPI) Source: https://docs.upstackdata.com/destinations/meta-capi Send server-side conversion events to Meta Ads with Upstack Signal — improve Event Match Quality and campaign optimization. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does Meta's Conversions API (CAPI) lets you send conversion events directly from a server to Meta, instead of relying solely on the browser-side Pixel. Upstack Signal forwards every storefront event — page views, product views, add-to-carts, checkouts, and purchases — to your Meta Pixel via CAPI, enriched with hashed customer data and click identifiers. For most Shopify merchants, Meta CAPI is the highest-impact destination you can connect. Events captured server-side reach Meta even when the browser Pixel is blocked by ad blockers, ITP, or cookie restrictions, which means Meta's algorithm sees a fuller picture of the conversions your ads actually drove. The practical result is higher Event Match Quality (EMQ), more accurate ROAS reporting inside Meta Ads Manager, and stronger optimization signal for campaigns that depend on conversion events. ## How it works Upstack Signal runs as a dual-tracking layer. The Upstack Pixel captures events in the browser and forwards each one to Upstack's edge infrastructure, where it is hashed, enriched with identity and attribution data, and then sent to Meta's Conversions API as a server-side event with a shared `event_id`. Meta deduplicates against any matching browser Pixel event using that ID, so you do not double-count. Every event carries the strongest available match keys — hashed `email`, `phone`, `first_name`, `last_name`, `city`, `state`, `zip`, `country`, plus `fbc`, `fbp`, and `external_id` — so Meta can attribute the conversion to the right user and ad interaction. ## Setup guides <CardGroup> <Card title="Onboarding guide" icon="route" href="/guides/facebook-ads/complete-how-to-guide-for-onboarding-facebook-meta-in-upstack-data"> End-to-end walkthrough for connecting Meta to Upstack Data. </Card> <Card title="Configure pixel destination" icon="sliders" href="/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data"> Configure the Meta Pixel destination inside Upstack Data. </Card> <Card title="Find Pixel Dataset ID" icon="magnifying-glass" href="/guides/facebook-ads/how-do-i-find-my-facebook-ads-pixel-dataset-id"> Locate your Meta Pixel Dataset ID in Events Manager. </Card> <Card title="Generate CAPI key" icon="key" href="/guides/facebook-ads/how-to-generate-my-facebook-conversion-api-key"> Generate a Conversions API access token in Meta. </Card> <Card title="Update CAPI key" icon="rotate" href="/guides/facebook-ads/how-to-update-facebook-meta-conversion-api-key"> Rotate or replace your existing CAPI access token. </Card> <Card title="Disable Shopify FB data sharing" icon="ban" href="/guides/facebook-ads/how-to-disable-facebook-and-instagram-data-sharing-in-shopify"> Turn off Shopify's native Facebook integration to prevent duplicate events. </Card> <Card title="Approve custom events" icon="circle-check" href="/guides/facebook-ads/how-to-approve-facebook-meta-custom-events"> Approve Upstack's custom events inside Meta Events Manager. </Card> </CardGroup> ## Event mapping Upstack maps storefront events to Meta standard events automatically: | Upstack event | Meta standard event | Key match data | | ------------------ | ------------------- | -------------------------------------------------- | | `PageView` | `PageView` | URL, referrer, user agent | | `ViewContent` | `ViewContent` | `content_ids`, `content_type`, `value`, `currency` | | `AddToCart` | `AddToCart` | `content_ids`, `value`, `currency` | | `InitiateCheckout` | `InitiateCheckout` | `value`, `currency`, `num_items` | | `Purchase` | `Purchase` | `value`, `currency`, `order_id`, `content_ids` | PII is hashed with SHA-256 before it leaves Upstack. Upstack includes every available match key on every event — `em`, `ph`, `fn`, `ln`, `ct`, `st`, `zp`, `country`, `fbc`, `fbp`, `external_id` — to maximize EMQ. ## FAQ <AccordionGroup> <Accordion title="What is Event Match Quality (EMQ) and why does it matter?"> EMQ is Meta's score (1–10) for how reliably it can match a conversion event back to a Meta user. Higher EMQ means Meta's algorithm has more signal to optimize against, which lowers cost per acquisition and improves ROAS. Server-side delivery via CAPI typically lifts EMQ by 20–35% compared to a browser-only Pixel because the events carry more match keys and are not blocked by browser restrictions. </Accordion> <Accordion title="Why send events through CAPI when I already have the Meta Pixel?"> The browser Pixel is blocked or degraded by ad blockers, Safari ITP, iOS privacy features, and third-party cookie restrictions. CAPI runs server-to-server, so it is not affected by any browser-side limitation. Meta itself recommends running CAPI alongside the Pixel for redundancy and higher data quality. </Accordion> <Accordion title="Will my events be counted twice if I run both the Pixel and CAPI?"> No. Upstack sends a shared `event_id` on every server-side event, and Meta deduplicates against the matching browser Pixel event with the same ID. As long as the Pixel ID in Upstack matches the Pixel ID firing in your storefront, deduplication is automatic. </Accordion> <Accordion title="Do I need to disable Shopify's native Facebook integration?"> Yes — if Shopify is also sending purchase events to the same Meta Pixel, you'll see duplicates that Meta cannot deduplicate (Shopify does not emit a matching `event_id`). Follow the guide above to disable Facebook & Instagram data sharing in Shopify before activating Upstack's Meta destination. </Accordion> <Accordion title="How do I verify CAPI events are arriving in Meta?"> Open Meta Events Manager, select your Pixel, and check the **Overview** and **Test Events** tabs. Server-side events show up with a "Server" badge. Upstack also surfaces delivery status and EMQ inside the destination settings in your dashboard. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack matches anonymous visitors to known customers for higher match rates. </Card> <Card title="TikTok Events API" icon="tiktok" href="/destinations/tiktok"> Set up TikTok's Events API as another server-side destination alongside Meta. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # NewsBreak Ads Source: https://docs.upstackdata.com/destinations/newsbreak Send conversion events to NewsBreak's postback API for native advertising campaign optimization — powered by Upstack Signal. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does NewsBreak's Server-to-Server Postback API is the conversion tracking method for their native advertising platform. Unlike other ad platforms, NewsBreak uses a simple GET-based postback rather than a full browser pixel SDK. Upstack Signal forwards purchases, add-to-carts, and other conversion events directly to NewsBreak's servers, bypassing browser ad blockers and giving NewsBreak's algorithm stronger signal for campaign optimization. Server-side delivery means conversions reach NewsBreak even when browser tracking is blocked by ad blockers, ITP, or cookie restrictions. Each event carries the click identifier (`nbclid`) captured from ad clicks so NewsBreak can match the conversion back to the ad interaction that drove it. <Warning> **Important limitation:** Unlike Meta, TikTok, Google, Reddit, and other ad platforms, NewsBreak does **NOT** support enhanced matching via hashed email, phone, or other PII. Attribution relies **solely on the click ID (`nbclid`)** captured from ad clicks. Events without a click ID cannot be attributed and are skipped. </Warning> ## How it works Upstack Signal captures and stores the NewsBreak click ID when visitors land from a NewsBreak ad. When a visitor takes an action on your store: 1. Captures the NewsBreak click ID (`nbclid`) when the visitor lands from a NewsBreak ad. 2. Stores the click ID in a first-party cookie for attribution across sessions. 3. On conversion events, sends the event to NewsBreak's postback endpoint with the click ID. 4. Logs the response so you can monitor delivery status from the Upstack dashboard. **Attribution model:** NewsBreak uses last-click attribution based solely on the `nbclid` parameter. Cross-device conversions, cookieless conversions, and conversions from returning visitors whose cookies expired **cannot be attributed** to NewsBreak campaigns. ## Setup guides <CardGroup> <Card title="Onboarding guide" icon="route" href="/guides/newsbreak-ads/complete-how-to-guide-for-onboarding-newsbreak-in-upstack-data"> End-to-end walkthrough for connecting NewsBreak to Upstack Data. </Card> <Card title="Configure destination" icon="sliders" href="/guides/newsbreak-ads/how-to-configure-newsbreak-destination-in-upstack-data"> Configure the NewsBreak destination inside Upstack Data. </Card> <Card title="Find Pixel ID" icon="magnifying-glass" href="/guides/newsbreak-ads/how-to-find-newsbreak-pixel-id"> Locate your NewsBreak Pixel ID in the Ad Manager Event Management. </Card> <Card title="Configure click ID tracking" icon="link" href="/guides/newsbreak-ads/how-to-configure-newsbreak-click-id-tracking"> Add the click ID parameter to your campaign URL suffix. </Card> </CardGroup> ## Event mapping Upstack maps storefront events to NewsBreak postback event types automatically: | Upstack event | NewsBreak event | Key parameters | Notes | | ------------------ | ------------------- | -------------------------------- | ------------------------ | | `Purchase` | `complete_payment` | `callback`, `nb_value` (revenue) | Primary conversion event | | `NC Purchase` | `complete_payment` | `callback`, `nb_value` (revenue) | New customer purchase | | `AddToCart` | `add_to_cart` | `callback` (click ID) | Cart additions | | `InitiateCheckout` | `initiate_checkout` | `callback` (click ID) | Checkout started | | `Lead` | `submit_form` | `callback` (click ID) | Form submissions | | `SignUp` | `subscribe` | `callback` (click ID) | Account registration | | `Subscribe` | `subscribe` | `callback` (click ID) | Newsletter signup | | `AddToWishlist` | `add_to_wishlist` | `callback` (click ID) | Wishlist additions | Every event includes the NewsBreak click ID (`nbclid`) when available. **Events without a click ID are skipped** because NewsBreak cannot attribute them to any campaign. <Note> NewsBreak only supports conversion events. Page views, content views, and browsing events are not supported. Revenue is only sent for purchase events via the `nb_value` parameter. </Note> ## FAQ <AccordionGroup> <Accordion title="Why is there no browser pixel for NewsBreak?"> NewsBreak does not provide a public JavaScript SDK like Meta (`fbq`) or TikTok (`ttq`). Their recommended integration method is server-side postbacks using the click ID captured from your landing page URL. Upstack handles all server-side delivery automatically once you configure the destination. </Accordion> <Accordion title="What if a visitor doesn't have a NewsBreak click ID?"> Without a click ID, NewsBreak cannot attribute the conversion to an ad click. This typically happens when visitors arrive through organic traffic or when the `nbclid` parameter is stripped from URLs (e.g., by link shorteners or redirects). Upstack will skip sending events for visitors without a captured click ID to avoid errors. </Accordion> <Accordion title="How do I verify events are arriving in NewsBreak?"> Open NewsBreak Ad Manager, navigate to **Tools → Event Management**, and check that events are appearing. Server-side events should start appearing within 5–10 minutes of storefront activity. Note that test events won't show up in the dashboard — conversions only register when a real user clicks on your ad. </Accordion> <Accordion title="Why are my attribution rates lower than other platforms?"> NewsBreak does not support enhanced matching with hashed PII (email, phone, IP, user-agent). Attribution relies **solely** on the click ID (`nbclid`). If a visitor clears cookies, uses a different device, or the click ID expires, the conversion cannot be attributed. This is a platform limitation, not an Upstack issue. </Accordion> <Accordion title="Does NewsBreak support event deduplication?"> NewsBreak does not have built-in event deduplication like Meta or TikTok. Instead, configure your events in NewsBreak's Event Management with the appropriate counting mode: "Every" (all conversions) or "Once" (unique users only). Since Upstack is server-side only, there is no browser pixel that could fire duplicate events. </Accordion> <Accordion title="What are NewsBreak's rate limits?"> NewsBreak enforces rate limits based on your account tier: | Tier | QPS | QPM | QPD | | -------- | --- | ----- | --------- | | Basic | 10 | 600 | 864,000 | | Advanced | 20 | 1,200 | 1,728,000 | | Premium | 30 | 1,800 | 2,592,000 | Upstack automatically handles rate limiting with exponential backoff and retries failed events. For high-volume accounts, contact NewsBreak about upgrading your tier. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="No conversions appearing in NewsBreak dashboard"> If events aren't appearing after confirmed store traffic: **Steps to fix:** 1. Verify your campaign URL suffix includes `nbclid=__CALLBACK_PARAM__` 2. Confirm the Upstack destination shows **Active** (green) 3. Check that the `_nbclid` cookie is being set on your storefront (inspect browser cookies) 4. Test with a real ad click — test traffic without `nbclid` in the URL won't generate events 5. Wait up to 24 hours — NewsBreak may take time to process and display events </Accordion> <Accordion title="No conversions attributed to ads"> Conversions are showing in NewsBreak but not attributed to campaigns: **Steps to fix:** 1. Verify your NewsBreak ad URLs use the correct macro: `?nbclid=__CALLBACK_PARAM__` 2. Confirm the event type in Upstack matches the event configured in NewsBreak Event Management 3. Check that you're not using link shorteners or redirects that strip URL parameters 4. Verify the attribution window in NewsBreak hasn't expired for old click IDs </Accordion> <Accordion title="Low attribution rate compared to other platforms"> This is expected due to NewsBreak's click-ID-only attribution model. **To maximize attribution:** * Ensure all campaigns include `nbclid=__CALLBACK_PARAM__` in the URL suffix * Verify the Upstack Pixel is loading on all pages to capture click IDs * Check that first-party cookies are not being blocked by browser settings * Note that cross-device and returning-visitor conversions will not be attributed </Accordion> <Accordion title="Rate limit errors (code 4034)"> If you see rate limit errors in Upstack logs: **Steps to fix:** 1. Upstack automatically retries with exponential backoff — most rate limit errors resolve on their own 2. If errors persist during peak traffic, consider spreading campaigns across time zones 3. Contact NewsBreak support ([adsupport@newsbreak.com](mailto:adsupport@newsbreak.com)) about upgrading to Advanced or Premium tier for higher limits </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond NewsBreak-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack matches anonymous visitors to known customers for higher match rates. </Card> <Card title="Outbrain destination" icon="rectangle-ad" href="/destinations/outbrain"> Set up Outbrain — another native advertising platform with click-ID-only attribution. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Omnisend Source: https://docs.upstackdata.com/destinations/omnisend Forward identity-resolved customer events and profiles to Omnisend to power email and SMS automation, abandoned cart recovery flows, and workflow triggers via the Omnisend API. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> Omnisend is connected through **Upstack Flows**, the product that handles event delivery to marketing automation platforms. The key value: Upstack identifies visitors that Shopify and Omnisend's native integration miss — turning anonymous browse and cart abandonment sessions into actionable Omnisend contacts with email addresses attached. This means more abandoned cart workflows fire, more browse abandonment messages send, and you recover revenue that would otherwise be invisible. ## How It Works When a visitor takes an action on your store, Upstack: 1. Captures the event through the Upstack Pixel and matches it to a known visitor profile using Upstack's identity resolution. 2. If the visitor is identified (email available), enriches the event with the contact's email and any other known properties. 3. Sends the event to Omnisend using your Omnisend API key as a trackable activity that can trigger workflows. 4. Optionally creates or updates the contact in Omnisend so it can be segmented and messaged. The result: abandoned cart and browse abandonment workflows fire for visitors that Shopify's native tracking misses. ## Set Up Omnisend Follow the onboarding guide for the full end-to-end setup, or jump to a specific step. <CardGroup> <Card title="Onboarding guide" icon="book" href="/guides/omnisend/complete-how-to-guide-for-onboarding-omnisend-in-upstack-data"> Complete step-by-step walkthrough for connecting Omnisend to Upstack. </Card> <Card title="Configure destination" icon="sliders" href="/guides/omnisend/how-to-configure-omnisend-pixel-destination-in-upstack-data"> Add and configure the Omnisend destination inside the Upstack dashboard. </Card> <Card title="Generate API key" icon="key" href="/guides/omnisend/how-to-generate-your-omnisend-api-key"> Generate the Omnisend API key Upstack uses to sync events and contacts. </Card> </CardGroup> ## FAQ <AccordionGroup> <Accordion title="How is this different from Omnisend's native Shopify integration?"> Omnisend's native Shopify integration only sees visitors that Shopify has identified — typically logged-in customers or shoppers who have entered an email at checkout. Upstack's identity resolution matches anonymous sessions to known customer profiles using cookies, click IDs, and cross-session behavioral data, then sends those events to Omnisend with the contact's email attached. This lets your abandoned cart and browse abandonment workflows fire for many more visitors. </Accordion> <Accordion title="Will I get duplicate events if I keep Omnisend's native Shopify integration?"> Possibly. If both Upstack and Omnisend's native integration send the same event types, Omnisend may record both. The recommended approach is to disable the corresponding events in Omnisend's native integration for any event types Upstack is configured to send, and keep the native integration only for events you're not routing through Upstack. </Accordion> <Accordion title="What permissions does the Omnisend API key need?"> The Omnisend API key must have permission to write events and contacts. Use a key with the minimum scope required — Upstack does not need account management or billing permissions. Step-by-step instructions are in [Generate API key](/guides/omnisend/how-to-generate-your-omnisend-api-key). </Accordion> <Accordion title="How long does it take for events to appear in Omnisend?"> Once the destination is active, events typically appear in Omnisend within 5 minutes. You can verify by triggering a test action on your store (such as adding a product to cart) and checking the contact's activity feed in Omnisend. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Data Enrichment" icon="magnifying-glass-plus" href="/concepts/data-enrichment"> How Upstack Enrichment improves visitor identification — the foundation of Flows recovery. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack ID connects anonymous sessions to known customers with email addresses. </Card> <Card title="Klaviyo Destination" icon="envelope" href="/destinations/klaviyo"> Sync events and contacts to Klaviyo using the same Upstack Flows pipeline. </Card> <Card title="Events Not Reaching Destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Outbrain Amplify Source: https://docs.upstackdata.com/destinations/outbrain Send conversion events to Outbrain's Unified Pixel API for native advertising campaign optimization — powered by Upstack Signal. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does Outbrain's Unified Pixel API is the server-side counterpart to the Outbrain browser pixel. Upstack Signal forwards storefront events — page views, product views, add-to-carts, and purchases — directly to Outbrain's servers for native advertising campaign optimization. Server-side delivery means conversions reach Outbrain even when the browser-side pixel is blocked by ad blockers, ITP, or cookie restrictions. Each event carries the click identifier (`obclid`) captured from ad clicks so Outbrain can match the conversion back to the ad interaction that drove it. <Warning> **Important limitation:** Unlike Meta, TikTok, Google, Reddit, and other ad platforms, Outbrain does **NOT** support enhanced matching via hashed email, phone, or other PII. Attribution relies **solely on the click ID (`obclid`)** captured from ad clicks. Events without a click ID cannot be attributed and are skipped. </Warning> ## How it works Upstack Signal runs as a dual-tracking layer alongside the Outbrain browser pixel. The Upstack Pixel captures events in the browser and forwards each one to Upstack's edge infrastructure, where it is enriched with the Outbrain click ID from cookie storage and sent to Outbrain's Unified Pixel API as a server-side event. Unlike other ad platforms, Outbrain's deduplication relies on the `orderId` field rather than a shared `event_id`. Always include a transaction ID on purchase events to prevent double-counting when running both browser pixel and server-side delivery. **Attribution model:** Outbrain uses last-click attribution based solely on the `obclid` parameter. Cross-device conversions, cookieless conversions, and conversions from returning visitors whose cookies expired **cannot be attributed** to Outbrain campaigns. ## Setup guides <CardGroup> <Card title="Onboarding guide" icon="route" href="/guides/outbrain/complete-how-to-guide-for-onboarding-outbrain-in-upstack-data"> End-to-end walkthrough for connecting Outbrain to Upstack Data. </Card> <Card title="Configure destination" icon="sliders" href="/guides/outbrain/how-to-configure-outbrain-destination-in-upstack-data"> Configure the Outbrain destination inside Upstack Data. </Card> <Card title="Find Marketer ID" icon="magnifying-glass" href="/guides/outbrain/how-to-find-outbrain-marketer-id"> Locate your Outbrain Marketer ID in the Amplify Dashboard. </Card> <Card title="Configure click ID tracking" icon="link" href="/guides/outbrain/how-to-configure-outbrain-click-id-tracking"> Add the click ID parameter to your campaign URL suffix. </Card> </CardGroup> ## Event mapping Upstack maps storefront events to Outbrain events automatically: | Upstack event | Outbrain event | Key parameters | Notes | | ------------- | -------------- | --------------------------------------- | ---------------------------------------- | | `Purchase` | `Conversion` | `orderValue`, `currency`, `orderId` | Primary conversion event | | `Lead` | `Lead` | `orderValue`, `orderId` | Lead form submissions | | `SignUp` | `Sign_Up` | `orderId` | Account registration | | `AddToCart` | `AddToCart` | `productId`, `productValue`, `currency` | Cart additions | | `ViewContent` | `Content_View` | `productId`, `productValue` | Product page views (disabled by default) | | `PageView` | `PAGE_VIEW` | — | Page load (disabled by default) | Every event includes the Outbrain click ID (`obclid`) when available. **Events without a click ID are skipped** because Outbrain cannot attribute them to any campaign. ## Field mapping | Upstack field | Outbrain field | Type | Notes | | -------------------- | -------------- | ------ | --------------------------- | | `data.value` | `orderValue` | number | Transaction amount | | `data.currency` | `currency` | string | ISO 4217 (USD, EUR, GBP) | | `data.transactionId` | `orderId` | string | Unique ID for deduplication | | `item.id` | `productId` | string | Product SKU | | `item.name` | `productName` | string | Product name | | `item.category` | `category` | string | Product category | | `item.quantity` | `quantity` | number | Number of items | ## FAQ <AccordionGroup> <Accordion title="How do I verify events are arriving in Outbrain?"> Open Outbrain Amplify Dashboard, navigate to **Conversions**, and check that events are appearing. Server-side events should start appearing within 5–10 minutes of storefront activity. Note that test events won't show up in the dashboard — conversions only register when a real user clicks on your ad in the Outbrain widget. </Accordion> <Accordion title="Why are my attribution rates lower than other platforms?"> Outbrain does not support enhanced matching with hashed PII (email, phone, IP, user-agent). Attribution relies **solely** on the click ID (`obclid`). If a visitor clears cookies, uses a different device, or the click ID expires (after 30 days), the conversion cannot be attributed. This is a platform limitation, not an Upstack issue. </Accordion> <Accordion title="Will my events be counted twice if I run both the pixel and server-side?"> Outbrain deduplicates based on the `orderId` field. Always include a unique transaction ID on purchase events. If you're sending events from multiple sources (Upstack, GTM, direct pixel), ensure they all use the same `orderId` for the same transaction. </Accordion> <Accordion title="Do event names need to match exactly?"> Yes — event names are **case-sensitive** and must exactly match the conversion name configured in your Outbrain Amplify dashboard. `Purchase` ≠ `purchase` ≠ `PURCHASE`. Verify the exact spelling in Amplify → Conversions before configuring Upstack. </Accordion> <Accordion title="What happens if the click ID is missing?"> Events without an Outbrain click ID are **skipped** and not sent to Outbrain. This is intentional — Outbrain cannot attribute conversions without a click ID, so sending them would inflate your event volume without improving attribution. Ensure your campaign URL suffix includes `obclid={{ob_click_id}}` so the Upstack Pixel can capture click IDs. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="No conversions appearing in Outbrain dashboard"> If events aren't appearing after confirmed store traffic: **Steps to fix:** 1. Verify your campaign URL suffix includes `obclid={{ob_click_id}}` 2. Confirm the Upstack destination shows **Active** (green) 3. Check that the Marketer ID matches your Amplify account 4. Test with a real ad click — test traffic without `obclid` in the URL won't generate events </Accordion> <Accordion title="Invalid Marketer ID error"> The Marketer ID (also called OB\_ADV\_ID or Pixel ID) must be the 32-character hexadecimal string from Amplify. **Steps to fix:** 1. Go to Amplify Dashboard → Settings → Tracking 2. Copy the full Marketer ID (no spaces, no extra characters) 3. Update the destination in Upstack with the correct ID </Accordion> <Accordion title="Low attribution rate compared to other platforms"> This is expected due to Outbrain's click-ID-only attribution model. **To maximize attribution:** * Ensure all campaigns include `obclid={{ob_click_id}}` in the URL suffix * Verify the Upstack Pixel is loading on all pages to capture click IDs * Check that first-party cookies are not being blocked by browser settings * Note that cross-device and returning-visitor conversions will not be attributed </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond Outbrain-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack matches anonymous visitors to known customers for higher match rates. </Card> <Card title="Meta CAPI destination" icon="meta" href="/destinations/meta-capi"> Set up Meta's Conversions API — supports enhanced matching unlike Outbrain. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Destinations Source: https://docs.upstackdata.com/destinations/overview Send conversion events and customer data from Upstack Data to ad platforms, analytics tools, and automation systems. Destinations are integrations that receive data **from** Upstack Data. When a visitor views a product, adds to cart, or completes a purchase, Upstack forwards that event — enriched with identity and attribution data — to the platforms where you need it most. ## Browser-side vs. server-side tracking Most ad platforms support two ways of receiving conversion data: | Method | How it works | Strengths | Limitations | | ------------------------ | ------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------- | | **Browser-side (pixel)** | JavaScript tag fires in the visitor's browser | Easy to set up; real-time | Blocked by ad blockers, ITP, and cookie restrictions; limited data quality | | **Server-side (CAPI)** | Your server sends events directly to the platform's API | Resistant to ad blockers; richer data; higher match rates | Requires server infrastructure and identity resolution | Upstack destinations use **server-side delivery** — events are sent from Upstack's infrastructure directly to each platform's conversion API. This means your data reaches ad networks even when browser pixels are blocked, giving you significantly higher event match rates and more accurate optimization signals. <Tip> Upstack still installs a lightweight browser pixel on your Shopify storefront to capture events in real time. The pixel feeds events into Upstack, which then forwards them server-side to your destinations. You get the speed of browser collection **and** the reliability of server delivery. </Tip> ## Upstack products that power destinations Destinations are configured through two Upstack products depending on the platform type: * **Upstack Signal** handles conversion API forwarding to ad platforms (Meta CAPI, Google Ads, TikTok, Pinterest, Snapchat, Reddit, AppLovin, LinkedIn, Microsoft/Bing, Outbrain, Taboola, NewsBreak). Signal enriches each event with hashed PII, click IDs, and attribution parameters before delivery so platforms can match conversions to the right ad interactions. * **Upstack Flows** handles event delivery to marketing automation and data platforms (Klaviyo, Omnisend, Sendlane, Loops, Attentive, PostHog, Slack, webhooks). Flows lets you map Upstack events to platform-specific actions — for example, triggering a Klaviyo flow when a high-intent visitor abandons checkout. ## Available destinations ### Ad Platforms <CardGroup> <Card title="Meta CAPI" icon="meta" href="/destinations/meta-capi"> Send conversion events to Facebook and Instagram via the Conversions API for improved ad optimization. </Card> <Card title="Google Ads" icon="google" href="/destinations/google-ads"> Forward conversion events to Google Ads for Smart Bidding and audience building. </Card> <Card title="TikTok" icon="tiktok" href="/destinations/tiktok"> Send conversion events to TikTok via the Events API for campaign optimization and audience building. </Card> <Card title="Pinterest" icon="pinterest" href="/destinations/pinterest"> Send conversion events to Pinterest via the Conversions API for campaign optimization. </Card> <Card title="Snapchat" icon="snapchat" href="/destinations/snapchat"> Send conversion events to Snapchat via the Conversions API for campaign optimization. </Card> <Card title="Reddit Ads" icon="reddit" href="/destinations/reddit"> Forward conversion events to Reddit's Conversions API to recover ad-blocker losses and improve EMQ. </Card> <Card title="AppLovin" icon="mobile" href="/destinations/applovin"> Send conversion events to AppLovin for mobile app install campaign optimization. </Card> <Card title="LinkedIn Ads" icon="linkedin" href="/destinations/linkedin"> Forward B2B conversion events to LinkedIn's Conversions API for campaign optimization. </Card> <Card title="Microsoft/Bing Ads" icon="microsoft" href="/destinations/bing"> Send conversion events to Microsoft Advertising via the Conversions API. </Card> <Card title="Outbrain" icon="bullhorn" href="/destinations/outbrain"> Forward conversion events to Outbrain for native advertising optimization. </Card> <Card title="Taboola" icon="rectangle-ad" href="/destinations/taboola"> Send conversion events to Taboola for native advertising campaign optimization. </Card> <Card title="NewsBreak" icon="newspaper" href="/destinations/newsbreak"> Forward conversion events to NewsBreak for news feed advertising optimization. </Card> </CardGroup> ### Email & SMS Marketing <CardGroup> <Card title="Klaviyo" icon="envelope" href="/destinations/klaviyo"> Sync customer events and properties to Klaviyo for email/SMS automation, segmentation, and flow triggers. </Card> <Card title="Omnisend" icon="envelope-open-text" href="/destinations/omnisend"> Sync customer events and profiles to Omnisend for email/SMS automation and abandonment flows. </Card> <Card title="Sendlane" icon="paper-plane" href="/destinations/sendlane"> Send customer events to Sendlane for email marketing automation. </Card> <Card title="Loops" icon="rotate" href="/destinations/loops"> Send customer events to Loops for automated email marketing workflows. </Card> <Card title="Attentive" icon="mobile-screen" href="/destinations/attentive"> Sync customer events to Attentive for SMS marketing automation. </Card> </CardGroup> ### Analytics <CardGroup> <Card title="PostHog" icon="chart-simple" href="/destinations/posthog"> Send events to PostHog for product analytics and feature flags. </Card> </CardGroup> ### Notifications & Integrations <CardGroup> <Card title="Slack" icon="slack" href="/destinations/slack"> Send real-time notifications to Slack channels for orders, events, and alerts. </Card> <Card title="Webhooks" icon="webhook" href="/destinations/webhooks"> Deliver raw event payloads to any HTTP endpoint for custom integrations and data warehouses. </Card> </CardGroup> ### Deprecated <CardGroup> <Card title="Google Analytics 4" icon="chart-line" href="/destinations/ga4"> GA4 destination is deprecated. Use native GA4 installation instead. </Card> </CardGroup> ## How destination delivery works When an event enters Upstack (from a source like Shopify), the delivery pipeline runs automatically: 1. **Identity enrichment** — the event is matched to a customer profile and enriched with hashed email, phone, and any available click IDs (`fbc`, `fbp`, `ttclid`, `gclid`). 2. **Destination mapping** — Upstack maps the event to each destination's expected schema (for example, `Purchase` becomes a Meta `Purchase` event with the correct currency, value, and content IDs). 3. **Server-side delivery** — the enriched, mapped event is sent to the destination's API from Upstack's infrastructure. 4. **Delivery confirmation** — Upstack logs the response from each destination so you can monitor match rates and troubleshoot failures from the dashboard. <Note> Each destination can be independently enabled or disabled without affecting other destinations. You can also filter which events are sent to each destination from the destination's settings page. </Note> # Pinterest Ads Source: https://docs.upstackdata.com/destinations/pinterest Send conversion events to Pinterest's Conversions API for ad campaign optimization, audience building, and attribution. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> Pinterest's Conversions API is the server-side counterpart to the Pinterest Pixel. Upstack sends purchases, add-to-carts, and other conversion events directly to Pinterest from your account, bypassing browser ad blockers and giving Pinterest's algorithm stronger signal for ad optimization. Server-side delivery consistently achieves higher event match rates than browser-only tracking. Combined with the Pinterest browser pixel, the two work together — Pinterest's deduplication logic keeps only one conversion when the same event arrives from both sources. ## How It Works When a visitor takes an action on your store, Upstack: 1. Captures the event through the Upstack Pixel and matches it to a known visitor profile. 2. Enriches the event with hashed PII (email, phone) and click IDs (`epik`) when available. 3. Sends the enriched event to Pinterest's Conversions API using your Pinterest Pixel Tag ID and Conversions API access token. 4. Logs the response so you can monitor delivery and match rates from the Upstack dashboard. ## Set Up Pinterest Follow the onboarding guide for the full end-to-end setup, or jump to a specific step. <CardGroup> <Card title="Onboarding guide" icon="book" href="/guides/pinterest-ads/complete-how-to-guide-for-onboarding-pinterest-in-upstack-data"> Complete step-by-step walkthrough for connecting Pinterest to Upstack. </Card> <Card title="Configure destination" icon="sliders" href="/guides/pinterest-ads/how-to-configure-pinterest-destination-in-upstack-data"> Add and configure the Pinterest destination inside the Upstack dashboard. </Card> <Card title="Find Pixel Tag ID" icon="magnifying-glass" href="/guides/pinterest-ads/how-to-find-pinterest-pixel-tag-id"> Locate an existing Pinterest Pixel Tag ID in your Pinterest Ads account. </Card> <Card title="Create Pixel Tag ID" icon="plus" href="/guides/pinterest-ads/how-to-create-a-new-pinterest-pixel-tag-id"> Create a new Pinterest Pixel Tag if you don't already have one. </Card> <Card title="Find Advertiser ID" icon="id-card" href="/guides/pinterest-ads/how-to-find-pinterest-advertiser-id"> Locate the Pinterest Advertiser ID required to identify your ad account. </Card> <Card title="Generate API access token" icon="key" href="/guides/pinterest-ads/how-to-generate-pinterest-conversion-api-key-access-token"> Generate the Conversions API access token Upstack uses to send events. </Card> <Card title="Disable Shopify data sharing" icon="ban" href="/guides/pinterest-ads/how-to-disable-pinterest-data-sharing-in-shopify"> Turn off Shopify's native Pinterest data sharing to prevent duplicate events. </Card> </CardGroup> ## FAQ <AccordionGroup> <Accordion title="Do I still need the Pinterest browser pixel?"> You don't need the browser pixel for Upstack to send events — server-side delivery works on its own. However, running both gives Pinterest the strongest signal. As long as the Pinterest Pixel Tag ID matches between your browser pixel and the Upstack destination, Pinterest's deduplication logic prevents double-counting. </Accordion> <Accordion title="Why disable Shopify's native Pinterest data sharing?"> Shopify's built-in Pinterest integration also forwards events to Pinterest. If both Shopify and Upstack are sending the same events without coordination, Pinterest can count conversions twice. Disabling Shopify's native sharing lets Upstack handle delivery exclusively, with the browser pixel for real-time signal and the Conversions API for reliability. See [Disable Shopify data sharing](/guides/pinterest-ads/how-to-disable-pinterest-data-sharing-in-shopify). </Accordion> <Accordion title="What's the difference between the Pixel Tag ID and the Advertiser ID?"> The **Pixel Tag ID** identifies a specific tracking pixel inside your Pinterest account. The **Advertiser ID** identifies the ad account that owns the pixel. Upstack needs both: the Pixel Tag ID to attribute events to the correct pixel, and the Advertiser ID to send them on behalf of the right ad account. </Accordion> <Accordion title="How long does it take for events to appear in Pinterest?"> Once the destination is active, events typically appear in Pinterest's Events Manager within 5-10 minutes. The first events confirm the connection is working — match quality and conversion attribution build over the following 24-48 hours as Pinterest correlates events to ad clicks. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Conversion API Forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack ID matches anonymous visitors to known customers for higher match rates. </Card> <Card title="Destinations Overview" icon="arrow-right-from-bracket" href="/destinations/overview"> Browse all available destinations and how Upstack delivers data to each. </Card> <Card title="Events Not Reaching Destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # PostHog Source: https://docs.upstackdata.com/destinations/posthog Forward identity-resolved customer events to PostHog for product analytics, session recordings, and feature flags. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> PostHog is an open-source product analytics platform. Upstack forwards enriched e-commerce events to PostHog so you can analyze customer behavior, track conversion funnels, and replay user sessions — all powered by Upstack's identity resolution. ## How it works When a visitor takes an action on your store, Upstack: 1. Captures the event through the Upstack Pixel and matches it to a known visitor profile using Upstack's identity resolution. 2. Enriches the event with identity data (distinct ID, email, IP, user agent, device info). 3. Sends the event to PostHog using your Project API Key via the PostHog Capture API. 4. PostHog records the event against the visitor's distinct ID for analytics, funnels, and session replays. The result: unified product analytics where anonymous visitors are resolved to their identities, giving you cleaner funnels and more complete user journeys. ## Set up PostHog <Steps> <Step title="Get your PostHog Project API Key"> In PostHog, go to **Project Settings → Project API Key**. The key starts with `phc_` followed by alphanumeric characters. </Step> <Step title="Note your data region"> PostHog offers two data regions: * **US** — Data hosted in the United States (`us.posthog.com`) * **EU** — Data hosted in the European Union (`eu.posthog.com`) Select the region that matches where your PostHog project is hosted. </Step> <Step title="Add the destination in Upstack"> In the Upstack dashboard, go to **Destinations → Add Destination → PostHog**. Enter: * **Project API Key** — Your PostHog project API key (starts with `phc_`) * **Data Region** — Select US or EU based on your PostHog project location </Step> <Step title="Optional: Configure additional settings"> * **Enable Auto Capture** — Automatically capture pageviews and clicks * **Enable Session Recording** — Enable session recording for user replays (requires PostHog session recording to be configured) </Step> <Step title="Save and verify"> Save the destination. Visit your store, trigger an event (view a product, add to cart), and verify the event appears in PostHog under **Activity → Live Events**. </Step> </Steps> ## Credentials | Field | Required | Description | | ------------------------ | -------- | -------------------------------------------------------------------------------------------------- | | Project API Key | Yes | Your PostHog project API key. Found in **Project Settings → Project API Key**. Starts with `phc_`. | | Data Region | Yes | The region where your PostHog data is hosted: `US` or `EU`. | | Enable Auto Capture | No | Automatically capture pageviews and clicks. | | Enable Session Recording | No | Enable session recording for user replays. | ## Event mapping Upstack automatically maps e-commerce events to PostHog events with enriched properties. | Upstack event | PostHog event | Description | | ------------------ | ------------------- | -------------------------------- | | `PageView` | `$pageview` | Page view on any storefront page | | `ViewContent` | `view_item` | Product detail page view | | `ViewCategory` | `view_category` | Category or collection page view | | `ViewCart` | `$pageview` | Cart page view | | `AddToCart` | `add_to_cart` | Product added to cart | | `InitiateCheckout` | `initiate_checkout` | Checkout started | | `Purchase` | `purchase` | Order completed | | `Search` | `search` | Search performed on storefront | | `SignUp` | `sign_up` | Account created | | `Lead` | `lead` | Lead form submitted | ## Event properties Each event sent to PostHog includes enriched properties from Upstack's identity resolution: | Property | PostHog field | Description | | ---------------- | -------------- | ---------------------------------------------- | | Distinct ID | `distinct_id` | Upstack identity ID (resolved across sessions) | | Current URL | `$current_url` | Page URL where the event occurred | | Referrer | `$referrer` | Referring URL | | IP Address | `$ip` | Visitor IP address | | User Agent | `$user_agent` | Browser user agent string | | Browser | `$browser` | Browser name | | Device Type | `$device_type` | Device type (desktop, mobile, tablet) | | Operating System | `$os` | Operating system name | | Email | `email` | Customer email (when identified) | ### E-commerce properties For purchase and cart events, additional e-commerce properties are included: | Property | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `value` | Total value of the event | | `currency` | Currency code (e.g., USD) | | `order_id` | Order ID (for purchases) | | `search_query` | Search query (for search events) | | `items` | Array of product items with `product_id`, `product_name`, `product_brand`, `product_category`, `price`, `quantity`, and `variant` | ## FAQ <AccordionGroup> <Accordion title="What is the difference between Upstack and PostHog's native Shopify integration?"> PostHog's native integration only sees visitors that Shopify can identify. Upstack's identity resolution matches anonymous sessions to known customer profiles using cookies, click IDs, and cross-session behavioral data. This means your PostHog funnels and cohorts include visitors that would otherwise be anonymous. </Accordion> <Accordion title="How does Upstack identify users in PostHog?"> Upstack uses its identity resolution engine to assign a consistent `distinct_id` to each visitor. This ID persists across sessions, devices, and browsers when Upstack can resolve the visitor's identity. Anonymous visitors receive a temporary ID that Upstack attempts to merge when the visitor is later identified. </Accordion> <Accordion title="Will I see duplicate events if I also have PostHog installed via another method?"> Possibly. If you have PostHog's JavaScript snippet or another integration sending the same events, you may see duplicates. Consider disabling overlapping event types in either Upstack or your other PostHog integration to avoid duplication. </Accordion> <Accordion title="How quickly do events appear in PostHog?"> Events typically appear in PostHog within 1-2 minutes of occurring on your storefront. Check **Activity → Live Events** in PostHog to verify events are arriving. </Accordion> <Accordion title="Can I use PostHog session recordings with Upstack?"> PostHog session recordings require PostHog's JavaScript snippet to be installed on your storefront. Upstack sends server-side events to PostHog, which can be correlated with session recordings if you have both installed. Enable "Session Recording" in the Upstack destination settings to include session replay metadata. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="Events not appearing in PostHog"> If events are showing in the Upstack Live Event Stream but not arriving in PostHog: **Steps to fix:** 1. Confirm the PostHog destination shows **Active** (green) in the Upstack dashboard 2. Verify your Project API Key is correct and starts with `phc_` 3. Check that you selected the correct data region (US or EU) matching your PostHog project 4. In PostHog, go to **Activity → Live Events** and look for events from Upstack 5. If the destination status is red, disconnect and reconnect with a fresh API key </Accordion> <Accordion title="Events showing with wrong distinct_id"> If events appear in PostHog but users aren't being properly identified: **Steps to fix:** 1. Verify Upstack's identity resolution is working by checking the Live Event Stream for resolved identities 2. Check that your PostHog project's person identification settings match how Upstack sends distinct IDs 3. Allow 24-48 hours for Upstack to build identity profiles for new visitors </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond PostHog-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack ID connects anonymous sessions to known customers. </Card> <Card title="Destinations Overview" icon="arrow-right-from-bracket" href="/destinations/overview"> How Upstack Signal and Upstack Flows power different types of destinations. </Card> <Card title="Custom Events" icon="code" href="/guides/custom-events/how-to-create-custom-event-triggers"> Send custom events to PostHog and other destinations. </Card> <Card title="Events Not Reaching Destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Reddit Conversions API Source: https://docs.upstackdata.com/destinations/reddit Forward identity-resolved conversion events to the Reddit Conversions API to recover the 30-50% of conversions lost to ad blockers and improve Reddit Ads Event Match Quality and ROAS. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does Reddit's Conversions API (CAPI) is the server-side counterpart to the Reddit Pixel. The browser pixel loses 30-50% of conversion events to ad blockers, iOS privacy restrictions, and cross-device journeys. Upstack Signal forwards every storefront event — page views, product views, add-to-carts, and purchases — to Reddit's Conversions API as a server-side event with strong match keys. For DTC brands running Reddit Ads, CAPI is essential. Reddit's algorithm only optimizes on what it sees. When half the conversions never make it back, the algorithm starves and your real ROAS hides behind degraded data. Server-side delivery via Upstack restores the full conversion picture so Reddit can optimize against accurate signal. The practical result is higher Event Match Quality (EMQ), more accurate ROAS reporting inside Reddit Ads Manager, and stronger optimization signal for campaigns that depend on conversion events. ## How it works Upstack Signal runs as a dual-tracking layer. The Upstack Pixel captures events in the browser and forwards each one to Upstack's edge infrastructure, where it is hashed, enriched with identity and attribution data, and then sent to Reddit's Conversions API as a server-side event with a shared `conversion_id`. Reddit deduplicates against any matching browser Pixel event using that ID, so you do not double-count. Every event carries the strongest available match keys — hashed `email`, `phone_number`, `external_id`, plus `rdt_cid` (Reddit click ID), `user_agent`, and `ip_address` — so Reddit can attribute the conversion to the right user and ad interaction. ## Setup guides <CardGroup> <Card title="Onboarding guide" icon="route" href="/guides/reddit-ads/complete-how-to-guide-for-onboarding-reddit-in-upstack-data"> End-to-end walkthrough for connecting Reddit Ads to Upstack Data. </Card> <Card title="Configure pixel destination" icon="sliders" href="/guides/reddit-ads/how-to-configure-reddit-destination-in-upstack-data"> Configure the Reddit destination inside Upstack Data. </Card> <Card title="Find Pixel ID" icon="magnifying-glass" href="/guides/reddit-ads/how-to-find-reddit-pixel-id"> Locate your Reddit Pixel ID in Reddit Ads Manager Events Manager. </Card> <Card title="Generate CAPI token" icon="key" href="/guides/reddit-ads/how-to-generate-reddit-conversion-api-token"> Generate a Conversions API access token in Reddit Ads Manager. </Card> <Card title="Update CAPI token" icon="rotate" href="/guides/reddit-ads/how-to-update-reddit-conversion-api-token"> Rotate or replace your existing Reddit CAPI access token. </Card> <Card title="Remove duplicate Reddit pixels" icon="ban" href="/guides/reddit-ads/how-to-disable-existing-reddit-pixel-in-shopify"> Remove existing Reddit pixel installations from Shopify to prevent duplicate events. </Card> </CardGroup> ## Event mapping Upstack maps storefront events to Reddit standard events automatically: | Upstack event | Reddit standard event | Key match data | | ------------------ | ------------------------- | ------------------------------------------------ | | `PageView` | `PageVisit` | URL, referrer, user agent | | `ViewContent` | `ViewContent` | `products`, `value`, `currency` | | `AddToCart` | `AddToCart` | `products`, `value`, `currency` | | `InitiateCheckout` | `Purchase` (intermediate) | `value`, `currency`, `itemCount` | | `Purchase` | `Purchase` | `value`, `currency`, `transactionId`, `products` | PII is hashed with SHA-256 before it leaves Upstack. Upstack includes every available match key on every event — `em` (hashed email), `ph` (hashed phone), `external_id`, `rdt_cid`, `user_agent`, and `ip_address` — to maximize EMQ. ## FAQ <AccordionGroup> <Accordion title="Why does Reddit need the Conversions API?"> Reddit's browser pixel loses 30-50% of conversion events to ad blockers, iOS privacy restrictions (ITP), and cross-device buyer journeys (e.g., browse on mobile, purchase on desktop). The Conversions API runs server-to-server, bypassing browser limitations entirely. Reddit officially recommends running both Pixel and CAPI together, with CAPI providing the reliable backbone. </Accordion> <Accordion title="What is Reddit Event Match Quality (EMQ)?"> Reddit's EMQ score (visible in Reddit Ads Manager) measures how reliably Reddit can match a conversion event back to a Reddit user. Higher EMQ means better optimization, lower CPA, and higher ROAS. Server-side delivery via CAPI typically lifts EMQ scores significantly because events carry hashed PII and click IDs that browser-only events lose. </Accordion> <Accordion title="Will my events be counted twice if I run both the Pixel and CAPI?"> No. Upstack sends a shared `conversion_id` on every server-side event, and Reddit deduplicates against the matching browser Pixel event with the same ID. As long as the Pixel ID in Upstack matches the Pixel ID firing in your storefront, deduplication is automatic. </Accordion> <Accordion title="Do I need to remove my existing Reddit pixel from Shopify?"> If you already have a Reddit pixel installed via Shopify Customer Events, theme.liquid, or a third-party app, that pixel will keep firing browser-side. As long as the Pixel ID matches the one configured in Upstack, deduplication via `conversion_id` prevents double-counting. However, if you have **multiple** Reddit pixels installed (a common cause of inflated metrics), follow the [remove duplicate Reddit pixels guide](/guides/reddit-ads/how-to-disable-existing-reddit-pixel-in-shopify) to consolidate to a single pixel before activating Upstack. </Accordion> <Accordion title="How do I verify CAPI events are arriving in Reddit?"> Open Reddit Ads Manager → **Events Manager** → select your pixel. The **Overview** tab shows recent events with a **Server** badge for CAPI events and a **Browser** badge for pixel events. The **EMQ** column shows match quality scores. Upstack also surfaces delivery status and EMQ inside the destination settings in your dashboard. </Accordion> <Accordion title="What are the typical results from adding Reddit CAPI?"> Brands running Reddit Ads with Upstack's CAPI integration typically see EMQ scores climb within 7-10 days and a 20-40% increase in tracked conversions vs. browser-only pixel. This translates to more accurate ROAS reporting (often revealing campaigns that looked unprofitable were actually performing well) and stronger Reddit Ads campaign optimization. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack matches anonymous visitors to known customers for higher match rates. </Card> <Card title="Meta Conversions API" icon="meta" href="/destinations/meta-capi"> Set up Meta CAPI as another server-side destination alongside Reddit. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Sendlane Source: https://docs.upstackdata.com/destinations/sendlane Forward identity-resolved customer events to Sendlane to power email and SMS automation, abandoned cart recovery, and browse abandonment workflows. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> Sendlane is connected through **Upstack Flows**, the product that handles event delivery to marketing automation platforms. Upstack identifies visitors that Shopify and Sendlane's native tracking miss — turning anonymous browse and cart abandonment sessions into actionable Sendlane contacts. This means more abandoned cart workflows fire, more browse abandonment messages send, and you recover revenue that would otherwise be invisible. ## How It Works When a visitor takes an action on your store, Upstack: 1. Captures the event through the Upstack Pixel and matches it to a known visitor profile using Upstack's identity resolution. 2. Looks up the contact in Sendlane by email or Sendlane contact ID to verify they exist. 3. If the contact is found, enriches the event with cart/product data and sends it to Sendlane as a custom event. 4. The custom event can trigger Sendlane automations like abandoned cart flows, browse abandonment sequences, and post-purchase campaigns. The result: abandoned cart and browse abandonment workflows fire for visitors that Shopify's native tracking misses. <Info> Sendlane events are only sent for contacts that already exist in Sendlane. This ensures your automations target real, opt-in subscribers and keeps your deliverability healthy. </Info> ## Required Credentials To connect Sendlane to Upstack, you need two credentials from your Sendlane account: | Credential | Description | Where to Find | | --------------------- | --------------------------------------------- | -------------------------------------------- | | **API Access Token** | Authenticates API requests to Sendlane | Sendlane → Settings → API | | **Integration Token** | Identifies custom events for your integration | Sendlane → Integrations → Custom Integration | <Steps> <Step title="Generate API Access Token"> In Sendlane, go to **Settings → API** and generate a new API token. Copy the token — you'll need it in the next step. </Step> <Step title="Create Custom Integration"> In Sendlane, go to **Integrations → Custom Integration** and create a new integration. Copy the **Integration Token** provided. </Step> <Step title="Configure in Upstack"> In the Upstack dashboard, go to **Destinations → Add Destination → Sendlane** and paste both credentials. </Step> </Steps> ## Event Mapping Upstack forwards the following events to Sendlane as custom events: | Upstack Event | Sendlane Event | Key Properties | Use Case | | ------------------------------- | ---------------------------------------------- | ------------------------------------------------------------- | ----------------------------- | | `ViewContent` | `product-viewed-upstackified` | `product_id`, `product_name`, `product_img_url`, `variant_id` | Browse abandonment flows | | `AddToCart` | `added-to-cart-upstackified` | `line_items`, `subtotal`, `total`, `currency` | Abandoned cart flows | | `InitiateCheckout` | `checkout-started-upstackified` | `checkout_id`, `line_items`, `subtotal`, `total`, `currency` | Checkout abandonment flows | | `Purchase` | `order-placed-upstackified` | `order_id`, `line_items`, `total`, `currency`, `discounts` | Post-purchase flows, win-back | | `SubscriptionRecurringPurchase` | `subscription-recurring-purchase-upstackified` | `order_id`, `line_items`, `total`, `currency` | Subscription renewal flows | Each event includes line item details such as `product_id`, `variant_id`, `sku`, `product_name`, `quantity`, `item_price`, `product_img_url`, and `product_url`. ## Best Practices <Tip> **Build abandonment automations on Upstack events.** Create Sendlane automations triggered by the `-upstackified` events (e.g., `added-to-cart-upstackified`) to capture visitors that your standard tracking misses. </Tip> <Tip> **Use cross-flow exclusions.** If you have both standard Sendlane automations and Upstack-powered automations, add exclusion filters to prevent the same customer from receiving duplicate messages. </Tip> <Warning> **Disable overlapping integrations.** If you previously used another attribution tool that sends similar events to Sendlane, disable those integrations before enabling Upstack to avoid duplicate events and messages. </Warning> ## FAQ <AccordionGroup> <Accordion title="How is this different from Sendlane's native Shopify integration?"> Sendlane's native Shopify integration only sees visitors that Shopify has identified — typically logged-in customers or shoppers who have entered an email at checkout. Upstack's identity resolution matches anonymous sessions to known customer profiles using cookies, click IDs, and cross-session behavioral data, then sends those events to Sendlane. This lets your abandoned cart and browse abandonment workflows fire for many more visitors. </Accordion> <Accordion title="What happens if a contact doesn't exist in Sendlane?"> Upstack only sends events for contacts that already exist in Sendlane. If the visitor's email isn't found in your Sendlane account, the event is skipped. This keeps your Sendlane account clean and ensures events only target real subscribers. </Accordion> <Accordion title="Will I get duplicate events if I keep Sendlane's native Shopify integration?"> Possibly. If both Upstack and Sendlane's native integration track the same event types, Sendlane may record both. The recommended approach is to disable the corresponding events in Sendlane's native integration for any event types Upstack is configured to send. </Accordion> <Accordion title="What permissions does the Sendlane API token need?"> The Sendlane API token must have permission to read contacts and send custom events. Use a token with the minimum scope required — Upstack does not need account management or billing permissions. </Accordion> <Accordion title="How long does it take for events to appear in Sendlane?"> Once the destination is active, events typically appear in Sendlane within 5 minutes. You can verify by triggering a test action on your store (such as adding a product to cart) and checking the contact's activity feed in Sendlane. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="Events not appearing in Sendlane"> If events are showing in the Upstack Live Event Stream but not arriving in Sendlane: **Steps to fix:** 1. Confirm the Sendlane destination shows **Active** (green) in the Upstack dashboard 2. Verify your API Access Token is valid and has not expired 3. Check that the contact exists in Sendlane — events are only sent for existing contacts 4. Verify the Integration Token matches the custom integration you created in Sendlane 5. If the destination status is red, disconnect and reconnect with fresh credentials </Accordion> <Accordion title="Custom events not triggering automations"> If events are arriving in Sendlane but not triggering your automations: **Steps to fix:** 1. Verify your automation is set to trigger on the correct event name (e.g., `added-to-cart-upstackified`, not `Added to Cart`) 2. Check that the automation is active and not paused 3. Ensure the contact meets any segment or filter conditions on the automation 4. Review the contact's activity feed to confirm the event was received </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond Sendlane-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Data Enrichment" icon="magnifying-glass-plus" href="/concepts/data-enrichment"> How Upstack Enrichment improves visitor identification — the foundation of Flows recovery. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack ID connects anonymous sessions to known customers with email addresses. </Card> <Card title="Klaviyo Destination" icon="envelope" href="/destinations/klaviyo"> Similar email/SMS marketing integration for Klaviyo users. </Card> <Card title="Events Not Reaching Destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Slack Source: https://docs.upstackdata.com/destinations/slack Send real-time event notifications to Slack channels for purchases, leads, and other key conversions. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does The Slack destination sends real-time notifications to any Slack channel when events occur on your store. Get instant alerts for purchases, new leads, abandoned carts, or any custom event — delivered directly to your team's Slack workspace. Unlike ad platform destinations that optimize campaigns, Slack notifications are designed for visibility. See every high-value conversion the moment it happens, celebrate wins with your team, or monitor for unusual activity. ## How it works When a matching event occurs, Upstack: 1. Evaluates the event against your configured event templates and conditions. 2. Renders a Block Kit message using the template's placeholder values (order ID, customer email, revenue, etc.). 3. POSTs the formatted message to your Slack webhook URL. 4. Logs the delivery status to the Upstack event debugger. Each event template can have its own conditions — for example, only notify on purchases over \$100, or only alert when a specific product is purchased. ## Supported events Slack notifications can be triggered by any standard or custom event: | Event | Use case | | ------------------ | ------------------------------------------------------- | | `Purchase` | Celebrate new orders, track high-value conversions | | `InitiateCheckout` | Monitor checkout abandonment in real-time | | `AddToCart` | Track product interest and cart activity | | `Lead` | Get notified of form submissions and newsletter signups | | `ViewContent` | Monitor traffic to key pages | | Custom events | Trigger on any event you define | ## Setup instructions ### Step 1: Create a Slack Incoming Webhook 1. Go to [Slack API Apps](https://api.slack.com/apps) and click **Create New App**. 2. Choose **From scratch**, name your app (e.g., "Upstack Notifications"), and select your workspace. 3. Under **Features**, click **Incoming Webhooks** and toggle it **On**. 4. Click **Add New Webhook to Workspace** and select the channel where notifications should appear. 5. Copy the **Webhook URL** — it looks like `https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX`. ### Step 2: Configure the Slack destination in Upstack 1. In the Upstack dashboard, go to **Destinations** and click **Add Destination**. 2. Select **Slack** from the destination list. 3. Paste your **Webhook URL** from Step 1. 4. Create one or more **Event Templates** to define which events trigger notifications and how they're formatted. ### Step 3: Create event templates Each template maps a source event to a Slack message: * **Source Event**: The event type that triggers this template (e.g., `Purchase`). * **Template**: The Block Kit message structure with placeholders like `{{data.order_id}}` and `{{data.value}}`. * **Conditions** (optional): Filter criteria — only send when conditions are met. ## Example message format Slack messages use Block Kit for rich formatting. Here's an example purchase notification: ```json theme={null} { "blocks": [ { "type": "header", "text": { "type": "plain_text", "text": "🎉 New Purchase!" } }, { "type": "section", "fields": [ { "type": "mrkdwn", "text": "*Order ID:*\n{{data.order_id}}" }, { "type": "mrkdwn", "text": "*Revenue:*\n${{data.value}}" }, { "type": "mrkdwn", "text": "*Customer:*\n{{data.email}}" }, { "type": "mrkdwn", "text": "*Source:*\n{{context.utm_source}}" } ] }, { "type": "context", "elements": [ { "type": "mrkdwn", "text": "via Upstack Data" } ] } ] } ``` Placeholders like `{{data.order_id}}` are replaced with actual event values at send time. ## Use cases <CardGroup> <Card title="Purchase alerts" icon="bell"> Get notified in Slack the moment a purchase completes. Include order value, customer info, and attribution source. </Card> <Card title="Lead notifications" icon="user-plus"> Alert your sales team when a lead form is submitted. Route different lead types to different channels. </Card> <Card title="High-value order alerts" icon="trophy"> Use conditions to only notify on orders above a threshold — celebrate the big wins. </Card> <Card title="Abandoned cart monitoring" icon="cart-shopping"> Track checkout initiations in real-time to spot abandonment patterns. </Card> </CardGroup> ## FAQ <AccordionGroup> <Accordion title="Where do I find my Slack webhook URL?"> Create an Incoming Webhook in your Slack workspace settings. Go to [Slack API Apps](https://api.slack.com/apps), create or select an app, enable Incoming Webhooks, and add a new webhook to your desired channel. The URL is generated automatically. </Accordion> <Accordion title="Can I send to multiple Slack channels?"> Each Slack destination has one webhook URL (one channel). To send to multiple channels, create multiple Slack destinations with different webhook URLs and configure each with the appropriate event templates. </Accordion> <Accordion title="How do conditions work?"> Conditions let you filter which events trigger a notification. For example, you can configure a template to only fire when `data.value` is greater than 100, or when `data.currency` equals "USD". Conditions support AND/OR logic for complex filtering. </Accordion> <Accordion title="What placeholders can I use in templates?"> Any field from the tracking event is available as a placeholder. Common examples: * `{{data.order_id}}` — Order ID * `{{data.value}}` — Order value * `{{data.email}}` — Customer email * `{{data.currency}}` — Currency code * `{{context.utm_source}}` — UTM source * `{{context.page_url}}` — Page URL where event occurred </Accordion> <Accordion title="What happens if the Slack webhook fails?"> Failed deliveries are logged to the Upstack event debugger. Upstack uses SQS-based retry with exponential backoff for transient failures. If the webhook URL is invalid or the Slack app is deleted, events will fail permanently and appear in your delivery logs. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Webhooks destination" icon="webhook" href="/destinations/webhooks"> Send raw event payloads to any HTTP endpoint for custom integrations. </Card> <Card title="Standard events reference" icon="bolt" href="/pixel/standard-events"> Full reference for all event types and properties available in templates. </Card> <Card title="Custom events" icon="code" href="/guides/custom-events/how-to-create-custom-event-triggers"> Create custom events to trigger Slack notifications for any action. </Card> <Card title="Destinations overview" icon="arrow-right-from-bracket" href="/destinations/overview"> How Upstack delivers events to all destination types. </Card> </CardGroup> # Snapchat Ads Source: https://docs.upstackdata.com/destinations/snapchat Send conversion events to Snapchat's Conversions API for ad campaign optimization, audience building, and attribution. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> Snapchat's Conversions API is the server-side counterpart to the Snap Pixel. Upstack sends purchases, add-to-carts, and other conversion events directly to Snapchat from your account, bypassing browser ad blockers and giving Snap's algorithm stronger signal for ad optimization. Server-side delivery consistently achieves higher event match rates than browser-only tracking. Combined with the Snap browser pixel, the two work together — Snapchat's deduplication logic keeps only one conversion when the same event arrives from both sources. ## How It Works When a visitor takes an action on your store, Upstack: 1. Captures the event through the Upstack Pixel and matches it to a known visitor profile. 2. Enriches the event with hashed PII (email, phone) and Snap click IDs (`scclid`) when available. 3. Sends the enriched event to Snapchat's Conversions API using your Snap Pixel ID and Conversions API token. 4. Logs the response so you can monitor delivery and match rates from the Upstack dashboard. ## Set Up Snapchat Follow the onboarding guide for the full end-to-end setup, or jump to a specific step. <CardGroup> <Card title="Onboarding guide" icon="book" href="/guides/snapchat-ads/complete-how-to-guide-for-onboarding-snapchat-in-upstack-data"> Complete step-by-step walkthrough for connecting Snapchat to Upstack. </Card> <Card title="Configure destination" icon="sliders" href="/guides/snapchat-ads/how-to-configure-snapchat-pixel-destination-in-upstack-data"> Add and configure the Snapchat destination inside the Upstack dashboard. </Card> <Card title="Get Pixel ID" icon="magnifying-glass" href="/guides/snapchat-ads/how-to-get-my-snapchat-pixel-id"> Locate the Snap Pixel ID in your Snapchat Ads account. </Card> <Card title="Generate Conversion API token" icon="key" href="/guides/snapchat-ads/how-to-generate-my-snapchat-conversion-api-token"> Generate the Conversions API token Upstack uses to send events. </Card> <Card title="Disable Shopify data sharing" icon="ban" href="/guides/snapchat-ads/how-to-disable-snapchat-data-sharing-in-shopify"> Turn off Shopify's native Snapchat data sharing to prevent duplicate events. </Card> </CardGroup> ## FAQ <AccordionGroup> <Accordion title="Do I still need the Snap browser pixel?"> You don't need the browser pixel for Upstack to send events — server-side delivery works on its own. However, running both gives Snap the strongest signal. As long as the Snap Pixel ID matches between your browser pixel and the Upstack destination, Snapchat's deduplication logic prevents double-counting. </Accordion> <Accordion title="Why disable Shopify's native Snapchat data sharing?"> Shopify's built-in Snapchat integration also forwards events to Snap. If both Shopify and Upstack are sending the same events without coordination, Snapchat can count conversions twice. Disabling Shopify's native sharing lets Upstack handle delivery exclusively, with the browser pixel for real-time signal and the Conversions API for reliability. See [Disable Shopify data sharing](/guides/snapchat-ads/how-to-disable-snapchat-data-sharing-in-shopify). </Accordion> <Accordion title="How long does it take for events to appear in Snapchat?"> Once the destination is active, events typically appear in Snap Events Manager within 5-10 minutes. The first events confirm the connection is working — match quality and conversion attribution build over the following 24-48 hours as Snap correlates events to ad clicks. </Accordion> <Accordion title="What permissions does the Conversions API token need?"> The Snapchat Conversions API token must have permission to send events on behalf of your ad account. Generate the token with the minimum scope required for sending conversion events — Upstack does not need management or spending permissions. Step-by-step instructions are in [Generate Conversion API token](/guides/snapchat-ads/how-to-generate-my-snapchat-conversion-api-token). </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Conversion API Forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack ID matches anonymous visitors to known customers for higher match rates. </Card> <Card title="Destinations Overview" icon="arrow-right-from-bracket" href="/destinations/overview"> Browse all available destinations and how Upstack delivers data to each. </Card> <Card title="Events Not Reaching Destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Taboola Source: https://docs.upstackdata.com/destinations/taboola Send conversion events to Taboola's S2S API for native advertising campaign optimization — powered by Upstack Signal. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does Taboola is a native advertising platform that displays sponsored content recommendations on publisher websites. Upstack Signal forwards storefront events — page views, product views, add-to-carts, and purchases — directly to Taboola's Server-to-Server (S2S) Conversion API for campaign optimization. Server-side delivery means conversions reach Taboola even when the browser-side pixel is blocked by ad blockers, ITP, or cookie restrictions. Each event carries the click identifier (`tblci`) captured from ad clicks so Taboola can match the conversion back to the ad interaction that drove it. <Warning> **Important limitation:** Taboola does **NOT** support enhanced matching via hashed email, phone, or other PII. Attribution relies **solely on the click ID (`tblci`)** captured from ad clicks. Events without a click ID cannot be attributed and are skipped. </Warning> ## How it works Upstack Signal runs as a dual-tracking layer alongside the Taboola browser pixel. The Upstack Pixel captures events in the browser and forwards each one to Upstack's edge infrastructure, where it is enriched with the Taboola click ID from cookie storage and sent to Taboola's S2S API as a server-side event. **S2S priority for deduplication:** When both the browser pixel and S2S report the same event, Taboola keeps the S2S event and deduplicates the pixel event. This makes server-side preferred for accurate attribution. **API behavior:** Taboola's S2S API returns HTTP 204 No Content for **all** requests, including invalid ones. There is no validation feedback from the API — use Taboola Backstage Test Events for verification. **Authentication:** Unlike Meta, TikTok, and Google APIs, Taboola's S2S API is unauthenticated. Events are attributed via the click ID only. ## Setup ### Prerequisites * A Taboola Backstage account with active campaigns * The Upstack Pixel installed on your storefront * Campaign URLs configured with the `tblci` click ID parameter ### Required credentials | Field | Description | Where to find | | ---------- | ------------------------------- | --------------------------------------- | | Account ID | Your numeric Taboola Account ID | Backstage → Account dropdown → Tracking | ### Configuration steps 1. In Upstack, navigate to **Settings** → **Destinations** 2. Click **Add Destination** and select **Taboola** 3. Enter your **Account ID** (numeric only) 4. Toggle **Enable Server-Side Tracking** to send events via the S2S API 5. Click **Save** ### Configure click ID tracking For Taboola to attribute conversions, your campaign URLs must include the click ID parameter: 1. In Taboola Backstage, go to **Campaigns** → select your campaign 2. Add `?tblci={click_id}` to your destination URL (or `&tblci={click_id}` if URL already has parameters) 3. The Upstack Pixel will automatically capture and store the `tblci` value <Note> The `tblci` parameter is case-sensitive. Ensure your URL uses lowercase `tblci`. </Note> ## Event mapping Upstack maps storefront events to Taboola events automatically: | Upstack event | Taboola event | Key parameters | Notes | | ---------------------- | ----------------------- | -------------------------------- | ------------------------------ | | `Purchase` | `make_purchase` | `revenue`, `currency`, `orderid` | Primary conversion event | | `InitiateCheckout` | `start_checkout` | `revenue`, `currency` | Checkout initiation | | `AddToCart` | `add_to_cart` | `quantity` | Cart additions | | `ViewContent` | `view_content` | — | Product page views | | `PageView` | `page_view` | — | Page load | | `Lead` | `lead` | `revenue` | Lead form submissions | | `SignUp` | `complete_registration` | — | Account registration | | `CompleteRegistration` | `complete_registration` | — | Account registration | | `Search` | `search` | — | Site search | | `Subscribe` | `subscribe` | — | Newsletter/subscription signup | Every event includes the Taboola click ID (`tblci`) when available. **Events without a click ID are skipped** because Taboola cannot attribute them to any campaign. <Warning> **Event names are case-sensitive.** Taboola event names must exactly match the conversion name configured in Taboola Realize. Upstack sends lowercase snake\_case names (e.g., `make_purchase`, `add_to_cart`). </Warning> ## Field mapping | Upstack field | Taboola field | Type | Notes | | -------------------------------------- | ------------- | ------ | ----------------------------------------- | | `context.properties.click.tblci` | `click-id` | string | **Required.** Click ID from ad click | | `data.value` | `revenue` | number | Conversion value (decimal, no commas) | | `data.currency` | `currency` | string | ISO 4217 (USD, EUR, GBP) — case-sensitive | | `data.orderId` or `data.transactionId` | `orderid` | string | Transaction ID for deduplication | | Aggregated from `items` | `quantity` | number | Total quantity across all items | | Event timestamp | `timestamp` | number | Milliseconds since Unix epoch | ## FAQ <AccordionGroup> <Accordion title="How do I verify events are arriving in Taboola?"> Open Taboola Backstage, navigate to **Tracking** → **Test Events**, and check that events are appearing. Note that Taboola's API returns 204 for all requests (even invalid ones), so the Test Events view is the only way to confirm events are being processed correctly. </Accordion> <Accordion title="Why are my attribution rates lower than other platforms?"> Taboola does not support enhanced matching with hashed PII (email, phone, IP, user-agent). Attribution relies **solely** on the click ID (`tblci`). If a visitor clears cookies, uses a different device, or the click ID expires, the conversion cannot be attributed. This is a platform limitation, not an Upstack issue. </Accordion> <Accordion title="Will my events be counted twice if I run both the pixel and server-side?"> No. When both the browser pixel and S2S report the same event, Taboola keeps the S2S event and deduplicates the pixel event. Including an `orderid` on purchase events further improves deduplication. </Accordion> <Accordion title="Do event names need to match exactly?"> Yes — event names are **case-sensitive** and must exactly match the conversion name configured in Taboola Realize. Upstack sends standard lowercase snake\_case names like `make_purchase`, `add_to_cart`, etc. </Accordion> <Accordion title="What happens if the click ID is missing?"> Events without a Taboola click ID are **skipped** and not sent to Taboola. This is intentional — Taboola cannot attribute conversions without a click ID, so sending them would inflate your event volume without improving attribution. Ensure your campaign URLs include `tblci={click_id}` so the Upstack Pixel can capture click IDs. </Accordion> <Accordion title="Why does the API always return 204?"> Taboola's S2S API returns HTTP 204 No Content for **all** requests, including those with invalid data. This is by design. Use Taboola Backstage Test Events to verify events are being processed correctly. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="No conversions appearing in Taboola Backstage"> If events aren't appearing after confirmed store traffic: **Steps to fix:** 1. Verify your campaign URL includes `tblci={click_id}` 2. Confirm the Upstack destination shows **Active** (green) 3. Check that the Account ID matches your Backstage account 4. Test with a real ad click — test traffic without `tblci` in the URL won't generate events 5. Check Taboola Backstage → Tracking → Test Events for any incoming events </Accordion> <Accordion title="Invalid Account ID"> The Account ID must be a numeric string (digits only). **Steps to fix:** 1. Go to Taboola Backstage → Account dropdown → Tracking 2. Copy the numeric Account ID (no spaces, no extra characters) 3. Update the destination in Upstack with the correct ID </Accordion> <Accordion title="Low attribution rate compared to other platforms"> This is expected due to Taboola's click-ID-only attribution model. **To maximize attribution:** * Ensure all campaigns include `tblci={click_id}` in the URL * Verify the Upstack Pixel is loading on all pages to capture click IDs * Check that first-party cookies are not being blocked by browser settings * Note that cross-device and returning-visitor conversions will not be attributed </Accordion> <Accordion title="Events appear to send but don't show in Backstage"> Remember that Taboola's API returns 204 for all requests, even invalid ones. **Steps to fix:** 1. Verify event names match exactly what's configured in Taboola Realize (case-sensitive) 2. Ensure the `click-id` parameter is being sent correctly (hyphenated, not underscored) 3. Check that revenue values don't contain commas 4. Verify currency codes are uppercase ISO 4217 (USD, not usd) </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond Taboola-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack matches anonymous visitors to known customers for higher match rates. </Card> <Card title="Outbrain destination" icon="rectangle-ad" href="/destinations/outbrain"> Set up Outbrain's native advertising API — similar click-ID-only attribution model. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # TikTok Events API Source: https://docs.upstackdata.com/destinations/tiktok Send conversion events to TikTok via the Events API for campaign optimization, audience building, and attribution — powered by Upstack Signal. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does TikTok's Events API is the server-side counterpart to the TikTok Pixel. Upstack Signal forwards storefront events — page views, product views, add-to-carts, checkouts, and purchases — directly to TikTok's servers, bypassing browser restrictions like ad blockers, ITP, and cookie limits. Server-side delivery gives TikTok's algorithm a fuller picture of the conversions your ads actually drove, which improves campaign optimization, audience modeling, and attribution accuracy. Match rates from server-side events are consistently higher than browser-only tracking because each event carries hashed customer data and the `ttclid` click identifier when available. <Note> Unlike Meta and Google Ads, TikTok uses **token-based auth** instead of OAuth. You'll paste a Pixel ID and an Events API access token into the Upstack destination — there is no OAuth handshake to step through. </Note> ## How it works Upstack runs as a dual-tracking layer alongside the TikTok Pixel. The Upstack Pixel captures events in the browser and forwards each event to Upstack's edge infrastructure, where it is hashed, enriched with identity and click-ID data, and sent to the TikTok Events API as a server-side event with a shared `event_id`. TikTok deduplicates server events against matching browser Pixel events using that `event_id`, so you do not double-count conversions as long as both sources use the same Pixel ID. PII (`email`, `phone`, `external_id`) is hashed with SHA-256 before delivery, as required by the Events API. ## Setup guides <CardGroup> <Card title="Onboarding guide" icon="route" href="/guides/tiktok-ads/complete-how-to-guide-for-onboarding-tiktok-ads-in-upstack-data"> End-to-end walkthrough for connecting TikTok to Upstack Data. </Card> <Card title="Configure pixel destination" icon="sliders" href="/guides/tiktok-ads/how-to-configure-tiktok-ads-pixel-destination-in-upstack-data"> Configure the TikTok Pixel destination inside Upstack Data. </Card> <Card title="Find Pixel ID" icon="magnifying-glass" href="/guides/tiktok-ads/how-to-find-your-tiktok-ads-pixel-id"> Locate your existing TikTok Pixel ID in Events Manager. </Card> <Card title="Create Pixel ID" icon="plus" href="/guides/tiktok-ads/how-to-create-new-tiktok-ads-pixel-id"> Create a new TikTok Pixel for your store. </Card> <Card title="Generate API token" icon="key" href="/guides/tiktok-ads/how-to-generate-your-tiktok-api-access-token"> Generate the Events API access token Upstack uses to send events. </Card> <Card title="Disable Shopify TikTok data sharing" icon="ban" href="/guides/tiktok-ads/how-to-disable-tiktok-data-sharing-in-shopify"> Turn off Shopify's native TikTok integration to prevent duplicate events. </Card> </CardGroup> ## Event mapping Upstack maps storefront events to TikTok standard events automatically: | Upstack event | TikTok event | Key parameters | Notes | | ------------------ | ------------------ | ------------------------------------------------- | ------------------------------------------------------ | | `PageView` | `ViewContent` | `url`, `referrer` | TikTok has no generic PageView — mapped to ViewContent | | `ViewContent` | `ViewContent` | `content_id`, `content_type`, `value`, `currency` | Product page views | | `AddToCart` | `AddToCart` | `content_id`, `content_type`, `value`, `currency` | Cart additions with product details | | `InitiateCheckout` | `InitiateCheckout` | `value`, `currency`, `quantity` | Checkout started | | `Purchase` | `CompletePayment` | `content_id`, `value`, `currency`, `order_id` | Completed orders with revenue | Every event includes user data parameters (`email`, `phone`, `external_id`) when available, hashed with SHA-256. TikTok click IDs (`ttclid`) captured by the Upstack Pixel are included for deterministic matching. ## FAQ <AccordionGroup> <Accordion title="How do I know events are reaching TikTok?"> Open TikTok Events Manager, select your Pixel, and check the **Overview** and **Test Events** tabs. Server-side events appear with a "Server" source badge, typically within 5–10 minutes of storefront activity. Upstack also surfaces delivery status inside the destination settings. </Accordion> <Accordion title="Will I see duplicate conversions if I run both the TikTok Pixel and the Events API?"> No — as long as the Pixel ID in Upstack matches the Pixel ID firing in your storefront's TikTok browser Pixel (`ttq.load`). Upstack sends a shared `event_id` on every server-side event, and TikTok's deduplication logic matches events by `event_id` and keeps only one. If you see duplicates, the Pixel IDs almost always differ between the two sources. </Accordion> <Accordion title="What if my event match rate is low?"> TikTok's match rate depends on how much identity data each event carries. Common causes of low match quality: * **Missing `ttclid`** — TikTok ads should link directly to your storefront so the click ID lands in the URL and is captured by the Upstack Pixel. * **Anonymous visitors** — events from visitors without email or phone have fewer keys to match against. Match rates improve as more identified customers convert. * **Missing checkout fields** — make sure your Shopify checkout collects email and phone; both are strong server-side match keys. </Accordion> <Accordion title="Do I need to disable Shopify's native TikTok integration?"> Yes — if Shopify is also sending events to the same TikTok Pixel, you'll see duplicates that TikTok cannot deduplicate (Shopify does not emit a matching `event_id`). Follow the guide above to disable TikTok data sharing in Shopify before activating Upstack's TikTok destination. </Accordion> <Accordion title="Can I send only specific event types to TikTok?"> Yes. Each destination supports event filtering — you can choose to forward only purchases, only standard events, or any custom subset. Excluded events are dropped at the Upstack level and are not retried. </Accordion> </AccordionGroup> ## Advanced configuration <Accordion title="TikTok Shop orders"> If you sell through TikTok Shop, those orders flow into Shopify as fulfilled orders. Upstack processes them like any other Shopify order, which means they get sent to all your active destinations — including Meta. **Should you exclude TikTok Shop orders from other destinations?** Upstack gives you the option via **Settings → Order Source Exclusions**, where you can block orders by source. However, sending TikTok Shop orders to Meta is generally beneficial — more conversion data helps Meta's algorithm find similar high-value customers, regardless of where the original purchase happened. If you still want to exclude them: 1. Go to **Upstack → Settings → Order Source Exclusions**. 2. Add TikTok Shop as a blocked source. 3. Orders originating from TikTok Shop will no longer fire to other destinations. </Accordion> ## Troubleshooting <AccordionGroup> <Accordion title="Events not appearing in TikTok Events Manager"> If events aren't appearing after 10 minutes of confirmed store traffic, check the basics first. **Steps to fix:** 1. Go to **Integrations → Destinations → TikTok** 2. Verify the **Pixel ID** and **Access Token** are correct (no extra spaces or truncated characters) 3. Confirm the destination status is Active (green) 4. If the token was revoked or expired, generate a new one in TikTok Business Center and update the destination </Accordion> <Accordion title="Duplicate conversions in TikTok"> If you see inflated conversion counts, another TikTok event source is likely still active. **Steps to fix:** 1. Check for the TikTok Shopify sales channel — disable its data sharing / pixel component 2. Look for third-party pixel apps (Omega, Mega TikTok Pixel) and uninstall them 3. Inspect your theme code for manual TikTok pixel snippets in the `<head>` section 4. After removing duplicate sources, monitor TikTok Events Manager for 24 hours to confirm counts normalize </Accordion> <Accordion title="Low match quality scores"> TikTok's match quality measures how well server events match to TikTok users. **Common causes:** * **High anonymous traffic** — Events from visitors who haven't logged in or provided contact info have fewer matching parameters. Match quality improves as more identified customers generate events. * **Incorrect pixel ID** — If the pixel ID doesn't match the one associated with your ad account, events arrive but can't be matched to campaign data. Match quality typically improves over 1–2 weeks as Upstack's identity resolution builds visitor profiles. </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond TikTok-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack matches anonymous visitors to known customers for higher match rates. </Card> <Card title="Meta CAPI destination" icon="meta" href="/destinations/meta-capi"> Set up Meta's Conversions API as another server-side destination alongside TikTok. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Webhooks Source: https://docs.upstackdata.com/destinations/webhooks Deliver raw event payloads to any HTTP endpoint for custom integrations, data warehouses, and internal systems. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does The webhook destination delivers Upstack events as JSON payloads to any HTTPS endpoint you control. Use it to feed data warehouses, trigger internal workflows, connect platforms Upstack does not support natively, or build custom integrations on top of Upstack's enriched event stream. Every event Upstack captures — including identity-resolved customer data and attribution context — can be delivered to your endpoint in near real-time. Webhooks give you the same enriched event payload that powers Upstack's native destinations, with full schema control on your side. ## How it works Webhook deliveries are HTTP POST requests with a JSON body. Upstack signs each request with HMAC-SHA256 using a per-destination signing secret, so your endpoint can verify the payload originated from Upstack and was not tampered with. Each delivery includes standard headers (`X-Upstack-Event-Id`, `X-Upstack-Event-Type`, `X-Upstack-Signature`, `X-Upstack-Timestamp`) for routing, deduplication, and signature verification. Delivery is at-least-once with a 10-second timeout per attempt and up to 5 retries with exponential backoff (1s, 5s, 30s, 2m, 10m). Events are delivered in approximate chronological order, but strict ordering is not guaranteed — your endpoint should be idempotent and use the `event_id` to deduplicate. ## Setup guides Webhook setup is configured directly in Upstack's destination settings — endpoint URL, event filter, headers, and signing secret. There are no platform-side credentials to provision. <CardGroup> <Card title="Standard events reference" icon="bolt" href="/pixel/standard-events"> Full reference for all event types and properties included in webhook payloads. </Card> <Card title="Properties and context" icon="list" href="/pixel/events/event-properties"> Complete list of event properties and context fields available in every payload. </Card> </CardGroup> ## Payload format Every webhook delivery is an HTTP POST with a JSON body that follows Upstack's standard event schema: ```json theme={null} { "event_id": "evt_abc123def456", "event_type": "Purchase", "timestamp": "2026-02-18T14:32:01.000Z", "pixel_id": "px_your_pixel_id", "session_id": "sess_789xyz", "user": { "anonymous_id": "anon_456def", "customer_id": "cust_123abc", "email_hash": "sha256:a1b2c3...", "phone_hash": "sha256:d4e5f6..." }, "properties": { "order_id": "1234", "value": 89.99, "currency": "USD", "items": [ { "product_id": "prod_001", "title": "Classic T-Shirt", "variant_id": "var_001", "price": 29.99, "quantity": 3 } ] }, "context": { "page_url": "https://your-store.myshopify.com/checkout", "referrer": "https://www.google.com", "user_agent": "Mozilla/5.0...", "ip": "203.0.113.42", "utm_source": "google", "utm_medium": "cpc", "utm_campaign": "summer-sale" }, "attribution": { "source": "google", "medium": "cpc", "campaign": "summer-sale", "click_ids": { "gclid": "abc123", "fbclid": null, "ttclid": null } } } ``` PII fields (`email_hash`, `phone_hash`) are delivered as SHA-256 hashes by default. Raw (unhashed) PII delivery is available for endpoints you own and is subject to your data processing agreement. ### Delivery headers | Header | Value | Description | | ---------------------- | ------------------ | --------------------------------------- | | `Content-Type` | `application/json` | Payload format | | `X-Upstack-Event-Id` | `evt_abc123...` | Unique event ID for deduplication | | `X-Upstack-Event-Type` | `Purchase` | Event type | | `X-Upstack-Signature` | `sha256=...` | HMAC signature for payload verification | | `X-Upstack-Timestamp` | `1708266721` | Unix timestamp of delivery attempt | ## FAQ <AccordionGroup> <Accordion title="What does Upstack guarantee about delivery?"> Webhooks use **at-least-once** delivery. Each request has a 10-second timeout and up to 5 retries with exponential backoff (1s, 5s, 30s, 2m, 10m). After all retries fail, the event is logged as a failed delivery in your dashboard's delivery log. In rare cases (network timeouts, retries) your endpoint may receive the same event more than once — deduplicate using the `event_id` field or the `X-Upstack-Event-Id` header. </Accordion> <Accordion title="How do I verify a webhook payload actually came from Upstack?"> Every delivery includes an `X-Upstack-Signature` header containing an HMAC-SHA256 signature of the raw request body, computed with your destination's signing secret. Recompute the signature on your end over the **raw** (un-parsed, un-reformatted) request body and compare using a constant-time comparison. If the signatures match, the payload is authentic. The signing secret is shown once when you create the destination — store it securely; it can only be regenerated, not retrieved. </Accordion> <Accordion title="Can I receive only certain event types?"> Yes. Each webhook destination supports event filtering — choose all events, standard events only, or any custom subset. Excluded events are dropped at the Upstack level and are not retried. </Accordion> <Accordion title="My endpoint is timing out. What should I do?"> Accept the request immediately (return `200`) and process the payload asynchronously. The 10-second timeout is end-to-end — including any work your endpoint does before responding. The standard pattern is: validate signature, enqueue the payload to your own queue, return `200`, then process the payload separately. </Accordion> <Accordion title="Does the endpoint URL need to be HTTPS?"> Yes. HTTP endpoints are not supported. Your endpoint must be publicly reachable (Upstack delivers from its cloud infrastructure) and serve a valid TLS certificate. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Standard events reference" icon="bolt" href="/pixel/standard-events"> Full reference for all event types and properties included in webhook payloads. </Card> <Card title="Properties and context" icon="list" href="/pixel/events/event-properties"> Complete list of event properties and context fields available in every payload. </Card> <Card title="Destinations overview" icon="arrow-right-from-bracket" href="/destinations/overview"> How Upstack delivers events to all destination types. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Frequently Asked Questions Source: https://docs.upstackdata.com/faq Answers to common questions about Upstack Data — event tracking, identity resolution, privacy, custom events, Shopify compatibility, team management, and platform concepts. <AccordionGroup> <Accordion title="What events does Upstack track automatically?"> Once the Upstack pixel is installed and Shopify is connected, the following events are captured automatically with no additional configuration: * **PageView** — every page load on your storefront * **ViewContent** — product detail page views * **AddToCart** — items added to the cart * **InitiateCheckout** — checkout started * **AddPaymentInfo** — payment method entered * **Purchase** — completed orders (captured server-side via Shopify webhooks for maximum accuracy) * **Search** — storefront search queries Shopify webhook events like `orders/refunded`, `orders/fulfilled`, and `customers/create` are also captured automatically through the server-side integration. You don't need to add any custom code for these standard events. For additional events, see [Custom Events](/pixel/custom-events). </Accordion> <Accordion title="How long does it take for events to appear?"> * **Live Event Stream:** Events appear within **30–60 seconds** of occurring on your storefront. This is the fastest way to verify your integration. * **Dashboard analytics:** Aggregated metrics update every **5–15 minutes** depending on processing load. * **Destination delivery:** Events are forwarded to destinations (Meta, TikTok, etc.) within **1–5 minutes** of capture. * **Attribution reports:** Attribution data may take up to **1 hour** to fully resolve, because Upstack waits for identity resolution to complete before finalizing attribution. If events aren't appearing after 5 minutes, see [Events Not in Dashboard](/troubleshooting/events-not-in-dashboard). </Accordion> <Accordion title="Does Upstack work with headless Shopify setups?"> Yes. Upstack supports headless Shopify storefronts using the **Upstack JavaScript SDK** instead of the Shopify app embed. For headless setups: 1. Install the Upstack SDK via npm or a `<script>` tag. 2. Initialize the SDK with your Pixel ID. 3. Call the tracking methods (`track`, `page`, `identify`) from your storefront code at the appropriate lifecycle points. Server-side event capture (orders, refunds, fulfillments) still works automatically through Shopify webhooks — no additional setup needed. See [Connect Shopify](/sources/shopify) for detailed headless integration instructions. </Accordion> <Accordion title="How does Upstack handle GDPR and privacy compliance?"> Upstack is designed with privacy in mind: * **Server-side first:** Most critical events (purchases, refunds) are captured server-side through Shopify webhooks, not browser cookies. This means tracking is more resilient to browser privacy restrictions while remaining compliant. * **Consent management:** Upstack integrates with popular consent management platforms (OneTrust, Cookiebot, Shopify's native consent API). When a visitor declines tracking, the client-side pixel respects that choice and suppresses non-essential events. * **Data processing:** Upstack processes data in accordance with GDPR, CCPA, and other applicable privacy regulations. Personal data like email and phone number is hashed (SHA-256) before being sent to ad platform destinations. * **Data retention:** You control how long event data is retained in your workspace settings. Default retention is 13 months. * **DPA:** We provide a Data Processing Agreement upon request. Contact [support@upstackdata.com](mailto:support@upstackdata.com). </Accordion> <Accordion title="Can I track custom events?"> Yes. Beyond the automatic standard events, you can track any custom event using the Upstack JavaScript SDK: ```javascript theme={null} upstack.track('WishlistAdd', { product_id: '12345', product_name: 'Blue Widget', value: 29.99, currency: 'USD' }); ``` Custom events: * Appear in the Live Event Stream and dashboards alongside standard events. * Can be forwarded to destinations — you map them in the destination's **Event Mapping** settings. * Support any JSON-serializable properties. * Are subject to the same identity resolution and enrichment as standard events. See [Custom Events](/pixel/custom-events) for naming conventions and best practices. </Accordion> <Accordion title="What happens if my pixel goes down?"> Upstack is built for resilience across multiple layers: * **Server-side backup:** Critical conversion events (purchases, refunds) are captured via Shopify webhooks regardless of pixel availability. Even if the client-side pixel fails completely, your conversion data is safe. * **Edge infrastructure:** The Upstack pixel endpoint runs on Cloudflare's global edge network with 99.99% uptime. Requests are served from the nearest edge location. * **Retry logic:** If an event fails to deliver, it's automatically retried with exponential backoff for up to 24 hours. * **Graceful degradation:** If the pixel script fails to load (due to an ad blocker or network issue), it does not break your storefront. The script is loaded asynchronously and fails silently. In practice, the most common "pixel down" scenario is an ad blocker in *your* browser during testing — your actual customers are rarely affected. </Accordion> <Accordion title="How does identity resolution affect my ad performance?"> Identity resolution is the core of what makes Upstack's server-side tracking valuable for ad platforms: 1. **Higher match rates:** When Upstack resolves an anonymous visitor to a known customer (via login, email at checkout, or cross-session fingerprinting), it enriches the event with hashed PII (email, phone). This gives ad platforms like Meta and TikTok a much higher Event Match Quality (EMQ) score. 2. **Better optimization:** Higher EMQ means the ad platform can match more conversions to ad clicks, which feeds the algorithm more signal. More signal = better audience targeting = lower CPA. 3. **Cross-device attribution:** Identity resolution stitches sessions across devices. A customer who clicks an ad on mobile but purchases on desktop is correctly attributed. Most Upstack customers see a **20–40% improvement in EMQ scores** after enabling Upstack ID compared to client-side-only tracking. Learn more in [Identity Resolution](/pixel/identity-resolution). </Accordion> <Accordion title="What Shopify plans does Upstack support?"> Upstack works with all Shopify paid plans: | Shopify Plan | Supported | Notes | | ---------------- | --------- | --------------------------------------------------------------------- | | Shopify Starter | Partial | Limited webhook support; no online store so pixel tracking is limited | | Basic Shopify | Full | All features available | | Shopify | Full | All features available | | Advanced Shopify | Full | All features available | | Shopify Plus | Full | All features available, including checkout extensibility support | Upstack does **not** support Shopify's free trial period — you must be on an active paid plan for webhooks and app embeds to function. </Accordion> <Accordion title="How do I add team members?"> You can invite team members to your Upstack workspace: 1. Go to **Settings → Team** in the Upstack dashboard. 2. Click **Add Team member** and enter their email address. 3. Choose a role: * **Admin** — full access: manage users, billing, integrations, and data. * **Owner** — account creator; only another owner can remove an owner. * **Member** — can view dashboards and event streams but cannot modify integrations or billing. 4. Click **Add Email** for each user, then click **Send Invitations**. 5. The invited user receives an email with a link to create their Upstack account (or sign in if they already have one). There's no limit on the number of team members on any plan. All roles can access the same event data — roles only control what actions a user can take. For the full walkthrough, see [How to invite a team member to your Upstack account](/resources/how-to-invite-a-team-member-to-your-upstack-account). </Accordion> <Accordion title="What's the difference between sources and destinations?"> Think of Upstack as sitting in the middle of your data flow: * **Sources** are where data comes *from*. These are the platforms that generate events and data that Upstack ingests. Examples: * **Shopify** — storefront events, orders, customers * **Facebook Ads** — ad spend and campaign data * **Google Ads** — ad spend and campaign data * **Destinations** are where data goes *to*. These are the platforms that Upstack forwards enriched event data to. Examples: * **Meta Conversions API (CAPI)** — server-side purchase and conversion events * **TikTok Events API** — server-side events for TikTok ad optimization * **Klaviyo** — customer and event data for email/SMS flows * **Google Analytics 4** — measurement protocol events The key insight: Upstack enriches events with identity resolution *between* source and destination. Raw storefront events go in, identity-resolved and enriched events come out. See [Sources overview](/sources/overview) and [Destinations overview](/destinations/overview) for the full list. </Accordion> </AccordionGroup> *** **Still stuck?** Contact [support@upstackdata.com](mailto:support@upstackdata.com) with your Pixel ID and a description of the issue. We typically respond within a few hours. # Configure contribution margin Source: https://docs.upstackdata.com/get-started/configure-contribution-margin Set up COGS, transaction fees, and marketing spend in Upstack to track CM1–CM4 contribution margins and real profitability. Upstack calculates four tiers of contribution margin so you can optimize on profit, not vanity metrics like revenue or ROAS. Each tier subtracts an additional layer of costs: | Level | What's subtracted | What it tells you | | ------- | --------------------------------------------------- | ---------------------------------------- | | **CM1** | COGS (cost of goods sold) | Gross margin | | **CM2** | + Fulfillment, transaction & gateway fees, shipping | Post-logistics margin | | **CM3** | + Marketing and ad spend | Contribution margin (most commonly used) | | **CM4** | + Operating expenses, agency fees, and other | Operating profit | ## Setup <Steps> <Step title="Enter COGS in Shopify"> Go to **Shopify Admin → Products** and select a product. For each variant, enter the **Cost per item** field. If you sell a product for $30 and it costs $5 to produce, enter \$5. Upstack pulls this in automatically — no manual sync required. <Info> After configuring COGS, allow approximately **4 hours** for historical data to backfill. CM1 values for past orders populate automatically once the backfill completes. </Info> </Step> <Step title="Configure your other costs in Upstack"> Open **Settings → Cost Overview** to add shipping, gateway fees, order costs, a fallback product margin, and fixed and variable costs. Each cost is assigned a category that maps to a contribution-margin tier: | Cost category | CM tier | | ------------------------------------------- | ------- | | COGS (product cost) | CM1 | | Fulfillment, transaction, gateway, shipping | CM2 | | Marketing and ad spend | CM3 | | Operating expenses, agency fees, other | CM4 | Fixed and variable costs land in the tier matching their category. See [Cost settings](/get-started/cost-settings) for a full walkthrough of every category. </Step> <Step title="Connect marketing spend"> Spend from **connected ad platforms** (Meta, Google, TikTok) flows in automatically. For **non-connected channels** (influencer, podcast, and similar), add it under **Settings → Cost Overview** as a fixed or variable cost so it counts toward CM3. </Step> </Steps> ## P\&L dashboard Two views are available: * **Summary** — aggregate P\&L across a date range * **Daily breakdown** — granular day-by-day performance Key metrics include Net Revenue, COGS, CM1, CM2, CM3, CM4, MER, and NCCM3. Over 250 measures are available and fully customizable. <Tip> **NCCM3** is contribution margin (CM3) for **new customers only** — net revenue minus product, fulfillment, transaction, shipping, marketing, and ad-spend costs. It's the single most useful metric for evaluating whether your prospecting spend is profitable after all variable costs. </Tip> <Accordion title="LTV cohort dashboard"> The LTV Cohort Dashboard shows customer lifetime value by acquisition cohort. Use it to measure how quickly cohorts pay back acquisition cost and identify your highest-value customer segments. This replaces standalone LTV tools like Lifetimely — the data is built directly from your Upstack event pipeline, so cohort metrics stay consistent with your P\&L and attribution data. </Accordion> ## Next step <CardGroup> <Card title="Verify end-to-end delivery" icon="arrow-right" href="/get-started/verify-end-to-end"> Confirm the complete pipeline works — from storefront event through attribution to destination delivery. </Card> </CardGroup> ## Related <CardGroup> <Card title="Cost settings" icon="coins" href="/get-started/cost-settings"> Set up product, order, shipping, gateway, fixed, and variable costs in detail. </Card> <Card title="Attribution and reporting" icon="chart-line" href="/concepts/attribution-and-reporting"> Learn how Upstack attributes conversions and calculates reporting metrics across channels. </Card> <Card title="Attribution reporting dashboard" icon="table-columns" href="/analytics/attribution-reporting"> Explore the attribution reporting dashboard and available metrics. </Card> <Card title="Custom events" icon="bolt" href="/guides/custom-events/how-to-create-custom-event-triggers"> Configure NC Purchase, subscription events, and order source exclusions for ad platform optimization. </Card> <Card title="Connect a destination" icon="plug" href="/get-started/connect-a-destination"> Set up Meta CAPI as your first server-side destination for high-quality conversion events. </Card> </CardGroup> # Connect destinations Source: https://docs.upstackdata.com/get-started/connect-a-destination Connect ad platforms and marketing tools as Upstack destinations to receive server-side conversion events with higher match quality. Destinations are the ad platforms and marketing tools that receive your conversion events. Upstack sends events server-side, bypassing browser restrictions and improving match quality. You connect once, and Upstack handles formatting, deduplication, and delivery for each platform. ## Destinations vs sources * **Destinations** receive conversion events (purchases, page views, add-to-carts) from Upstack for ad optimization * **Sources** pull ad spend and performance data *into* Upstack for unified reporting dashboards * Most platforms need both — a destination for conversion tracking and a source for spend data ## Available destinations Each destination has its own hub page with setup guides, event mapping, troubleshooting, and FAQs. Pick the platforms you use and follow the setup guide on each hub. <CardGroup> <Card title="Meta CAPI" href="/destinations/meta-capi"> Connect Meta's Conversions API for server-side event delivery to Facebook and Instagram Ads. </Card> <Card title="Google Ads" href="/destinations/google-ads"> Send purchase conversions to Google Ads with Smart Bidding-ready conversion goals. </Card> <Card title="TikTok" href="/destinations/tiktok"> Forward events to TikTok Events API with token-based auth and click-ID matching. </Card> <Card title="Klaviyo" href="/destinations/klaviyo"> Sync enriched events and profiles to Klaviyo for abandonment flows and email/SMS automation. </Card> <Card title="Pinterest" href="/destinations/pinterest"> Connect Pinterest's Conversion API for server-side conversion tracking. </Card> <Card title="Snapchat" href="/destinations/snapchat"> Send conversion events to Snapchat's Conversion API for ad optimization. </Card> <Card title="Omnisend" href="/destinations/omnisend"> Forward events to Omnisend for email automation and customer profile enrichment. </Card> <Card title="Custom Webhooks" href="/destinations/webhooks"> Stream events to any HTTPS endpoint for custom integrations and data warehousing. </Card> </CardGroup> ## Connect sources for reporting To see ad spend and ROAS in the Upstack dashboard, connect your ad accounts as sources (data integrations). This pulls spend data into Upstack — it doesn't affect conversion tracking. <CardGroup> <Card title="Connect Facebook Ads account" href="/guides/facebook-ads/how-to-connect-your-facebook-ads-account-in-upstack-data-integrations"> Pull Facebook ad spend into Upstack for unified reporting. </Card> <Card title="Connect Google Ads account" href="/guides/integrations/how-to-connect-your-google-ads-account-in-upstack-data-integrations"> Pull Google Ads spend into Upstack for unified reporting. </Card> </CardGroup> ## Next step <CardGroup> <Card title="Disable existing tracking" icon="arrow-right" href="/get-started/disable-existing-tracking"> Remove redundant browser-side tracking to prevent duplicate conversions. </Card> </CardGroup> # Set up cost settings Source: https://docs.upstackdata.com/get-started/cost-settings Configure product costs, order costs, shipping, gateway fees, and fixed and variable costs in Upstack so your contribution margin and P&L reflect real profitability. Cost settings are where you tell Upstack what it actually costs to fulfill an order. Once your costs are in, Upstack subtracts them from revenue to give you accurate contribution margin (CM1–CM4) and a real P\&L — not just revenue and ROAS. This guide walks through each cost category and how to set it up. <Info> Cost settings are available to **admin and owner** roles, and may not be enabled on every account yet. If you don't see the Costs section in Settings, contact the Upstack team. </Info> ## Where to find it Open **Settings → Cost Overview** (under the **Costs** section of the settings menu). The overview lists every cost category as a card and shows which ones you've configured. Each card links to its own page. <Tip> Two things to know before you start: * **Changes apply to past orders too.** When you add or edit a cost, Upstack recalculates matching historical orders within that cost's date range — so your reporting stays consistent. * **You can date every cost.** Most cost lines accept an effective start and end date, so a rate change from last month doesn't rewrite the months before it. </Tip> ## Where to start The overview marks **Gateways** and **Shipping** as recommended starting points — they apply to almost every order. A good first-time order: 1. **Gateways** — your payment processing fees 2. **Shipping** — what it costs to ship an order 3. **Product Defaults** — a fallback margin so every product has a cost 4. **Order Costs** — any other per-order or per-item fees Add **Product Costs**, **Fixed Costs**, and **Variable Costs** as you need them. ## Product Defaults Two settings that apply when a product is missing its own cost data: * **Default COGS %** — a percentage of the item's sale price (0–100), used as the cost of goods for any product that has no specific cost. This is the fallback when a variant has no cost. * **Global Handling Fee** — a flat amount added per line item. This is a separate handling cost that applies whenever it's set; it isn't part of the product-cost fallback. Set the Default COGS % first so no order is ever missing a product cost. ## Product Costs Per-variant cost overrides. If you maintain **Cost per item** in Shopify, Upstack syncs it automatically — those synced costs are read-only here. You can also enter your own cost for any variant, with effective date ranges; your manual entry takes precedence over the Shopify-synced value. <Note> Give each cost entry for a variant a **different start date**. If two entries share the same start date, only one of them is used for an order, and Upstack flags the duplicate so you can fix it. </Note> ## Order Costs Fees that apply per order, per line item, or per refund — beyond product cost. For each cost line you choose how it's calculated: | Type | What it does | | ------------------------------------------------ | ----------------------------------- | | Per Order / Per Line Item | A flat amount per order or per item | | Per Refund Order / Per Refund Line Item | A flat amount applied on refunds | | By Order Weight | Tiered by the order's weight | | By Order Quantity / By Line Item Quantity | Tiered by how many units | | % of COGS / Shipping / Total / Gross / Net Sales | A percentage of the chosen base | Each cost line is assigned a **category** (COGS, Fulfillment, Transaction, Marketing, Agency Fees, Opex, or Other) — which determines its contribution-margin tier — and a **channel** (Online, POS, or Both). Rich filters let you scope a cost to specific gateways, tags, vendors, product types, countries, or products. ## Shipping Choose how Upstack accounts for shipping cost, using one of three modes: | Mode | When to use it | | -------------------------------- | ------------------------------------------------------- | | **Use Shopify Shipping Charges** | Use the shipping amount already on your Shopify orders | | **Fixed Rate Per Order** | Apply one flat shipping cost to every order | | **Shipping Profiles** | Set rates by country/region — flat, or tiered by weight | With **Shipping Profiles**, each profile matches one or more countries. A profile can be a single **Flat Rate** or **Weight Tiered**, and you can set a default profile as a fallback. <Warning> If two shipping profiles cover the same country, Upstack shows an **Overlapping Shipping Profiles** warning and uses the first match. Keep country coverage distinct so the right rate always applies. </Warning> ## Gateways Payment processing fees per gateway, entered as a flat amount plus a percentage: * **Flat Fee** — a fixed amount per transaction (e.g. \$0.30) * **Percent Fee (%)** — a percentage of the order (e.g. 2.9%) Gateway names are discovered from your order history, so you only configure the ones you actually use. ## Fixed Costs Recurring overheads like rent, salaries, and software subscriptions. Set an amount and a **frequency** — Daily, Weekly, Monthly, Quarterly, or Yearly — and a **category** (Marketing, Opex, Agency Fees, or Other). Upstack averages the cost across the period so it shows up correctly in your P\&L. ## Variable Costs Costs that scale with ad spend. Today this is **% of Ad Spend** — a percentage applied to your ad spend, with an optional filter for which ad platforms it applies to, under a **Marketing** or **Opex** category. Useful for agency fees or tools billed as a percentage of spend. ## How costs roll into contribution margin Each cost's **category** decides which margin tier it reduces: | Tier | Reduced by costs in these categories | | ------- | ----------------------------------------------- | | **CM1** | Cost of goods sold (product cost) | | **CM2** | Fulfillment, transaction, gateway, and shipping | | **CM3** | Marketing — your marketing costs and ad spend | | **CM4** | Operating expenses, agency fees, and other | Fixed and variable costs land in the tier that matches the **category** you give them — a Marketing-category cost reduces CM3, while an Operating expenses, Agency fees, or Other cost reduces CM4. See [Contribution margin](/get-started/configure-contribution-margin) for how the tiers are used across the P\&L dashboard. ## Frequently asked questions <AccordionGroup> <Accordion title="Do cost changes apply to past orders?"> Yes. When you add or edit a cost, Upstack recalculates matching historical orders within that cost's effective date range. Set start and end dates to control exactly which orders a cost applies to. </Accordion> <Accordion title="What happens if a product has no cost?"> Its cost falls back to your **Default COGS %** from Product Defaults. (The Global Handling Fee is a separate cost that applies on its own, not part of this fallback.) Set the Default COGS % first so every order has a product cost. </Accordion> <Accordion title="Which costs land in which margin tier?"> A cost's category determines its tier: COGS → CM1; Fulfillment, Transaction, Gateway, and Shipping → CM2; Marketing and ad spend → CM3; Operating expenses, Agency Fees, and Other → CM4. Fixed and variable costs follow the same rule — they land in the tier matching their category. </Accordion> <Accordion title="Can I set costs in a different currency?"> Yes. You can enter a cost in its own currency, and Upstack converts it into the order's currency for you. </Accordion> <Accordion title="Who can edit cost settings?"> Admin and owner roles. The Costs section may not be enabled on every account yet — contact the Upstack team if you don't see it. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Contribution margin" icon="layer-group" href="/get-started/configure-contribution-margin"> How CM1–CM4 and the P\&L dashboard use your costs. </Card> <Card title="Manage costs from the CLI" icon="terminal" href="/cli/costs"> Read and update cost configuration with the `upstack costs` command. </Card> <Card title="Attribution and reporting" icon="chart-line" href="/concepts/attribution-and-reporting"> How Upstack attributes conversions and calculates reporting metrics. </Card> <Card title="Costs API" icon="code" href="/api-reference/overview"> Manage cost configuration programmatically. </Card> </CardGroup> # Create an Upstack Data account Source: https://docs.upstackdata.com/get-started/create-an-account Sign up for Upstack Data at app.upstackdata.com/signup to start capturing server-side events from your store. Creating an Upstack account is the first step. You'll set up your workspace, choose a plan, and connect your store. The whole process takes about 5 minutes. ## Sign up <Steps> <Step title="Go to the Upstack signup page"> Open [app.upstackdata.com/signup](https://app.upstackdata.com/signup) in your browser. </Step> <Step title="Create your account"> Enter your email and choose a password. You'll receive a verification email — click the link to confirm your address. </Step> <Step title="Set up your workspace"> Enter your company name and basic details. The workspace name appears in the Upstack dashboard and on billing receipts. </Step> <Step title="Choose a plan"> Select a plan that matches your store volume. You can [compare plans](/billing/plans-and-pricing) and change your selection later from the billing settings page. </Step> <Step title="Add a payment method"> Enter card details through Stripe. Upstack offers a 21-day free trial — your card is not charged until the trial ends. </Step> </Steps> <Tip> **Already have an account?** Sign in at [app.upstackdata.com](https://app.upstackdata.com) instead. If you previously installed Upstack Data through the Shopify App Store, your account was created during the install — sign in with the email you used. </Tip> ## What happens next Once your account is active, you'll connect your store as a data source. The next step depends on your platform: <CardGroup> <Card title="Install on Shopify" href="/get-started/install-on-shopify"> The most common path. Install the Upstack Data Shopify app and enable the tracking pixel. </Card> <Card title="Headless Shopify" href="/installation/headless-shopify"> For Hydrogen, Next.js, Remix, or other custom storefronts. </Card> <Card title="WordPress / GTM" href="/resources/implementing-upstack-data-on-landing-pages"> Install Upstack on WordPress via Google Tag Manager. </Card> <Card title="Checkout Champ" href="/resources/how-to-set-up-upstack-data-on-checkout-champ"> Install Upstack on a Checkout Champ funnel. </Card> </CardGroup> ## Next step <CardGroup> <Card title="Install on Shopify" icon="arrow-right" href="/get-started/install-on-shopify"> Connect your Shopify store and start capturing events. </Card> </CardGroup> # Disable existing tracking Source: https://docs.upstackdata.com/get-started/disable-existing-tracking Remove duplicate pixels, Elevar tags, native Shopify integrations, and third-party trackers after Upstack is confirmed firing. Running two tracking systems at the same time causes duplicate events, inflated attribution, and corrupted ad platform optimization. This is the most critical step in your migration — get the order right. <Warning> **Never disable old tracking before Upstack is confirmed working.** A gap in event data is worse than a brief overlap. Verify Upstack events are firing first (check the Upstack debug view or Meta Pixel Helper), then proceed with the steps below. </Warning> ## Order of operations <Steps> <Step title="Verify Upstack is firing"> Confirm events are flowing in the Upstack dashboard or with Meta Pixel Helper before you touch anything. If Upstack isn't sending events yet, stop here and resolve that first. </Step> <Step title="Disable old Facebook/Meta tags"> Remove or pause your previous tool's Facebook/Meta event tags. This is the highest-priority item — Meta is the most common source of duplicate conversions. </Step> <Step title="Disable old Klaviyo secondary flows"> If your previous tool (Elevar, Triple Whale, etc.) created secondary Klaviyo abandonment flows, disable them. Upstack's flows replace these. See the [Klaviyo destination hub](/destinations/klaviyo) for the replacement flow setup. </Step> <Step title="Disable old TikTok and other ad platform tags"> Pause or remove your previous tool's TikTok, Snapchat, and Google Ads event tags if Upstack is now handling those destinations. </Step> <Step title="Enable any inactive Upstack destinations"> If any Upstack destinations were set to **Inactive** during initial setup, toggle them to **Active** now. </Step> <Step title="Monitor for 24–48 hours"> Watch for duplicate events in your ad platform dashboards. Check event counts in the Upstack dashboard against what each platform reports. If counts roughly double what you expect, a legacy tag is still firing. </Step> </Steps> ## What to disable <AccordionGroup> <Accordion title="Elevar / Google Tag Manager"> Most brands migrating to Upstack are coming from Elevar. Elevar fires events through Google Tag Manager, so you'll disable tracking there. 1. Open **GTM → Tags**. 2. Find Elevar's **Meta/Facebook tags** — pause or disable them. 3. Find Elevar's **Klaviyo tags** (if present) — pause or disable them. 4. **GA4 tags:** Check whether they run through Elevar or are standalone. If standalone, leave them — Upstack does not replace GA4. 5. **Google Ads tags:** Same check. If standalone, leave them. 6. **Save and publish** the GTM container. In Klaviyo, disable Elevar's secondary abandonment flows (Browse, Cart, Checkout). Upstack's flows replace these. </Accordion> <Accordion title="Native Shopify Facebook & Instagram"> 1. In Shopify Admin, go to **Sales Channels → Facebook & Instagram**. 2. Open **Settings → Data Sharing**. 3. Turn data sharing **OFF**. You don't need to uninstall the sales channel. Shop features and your product catalog still work — you're only disabling the pixel/event tracking. For detailed steps, see [How to disable Facebook and Instagram data sharing in Shopify](/guides/facebook-ads/how-to-disable-facebook-and-instagram-data-sharing-in-shopify). </Accordion> <Accordion title="Native Shopify TikTok"> Disable the tracking and pixel features within the TikTok sales channel settings. If you're not using TikTok Shop features (product sync, in-app checkout), you can uninstall the channel entirely. For detailed steps, see [How to disable TikTok data sharing in Shopify](/guides/tiktok-ads/how-to-disable-tiktok-data-sharing-in-shopify). </Accordion> <Accordion title="Feed apps (Symprosis, etc.)"> Feed apps sometimes have tracking features enabled alongside their catalog sync function. These fire extra pixels that duplicate what Upstack sends. **Disable:** * Custom pixels within the feed app * Facebook pixel tracking within the feed app * GA4 tracking within the feed app **Keep:** * Product catalog and feed sync features — these don't conflict with Upstack </Accordion> <Accordion title="Third-party pixel apps"> Uninstall any standalone pixel management apps: * Omega TikTok Pixel * Add Naboo Pixel * Trackify * Any other app whose sole purpose is firing conversion pixels Upstack fully replaces these. </Accordion> <Accordion title="Cookie / GDPR consent banners (US-only brands)"> For stores that only sell to US customers, consider disabling Shopify's cookie consent banner. Consent banners block tracking scripts until a visitor opts in — and most visitors never do. 1. In Shopify Admin, go to **Settings → Privacy → Cookie Banner → Regions**. 2. Set the region to **None**. Removing the banner can increase trackable sessions by 25% or more on low-volume stores. <Warning> **Keep your consent banner** if you have EU or UK customers. GDPR requires consent management for those regions, and removing the banner creates legal exposure. </Warning> </Accordion> <Accordion title="Triple Whale / Northbeam"> These tools can run in parallel with Upstack during a comparison period (30 days recommended). You don't need a hard cutover. **Disable immediately:** * Triple Whale's secondary Klaviyo flows — disable as soon as Upstack's flows go live * Any server-side event forwarding to the same platform Upstack is already sending to (running both tools' CAPI events to Meta simultaneously causes double-counting) **Can keep running:** * The Triple Whale or Northbeam dashboard for attribution comparison during your evaluation period </Accordion> <Accordion title="GA4"> <Info> Upstack does **not** replace GA4. Keep GA4 connected through Shopify's native connector or your standalone GTM setup. </Info> GA4's attribution model differs fundamentally from Meta and Google Ads — the numbers will never match across these systems, and that's expected. GA4 serves a different analytical purpose than ad platform conversion tracking. </Accordion> </AccordionGroup> ## You'll know it's working when... * [ ] Old tracking tags are paused or removed in GTM / Shopify / third-party apps * [ ] Upstack destinations show **Active** status (green) in the dashboard * [ ] Ad platform event counts are stable (not doubled) over a 24–48 hour window * [ ] No duplicate conversion warnings appear in Meta Events Manager diagnostics ## Next step <CardGroup> <Card title="Set up custom events" icon="arrow-right" href="/guides/custom-events/how-to-create-custom-event-triggers"> Send new customer purchase data and other specialized signals to Meta for better optimization. </Card> </CardGroup> ## Related <CardGroup> <Card title="Disable Facebook data sharing in Shopify" icon="meta" href="/guides/facebook-ads/how-to-disable-facebook-and-instagram-data-sharing-in-shopify"> Step-by-step guide to turning off native Shopify Facebook & Instagram data sharing. </Card> <Card title="Disable TikTok data sharing in Shopify" icon="music" href="/guides/tiktok-ads/how-to-disable-tiktok-data-sharing-in-shopify"> How to disable TikTok event tracking in the Shopify sales channel. </Card> <Card title="Disable Snapchat data sharing in Shopify" icon="ghost" href="/guides/snapchat-ads/how-to-disable-snapchat-data-sharing-in-shopify"> How to disable Snapchat event tracking in Shopify. </Card> <Card title="Troubleshooting: Duplicate events" icon="wrench" href="/troubleshooting/duplicate-events"> Diagnose and resolve duplicate conversion events across your ad platforms. </Card> </CardGroup> # Health and wellness brand setup Source: https://docs.upstackdata.com/get-started/health-wellness-setup How Upstack's server-side protective container keeps health and wellness brands compliant with Meta restrictions and prevents pixel flagging. Health and wellness brands — supplements, CBD, wellness products — face unique tracking restrictions from Meta. Standard browser pixels can trigger flagging, ad account restrictions, and blocked purchase events. This guide covers what's different about the Upstack setup for H\&W brands and how the server-side protective container keeps you compliant. ## Why H\&W Brands Need a Different Setup Meta restricts or flags health and wellness brands that send certain event data through standard browser pixels. The consequences escalate quickly: * **Pixel flagging or rejection** — Meta categorizes your domain as restricted and limits event processing * **Ad account restrictions** — campaigns are paused or accounts are disabled without warning * **Purchase events blocked** — your highest-value conversion signal disappears from optimization * **CPAs spike** — costs increase with no clear cause as Meta's algorithm loses signal Upstack handles this with a server-side **protective container** that filters event payloads before Meta sees them. ## How the Protective Container Works The protective container changes the event pipeline so Meta never receives data that triggers health and wellness restrictions: 1. Upstack removes the browser pixel entirely — all events route server-side via CAPI only 2. The protective container strips restricted data fields from event payloads 3. Custom events (e.g., `upstack_hw`) replace standard purchase events for optimization 4. Meta receives clean, compliant data without triggering health and wellness restrictions <Info> You can toggle between the standard and H\&W containers at any time from the Upstack dashboard. If you're unsure which setup you need, Upstack starts with the standard container and switches to H\&W only if needed. </Info> ## Setup Differences from Standard Onboarding The H\&W setup follows the same onboarding flow with three critical differences. Everything else — Shopify install, Google Ads, Klaviyo, TikTok — works the same as standard onboarding. <Warning> **Do NOT connect the Facebook destination yourself.** Wait for Upstack to deploy the server-side protective container first. Connecting Meta before the container is live will expose your domain to flagging. Deployment typically happens the same day as your onboarding call. </Warning> <Steps> <Step title="Wait for the protective container deployment"> After your onboarding call, Upstack deploys the server-side protective container for your account. This typically happens the same day. You'll receive confirmation when the container is live and ready. Do not proceed with the Meta destination setup until you've received this confirmation. </Step> <Step title="Add your domain to Meta's verified domains"> Once the container is live, add your Shopify storefront domain to Meta's verified domains and approval list in **Meta Business Settings → Brand Safety → Domains**. For details on how the domain aliasing works with the protective container, see [How Domain Aliasing Works for Health & Wellness Tracking](/guides/facebook-ads/how-domain-aliasing-works-for-health-wellness-tracking). </Step> <Step title="Confirm before running ads"> Do not run Meta ads until the container is confirmed live and your domain is verified. Running ads before the container is active exposes your pixel to the same flagging risks you're trying to avoid. Once confirmed, Upstack configures custom event mappings that replace standard purchase events. See [Health & Wellness Custom Event Mappings](/guides/facebook-ads/health-and-wellness-custom-event-mappings) for the full mapping reference. </Step> </Steps> ## Advanced Configuration <Accordion title="Recovery timeline for flagged accounts"> If your account has already been flagged by Meta, Upstack's H\&W recovery process can restore your event pipeline: * **100% success rate** on H\&W recovery setups to date * **CPAs typically return to baseline within \~60 days** as Meta's algorithm re-learns with clean data * **Recovery process:** server-side container deployed → browser pixel removed → custom events replace standard events → Meta re-evaluates your domain The timeline depends on how severely your account was flagged. Brands with multiple flags or disabled ad accounts may take longer to fully recover, but the protective container prevents further flagging from day one. </Accordion> <Accordion title="When to use H&W vs. standard setup"> **Use the H\&W container when:** * Your domain is flagged or categorized as health and wellness by Meta * Your purchase event has been rejected * You sell supplements, CBD, wellness products, or anything Meta considers restricted * You've been flagged or restricted multiple times **Standard setup is sufficient when:** * Your brand is throttled or penalized but not categorized as H\&W * You sell products adjacent to H\&W but not in a restricted category Upstack tries the standard container first and switches to H\&W only if needed. You can toggle between standard and H\&W containers at any time. </Accordion> <Accordion title="New Business Manager strategy"> For brands with a thoroughly flagged Business Manager, starting fresh may be the fastest path to recovery: * **Create a new Business Manager** with a new pixel to get a clean slate * **Don't run two pixels from the same ad account** — the newer pixel will retarget the old pixel's funnel and steal conversions * **Recommended approach:** pause old campaigns, clone them, and relaunch with the new pixel * **Alternative:** test with one campaign first before committing to a full migration Combine the new Business Manager with Upstack's protective container to ensure the new pixel stays clean from day one. </Accordion> ## Back to Getting Started <CardGroup> <Card title="Verify End-to-End Delivery" icon="arrow-left" href="/get-started/verify-end-to-end"> Go back to the final verification step and confirm your complete pipeline is working. </Card> </CardGroup> ## Related <CardGroup> <Card title="H&W Custom Event Mappings" icon="table" href="/guides/facebook-ads/health-and-wellness-custom-event-mappings"> Reference for how standard events are remapped to custom events in the protective container. </Card> <Card title="Domain Aliasing for H&W Tracking" icon="globe" href="/guides/facebook-ads/how-domain-aliasing-works-for-health-wellness-tracking"> How Upstack's domain aliasing works alongside the protective container for health and wellness brands. </Card> <Card title="Connect a Destination" icon="plug" href="/get-started/connect-a-destination"> Standard Meta CAPI destination setup for brands not in restricted categories. </Card> <Card title="Conversion API Forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> Learn how Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> </CardGroup> # Install Upstack on Shopify Source: https://docs.upstackdata.com/get-started/install-on-shopify Connect your Shopify store to Upstack from the Upstack dashboard and start capturing server-side events in under 10 minutes. Connect Shopify from inside the Upstack dashboard — not from the Shopify App Store. Sign in to Upstack, open **Data Sources → Shopify**, then authorize the install in your Shopify Admin. From there, enable the theme app extension, add the custom pixel, and verify events. <Info> **Prerequisite:** an active Upstack Data account. If you haven't already, [create your Upstack account](/get-started/create-an-account) before continuing. </Info> <CardGroup> <Card title="Complete Shopify setup guide" icon="arrow-right" href="/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify"> Step-by-step walkthrough with screenshots covering all parts. </Card> </CardGroup> ## Individual step guides <CardGroup> <Card title="Install the app" icon="download" href="/guides/shopify/how-to-download-and-install-upstack-data-app-in-shopify"> Connect your Shopify store from the Upstack dashboard. </Card> <Card title="Enable theme extension" icon="toggle-on" href="/guides/shopify/how-to-ensure-upstack-data-theme-app-extension-is-enabled"> Verify the theme app extension is active in your Shopify theme editor. </Card> <Card title="Install Pixel Helper" icon="puzzle-piece" href="/guides/shopify/how-to-install-upstack-data-pixel-helper"> Install the browser extension to debug pixel events in real time. </Card> <Card title="Pixel privacy settings" icon="shield-halved" href="/guides/shopify/how-to-setup-upstack-custom-pixel-privacy-settings"> Configure consent and privacy settings for the Upstack custom pixel. </Card> </CardGroup> ## Headless Shopify If your storefront runs on Shopify Hydrogen, Next.js, Remix, or another custom framework, the theme app extension won't load. Use the Upstack JavaScript SDK instead. <CardGroup> <Card title="Headless Shopify installation" icon="code" href="/installation/headless-shopify"> Install the Upstack pixel via CDN script or the `@upstackdata/pixel` npm package on Hydrogen, Next.js, Remix, and other custom storefronts. </Card> </CardGroup> ## Alternative: Use the CLI Prefer working from the terminal? The Upstack CLI lets you query data, manage dashboards, and automate workflows without opening the web app. <CardGroup> <Card title="Install the CLI" icon="terminal" href="/cli/install"> Install the `upstack` CLI and configure it with your API key and pixel ID. </Card> </CardGroup> ## Next step <CardGroup> <Card title="Verify events are flowing" icon="arrow-right" href="/get-started/verify-events"> Confirm your store is sending the right events and they appear in the dashboard. </Card> </CardGroup> # Step 4: Validate End-to-End Delivery Source: https://docs.upstackdata.com/get-started/verify-end-to-end Confirm the complete pipeline works — from storefront event to Upstack dashboard to a matched conversion in Meta Events Manager. You've installed the pixel, verified events, and connected Meta CAPI. Now run a single end-to-end test to confirm the full pipeline is working: a storefront action should flow through Upstack and arrive as a matched conversion in Meta. ## What You'll Accomplish Trigger a real event on your Shopify store and trace it through every stage — from the Upstack Live Event Stream to Meta Events Manager — confirming that server-side conversion data is being delivered correctly. ## Prerequisites <Info> **Prerequisites:** * An active Shopify store * The Upstack Data app installed from the Shopify App Store * Your Pixel ID (found in the Upstack dashboard under Settings → Pixel) </Info> You should have completed [Step 3: Connect a Destination](/get-started/connect-a-destination). ## Validation Steps <Steps> <Step title="Prepare your test environment"> Open three tabs: 1. **Upstack Dashboard** — navigate to **Events → Live Event Stream** 2. **Meta Events Manager** — navigate to **Your Pixel → Test Events** and enter your storefront URL 3. **Your Shopify storefront** — use an incognito/private window for a clean session <Info> Using Meta's **Test Events** tab gives you real-time visibility into incoming server events. Events in Test Events show within seconds, while the main Overview tab can have a 20+ minute delay. </Info> </Step> <Step title="Trigger a test purchase or add-to-cart"> On your Shopify storefront, perform a complete flow: 1. Visit a product page (generates `ViewContent`) 2. Add the product to cart (generates `AddToCart`) 3. Begin checkout (generates `InitiateCheckout`) 4. If possible, complete a test purchase using Shopify's [Bogus Gateway](https://help.shopify.com/en/manual/checkout-settings/test-orders) (generates `Purchase`) <Tip> If you can't complete a test purchase, an `AddToCart` event is sufficient to validate the pipeline. The key is confirming the event appears in both Upstack and Meta. </Tip> </Step> <Step title="Confirm the event in Upstack"> Switch to the Upstack Live Event Stream tab. Within a few seconds, you should see the events you just triggered. Click on an event to expand it and verify: * **Event type** matches your action (`AddToCart`, `Purchase`, etc.) * **Pixel ID** is correct * **User data** is populated (especially if you entered shipping details at checkout) * **Destination status** shows the event was forwarded to Meta </Step> <Step title="Confirm the event in Meta Events Manager"> Switch to Meta Events Manager → Test Events. You should see the corresponding server event within 2-5 minutes. Look for: * The event name matches (e.g., `AddToCart` or `Purchase`) * The source shows **Server** (not just Browser) * The event details include user data parameters like `em` (hashed email), `ph` (hashed phone) If you see the event from both Browser and Server sources but only counted once, deduplication is working correctly. </Step> </Steps> ## You'll Know It's Working When... <Tip> Your end-to-end pipeline is validated when a single storefront action produces a matched event in both the Upstack Live Event Stream and Meta Events Manager. The Meta event should show **Server** as the source, include hashed user data parameters, and arrive within 5 minutes of the storefront action. </Tip> If any step fails, refer back to the relevant earlier step: * Events not appearing in Upstack? See [Step 2: Verify Events Are Flowing](/get-started/verify-events) * Events in Upstack but not Meta? See the troubleshooting section in [Step 3: Connect a Destination](/get-started/connect-a-destination) ## Next Step <CardGroup> <Card title="What's Next" icon="arrow-right" href="/overview"> Your core pipeline is live. Explore what to do next — add more destinations, dive into attribution, or configure advanced identity resolution. </Card> </CardGroup> ## Related <CardGroup> <Card title="Events not reaching destination" icon="triangle-exclamation" href="/troubleshooting/events-not-reaching-destination"> Troubleshoot events visible in Upstack but not arriving at Meta, TikTok, or other destinations. </Card> <Card title="Duplicate events" icon="clone" href="/troubleshooting/duplicate-events"> Fix duplicate events, inflated revenue, and doubled conversion counts in your pipeline. </Card> <Card title="EMQ showing zeros" icon="chart-line" href="/guides/facebook-ads/why-is-my-meta-emq-panel-showing-zeros-0-0-10"> Understand why your Meta Event Match Quality panel may show zero values and how to fix it. </Card> </CardGroup> # Step 2: Verify Events Are Flowing Source: https://docs.upstackdata.com/get-started/verify-events Confirm that your Shopify store is sending tracking events to the Upstack pipeline before connecting a destination. Before connecting a destination like Meta CAPI, take a minute to verify that your events are arriving correctly. This saves you from debugging destination issues that are actually source issues. ## What You'll Accomplish Confirm that storefront actions generate events in the Upstack dashboard with the expected event types, URLs, and customer data. ## Prerequisites <Info> **Prerequisites:** * An active Shopify store * The Upstack Data app installed from the Shopify App Store * Your Pixel ID (found in the Upstack dashboard under Settings → Pixel) </Info> You should have already completed [Step 1: Install the Upstack Pixel](/get-started/install-on-shopify). ## Verification Steps <Steps> <Step title="Open the Live Event Stream"> In the Upstack dashboard, navigate to **Events → Live Event Stream**. This view shows events arriving from your store in real time, with the most recent events at the top. Leave this tab open — you'll use it to confirm events as you trigger them. </Step> <Step title="Trigger a test pageview"> Open your Shopify storefront in a new browser tab (or incognito window for a clean session). Visit your store's homepage. Switch back to the Live Event Stream. Within a few seconds, you should see a `PageView` event appear with the URL of your homepage. </Step> <Step title="Trigger additional event types"> Continue browsing your store to generate a range of events: | Action | Expected Event | | --------------------- | ------------------ | | View a product page | `ViewContent` | | Add a product to cart | `AddToCart` | | Begin checkout | `InitiateCheckout` | Verify each event appears in the stream with the correct event type and a populated URL. </Step> <Step title="Inspect an event payload"> Click on any event in the Live Event Stream to expand its details. Confirm the payload includes: * **Pixel ID** — matches the Pixel ID shown in Settings → Pixel * **Event type** — correct for the action you took * **Page URL** — matches the page you visited * **Timestamp** — recent and in the correct timezone * **User data** — if you're logged in as a customer, look for email or customer ID fields </Step> </Steps> ## You'll Know It's Working When... <Tip> You should see at least three different event types (`PageView`, `ViewContent`, `AddToCart`) in the Live Event Stream, each with a valid payload containing your Pixel ID, a page URL, and a recent timestamp. If events appear within seconds of your storefront actions, your pipeline is healthy. </Tip> <Warning> **Missing events?** If you see `PageView` events but not `AddToCart` or `ViewContent`, your Shopify theme may be missing standard event hooks. Check **Shopify Admin → Online Store → Themes → Customize → App Embeds** and ensure Upstack Data is enabled. See [Troubleshooting: Events Not in Dashboard](/troubleshooting/events-not-in-dashboard) for more. </Warning> ## Next Step <CardGroup> <Card title="Step 3: Connect a Destination" icon="arrow-right" href="/get-started/connect-a-destination"> Now that events are flowing into Upstack, connect Meta as your first destination and start sending high-quality server-side conversions to your ad account. </Card> </CardGroup> ## Related <CardGroup> <Card title="Use Pixel Helper" icon="magnifying-glass" href="/guides/shopify/how-to-use-upstack-data-pixel-helper"> Learn how to use the Upstack Pixel Helper browser extension to inspect events firing on your storefront. </Card> <Card title="Install Pixel Helper" icon="puzzle-piece" href="/guides/shopify/how-to-install-upstack-data-pixel-helper"> Install the Upstack Pixel Helper browser extension to debug pixel events in real time. </Card> <Card title="Events not in dashboard" icon="triangle-exclamation" href="/troubleshooting/events-not-in-dashboard"> Troubleshoot missing events in your Upstack dashboard — covers pixel installation, browser blockers, and theme conflicts. </Card> </CardGroup> # Complete How-To Guide for Onboarding AppLovin in Upstack Data Source: https://docs.upstackdata.com/guides/applovin-ads/complete-how-to-guide-for-onboarding-applovin-in-upstack-data Onboard AppLovin Axon in Upstack Data — locate your Pixel ID (Event Key), generate the Conversions API token, and configure the destination for server-side conversion tracking. <Info> **New to Upstack?** Follow the [getting started guide](/get-started/install-on-shopify) for a streamlined onboarding walkthrough. </Info> <Tip> * Configure the **AppLovin destination** in Upstack Data with your **Pixel ID** (Event Key) and **Conversions API access token**. * Verify events appear in the **AppLovin Axon Dashboard** Events section within 5-10 minutes. * Monitor match quality improvements as more identified customers convert. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to an **AppLovin Axon** account * A configured **Axon Pixel** in the [AppLovin Dashboard](https://dash.applovin.com/) * A **Conversions API access token** generated from the Axon Dashboard — see [How to generate your AppLovin CAPI token](/guides/applovin-ads/how-to-generate-applovin-conversion-api-token) <Steps> <Step title="Locate your AppLovin Pixel ID (Event Key)"> In the AppLovin Dashboard, navigate to **Account → General → Keys** to find your **Event Key** (Pixel ID). Help guide: [How to find your AppLovin Pixel ID →](/guides/applovin-ads/how-to-find-applovin-pixel-id) </Step> <Step title="Generate a Conversions API access token"> In the AppLovin Dashboard, navigate to **Account → General → Keys** and generate a new **Conversions API Key**. Help guide: [How to generate your AppLovin CAPI token →](/guides/applovin-ads/how-to-generate-applovin-conversion-api-token) </Step> <Step title="Configure the AppLovin destination in Upstack Data"> In the Upstack dashboard, navigate to **Event Destinations** and add an **AppLovin** destination using your **Pixel ID** and **Conversions API access token**. Help guide: [How to configure the AppLovin destination in Upstack Data →](/guides/applovin-ads/how-to-configure-applovin-destination-in-upstack-data) </Step> <Step title="Verify the full setup is healthy"> Confirm each piece of the setup is working: * In the Upstack dashboard, **Event Destinations** shows your AppLovin destination as **Healthy** (green). * In the [AppLovin Axon Dashboard](https://dash.applovin.com/), the Events section shows recent events arriving via the Conversions API. * Events appear within 5-10 minutes of storefront activity. If anything is unhealthy, check the corresponding help guide above for troubleshooting steps. </Step> </Steps> ## What to expect after setup ### Event delivery timeline * **Events start appearing** in the AppLovin Dashboard within 5-10 minutes of storefront activity. * **Match quality improves** as more identified customers (with email/phone at checkout) convert. * The `dedupe_id` ensures browser Pixel events and server-side CAPI events are not double-counted. ### Reporting differences * Your **AppLovin campaign performance** will likely improve after a few days as the algorithm receives more complete conversion data. * Conversion volume may temporarily fluctuate during the first 48 hours as AppLovin's deduplication logic adjusts to receiving both pixel and CAPI events. <Warning> **Important:** AppLovin's batch API drops the **entire batch** if any single event is invalid. Ensure all events include a `dedupe_id` and at least one user identifier (`aleid`, `axwrt`, `client_id`, `email`, `phone`, or `user_id`). </Warning> <Note> **Need help?** If you encounter any issues during setup or events aren't appearing after 15 minutes, contact our [support team](/support) with your **AppLovin Pixel ID** and we'll help diagnose the problem. </Note> # How to Configure AppLovin Destination in Upstack Data Source: https://docs.upstackdata.com/guides/applovin-ads/how-to-configure-applovin-destination-in-upstack-data Configure the AppLovin Axon destination in Upstack Data with your Pixel ID and Conversions API access token to enable dual tracking via browser pixel and server-side CAPI. <Tip> * In the Upstack dashboard, go to **Event Destinations** and click **+ New Destination**. * Select **AppLovin Axon**. * Enter your **Pixel ID** (Event Key from AppLovin Dashboard). * Paste your **Conversions API access token**. * Click **Create Configuration** and verify the destination shows **Healthy**. </Tip> <Note> **What this setup enables** Setting up the AppLovin destination in Upstack Data enables dual tracking via browser pixel and server-side Conversions API (CAPI), recovering conversions lost to ad blockers, iOS restrictions, and cross-device journeys. </Note> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to an **AppLovin Axon** account * A configured **Axon Pixel** in the [AppLovin Dashboard](https://dash.applovin.com/) — see [How to find your AppLovin Pixel ID](/guides/applovin-ads/how-to-find-applovin-pixel-id) * A **Conversions API access token** — see [How to generate your AppLovin CAPI token](/guides/applovin-ads/how-to-generate-applovin-conversion-api-token) ## Configuration steps <Steps> <Step title="Sign in to Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com/pixel/event-destinations). </Step> <Step title="Open the destination configuration"> In the Upstack dashboard, navigate to **Event Destinations**. Click **+ New Destination** in the top-right of the page. In the **Select a Destination** popup, click **AppLovin Axon**, then click **Next**. </Step> <Step title="Enter your Pixel ID and CAPI token"> Fill in the form: 1. **Pixel ID** — the Event Key identifier for your Axon pixel. Find this in the AppLovin Dashboard under Account → General → Keys. 2. **Conversions API access token** — a secure key generated from the AppLovin Dashboard under Account → General → Keys. <Warning> The Conversions API token is a secure key. Store it securely and never expose it client-side. If the token is compromised, generate a new one in the AppLovin Dashboard. </Warning> <Note> **Need help finding these?** * [How to find your AppLovin Pixel ID](/guides/applovin-ads/how-to-find-applovin-pixel-id) * [How to generate your AppLovin CAPI token](/guides/applovin-ads/how-to-generate-applovin-conversion-api-token) </Note> </Step> <Step title="Configure optional settings"> **Enable Conversion API** — Toggle this on to send events to AppLovin's server-side Conversions API (recommended). **Send User Data** — Toggle this on to include hashed PII (email, phone) for improved match quality. </Step> <Step title="Create the configuration"> Click the **Create Configuration** button. You should see a confirmation message and the AppLovin destination will appear in your **Event Destinations** list. </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, the AppLovin destination card should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**: * Confirm your **Pixel ID** is correct (no leading/trailing spaces). * Confirm your **Conversions API token** was pasted in full (no truncation, no whitespace). * Confirm the token was generated for the same AppLovin account as the Pixel ID. </Step> </Steps> # How to Find your AppLovin Pixel ID Source: https://docs.upstackdata.com/guides/applovin-ads/how-to-find-applovin-pixel-id Find your AppLovin Axon Pixel ID (Event Key) in the AppLovin Dashboard — required to configure the Upstack Data AppLovin destination for server-side conversion forwarding. <Tip> * Sign in to the [AppLovin Dashboard](https://dash.applovin.com/). * Navigate to **Account → General → Keys**. * Locate your **Event Key** (this is your Pixel ID). * Copy the Event Key and paste it into your Upstack AppLovin destination configuration. </Tip> <Note> **What is an AppLovin Pixel ID?** Your **AppLovin Pixel ID** (also called the **Event Key**) is a unique identifier that Upstack Data uses to send conversion data to your AppLovin Axon account. This key is required both for browser-side pixel tracking and server-side Conversions API events. </Note> ## Prerequisites Before you start, you need: * Access to an **AppLovin** account at [dash.applovin.com](https://dash.applovin.com/) * An Axon pixel already set up (or follow the steps below to create one) ## Steps to find your AppLovin Pixel ID <Steps> <Step title="Sign in to the AppLovin Dashboard"> Sign in to the AppLovin Dashboard at [dash.applovin.com](https://dash.applovin.com/). </Step> <Step title="Navigate to Account Settings"> Click on your account menu (typically in the top-right corner) and select **Account** or navigate directly to account settings. </Step> <Step title="Open the Keys section"> In the Account settings, navigate to **General → Keys**. This section contains all your API keys including the Event Key (Pixel ID) and Conversions API Key. </Step> <Step title="Locate your Event Key (Pixel ID)"> Find the **Event Key** in the Keys section. **Example format:** A string of alphanumeric characters (e.g., `abc123def456ghi789`) This Event Key is your Pixel ID that you'll use in Upstack Data. </Step> <Step title="Copy and paste into Upstack Data"> Copy your Event Key and paste it into the **Pixel ID** field in your Upstack AppLovin destination setup. <Tip> Ensure there are no extra spaces before or after the ID. Copy the exact value shown in the dashboard. </Tip> </Step> <Step title="Save the configuration"> Click **Create Configuration** to save the destination. </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, navigate to **Event Destinations**. Your AppLovin destination should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**, double-check that the Pixel ID matches exactly what you see in the AppLovin Dashboard (correct format, no whitespace). </Step> </Steps> <Note> **Next step:** [How to generate your AppLovin CAPI token](/guides/applovin-ads/how-to-generate-applovin-conversion-api-token) </Note> # How to Generate your AppLovin Conversions API Token Source: https://docs.upstackdata.com/guides/applovin-ads/how-to-generate-applovin-conversion-api-token Generate an AppLovin Conversions API access token in the AppLovin Dashboard — required to authenticate the Upstack Data AppLovin destination and forward server-side conversions via the Axon Conversions API. <Tip> * Sign in to the [AppLovin Dashboard](https://dash.applovin.com/). * Navigate to **Account → General → Keys**. * Find or generate a **Conversions API Key**. * Copy the token immediately and paste it into your Upstack AppLovin destination. </Tip> <Note> **What is an AppLovin Conversions API token?** A **Conversions API access token** (also called the **Conversions API Key**) is a secure key that allows Upstack Data to send conversion event data to AppLovin's Axon Conversions API. This key authenticates server-side event requests. </Note> ## Prerequisites Before you start, you need: * **Admin access** to an **AppLovin** account * A configured Axon pixel in the [AppLovin Dashboard](https://dash.applovin.com/) — see [How to find your AppLovin Pixel ID](/guides/applovin-ads/how-to-find-applovin-pixel-id) * An Upstack Data account ready to receive the token ([sign in](https://app.upstackdata.com)) ## Steps to generate your AppLovin CAPI token <Steps> <Step title="Sign in to the AppLovin Dashboard"> Sign in to the AppLovin Dashboard at [dash.applovin.com](https://dash.applovin.com/). </Step> <Step title="Navigate to Account Settings"> Click on your account menu (typically in the top-right corner) and select **Account** or navigate directly to account settings. </Step> <Step title="Open the Keys section"> In the Account settings, navigate to **General → Keys**. This section contains all your API keys including the Event Key (Pixel ID) and Conversions API Key. </Step> <Step title="Find or generate the Conversions API Key"> Look for the **Conversions API Key** in the Keys section. **If you already have one**, you can use the existing key. **If you need to generate a new one:** * Click the option to generate a new Conversions API Key * Follow any prompts to complete the generation </Step> <Step title="Copy your CAPI token"> Copy the Conversions API Key — a string of letters and numbers. <Warning> Copy the token to a secure location. Treat it like a password and never expose it in client-side code or share it publicly. </Warning> </Step> <Step title="Add the token to Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com/pixel/event-destinations) and open your **AppLovin** destination under **Event Destinations**. Paste the token into the **Conversions API access token** field. <Warning> The Conversions API token is sensitive — store it securely. Never expose it in client-side code or share it publicly. </Warning> </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, the AppLovin destination card should show **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**: * Confirm the token was pasted in full (no truncation, no whitespace). * Confirm the token was generated for the same AppLovin account as the Pixel ID. * Confirm the **Pixel ID** matches the Event Key from the same account. </Step> </Steps> <Note> **Need help with the Pixel ID?** See [How to find your AppLovin Pixel ID](/guides/applovin-ads/how-to-find-applovin-pixel-id). </Note> # Destination event mappings in Upstack Source: https://docs.upstackdata.com/guides/custom-events/destination-event-mappings Fine-tune event mappings for a single destination — turn an inherited global mapping off, override it, or add a trigger that only one destination receives. [Global event mappings](/guides/custom-events/global-event-mappings) apply to every destination. When you need one destination to behave differently — skip a mapping, change its rules, or get an event no other destination receives — you do that on the destination itself. ## Prerequisites * A [destination connected](/get-started/connect-a-destination) and saved * Familiarity with [global event mappings](/guides/custom-events/global-event-mappings) (the inherited ones you'll fine-tune here) ## Open the Event Mappings tab Open the destination from **Event Destinations**, then select the **Event Mappings** tab. <Note> The Event Mappings tab appears only after a destination is saved, and it isn't available for **Google Ads** (Google Ads uses Conversion Actions instead). </Note> The tab has two sections: * **Inherited Mappings** — the global mappings this destination receives. * **Custom Triggers** — mappings that belong to this destination only. ## Adjust an inherited mapping Open the **Inherited Mappings** section to see every global mapping this destination inherits. For any one of them you can: * **Turn it off for this destination** — use the switch next to the mapping. The mapping keeps working everywhere else; this destination just stops receiving it. * **Override it** — click **Override** to make a copy you can edit just for this destination. The destination then follows your copy instead of the global version. <Info> Turning a mapping off here only affects this one destination. The global mapping still fires and still reaches your other destinations and your reporting. </Info> ## Add a destination-only custom trigger Open the **Custom Triggers** section and click **Add Custom Trigger** to create a mapping that only this destination receives. It uses the same editor as global mappings — set a **Display name**, **Base event**, **Destination event name**, optional **conditions**, and an optional **value override** — then click **Save custom event**. Each custom trigger in the list can be switched on or off, edited, or removed at any time. ## Save your changes Changes on the Event Mappings tab are staged until you save. Click **Update Configuration** to apply them to the destination. ## Which mapping wins When a destination has its own version of a mapping, that version takes over for that destination: * A **destination override** beats the inherited global mapping — for that one destination. * Everywhere else, the global mapping still applies as usual. ## Related <CardGroup> <Card title="Global event mappings" icon="globe" href="/guides/custom-events/global-event-mappings"> Create a mapping once and send it to every destination. </Card> <Card title="Custom events overview" icon="bolt" href="/guides/custom-events/how-to-create-custom-event-triggers"> What custom events are and when to use them. </Card> <Card title="Connect a destination" icon="plug" href="/get-started/connect-a-destination"> Add Meta, Google, TikTok, Klaviyo, and more. </Card> <Card title="NC & RC Purchase in Meta" icon="meta" href="/guides/facebook-ads/set-up-nc-and-rc-purchase-events-in-meta"> Set up new- and returning-customer purchase events in Meta. </Card> </CardGroup> # Global event mappings in Upstack Source: https://docs.upstackdata.com/guides/custom-events/global-event-mappings Rename or derive an event once and send it to all your connected destinations. Set conditions, add a worked example, and see how global mappings show up in your reporting. Global event mappings let you take an event that's already flowing through Upstack — like a purchase — and send it to your destinations under a new name when it meets conditions you choose. You set it up **once**, and every connected destination inherits it. It's the fastest way to create events like `high_value_purchase` or `subscription_purchase` without touching each destination one by one. ## Prerequisites * An [Upstack Data](https://app.upstackdata.com) account with the pixel installed and events flowing * At least one [destination connected](/get-started/connect-a-destination) * A clear idea of the event you want to create and when it should fire ## What a global event mapping does A mapping watches for a base event (standard or custom), and when its conditions match, it sends that event to your destinations under a new name. For example, a purchase over \$500 can be sent as `high_value_purchase`, so your ad platforms can optimize for high-value buyers specifically. A few things to know up front: * **It applies everywhere.** Every connected destination inherits your global mappings automatically. You can fine-tune or turn one off for a single destination later — see [Destination event mappings](/guides/custom-events/destination-event-mappings). * **It shows up in your reporting.** A global mapping fires as a real event, so it appears in your Upstack analytics and event debugger as well as at your destinations. * **Your standard events keep flowing.** A mapping adds a renamed event — it doesn't replace or stop the original. <Note> Google Ads is the one exception — it doesn't use event mappings. Google Ads relies on its own Conversion Action setup instead. </Note> ## Create a global event mapping <Steps> <Step title="Open Event Mappings"> Go to **Event Destinations** and click the **Event Mappings** button (globe icon) in the page header. The right-side **Global Event Mappings** panel opens, listing any mappings you already have. </Step> <Step title="Add a mapping"> Click **Add Mapping** to open the trigger editor. </Step> <Step title="Name it and pick the base event"> Give the mapping a clear **Display name** (just for you — it isn't sent to destinations). Then choose the **Base event** — pick a standard event like `purchase` from the list, or type your own custom event name. </Step> <Step title="Set the conditions (optional)"> Under **Only when…**, add the conditions that decide when the event fires. Set **Match** to **ALL** or **ANY** of your condition groups, then add conditions inside each group (for example, order value **is greater than** 500). Use **ANY** when any one rule should be enough; use **ALL** when every rule must be true. Leave it empty to fire on every base event. </Step> <Step title="Set the destination event name"> Enter the **Destination event name** — the name your destinations receive. Use lowercase with underscores, e.g. `high_value_purchase`. </Step> <Step title="Choose the value to send (optional)"> Turn on **Override event value** to send profit, margin, a fixed amount, or a custom formula instead of the event's own value — see [Set the value sent with the event](#set-the-value-sent-with-the-event) below. </Step> <Step title="Save"> Click **Save custom event**. The mapping is now live for every connected destination (except Google Ads). </Step> </Steps> ## Worked example: high-value purchases Say you want to optimize for orders over \$500. 1. **Display name:** High value purchase 2. **Base event:** `purchase` 3. **Conditions:** Match **ALL** → order value **is greater than** `500` 4. **Destination event name:** `high_value_purchase` Now whenever a purchase over \$500 comes through, your destinations also receive a `high_value_purchase` event — and it shows up in your Upstack reporting so you can confirm it's firing. <Tip> If you send a revenue event to Meta, pair it with a matching Custom Conversion in Meta Events Manager so you can select it as a campaign optimization goal. See [Approve Meta custom events](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events). </Tip> ## Conditions Conditions (the **Only when…** section) are the filters that decide when a mapping fires. Leave them empty and the mapping fires on **every** base event; add conditions and it fires **only** when they match. Each condition is a **field**, an **operator**, and a **value** — for example *order value* **is greater than** `500`. You can filter on any field the event carries: order and cart values, customer traits, page and campaign context, device, and more. **Operators** include comparisons (*is greater than*, *is at least*, *equals*), text matches (*contains*, *starts with*), list checks (*is in*, *includes any*), and existence checks (*exists*, *does not exist*). The available operators change to fit the field you pick. **Groups.** Conditions live in groups. Set **Match** to **ALL** (every condition in the group must be true) or **ANY** (one is enough). Add multiple groups for more complex logic — for example *(order value > 500)* **OR** *(customer is returning AND category is apparel)*. <Tip> Start simple. A single condition like *order value is greater than 500* covers most high‑value‑purchase mappings. Add more groups only when one rule isn't enough. </Tip> ## Set the value sent with the event By default, Upstack forwards the event's own value. Turn on **Override event value** to send profit, margin, a fixed amount, or a custom formula instead — so your ad platforms optimize on the value that matters to you. See **[Custom event value & formulas](/guides/custom-events/value-and-formulas)** for every value option, the formula builder (Simple vs Advanced), and the full operand reference. ## Frequently asked questions <AccordionGroup> <Accordion title="Do global mappings change my standard events?"> No. A mapping adds a renamed event when its conditions match — your standard events keep flowing exactly as before. </Accordion> <Accordion title="Will the mapped event appear in my reporting?"> Yes. Global mappings fire as real events, so they show up in your Upstack analytics and event debugger in addition to being sent to your destinations. </Accordion> <Accordion title="Does every destination get the mapping?"> Every connected destination inherits it automatically — except Google Ads, which uses Conversion Actions instead. You can disable or override a global mapping for a single destination from that destination's Event Mappings tab. </Accordion> <Accordion title="What if two mappings could apply to the same event?"> Each mapping is evaluated independently — every mapping whose conditions match fires. There's no priority ordering between global mappings, so if you don't want overlap, make each mapping's conditions specific enough that only one matches. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Destination event mappings" icon="sliders" href="/guides/custom-events/destination-event-mappings"> Disable or override a global mapping for a single destination, or add destination-only triggers. </Card> <Card title="Custom events overview" icon="bolt" href="/guides/custom-events/how-to-create-custom-event-triggers"> What custom events are and when to use them. </Card> <Card title="NC & RC Purchase in Meta" icon="meta" href="/guides/facebook-ads/set-up-nc-and-rc-purchase-events-in-meta"> Set up new- and returning-customer purchase events in Meta. </Card> <Card title="Approve Meta custom events" icon="check" href="/guides/facebook-ads/how-to-approve-facebook-meta-custom-events"> Approve and verify custom events in Meta Events Manager. </Card> </CardGroup> # How to create custom event triggers in Upstack Source: https://docs.upstackdata.com/guides/custom-events/how-to-create-custom-event-triggers Track specific actions beyond standard events — quiz completions, subscriptions, category-specific purchases, high-value orders. Send enriched custom events to Facebook, Google, TikTok, and more. Custom event triggers let you go beyond standard ecommerce events — page views, add-to-carts, purchases — to track the specific actions that matter most to your business. This guide explains what custom event triggers are, when to use them, and how they flow through Upstack's server-side pipeline to your ad platforms. ## Prerequisites * An [Upstack Data](https://app.upstackdata.com) account with the Upstack pixel installed and standard events flowing * At least one destination connected (see [Connect a destination](/get-started/connect-a-destination)) — Meta, Google Ads, TikTok, Klaviyo, etc. * A clear definition of the trigger condition you want to track (e.g., new customer purchase, quiz completion, high-value order) * Admin access to the destination platform's event manager (e.g., [Meta Events Manager](https://business.facebook.com/events_manager)) so you can approve custom events and create matching Custom Conversions ## What are custom event triggers? Standard ecommerce tracking covers the basics: someone views a product, adds it to their cart, begins checkout, and completes a purchase. But your business likely has actions that fall outside that flow — quiz completions, email sign-ups, subscription enrollments, or purchases from a specific product category. Custom event triggers let you define those actions as trackable events in Upstack. Once configured, they flow through the same server-side pipeline as your standard events: enriched with identity data, matched to user profiles, and forwarded to your connected destinations (Meta, Google Ads, TikTok, and others). This means you can tell Meta "this person completed a quiz" or "this was a first-time customer purchase" with the same data quality and identity enrichment your standard purchase events receive. <Info> Custom events complement standard tracking — they don't replace it. Keep sending the standard `Purchase` event alongside any custom variant like `nc_purchase`. Ad platforms rely on the standard event for baseline optimization and reporting. </Info> ## Why custom event triggers matter Custom events unlock capabilities that standard tracking cannot: * **New customer acquisition optimization.** Send a dedicated event when a first-time customer purchases, so Meta or Google can optimize for acquiring net-new buyers — not just driving repeat orders. * **Category-level optimization.** If you sell across multiple product categories (e.g., skincare and supplements), purchase events scoped per category let ad platforms optimize for the right products. * **Funnel-stage tracking.** Track mid-funnel actions like quiz completions or email captures as conversion events, giving ad platforms more signal about user intent earlier in the journey. * **High-value action identification.** Define events for actions that predict high lifetime value — subscribing, purchasing a bundle, or hitting a spend threshold. ## Common use cases <AccordionGroup> <Accordion title="New customer purchase (nc_purchase)"> Fires only when an order comes from a customer with no prior Shopify order history. The most popular custom event — it lets Meta and Google optimize for net-new customer acquisition rather than total purchases. See [Setting up new customer purchase metrics in Meta Ads Manager](/guides/facebook-ads/complete-how-to-guide-for-setting-up-new-customer-purchase-metrics-in-facebook-meta-ads-manager). </Accordion> <Accordion title="Returning customer purchase (rc_purchase)"> The complement to `nc_purchase` — fires when a customer with existing order history makes a purchase. Useful for building retargeting audiences or measuring retention campaign performance. </Accordion> <Accordion title="Category-specific purchases"> Fires when a purchase includes products from a specific collection or product type. A brand selling apparel and accessories might create `apparel_purchase` and `accessories_purchase` events to let Meta optimize separately for each category. </Accordion> <Accordion title="Quiz or form completion"> Fires when a customer completes an on-site quiz, survey, or lead capture form. Gives ad platforms a mid-funnel signal that helps them find users more likely to engage deeply with your brand. </Accordion> <Accordion title="Subscription enrollment"> Fires when a customer signs up for a subscription product. Especially valuable for brands where subscription customers have significantly higher lifetime value. </Accordion> <Accordion title="High-value purchase"> Fires when an order exceeds a specified dollar threshold (e.g., orders over \$150). Lets ad platforms optimize for higher-AOV customers. </Accordion> </AccordionGroup> ## How custom events flow through Upstack Custom events follow the same path as standard events: <Steps> <Step title="Trigger condition is met"> The action you defined occurs — a new customer makes a purchase, a quiz is completed, a high-value order is placed. </Step> <Step title="Upstack captures and enriches the event"> The event runs through Upstack's server-side pipeline, where identity resolution attaches available user data — email, phone, IP, browser fingerprint, click IDs. </Step> <Step title="Event is sent to destinations"> The enriched event is delivered to your connected destinations via their server-side APIs — Meta CAPI, Google Ads offline conversions, TikTok Events API, and others. </Step> <Step title="Ad platforms match the event"> The destination uses the identity parameters to match the event to a user profile. The richer the identity data, the higher the match quality. </Step> </Steps> Because custom events go through the same enrichment pipeline, they benefit from the same identity resolution and data quality as your standard events. ## Set them up yourself You can create and manage custom event triggers directly in Upstack — no onboarding ticket required. There are two places to do it, depending on how widely you want the event to apply: <CardGroup> <Card title="Global event mappings" icon="globe" href="/guides/custom-events/global-event-mappings"> Create a trigger once and send it to every connected destination. Best for events you want everywhere, like `high_value_purchase`. </Card> <Card title="Destination event mappings" icon="sliders" href="/guides/custom-events/destination-event-mappings"> Turn an inherited trigger off, override it, or add a trigger that only one destination receives. </Card> </CardGroup> In both places you set a display name, the base event, the destination event name, the conditions that decide when it fires, and — optionally — the [value sent with the event](/guides/custom-events/global-event-mappings#set-the-value-sent-with-the-event) (profit, margin, a fixed amount, or a custom formula). The two guides above walk through every field with examples. <Note> After your event is firing, create a matching Custom Conversion in your ad platform (for Meta, see [Approve Meta custom events](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events)) so you can select it as a campaign optimization goal. </Note> ## Best practices ### Naming conventions * Use lowercase with underscores: `nc_purchase`, `quiz_complete`, `high_value_order`. * Keep names short but descriptive — ad platform UIs have limited space for event names. * Be consistent. If you use `nc_purchase` for new customer purchase, use `rc_purchase` for returning — not `returning_customer_buy`. ### Start with high-impact events Don't create a dozen custom events on day one. Start with the one or two that will most directly improve your ad optimization: * If your primary goal is new customer acquisition, start with `nc_purchase`. * If you sell across distinct categories, start with category-specific purchase events. * If you have a quiz-driven funnel, add quiz completion early. ### Validate before scaling After creating a custom event, verify it's firing correctly and being received by your destination platforms before building ad campaigns around it: * In the [Upstack dashboard](https://app.upstackdata.com) under **Event Health**, confirm the custom event appears with the expected name and parameters. * In your destination's event manager ([Meta Events Manager](https://business.facebook.com/events_manager), Google Ads conversions, TikTok Events Manager, etc.), confirm the event is arriving with the expected parameters. * Trigger the event in a controlled test (e.g., place a test order matching your condition) and confirm it shows up end-to-end before scaling spend. ### Avoid duplicating standard events Custom events should complement standard tracking. Keep sending the standard `Purchase` event alongside any custom purchase events like `nc_purchase`. Ad platforms rely on the standard event for baseline optimization and reporting. ### Include value parameters Whenever a custom event is tied to revenue (like a purchase event), include the value and currency parameters. This lets ad platforms calculate ROAS for campaigns optimized toward that event. <Tip> **Pair every revenue-bearing custom event with a Custom Conversion in Meta.** The custom event populates Meta's pipeline; the Custom Conversion is what you actually select as a campaign optimization goal. See [How to approve Meta custom events](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events). </Tip> ## Frequently asked questions <AccordionGroup> <Accordion title="Do custom events get the same identity enrichment as standard events?"> Yes. Custom events flow through the same Upstack pipeline as standard events, receiving the same identity resolution, data enrichment, and server-side delivery. </Accordion> <Accordion title="How many custom events can I create?"> There is no hard limit in Upstack, but ad platforms have their own. Meta, for example, allows up to 100 custom conversions per ad account. Focus on the events that meaningfully improve your optimization. </Accordion> <Accordion title="Will custom events affect my Event Match Quality (EMQ)?"> Custom events are scored separately from standard events in Meta's system. They benefit from the same identity parameters Upstack attaches, so they should have similar match quality to your standard events. </Accordion> <Accordion title="Can I send the same custom event to multiple destinations?"> Yes. When you configure a custom event, you can map it to any of your connected destinations. The same event can be sent to Meta, Google Ads, TikTok, and others simultaneously. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Global event mappings" icon="globe" href="/guides/custom-events/global-event-mappings"> Create a trigger once and send it to every connected destination. </Card> <Card title="Destination event mappings" icon="sliders" href="/guides/custom-events/destination-event-mappings"> Disable, override, or add triggers for a single destination. </Card> <Card title="NC & RC Purchase in Meta" icon="meta" href="/guides/facebook-ads/set-up-nc-and-rc-purchase-events-in-meta"> Set up new- and returning-customer purchase events in Meta. </Card> <Card title="Custom events data dictionary" icon="book" href="/pixel/events/custom-events"> Reference for custom event names, parameters, and payloads. </Card> <Card title="Approve Meta custom events" icon="check" href="/guides/facebook-ads/how-to-approve-facebook-meta-custom-events"> Approve and verify custom events in Meta Events Manager. </Card> </CardGroup> # Custom event value & formulas in Upstack Source: https://docs.upstackdata.com/guides/custom-events/value-and-formulas Override the value sent with a custom event — send profit, margin, a fixed amount, or a custom formula so ad platforms optimize on the value that matters to you. By default, Upstack forwards the event's own value to your destinations. You can **override** it so your ad platforms optimize on the value that matters to you — profit instead of revenue, a fixed lead value, or a number you compute yourself. This is the foundation of value‑based bidding. You set this while creating or editing a mapping (see [Global event mappings](/guides/custom-events/global-event-mappings) and [Destination event mappings](/guides/custom-events/destination-event-mappings)). Turn on **Override event value**, then choose under **Set value to**. ## Value options | Option | What it sends | Requirements | | --------------------------- | ----------------------------------------------------------- | ------------------------------------ | | **Event value** | The value already on the event (the default — no override). | — | | **Net Revenue** | Revenue after discounts and refunds. | Shopify order data · purchase events | | **CM1 (Gross Margin)** | Net revenue minus product cost (COGS). | Shopify order data · purchase events | | **CM2 (After Fulfillment)** | CM1 minus shipping, handling, and fees. | Shopify order data · purchase events | | **Fixed value** | A set amount you choose (e.g. a flat lead value). | — | | **Custom formula** | A value you build yourself. | See below | The revenue and profit presets are computed per order from your [cost settings](/get-started/cost-settings). They require Shopify order data and apply to purchase events. Value‑bearing events like `add_to_cart` can use **Net Revenue** (revenue only — no cost). <Note> Cost- and revenue-based options need Shopify order data. On non‑Shopify accounts you can still use **Fixed value** or a **Custom formula** over your own `data.*` fields. </Note> ## Custom formula The formula builder has two modes: * **Simple builder** — start with a value, then adjust it step by step (e.g. **Event value × 0.7**). Each part is a **Metric** (a known measure), a **Field** (a custom event field, entered as `data.fieldName`), or a **Number**. Steps apply left to right, like a calculator. * **Advanced** — write the raw formula directly, with autocomplete for variables. Use `+ − * /` and parentheses. ### Operands you can reference | Operand | Meaning | Available on | | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------------- | | `data.value` | The value already on the event. | Every event | | `data.<field>` | Any custom field on the event (e.g. `data.leadValue`). | Every event | | `orders.gross_revenue` | Gross revenue before discounts and refunds. | Shopify purchase | | `orders.net_revenue` | Revenue after discounts and refunds. | Shopify purchase | | `orders.subtotal`, `orders.tax`, `orders.discount_amount`, `orders.refund_amount`, `orders.units` | Order revenue components. | Shopify purchase | | `orders.cogs`, `orders.other_cogs` | Cost of goods sold. | Shopify purchase | | `orders.shipping_cost`, `orders.handling_cost`, `orders.other_fulfillment_cost` | Fulfillment costs. | Shopify purchase | | `orders.gateway_cost`, `orders.other_transaction_cost` | Transaction/gateway fees. | Shopify purchase | Cost operands (`orders.cogs`, `orders.shipping_cost`, …) are only available on purchase events, where full order cost data exists. ### Examples | Goal | Formula | | ---------------------------------------- | ---------------------------------- | | Send 70% of the event value | `data.value * 0.7` | | Send profit (revenue minus product cost) | `orders.net_revenue - orders.cogs` | | Subtract a flat fee from the value | `data.value - 15` | | Scale a custom lead value | `data.leadValue * 0.4` | <Note> **A missing field skips the formula — it doesn't zero your value.** If an event doesn't carry a field your formula references (say `data.leadValue` on an event that didn't send it), Upstack skips the override and forwards the event's own value instead, so a missing field never overwrites a real value with `0`. A field that *is* present but genuinely `0` is used as `0`. Still, reference only fields your events reliably send, so the formula applies when you expect it to. </Note> ## Related <CardGroup> <Card title="Global event mappings" icon="globe" href="/guides/custom-events/global-event-mappings"> Create a mapping once and send it to every destination. </Card> <Card title="Cost settings" icon="calculator" href="/get-started/cost-settings"> Configure the costs behind Net Revenue, CM1, and CM2. </Card> <Card title="Custom events overview" icon="bolt" href="/guides/custom-events/how-to-create-custom-event-triggers"> What custom events are and when to use them. </Card> <Card title="Approve Meta custom events" icon="check" href="/guides/facebook-ads/how-to-approve-facebook-meta-custom-events"> Approve and verify custom events in Meta Events Manager. </Card> </CardGroup> # Complete How-To Guide for Onboarding Facebook (Meta) in Upstack Data Source: https://docs.upstackdata.com/guides/facebook-ads/complete-how-to-guide-for-onboarding-facebook-meta-in-upstack-data Onboard Facebook (Meta) Ads in Upstack Data — connect your Pixel and Conversions API, disable duplicate tracking, configure NC-ROAS, and verify events flow through to Meta Events Manager. <Info> **New to Upstack?** Follow the [getting started guide](/get-started/install-on-shopify) for a streamlined onboarding walkthrough. </Info> <Tip> * Configure the **Meta destination** in Upstack Data with your **Pixel ID** and **CAPI token**. * Disable **Facebook & Instagram data sharing** in Shopify to prevent duplicate events. * Set up the **NC Purchase** custom conversion and share it with your ad accounts. * Add **NC-ROAS** and other new-customer columns to Meta Ads Manager. * Monitor **Event Match Quality** improvements over 7–10 days. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to a **Meta Business Manager** account * A configured **Meta Pixel** in [Meta Events Manager](https://business.facebook.com/events_manager) * A **CAPI token** generated from that pixel — see [How to generate your CAPI token](/guides/facebook-ads/how-to-generate-my-facebook-conversion-api-key) * Shopify owner/staff access (for the duplicate-events cleanup step) <Steps> <Step title="Configure the Meta destination in Upstack Data"> In the Upstack dashboard, navigate to **Event Destinations** and add a **Facebook Advertising** destination using your **Pixel ID** (15–16 digit number, no prefix) and **CAPI token** (starts with `EAA`). Help guide: [How to configure the Meta Pixel destination in Upstack Data →](/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data) </Step> <Step title="Disable Facebook & Instagram data sharing in Shopify"> <Warning> You must disable all other Meta pixel integrations to prevent duplicate events. Multiple active pixels inflate conversion metrics and harm campaign optimization. </Warning> Help guide: [How to disable Facebook and Instagram data sharing in Shopify →](/guides/facebook-ads/how-to-disable-facebook-and-instagram-data-sharing-in-shopify) **Additional pixels to check and disable:** * Native Shopify Facebook & Instagram sales channel pixel * Third-party Facebook pixel apps in Shopify * Manual pixel code in your theme files (`theme.liquid`, header snippets) * Facebook pixel tags inside Google Tag Manager </Step> <Step title="Set up new-customer purchase metrics in Meta Ads Manager"> **Key metrics you'll configure:** * **NC-ROAS** (New Customer Return on Ad Spend) — revenue from new customers only * **NC-CPA** (New Customer Cost Per Acquisition) — cost to acquire each new customer Help guide: [How to set up new-customer purchase metrics in Meta Ads Manager →](/guides/facebook-ads/complete-how-to-guide-for-setting-up-new-customer-purchase-metrics-in-facebook-meta-ads-manager) </Step> <Step title="Verify the full setup is healthy"> Confirm each piece of the setup is working: * In the Upstack dashboard, **Event Destinations** shows your Meta destination as **Healthy** (green). * In [Meta Events Manager](https://business.facebook.com/events_manager), the pixel shows recent events with the **Server** connection label. * In Meta Ads Manager, the **NC Purchase** custom conversion is visible and the **NC-ROAS** custom metric appears in your column layout. If anything is unhealthy, check the corresponding help guide above for troubleshooting steps. </Step> </Steps> ## What to expect after setup ### Event Match Quality timeline * **Event Match Quality (EMQ)** scores start to improve in 2–3 days and normalize over 7–10 days. * You can typically expect a 1–2 point increase on lower-funnel events (PageView, ViewContent, AddToCart). * The **Purchase** EMQ score will remain largely unchanged — at checkout, all match parameters (email, name, address) are already being sent to Meta. ### Normal warnings and notifications **Red triangle ⚠️ warnings in Meta Events Manager** You may see new warnings appear next to your events in Meta Events Manager during the first few days. These are **normal** and **require no action**. They appear because: * Meta detects the change in data source from the Shopify sales channel to Upstack Data * Meta recognizes a different set of parameter configurations * Meta's algorithm is adjusting to the new data format <img alt="Meta Events Manager showing warning triangles during initial data adjustment" /> <Note> **What to do:** Monitor your events to confirm they're firing correctly, but avoid making changes based solely on these warnings. </Note> <Note> **Need help?** If you encounter any issues during setup or don't see expected improvements after 10 days, contact our support team with your **Meta Pixel ID** and we'll help diagnose the problem. </Note> # Complete How-To Guide for Setting up New Customer Purchase Metrics in Facebook (Meta) Ads Manager Source: https://docs.upstackdata.com/guides/facebook-ads/complete-how-to-guide-for-setting-up-new-customer-purchase-metrics-in-facebook-meta-ads-manager Set up the New Customer Purchase conversion in Facebook (Meta) Ads Manager to optimize campaigns for first-time buyers and report NC-ROAS alongside total ROAS. <Tip> * Verify the **ncPurchase** event in [Meta Events Manager](https://business.facebook.com/events_manager). * Create the **NC Purchase** custom conversion and optimize it for **Purchase**. * Share the custom conversion with every Meta ad account that needs it. * In [Meta Ads Manager](https://adsmanager.facebook.com), customize columns to add NC Purchase metrics. * Create the **NC-ROAS** custom metric: `NC Purchase Conversion Value ÷ Amount spent`. </Tip> ## Prerequisites Before you start, you need: * The **Meta destination** configured in Upstack Data — see [How to configure the Meta Pixel destination](/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data) * At least one real new-customer purchase already processed so the **ncPurchase** event appears in Meta Events Manager * Admin access to the **Meta Business Manager** that owns the pixel and to every ad account you'll share the conversion with ## What you'll achieve After completing all three parts below, **Meta Ads Manager** will display new-customer metrics — **NC-ROAS** (New Customer Return on Ad Spend), **Cost per NC Purchase**, and **Total NC Purchases** — directly in your campaigns, ad sets, and ads tables. ## Setup process overview Set up new-customer purchase tracking in three parts. Complete them in order — later steps depend on earlier ones. ### Part 1 — Verify the ncPurchase event Before you can create any custom conversions, the **ncPurchase** event must be verified in Meta Events Manager. Guide to complete this step: [How to verify the NC Purchase event in Meta Events Manager →](/guides/facebook-ads/how-to-verify-the-nc-purchase-event-in-facebook-meta-events-manager) ### Part 2 — Create and share the custom conversion Once **ncPurchase** is verified, create the **NC Purchase** custom conversion and share it with your ad accounts. Guide to complete this step: [How to create and share the NC Purchase custom conversion →](/guides/facebook-ads/how-to-create-and-share-nc-purchase-custom-conversion-in-facebook-meta) ### Part 3 — Add metrics to Meta Ads Manager Configure your Ads Manager columns to display the NC Purchase metrics and create the **NC-ROAS** custom metric. Guide to complete this step: [How to add NC Purchase metrics and NC-ROAS to Meta Ads Manager →](/guides/facebook-ads/how-to-add-nc-purchase-metrics-and-nc-roas-to-facebook-meta-ads-manager) ## Verify the setup is complete Once you've finished all three parts, confirm: * In [Meta Events Manager](https://business.facebook.com/events_manager), the **ncPurchase** event has no red triangle warning and is listed as **Active**. * In **Custom Conversions**, **NC Purchase** is shared with the ad accounts you selected. * In your Meta Ads Manager column layout, **NC Purchase (Total)**, **NC Purchase (Cost)**, and **NC-ROAS** are all visible. <Note> **Done 🎉** Initially, the new columns may show **0** or **—** because Meta does **not** retroactively attribute custom conversions from before they were created. Data starts populating for new-customer purchases that occur **after** the conversion was created and shared. Allow 24–48 hours of new traffic before judging the values. </Note> # Health and Wellness Custom Event Mappings Source: https://docs.upstackdata.com/guides/facebook-ads/health-and-wellness-custom-event-mappings Map Upstack Data events to Meta Custom Events for Health and Wellness brands so server-side conversions reach Meta CAPI without violating Meta's restricted-category rules. ## Prerequisites Before you start, you need: * A configured **Health & Wellness container** in Upstack Data (created and activated by support) * Admin access to a **Meta Business Manager** account * Your store domain **verified and approved** in [Meta Events Manager](https://business.facebook.com/events_manager) → **Domains** * Access to email so you can request aliasing activation from Upstack support ## Configuration steps ### Part 1 — Set up domain aliasing and configure the Health & Wellness container 1. **Set up and activate your Health & Wellness container.** Confirm the container has been fully created and activated by Upstack support before continuing. 2. **Verify and approve your store domain in Meta Events Manager.** * In [Meta Events Manager](https://business.facebook.com/events_manager), navigate to **Domains** in the left-hand menu. * Add your store domain and complete Meta's domain verification process (DNS or meta-tag). * Domain approval is **required** before aliasing can be applied. 3. **Apply domain aliasing (Health & Wellness scrubbing).** Once your domain has been verified, Upstack implements aliasing so events from your store are properly tracked under the Health & Wellness container. 4. **Enable custom event optimization.** After aliasing is active, you can optimize ad campaigns for the custom purchase event **`UPSTACK_HW_6117d13b`** (the Health & Wellness alias for the Purchase event). See the full mapping in Part 2 below. 5. **Request domain aliasing activation for standard funnel events.** After completing domain verification, email [support@upstackdata.com](mailto:support@upstackdata.com) and ask us to enable domain aliasing for your standard funnel events. ### Part 2 — Health & Wellness custom event mappings Below are the Health & Wellness pixel mappings. Standard event names are remapped to opaque `UPSTACK_HW_*` custom event names so Meta does not associate them with restricted Health & Wellness categories. ```text theme={null} Health & Wellness Pixel Mappings ================================ PageView -> PageView ViewContent -> ViewContent ViewCategory -> view_category AddToCart -> UPSTACK_HW_de792bda InitiateCheckout -> UPSTACK_HW_d823e4ff Purchase -> UPSTACK_HW_6117d13b Lead -> UPSTACK_HW_289161cb Schedule -> UPSTACK_HW_5a3811fb Complete Registration -> UPSTACK_HW_895b83ff Contact -> UPSTACK_HW_4c62e638 Invite Meeting Scheduled -> UPSTACK_HW_529b7e00 AddPaymentInfo -> UPSTACK_HW_9984f5f9 AddShippingInfo -> UPSTACK_HW_3c4012cc All Purchase -> UPSTACK_HW_f0e986fc NC Purchase -> UPSTACK_HW_fa2b3354 RC Purchase -> UPSTACK_HW_5ec76558 ``` ### Part 3 — Approve the custom events in Meta #### Why event approval is required <Note> Custom events showing ⚠️ red triangle warnings must be approved in Meta Events Manager. Until approved, the events won't be available for ad delivery optimization, audiences, or campaign reporting. The approval flow simply confirms that you acknowledge the custom event is legitimate for your business. </Note> Help guide to complete this step: [How to approve Meta custom events →](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events) ### Verify the setup is working After approval, confirm the Health & Wellness mappings are flowing correctly: * In [Meta Events Manager](https://business.facebook.com/events_manager), open your pixel and confirm the `UPSTACK_HW_*` events appear in the events list with the **Server** connection label. * None of the listed events should show a red triangle warning. * In **Custom Conversions**, you can now create conversions targeting `UPSTACK_HW_6117d13b` for Purchase optimization. # How do I find my Facebook Ads Pixel (Dataset) ID? Source: https://docs.upstackdata.com/guides/facebook-ads/how-do-i-find-my-facebook-ads-pixel-dataset-id Find your Facebook (Meta) Pixel/Dataset ID in Meta Events Manager to configure the Upstack Data Meta Ads destination for server-side tracking. <Tip> * Sign in to [Meta Events Manager](https://business.facebook.com/events_manager) and locate your pixel. * Click the pixel name, then open the **Settings** tab. * Copy the **Pixel ID** — a 15–16 digit number, no prefix (e.g., `123456789012345`). * Paste it into your Upstack Meta destination configuration. </Tip> <Note> **What is a Meta Pixel ID?** Your **Meta Pixel ID** (sometimes shown as "Dataset ID" inside Meta Events Manager) is a 15–16 digit number Upstack Data uses to send conversion data to your Meta ad account. Meta Pixel IDs have **no prefix** — that's how they differ from Google Ads conversion IDs (which start with `AW-`). </Note> ## Prerequisites Before you start, you need: * Access to a **Meta Business Manager** account * A pixel already created in [Meta Events Manager](https://business.facebook.com/events_manager) (or follow the create-pixel steps below) ## Steps to find your Meta Pixel ID <Steps> <Step title="Sign in to Meta Events Manager"> Sign in to Meta Events Manager at [business.facebook.com/events\_manager](https://business.facebook.com/events_manager). </Step> <Step title="Find or create your pixel"> **If you already have a pixel**, you'll see it listed in the left-hand **Data Sources** panel — proceed to the next step. **If you need to create one:** * Click the green **Connect Data Sources** button * Select **Web** * Click **Next** or **Get Started** * Follow the instructions to create a new Meta Pixel <img alt="Meta Events Manager with Connect Data Sources button" /> <img alt="Select Web as data source type in Meta Events Manager" /> </Step> <Step title="Open the pixel overview"> In the **Data Sources** list, click the pixel's name. You'll land on the pixel's **Overview** page. </Step> <Step title="Locate your Pixel ID"> On the pixel **Overview** page, click the **Settings** tab in the left-hand menu. On the **Settings** tab, locate **Dataset ID** at the top of the page. This is your **Pixel ID** — a 15–16 digit number with no prefix. <img alt="Meta Pixel Settings page showing Dataset ID at the top" /> **Example format:** `123456789012345` </Step> <Step title="Copy and paste into Upstack Data"> Copy your Pixel ID and paste it into the **Pixel ID** field in your Upstack Meta destination setup. <img alt="Upstack Meta destination configuration with Pixel ID field" /> <Tip> Ensure there are no extra spaces before or after the ID. The value should be exactly 15 or 16 digits with no `AW-` or other prefix. </Tip> </Step> <Step title="Save the configuration"> Click **Create Configuration** to save the destination. <img alt="Create Configuration button to save Meta destination setup" /> </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, navigate to **Event Destinations**. Your Meta destination should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**, double-check that the Pixel ID matches exactly what you see in Meta Events Manager (no prefix, no whitespace). </Step> </Steps> <Note> **Next step:** [How to generate your CAPI token](/guides/facebook-ads/how-to-generate-my-facebook-conversion-api-key) </Note> # How Domain Aliasing Works for Health & Wellness Tracking Source: https://docs.upstackdata.com/guides/facebook-ads/how-domain-aliasing-works-for-health-wellness-tracking Bypass Meta's Health & Wellness domain flag with Upstack's alias domain — replacing event source URLs so server-side events deliver cleanly without triggering category restrictions. ### The Short Version Meta's Health & Wellness flag lives on your **domain**, not your pixel. Any pixel that receives events from a flagged domain inherits the flag — even a brand-new pixel. Domain aliasing solves this by routing all events through a clean, unflagged domain so Meta never associates your new pixel with the restricted one. ### Why the Flag Is Domain-Level (and Why That Matters) When Meta flags a store under Health & Wellness, the flag is applied to the **root domain** (e.g., `yourstore.com`). This is a critical detail that catches many brands off guard. Here's what it means in practice: **Creating a new pixel doesn't help.** If you create a fresh pixel and start sending events from `yourstore.com`, that new pixel gets flagged too. The flag follows the domain, not the pixel ID. **Subdomains don't help.** Sending events from `shop.yourstore.com` or `checkout.yourstore.com` still traces back to the same root domain. Meta's systems resolve subdomains to their parent. **Changing your Shopify domain doesn't help (usually).** If you switch from a `.myshopify.com` domain to a custom domain, you're still operating on a domain that Meta can flag. And if the custom domain was already flagged, it stays flagged regardless of what platform it's on. **The flag doesn't expire on its own.** There is no known timeline for Meta to automatically remove a Health & Wellness flag. Some brands have reported flags persisting for months or longer, even after removing products. This is why aliasing is essential — it's the only way to present Meta with a domain that has no H\&W history. ### How Domain Aliasing Works Domain aliasing is straightforward in concept: every event sent to Meta reports a different domain as its origin. Instead of Meta seeing events from `yourstore.com`, it sees events from `youraliasdomain.com` — a clean domain with no flag history. ### The Technical Mechanics Every Conversions API event sent to Meta includes a field called `event_source_url`. This tells Meta which web page the event came from. In a normal setup, this would be something like: <Note> **Before aliasing:** `event_source_url`: [https://yourstore.com/products/daily-vitamin-pack](https://yourstore.com/products/daily-vitamin-pack) </Note> With aliasing active, Upstack replaces this field before sending the event: <Note> **After aliasing:** `event_source_url`: [https://youraliasdomain.com/](https://youraliasdomain.com/) </Note> Meta receives the event, checks the `event_source_url`, and associates it with the alias domain — which is clean, compliant, and unflagged. ### What Meta's Bot Sees Meta doesn't just accept the `event_source_url` at face value. Its compliance bot periodically visits the domain to verify what's there. When it visits your alias domain, it finds: * A simple, compliant landing page with a generic headline and an image * No health or wellness product content * No supplement terminology * No links to your flagged store This is exactly what Meta expects to see from a non-H\&W domain. The events pass through without triggering any flags. ### What Doesn't Change Aliasing only affects the `event_source_url` field in the CAPI payload. Everything else remains accurate: * **User identifiers** (hashed email, phone, click ID) still match the real customer * **Event timing** still reflects when the action actually happened * **Conversion values** still reflect real purchase amounts * **Attribution** still connects the conversion to the correct ad click The alias domain is purely a compliance layer. It doesn't affect the accuracy of your tracking or the quality of your attribution data. ### What Makes a Good Alias Domain The alias domain needs to satisfy Meta's compliance checks without raising any red flags. ### It Must Be a Root Domain `youraliasdomain.com` works. `alias.yourstore.com` does not. Meta resolves subdomains to their root, so a subdomain of a flagged domain is still associated with the flag. The alias must be an entirely separate root domain. ### It Must Be New to Meta The domain should have no prior history with Meta's ad system. Don't reuse an old domain, a domain from a previous brand, or a domain that was ever connected to a Meta pixel. Register something fresh. ### It Must Have a Compliant Landing Page When Meta's bot visits, it needs to find a page that looks like a normal, non-health website. A single page with a generic headline and a stock image is sufficient. The page does not need to be functional — no forms, no checkout, no navigation. What to avoid on the page: * Health, wellness, supplement, or medical terminology * Product images of pills, capsules, powders, or health products * Links to your real store * Any content that could be interpreted as health-related ### It Must Stay Live Meta's bot can revisit the alias domain at any time. If the domain expires or the landing page goes down, Meta may flag the events as coming from an invalid source, which could disrupt your tracking. ### How Aliasing Fits into the Full Solution Domain aliasing handles one specific problem: preventing the flagged domain from tainting your new pixel. But it works in tandem with the other three components: **Without server-side-only tracking,** the browser pixel would still fire from your real domain, sending the real `event_source_url` directly to Meta — bypassing the alias entirely. **Without data sanitization,** even though the domain looks clean, the event payload would still contain product names and URLs from your flagged store. Meta's classifiers could flag the content regardless of the source domain. **Without custom event mappings,** standard event names like "Purchase" or "AddToCart" on a store that sells health products could still draw scrutiny from automated systems. All four layers need to be in place. Aliasing is the visible "front door" — it determines what domain Meta associates with your pixel. The other three components ensure that everything behind that front door is also clean. ### Common Questions ### Will Meta eventually flag the alias domain too? As long as the alias domain's landing page stays compliant and the event data sent from it is sanitized (which Upstack handles automatically), there is no reason for Meta to flag it. The alias domain never has health/wellness content, and the events from it never contain flaggable product data. ### Can I use the same alias domain for multiple stores? Generally no. Each store should have its own alias domain to avoid cross-contamination. If Meta were to flag one store's alias domain for any reason, you wouldn't want it to affect your other stores. ### Does the alias domain need SSL/HTTPS? Yes. Meta expects `event_source_url` values to use HTTPS. Most modern hosting providers and domain registrars include free SSL certificates, so this is usually automatic. ### Can I use the alias domain for anything else? It's best to keep the alias domain dedicated solely to this purpose. Don't use it for email marketing, other ad platforms, or any purpose that could generate content Meta might scrutinize. The simpler and cleaner it stays, the better. ### What happens to the alias domain if I stop using Upstack? The alias domain is yours — you registered it. If you stop using Upstack, you can let it expire or repurpose it. However, if you plan to continue running Meta ads for a health/wellness brand, you'll need some form of domain aliasing regardless of what tracking solution you use. ### What You Need to Do You're responsible for registering the alias domain and setting up the landing page. Upstack handles the technical aliasing — replacing the `event_source_url` in every CAPI event. For step-by-step instructions: [How to Set Up an Alias Domain for Health & Wellness Tracking →](/guides/health-wellness/setup-alias-domain-health-wellness) ### Related Articles * [How Upstack Data Solves Health & Wellness Restrictions](/guides/health-wellness/how-upstack-solves-health-wellness-restrictions) * [How to Set Up an Alias Domain for Health & Wellness Tracking](/guides/health-wellness/setup-alias-domain-health-wellness) * [How to Set Up a Health & Wellness Pixel for Meta](/guides/health-wellness/setup-health-wellness-pixel-for-meta) # How to Add NC Purchase Metrics and NC-ROAS to Facebook (Meta) Ads Manager Source: https://docs.upstackdata.com/guides/facebook-ads/how-to-add-nc-purchase-metrics-and-nc-roas-to-facebook-meta-ads-manager Add NC Purchase metrics and create NC-ROAS in Facebook (Meta) Ads Manager to measure new-customer revenue and optimize campaigns for first-time buyers. <Tip> * Sign in to [Meta Ads Manager](https://adsmanager.facebook.com) and open any campaigns table. * Click **Columns → Customize columns**. * Under **Custom Conversions**, add **NC Purchase** (Total + Cost). * Click **Create custom metric** and define **NC-ROAS = NC Purchase Conversion Value ÷ Amount spent**. * Click **Apply** to save the column layout. </Tip> ## Prerequisites Before you start, you need: * The **NC Purchase** custom conversion already created **and** shared with the ad account you're configuring — see [How to create and share the NC Purchase custom conversion](/guides/facebook-ads/how-to-create-and-share-nc-purchase-custom-conversion-in-facebook-meta) * Admin or campaign-management access to the Meta ad account you want to update columns for ## What you'll achieve After completing this setup, you'll see new-customer metrics — **NC-ROAS** (New Customer Return on Ad Spend), **Cost per NC Purchase**, and **Total NC Purchases** — directly in Meta Ads Manager. ## Part 1 — Add NC Purchase metrics to columns <Steps> <Step title="Open Customize columns in Meta Ads Manager"> Sign in to Meta Ads Manager at [adsmanager.facebook.com](https://adsmanager.facebook.com), select the ad account you want to configure, then on the campaigns/ad sets/ads table click **Columns** in the toolbar above the table and select **Customize columns**. <img alt="Meta Ads Manager Columns dropdown with Customize columns option" /> </Step> <Step title="Add the NC Purchase metrics"> In the **Customize columns** dialog, scroll the left-hand category list to **Custom Conversions** and select your **NC Purchase** conversion (it may be named **NewCustomerPurchase** depending on how you created it). Check both checkboxes that appear: * **Total** — total number of new-customer purchases attributed * **Cost** — cost per new-customer purchase <img alt="Customize columns showing NC Purchase conversion with Total and Cost checkboxes" /> </Step> </Steps> ## Part 2 — Set up the NC-ROAS custom metric <Steps> <Step title="Open Create custom metric"> Inside the **Customize columns** dialog, click **Create custom metric** in the bottom-left. <img alt="Create custom metric button in Customize columns dialog" /> </Step> <Step title="Configure the NC-ROAS formula"> Fill in the new-metric form: * **Name:** `NC-ROAS` * **Formula:** `NC Purchase Conversion Value` ÷ `Amount spent` * Click **Create metric** <Warning> Check **Everyone with access to this Business** if you want the metric to be available to your whole team. </Warning> <img alt="NC-ROAS custom metric formula with conversion value divided by amount spent" /> </Step> <Step title="Add NC-ROAS to your columns and apply"> Back in **Customize columns**, find **NC-ROAS** under **Custom metrics** and check it so it appears in your table. Click **Apply** in the bottom-right of the dialog to save the column layout. <img alt="Apply button to save column layout with NC-ROAS added" /> </Step> <Step title="Verify the new columns appear"> Your Ads Manager table should now show three new columns: * **NC Purchase (Total)** — number of new customers acquired * **NC Purchase (Cost)** — cost per new customer * **NC-ROAS** — return on ad spend from new customers <Warning> Initially, the new columns may show **0** or **—** because Meta does **not** retroactively attribute custom conversions from before they were created. Data populates for conversions that occur **after** the conversion was created and shared. Allow 24–48 hours of new traffic before judging the values. </Warning> </Step> </Steps> # How to Approve Facebook (Meta) Custom Events Source: https://docs.upstackdata.com/guides/facebook-ads/how-to-approve-facebook-meta-custom-events Approve custom events in Facebook (Meta) Events Manager so they become eligible for ad campaign optimization, custom audiences, and conversion reporting. ## Why event approval is required <Note> Custom events showing the ⚠️ red triangle warning in Meta Events Manager must be approved (acknowledged and confirmed) before Meta will use them for ad delivery optimization or campaign targeting. </Note> <Tip> * Sign in to [Meta Events Manager](https://business.facebook.com/events_manager2) and open the affected pixel. * Click the **custom event** (or its red triangle icon) and choose **Manage status**. * Click **I acknowledge**, then **Confirm the custom event**, then **Confirm**. * Refresh the events list and confirm the red triangle is gone. </Tip> ## Prerequisites Before you start, you need: * Access to the same **Meta Business Manager** that owns the pixel firing the custom event * Editor or admin permissions on the pixel/dataset in Meta Events Manager * At least one fired instance of the custom event (so it appears in the events list) ## Step-by-step instructions <Steps> <Step title="Sign in to Meta Events Manager"> Sign in to Meta Events Manager at [business.facebook.com/events\_manager2](https://business.facebook.com/events_manager2) and select the pixel containing the custom event. <img alt="Meta Events Manager showing pixel with custom events" /> </Step> <Step title="Open the custom event for review"> On the pixel **Overview** tab, locate the custom event with the ⚠️ warning. Click either: * The **name** of the custom event, or * The **red triangle ⚠️** warning icon next to it Then click **Review** (or open **Manage status**). <img alt="Custom event with red triangle warning icon in events list" /> <img alt="Manage status option for reviewing custom event" /> </Step> <Step title="Acknowledge the event"> In the review dialog, click **I acknowledge**. <Note> This confirms you understand this is a custom event you've intentionally created (in this case, sent by Upstack Data). </Note> <img alt="I acknowledge button in custom event review dialog" /> </Step> <Step title="Confirm the custom event"> Complete the final approval: * Click **Confirm the custom event** * Click **Confirm** to finalize <img alt="Confirm the custom event button to finalize approval" /> </Step> <Step title="Verify the warning is cleared"> Refresh the **Overview** tab. The ⚠️ red triangle should no longer appear next to the event, and its status should read **Active**. The event is now approved and available as an optimization or targeting event in **Meta Ads Manager**. </Step> </Steps> # How to Configure Facebook (Meta) Ads Pixel Destination in Upstack Data Source: https://docs.upstackdata.com/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data Configure the Facebook (Meta) Ads destination in Upstack Data with your Pixel ID and Conversion API key to enable dual tracking via browser pixel and server-side CAPI. <Tip> * In the Upstack dashboard, go to **Event Destinations** and click **+ New Destination**. * Select **Facebook Advertising**. * Enter your **Meta Pixel ID** (15–16 digit number, no prefix). * Enable the **Conversions API** checkbox and paste your **CAPI token** (starts with `EAA`). * Click **Create Configuration** and verify the destination shows **Healthy**. </Tip> <Note> **What this setup enables** Setting up the Meta Ads Pixel destination in Upstack Data enables dual tracking via browser pixel and server-side Conversions API (CAPI), ensuring accurate conversion data despite iOS restrictions and ad blockers. </Note> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to a **Meta Business Manager** account * A configured **Meta Pixel** in [Meta Events Manager](https://business.facebook.com/events_manager) — see [How to find your Meta Pixel ID](/guides/facebook-ads/how-do-i-find-my-facebook-ads-pixel-dataset-id) * A **Conversions API access token** — see [How to generate your CAPI token](/guides/facebook-ads/how-to-generate-my-facebook-conversion-api-key) ## Configuration steps <Steps> <Step title="Sign in to Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com/pixel/event-destinations). </Step> <Step title="Open the destination configuration"> In the Upstack dashboard, navigate to **Event Destinations**. Click **+ New Destination** in the top-right of the page. <img alt="Add New Destination" /> In the **Select a Destination** popup, click **Facebook Advertising**, then click **Next**. <img alt="Facebook Pixel Configuration" /> </Step> <Step title="Enter your Pixel ID and CAPI token"> Fill in the form: 1. **Meta Pixel ID** — the 15–16 digit number, no prefix (e.g., `123456789012345`). Meta Pixel IDs do **not** have an `AW-` prefix; that prefix belongs to Google Ads. 2. Check the box **Check to enable sending events via Facebook Conversions API**. 3. **CAPI token** — starts with `EAA`, approximately 190 characters long. <Warning> The Conversions API checkbox **must be selected** for server-side tracking to work. </Warning> <img alt="Meta destination form with Pixel ID and Conversions API fields" /> <Note> **Need help finding these?** * [How to find your Meta Pixel ID](/guides/facebook-ads/how-do-i-find-my-facebook-ads-pixel-dataset-id) * [How to generate your CAPI token](/guides/facebook-ads/how-to-generate-my-facebook-conversion-api-key) </Note> </Step> <Step title="Create the configuration"> Click the **Create Configuration** button. <img alt="Create Configuration button to save Meta destination" /> You should see a confirmation message and the Meta destination will appear in your **Event Destinations** list. <img alt="Meta destination showing Healthy status in Event Destinations list" /> </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, the Meta destination card should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**: * Confirm your **Pixel ID** is correct (15–16 digits, no leading/trailing spaces, no prefix). * Confirm your **CAPI token** is the full string starting with `EAA`. * Confirm the **Conversions API** checkbox was selected. * See [How to update your CAPI token](/guides/facebook-ads/how-to-update-facebook-meta-conversion-api-key) if your token may have expired. </Step> </Steps> # How to Connect your Facebook Ads Account in Upstack Data Integrations Source: https://docs.upstackdata.com/guides/facebook-ads/how-to-connect-your-facebook-ads-account-in-upstack-data-integrations Connect your Facebook Ads account to Upstack Data so spend, impressions, and clicks pull into the dashboard for unified channel-level ROAS and attribution reporting. <Tip> * Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com) and navigate to **Data Integrations**. * On the **Facebook ads** card, open the **kebab menu** (3 dots) → click **Connect**. * Authorize with Facebook and select the **ad account** you want to connect. * Click **Save** and verify the integration shows **Healthy**. </Tip> <Note> **Purpose of this setup** Connecting your Facebook ads account is required to access performance data at the account, campaign, ad set, and ad levels, which powers your dashboards and attribution reporting. </Note> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin or advertiser access to the **Facebook ad account** you want to connect * A Facebook user account that can sign in via OAuth on this browser ## Configuration steps <Steps> <Step title="Sign in to Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com), then navigate to **Data Integrations** in the left-hand menu (or open it directly at [app.upstackdata.com/pixel/integrations](https://app.upstackdata.com/pixel/integrations)). <img alt="Upstack dashboard with Data Integrations menu option" /> </Step> <Step title="Open the Facebook ads connector"> On the **Data Integrations** page, find the **Facebook ads** card and click the **kebab menu** (3 dots) in the top-right of the card, then click **Connect**. <img alt="Facebook ads card with kebab menu showing Connect option" /> If the Facebook account shown is correct, click **Connect** or **Reconnect**. <img alt="Facebook account confirmation with Connect button" /> If the Facebook account shown is **not** the one that has access to your ad account, click **Log into another account**. <img alt="Log into another account option for different Facebook user" /> </Step> <Step title="Select the Facebook ad account"> A popup displays every ad account linked to your Facebook user. Select the **Facebook ad account** you want Upstack Data to read performance data from. <img alt="Facebook ad account selection popup with available accounts" /> </Step> <Step title="Save the configuration"> Click the **Save** button. <img alt="Save button to confirm Facebook ads connection" /> <img alt="Facebook ads integration showing successful connection" /> </Step> <Step title="Verify the integration is healthy"> In the Upstack dashboard, the **Facebook ads** integration card should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy** or **Reconnect required**: * Confirm the Facebook user that authorized the connection still has access to the ad account. * Re-run the **Connect** flow and re-grant all requested permissions when prompted. </Step> </Steps> # How to Create and Share NC Purchase Custom Conversion in Facebook (Meta) Source: https://docs.upstackdata.com/guides/facebook-ads/how-to-create-and-share-nc-purchase-custom-conversion-in-facebook-meta Create and share an NC Purchase custom conversion in Facebook (Meta) Events Manager to attribute new-customer revenue to ads and share the metric across ad accounts. <Tip> * Sign in to [Meta Events Manager](https://business.facebook.com/events_manager) and open **Custom Conversions → Create custom conversion**. * Name the conversion **NC Purchase** and select the **ncPurchase** event. * Choose **Purchase** as the optimization event and add a URL rule of **doesn't contain `doesnotexist`**. * Share the conversion with every ad account that needs to use it. </Tip> <Note> **What you'll create** A custom conversion that tracks **new-customer** purchases, so you can optimize campaigns for customer acquisition rather than repeat purchases. </Note> ## Prerequisites Before you start, you need: * The **Meta destination** configured in Upstack Data — see [How to configure the Meta Pixel destination](/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data) * The **ncPurchase** event verified in Meta Events Manager — see [How to verify the NC Purchase event](/guides/facebook-ads/how-to-verify-the-nc-purchase-event-in-facebook-meta-events-manager) * Admin access to the Meta Business Manager and to every ad account you plan to share the conversion with ## Part 1 — Create the NC Purchase custom conversion <Steps> <Step title="Sign in to Meta Events Manager"> Sign in to Meta Events Manager at [business.facebook.com/events\_manager](https://business.facebook.com/events_manager). </Step> <Step title="Open Custom Conversions"> In the left-hand menu, click **Custom Conversions**, then click **Create custom conversion** in the top-right. <img alt="Meta Events Manager Custom Conversions page with Create button" /> </Step> <Step title="Name and select the event"> In the **Create a custom conversion** dialog: * **Name:** `NC Purchase` * **Event:** select **ncPurchase** <Note> If you don't see **ncPurchase** in the Event dropdown, return to Meta Events Manager and verify the event first. See [How to verify the NC Purchase event](/guides/facebook-ads/how-to-verify-the-nc-purchase-event-in-facebook-meta-events-manager). </Note> </Step> <Step title="Set the optimization event"> In the **Choose a standard event for optimization** field, select **Purchase**. This tells Meta to optimize delivery using its Purchase model when this custom conversion is used. </Step> <Step title="Configure URL rules"> Under **Rules**: 1. Choose **URL** as the parameter 2. Select **doesn't contain** as the condition 3. Type `doesnotexist` in the value field 4. Press **Enter** until the value becomes a light-grey tag 5. Click **Create** <Note> **Why this rule?** Since no URL on your store contains `doesnotexist`, this rule effectively matches every page — so the custom conversion fires for the **ncPurchase** event across your entire site. </Note> <img alt="Custom conversion URL rule configuration with doesnotexist condition" /> </Step> </Steps> ## Part 2 — Share with ad accounts <Steps> <Step title="Open the share menu"> On the **Custom Conversions** page, find the **NC Purchase** conversion you just created. Click the **dropdown** (kebab menu) on the right of the row, then click **Share**. <img alt="NC Purchase conversion row with kebab menu showing Share option" /> </Step> <Step title="Choose Share with an Ad Account"> In the share dialog, click **Share with an Ad Account**. <img alt="Share dialog with Share with an Ad Account option" /> </Step> <Step title="Select the ad accounts"> Check every ad account that needs to use this custom conversion. <img alt="Ad account selection list with checkboxes" /> <img alt="Multiple ad accounts selected for sharing" /> </Step> <Step title="Confirm sharing"> Click **Share Custom Conversion** to confirm. <img alt="Share Custom Conversion button to confirm sharing" /> </Step> <Step title="Verify the conversion is shared and active"> Back on the **Custom Conversions** page, the **NC Purchase** row should show: * **Status:** Active (no warning icon) * **Shared with:** the ad accounts you selected Open one of those ad accounts in **Ads Manager** and confirm **NC Purchase** appears in the **Custom Conversions** list when you customize columns or pick a conversion event for a campaign. </Step> </Steps> ## What's next? After creating and sharing the conversion, set up reporting: [Set up NC-ROAS metrics in Ads Manager →](/guides/facebook-ads/how-to-add-nc-purchase-metrics-and-nc-roas-to-facebook-meta-ads-manager) # How to Disable Facebook and Instagram Data Sharing in Shopify Source: https://docs.upstackdata.com/guides/facebook-ads/how-to-disable-facebook-and-instagram-data-sharing-in-shopify Disable Shopify's Facebook and Instagram sales channel pixel to stop duplicate Meta Pixel events and let Upstack Data deliver clean server-side conversions to Meta CAPI. <Tip> * Sign in to your Shopify admin at [admin.shopify.com](https://admin.shopify.com). * Open **Sales channels → Facebook & Instagram → Settings**. * Under **Share data**, click **Change**. * Toggle **Share data** to **Off** and click **Save**. </Tip> <Warning> Most causes of duplicate events are because you have more than one Facebook integration active on your site. Disable the **Facebook & Instagram sales channel data sharing** in Shopify and confirm no other Facebook pixel apps (or theme-injected pixels) are installed. </Warning> ## Prerequisites Before you start, you need: * Owner or staff access to your **Shopify admin** with permission to edit sales channels * The **Facebook & Instagram sales channel** installed in Shopify (if it's not installed, there's nothing to disable) * A configured Meta destination in Upstack Data so the pixel keeps firing after you disable Shopify's native integration — see [How to configure the Meta Pixel destination](/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data) ## Steps to disable Facebook and Instagram data sharing in Shopify <Steps> <Step title="Sign in to Shopify"> Sign in to your Shopify admin at [admin.shopify.com](https://admin.shopify.com). </Step> <Step title="Open the Facebook & Instagram sales channel"> In the Shopify admin, click **Sales channels** in the left-hand menu, select **Facebook & Instagram**, then click the **Settings** tab. *Tip: You can also use the top search bar to jump directly to the Facebook & Instagram sales channel.* <img alt="Shopify admin with Facebook & Instagram sales channel selected" /> </Step> <Step title="Open the Share data settings"> On the Facebook & Instagram **Settings** page, locate the **Share data** section and click **Change**. <img alt="Facebook & Instagram Settings page with Share data section and Change button" /> </Step> <Step title="Toggle off data sharing"> Toggle **Share data** to **Off**. <img alt="Share data toggle switched to Off position" /> </Step> <Step title="Save your changes"> With **Share data** now set to **Off**, click the **Save** button at the bottom of the page. <img alt="Save button to confirm Share data changes" /> </Step> <Step title="Verify data sharing is disabled"> After saving, the Facebook & Instagram **Settings** page should now show **Share data: Off**. <img alt="Facebook & Instagram Settings showing Share data Off confirmation" /> Within 24 hours, you should also see duplicate-event warnings clear in **Meta Events Manager**. If duplicates persist, also check for: * Third-party Facebook pixel apps in Shopify * Manual pixel code in your theme files (`theme.liquid`, header snippets) * Facebook pixel tags inside Google Tag Manager </Step> </Steps> <Note> **Need help?** If duplicate events continue after disabling Shopify's native integration, contact our support team with your Pixel ID and we'll help diagnose the source. </Note> ## Related Articles <CardGroup> <Card title="Configure Meta Pixel destination" href="/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data" /> <Card title="Duplicate events troubleshooting" href="/troubleshooting/duplicate-events" /> <Card title="Enable theme app extension" href="/guides/shopify/how-to-ensure-upstack-data-theme-app-extension-is-enabled" /> <Card title="Complete Meta onboarding guide" href="/guides/facebook-ads/complete-how-to-guide-for-onboarding-facebook-meta-in-upstack-data" /> </CardGroup> # How to Generate my Facebook Conversion API Key? Source: https://docs.upstackdata.com/guides/facebook-ads/how-to-generate-my-facebook-conversion-api-key Generate a Facebook (Meta) Conversion API access token in Meta Events Manager and paste it into Upstack Data to enable server-side conversion forwarding via CAPI. <Tip> * Sign in to [Meta Events Manager](https://business.facebook.com/events_manager) and open your pixel. * Open the **Settings** tab and scroll to the **Conversions API** section. * Click **Generate access token** and copy the token immediately — it is shown only once. * Paste the **CAPI token** (starts with `EAA`) into your Upstack Meta destination. </Tip> <Note> **What is a CAPI token?** A **Conversions API (CAPI) token** is a Meta access token that lets Upstack Data send conversions from your server to Meta, improving accuracy for iOS users and ad-blocked traffic. </Note> ## Prerequisites Before you start, you need: * **Admin access** (or full access) to a **Meta Business Manager** account * A pixel already created in [Meta Events Manager](https://business.facebook.com/events_manager) — see [How to find your Meta Pixel ID](/guides/facebook-ads/how-do-i-find-my-facebook-ads-pixel-dataset-id) * An Upstack Data account ready to receive the token ([sign in](https://app.upstackdata.com)) ## Steps to generate your CAPI token <Steps> <Step title="Sign in to Meta Events Manager"> Sign in to Meta Events Manager at [business.facebook.com/events\_manager](https://business.facebook.com/events_manager). </Step> <Step title="Find or create your pixel"> **If you already have a pixel**, you'll see it listed in the **Data Sources** panel — proceed to the next step. **If you need to create one:** * Click the green **Connect Data Sources** button * Select **Web** * Click **Next** or **Get Started** * Follow the instructions to create a new Meta Pixel <img alt="Meta Events Manager with Connect Data Sources button" /> <img alt="Select Web as data source type in Meta Events Manager" /> </Step> <Step title="Open the pixel overview"> In the **Data Sources** list, click your pixel's name. You'll land on the pixel's **Overview** page. </Step> <Step title="Navigate to the Settings tab"> On the pixel **Overview** page, click the **Settings** tab in the left-hand menu. <img alt="Meta Pixel Settings tab in left-hand navigation" /> </Step> <Step title="Generate the access token"> On the **Settings** tab, scroll down to the **Conversions API** section and click **Generate access token**. <img alt="Conversions API section with Generate access token button" /> </Step> <Step title="Copy your CAPI token"> Copy the value of the access token shown in the dialog. This is your **CAPI token**. <Warning> The token is shown **only once** — copy it immediately to a secure location. If you close the dialog without copying, you'll need to generate a new one. </Warning> <img alt="Generated CAPI access token dialog with copy option" /> **Token format:** starts with `EAA`, approximately 190 characters long (e.g., `EAAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx...`). </Step> <Step title="Add the token to Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com/pixel/event-destinations) and open your **Meta** destination under **Event Destinations**. Paste the token into the **Conversions API token** field. <Note> Make sure the **Check to enable sending events via Facebook Conversions API** checkbox is selected. </Note> <img alt="Upstack Meta destination with Conversions API token field" /> <Warning> The CAPI token is sensitive — store it securely. The token is tied to a single Meta ad account and cannot be reused across accounts. </Warning> </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, the Meta destination card should show **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**: * Confirm the token starts with `EAA` and was pasted in full (no truncation, no whitespace). * Confirm the **Conversions API** checkbox is selected. * Confirm the Pixel ID matches the pixel you generated the token for. </Step> </Steps> <Note> **Need help with the Pixel ID?** See [How to find your Meta Pixel ID](/guides/facebook-ads/how-do-i-find-my-facebook-ads-pixel-dataset-id). </Note> ## Related Articles <CardGroup> <Card title="Find your Meta Pixel ID" href="/guides/facebook-ads/how-do-i-find-my-facebook-ads-pixel-dataset-id" /> <Card title="Configure Meta Pixel destination" href="/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data" /> <Card title="Update Facebook CAPI key" href="/guides/facebook-ads/how-to-update-facebook-meta-conversion-api-key" /> <Card title="Connection errors and disconnections" href="/troubleshooting/integration-connection-errors-and-disconnections" /> </CardGroup> # How to Update Facebook (Meta) Conversion API Key? Source: https://docs.upstackdata.com/guides/facebook-ads/how-to-update-facebook-meta-conversion-api-key Rotate or update your Facebook (Meta) Conversion API access token in Upstack Data to keep server-side events flowing into Meta CAPI without breaking pixel health. ## Overview <Note> If you've seen warnings like *"My Conversions API is not getting any events"* or received an email that your *Meta Pixel is unhealthy*, it means your CAPI token needs to be refreshed. This guide walks you through updating your Meta CAPI token in Upstack Data so events flow correctly, attribution stays accurate, and your pixel remains healthy. </Note> <Tip> * Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com/pixel/event-destinations) and open **Event Destinations**. * Click your **Meta destination** to edit it. * Paste a fresh **CAPI token** (starts with `EAA`) into the **Conversions API token** field. * Click **Update Configuration** and verify the destination shows **Healthy**. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account with a Meta destination already configured * A new **CAPI token** generated from [Meta Events Manager](https://business.facebook.com/events_manager) — see [How to generate your CAPI token](/guides/facebook-ads/how-to-generate-my-facebook-conversion-api-key) * The token copied to your clipboard (it is shown only once when generated) ## Configuration steps <Steps> <Step title="Sign in to Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com/pixel/event-destinations). In the Upstack dashboard, navigate to **Event Destinations**. <img alt="Upstack dashboard Event Destinations page" /> </Step> <Step title="Open your Meta destination"> In the **Event Destinations** list, click your **Meta destination** to edit it. <img alt="Meta destination card in Event Destinations list" /> Confirm the **Check to enable sending events via Facebook Conversions API** checkbox is selected, then paste your new **CAPI token** into the **Conversions API token** field. Replace the existing value entirely. <img alt="Meta destination edit form with CAPI token field" /> <Note> The CAPI token starts with `EAA` and is approximately 190 characters long. Leave the **Pixel ID** unchanged (15–16 digit number, no prefix). </Note> <Note> **Need help finding these?** * [How to generate your CAPI token](/guides/facebook-ads/how-to-generate-my-facebook-conversion-api-key) * [How to find your Meta Pixel ID](/guides/facebook-ads/how-do-i-find-my-facebook-ads-pixel-dataset-id) </Note> </Step> <Step title="Save the updated configuration"> Click **Update Configuration** to save the change. <img alt="Update Configuration button to save Meta destination changes" /> </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, the Meta destination card should display **Healthy** with a green status indicator within 5 minutes. If the status still shows **Unhealthy**: * Confirm the new CAPI token starts with `EAA` and was pasted in full (no truncation or whitespace). * Confirm the user who generated the token has admin access to the Meta Business Manager that owns the pixel. * See [Why is my Meta EMQ panel showing zeros?](/guides/facebook-ads/why-is-my-meta-emq-panel-showing-zeros-0-0-10) for token-permission troubleshooting. </Step> </Steps> # How to Verify the NC Purchase Event in Facebook (Meta) Events Manager Source: https://docs.upstackdata.com/guides/facebook-ads/how-to-verify-the-nc-purchase-event-in-facebook-meta-events-manager Verify the NC Purchase event arrives in Facebook (Meta) Events Manager from Upstack Data — confirm event match quality, deduplication, and new-customer attribution before enabling optimization. <Tip> * Sign in to [Meta Events Manager](https://business.facebook.com/events_manager) and open the pixel connected to Upstack Data. * On the **Overview** tab, find the **ncPurchase** event in the events list. * Hover over the event to reveal **Review**, or open **Manage status** and click **Review**. * Acknowledge and confirm the event so the red triangle warning clears. </Tip> <Note> **What is the New Customer (NC) Purchase event?** The **NC Purchase** (`ncPurchase`) event is a custom event sent by Upstack Data that fires when a first-time customer makes a purchase. The event must be verified in Meta Events Manager before you can create custom conversions or track new-customer metrics in Meta Ads Manager. </Note> ## Prerequisites Before you start, you need: * The **Meta destination** configured in Upstack Data — see [How to configure the Meta Pixel destination](/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data) * At least one real new-customer purchase already processed so the **ncPurchase** event is visible in Meta Events Manager * Access to the same Meta Business Manager that owns the pixel ## Steps to verify the ncPurchase event <Steps> <Step title="Sign in to Meta Events Manager"> Sign in to Meta Events Manager at [business.facebook.com/events\_manager](https://business.facebook.com/events_manager) and open the pixel that Upstack Data is sending events to. </Step> <Step title="Locate the ncPurchase event"> On the pixel **Overview** tab, scroll the events list until you see **ncPurchase**. If you don't see it, wait a few hours after your first new-customer purchase or contact support. </Step> <Step title="Open the review flow"> Use either of the following: * **Option A:** Hover over the **ncPurchase** row to reveal the **Review** button, then click **Review**. <img alt="ncPurchase event row with Review button on hover" /> * **Option B:** Click **Manage status** in the top-right of the events list, then click **Review** next to **ncPurchase**. <img alt="Manage status dropdown with Review option for ncPurchase" /> </Step> <Step title="Acknowledge and confirm"> In the review dialog, click **I acknowledge**, then click **Confirm the custom event** and **Confirm** to finalize. See [How to approve Meta custom events](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events) for the full approval flow with screenshots. </Step> <Step title="Verify the event is approved"> Refresh the **Overview** tab. The red triangle warning next to **ncPurchase** should be gone, and the event status should read **Active** (or no warning icon). Once verified, you can use **ncPurchase** when creating custom conversions in Meta. </Step> </Steps> ## What's next? After verifying the ncPurchase event, you can: * [Create and share the NC Purchase custom conversion](/guides/facebook-ads/how-to-create-and-share-nc-purchase-custom-conversion-in-facebook-meta) * [Set up NC-ROAS metrics in Ads Manager](/guides/facebook-ads/how-to-add-nc-purchase-metrics-and-nc-roas-to-facebook-meta-ads-manager) # "Low Rate of Pixel Events Covered by Conversions API" in Meta Events Manager Source: https://docs.upstackdata.com/guides/facebook-ads/low-rate-of-pixel-events-covered-by-conversions-api-in-meta-events-manager Why this Meta Events Manager warning is normal for Upstack customers, why no action is needed, and why you should not set up the Conversions API Gateway. <Note> **Short answer: this is normal and you can disregard it.** No action is needed. Your events are already being sent through the Conversions API by Upstack Data. Do not click "Review solution" and do not set up Meta's Conversions API Gateway — doing so will cause duplicate events. </Note> ### What You're Seeing In **Meta Events Manager**, under "Top errors affecting your performance" (or the Diagnostics tab), you see a warning that looks like this: <img alt="Meta Events Manager warning showing low rate of pixel events covered by Conversions API" /> <Note> Insert the Events Manager screenshot showing the "Low rate of pixel events covered by Conversions API" warning here. </Note> The warning reads: <Note> **Low rate of pixel events covered by Conversions API** Try the Conversions API Gateway demo to improve your coverage rate and get better reporting accuracy. Advertisers with a 75 percent coverage rate saw lower cost per result versus Pixel alone for events. </Note> Next to it there is a blue **Review solution** button. ### Why You Don't Need to Do Anything This is one of Meta's standard recommendations, shown across many ad accounts, and for Upstack Data customers it's a false positive. Here's why you can safely ignore it: * **Upstack is already sending your events through the Conversions API.** Every event we track is sent twice — once from the browser pixel and once server-side through CAPI — with a shared `event_id` so Meta deduplicates them into a single event. * **The "Review solution" flow is designed for advertisers who don't have CAPI set up.** That is not you. Meta shows the same prompt to every account that dips below their target coverage rate, regardless of whether a CAPI integration is already running. * **Your reporting, attribution, and optimization are unaffected.** The warning does not impact how Meta counts your conversions or optimizes your ad delivery. ### What You Should NOT Do <Warning> Do NOT set up any additional Conversions API integration on top of Upstack. This includes: </Warning> * **Do not click "Review solution"** or start Meta's Conversions API Gateway demo * **Do not install Meta's Conversions API Gateway** (the Cloudflare-hosted CAPI forwarder) * **Do not enable CAPI through the Shopify Facebook & Instagram sales channel** * **Do not install any third-party CAPI app** (for example, other tracking tools that also offer server-side Meta events) Adding another CAPI sender alongside Upstack will cause the **same event to be sent twice without matching deduplication IDs**. Meta will count those as separate events, which inflates your reported conversions, distorts cost per result, and can confuse ad delivery optimization. ### Why Meta Shows This Warning Anyway Meta's "coverage rate" compares two event streams on the same pixel: browser events (fired by the Meta Pixel JavaScript) and server events (sent via the Conversions API). When the ratio of matched browser-to-server events drops below roughly 75 percent on a rolling window, Meta surfaces this warning. A few reasons you can see this warning even though Upstack is working correctly: * **Measurement noise.** Meta's coverage math is not always perfect, especially on low-volume days or when events arrive out of order. Short dips below the threshold are common and self-correct over time. * **Rolling window lag.** The metric is calculated over a trailing 7-day window, so recent fixes (new token, new setup) take a few days to show up in the score. * **Browser events from non-Upstack sources.** If another tool on your site is firing browser pixel events that Upstack doesn't see — for example, a raw pixel in your Shopify theme, a GTM tag, or a landing page builder — those events have no matching server-side pair, which lowers coverage. See "When to contact us" below. None of these require you to add more CAPI coverage. They require (at most) cleaning up duplicate browser-side sources, which we can help with. ### When to Contact Us You only need to reach out if you see one of the following, which would suggest a real issue rather than normal measurement drift: * Your Meta destination inside Upstack Data is flagged as **"needs attention"** or shows as unhealthy * Your **Event Match Quality (EMQ) scores** drop sharply in the Upstack dashboard * Your reported Meta conversions are meaningfully different from your actual orders in Shopify or WooCommerce * You suspect another pixel is firing alongside Upstack and want help identifying it Otherwise, no action is required — the warning can stay in your Events Manager without affecting your performance. ### Related Articles * [Why is my Meta EMQ Panel Showing Zeros (0.0/10)?](/guides/facebook-ads/why-is-my-meta-emq-panel-showing-zeros-0-0-10) * [How to Configure Facebook (Meta) Ads Pixel Destination in Upstack Data](/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data) * [How to Generate my Facebook Conversion API Key](/guides/facebook-ads/how-to-generate-my-facebook-conversion-api-key) * [How to Update Facebook (Meta) Conversion API Key](/guides/facebook-ads/how-to-update-facebook-meta-conversion-api-key) <Note> **Still have questions?** If you're unsure whether the warning in your account is normal or something to worry about, message our support team with your Pixel ID and store URL. We'll check your CAPI event stream and confirm everything is healthy. </Note> # Set up NC & RC Purchase events in Meta Source: https://docs.upstackdata.com/guides/facebook-ads/set-up-nc-and-rc-purchase-events-in-meta Configure NC Purchase, RC Purchase, and subscription events in Meta Events Manager and Ads Manager to optimize for new customer acquisition and retention. Custom events give ad platforms more specific signals to optimize against. The most impactful is **NC Purchase** — it tells Meta to find buyers who've never purchased from you before, instead of optimizing toward repeat customers. Without it, Meta's algorithm treats a first-time buyer and a fifth-time buyer as equally valuable conversions. ## New customer purchase (NC Purchase) NC Purchase fires only when an order comes from a customer with no prior Shopify order history. This enables NC CPA and NC ROAS reporting directly in Meta Ads Manager — two metrics that separate prospecting performance from retargeting performance. ### Set up in Facebook <Steps> <Step title="Wait for the first event"> Once Upstack is live, the first NC Purchase event appears in Meta Events Manager within minutes for active stores. You need at least one event before you can proceed. See [How to verify the NC Purchase event in Facebook Events Manager](/guides/facebook-ads/how-to-verify-the-nc-purchase-event-in-facebook-meta-events-manager) for a walkthrough. </Step> <Step title="Acknowledge the event"> Go to **Events Manager → find NC Purchase → Review → Acknowledge/Confirm**. This tells Meta to start processing NC Purchase as a recognized event. </Step> <Step title="Create a custom conversion"> In Events Manager, go to **Custom Conversions → Create**. Set the event to **NC Purchase** and give it a clear name (e.g., "Upstack NC Purchase"). See [How to create and share NC Purchase custom conversion in Facebook](/guides/facebook-ads/how-to-create-and-share-nc-purchase-custom-conversion-in-facebook-meta) for detailed steps. <Info> You need **Business Manager admin access** (not just ad account admin) to create custom conversions. If you run ads through an agency ad account, switch the Events Manager view to your own Business Manager before creating the conversion. </Info> </Step> <Step title="Add reporting columns"> In Ads Manager, add **NC CPA** and **NC ROAS** as columns in your reporting view. These metrics let you evaluate prospecting performance independently from retargeting. See [How to add NC Purchase metrics and NC ROAS to Facebook Ads Manager](/guides/facebook-ads/how-to-add-nc-purchase-metrics-and-nc-roas-to-facebook-meta-ads-manager) for column configuration. </Step> </Steps> <Note> Attribution is forward-looking only — Meta does not backfill historical data for new event types. NC Purchase metrics start populating from the moment the custom conversion is created. </Note> For the complete end-to-end walkthrough, see [Complete guide to setting up NC Purchase metrics in Facebook Ads Manager](/guides/facebook-ads/complete-how-to-guide-for-setting-up-new-customer-purchase-metrics-in-facebook-meta-ads-manager). <Accordion title="When to use NC Purchase vs. standard Purchase"> Custom purchase events supplement the standard `Purchase` event — they don't replace it. Keep standard `Purchase` active alongside the custom events so Meta's baseline models still receive every order. | Scenario | Recommended event | | ---------------------------------------------- | ------------------------------------ | | General ROAS optimization | Standard `Purchase` | | Scaling new customer acquisition | `nc_purchase` | | Prospecting campaigns targeting cold audiences | `nc_purchase` | | Retargeting campaigns for existing customers | `rc_purchase` or standard `Purchase` | | Brand awareness / top-of-funnel | Standard `Purchase` (broader signal) | | Measuring retention campaign performance | `rc_purchase` | **Allow a learning phase.** When you switch an ad set from standard Purchase to `nc_purchase`, it re-enters Meta's learning phase. Meta needs roughly 50 optimization events per week to exit learning, so start with your highest-spend or highest-volume campaign first if new-customer volume is low. **Compare before shifting budget.** Run `nc_purchase`-optimized campaigns alongside standard Purchase-optimized campaigns for 2–4 weeks and compare new-customer rate, CAC, and ROAS before committing. </Accordion> ## Returning customer purchase (RC Purchase) RC Purchase is the inverse of NC Purchase: it fires only when an order comes from a customer **with existing Shopify order history**. Together, the two events partition every order into acquisition vs. retention signals, which you can use separately in audience building, retargeting, and retention measurement. Classification uses the same Shopify-order-history check as NC Purchase — if the customer has zero prior completed orders, Upstack fires `nc_purchase`; if they have one or more, it fires `rc_purchase`. The standard `Purchase` event still fires for every order regardless of customer status, so baseline reporting is unaffected. ### Why it matters * **Build retargeting audiences that exclude first-time buyers.** Feed `rc_purchase` into custom audiences of recent repeat customers for win-back campaigns, loyalty offers, or cross-sells. * **Measure retention, not just acquisition.** Treat `rc_purchase` volume and value as a direct signal of how well retention campaigns (email, SMS, paid retargeting) are performing. * **Avoid over-indexing on repeat buyers in prospecting.** Pairing `rc_purchase` with `nc_purchase` makes it obvious when a "Purchase-optimized" campaign is really just retargeting existing customers. ### Set it up RC Purchase uses the **same four steps as NC Purchase above** — wait for the first event, acknowledge it, create a custom conversion, and add it to your reporting. Only two things differ: * **Creating the custom conversion:** select **RC Purchase** as the event (name it e.g. "Upstack RC Purchase"), set the category to **Purchase**, and leave the value at its default so Meta uses the order value sent with the event. * **Using it:** make the RC Purchase custom conversion the optimization event for **retargeting and retention** ad sets, or add it as a measurement column alongside NC CPA / NC ROAS to see acquisition and retention side by side. <Tip> Enable `nc_purchase` and `rc_purchase` together — running only one leaves half the acquisition-vs-retention segmentation on the table. </Tip> ## Subscription events For subscription brands, Upstack handles subscription events automatically. No manual setup is required. | Event | When it fires | Sent to Meta? | | ---------------------- | ------------------------ | --------------------------- | | Subscription Initial | First subscription order | Yes — counted as a purchase | | Subscription Recurring | Renewal orders | No — excluded from Meta | <Warning> **Why recurring subscriptions are excluded from Meta:** Sending renewal orders as purchase events tells Meta's algorithm that existing customers are converting. This shifts optimization toward retargeting instead of prospecting — the algorithm learns to chase people who were going to buy anyway. Only the initial subscription triggers a purchase event so Meta stays focused on finding new subscribers. </Warning> ## Advanced configuration <Accordion title="Category-specific events"> If you sell across multiple product categories (e.g., apparel and skincare), you can fire purchase events scoped to each category — `apparel_purchase`, `skincare_purchase`, and so on — then create a category-specific custom conversion in Meta for each and optimize ad sets per product line. Set these up yourself with [global event mappings](/guides/custom-events/global-event-mappings): add a condition on the product category and map it to a new event name. </Accordion> <Accordion title="Order source exclusions"> Not every order should feed back into Meta or Google's optimization. Some sources would pollute your conversion data. To configure exclusions, go to **Settings → Order Source Exclusions** and select the sources you want to block: * **TikTok Shop orders** * **Loop** (returns/exchanges) * **Matrixify** (bulk imports) * **Draft Orders** * **POS** (in-store transactions) Recurring subscription orders are excluded automatically. Initial subscription orders **are** sent — these represent genuine new-customer acquisitions. Sources only appear in the exclusion list if you have orders from them. If you don't see a source listed, you haven't had any orders from it yet. <Tip> Send more data to Facebook, not less. Even TikTok Shop orders help Meta find similar customers — the algorithm benefits from volume. Only exclude a source if the orders don't represent real customer acquisition (e.g., wholesale imports) or would actively mislead optimization (e.g., POS sales unrelated to your online ad spend). </Tip> </Accordion> ## Next step <CardGroup> <Card title="Configure contribution margin" icon="arrow-right" href="/get-started/configure-contribution-margin"> Set up COGS, transaction fees, and marketing spend so the P\&L dashboard reflects real profitability. </Card> </CardGroup> ## Related <CardGroup> <Card title="Complete NC Purchase setup guide" icon="book" href="/guides/facebook-ads/complete-how-to-guide-for-setting-up-new-customer-purchase-metrics-in-facebook-meta-ads-manager"> End-to-end walkthrough for NC Purchase, custom conversions, and reporting columns in Meta Ads Manager. </Card> <Card title="Verify NC Purchase events" icon="circle-check" href="/guides/facebook-ads/how-to-verify-the-nc-purchase-event-in-facebook-meta-events-manager"> Confirm NC Purchase events are arriving in Meta Events Manager and recognized correctly. </Card> <Card title="Connect a destination" icon="plug" href="/get-started/connect-a-destination"> Set up Meta CAPI as your first server-side destination for high-quality conversion events. </Card> <Card title="Verify end-to-end delivery" icon="list-check" href="/get-started/verify-end-to-end"> Confirm the complete pipeline works — from storefront event to destination delivery. </Card> </CardGroup> # What is FBC / Facebook Click ID? Source: https://docs.upstackdata.com/guides/facebook-ads/what-is-fbc-facebook-click-id Learn what Facebook's FBC and FBP cookies are, how Upstack sends them via the Conversions API, why FBC expires, and what causes missing or modified values. When someone clicks a Facebook ad, Facebook appends `fbclid` to the URL (for example, `?fbclid=abc123`). Facebook's pixel script reads it and stores it as a first-party cookie (`_fbc`) with a version prefix, timestamp, and click ID value. * **FBCLID** is the URL parameter. * **FBC** is the cookie that stores it. Upstack includes the FBC cookie value when sending events via the Conversions API (CAPI). Facebook compares it against its records — mismatches trigger diagnostics warnings. <Tip> Upstack also preserves click IDs across sessions and devices via its identity graph. A visitor who clicked a Facebook ad last week and returns today via Google can still have their original click ID restored. </Tip> ## FBC expiry Facebook click IDs are valid for 90 days. After that, Facebook considers them expired. Upstack stores click IDs beyond this window so returning visitors can still be matched, but if Facebook no longer recognizes the value, it may trigger a "Modified FBC" diagnostic. ## FBP (Facebook Browser ID) FBC ties to a specific ad click, but Facebook also sets a second first-party cookie called `_fbp`. FBP identifies the browser regardless of whether the visitor came from an ad. Both are sent with every Conversions API event. ## FBC is one of Facebook's strongest matching signals FBC directly links a conversion back to a specific ad click, which is why it carries more weight than email or phone for attribution. A high percentage of missing or modified FBC values can reduce your Event Match Quality score in Events Manager. ## Common reasons FBC goes missing * **Redirects** (age gates, A/B tests, language selectors) can strip the `fbclid` parameter before the pixel reads it. * **Ad blockers** can prevent the cookie from being set in the browser — which is why Upstack also sends events server-side. ## Related Articles <CardGroup> <Card title="Modified FBC value warning" href="/troubleshooting/server-sending-modified-fbc-value-in-events-manager" /> <Card title="Generate Facebook CAPI key" href="/guides/facebook-ads/how-to-generate-my-facebook-conversion-api-key" /> <Card title="Configure Meta Pixel destination" href="/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data" /> <Card title="Attribution mismatch troubleshooting" href="/troubleshooting/attribution-mismatch" /> </CardGroup> # Why is my Meta EMQ Panel Showing Zeros (0.0/10)? Source: https://docs.upstackdata.com/guides/facebook-ads/why-is-my-meta-emq-panel-showing-zeros-0-0-10 Fix Meta EMQ panel zero scores (0.0/10) in Upstack — caused by an access token missing Dataset Quality API permissions. Generate a new token with the right scopes to restore EMQ visibility. # Symptom Your **Meta Event Match Quality (EMQ) panel** inside Upstack Data is showing **0.0/10** across all events (Purchase, Initiate Checkout, View Content, etc.), even though events may still be flowing through to Meta and attribution looks normal. You may also see a notification in Upstack reading something like: <Note> **Meta Pixel destination needs attention. Please check your Meta destination configuration.** </Note> # Why this happens In most cases, a 0.0/10 EMQ score is a **timing issue** — Meta hasn't calculated a score yet. Upstack polls Meta's **Dataset Quality API** hourly to read EMQ scores and display them in the UI, and if Meta has nothing to return, Upstack shows `0.0`. But a persistent 0.0/10 can also indicate a configuration problem — a missing permission on your Meta access token, a pixel ID mismatch, or events not reaching Meta at all. The accordions below cover every cause we see, ordered roughly from most to least common. ## Possible causes <AccordionGroup> <Accordion title="You just connected the destination (most common)"> Meta does not calculate EMQ scores instantly. After you connect your Meta pixel as a destination in Upstack, it takes **24 to 48 hours** for Meta to receive enough events, process them, and generate a score. During this window, EMQ will read 0.0/10 — this is normal and not a sign of a broken configuration. **Fix:** Wait 48 hours after connecting before troubleshooting. If events are visible in [Meta Events Manager](https://business.facebook.com/events_manager) with the "Server" connection label, EMQ will populate on Meta's schedule. </Accordion> <Accordion title="No purchase events have occurred since connecting"> EMQ is calculated per event type, and the Purchase event is the one most people check first. If your store hasn't had any real orders since Upstack was connected, there are no purchase events for Meta to score — so the Purchase EMQ will stay at 0.0/10. **Fix:** Wait for real customer orders to flow through. Test orders and draft orders generally don't trigger the same scoring behavior as real checkouts, so don't rely on them for EMQ evaluation. </Accordion> <Accordion title="Low event volume — Meta hasn't generated a score yet"> Even when events are arriving at Meta, the scoring system needs a minimum volume before it will produce an EMQ reading. New or low-traffic stores can sit at 0.0/10 for longer than 48 hours simply because Meta doesn't have enough data points. **Fix:** If server events are visible in Events Manager but EMQ is still 0.0, continue to let volume build up. Scores typically appear once a handful of events per event type have been processed. </Accordion> <Accordion title="The Pixel ID is misconfigured"> If the Facebook Pixel ID configured in Upstack doesn't match a valid pixel in your Meta Business Manager, events are either rejected or sent to the wrong pixel — and no EMQ score will appear for the pixel you're watching. **Fix:** Verify the pixel ID in both places: 1. In [Meta Events Manager](https://business.facebook.com/events_manager), go to **Data Sources** and confirm the ID of the pixel you expect to receive events. 2. Compare it to the Pixel ID saved on your Upstack Meta destination. 3. If the two don't match, update the ID in Upstack and save the destination. </Accordion> <Accordion title="Events aren't reaching Meta at all"> A 0.0/10 across every event type — with **no server events visible in Events Manager** — usually means events aren't being delivered, not that scoring hasn't happened. Common causes: the destination isn't fully connected, the access token is invalid, or Shopify's native Facebook integration is interfering with Upstack's pipeline. **Fix:** 1. In [Events Manager](https://business.facebook.com/events_manager), open the **Overview** tab and filter for **Server** events. If none are arriving, the issue is upstream of EMQ scoring. 2. Confirm the Upstack Meta destination is saved, active, and not flagged as unhealthy. 3. If Shopify's native Facebook data sharing is enabled, disable it — Upstack handles server-side delivery with stronger identity enrichment, and running both can cause conflicts. </Accordion> <Accordion title="Access token is missing ads_read / ads_management scopes"> This is the most common *configuration* cause (as opposed to a timing cause). Events are flowing and attribution works normally, but Upstack can't read EMQ scores back from Meta because the access token doesn't have the permissions required by the Dataset Quality API. When this happens, the token is **valid and refreshing successfully**, but Meta returns an empty/permission-denied response to the EMQ read call and Upstack stores `0.0` as the last known score. After two consecutive failed hourly pulls, Upstack's destination health manager flags the destination as unhealthy and fires the "needs attention" notification. **Which permissions are required** Per [Meta's Dataset Quality API documentation](https://developers.facebook.com/docs/marketing-api/conversions-api/dataset-quality-api/), the access token used to read EMQ data must include, at minimum: * `ads_read` * Either `ads_management` **or** `business_management` In addition, the **user (or system user) that generated the token** must have the **Partial access → Use events dataset** permission on the pixel/dataset inside Meta Business Manager. Tokens generated with only the basic Conversions API scope (enough to *send* events) will **not** be enough to *read* Dataset Quality metrics. This is especially common on tokens generated a long time ago or generated by a user who no longer has full access to the Business Manager. **Fix: generate a new CAPI token and update the destination** <Steps> <Step title="Generate a new CAPI token in Meta Events Manager"> * Sign in to [Meta Events Manager](https://business.facebook.com/events_manager) at `business.facebook.com/events_manager`. * In the **Data Sources** panel, select the **pixel/dataset** that is showing zeros in Upstack. * Click **Settings** in the left-hand menu inside the pixel. * Scroll to the **Conversions API** section. * Click **Generate access token**. * Copy the token immediately — Meta only shows it once. The token starts with `EAA` and is approximately 190 characters long. <Warning> The user generating the token **must be an admin** (or have full access) on the Meta Business Manager that owns the pixel. If the token is generated by a user with only partial or assigned access, it may still be missing the `ads_read` / `ads_management` scopes and the EMQ panel will continue to read zero. </Warning> </Step> <Step title="Update the CAPI token in the Upstack dashboard"> * Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com/pixel/event-destinations). * Navigate to **Event Destinations** and open your **Meta** destination. * Paste the new token into the **Conversions API token** field, replacing the existing value. * Leave the **Pixel ID** unchanged (15–16 digit number, no prefix). * Click **Update Configuration**. </Step> <Step title="Wait for the next hourly pull and verify"> Upstack queries Meta's Dataset Quality API **once per hour**. After saving the new token, your EMQ scores should populate on the next scheduled pull (within 1–2 hours). After 1–2 hours, in the Upstack dashboard: * The **EMQ panel** should display non-zero scores (typically 6.0–10.0/10). * The Meta destination card should show **Healthy** with a green status indicator. * The **"Meta Pixel destination needs attention"** notification should clear. If the scores are still 0.0/10 after 2 hours, contact support so we can trigger a manual refresh and verify the token permissions. </Step> </Steps> </Accordion> </AccordionGroup> # How to confirm the fix worked * The EMQ panel inside Upstack should now show **non-zero scores** (typically 6.0–10.0/10 depending on the richness of your event data) * The **"Meta Pixel destination needs attention"** notification should clear * The destination health indicator should return to **healthy/green** # Related Articles [How to find my Upstack Data Pixel ID?](/resources/how-to-find-my-upstack-data-pixel-id) <Note> **Still seeing zeros?** If you've generated a new token from an admin account and the EMQ panel is still reading 0.0/10 after a couple of hours, contact our support team. The most common edge cases are: (1) the token was generated by a user without full Business Manager access, (2) the pixel is owned by a different Business Manager than the one the token is scoped to, or (3) your app doesn't have the Dataset Quality API feature enabled. We can diagnose all of these quickly. </Note> # Complete Upstack Data Onboarding Guide Source: https://docs.upstackdata.com/guides/getting-started/complete-upstack-data-onboarding-guide Complete onboarding guide — install Upstack Data on Shopify, set up your pixel, connect ad and email platforms, and configure data integrations for accurate tracking and attribution. ## Prerequisites Before you start, make sure you have: * An active Shopify store (`your-store.myshopify.com`) and [Shopify Admin](https://admin.shopify.com) access with permission to install apps and edit themes. * Admin access to every ad platform you'll connect (Meta, Google Ads, TikTok, Snapchat, Pinterest). * Admin access to your email/CRM platform (Klaviyo, Omnisend) if you plan to enrich those flows. * A valid payment method on the Shopify account that will install Upstack Data — [see plans and pricing](/billing/plans-and-pricing). * Access to the email inbox you'll use for your [Upstack Data](https://app.upstackdata.com) account (a verification code is sent during sign-up). ## Part 1: Install and set up Upstack Data in Shopify In this step, you will install the Upstack Data app from the Shopify App Store and complete the initial setup. This connects your Shopify store to Upstack Data, enabling pixel tracking, event collection, and data integration needed for accurate reporting and attribution. Help guide to complete this step: [Complete How-To Guide for Setting Up the Upstack Data App in Shopify](/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify) ## Part 2: Connect ad platforms In this step, you will connect your ad platforms (Meta, Google Ads, Snapchat, Pinterest, and TikTok) as destinations in [Upstack Data](https://app.upstackdata.com). This enables syncing of performance data and sending server-side conversion events for more accurate tracking and attribution. ### 2.1. Facebook (Meta) Ads [Complete How-To Guide for Onboarding Facebook (Meta) in Upstack Data](/guides/facebook-ads/complete-how-to-guide-for-onboarding-facebook-meta-in-upstack-data) ### 2.2. Google Ads [Complete How-To Guide for Onboarding Google Ads in Upstack Data](/guides/google-ads/complete-how-to-guide-for-onboarding-google-ads-in-upstack-data) ### 2.3. Snapchat Ads [Complete How-To Guide for Onboarding Snapchat in Upstack Data](/guides/snapchat-ads/complete-how-to-guide-for-onboarding-snapchat-in-upstack-data) ### 2.4. Pinterest Ads [Complete How-To Guide for Onboarding Pinterest in Upstack Data](/guides/pinterest-ads/complete-how-to-guide-for-onboarding-pinterest-in-upstack-data) ### 2.5. Tiktok Ads [Complete How-To Guide for Onboarding TikTok Ads in Upstack Data](/guides/tiktok-ads/complete-how-to-guide-for-onboarding-tiktok-ads-in-upstack-data) ## Part 3: Connect email & CRM platforms In this step, you'll connect your email and CRM platforms (such as Klaviyo and Omnisend) to [Upstack Data](https://app.upstackdata.com). This syncs customer data and events, enabling enriched reporting and more effective marketing automation. ### 3.1. Klaviyo #### 3.1.1. Klaviyo Integration Setup [Complete How-To Guide for Onboarding Klaviyo in Upstack Data](/guides/klaviyo/complete-how-to-guide-for-onboarding-klaviyo-in-upstack-data) #### 3.1.2. Upstack Abandonment Flows Setup [Complete Guide to Setting Up Upstack Abandonment Flows in Klaviyo](/guides/klaviyo-abandonment-flows/complete-guide-to-setting-up-upstack-abandonment-flows-in-klaviyo) ### 3.2 Omnisend [Complete How-To Guide for Onboarding Omnisend in Upstack Data](/guides/omnisend/complete-how-to-guide-for-onboarding-omnisend-in-upstack-data) ## Part 4: Data Integrations setup In this step, you'll configure Data Integrations in the [Upstack dashboard](https://app.upstackdata.com/pixel/integrations) to unify tracking across platforms. This ensures accurate event collection, consistent attribution, and reliable reporting. ### 4.1. Facebook (Meta) Ads [How to Connect your Facebook Ads Account in Upstack Data Integrations](/guides/facebook-ads/how-to-connect-your-facebook-ads-account-in-upstack-data-integrations) ### 4.2. Google Ads [How to Connect your Google Ads Account in Upstack Data Integrations](/guides/integrations/how-to-connect-your-google-ads-account-in-upstack-data-integrations) ## Part 5: Verify the install After completing the previous parts, confirm everything is wired up correctly before scaling spend: * In [Shopify Admin → Settings → Customer events](https://admin.shopify.com), confirm the **UpstackData** Custom Pixel is **Connected**. * In [Shopify Admin → Online Store → Themes → Customize → App embeds](https://admin.shopify.com), confirm **UpStackified Pixel** is enabled on your live theme. * In the [Upstack dashboard](https://app.upstackdata.com), open **Event Health** and confirm `PageView`, `AddToCart`, `InitiateCheckout`, and `Purchase` events are arriving. * On the [Data Integrations](https://app.upstackdata.com/pixel/integrations) page, confirm every connected destination shows status **Healthy**. * In each destination platform's event manager (e.g., [Meta Events Manager](https://business.facebook.com/events_manager), Google Ads conversions), confirm events are arriving via the server-side / CAPI channel. <Note> **Need help?** If you encounter any issues during setup, contact our support team and we'll help diagnose the problem. </Note> ## What's next <CardGroup> <Card title="Explore analytics" icon="chart-line" href="/analytics/query-guide"> Build custom reports with the analytics dashboard and query builder. </Card> <Card title="Use the CLI" icon="terminal" href="/cli/install"> Query data and automate workflows from the command line. </Card> <Card title="Troubleshoot issues" icon="wrench" href="/troubleshooting/pixel-stuck-on-waiting-for-first-events"> Common fixes if events aren't appearing after setup. </Card> <Card title="Manage billing" icon="credit-card" href="/billing/subscriptions-and-billing"> View invoices, upgrade plans, and manage your subscription. </Card> </CardGroup> # How to get the most out of Upstack Data: a complete guide Source: https://docs.upstackdata.com/guides/getting-started/get-the-most-out-of-upstack-data A complete guide to setting up Upstack Data: connecting destinations, configuring sources, improving event match quality, and using attribution insights. Upstack Data gives Shopify brands three capabilities in one platform: server-side event tracking, multi-touch attribution, and Klaviyo data enrichment. This guide walks you through everything you need to do after installation to get the most value from the platform — from connecting your ad accounts to understanding your attribution dashboard. ## Prerequisites * The Upstack Data app installed in your [Shopify Admin](https://admin.shopify.com) (see [Install on Shopify](/get-started/install-on-shopify)) * An [Upstack Data](https://app.upstackdata.com) account with subscription active * Admin access to each destination you'll connect (Meta, Google Ads, TikTok, Klaviyo, etc.) * Admin access to each source you'll connect for reporting (Shopify, Meta, Google Ads, TikTok) ## Upstack's three products <CardGroup> <Card title="Signal — server-side tracking" icon="satellite-dish"> Sends Shopify events (page views, add-to-carts, checkouts, purchases) to ad platforms via server-side APIs (Meta CAPI, Google Ads, TikTok Events API). Each event is enriched with identity data before delivery for higher match rates and better optimization signal. </Card> <Card title="Analytics — attribution and reporting" icon="chart-line"> Pulls spend data from your ad platforms and combines it with Shopify revenue data to show which channels, campaigns, and ads are driving results. Gives you a unified view that doesn't rely solely on any single ad platform's self-reported numbers. </Card> <Card title="Flows — marketing automation enrichment" icon="envelope"> Sends enriched event data to Klaviyo and Omnisend, giving your abandonment flows and segments more complete customer profiles. Abandoned cart emails, browse abandonment, and win-back campaigns trigger more often and personalize better. </Card> </CardGroup> ## First 48 hours after installation Your first two days are about getting data flowing. Here's what to prioritize: <Steps> <Step title="Day 1 — Connect your primary destinations"> 1. **Connect [Meta CAPI](/destinations/meta-capi).** This is typically the highest-priority destination. You'll need your Pixel ID and ad account access. See [Connect a destination](/get-started/connect-a-destination). 2. **Connect [Google Ads](/destinations/google-ads).** Enter your conversion action ID and connect your Google Ads account. 3. **Connect any additional destinations** ([TikTok](/destinations/tiktok), [Pinterest](/destinations/pinterest), [Klaviyo](/destinations/klaviyo), [Snapchat](/destinations/snapchat), [Omnisend](/destinations/omnisend)) you actively advertise on. </Step> <Step title="Day 1–2 — Connect your sources"> 1. **Connect [Shopify](/sources/shopify)** (typically done automatically during [app installation](/get-started/install-on-shopify)). 2. **Connect ad platform spend data** for [Meta](/sources/facebook-ads), [Google](/sources/google-ads), and [TikTok](/sources/tiktok) so your attribution dashboard has complete spend data. </Step> <Step title="Day 2 — Verify data is flowing"> 1. Open [Meta Events Manager](https://business.facebook.com/events_manager) and confirm events are arriving from Upstack via the **Conversions API** channel. 2. Open the [Upstack dashboard](https://app.upstackdata.com) and confirm event activity under **Event Health**. 3. **Don't panic if EMQ shows 0.0** — Meta takes 24–48 hours to calculate Event Match Quality scores. See [Why is my Meta EMQ panel showing zeros?](/guides/facebook-ads/why-is-my-meta-emq-panel-showing-zeros-0-0-10). </Step> </Steps> <Tip> Don't forget to [disable existing tracking](/get-started/disable-existing-tracking) (Shopify's native Facebook/Google data sharing) once Upstack is sending server-side events. Leaving both enabled can cause duplicate events and less accurate optimization. </Tip> ## Setting up all destinations Destinations are the platforms Upstack sends event data to. Set up every platform you actively advertise on or use for marketing automation. | Destination | What Upstack sends | Priority | | -------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------- | | [Meta CAPI](/destinations/meta-capi) | Purchase, Add to Cart, View Content, Initiate Checkout, custom events via CAPI | High | | [Google Ads](/destinations/google-ads) | Purchase and conversion events via offline conversions | High | | [TikTok](/destinations/tiktok) | Purchase and funnel events via Events API | Medium | | [Klaviyo](/destinations/klaviyo) | Browse, cart, and purchase events for flow triggering | Medium–High | | [Pinterest](/destinations/pinterest) | Conversion events via Conversions API | Medium | | [Snapchat](/destinations/snapchat) | Conversion events via Conversions API | Lower | | [Omnisend](/destinations/omnisend) | Browse, cart, and purchase events for flow triggering | Medium (if you use Omnisend) | | [Webhooks](/destinations/webhooks) | Any configured event to a custom HTTP endpoint | As needed | For the full list and configuration options, see the [destinations overview](/destinations/overview). ## Setting up sources for reporting Sources feed your attribution dashboard. Without them, Analytics can show your Shopify revenue but can't calculate ROAS or compare channel performance. | Source | What it provides | | -------------------------------------------- | ---------------------------------------------------------- | | [Shopify](/sources/shopify) | Order data, revenue, product details, customer information | | [Meta (Facebook Ads)](/sources/facebook-ads) | Ad spend, campaign structure, impressions, clicks | | [Google Ads](/sources/google-ads) | Ad spend, campaign structure, impressions, clicks | | [TikTok](/sources/tiktok) | Ad spend, campaign structure, impressions, clicks | Connect every platform where you're spending ad budget so your attribution dashboard has complete data. See the [sources overview](/sources/overview). ## Understanding your attribution dashboard Once destinations and sources are connected, your Analytics dashboard will begin populating with attribution data. Here's how to read it: * **Revenue data** comes from Shopify orders and is attributed to channels based on Upstack's attribution model. * **Spend data** comes from your connected ad platform sources. * **ROAS (Return on Ad Spend)** is calculated by dividing attributed revenue by ad spend for each channel. * **Attribution windows** determine how far back Upstack looks to credit a touchpoint. The default window is typically 7 days for clicks and 1 day for views, configurable by plan. See [Attribution and reporting](/concepts/attribution-and-reporting) for a full walkthrough. ## Configuring costs for accurate P\&L For your attribution dashboard to show accurate profitability, it needs your complete cost picture: 1. **Ad spend** is pulled automatically from connected sources (Meta, Google, TikTok). 2. **Product costs (COGS)** may need to be configured depending on your plan. See [Configure contribution margin](/get-started/configure-contribution-margin). 3. **Shipping and handling costs** may be available through Shopify order data. ## Optimizing Klaviyo flows with Upstack Flows If you use Klaviyo for email and SMS, [Upstack Flows](/destinations/klaviyo) can significantly improve your flow performance: <Steps> <Step title="Connect Klaviyo as a destination"> Use your Klaviyo API key. See the [Klaviyo destination guide](/destinations/klaviyo). </Step> <Step title="Confirm enriched events are flowing"> Browse and cart events flow to Klaviyo with more complete customer profiles, meaning your abandonment flows trigger for more visitors — not just those already identified by Klaviyo's on-site tracking. </Step> <Step title="Review your flow triggers"> Ensure your abandoned cart, browse abandonment, and other flows are set up to use the events coming from Upstack. </Step> <Step title="Monitor flow performance"> After connecting, you should see an increase in flow recipients and improved conversion rates from those flows. </Step> </Steps> ## Monitoring EMQ and pixel health Event Match Quality (EMQ) is Meta's 0–10 score measuring how well your event data matches to real Facebook users. Upstack's identity enrichment is designed to improve your EMQ compared to browser-only tracking. <Info> **EMQ benchmarks** * **7.0+** is considered good. * **9.0+** is excellent and indicates strong identity matching. * **Below 5.0** suggests missing identity parameters or configuration issues. </Info> ### How to check 1. View your EMQ score in the [Upstack dashboard](https://app.upstackdata.com) under **Event Health**. 2. Cross-reference in [Meta Events Manager](https://business.facebook.com/events_manager) under your pixel's event details. 3. If EMQ is lower than expected, verify all identity parameters are being sent (email, phone, name, address data). For troubleshooting, see [Why is my Meta EMQ panel showing zeros?](/guides/facebook-ads/why-is-my-meta-emq-panel-showing-zeros-0-0-10). ## Custom events for advanced optimization Once your standard tracking is running, consider adding [custom events](/guides/custom-events/how-to-create-custom-event-triggers) to improve ad platform optimization: * **`nc_purchase` (new customer purchase)** — lets Meta and Google optimize for acquiring new buyers specifically. This is the most popular and impactful custom event for most brands. * **Category-specific purchases** — optimize for purchases in specific product categories. * **Quiz or form completions** — give ad platforms mid-funnel signals. ## When to contact support vs. self-serve <AccordionGroup> <Accordion title="Self-serve tasks"> * Adding or removing destinations * Connecting new sources * Viewing attribution reports * Checking EMQ scores * Creating custom events </Accordion> <Accordion title="Contact Upstack support"> * EMQ remains at 0.0 after 48+ hours with confirmed purchases * Events are not appearing in your ad platform's event manager after 24 hours * Discrepancies between Upstack attribution and Shopify revenue * Questions about which attribution model is right for your business * Issues with Shopify app permissions or installation * Billing or plan questions </Accordion> </AccordionGroup> ## Frequently asked questions <AccordionGroup> <Accordion title="How long does it take to see data after connecting Upstack?"> Events begin flowing to destinations within minutes of connecting. Attribution data in the Analytics dashboard depends on having both event data and spend data connected, and may take 24–48 hours to fully populate. EMQ scores from Meta take 24–48 hours to calculate. </Accordion> <Accordion title="Do I need to disable my existing Facebook pixel?"> No. Upstack's server-side tracking works alongside your existing browser-side pixel. However, you should [disable Facebook's built-in data sharing](/get-started/disable-existing-tracking) within Shopify's settings, as Upstack replaces that functionality with better-enriched server-side events. </Accordion> <Accordion title="Which destination should I connect first?"> Connect the platform where you spend the most ad budget first. For most Shopify brands, this is Meta. Getting high-quality data flowing to your largest spend platform produces the biggest impact on ad performance. </Accordion> <Accordion title="Can I use Upstack with agencies managing my ads?"> Yes. Share your Upstack dashboard access with your agency so they can see attribution data. Your agency will also see improved event data quality in the ad platforms they manage, which benefits their optimization. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Install on Shopify" icon="shopify" href="/get-started/install-on-shopify"> Get the Upstack app installed and configured in your store. </Card> <Card title="Connect a destination" icon="plug" href="/get-started/connect-a-destination"> Step-by-step setup for your first destination. </Card> <Card title="Disable existing tracking" icon="ban" href="/get-started/disable-existing-tracking"> Turn off Shopify's built-in pixel sharing to avoid duplicate events. </Card> <Card title="Custom events" icon="code" href="/guides/custom-events/how-to-create-custom-event-triggers"> Add custom events like `nc_purchase` for advanced optimization. </Card> <Card title="Destinations overview" icon="arrow-right-from-bracket" href="/destinations/overview"> Every supported destination. </Card> <Card title="Sources overview" icon="arrow-right-to-bracket" href="/sources/overview"> Every supported source. </Card> <Card title="Why is my Meta EMQ showing zeros?" icon="circle-question" href="/guides/facebook-ads/why-is-my-meta-emq-panel-showing-zeros-0-0-10"> Troubleshoot EMQ scores stuck at 0.0. </Card> </CardGroup> # Complete How-To Guide for Onboarding Google Ads in Upstack Data Source: https://docs.upstackdata.com/guides/google-ads/complete-how-to-guide-for-onboarding-google-ads-in-upstack-data Onboard Google Ads in Upstack Data — create a purchase goal with Enhanced Conversions, connect your account, and forward server-side conversions for accurate Smart Bidding signal. <Info> **New to Upstack?** Follow the [getting started guide](/get-started/install-on-shopify) for a streamlined onboarding walkthrough. </Info> <Tip> **Quick Summary** * Create a new Purchase conversion goal named **"Purchase - UpstackData"** in [Google Ads](https://ads.google.com). * Configure the goal with a **30-day click-through window and Enhanced Conversions enabled**. * Set up the Google Ads destination in the Upstack dashboard with your **Conversion ID and Conversion Label**. * Switch the goal to **Primary optimization** after 4–7 days. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * **Admin** or **Manager** access to a **Google Ads** account * Permission to create or edit **conversion actions** in Google Ads <Steps> <Step title="Create a New Purchase Conversion Goal"> Help guide to complete this step: [How to Create a New Upstack Data Purchase Goal in Google Ads →](/guides/google-ads/how-to-create-a-new-upstack-data-purchase-goal-in-google-ads) </Step> <Step title="Create and Configure Google Ads Pixel Destination in Upstack Data"> Help guide to complete this step: [How to Configure Google Ads Pixel Destination in Upstack Data →](/guides/google-ads/how-to-configure-google-ads-destination-in-upstack-data) Where to find your Google Conversion ID and Label: [How to Get Your Google Ads Conversion ID and Label →](/guides/google-ads/how-to-get-your-google-ads-conversion-id-and-label) </Step> <Step title="Enable the Google Ads Upstack Purchase Goal and Switch to Primary Optimization Goal"> <Note> When creating a new Purchase Goal in Google Ads (Purchase - Upstack Data), we initially will set this as the secondary goal, for observation only. We advise to make this goal Primary after 4-7 days to allow the Goal to become active. All other Purchase goals are then set to secondary when Upstack becomes **Primary.** </Note> Help guide to complete this step: [How to Enable the Google Ads Upstack Purchase Goal and Switch to Primary Optimization Goal →](/guides/google-ads/how-to-enable-the-google-ads-upstack-purchase-goal-and-switch-to-primary-optimization-goal) </Step> </Steps> <Tip> **Optional: enable server-side forwarding.** For maximum coverage, also turn on the Google Ads Conversions API so Upstack forwards events server-side even when the browser pixel is blocked. See [How to Set Up Google Ads Server-Side Conversions API in Upstack Data →](/guides/google-ads/how-to-set-up-google-ads-server-side-conversions-api-in-upstack-data). </Tip> ## Verify the Setup After completing all three steps: * In the Upstack dashboard, navigate to **Events Destination** at [app.upstackdata.com/pixel/event-destinations](https://app.upstackdata.com/pixel/event-destinations) and confirm the Google Ads destination shows as **Healthy**. * In Google Ads, go to **Goals → Conversions → Summary** and confirm **"Purchase - UpstackData"** is listed and (after 4–7 days) marked **Primary**. * Place a test order on your store and check that the conversion appears in Google Ads within 24–48 hours. <Note> **Need help?** If you encounter any issues during setup or don't see expected improvements after 10 days, contact our support team with your Google Ads **Conversion ID** and **Conversion Label** and we'll help diagnose the problem. </Note> # How to Configure Google Ads Destination in Upstack Data Source: https://docs.upstackdata.com/guides/google-ads/how-to-configure-google-ads-destination-in-upstack-data Configure the Google Ads destination in Upstack Data with your Conversion ID and Conversion Label to forward server-side purchases with Enhanced Conversions match keys. <Tip> **Quick Summary** * In the Upstack dashboard, click **"+ New Destination"** and select Google Ads. * In Google Ads, find your conversion under **Goals → Conversions → Summary**. * Open **Tag Setup** to reveal your **Conversion ID** and **Conversion Label**. * Paste both values into the Upstack dashboard and **Create Configuration**. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * **Admin** or **Manager** access to a **Google Ads** account * An existing **Purchase conversion action** in Google Ads (or follow [How to Create a New Upstack Data Purchase Goal in Google Ads](/guides/google-ads/how-to-create-a-new-upstack-data-purchase-goal-in-google-ads) first) ## Configuration Steps <Steps> <Step title="Sign in to Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com). </Step> <Step title="Add a new Google Ads destination"> * In the Upstack dashboard, navigate to **Events Destination** ([app.upstackdata.com/pixel/event-destinations](https://app.upstackdata.com/pixel/event-destinations)) * Click **"+ New Destination"** in the top-right corner of the page <img alt="Add New Destination" /> * In the **Select a Destination** popup, click **"Google Ads"** * Click **Next** <img alt="Select Google Ads destinations" /> </Step> <Step title="Find your conversion in Google Ads"> * In a new tab, sign in to [Google Ads](https://ads.google.com) * In the left-hand menu, navigate to **Goals → Conversions → Summary** <img alt="Google Ads menu with Goals and Conversions Summary options" /> *`Google Ads Conversions Summary Page`* Find your primary Purchase conversion (usually named **"Purchase - UpstackData"**) and click to open it. <img alt="Primary Purchase conversion event in Google Ads Conversions list" /> *`Example Primary Conversion Event`* <Note> **Note:** Your conversion may be named differently. Look for the primary event linked to your purchase conversion. </Note> </Step> <Step title="Open Tag Setup to reveal your IDs"> On the conversion detail page, scroll down to the **Tag Setup** section and click **"Use Google Tag Manager"**. <Note> For a step-by-step walkthrough, see [How to Get Your Google Ads Conversion ID and Label →](/guides/google-ads/how-to-get-your-google-ads-conversion-id-and-label). </Note> <img alt="Tag Setup section with Use Google Tag Manager option" /> Google Ads displays your **Conversion ID** and **Conversion Label**. * **Conversion ID** — starts with `AW-` followed by 9–10 digits (e.g., `AW-123456789`) * **Conversion Label** — 11-character alphanumeric string (e.g., `ABc1d2EFG3h`) <img alt="Google Tag Manager showing Conversion ID and Conversion Label values" /> </Step> <Step title="Enter your Conversion ID and Conversion Label"> Back in the Upstack dashboard: * In the **Conversion ID** field, paste your full Conversion ID from Google Ads (e.g., `AW-123456789`). The `AW-` prefix is required. * In the **Conversion Label** field, paste your Conversion Label from Google Ads (e.g., `ABc1d2EFG3h`). <img alt="Upstack Google Ads destination form with Conversion ID and Label fields" /> </Step> <Step title="Create the configuration"> Click the **Create Configuration** button to save the setup. <img alt="Create Configuration button to save Google Ads destination" /> <Note> **Success! 🎉** You should see a confirmation message and the Google Ads destination will appear as **"Healthy"** in your destinations list. </Note> <img alt="Google Ads destination showing Healthy status in destinations list" /> </Step> </Steps> ## Verify the Setup To confirm the destination is working: * In the Upstack dashboard, the Google Ads destination should show **Healthy** status under **Events Destination**. * Place a test order on your store and check Google Ads **Goals → Conversions → Summary** within 24–48 hours to confirm the conversion is recorded. If the destination shows **Unhealthy** or no conversions arrive, double-check that: * The **Conversion ID** starts with `AW-` and matches the value shown in Google Ads. * The **Conversion Label** was copied without leading or trailing spaces. * The conversion action in Google Ads is enabled and not paused. If issues persist, contact Upstack Data support with your **Conversion ID** and **Conversion Label**. # How to Create a New Upstack Data Purchase Goal in Google Ads Source: https://docs.upstackdata.com/guides/google-ads/how-to-create-a-new-upstack-data-purchase-goal-in-google-ads Create an Upstack Data purchase conversion goal in Google Ads with Enhanced Conversions enabled — required for server-side conversion forwarding from Upstack to Google. <Tip> **Quick Summary** * In Google Ads, navigate to **Goals → Conversions → Summary** and click **"+ Create conversion action"**. * Select **Conversions on a website**. * Choose **Purchase** as the goal type and select **Set up manually using a code**. * Name the conversion **"Purchase - UpstackData"**, set **Click-through conversion window** to **30 days**, and enable **Enhanced Conversions**. * **Save** to generate your Conversion ID and Conversion Label. </Tip> ## Prerequisites Before you start, you need: * **Admin** or **Manager** access to a **Google Ads** account * Permission to create conversion actions in Google Ads ## Step-by-Step Instructions <Steps> <Step title="Sign in to Google Ads"> Sign in to [Google Ads](https://ads.google.com). </Step> <Step title="Open the Conversions summary"> In the left-hand menu, navigate to **Goals → Conversions → Summary**. <img alt="Google Ads left menu with Goals, Conversions, and Summary navigation" /> </Step> <Step title="Create a new conversion action"> * Click the **"+ Create conversion action"** button * Select **"Conversions on a website"** by ticking the checkbox on the right side of the panel * Click **Save and continue** <img alt="Create conversion action button in Conversions Summary" /> <img alt="Select Conversions on a website option with checkbox" /> </Step> <Step title="Configure the Purchase goal"> * Select **"Purchase"** as the goal/conversion action * In the **"Choose an event to measure Purchase"** panel, under **"Create a new conversion action"**, select **"Set up manually using a code"** * Click **"Conversion settings"** to expand the section * Set the **Conversion name** to **"Purchase - UpstackData"** * Set **Click-through conversion window** to **30 days** <img alt="Set up manually using a code option with Purchase goal selected" /> `Example - select **Set up manually using a code** and **Purchase** as the Goal/Conversion action` <img alt="Conversion name field with Purchase UpstackData and 30 day window" /> `Example - Conversion name: **Purchase - UpstackData** and Click-through conversion window: **30 days**` </Step> <Step title="Enable Enhanced Conversions"> Check the **"Use enhanced conversion for conversion action"** option to enable **Enhanced Conversions**. Click **Done** to save the changes and close the panel. <img alt="Enhanced Conversions checkbox enabled for conversion action" /> <Note> **Note:** Enhanced Conversions improves match rates by using first-party customer data securely. </Note> </Step> <Step title="Save the configuration"> Click **Save and Continue** to complete the setup. <img alt="Save and Continue button to complete conversion setup" /> <Note> *If your Google Ads interface looks different, see:* \*\*[How to Create a Purchase Goal in Google Ads Using the Google Ads Tag (For Different Interface) →](/guides/google-ads/how-to-create-a-purchase-goal-in-google-ads-using-the-google-ads-tag-for-different-interface)\*\* </Note> </Step> </Steps> ## What You'll Receive After saving, Google Ads displays: * **Conversion ID** — starts with `AW-` followed by 9–10 digits (e.g., `AW-123456789`) * **Conversion Label** — 11-character alphanumeric string (e.g., `ABc1d2EFG3h`) Use these values in your Upstack Data destination configuration. ## Verify the Setup To confirm the goal was created correctly: * Return to **Goals → Conversions → Summary** in Google Ads — the new **"Purchase - UpstackData"** conversion should appear in the list with a status of **Inactive** (it will become **Active** once it receives data). * Confirm the **Click-through conversion window** is **30 days** and **Enhanced Conversions** is enabled on the conversion's detail page. If the conversion is missing, refresh the page and check that you saved the action. If issues persist, contact Upstack Data support. # How to Enable the Google Ads Upstack Purchase Goal and Switch to Primary Optimization Goal Source: https://docs.upstackdata.com/guides/google-ads/how-to-enable-the-google-ads-upstack-purchase-goal-and-switch-to-primary-optimization-goal Promote the Upstack Data purchase goal from secondary to primary in Google Ads after 4–7 days of data — switching optimization to server-side conversions for better Smart Bidding performance. <Tip> **Quick Summary** * Wait 4–7 days after creating the **"Purchase - UpstackData"** goal so Google can collect baseline data. * In Google Ads, navigate to **Goals → Summary** and click **Edit goals**. * Open the **Conversion action optimization** section. * Set **"Purchase - UpstackData"** as **Primary** and switch all other Purchase goals to **Secondary**. * Click **Save**. </Tip> ## Prerequisites Before you start, you need: * **Admin** or **Manager** access to the **Google Ads** account * The **"Purchase - UpstackData"** conversion already created and live for **4–7 days** (see [How to Create a New Upstack Data Purchase Goal in Google Ads →](/guides/google-ads/how-to-create-a-new-upstack-data-purchase-goal-in-google-ads)) ## Importance of this Step <Note> When creating the **"Purchase - UpstackData"** goal in Google Ads, we initially set it as **Secondary** for observation only. This allows Google to collect baseline data without disrupting current optimization. After 4–7 days, switching to **Primary** activates the goal as the optimization target with sufficient data. </Note> ## Steps to Switch Your Purchase Goal <Steps> <Step title="Sign in to Google Ads"> Sign in to [Google Ads](https://ads.google.com). </Step> <Step title="Open the Goals summary"> In the left-hand menu, navigate to **Goals → Summary**. <img alt="Google Ads left menu with Goals and Summary navigation selected" /> </Step> <Step title="Find the Purchase conversions list"> On the Goals Summary page, scroll down to the **Purchase** conversion list. <img alt="Google Ads Goals Summary page showing Purchase conversion list" /> </Step> <Step title="Open the goal settings"> Click **Edit goals** to open the goal settings panel. <img alt="Edit goals button in Google Ads conversion settings" /> </Step> <Step title="Expand Conversion action optimization"> Click **"Conversion action optimization"** to expand the section. <img alt="Conversion action optimization section expanded in goal settings" /> </Step> <Step title="Set Purchase - UpstackData as Primary"> Set **"Purchase - UpstackData"** as **Primary**. <img alt="Purchase UpstackData goal set as Primary conversion action" /> </Step> <Step title="Set other Purchase goals to Secondary"> Set all other Purchase goals to **Secondary**. <Warning> Ensure only **one Primary** Purchase conversion goal is active at a time. </Warning> <img alt="Other Purchase goals switched to Secondary status" /> <img alt="Goal list showing Purchase UpstackData as Primary with others as Secondary" /> `Example: Purchase - UpstackData is Primary and other Purchase conversions are Secondary` </Step> <Step title="Save the changes"> Click **Save** to apply the new settings. <img alt="Save button to apply goal optimization changes in Google Ads" /> </Step> </Steps> ## Verify the Setup To confirm the switch was applied: * Return to **Goals → Summary** in Google Ads — **"Purchase - UpstackData"** should be labelled **Primary** and all other Purchase goals should be labelled **Secondary**. * Open one of your active Search or Performance Max campaigns and confirm it is optimizing against the new Primary goal. If the goal still appears as Secondary, refresh the page and re-open **Edit goals** to confirm the change saved. If issues persist, contact Upstack Data support. # How to Get Your Google Ads Conversion ID and Label Source: https://docs.upstackdata.com/guides/google-ads/how-to-get-your-google-ads-conversion-id-and-label Find your Google Ads Conversion ID and Conversion Label from an existing purchase conversion — both required to configure the Upstack Data Google Ads destination. <Tip> **Quick Summary** * In Google Ads, navigate to **Goals → Conversions → Summary**. * Click your **Purchase conversion** to open its detail page. * Scroll to **Tag Setup** and click **"Use Google Tag Manager"**. * Copy the **Conversion ID** (`AW-` followed by 9–10 digits) and the **Conversion Label** (11-character alphanumeric string). </Tip> ## Prerequisites Before you start, you need: * **Admin** or **Manager** access to a **Google Ads** account * An existing Purchase conversion action (e.g., **"Purchase - UpstackData"**). If you haven't created one yet, see [How to Create a New Upstack Data Purchase Goal in Google Ads →](/guides/google-ads/how-to-create-a-new-upstack-data-purchase-goal-in-google-ads). ## Steps to Find Your Conversion ID and Label <Steps> <Step title="Sign in to Google Ads"> Sign in to [Google Ads](https://ads.google.com). </Step> <Step title="Open the Conversions summary"> In the left-hand menu, navigate to **Goals → Conversions → Summary**. <img alt="Google Ads left menu with Goals, Conversions, and Summary options" /> </Step> <Step title="Open your Purchase conversion"> Find and click your **"Purchase - UpstackData"** conversion (or your existing purchase conversion). <img alt="Purchase UpstackData conversion in Conversions Summary list" /> </Step> <Step title="Scroll to Tag Setup"> On the conversion detail page, scroll down to the **Tag Setup** section. <img alt="Tag Setup section" /> </Step> <Step title="Click Use Google Tag Manager"> Click **"Use Google Tag Manager"**. <img alt="Use Google Tag Manager button in Tag Setup section" /> `Use Google Tag Manager button` </Step> <Step title="Copy your Conversion ID and Conversion Label"> Google Ads displays: * **Conversion ID** — starts with `AW-` followed by 9–10 digits (e.g., `AW-123456789`) * **Conversion Label** — 11-character alphanumeric string (e.g., `ABc1d2EFG3h`) <img alt="Conversion ID and Conversion Label values displayed in GTM setup" /> Copy both values, then paste them into your Google Ads destination in the Upstack dashboard ([app.upstackdata.com/pixel/event-destinations](https://app.upstackdata.com/pixel/event-destinations)). Click **Create Configuration** in the Upstack dashboard to save the setup. <img alt="Upstack Google Ads destination form with ID and Label fields filled" /> </Step> </Steps> ## Verify the Setup To confirm you copied the correct values: * The **Conversion ID** should match the format `AW-` + 9–10 digits. * The **Conversion Label** should be exactly 11 characters (letters and digits, no spaces). * After saving in the Upstack dashboard, the Google Ads destination should appear as **Healthy** under **Events Destination**. If the destination shows **Unhealthy**, re-open the **Tag Setup** in Google Ads to confirm both values were copied without leading or trailing spaces. If issues persist, contact Upstack Data support. # How to Set Up Google Ads Server-Side Conversions API in Upstack Data Source: https://docs.upstackdata.com/guides/google-ads/how-to-set-up-google-ads-server-side-conversions-api-in-upstack-data Connect Google Ads with OAuth and map your tracked events to conversion actions so Upstack forwards purchases server-side via the Google Ads Conversions API — independent of the browser pixel. <Tip> **Quick Summary** * Open your Google Ads destination in Upstack and turn on **Enable Conversion API**. * Click **Connect Google Ads** and grant Upstack offline access during the Google consent screen. * Select the **Google Ads account** you want to forward conversions to. * In **Event Conversion Mappings**, link each tracked event to a conversion action — use **Create & Link** to create dedicated Upstack conversion actions automatically. * Save the configuration and confirm the destination shows **Healthy**. </Tip> ## What the Conversions API path adds The browser pixel (Conversion ID and Conversion Label) tracks your **primary** conversion from the visitor's browser. The server-side **Conversions API** runs alongside it: Upstack sends each tracked event directly to Google Ads server-to-server, attached to its own dedicated conversion action. Server-side delivery reaches Google even when the browser pixel is blocked by ad blockers, ITP, or cookie restrictions, and it carries the original click identifier (`gclid`, `gbraid`, or `wbraid`) plus SHA-256 hashed customer data for Enhanced Conversions match-rate uplift. <Note> The Conversions API and the browser pixel run **independently and in parallel**. Enabling server-side forwarding does not change or disable your pixel — the pixel keeps tracking your primary conversion using the **Conversion ID** on the destination. </Note> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * An existing **Google Ads destination** in Upstack with the **Conversion ID** and **Pixel ID** already filled in. If you haven't set those yet, follow [How to Configure Google Ads Destination in Upstack Data →](/guides/google-ads/how-to-configure-google-ads-destination-in-upstack-data) first. * **Admin** or **Manager** access to a **Google Ads** account, with permission to create or edit **conversion actions** * The Google account you sign in with during OAuth must have access to the Google Ads account you want to forward to (including the manager/MCC account, if you use one) ## Setup Steps <Steps> <Step title="Open your Google Ads destination"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com), navigate to **Events Destination** ([app.upstackdata.com/pixel/event-destinations](https://app.upstackdata.com/pixel/event-destinations)), and open your **Google Ads** destination. If you haven't created the destination yet, add it first using [How to Configure Google Ads Destination in Upstack Data →](/guides/google-ads/how-to-configure-google-ads-destination-in-upstack-data). </Step> <Step title="Enable the Conversion API"> Turn on the **Enable Conversion API** toggle on the destination. The server-side connection panel appears below the pixel fields. </Step> <Step title="Connect Google Ads with OAuth"> In the **Connect Google Ads** card, click **Connect Google Ads**. A Google consent screen opens. Sign in with a Google account that has access to your Google Ads account and grant the requested permissions. <Warning> You must grant **offline access** so Google returns a refresh token. If you skip or revoke that permission, Upstack shows the error *"Google did not return a refresh token. Make sure you grant offline access."* — reconnect and accept all requested scopes. </Warning> On success the panel updates to **Google Ads Server-Side Connected** with the connection timestamp. </Step> <Step title="Select your Google Ads account"> Under **Google Ads Account**, choose the account you want to forward conversions to. The dropdown lists every account your connected Google login can access, shown as **Account Name (10-digit ID)**. <Note> If you manage accounts through a manager (MCC) account, pick the individual advertising account that owns the conversions — not the manager account itself. </Note> </Step> <Step title="Map events to conversion actions"> The **Event Conversion Mappings** table loads pre-filled with common events so you can map them quickly: * **Purchase** * **NC Purchase** (new customer purchase) * **Subscription Initial Purchase** * **Subscription Recurring Purchase** * **Add to Cart** * **Initiate Checkout** For each row, set the **Conversion Action** the event should report to: * **Pick an existing action** from the dropdown, or * Choose **+ Create new in Google Ads** to create a dedicated conversion action for that event (named *" - Upstack (Server-side)"*). Use **+ Add Mapping** to add a row for a custom event (type the event name into the event combobox), and the trash icon to remove any event you don't want to forward. <Tip> To set up everything at once, fill in the event names you want and click **Create & Link**. Upstack creates a dedicated Google Ads conversion action for every row that doesn't have one yet and links it for server-side forwarding. Remove any rows you don't need **before** clicking it. </Tip> </Step> <Step title="Save the configuration"> Save the destination. You need at least one complete mapping (an event name **and** a conversion action) for server-side forwarding to start. <Note> If no row has both an event and a conversion action, Upstack shows *"No server-side events will be forwarded yet."* The pixel keeps running regardless — only server-side forwarding is paused until you complete a mapping. </Note> </Step> </Steps> ## Promote new conversion actions carefully Conversion actions that Upstack creates start as **secondary** (observation-only) goals. As with any new Google Ads conversion, run them alongside your existing setup for **7–14 days** and confirm the volume reconciles before promoting one to **primary**. See [How to Enable the Google Ads Upstack Purchase Goal and Switch to Primary Optimization Goal →](/guides/google-ads/how-to-enable-the-google-ads-upstack-purchase-goal-and-switch-to-primary-optimization-goal). ## Verify the Setup After saving: * The Google Ads destination should show **Healthy** under **Events Destination** in the Upstack dashboard. * Place a test order on your store, then check **Goals → Conversions → Summary** in Google Ads within 24–48 hours and confirm the mapped conversion action records the event. ## FAQ & Troubleshooting <AccordionGroup> <Accordion title="Do I still need the pixel Conversion ID and Pixel ID?"> Yes. The Conversion ID and Pixel ID power the browser pixel, which tracks your primary conversion and remains required on the destination. The Conversions API is an additional server-side path that forwards events to their own conversion actions — it does not replace the pixel. </Accordion> <Accordion title="Why does Upstack create separate conversion actions instead of using my pixel conversion?"> Sending server-side events into the same conversion the pixel fires would mix two sources into one goal and make deduplication and quality comparison impossible. Dedicated server-side conversion actions keep the data clean and let you compare them against your existing goals before promoting any to primary. </Accordion> <Accordion title="I got an error that the conversion action name already exists."> Google reserves the names of conversion actions even after they're removed, so creating *"Purchase - Upstack (Server-side)"* can fail if one existed before (*"A Google Ads conversion action named … already exists in this account"*). Give the action a different display name and try again. </Accordion> <Accordion title="A conversion action shows '— removed in Google Ads'."> The action was deleted on the Google Ads side after it was mapped in Upstack. Pick a different existing action or create a new one for that event, then save. </Accordion> <Accordion title="I use a manager (MCC) account — does that work?"> Yes. Connect with a Google login that can access the account through the manager account, then select the individual advertising account that owns the conversions. Upstack handles the manager-account context when it forwards events. </Accordion> <Accordion title="How do I turn off server-side forwarding?"> Click **Disconnect** in the connection panel, or turn off **Enable Conversion API**. This clears the stored OAuth connection, the selected account, and all event mappings. The browser pixel keeps tracking your primary conversion. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Configure destination" icon="sliders" href="/guides/google-ads/how-to-configure-google-ads-destination-in-upstack-data"> Set the pixel Conversion ID and Pixel ID on the Google Ads destination. </Card> <Card title="Enable primary goal" icon="circle-check" href="/guides/google-ads/how-to-enable-the-google-ads-upstack-purchase-goal-and-switch-to-primary-optimization-goal"> Promote a conversion to primary so Smart Bidding optimizes against it. </Card> <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # [DRAFT] How Custom Event Mappings Work for Health & Wellness Stores Source: https://docs.upstackdata.com/guides/health-wellness/custom-event-mappings-health-wellness Learn why Upstack replaces standard Meta event names with custom events, how to use them in Ads Manager, and the full mapping reference. ### The Short Version Upstack's Health & Wellness container replaces standard Meta events (like Purchase and AddToCart) with **custom-named events** (like `UPSTACK_HW_6117d13b`). This prevents Meta's automated flagging systems from recognizing and restricting your conversion events. The custom events work identically for campaign optimization — you just need to approve them in Events Manager and select them when setting up your ad sets. ### Why Standard Event Names Are a Problem Meta defines a set of standard events — Purchase, AddToCart, InitiateCheckout, ViewContent, and others — that are used across millions of advertisers. These event names are deeply integrated into Meta's advertising system for optimization, reporting, and audience building. For Health & Wellness flagged stores, this is a problem. When Meta sees a Purchase event coming from a domain or pixel that's flagged as H\&W, it applies additional restrictions to that event: * **The event may be blocked from optimization.** Meta can prevent you from using Purchase as an optimization objective in your campaigns. * **The event may be downgraded.** Even if not fully blocked, Meta may give less weight to the event in its delivery algorithm. * **The event triggers automated review.** Standard events on flagged accounts are scrutinized more heavily by Meta's compliance systems. The standard event names essentially act as labels that Meta's flagging system monitors. By replacing them with custom event names that Meta's system doesn't recognize as health-related, the events pass through without triggering these restrictions. ### How Custom Event Mappings Work ### What Changes Every standard Meta event is remapped to a unique custom event name. The mapping is consistent — the same standard event always maps to the same custom event — so Meta can learn and optimize on the custom events just like it would with standard ones. For example: * When a customer makes a purchase, instead of sending a `Purchase` event, Upstack sends `UPSTACK_HW_6117d13b` * When a customer adds an item to their cart, instead of `AddToCart`, Upstack sends `UPSTACK_HW_de792bda` The custom event names are deterministic hashes — they look random but map consistently to the same standard event. This means `UPSTACK_HW_6117d13b` always means "Purchase" across all Upstack H\&W customers. ### What Stays the Same The custom event carries all the same data as the standard event it replaces: * **Value and currency** — still attached for conversion value optimization * **User identifiers** — still hashed and sent for attribution * **Event timing** — still accurate The only thing that changes is the `event_name` field. From Meta's perspective, it's receiving a custom conversion event with value data — exactly like any other custom event an advertiser might define. ### Full Event Mapping Reference <table><tbody><tr><td><p><b>Standard Event</b></p></td><td><p><b>H\&W Custom Event</b></p></td><td><p><b>Notes</b></p></td></tr><tr><td><p>PageView</p></td><td><p>PageView</p></td><td><p>Unchanged — not flagged</p></td></tr><tr><td><p>ViewContent</p></td><td><p>ViewContent</p></td><td><p>Unchanged — not flagged</p></td></tr><tr><td><p>ViewCategory</p></td><td><p>view\_category</p></td><td><p>Minor rename</p></td></tr><tr><td><p>AddToCart</p></td><td><p>UPSTACK\_HW\_de792bda</p></td><td /></tr><tr><td><p>InitiateCheckout</p></td><td><p>UPSTACK\_HW\_d823e4ff</p></td><td /></tr><tr><td><p>Purchase</p></td><td><p>UPSTACK\_HW\_6117d13b</p></td><td><p>Primary optimization event</p></td></tr><tr><td><p>Lead</p></td><td><p>UPSTACK\_HW\_289161cb</p></td><td /></tr><tr><td><p>Schedule</p></td><td><p>UPSTACK\_HW\_5a3811fb</p></td><td /></tr><tr><td><p>Complete Registration</p></td><td><p>UPSTACK\_HW\_895b83ff</p></td><td /></tr><tr><td><p>Contact</p></td><td><p>UPSTACK\_HW\_4c62e638</p></td><td /></tr><tr><td><p>Invite Meeting Sched.</p></td><td><p>UPSTACK\_HW\_529b7e00</p></td><td /></tr><tr><td><p>AddPaymentInfo</p></td><td><p>UPSTACK\_HW\_9984f5f9</p></td><td /></tr><tr><td><p>AddShippingInfo</p></td><td><p>UPSTACK\_HW\_3c4012cc</p></td><td /></tr><tr><td><p>All Purchase</p></td><td><p>UPSTACK\_HW\_f0e986fc</p></td><td><p>All purchases (new + returning)</p></td></tr><tr><td><p>NC Purchase</p></td><td><p>UPSTACK\_HW\_fa2b3354</p></td><td><p>New customer purchases only</p></td></tr><tr><td><p>RC Purchase</p></td><td><p>UPSTACK\_HW\_5ec76558</p></td><td><p>Returning customer purchases only</p></td></tr></tbody></table> Note that **PageView** and **ViewContent** are sent with their standard names. These top-of-funnel events are generally not restricted by the H\&W flag, and keeping them standard helps with audience building and funnel reporting in Meta. ### Approving Custom Events in Meta Events Manager When custom events first appear in Meta Events Manager, they show a **red triangle warning** (⚠️). This is normal — Meta flags any new custom event that hasn't been explicitly approved by the account owner. Until you approve them, the events are tracked but **cannot be used for campaign optimization**. This means you must approve the events before you can set up ad sets that optimize toward them. ### How to Approve <Steps> <Step title="Open Meta Events Manager"> Sign in to [Meta Events Manager](https://business.facebook.com/events_manager) and select your new (clean) pixel. You'll see the custom events listed with red triangle icons. </Step> <Step title="Review each event"> For each event, click the event name or the warning icon, then click **Review** or **Manage Status**. </Step> <Step title="Confirm the event"> Click **I acknowledge**, then click **Confirm the custom event → Confirm**. </Step> </Steps> The red triangle disappears and the event becomes available for optimization. For detailed steps with screenshots: [How to Approve Facebook (Meta) Custom Events →](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events) ### Using Custom Events in Ads Manager Once approved, custom events work exactly like standard events in your campaign setup. ### Setting Up Campaigns When creating or editing an ad set, you'll choose your optimization event. Instead of selecting "Purchase" from the standard events dropdown, you'll: <Steps> <Step title="Find Custom Events in the optimization dropdown"> In Meta Ads Manager, on the ad set screen, open the **Performance Goal / Conversion Event** dropdown and scroll to **Custom Events** (or the custom events section). </Step> <Step title="Select the Purchase event"> Choose `UPSTACK_HW_6117d13b` (this is your Purchase event). </Step> <Step title="Continue with campaign settings"> Continue with your normal campaign settings. Everything else — budget, audience targeting, bidding strategy, creative — stays exactly the same. </Step> </Steps> ### Reporting and Columns In Ads Manager reporting, custom events appear as their custom names. To make reporting easier: * **Add custom columns** for your key H\&W events (especially `UPSTACK_HW_6117d13b` for Purchase). * **Create saved column presets** so you don't have to reconfigure reporting views each time. * **Use custom conversions** if you want to create more readable names in reporting (e.g., create a custom conversion called "H\&W Purchase" based on the `UPSTACK_HW_6117d13b` event). ### Value Optimization Because the custom Purchase event still carries value and currency data, you can use **value-based optimization** (ROAS bidding) with H\&W events. This works identically to optimizing toward a standard Purchase event with value. ### Why Not Just Use Custom Conversions Instead? You might wonder why Upstack sends entirely different event names rather than sending a standard Purchase event and relying on Meta's custom conversions feature to filter. The reason is that Meta's restriction layer operates at the **event level**, not the custom conversion level: * A standard `Purchase` event from a flagged source is restricted **before** it reaches the optimization layer. * A custom event name like `UPSTACK_HW_6117d13b` is not in Meta's restriction list, so it passes through normally. Custom conversions are a reporting/optimization feature that sits on top of events. They can't bypass restrictions that are applied to the underlying event itself. ### NC Purchase vs. RC Purchase vs. All Purchase Upstack's H\&W mappings include three Purchase variants: **All Purchase (`UPSTACK_HW_f0e986fc`)** — Every purchase, regardless of customer type. This is the broadest purchase event. **NC Purchase (`UPSTACK_HW_fa2b3354`)** — New customer purchases only. Fires only when the purchaser is identified as a first-time buyer. Use this when you want to optimize specifically for customer acquisition. **RC Purchase (`UPSTACK_HW_5ec76558`)** — Returning customer purchases only. Fires when an existing customer makes a repeat purchase. **Purchase (`UPSTACK_HW_6117d13b`)** — The primary purchase event, equivalent to Meta's standard Purchase. This is the recommended default for campaign optimization. Which one you optimize toward depends on your business goals. Most brands start with the primary Purchase event and layer in NC/RC optimization as they scale. ### What You Need to Do 1. **Approve all custom events** in Meta Events Manager (the red triangle step). 2. **Update your campaign optimization** to point to `UPSTACK_HW_6117d13b` for Purchase. 3. **Update your Ads Manager reporting columns** to include the custom events you care about. Upstack handles the mapping automatically — you never need to configure which events map to which names. That's built into the H\&W container. ### Related Articles * [Global Event Mappings](/guides/custom-events/global-event-mappings) — set up your own event mappings for any destination * [Health & Wellness Custom Event Mappings](/guides/facebook-ads/health-and-wellness-custom-event-mappings) * [How to Approve Facebook (Meta) Custom Events](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events) * [How Upstack Data Solves Health & Wellness Restrictions](/guides/health-wellness/how-upstack-solves-health-wellness-restrictions) * [How to Set Up a Health & Wellness Pixel for Meta](/guides/health-wellness/setup-health-wellness-pixel-for-meta) # [DRAFT] How Data Sanitization Protects Health & Wellness Stores Source: https://docs.upstackdata.com/guides/health-wellness/data-sanitization-health-wellness Learn what data Upstack scrubs before sending events to Meta, why each piece matters, and exactly what Meta still receives for optimization. ### The Short Version Before any event reaches Meta, Upstack's Health & Wellness container runs it through a **sanitization layer** that strips out product names, URLs, SKUs, and any other content that could contain health or wellness keywords. Meta still gets everything it needs for attribution and optimization — event type, value, currency, and user identifiers — but none of the content that causes flags. ### Why Sanitization Is Necessary Meta's Health & Wellness flagging system doesn't just look at your domain once and make a decision. It continuously evaluates the data your pixel sends. Every event that arrives at Meta carries metadata — and that metadata can contain the keywords, product names, and URLs that trigger or reinforce the flag. Here's what a typical unsanitized Purchase event looks like when sent to Meta: <Note> **Example: Unsanitized event payload** `event_name`: Purchase `event_source_url`: [https://yourstore.com/checkout/thank-you](https://yourstore.com/checkout/thank-you) `content_ids`: \["sup-ashwagandha-60ct"] `content_name`: "Organic Ashwagandha Supplement - 60 Capsules" `content_category`: "Supplements > Adaptogens" `value`: 59.99 | `currency`: USD </Note> Look at what's embedded in that payload: the product is called "Organic Ashwagandha Supplement," the category is "Supplements > Adaptogens," and the content ID contains "sup-ashwagandha." Every one of these fields is a signal to Meta's automated systems that this store sells health and wellness products. ### What Gets Stripped Upstack's sanitization layer removes or neutralizes the following fields before any event is sent to Meta: ### Product Names (content\_name) Any text that identifies what the customer bought or viewed. This is the most common source of flaggable keywords — product titles like "Collagen Peptides Powder" or "Vitamin D3 5000 IU" are exactly what Meta's classifiers look for. **Before:** `"content_name": "Organic Ashwagandha Supplement - 60 Capsules"` **After:** Field removed entirely. ### Product IDs and SKUs (content\_ids) Even encoded or abbreviated product identifiers can contain flaggable terms. A SKU like `CBD-TINCTURE-30ML` or a product ID like `probiotic-daily-60` carries the same signal as the full product name. **Before:** `"content_ids": ["sup-ashwagandha-60ct"]` **After:** Field removed entirely. ### Product Categories (content\_category) Category paths often contain the broadest and most obvious health/wellness terms: "Supplements," "Vitamins," "Health," "Wellness," "CBD," etc. **Before:** `"content_category": "Supplements > Adaptogens"` **After:** Field removed entirely. ### Page URLs (event\_source\_url) The URL where the event occurred is replaced with a URL from the clean alias domain. This prevents Meta from seeing paths like `/products/organic-turmeric-capsules` or `/collections/immune-support`. **Before:** `"event_source_url": "https://yourstore.com/products/organic-ashwagandha"` **After:** `"event_source_url": "https://youraliasdomain.com/"` ### What Still Gets Sent After sanitization, the event that reaches Meta looks like this: <Note> **Example: Sanitized event payload** `event_name`: UPSTACK\_HW\_6117d13b `event_source_url`: [https://youraliasdomain.com/](https://youraliasdomain.com/) `user_data`: hashed email, hashed phone, fbclid, fbp, IP, user agent `value`: 59.99 | `currency`: USD </Note> Here's what each remaining field does: * **event\_name** — Mapped to a custom H\&W event. Tells Meta what action occurred without using flagged standard event names. * **event\_source\_url** — The alias domain URL. Meta's bot can visit this domain and see a compliant page. * **user\_data** — Hashed email, hashed phone, Facebook click ID, browser ID, IP address, and user agent. These are the identity signals Meta uses to match the event to a user. They contain no product or health information. * **value and currency** — The monetary value of the conversion. Essential for ROAS optimization and value-based bidding. ### Why This Level of Scrubbing Is Necessary You might wonder: "Can't we just rename the products or change the URLs?" In practice, partial measures don't hold up: **Meta's classifiers are broad.** They don't just look for the word "supplement." They flag terms like "capsules," "extract," "daily," "formula," "blend," and dozens of other words common across health product catalogs. Trying to rename everything to be compliant is a losing game. **The flag is persistent.** Once a domain is flagged, Meta's systems are primed to look for health-related content from that source. Even mildly suggestive terminology can reinforce the classification. Clean scrubbing removes the ambiguity entirely. **You can't control every surface.** Product data shows up in URLs, page titles, meta tags, structured data, Open Graph tags, and more. The browser pixel can read all of these. Server-side sanitization is the only way to ensure nothing slips through. **Future-proofing.** If you add a new product line or a new employee adds products with flaggable names, the sanitization layer catches it automatically. You don't need to audit every SKU before launching. ### How Sanitization Interacts with Other Components Data sanitization doesn't work alone — it's one piece of the four-part H\&W solution: * **Server-side-only tracking** ensures the browser pixel never sends unsanitized data directly to Meta. * **Data sanitization** cleans the event payload before it leaves Upstack's servers. * **Domain aliasing** replaces the flagged domain in the event\_source\_url field. * **Custom event mappings** replace standard event names with non-flaggable custom names. All four layers work together. If you removed sanitization but kept the other three, product data in the event payload could still trigger a re-flag. If you kept sanitization but sent from the flagged domain, Meta's domain-level restrictions would still apply. ### What You Need to Do Nothing — sanitization is handled automatically by Upstack's Health & Wellness container. There is no configuration required on your end. <Note> **Note on product-level reporting:** Since product IDs and names are stripped, you won't see per-product conversion breakdowns in Meta Ads Manager. You can still get this data from Shopify analytics, the [Upstack dashboard](https://app.upstackdata.com), or third-party attribution tools like Triple Whale (which receives unsanitized data since it's not sending to Meta). </Note> ### Related Articles * [How Upstack Data Solves Health & Wellness Restrictions](/guides/health-wellness/how-upstack-solves-health-wellness-restrictions) * [How to Set Up a Health & Wellness Pixel for Meta](/guides/health-wellness/setup-health-wellness-pixel-for-meta) # [DRAFT] How Upstack Data Solves Health & Wellness Restrictions Source: https://docs.upstackdata.com/guides/health-wellness/how-upstack-solves-health-wellness-restrictions Restore accurate Meta tracking for Health & Wellness brands with Upstack's protective container — server-side-only delivery, data sanitization, domain aliasing, and custom event mappings. Learn how Upstack's Health & Wellness container restores accurate Meta tracking using server-side-only delivery, data sanitization, domain aliasing, and custom event mappings. ### Overview When Meta flags your store under Health & Wellness, standard tracking breaks down. Upstack Data implements a specialized **Health & Wellness container** that works around these restrictions while staying fully compliant. The result: Meta receives high-quality conversion data for optimization, and your store avoids being re-flagged. The solution has four components that work together. ### 1. Server-Side-Only Tracking For Health & Wellness stores, Upstack **removes the Facebook browser pixel entirely** and operates server-side only via Meta's Conversions API (CAPI). **Why this matters:** The browser pixel (JavaScript) has a mind of its own — it sits on your website and grabs data automatically, including product names, URLs, and page content that may contain flaggable keywords. Upstack cannot control what the browser pixel pulls, and it runs in the background independently. By going server-side only through CAPI, Upstack has complete control over every piece of data sent to Meta with **100% guaranteed delivery**. The entire Upstack platform is built around ensuring redundancy without the browser pixel. ### 2. Data Sanitization Before sending any data to Meta, Upstack pre-processes it to remove anything that could trigger a flag: * **Product names** containing health/wellness keywords are stripped — for example, a product like "Magnesium Supplement for Cramping" would be flagged because "cramping" is a medical condition in that context. * **Product URLs** with flaggable terms are cleaned. * **Product descriptions** that could indicate medical conditions are filtered. * **SKUs, product IDs, and titles** are removed or anonymized. * Only **essential data** is sent: event type, purchase value, currency, and user identifiers (email, phone, click ID). Meta still receives everything it needs for accurate attribution and optimization — without the content that causes flags. ### 3. Domain Aliasing All events are sent from a **clean alias domain** instead of your flagged primary domain. This prevents new pixels from inheriting the flag. How it works: * The alias domain is a separate root domain (not a subdomain) that you register. * It has a simple, compliant landing page — just a headline and an image. * No real traffic is ever sent to this domain. It exists so Meta's compliance bot sees a clean page. * All CAPI events are reported as originating from this alias domain. Since the Health & Wellness flag is attached to your domain (not your pixel), aliasing is what makes the entire solution work. The alias domain prevents Meta from connecting the event data you're sending to anything that has previously been flagged on their backend. Domain aliasing has **no negative performance impact** — it is purely a safety measure. ### 4. Custom Event Mappings Standard Meta events (AddToCart, Purchase, etc.) are mapped to **Upstack Health & Wellness custom events** to avoid triggering Meta's automated flagging systems. For example, the Purchase event becomes `UPSTACK_HW_6117d13b` and AddToCart becomes `UPSTACK_HW_de792bda`. These custom events must be approved in Meta Events Manager before they can be used for campaign optimization. For the full mapping table: [Health & Wellness Custom Event Mappings →](/guides/facebook-ads/health-and-wellness-custom-event-mappings) For instructions on approving custom events: [How to Approve Facebook (Meta) Custom Events →](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events) ### Dual-Pixel Transition Strategy When switching to a new pixel, Upstack supports a **dual-pixel approach**: * Data feeds to **both your existing pixel and the new clean pixel** simultaneously. * Your current campaigns continue running on the existing pixel while the new pixel builds up data. * Once the new pixel has enough data (typically about a week), you can begin migrating campaigns. * How fast you switch depends on your current ad performance — if things are painful, switch quickly; if performance is acceptable, train the new pixel with data first and transition gradually. If your existing pixel has not been flagged and retains its audience data, you may be able to continue using it instead of creating a new one. Discuss this with the Upstack team during onboarding. ### Ongoing Protection Once set up with the Health & Wellness container: * **No re-flagging** as long as all Meta events are sent through Upstack (no direct browser pixel, no data from the flagged domain). This approach has a **100% success rate** in preventing re-flagging. * **The alias domain stays in place permanently** — the registration fee and hosting cost are the only ongoing expenses. * **Theme changes don't break tracking** since everything is server-side (no Theme App Extension dependency for Meta events). * **No extra cost** — the Health & Wellness container, implementation, and ongoing support are all included in your Upstack subscription. ### Get Started Ready to set up the Health & Wellness solution? Follow the step-by-step guide: [How to Set Up a Health & Wellness Pixel for Meta →](/guides/health-wellness/setup-health-wellness-pixel-for-meta) ### Related Articles * [Understanding Meta's Health & Wellness Flag](/guides/health-wellness/understanding-meta-health-wellness-flag) * [How to Set Up a Health & Wellness Pixel for Meta](/guides/health-wellness/setup-health-wellness-pixel-for-meta) * [Health & Wellness Custom Event Mappings](/guides/facebook-ads/health-and-wellness-custom-event-mappings) * [How to Approve Facebook (Meta) Custom Events](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events) # [DRAFT] How Server-Side-Only Tracking Protects Health & Wellness Stores Source: https://docs.upstackdata.com/guides/health-wellness/server-side-tracking-health-wellness-protection Learn why Upstack removes the Meta browser pixel entirely for Health & Wellness flagged stores and sends all data through the Conversions API instead. ### The Short Version For stores flagged under Meta's Health & Wellness category, Upstack Data operates in **server-side-only mode** — meaning the Facebook browser pixel (the JavaScript snippet that normally runs on your website) is completely removed. All event data is sent directly from Upstack's servers to Meta through the Conversions API (CAPI). This gives Upstack complete control over what data reaches Meta, which is the foundation of the entire Health & Wellness solution. ### Why the Browser Pixel Is a Problem for H\&W Stores The standard Meta pixel is a JavaScript snippet that runs in your customer's browser. When someone visits your store, the pixel automatically reads information from the page and sends it to Meta. This includes: * The **page URL** (e.g., `yourstore.com/products/organic-ashwagandha-supplement`) * The **page title** (e.g., "Organic Ashwagandha Supplement - 60 Capsules") * **Product data** embedded in the page (names, descriptions, categories) * **Referrer URLs** that may contain health-related search terms * **Content IDs** and other metadata tied to your product catalog The problem is that this happens automatically. The browser pixel scrapes whatever is on the page and sends it along with the event. For a Health & Wellness flagged store, this means Meta is constantly receiving data full of the exact keywords and content that triggered the flag in the first place — product names with words like "supplement," "vitamin," "collagen," "probiotic," or "CBD." Even if you've already been flagged, continuing to send this kind of data through the browser pixel can: * **Reinforce the flag**, making it harder to resolve * **Trigger a re-flag** if you've set up a new pixel * **Reduce Event Match Quality** as Meta discards or downgrades events it considers non-compliant You cannot selectively control what the browser pixel sends. It reads the DOM (the page content) and transmits what it finds. This is by design — Meta wants as much signal as possible for optimization. But for H\&W stores, that same signal is what causes the restrictions. ### How Server-Side-Only Mode Works When Upstack activates the Health & Wellness container, the tracking flow changes completely: ### Standard Tracking (Browser + Server) In a normal Upstack setup, events are sent two ways: 1. **Browser pixel** fires in the customer's browser and sends data directly to Meta 2. **Server-side (CAPI)** sends the same event from Upstack's servers to Meta Both carry a shared `event_id` so Meta deduplicates them into a single event. This redundancy improves match rates and ensures events aren't lost to ad blockers or browser restrictions. ### Health & Wellness Mode (Server-Only) In H\&W mode, the Meta browser pixel is removed entirely: <Steps> <Step title="Customer actions are captured"> Customer actions (page views, add to cart, purchases) are captured by Upstack's Theme App Extension on your store. </Step> <Step title="Data is sent to Upstack"> Event data is sent to **Upstack's servers** — not to Meta. </Step> <Step title="Data is sanitized"> Upstack **processes and sanitizes** the data (see the [Data Sanitization](/guides/health-wellness/data-sanitization-health-wellness) article). </Step> <Step title="Clean event is sent to Meta"> The clean event is sent to Meta via the **Conversions API only**. </Step> </Steps> No JavaScript from Meta ever runs on your site. Meta never sees your page content, URLs, or product data directly. ### What Data Gets Sent to Meta In server-side-only mode, Upstack sends only what Meta needs for attribution and optimization: **Always sent:** * **Event type** — the action that occurred (mapped to a custom H\&W event name) * **Event time** — when the action happened * **User identifiers** — hashed email, hashed phone number, Facebook click ID (`fbclid`), and browser ID (`fbp`) for matching the event to a Meta user * **Event source URL** — the alias domain URL (not your real store URL) **Sent for conversion events (Purchase, Add to Cart, etc.):** * **Value** — the purchase amount or cart value * **Currency** — e.g., USD **Never sent:** * Product names, descriptions, or categories * Real page URLs from your flagged domain * SKUs, product IDs, or catalog data * Any content that could contain health/wellness keywords This is enough data for Meta to attribute conversions to your ads, optimize delivery, and build audiences — without exposing any content that would trigger or reinforce the H\&W flag. ### Why CAPI-Only Still Works for Optimization A common concern is that removing the browser pixel will hurt performance. In practice, for H\&W flagged stores, the opposite is true. **The browser pixel was already compromised.** Once a store is flagged, Meta restricts what it does with browser pixel data from that domain. In many cases, browser events are partially or fully ignored for optimization. Removing a data source that Meta is already discounting doesn't hurt you — it removes a liability. **CAPI events are treated as higher quality.** Server-side events carry hashed first-party data (email, phone) that provides stronger identity matching than cookies alone. Meta's own documentation recommends CAPI as the primary data source, with the browser pixel as a supplement. **Event Match Quality stays strong.** EMQ depends on the quality of user identifiers (email, phone, click ID), not on the transmission method. Upstack captures these identifiers at key moments (checkout, account creation) and sends them via CAPI. Most Upstack H\&W customers see EMQ scores comparable to or better than their pre-flag performance. **The flag was the real performance killer.** The biggest optimization hit comes from the flag itself — restricted audiences, blocked events, degraded delivery. By going server-side only with clean data from an unflagged domain, you're restoring what the flag took away. ### How This Differs from Standard CAPI Setups Not all server-side tracking is the same. Here's how Upstack's H\&W implementation differs from a standard CAPI setup: <table><tbody><tr><td><p><b>Feature</b></p></td><td><p><b>Standard CAPI</b></p></td><td><p><b>Upstack H\&W (Server-Only)</b></p></td></tr><tr><td><p>Browser pixel active</p></td><td><p>Yes (redundant tracking)</p></td><td><p>No (completely removed)</p></td></tr><tr><td><p>Data sanitization</p></td><td><p>No</p></td><td><p>Yes (keywords, URLs, product data stripped)</p></td></tr><tr><td><p>Event source URL</p></td><td><p>Your real domain</p></td><td><p>Clean alias domain</p></td></tr><tr><td><p>Event names</p></td><td><p>Standard Meta events</p></td><td><p>Custom H\&W event mappings</p></td></tr><tr><td><p>Product data sent</p></td><td><p>Yes (content\_ids, content\_name)</p></td><td><p>No (stripped before sending)</p></td></tr></tbody></table> A standard CAPI setup still relies on the browser pixel running alongside it. For H\&W stores, that browser pixel is the source of the problem. Upstack's approach eliminates it entirely and controls every byte of data that reaches Meta. ### What You Need to Do Nothing — Upstack handles this automatically when the Health & Wellness container is activated during your onboarding call. The browser pixel removal, CAPI-only routing, and data processing all happen on Upstack's side. <Note> **Watch for other tracking tools.** Any active browser pixel — from Shopify's native integration, Triple Whale Sonar, Elevar, or hardcoded JavaScript — will send unsanitized data to Meta and undermine the server-side-only approach. Make sure all other Meta pixel sources are disabled. </Note> [How to Disable Facebook and Instagram Data Sharing in Shopify →](/guides/facebook-ads/how-to-disable-facebook-and-instagram-data-sharing-in-shopify) ### Related Articles * [How Upstack Data Solves Health & Wellness Restrictions](/guides/health-wellness/how-upstack-solves-health-wellness-restrictions) * [How to Set Up a Health & Wellness Pixel for Meta](/guides/health-wellness/setup-health-wellness-pixel-for-meta) * [How to Disable Facebook and Instagram Data Sharing in Shopify](/guides/facebook-ads/how-to-disable-facebook-and-instagram-data-sharing-in-shopify) # [DRAFT] How to Set Up an Alias Domain for Health & Wellness Tracking Source: https://docs.upstackdata.com/guides/health-wellness/setup-alias-domain-health-wellness Step-by-step instructions for registering a clean alias domain and building a compliant landing page for Meta's Health & Wellness tracking solution. Step-by-step instructions for registering a clean alias domain and building a compliant landing page for Meta's Health & Wellness tracking solution. ### Prerequisites * An [Upstack Data](https://app.upstackdata.com) account in good standing (subscription active) * Admin access to your [Meta Business Manager](https://business.facebook.com) and the (new, unflagged) pixel you'll use for H\&W tracking * A new domain registrar account (Namecheap, GoDaddy, Cloudflare, etc.) for purchasing the alias domain * Access to a hosting provider or landing page builder (Carrd, Unbounce, Instapage, or any static host) * A means to contact the Upstack team (your shared Slack channel or `support@upstackdata.com`) ### Why You Need an Alias Domain Meta's Health & Wellness flag is attached to your domain. Any pixel receiving events from a flagged domain will also get flagged — even a brand-new pixel. The alias domain gives your new pixel a clean origin so it stays unflagged. The alias domain is a separate root domain with a simple landing page. No real traffic goes to it. It exists solely so that Meta's compliance bot sees a clean, compliant page when it checks the event source. ### Requirements Your alias domain must meet all of the following: **Must be a new root domain.** For example, `mybrandwellness.com`. It cannot be a subdomain like `safe.mybrand.com` — Meta flags at the root domain level. **Must have no history with Meta.** Register a brand-new domain that has never been used with a Meta pixel or ad account. **Must never receive real ad traffic.** Do not run ads pointing to this domain. It is only for Meta's bot to visit. **Must have a simple, compliant landing page.** A headline and an image — nothing that references health, wellness, or supplement products. **Must be hosted somewhere accessible.** Any cheap hosting option works: Carrd, Unbounce, Instapage, or simple static hosting. ### Setup Steps <Steps> <Step title="Register the domain"> Purchase a new root domain from any registrar (Namecheap, GoDaddy, Cloudflare, etc.). Choose something brand-adjacent but generic — avoid words like "health," "wellness," "supplements," or "vitamins" in the domain name itself. **Good examples:** `mybrandshop.com`, `shopbrandname.com`, `brandlifestyle.com`, `getbrandname.com`, `trybrandname.com` **Bad examples:** `mybrandsupplements.com`, `brandwellnessstore.com`, `brandvitamins.com` A common pattern is to take your existing domain and add a prefix like "get" or "shop." For example, if your store is `tryanomalyhealth.com`, your alias could be `getanomalyhealth.com`. </Step> <Step title="Build the landing page"> The landing page needs to be simple and compliant. Here's what to include: **What to put on the page:** * A generic headline (e.g., an advertorial-style headline that does not mention supplements, health, wellness, or medical terms) * A stock image * That's it — no forms, no product listings, no links to your real store The page can be as simple as a single image — nobody will ever see it. Some brands repurpose an existing landing page and just remove any medical or health terminology. A listicle-style page with broad lifestyle content also works well. **What NOT to put on the page:** * Any health or wellness product names, descriptions, or keywords (e.g., "osteoporosis," "cramping," "supplement," "vitamin") * Links to your flagged store * Supplement, vitamin, or medical terminology * Real product content of any kind You can use any landing page builder. Carrd (\$19/year) or a single HTML file on static hosting are the simplest options. </Step> <Step title="Verify the domain in Meta Events Manager"> Once the landing page is live: 1. Sign in to [Meta Events Manager](https://business.facebook.com/events_manager). 2. Select your new (unflagged) pixel. 3. Open **Settings → Domains**, add the alias domain, and complete the domain verification process Meta provides (typically a DNS TXT record or `meta-tag` upload). 4. Wait for domain approval — this is required before Upstack can activate aliasing. </Step> <Step title="Request aliasing activation"> After the domain is approved in Meta Events Manager, contact the Upstack team to enable domain aliasing: * **Slack:** Post in your shared Slack channel. * **Email:** [support@upstackdata.com](mailto:support@upstackdata.com). Upstack will configure aliasing so all events report from the clean alias domain instead of your flagged primary domain. </Step> <Step title="Verify aliasing is live"> After Upstack confirms the alias is live: 1. Trigger a test event (e.g., place a test order or load a tracked page). 2. In [Meta Events Manager](https://business.facebook.com/events_manager) → your new pixel → **Test Events** or **Overview**, confirm the **Event Source URL** matches your alias domain (not your flagged primary domain). 3. In the [Upstack dashboard](https://app.upstackdata.com), confirm events continue to flow under **Event Health**. </Step> </Steps> ### Ongoing Maintenance The alias domain stays in place permanently. The only ongoing costs are: * **Domain registration renewal** (typically \$10–15/year) * **Hosting** (free to minimal, depending on provider) Do not let the domain registration expire or take down the landing page — Meta's bot may revisit the domain at any time. ### Need Help? If you'd like the Upstack team to review your landing page before going live, post it in your shared Slack channel for a quick sign-off. ### Related Articles * [How to Set Up a Health & Wellness Pixel for Meta](/guides/health-wellness/setup-health-wellness-pixel-for-meta) * [Understanding Meta's Health & Wellness Flag](/guides/health-wellness/understanding-meta-health-wellness-flag) * [How Upstack Data Solves Health & Wellness Restrictions](/guides/health-wellness/how-upstack-solves-health-wellness-restrictions) # [DRAFT] How to Set Up a Health & Wellness Pixel for Meta Source: https://docs.upstackdata.com/guides/health-wellness/setup-health-wellness-pixel-for-meta Step-by-step guide for setting up Upstack Data's Health & Wellness tracking solution for Meta-flagged stores. Each step links to a focused article with detailed instructions. This guide walks you through setting up Upstack Data's Health & Wellness tracking solution for stores flagged by Meta. Each step links to a focused article with detailed instructions. ### Quick Summary * Upstack restores accurate Meta tracking for stores flagged under Health & Wellness restrictions. * Setup requires a **clean alias domain**, a **new Meta pixel**, and an **Upstack Data account**. * All tracking runs **server-side only** — the browser pixel is removed entirely. * Standard events are mapped to **custom H\&W events** that must be approved in Meta Events Manager. * After setup, migrate your ad campaigns to the new pixel and optimize toward the H\&W Purchase event. ### What Is the Health & Wellness Flag? Meta restricts stores that sell supplements, wellness products, or health-related goods. Once flagged, your pixel loses the ability to fully track and optimize bottom-funnel events like AddToCart and Purchase — leading to weaker campaign performance and declining ROAS. **The flag is attached to your domain, not your pixel.** Creating a new pixel on the same domain will also get flagged. That's why Upstack uses a different approach. [Understanding Meta's Health & Wellness Flag →](/guides/health-wellness/understanding-meta-health-wellness-flag) ### How Upstack Data Solves This Upstack deploys a specialized Health & Wellness container with four components: server-side-only tracking (no browser pixel), data sanitization to strip flaggable content, domain aliasing from a clean domain, and custom event mappings that avoid Meta's automated flagging. [How Upstack Data Solves Health & Wellness Restrictions →](/guides/health-wellness/how-upstack-solves-health-wellness-restrictions) ### Prerequisites Have the following ready before booking your onboarding call: * An **active Shopify store** (`your-store.myshopify.com`) with [Shopify Admin](https://admin.shopify.com) access * A **[Meta Business Manager](https://business.facebook.com)** account with admin access * A **new, clean root domain** for aliasing (see Step 1) * A **new Meta pixel** created but not connected to anything (see Step 2). Meta Pixel ID format: a 15–16 digit number such as `123456789012345` * An **Upstack Data account** at [app.upstackdata.com](https://app.upstackdata.com) with a subscription and payment method on file. Your Upstack Pixel ID format: `XXXX-XXXX-XXXXX-XXXX` (e.g., `58284d43-85f6-41fb-b2e0-f32f8ecb4e9b`) ### Setup Steps <Steps> <Step title="Create your alias domain and landing page"> You'll need a brand-new root domain (not a subdomain) with a simple, compliant page — just a headline and an image. No health/wellness product names, supplement terms, or links to your store. This domain exists solely for Meta's compliance bot. No real ad traffic should ever go to it. [How to Set Up an Alias Domain for Health & Wellness Tracking →](/guides/health-wellness/setup-alias-domain-health-wellness) </Step> <Step title="Create a new Meta pixel"> Create a fresh pixel in Meta Business Manager. **Do not send any data to it from your flagged domain** — even one event will flag the new pixel. 1. Sign in to [Meta Events Manager](https://business.facebook.com/events_manager). 2. Click **Connect Data Sources** (top-left of the page) and create a new **Pixel / Dataset**. 3. Name it (e.g., `Brand Name - Clean Pixel`). 4. Do not configure or connect it to anything yet — just note the Pixel ID (15–16 digits). [How to Configure Facebook (Meta) Ads Pixel Destination in Upstack Data →](/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data) </Step> <Step title="Set up your Upstack Data account"> Sign up, select a plan, and enter your payment information. [How to Download and Install Upstack Data App in Shopify →](/guides/shopify/how-to-download-and-install-upstack-data-app-in-shopify) </Step> <Step title="Book your onboarding call"> With the alias domain, new pixel, and Upstack account ready, book an onboarding call (typically 30–45 minutes). The Upstack team will handle: * Standard Shopify setup * Health & Wellness container activation (the "protective layer") * Domain aliasing configuration * Meta destination setup with CAPI in server-side-only mode The H\&W container typically takes the Upstack team an afternoon to configure and push live after the onboarding call. <Warning> Do not connect your Facebook Ads or send any data to Meta until the Upstack team confirms the Health & Wellness protective layer has been deployed. Connecting before the container is active increases your risk of getting flagged or banned. </Warning> [Complete Upstack Data Onboarding Guide →](/guides/getting-started/complete-upstack-data-onboarding-guide) </Step> <Step title="Approve the alias domain in Meta Events Manager"> During or after onboarding: 1. Sign in to [Meta Events Manager](https://business.facebook.com/events_manager) and select your new pixel. 2. Open **Settings → Domains** and add the alias domain. 3. Complete the domain verification process Meta prompts you through. <Warning> Domain approval is required before aliasing can be activated. </Warning> </Step> <Step title="Activate domain aliasing"> Contact the Upstack team via your shared Slack channel or [support@upstackdata.com](mailto:support@upstackdata.com) to enable domain aliasing. Once activated, all events will report from the clean alias domain instead of your flagged domain. </Step> <Step title="Approve custom events in Meta Events Manager"> Custom H\&W events will appear with red triangle warnings in Events Manager. Each must be acknowledged and confirmed before it can be used for optimization. **Key event for campaign optimization:** `UPSTACK_HW_6117d13b` (Purchase) [How to Approve Facebook (Meta) Custom Events →](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events) For the full event mapping reference: [Health & Wellness Custom Event Mappings →](/guides/facebook-ads/health-and-wellness-custom-event-mappings) </Step> <Step title="Disable conflicting tracking"> Turn off all other sources sending events to Meta to prevent duplicate events and avoid re-flagging: * **Shopify Facebook & Instagram data sharing** — disable under [Shopify Admin → Settings → Apps and sales channels → Facebook & Instagram](https://admin.shopify.com). * **Third-party tracking apps** (Triple Whale Sonar, Elevar, etc.) — disable Meta event sending in each app. * **Hardcoded Meta pixel code** — remove from your Shopify theme (`theme.liquid` and any custom snippets). [How to Disable Facebook and Instagram Data Sharing in Shopify →](/guides/facebook-ads/how-to-disable-facebook-and-instagram-data-sharing-in-shopify) </Step> <Step title="Migrate campaigns to the new pixel"> During the transition, Upstack feeds data to **both your existing pixel and the new clean pixel** simultaneously. This lets the new pixel build up audience data before you switch campaigns. Your media buyers will need to: 1. Create new campaigns (or duplicate existing ones) pointing to the new pixel. 2. Optimize toward the H\&W custom Purchase event: `UPSTACK_HW_6117d13b`. 3. Gradually shift spend from the old pixel to the new one. 4. Monitor performance as the new pixel exits Meta's learning phase. Migration speed depends on your ad spend, risk tolerance, and how painful your current ad performance is. If performance has degraded significantly, you may want to switch quickly. If performance is still acceptable, consider training the new pixel with about a week of data before transitioning. Some brands cut over immediately; others run both pixels in parallel for 1–2 weeks. <Note> If your existing pixel has not been flagged and retains its audience data, you may be able to continue using it rather than creating a new one. Discuss this with the Upstack team during onboarding. </Note> </Step> <Step title="Verify the H&W setup is working"> Once the container is live and campaigns are pointed at the clean pixel: 1. Place a test order on your store. 2. In [Meta Events Manager](https://business.facebook.com/events_manager) → your new pixel → **Test Events** or **Overview**, confirm the test event arrives via the **Conversions API** channel and the **Event Source URL** is your alias domain (not your flagged primary domain). 3. Confirm the event uses the H\&W custom event name (e.g., `UPSTACK_HW_6117d13b` for Purchase) — not the standard `Purchase` event. 4. In the [Upstack dashboard](https://app.upstackdata.com) → **Event Health**, confirm the event is listed and shows status **Sent**. 5. Confirm there are no events being sent to Meta from any other source (no browser pixel from Shopify, no Triple Whale, no Elevar, no hardcoded scripts). </Step> </Steps> ### What to Expect After Setup <table><tbody><tr><td><p>Milestone</p></td><td><p>Timeframe</p></td></tr><tr><td><p>Events start flowing via CAPI</p></td><td><p>Immediately</p></td></tr><tr><td><p>EMQ improvements visible</p></td><td><p>Within 72 hours</p></td></tr><tr><td><p>Full optimization impact</p></td><td><p>14–21 days</p></td></tr><tr><td><p>Campaign performance recovery</p></td><td><p>Varies by brand</p></td></tr></tbody></table> Once set up, you should never get re-flagged as long as all Meta events flow through Upstack. **Using a third-party checkout?** (e.g., Phoenix, Checkout Champ) Let the Upstack team know before going live so tracking can be configured for your checkout platform. ### Need Help? Reach out via your shared Slack channel or contact support with your Meta Pixel ID. ### Related Articles * [Health & Wellness Custom Event Mappings](/guides/facebook-ads/health-and-wellness-custom-event-mappings) * [How to Approve Facebook (Meta) Custom Events](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events) * [How to Configure Facebook (Meta) Ads Pixel Destination in Upstack Data](/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data) * [How to Disable Facebook and Instagram Data Sharing in Shopify](/guides/facebook-ads/how-to-disable-facebook-and-instagram-data-sharing-in-shopify) * [Complete How-To Guide for Setting Up the Upstack Data App in Shopify](/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify) * [Complete Upstack Data Onboarding Guide](/guides/getting-started/complete-upstack-data-onboarding-guide) # [DRAFT] Understanding Meta's Health & Wellness Flag Source: https://docs.upstackdata.com/guides/health-wellness/understanding-meta-health-wellness-flag Learn what Meta's Health & Wellness flag is, how it affects your ad performance, and why standard fixes like creating a new pixel don't work. Learn what Meta's Health & Wellness flag is, how it affects your ad performance, and why standard fixes like creating a new pixel don't work. ### What Is the Health & Wellness Flag? Meta categorizes certain stores — those selling supplements, wellness products, or health-related goods — under a restricted "Health & Wellness" category. Once your store is flagged, Meta applies stricter privacy and content policies that limit what data your pixel can collect and use for optimization. There is no notification from Meta when the flag is applied. Most brands discover it when they see unexplained performance declines or when events stop being accepted for optimization. ### Why Meta Created the Health & Wellness Category The policy originated after Hims & Hers gained public visibility through their IPO filings, which revealed how much they were spending on Facebook ads. Because their products are medical in nature, every customer who purchased through Facebook was effectively listed in Meta's database as buying a medical product — creating what amounts to a medical patient profile. Meta realized it was collecting protected health information at scale without the facilities to manage it, and faced significant legal liability. In response, Meta implemented a new layer of rules specifically around the **data** advertisers send back, on top of existing creative and landing page compliance requirements. The fundamental stance is "don't ask, don't tell" — Meta doesn't want to collect potentially problematic health data, and as long as you don't send it, there's no problem. ### How It Impacts Performance There is no uniform severity — Meta doesn't expose "levels" of the flag. However, brands typically see one of three patterns: **Minimal impact.** The flag appears but the brand sees no noticeable performance change. Everything continues to work as normal. **Steep drop-off.** Performance drops sharply right after the flag. Ad spend goes to near-zero or CPA spikes dramatically. **Slow decline.** A gradual decline over weeks or months. CPMs may rise (or sometimes drop to unrealistically low levels). Targeting degrades because Meta is optimizing on partial data. Eventually performance stabilizes at a lower baseline that becomes very hard to escape. ### What Gets Restricted The specifics vary, but common restrictions include: * **Loss of Purchase event optimization.** In some cases, brands lose the ability to optimize toward Purchase events entirely. Meta has an internal setting called **"core setup"** that is either on or off. When core setup is **on**, you typically cannot optimize toward Purchase events at all — this is the most severe level. * **Browser pixel data rejection.** Meta may restrict or ignore data sent from the browser pixel on the flagged domain. * **Reduced audience building.** With less event data flowing, custom audiences and lookalike audiences degrade over time. Meta flags specific keywords in context. For example, a term like "cramping" in the context of a magnesium supplement would be flagged because "cramping" is a medical condition. Product names, descriptions, SKUs, and URLs containing these terms all contribute to flagging. ### Can You Appeal the Flag? Yes, you can contest the flag through Meta's support channels, and some brands do win their appeal. However, winning an appeal does not guarantee a full resolution. There is a known issue where a **lingering overlay** can remain on your account even after a successful appeal — essentially a residual penalty on Meta's backend that continues to affect performance. The only way to remove this overlay is to work directly with a Meta representative, which typically costs between **$2,000 and $5,000**. Because of this uncertainty, many brands choose to implement a compliance solution (like Upstack's) rather than relying solely on the appeal process. ### The Key Fact: The Flag Is on Your Domain This is the most important thing to understand: **The Health & Wellness flag is attached to your domain, not your pixel.** Creating a new pixel and sending data from the same flagged domain will result in the new pixel also getting flagged. This is why simply swapping pixels doesn't solve the problem — and why domain aliasing is a core part of Upstack's solution. ### Next Steps Now that you understand the flag, learn how Upstack solves it: [How Upstack Data Solves Health & Wellness Restrictions →](/guides/health-wellness/how-upstack-solves-health-wellness-restrictions) Ready to get started? Follow the complete setup process: [How to Set Up a Health & Wellness Pixel for Meta →](/guides/health-wellness/setup-health-wellness-pixel-for-meta) ### Related Articles * [How Upstack Data Solves Health & Wellness Restrictions](/guides/health-wellness/how-upstack-solves-health-wellness-restrictions) * [How to Set Up a Health & Wellness Pixel for Meta](/guides/health-wellness/setup-health-wellness-pixel-for-meta) * [Health & Wellness Custom Event Mappings](/guides/facebook-ads/health-and-wellness-custom-event-mappings) # Automatic Form Capture Source: https://docs.upstackdata.com/guides/integrations/form-capture-integrations Automatic lead capture from Klaviyo, Postscript, Attentive, Omnisend, Sendlane, Recart, Listrak, Justuno, Alia, Octane AI, and Loop Subscriptions. Upstack Data detects form submissions and fires Lead events automatically. Upstack automatically detects and captures form submissions from popular email and SMS platforms. When a visitor submits a form on one of these platforms, we capture their email and/or phone number and fire appropriate tracking events. <Note> **Works on any website** — these integrations work on Shopify stores, headless storefronts, and custom websites. As long as the Upstack pixel and the third-party tool are both installed, form capture is automatic. </Note> <Tip> **No configuration required** — these integrations work automatically when both Upstack and the third-party tool are installed on your site. </Tip> ## How It Works When a visitor submits a signup form from a supported platform: 1. **Upstack detects the submission** automatically when both apps are installed 2. **Captures email and/or phone** from the form data 3. **Fires a `Lead` event** with the captured information 4. **Associates the session** with the captured identity 5. **Forwards to destinations** (Meta, TikTok, Klaviyo, etc.) *** ## Supported Platforms Upstack automatically captures signups from the following platforms: | Platform | Supported Forms | | ---------------------- | ------------------------------- | | **Klaviyo** | Popups, embedded forms, flyouts | | **Postscript** | SMS opt-in popups and forms | | **Attentive** | Two-tap creative, email capture | | **Omnisend** | Popups, signup boxes, wheels | | **Sendlane** | Popups and embedded forms | | **Recart** | Opt-in popups and tools | | **Listrak** | Email and SMS capture forms | | **Justuno** | Popups and embedded forms | | **Alia** | Signup popups | | **Octane AI** | Quiz lead capture | | **Loop Subscriptions** | Subscription management events | *** ## Events Fired When a visitor interacts with a supported form, the following events may fire: | Event | When It Fires | | ----------------------------- | ------------------------------------------------ | | `email_opt_in_form_displayed` | Popup or form becomes visible to visitor | | `Lead` | Visitor submits email and/or phone | | `email_opt_in_form_submitted` | Same as Lead — fired alongside for compatibility | | `email_opt_in_form_declined` | Visitor dismisses the form without submitting | All events include captured email/phone for identity resolution when available. *** ## Platform Details ### Recart Upstack automatically captures leads from Recart opt-in tools. **Events Captured:** * `recart:optin-tool:email-captured` * `recart:optin-tool:phone-number-captured` **Data Captured:** * Email address * Phone number * Opt-in tool ID * Opt-in tool name **Upstack Event Fired:** `Lead` *** ### Listrak Upstack automatically captures leads from Listrak forms. **Events Captured:** * `ltkEmailIdentityEvent` * `ltkPhoneIdentityEvent` **Data Captured:** * Email address * Phone number **Upstack Event Fired:** `Lead` *** ### Justuno Upstack automatically captures leads from Justuno popups and forms. **Detection Method:** Monitors form field changes for `ju_hidden_email` and `ju_hidden_sms` fields. **Data Captured:** * Email address (from `ju_hidden_email` field) * Phone number (from `ju_hidden_sms` field) **Upstack Event Fired:** `Lead` *** ### Alia Upstack automatically captures leads from Alia signup popups. **Events Captured:** * `alia:signup` **Data Captured:** * Email address * Phone number * Popup ID **Upstack Event Fired:** `Lead` *** ### Octane AI Quiz Upstack automatically tracks quiz interactions from Octane AI, including question responses, quiz completion, and lead capture. **Events Captured:** | Octane Event | Upstack Event | | ------------------------------ | --------------------------------------------------- | | `octane.quiz.questionAnswered` | `quiz_question_answered` | | `octane.quiz.completed` | `quiz_completed` + `Lead` (if email/phone captured) | | `octane.quiz.accessed` | `view_quiz_results` | **Data Captured:** * Quiz answer details * Email address (from lead capture step) * Phone number (from lead capture step) * Quiz completion status <Info> The `Lead` event fires automatically when email or phone is captured during quiz completion. </Info> *** ### Loop Subscriptions Upstack tracks subscription management events from Loop Subscriptions, enabling attribution for subscription-related cart actions. **Events Captured:** | Loop Event | Upstack Event | | ---------------------------------- | --------------------------- | | `loopAddAsOneTime` | `add_to_cart` | | `loopAddAsSubscription` | `add_to_cart` | | `loopBundleAddAsOneTime` | `add_to_cart` | | `loopBundleAddAsSubscription` | `add_to_cart` | | `loopItemAddToBundleSuccessEvent` | `add_to_cart` | | `loopByobAddToCartSuccessEvent` | `add_to_cart` | | `loopPresetAddToCartSuccessEvent` | `add_to_cart` | | `loopRemoveForOneTime` | `product_removed_from_cart` | | `loopRemoveFromSubscription` | `product_removed_from_cart` | | `loopBundleRemoveForOneTime` | `product_removed_from_cart` | | `loopBundleRemoveFromSubscription` | `product_removed_from_cart` | **Data Captured:** * Product ID * Variant ID * Product title * Price * Quantity <Note> Loop also fires additional subscription management events (pause, resume, cancel, etc.) that are tracked for analytics but not mapped to standard e-commerce events. </Note> *** ### What Destinations Receive When a form submission is detected, Upstack automatically forwards the event to your connected destinations: ```json theme={null} // Destination wire format (what Meta CAPI receives) { "event_name": "Lead", "event_time": "2026-02-18T14:39:00.000Z", "event_source_url": "https://example-store.com/", "user_data": { "em": "a1b2c3d4e5f6...hashed", "ph": "f6e5d4c3b2a1...hashed", "client_ip_address": "203.0.113.42", "client_user_agent": "Mozilla/5.0..." }, "custom_data": { "content_name": "Newsletter Signup" } } ``` <Note> You don't need to write any code for form capture integrations — Upstack detects and processes these automatically. </Note> *** ## Destination Forwarding Form submissions are automatically forwarded to your enabled destinations: | Destination | Event Received | Lead Data | | --------------------- | ----------------------- | ------------------------------ | | **Meta CAPI** | `Lead` | Email (hashed), phone (hashed) | | **TikTok Events API** | `SubmitForm` | Email (hashed), phone (hashed) | | **Google Ads** | `generate_lead` | Enhanced conversions data | | **Klaviyo** | Profile created/updated | Full PII | | **Attentive** | Subscriber created | Phone, email | <Note> Lead events are valuable for building audiences and measuring top-of-funnel performance, even if you don't optimize directly for leads. </Note> *** ## Identity Resolution When a form is submitted: 1. **Email is captured** and used as primary identifier 2. **Phone is captured** if provided (E.164 format) 3. **Session is associated** with the captured identity 4. **Cross-device matching** becomes possible for repeat visitors This means when a visitor who previously submitted a form returns to your site, Upstack can recognize them and attribute their behavior to the original touchpoint — even if they're on a different device. <Info> Identity resolution works across all form capture integrations and connects with data from [checkout identity capture](/sources/shopify-automatic-tracking#identity-capture). </Info> *** ## Troubleshooting <AccordionGroup> <Accordion title="Form submissions not tracking"> **Verify both apps are installed:** 1. Confirm Upstack is installed and active (check for events in the dashboard) 2. Confirm the third-party tool (Klaviyo, Postscript, etc.) is installed on your storefront 3. Test by submitting a form and checking the Live Event Stream in your Upstack dashboard **Check browser console:** Open browser DevTools (F12) and look for JavaScript errors that might prevent form detection. **Contact support:** If the form is from a supported platform but not tracking, contact support with the form URL for investigation. </Accordion> <Accordion title="Identity not resolving"> **Verify data format:** * Email must be a valid email format * Phone should be in E.164 format (e.g., `+14155551234`) **Check consent settings:** If the visitor hasn't granted analytics consent, identity resolution may be limited. **Allow time for resolution:** Identity stitching happens asynchronously. Check back in a few minutes if the identity doesn't appear immediately. </Accordion> <Accordion title="Events not forwarding to destinations"> **Check destination configuration:** 1. Go to **Integrations → Destinations** in your Upstack dashboard 2. Verify the destination is connected and active 3. Check that Lead events are enabled for that destination **Review event mapping:** Some destinations may map Lead events to different event names. Check the destination-specific documentation for details. </Accordion> </AccordionGroup> *** ## Related <CardGroup> <Card title="Standard Events" icon="list-check" href="/pixel/standard-events"> Full reference for Lead and other standard events. </Card> <Card title="Shopify Automatic Tracking" icon="shopify" href="/sources/shopify-automatic-tracking"> How checkout and storefront events are captured. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack connects visitor sessions across devices. </Card> <Card title="Meta CAPI" icon="meta" href="/destinations/meta-capi"> Configure Lead event forwarding to Meta. </Card> </CardGroup> # How to Connect your Google Ads Account in Upstack Data Integrations Source: https://docs.upstackdata.com/guides/integrations/how-to-connect-your-google-ads-account-in-upstack-data-integrations Connect your Google Ads account to Upstack Data so spend, impressions, and clicks pull into the dashboard for unified channel-level ROAS and attribution reporting. <Tip> **Quick Summary** * Sign in to [Upstack Data](https://app.upstackdata.com) and navigate to **[Data Integrations](https://app.upstackdata.com/pixel/integrations)**. * On the Google Ads row, click the **kebab menu** (3 dots) → **Connect**. * **Select the Google Ads account** you want to connect. </Tip> <Note> **Purpose of this setup** Connecting your Google Ads account is required to access performance data at the account, campaign, ad set, and ad levels, which powers your Upstack dashboards and attribution reporting. </Note> ## Prerequisites * An [Upstack Data](https://app.upstackdata.com) account with subscription active * A Google account with admin access to the Google Ads account you want to connect (Customer ID format: `123-456-7890`) * No active Google Ads OAuth session that conflicts with the account you want to connect (sign out of unrelated Google accounts in your browser if needed) ## Configuration Steps <Steps> <Step title="Sign in to Upstack Data"> Sign in to your [Upstack Data](https://app.upstackdata.com) account and navigate to **[Data Integrations](https://app.upstackdata.com/pixel/integrations)**. <img alt="Upstack Data dashboard with Data Integrations page open" /> </Step> <Step title="Start the Google Ads connection"> On the Data Integrations page, click the **kebab menu** (3 dots) on the Google Ads row → click **Connect**. <img alt="Google Ads row with kebab menu showing Connect option" /> **Choose the Google account** you want to connect with Upstack Data. <img alt="Google account selection screen for OAuth connection" /> Click **Continue**. <img alt="Google OAuth consent screen with Continue button" /> </Step> <Step title="Select the Google Ads account"> A popup displays all ad accounts linked to your Google account. **Select the Google Ads account** you want to connect. <img alt="Google Ads account selection popup with available ad accounts" /> </Step> <Step title="Save the configuration"> Click the **Save** button. <img alt="Save button to confirm Google Ads account connection" /> <Note> **Success!** You should see a confirmation message and the Google integration will appear as **Healthy** in your Data Integrations list. </Note> <img alt="Google Ads integration showing Healthy status in Data Integrations" /> </Step> <Step title="Verify the connection"> * On the [Data Integrations](https://app.upstackdata.com/pixel/integrations) page, confirm the Google Ads row shows status **Healthy**. * Open your Upstack dashboard reporting and confirm Google Ads spend and campaign data appear within 24 hours of connecting. </Step> </Steps> # How to boost Klaviyo abandonment revenue with Upstack Source: https://docs.upstackdata.com/guides/klaviyo-abandonment-flows/boost-klaviyo-abandonment-revenue Recover 30-40% more abandoned cart, browse, and checkout sessions by enabling Upstack's identity resolution alongside Klaviyo's native tracking. Upstack's Klaviyo identity enrichment identifies returning visitors that Klaviyo's native tracking misses, then pushes those profiles to Klaviyo in real time so your abandonment flows trigger for sessions that would otherwise be lost. Brands using this setup typically see 30–40% more profiles entering abandonment flows, directly increasing revenue from browse, cart, and checkout abandonment emails. This guide explains how the enrichment works, how to set up the "waterfall" flow architecture alongside your existing Klaviyo flows, and best practices for maximizing incremental revenue without over-messaging customers. ## The problem: Klaviyo misses returning visitors Klaviyo's abandonment flows are among the highest-revenue automated flows for DTC brands. But they only trigger when Klaviyo can identify who the visitor is, and Klaviyo's native tracking has significant blind spots. ### When Klaviyo loses identity * **Cross-device sessions.** A customer clicks your Instagram ad on their phone, browses products, then switches to their laptop. Klaviyo's browser cookie on the phone has no connection to the laptop session — that session is anonymous and no flow triggers. * **Cookie expiration.** Safari and most iOS browsers expire first-party cookies set via JavaScript within 7 days. A customer who visited 8 days ago and returns today looks like a brand-new anonymous visitor. * **In-app browser to default browser.** A customer taps a link in the Instagram or Facebook app, which opens an in-app browser with isolated cookie storage. When they later open Safari or Chrome on the same device, the session doesn't carry over. * **Ad blocker interference.** Klaviyo's client-side tracking JavaScript can be blocked by ad blockers, which roughly 30% of desktop users run. These visitors are completely invisible to Klaviyo's identification system. The cumulative effect: Klaviyo's native tracking typically identifies only 60–70% of visitors who could be matched to a known profile. The remaining 30–40% browse, add to cart, or start checkout — and leave without triggering any abandonment flow. ## How Upstack's Klaviyo identity enrichment works Upstack's [identity resolution](/pixel/identity-resolution) engine operates server-side, independent of the visitor's browser. It identifies returning visitors using signals that survive the limitations Klaviyo's client-side tracking faces: <Steps> <Step title="Server-side identity matching"> When a visitor arrives, Upstack matches server-side signals — IP address, user agent, device fingerprint, and hashed identifiers from previous sessions — against its identity graph. This works even when cookies are expired, the device is different, or the browser is blocking tracking scripts. </Step> <Step title="Session stitching"> Upstack connects fragmented sessions across devices and browsers into a single identity. The customer who browsed on their phone and returned on their laptop is recognized as the same person. </Step> <Step title="Real-time profile push to Klaviyo"> When Upstack identifies a visitor that Klaviyo doesn't recognize, it pushes the resolved profile — including email, browsing activity, and cart contents — to Klaviyo via API in real time. This enables Klaviyo flows to trigger for sessions that would otherwise be anonymous. </Step> </Steps> The result: abandonment flows fire for a significantly larger pool of identified sessions, without changing anything about your email content or flow logic. ## The "waterfall" flow architecture The recommended setup runs Upstack-triggered flows alongside your existing Klaviyo-native flows — not instead of them. Klaviyo's native tracking catches what it can, and Upstack catches what Klaviyo misses. <Tip> **Don't replace your native Klaviyo flows.** They serve different visitor pools. The goal is to add incremental coverage, not swap one set of flows for another. </Tip> ### How it works ``` Visitor arrives on your store │ ├── Klaviyo identifies them (cookie match, logged in, etc.) │ └── Native Klaviyo flow triggers → abandonment email sent │ └── Klaviyo does NOT identify them └── Upstack identifies them server-side └── Pushes profile to Klaviyo └── Upstack-triggered flow fires → abandonment email sent ``` Both paths lead to the same outcome — an abandonment email — but they catch different pools of visitors. The mutual exclusion window (covered below) prevents anyone from receiving both. ## Setup steps For complete onboarding, see [Onboarding Klaviyo in Upstack Data](/guides/klaviyo/complete-how-to-guide-for-onboarding-klaviyo-in-upstack-data) and [Setting up Upstack abandonment flows in Klaviyo](/guides/klaviyo-abandonment-flows/complete-guide-to-setting-up-upstack-abandonment-flows-in-klaviyo). The summary below covers the conceptual setup. <Steps> <Step title="Connect Klaviyo as a destination in Upstack"> Configure the Klaviyo destination so Upstack can push identified profiles and event data. Full instructions: [Klaviyo destination](/destinations/klaviyo). Once connected, Upstack begins sending identified profiles and their event data to Klaviyo when it resolves visitors that Klaviyo's native tracking missed. </Step> <Step title="Clone your Browse Abandonment flow"> 1. In Klaviyo, navigate to **Flows** and find your existing Browse Abandonment flow. 2. Clone the flow. 3. Rename the clone with the **` - Upstack Data`** suffix — for example, `Browse Abandonment - Upstack Data` — so you can distinguish it from the standard flow. Detailed walkthrough: [How to clone your standard flows in Klaviyo](/guides/klaviyo-abandonment-flows/how-to-clone-your-standard-flows-in-klaviyo). </Step> <Step title="Change the trigger to the Upstackified Klaviyo metric"> In the cloned flow, edit the trigger and change the source to the matching Upstack-emitted Klaviyo metric: * Browse Abandonment → **Viewed Product - Upstackified** * Cart Abandonment → **Added to Cart - Upstackified** * Checkout Abandonment → **Started Checkout - Upstackified** * Site Abandonment → **Active on Site - Upstackified** Upstack pushes these events to Klaviyo for sessions identified server-side rather than by Klaviyo's native tracking. </Step> <Step title="Add a 30-minute delay offset"> In the Upstack copy of the flow, add **+30 minutes** to the first wait step compared to the standard flow (for example, `1 hour` becomes `1 hour 30 minutes`). This serves two purposes: * It gives Klaviyo's native tracking time to identify the visitor on its own. If Klaviyo picks them up within those 30 minutes, the mutual exclusion filter (next step) prevents the Upstack flow from sending. * It aligns with the typical window in which visitors are most likely to return on their own, before the abandonment email is most effective. </Step> <Step title="Set mutual exclusion filters"> Add a profile filter on each flow's trigger so visitors don't receive abandonment emails from both flows: 1. On the **standard** flow, add: **Has received email 0 times in last 7 days where Flow = `[Upstack copy of the flow]`** (for example, `Abandoned Cart - Upstack Data`). 2. On the **Upstack copy** of the flow, add the reverse filter: **Has received email 0 times in last 7 days where Flow = `[Standard flow]`** (for example, `Abandoned Cart`). This 7-day mutual exclusion window prevents over-messaging. Detailed walkthrough: [Add cross-flow exclusion filters in Klaviyo](/guides/klaviyo-abandonment-flows/how-to-add-cross-flow-exclusion-filters-in-klaviyo). </Step> <Step title="Repeat for Cart, Checkout, and Site Abandonment"> Follow the same process for your Cart Abandonment, Checkout Abandonment, and Site Abandonment flows: clone with the ` - Upstack Data` suffix, change the trigger to the corresponding `*- Upstackified` event, add the 30-minute delay offset, and set mutual exclusion filters in both directions. </Step> <Step title="Match email content and step structure"> Your Upstack-triggered flows should use the same email templates, timing between steps, and step statuses (live/draft/manual) as your native flows. The visitor experience should be identical regardless of which flow they entered through — the only difference is how they were identified. </Step> <Step title="Set flows live and monitor"> 1. Set each Upstack flow to **Live** status. 2. Monitor performance over the first 7 days to verify events are flowing and emails are sending. </Step> </Steps> <Warning> **Mutual exclusion filters are required.** Without them, a customer identified by both Klaviyo and Upstack will receive duplicate abandonment emails. Always configure the 7-day exclusion in both directions. </Warning> ## Expected results Brands implementing the waterfall setup typically see: | Metric | Before enrichment | After enrichment | | ----------------------------------- | ----------------- | ---------------- | | Profiles entering abandonment flows | Baseline | +30–40% | | Browse abandonment flow revenue | Baseline | +25–35% | | Cart abandonment flow revenue | Baseline | +20–30% | | Total email-attributed revenue | Baseline | Measurable lift | The exact lift depends on your existing Klaviyo identification rate, traffic volume, and how much of your audience shops across multiple devices or returns after cookie expiration. Brands with high mobile and social media traffic see the largest improvement because those channels produce the most cross-device and in-app browser sessions. ## Best practices ### Run both flow sets in parallel — indefinitely Don't turn off your native Klaviyo flows when Upstack flows are running. They serve different visitor pools. Disabling native flows means you lose coverage for the visitors Klaviyo already identifies successfully. ### Track attribution separately Use UTM parameters to distinguish Upstack-triggered emails from native Klaviyo emails: * Native flow: `utm_source=klaviyo&utm_medium=email&utm_campaign=browse_abandon` * Upstack flow: `utm_source=klaviyo&utm_medium=email&utm_campaign=browse_abandon_upstack` This lets you measure incremental revenue contribution separately from your existing Klaviyo revenue — critical for understanding ROI. ### Monitor flow performance weekly In your first month, check these metrics weekly for each Upstack flow: * **Flow entry rate.** How many profiles are entering the Upstack flows? If it's near zero, the Klaviyo connection or trigger configuration may need attention. * **Email open and click rates.** These should be comparable to your native flows. If significantly lower, the identified profiles may be lower quality or the timing may need adjustment. * **Revenue per recipient.** The key metric. Compare this between native and Upstack flows to understand incremental value. * **Unsubscribe rate.** Monitor closely in the first two weeks. If Upstack flows show elevated unsubscribes, consider extending the delay or tightening exclusion filters. ### Adjust the delay window if needed The 30-minute delay is a starting point. If you find significant overlap between native and Upstack flows (visible as a high exclusion filter rate on the Upstack side), extend the delay to 45 or 60 minutes. If you're seeing very little overlap, you can shorten it to 15 minutes to trigger faster. ## Frequently asked questions <AccordionGroup> <Accordion title="Will Upstack replace my existing Klaviyo flows?"> No. Upstack's Klaviyo enrichment is designed to run alongside your existing flows, not replace them. Your native Klaviyo flows continue to catch visitors that Klaviyo identifies on its own. Upstack flows catch the visitors Klaviyo misses. Both run in parallel with mutual exclusion filters to prevent overlap. </Accordion> <Accordion title="How does Upstack identify visitors that Klaviyo can't?"> Upstack uses server-side identity resolution — matching visitors through a combination of server-side signals (IP, user agent, device fingerprint, hashed identifiers) against an identity graph built from previous sessions. This works independent of browser cookies, so it survives cross-device transitions, cookie expiration, and in-app browser isolation that break Klaviyo's client-side tracking. </Accordion> <Accordion title="Will this cause customers to receive duplicate emails?"> Not if you set up mutual exclusion filters correctly. The 7-day exclusion window ensures that a customer identified by both Klaviyo and Upstack only receives one abandonment email. The 30-minute delay on Upstack flows gives Klaviyo's native tracking first priority. </Accordion> <Accordion title="How long does it take to see results?"> You should see profiles entering Upstack flows within 24 hours of going live. Meaningful revenue data typically requires 7–14 days of flow activity, depending on your traffic volume and conversion rates. </Accordion> <Accordion title="Can I use Upstack identity enrichment for flows other than abandonment?"> Yes. While abandonment flows are the highest-impact use case, Upstack's identified profiles can trigger any Klaviyo flow — win-back campaigns, post-purchase sequences, or custom flows based on specific browsing behavior. The same waterfall principle applies. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Klaviyo destination" icon="plug" href="/destinations/klaviyo"> Configure the Klaviyo destination to enable identity-enriched profile delivery. </Card> <Card title="Onboarding Klaviyo in Upstack" icon="rocket" href="/guides/klaviyo/complete-how-to-guide-for-onboarding-klaviyo-in-upstack-data"> End-to-end Klaviyo onboarding inside Upstack. </Card> <Card title="Set up Upstack abandonment flows" icon="bolt" href="/guides/klaviyo-abandonment-flows/complete-guide-to-setting-up-upstack-abandonment-flows-in-klaviyo"> Step-by-step Klaviyo flow setup with cloning, delays, and exclusions. </Card> <Card title="Clone your standard flows" icon="copy" href="/guides/klaviyo-abandonment-flows/how-to-clone-your-standard-flows-in-klaviyo"> Detailed clone procedure for each standard abandonment flow. </Card> <Card title="Cross-flow exclusion filters" icon="filter" href="/guides/klaviyo-abandonment-flows/how-to-add-cross-flow-exclusion-filters-in-klaviyo"> Configure mutual exclusion between native and Upstack flows. </Card> <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack's server-side identity engine works. </Card> </CardGroup> # Complete Guide to Setting Up Upstack Abandonment Flows in Klaviyo Source: https://docs.upstackdata.com/guides/klaviyo-abandonment-flows/complete-guide-to-setting-up-upstack-abandonment-flows-in-klaviyo Set up Upstack-enhanced abandonment flows in Klaviyo — clone standard flows, swap triggers, add cross-flow exclusions, and recover 30-50% more browse, cart, and checkout abandonment revenue. <Tip> **Quick Summary** * In Klaviyo, enable account-wide UTM tracking under **Account → Settings → Other → UTM Tracking** * Locate the **standard abandonment flow** in **Flows** * **Enable UTM tracking for every Email and SMS node** inside the standard flow * **Clone** the standard flow * Rename the clone with the **` - Upstack Data`** suffix → switch trigger to the corresponding `*- Upstackified` Klaviyo metric * Open the standard and Upstack copies of the flow **side-by-side** * **Add a 30-minute delay** to the Upstack copy * Set cross-flow exclusion filters to **7 days** (or 14 days if preferred) * Adjust re-entry timing to **7 days** * Set the Upstack copy of the flow to **Live** * **Match the live/draft status of every step** in the Upstack copy to the standard flow </Tip> ## Prerequisites Before you start, you need: * The **Klaviyo destination configured in Upstack Data** ([learn how](/guides/klaviyo/how-to-configure-klaviyo-destination-in-upstack-data)) * Existing **standard abandonment flows** in your Klaviyo account (Browse, Cart, Checkout, Site) * **Admin (manager) access** to the store's Klaviyo account * Confirm the following Upstack-emitted events appear in Klaviyo under **Analytics → Metrics**: * **Viewed Product - Upstackified** * **Added to Cart - Upstackified** * **Started Checkout - Upstackified** * **Active on Site - Upstackified** ## Important Terms <Note> * **Standard flow** → the existing abandonment flow already in the brand/store's Klaviyo account. * **Upstack copy of the flow** → the cloned and modified version triggered by Upstack Data's `*- Upstackified` events. Always identifiable by the ` - Upstack Data` name suffix. </Note> ## Configuration Steps <Steps> <Step title="Sign in to Klaviyo"> Sign in to **[Klaviyo](https://www.klaviyo.com/login)**. </Step> <Step title="Enable account-wide UTM tracking"> In Klaviyo, click your **profile icon** in the bottom-left navigation and go to **Settings → Other → UTM Tracking**, then ensure UTM tracking is toggled on. Detailed walkthrough: [How to enable UTM tracking in Klaviyo](/guides/klaviyo-abandonment-flows/how-to-enable-utm-tracking-in-klaviyo). </Step> <Step title="Locate the standard abandonment flows"> * In Klaviyo, go to **Flows** in the left navigation. * Use the search bar and type **`abandon`**. * Identify the four standard abandonment flows: * **Cart Abandonment** * **Browse Abandonment** * **Site Abandonment** * **Checkout Abandonment** <img alt="Klaviyo Flows page showing search results for abandonment flows" /> </Step> <Step title="Enable UTM tracking on every Email and SMS node"> <Note> Before cloning, make sure **Enable UTM Tracking** is checked on **every Email and SMS node** inside the standard flow. The setting is copied into the clone, so enabling it now saves rework. </Note> * In **Flows**, open the standard flow. <img alt="Klaviyo standard abandonment flow open in flow editor" /> * Click an **Email** or **SMS** node. * In the right-hand details panel, check **Enable UTM Tracking**. * Click **Save**. <img alt="Email node settings panel with Enable UTM Tracking checkbox" /> <Warning> Repeat this step for **every Email and SMS node** inside the standard flow. </Warning> </Step> <Step title="Clone the standard flow"> Clone each standard flow and rename the clone with the ` - Upstack Data` suffix (for example, `Abandoned Cart - Upstack Data`). When cloning, change the trigger to the corresponding `*- Upstackified` event: * Browse Abandonment → **Viewed Product - Upstackified** * Cart Abandonment → **Added to Cart - Upstackified** * Checkout Abandonment → **Started Checkout - Upstackified** * Site Abandonment → **Active on Site - Upstackified** Detailed walkthrough: [How to clone your standard flows in Klaviyo](/guides/klaviyo-abandonment-flows/how-to-clone-your-standard-flows-in-klaviyo). </Step> <Step title="Open the standard and Upstack copies side-by-side"> To make comparing settings easier, keep: * The **standard flow** in one browser tab. * The **Upstack copy of the flow** in another tab. </Step> <Step title="Add a 30-minute delay to the Upstack copy"> In the **Upstack copy of the flow**, add **+30 minutes** to the first wait step compared to the standard flow. *Example: `1 hour` → `1 hour 30 minutes`* <img alt="Wait step configured with 1 hour 30 minutes delay in Upstack flow" /> </Step> <Step title="Add cross-flow exclusion filters"> <Note> **Purpose:** Prevent someone from entering both the standard and Upstack copies within a 7-day window, which would result in duplicate emails. </Note> Add a filter on each flow's trigger: * On the **standard flow**: **Has received email 0 times in last 7 days where Flow = `[Upstack copy of the flow]`** * On the **Upstack copy of the flow**: **Has received email 0 times in last 7 days where Flow = `[Standard flow]`** Detailed walkthrough: [How to add cross-flow exclusion filters in Klaviyo](/guides/klaviyo-abandonment-flows/how-to-add-cross-flow-exclusion-filters-in-klaviyo). </Step> <Step title="Turn on the Upstack copy of the flow"> * Open the **Upstack copy of the flow**. * In the top-right of the page, click the **Review and turn on** button. <img alt="Review and turn on button in Klaviyo flow editor" /> * In the right-side panel that appears, set **Flow status** to **Live**. * Select **Update status now**. * Click **Save**. <img alt="Flow status panel with Live option selected and Save button" /> </Step> <Step title="Match step statuses to the standard flow"> * In the **standard flow**, note which steps are **Live** vs **Draft / Manual**. * In the **Upstack copy of the flow**, set each corresponding step to the **same status**. * Double-check that every step's status matches the standard flow before continuing. </Step> <Step title="Verify the setup"> * Confirm the Upstack copy of the flow is **Live** and that step statuses mirror the standard flow exactly. * In Klaviyo, open **Analytics → Metrics** and confirm the corresponding `*- Upstackified` event is recording activity (within minutes of live traffic). * In **Flows**, open the Upstack copy and check the **Analytics** tab over the first 24–48 hours to confirm profiles are entering the flow. * Spot-check a recipient profile to confirm they did **not** also receive the standard flow's email within the same 7-day window. </Step> </Steps> ## Best Practices * Always confirm timing and messaging changes between the standard flow and the Upstack copy. * Test triggers to ensure the `*- Upstackified` events are firing correctly. * Monitor reporting weekly after launch to assess performance. <Warning> **Repeat every step** for **each** standard abandonment flow: Cart, Browse, Site, and Checkout Abandonment. </Warning> <Note> **Need help or found an issue?** If you encounter any issues or have questions while following this guide, you may reach out to us at **[support@upstackdata.com](mailto:support@upstackdata.com)** </Note> # How to Add Cross-Flow Exclusion Filters in Klaviyo Source: https://docs.upstackdata.com/guides/klaviyo-abandonment-flows/how-to-add-cross-flow-exclusion-filters-in-klaviyo Add cross-flow exclusion filters in Klaviyo so the same shopper can't enter multiple Upstack abandonment flows within overlapping windows — preventing over-emailing and duplicate sends. ## Why this Step Matters <Note> The purpose of cross-flow exclusion filters is to **prevent someone from entering both the standard flow and the Upstack copy of the flow within a set timeframe.** This avoids overlapping or duplicate messages, ensuring a smoother customer experience, reducing message fatigue, and keeping your reporting data clean. </Note> ## Prerequisites Before you start, you need: * The **Klaviyo destination configured in Upstack Data** * **Existing standard abandonment flows** in your Klaviyo account (Browse, Cart, Checkout, Site) * The **Upstack copy of each abandonment flow** already cloned and renamed with the ` - Upstack Data` suffix ([learn how](/guides/klaviyo-abandonment-flows/how-to-clone-your-standard-flows-in-klaviyo)) * Admin (manager) access to the store's Klaviyo account <Note> **Key terms used below:** * **Standard flow** → the original abandonment flow in your Klaviyo account (for example, `Abandoned Cart`). * **Upstack copy of the flow** → the cloned version triggered by Upstack Data's `*- Upstackified` events, named with the ` - Upstack Data` suffix (for example, `Abandoned Cart - Upstack Data`). </Note> ## Part 1: Add the exclusion filter to the standard flow * Open the **standard flow** (for example, `Abandoned Cart`) in Klaviyo. * Click the **Trigger** card at the top of the flow. <img alt="Klaviyo flow editor with Trigger card selected at top of flow" /> * Go to **Profile filters** and click **Edit**. * Scroll to the bottom of the existing profile filters and click **+ AND**. <img alt="Profile filters section with Edit button and AND condition option" /> * Select the condition: **What someone has done (or not done)**. * Choose **Person has** → **Received Email**. * Set the count and timeframe: **zero times** → **in the last 7 days** *(or 14 days if preferred)*. * Click **Where** and add: **Flow** **equals** the **Upstack copy of this flow**. For example: `Flow equals Abandoned Cart - Upstack Data`. Read as: **Has received email 0 times in last 7 days where Flow = `Abandoned Cart - Upstack Data`**. * Click **Save**. <img alt="Cross-flow exclusion filter configured with zero emails in last 7 days" /> ## Part 2: Add the reverse exclusion filter to the Upstack copy of the flow * Open the **Upstack copy of the flow** (for example, `Abandoned Cart - Upstack Data`) in Klaviyo. * Click the **Trigger** card at the top of the flow. <img alt="Upstack copy of flow with Trigger card selected for editing" /> * Go to **Profile filters** and click **Edit**. * Scroll to the bottom of the existing profile filters and click **+ AND**. <img alt="Profile filters Edit panel with AND condition button" /> * Select the condition: **What someone has done (or not done)**. * Choose **Person has** → **Received Email**. * Set the count and timeframe: **zero times** → **in the last 7 days** *(or 14 days if preferred)*. * Click **Where** and add: **Flow** **equals** the **standard flow**. For example: `Flow equals Abandoned Cart`. Read as: **Has received email 0 times in last 7 days where Flow = `Abandoned Cart`**. * Click **Save**. <img alt="Reverse exclusion filter referencing the standard flow name" /> ## Part 3: Verify both filters are in place * On the **standard flow** trigger, confirm the profile filter references the **Upstack copy** name (for example, `Abandoned Cart - Upstack Data`). * On the **Upstack copy of the flow** trigger, confirm the profile filter references the **standard flow** name (for example, `Abandoned Cart`). * Spot-check a recipient profile after going live: confirm they only receive an email from one of the two flows within the 7-day window. <Note> **Done 🎉** Repeat both Part 1 and Part 2 for **each** abandonment flow pair: Cart, Browse, Site, and Checkout. For the full setup walkthrough, see [How to set up your Upstack abandonment flows in Klaviyo](/guides/klaviyo-abandonment-flows/complete-guide-to-setting-up-upstack-abandonment-flows-in-klaviyo). </Note> <Note> **Need help or found an issue?** If you encounter any issues or have questions while following this guide, reach out to us at **[support@upstackdata.com](mailto:support@upstackdata.com)**. </Note> # How to Clone your Standard Flows in Klaviyo Source: https://docs.upstackdata.com/guides/klaviyo-abandonment-flows/how-to-clone-your-standard-flows-in-klaviyo Clone your existing Klaviyo standard abandonment flows so the Upstack-enhanced versions inherit your branding, copy, and timing — preserving your design while triggering on Upstack events. ## Prerequisites Before you start, you need: * The **Klaviyo destination configured in Upstack Data** * **Existing standard abandonment flows** in your Klaviyo account (Browse, Cart, Checkout, Site) * **Admin (manager) access** to the store's Klaviyo account * The following Upstack-emitted events present in Klaviyo (under **Analytics → Metrics**): * **Viewed Product - Upstackified** * **Added to Cart - Upstackified** * **Started Checkout - Upstackified** * **Active on Site - Upstackified** <Note> **Key terms:** * **Standard flow** → the existing abandonment flow in the brand/store's Klaviyo account (for example, `Abandoned Cart`). * **Upstack copy of the flow** → the cloned and modified version triggered by Upstack Data's `*- Upstackified` events. Always identifiable by the ` - Upstack Data` name suffix (for example, `Abandoned Cart - Upstack Data`). </Note> ## Trigger mapping Use this mapping when changing the trigger on the cloned flow: | Standard flow | Upstack trigger event | | -------------------- | ----------------------------------- | | Browse Abandonment | **Viewed Product - Upstackified** | | Cart Abandonment | **Added to Cart - Upstackified** | | Checkout Abandonment | **Started Checkout - Upstackified** | | Site Abandonment | **Active on Site - Upstackified** | ## Configuration Steps <Steps> <Step title="Sign in to Klaviyo"> Sign in to **[Klaviyo](https://www.klaviyo.com/login)**. </Step> <Step title="Clone the standard flow"> * In the left navigation, go to **Flows** and open the **standard flow** you want to clone. * In the far-right column of the flow's row, click the **vertical three-dot (kebab) menu** and select **Clone**. <img alt="Klaviyo flows list with kebab menu showing Clone option for a flow" /> * A right-side panel will slide in, prompting you to specify the **new flow name** for the clone. * Name the clone the same as the original, plus the **` - Upstack Data`** suffix. For example: `ABC | Pre | Added to Cart | Flow | Abandoned Cart` becomes `ABC | Pre | Added to Cart | Flow | Abandoned Cart - Upstack Data`. * Click **Continue**. <img alt="Clone flow panel with name field showing Upstack Data suffix" /> * Change the **Trigger** to the matching `*- Upstackified` Klaviyo metric using the **Trigger mapping** table above (for example, **Viewed Product - Upstackified** for Browse Abandonment). * Save by clicking **Clone Flow**. <img alt="Clone Flow button with Upstackified trigger event selected" /> * A confirmation modal will let you know you'll receive a notification once the cloned flow is ready to edit. Click **Got it** to proceed. <img alt="Confirmation modal indicating cloned flow will be ready to edit" /> </Step> <Step title="Verify the clone"> * Once Klaviyo finishes cloning, open the new flow and confirm: * The flow name ends with **` - Upstack Data`**. * The **Trigger** is set to the correct `*- Upstackified` event from the trigger mapping table above. * The flow is in **Draft** status (you'll set it Live later in the [setup guide](/guides/klaviyo-abandonment-flows/complete-guide-to-setting-up-upstack-abandonment-flows-in-klaviyo)). </Step> </Steps> <Note> **Done 🎉** Repeat these steps for **each** standard abandonment flow: **Cart, Browse, Site, and Checkout Abandonment**. For the full setup walkthrough, see [How to set up your Upstack abandonment flows in Klaviyo](/guides/klaviyo-abandonment-flows/complete-guide-to-setting-up-upstack-abandonment-flows-in-klaviyo). </Note> <Note> **Need help or found an issue?** If you encounter any issues or have questions while following this guide, reach out to us at **[support@upstackdata.com](mailto:support@upstackdata.com)**. </Note> # How to Enable UTM Tracking in Klaviyo Source: https://docs.upstackdata.com/guides/klaviyo-abandonment-flows/how-to-enable-utm-tracking-in-klaviyo Enable UTM tracking in Klaviyo so emails sent from Upstack-enhanced abandonment flows attribute their conversions correctly back to the email channel in Upstack Analytics. ## Prerequisites Before you start, you need: * The **Klaviyo destination configured in Upstack Data** * **Admin (manager) access** to the store's Klaviyo account * The following Upstack-emitted events present in Klaviyo (under **Analytics → Metrics**): * **Viewed Product - Upstackified** * **Added to Cart - Upstackified** * **Started Checkout - Upstackified** * **Active on Site - Upstackified** ## Configuration Steps <Steps> <Step title="Sign in to Klaviyo"> Sign in to **[Klaviyo](https://www.klaviyo.com/login)**. </Step> <Step title="Open the UTM Tracking settings"> * In Klaviyo, click your **profile icon / account name** in the bottom-left navigation. * Go to **Settings → Other → UTM Tracking**. <img alt="Klaviyo Settings menu with UTM Tracking option under Other section" /> </Step> <Step title="Enable account-wide UTM tracking"> * At the bottom of the UTM parameter list, toggle on **Automatically add UTM parameters to links**. * Click the **Add UTM parameter** button. * Set **UTM Parameter Name** to **`up_kprofile_id`**, then set both the **Campaign value** and the **Flow value** to **Klaviyo profile id**. * Confirm the UTM parameter named **Campaign (`utm_campaign`)** is enabled, with **Campaign value** set to **Campaign name** and **Flow value** set to **Flow name**. * Confirm the UTM parameter named **Id (`utm_id`)** is enabled, with **Campaign value** set to **Campaign name (campaign id)** and **Flow value** set to **Flow message name (flow message id)**. * Click **Save** in the top-right of the page. <img alt="Klaviyo UTM Tracking settings with up_kprofile_id parameter configured" /> </Step> <Step title="Verify UTM tracking is enabled"> * Reload the **Settings → Other → UTM Tracking** page and confirm: * **Automatically add UTM parameters to links** is toggled **on**. * The **`up_kprofile_id`**, **`utm_campaign`**, and **`utm_id`** parameters are all enabled with the values configured above. * Send yourself a test email from any flow and confirm the links in the email contain `up_kprofile_id`, `utm_campaign`, and `utm_id` query parameters. </Step> </Steps> <Note> **Done 🎉** Continue with the full setup walkthrough: [How to set up your Upstack abandonment flows in Klaviyo](/guides/klaviyo-abandonment-flows/complete-guide-to-setting-up-upstack-abandonment-flows-in-klaviyo). </Note> <Note> **Need help or found an issue?** If you encounter any issues or have questions while following this guide, reach out to us at **[support@upstackdata.com](mailto:support@upstackdata.com)**. </Note> # Complete How-To Guide for Onboarding Klaviyo in Upstack Data Source: https://docs.upstackdata.com/guides/klaviyo/complete-how-to-guide-for-onboarding-klaviyo-in-upstack-data Onboard Klaviyo in Upstack Data — generate the Private API key, configure the destination, and clone abandonment flows to lift triggered abandoned cart, checkout, and browse revenue 40%+. <Info> **New to Upstack?** Follow the [getting started guide](/get-started/install-on-shopify) for a streamlined onboarding walkthrough. </Info> <Tip> **Quick Summary** Complete Klaviyo integration requires three essential steps plus a critical follow-up for maximum value from your setup. * Generate a **Klaviyo Private API key** with Full Access in Klaviyo. * Connect Klaviyo in the **[Upstack dashboard](https://app.upstackdata.com/pixel/event-destinations)** using the Klaviyo Private API key. * Contact **[support@upstackdata.com](mailto:support@upstackdata.com)** to activate Upstack abandonment flows. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to a **Klaviyo** account * The ability to generate a **Klaviyo Private API key** with Full Access ([learn how to generate one](/guides/klaviyo/how-to-generate-klaviyo-api-key-for-upstack-data)) ## Part 1: Generate a Klaviyo Private API key * Sign in to **[Klaviyo](https://www.klaviyo.com/login)**. * Click your **profile icon** in the bottom-left navigation. * Go to **Settings → Account → API Keys**. * Click the **Create Private API Key** button. * Name the new key **`UpstackData`**. * Under *Select Access Level*, choose **Full Access Key**. * Click **Create**. * Copy and save the Klaviyo Private API key immediately. It starts with `pk_` followed by alphanumeric characters (for example, `pk_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678`). <img alt="Klaviyo API Keys page with Create Private API Key button" /> **`Important:`** `This key will only be shown once.` Need a more detailed walkthrough? See [How to generate a Klaviyo Private API key for Upstack Data](/guides/klaviyo/how-to-generate-klaviyo-api-key-for-upstack-data). ## Part 2: Configure the Klaviyo destination in the Upstack dashboard * Sign in to **[Upstack Data](https://app.upstackdata.com)**. * In the Upstack dashboard, navigate to **[Pixel → Event Destinations](https://app.upstackdata.com/pixel/event-destinations)**. * Click **+ New Destination** in the top-right of the page. * In the *Select a Destination* popup, choose **Klaviyo** and click **Next**. * Paste your **Klaviyo Private API key** into the *Private API Key* field. * Click **Create Configuration**. <img alt="Upstack Event Destinations page with Klaviyo configuration form" /> **`Success!`** `Klaviyo is now connected to Upstack Data.` Need a more detailed walkthrough? See [How to configure the Klaviyo destination in Upstack Data](/guides/klaviyo/how-to-configure-klaviyo-destination-in-upstack-data). ## Part 3: Verify the connection * In the Upstack dashboard, go to **Pixel → Event Destinations**. * Confirm the **Klaviyo** destination is listed with a **Healthy** status. * In Klaviyo, go to **Analytics → Metrics** and confirm Upstack-emitted events (for example, **Viewed Product - Upstackified**, **Added to Cart - Upstackified**, **Started Checkout - Upstackified**, **Active on Site - Upstackified**) begin appearing within a few minutes of live traffic. <Warning> After completing the Klaviyo setup, contact **[support@upstackdata.com](mailto:support@upstackdata.com)** to request your Upstack abandonment flows be set up. These additive flows improve your abandonment capture by **up to 40% or more**. </Warning> # How to Configure Klaviyo Destination in Upstack Data Source: https://docs.upstackdata.com/guides/klaviyo/how-to-configure-klaviyo-destination-in-upstack-data Configure the Klaviyo destination in Upstack Data with your Klaviyo Private API key and verify identity-resolved events sync to power abandonment flow recovery. <Tip> **Quick Summary** * In the **[Upstack dashboard](https://app.upstackdata.com/pixel/event-destinations)**, go to **Pixel → Event Destinations** and click **+ New Destination** * Select **Klaviyo** from the destination options * Enter your **Klaviyo Private API key** * Click **Create Configuration** and verify the destination is **Healthy** </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to a **Klaviyo** account * A **Klaviyo Private API key** with Full Access ([learn how to generate one](/guides/klaviyo/how-to-generate-klaviyo-api-key-for-upstack-data)) ## Configuration Steps <Steps> <Step title="Sign in to Upstack Data"> Sign in to **[Upstack Data](https://app.upstackdata.com)**. </Step> <Step title="Open the Event Destinations page"> * In the Upstack dashboard, navigate to **Pixel → Event Destinations** (or open it directly: **[Event Destinations](https://app.upstackdata.com/pixel/event-destinations)**). * Click **+ New Destination** in the top-right of the page. <img alt="Add New Destination" /> * In the *Select a Destination* popup, click **Klaviyo**. * Click **Next**. <img alt="Select Klaviyo as Destination" /> </Step> <Step title="Enter your Klaviyo Private API key"> Paste your **Klaviyo Private API key** into the *Private API Key* field. The key starts with `pk_` followed by alphanumeric characters (for example, `pk_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678`). <img alt="Klaviyo destination configuration form with Private API Key field" /> `Important: Ensure there are no extra spaces before or after the key.` <Note> Need to generate the key first? See [How to generate a Klaviyo Private API key for Upstack Data](/guides/klaviyo/how-to-generate-klaviyo-api-key-for-upstack-data). </Note> </Step> <Step title="Create the configuration"> Click the **Create Configuration** button to save the setup. <img alt="Create Configuration button to save Klaviyo destination setup" /> <Note> **Success! 🎉** You should see a confirmation message and the Klaviyo destination will appear as **Healthy** in your destinations list. </Note> <img alt="Klaviyo destination showing Healthy status in destinations list" /> </Step> <Step title="Verify events are flowing to Klaviyo"> * In the Upstack dashboard, return to **Pixel → Event Destinations** and confirm the **Klaviyo** row shows a **Healthy** status. * In Klaviyo, navigate to **Analytics → Metrics** and confirm Upstack-emitted events (for example, **Viewed Product - Upstackified**, **Added to Cart - Upstackified**, **Started Checkout - Upstackified**, **Active on Site - Upstackified**) appear within a few minutes of live traffic on your store. </Step> </Steps> <Warning> After completing setup, contact **[support@upstackdata.com](mailto:support@upstackdata.com)** to request your Upstack abandonment flows be set up. These additive flows improve your abandonment capture by **up to 40% or more**. </Warning> # How to Generate Klaviyo API Key for Upstack Data Source: https://docs.upstackdata.com/guides/klaviyo/how-to-generate-klaviyo-api-key-for-upstack-data Generate a Klaviyo Private API key with Full Access permissions to authenticate the Upstack Data Klaviyo destination and enable identity-enriched event sync. <Tip> **Quick Summary** * In Klaviyo, navigate to **Settings → Account → [API Keys](https://www.klaviyo.com/create-private-api-key)** * Click **Create Private API Key** * Name it **`UpstackData`** and select **Full Access Key** * **Copy and save** the key securely (it starts with `pk_`) </Tip> ## Prerequisites Before you start, you need: * Admin access to a **Klaviyo** account (required to create Private API keys) * Permission to grant **Full Access** to API keys ## Steps to Generate the Klaviyo Private API key <Steps> <Step title="Sign in to Klaviyo"> Sign in to **[Klaviyo](https://www.klaviyo.com/login)**. </Step> <Step title="Open the API Keys settings"> * Click your **profile icon** in the bottom-left navigation. * Go to **Settings → Account → [API Keys](https://www.klaviyo.com/create-private-api-key)**. <img alt="Klaviyo profile icon and Settings menu in bottom-left navigation" /> `Settings menu` <img alt="Klaviyo Account settings with API Keys option" /> `API keys menu` </Step> <Step title="Create a new Private API key"> Click the **Create Private API Key** button. <img alt="Create Private API Key button in Klaviyo" /> </Step> <Step title="Configure key name and access level"> * Name your Klaviyo Private API key **`UpstackData`**. * Under *Select Access Level*, choose **Full Access Key**. * Click the **Create** button. <img alt="API key creation form with name field and Full Access Key selected" /> <Warning> Full Access is required for all Upstack Data features to work properly. </Warning> </Step> <Step title="Copy and save your Klaviyo Private API key"> Copy the generated key immediately. It starts with `pk_` followed by alphanumeric characters (for example, `pk_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678`). <img alt="Generated Klaviyo Private API key with copy button" /> <Warning> This key will only be shown once. Store it securely — you will need it to configure the Klaviyo destination in the Upstack dashboard. </Warning> </Step> <Step title="Verify the key was created"> * Return to **Settings → Account → API Keys** in Klaviyo. * Confirm the new **`UpstackData`** key appears in the list with **Full Access** permissions. * Continue to [How to configure the Klaviyo destination in Upstack Data](/guides/klaviyo/how-to-configure-klaviyo-destination-in-upstack-data) to paste the key into the Upstack dashboard. </Step> </Steps> # Klaviyo integration and abandonment flows Source: https://docs.upstackdata.com/guides/klaviyo/klaviyo-integration-and-abandonment-flows How the Upstack Klaviyo integration works, why Klaviyo misses some visitors, how cloned abandonment flows recover more revenue, and how to troubleshoot them. ## How does the Klaviyo integration work? Upstack connects to Klaviyo through a private API key — create a full-access key in Klaviyo and add it in the Upstack dashboard. That's the entire connection step. Once connected, Upstack: 1. Uses Klaviyo profile data to enrich events sent to Meta, improving Event Match Quality scores. 2. Re-identifies returning visitors that Klaviyo no longer recognizes, putting them back through your abandonment flows. ## Why does Klaviyo miss some visitors? When someone opts in (for example, enters their email for a discount), Klaviyo records their identity in that browser session. If they return later in a different browser — say they clicked an ad in the Instagram app and come back in Safari — Klaviyo treats them as unknown, and their activity won't trigger an abandonment flow. Upstack's identity resolution reconnects that visitor to their known profile and sends the information back to Klaviyo, which then triggers the flow as expected. ## How do the cloned abandonment flows work? The Upstack team clones your existing flows and sets them up in a waterfall: 1. Your standard Klaviyo flow fires first (unchanged). 2. After a 30-minute delay, the Upstack flow fires. 3. Anyone who received one flow is excluded from the other. No duplicate emails. The cloned flows use the same content, design, and steps as your originals — the only differences are the trigger event, the delay, and the exclusion filters. ## Which flows are cloned? Up to four, depending on your setup: browse abandonment, cart abandonment, site abandonment, and checkout abandonment. After setup, you'll have two versions of each in Klaviyo — the standard one and the Upstack Data one. ## What improvement should I expect? Most stores see a 30–40% increase in abandonment flow volume — meaning that many more people are identified and entering flows. This translates directly to additional recovered revenue from emails that wouldn't have been sent otherwise. The improvement compounds over time as Upstack builds a larger visitor profile. ## Who sets up the flows? The Upstack team handles flow cloning for you. During onboarding, you invite the team to your Klaviyo account. Setup is typically completed within 48 to 72 hours. Your existing flows remain unchanged. ## Troubleshooting * **Flows not sending emails** — Verify both the standard and Upstack flows are set to Live in Klaviyo, and that each email step matches the status of the original. * **Low volume on Upstack flows** — Expected in the first few days. If volume stays low after two weeks, confirm no other tool (for example, Triple Whale) is running conflicting flows. If you run into issues, reach out to [support@upstackdata.com](mailto:support@upstackdata.com). * **Duplicate emails** — Check that exclusion windows are set correctly (recommended: 7 days) and that both flows reference each other in their filters. # Complete How-To Guide for Onboarding LinkedIn Ads in Upstack Data Source: https://docs.upstackdata.com/guides/linkedin-ads/complete-how-to-guide-for-onboarding-linkedin-in-upstack-data Onboard LinkedIn Ads in Upstack Data — locate your Partner ID, create conversion rules, generate the Conversions API token, configure the destination, and enable click ID tracking. <Info> **New to Upstack?** Follow the [getting started guide](/get-started/install-on-shopify) for a streamlined onboarding walkthrough. </Info> <Tip> * Configure the **LinkedIn destination** in Upstack Data with your **Partner ID**, **API Access Token**, and **Conversion Rule IDs**. * Create **Conversion Rules** in LinkedIn Campaign Manager for each event type you want to track. * Enable **Enhanced Conversion Tracking** to capture `li_fat_id` click IDs. * Verify events appear in **LinkedIn Campaign Manager → Data → Signal Diagnostics**. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to a **LinkedIn Ads** account with the **Campaign Manager** role * The **LinkedIn Insight Tag** installed on your storefront (Upstack will fire it alongside server-side events) * Shopify owner/staff access (if applicable) <Steps> <Step title="Find your LinkedIn Partner ID"> Your **Partner ID** identifies your LinkedIn ad account and Insight Tag installation. You'll need this to configure the Upstack destination. Help guide: [How to find your LinkedIn Partner ID →](/guides/linkedin-ads/how-to-find-linkedin-partner-id) </Step> <Step title="Create Conversion Rules in Campaign Manager"> Unlike Meta or TikTok, LinkedIn requires you to create **Conversion Rules** for each event type you want to track. Each rule gets a unique **Conversion Rule ID** that Upstack uses to send events to the correct conversion action. <Warning> You must create separate Conversion Rules for **Purchase**, **Add to Cart**, **Lead**, and any other events you want to track. Without a Conversion Rule ID, Upstack cannot send events for that action. </Warning> Help guide: [How to create LinkedIn Conversion Rules →](/guides/linkedin-ads/how-to-create-linkedin-conversion-rules) </Step> <Step title="Generate a Conversions API access token"> Upstack needs a **Direct Access Token** with the **Manage conversions** permission to send events to LinkedIn's Conversions API. You generate it directly in Campaign Manager — no LinkedIn Developer app required. Help guide: [How to generate a LinkedIn Conversions API token →](/guides/linkedin-ads/how-to-generate-linkedin-conversion-api-token) </Step> <Step title="Configure the LinkedIn destination in Upstack Data"> In the Upstack dashboard, navigate to **Event Destinations** and add a **LinkedIn Ads** destination using your **Partner ID**, **API Access Token**, and **Conversion Rule IDs**. Help guide: [How to configure the LinkedIn destination in Upstack Data →](/guides/linkedin-ads/how-to-configure-linkedin-destination-in-upstack-data) </Step> <Step title="Enable LinkedIn click ID tracking"> <Note> **Optional but recommended.** Enabling enhanced conversion tracking allows LinkedIn to capture the `li_fat_id` click ID, which significantly improves match rates. </Note> Help guide: [How to enable LinkedIn click ID tracking →](/guides/linkedin-ads/how-to-enable-linkedin-click-id-tracking) </Step> <Step title="Verify the full setup is healthy"> Confirm each piece of the setup is working: * In the Upstack dashboard, **Event Destinations** shows your LinkedIn destination as **Healthy** (green). * In [LinkedIn Campaign Manager](https://www.linkedin.com/campaignmanager/) → **Data** → **Signals Manager** → **Signal Diagnostics**, events appear with status "Received." * The **Match Quality** column shows match rates — these will improve over the next 1-2 weeks. If anything is unhealthy, check the corresponding help guide above for troubleshooting steps. </Step> </Steps> ## What to expect after setup ### Match quality timeline * **Match quality** scores start to improve in 2-3 days and normalize over 1-2 weeks. * You can typically expect a 20-40% increase in tracked conversions vs. the browser Insight Tag alone, since CAPI captures conversions lost to ad blockers and iOS restrictions. * The **Purchase** match quality sees the biggest improvement because checkout-time events carry the strongest match keys (hashed email, LinkedIn click ID). ### Reporting differences * Your **LinkedIn Campaign Manager ROAS** will likely **increase** after a few days as LinkedIn attributes more conversions to ads. Many brands discover their LinkedIn campaigns were performing better than the browser-only data suggested. * Conversion volume may temporarily fluctuate during the first 48 hours as LinkedIn's deduplication logic adjusts to receiving both Insight Tag and CAPI events. ### B2B-specific benefits LinkedIn's Conversions API supports **B2B match keys** that other platforms don't: * **Company name** — match events to LinkedIn Company Pages * **Job title** — improve targeting for professional audiences * **First-party click ID (`li_fat_id`)** — the strongest match signal for LinkedIn <Note> **Need help?** If you encounter any issues during setup or don't see expected match quality improvements after 2 weeks, contact our [support team](/support) with your **LinkedIn Partner ID** and we'll help diagnose the problem. </Note> # How to Configure LinkedIn Destination in Upstack Data Source: https://docs.upstackdata.com/guides/linkedin-ads/how-to-configure-linkedin-destination-in-upstack-data Configure the LinkedIn Ads destination in Upstack Data — enter your Partner ID, API Access Token, and Conversion Rule IDs to enable server-side conversion forwarding. <Tip> * Navigate to **Event Destinations** in your Upstack dashboard. * Add a **LinkedIn Ads** destination with your **Partner ID**, **API Access Token**, and **Conversion Rule IDs**. * Enable **Enhanced Matching** to send hashed user data for improved attribution. * Verify the destination shows **Healthy** status after saving. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Your **LinkedIn Partner ID** — see [How to find your LinkedIn Partner ID](/guides/linkedin-ads/how-to-find-linkedin-partner-id) * A **Conversions API access token** — see [How to generate a LinkedIn Conversions API token](/guides/linkedin-ads/how-to-generate-linkedin-conversion-api-token) * **Conversion Rule IDs** for each event type — see [How to create LinkedIn Conversion Rules](/guides/linkedin-ads/how-to-create-linkedin-conversion-rules) ## Steps to configure the LinkedIn destination <Steps> <Step title="Open Event Destinations in Upstack"> Sign in to your [Upstack Data dashboard](https://app.upstackdata.com) and navigate to **Event Destinations** from the left sidebar. </Step> <Step title="Add a new destination"> Click **+ Add Destination** and select **LinkedIn Ads** from the destination catalog. </Step> <Step title="Enter your Partner ID"> Paste your **LinkedIn Partner ID** into the **Partner ID** field. <Tip> Your Partner ID is a numeric value (e.g., `123456`) found in LinkedIn Campaign Manager → Data → Signals Manager. Ensure there are no extra spaces. </Tip> </Step> <Step title="Enable the Conversions API"> Toggle **Enable LinkedIn Conversions API** to send server-side events in addition to the Insight Tag. <Note> When enabled, Upstack sends events directly to LinkedIn's Conversions API, bypassing browser restrictions. We recommend keeping this enabled for maximum match quality. </Note> </Step> <Step title="Enter your API Access Token"> Paste your **Conversions API access token** into the **API Access Token** field. This is the **Direct Access Token** you generate in Campaign Manager with the **Manage conversions** permission. If you haven't generated one yet, see [How to generate a LinkedIn Conversions API token](/guides/linkedin-ads/how-to-generate-linkedin-conversion-api-token). </Step> <Step title="Map Conversion Rule IDs"> Enter the **Conversion Rule ID** for each event type you want to track: | Field | Description | | ---------------------------------- | --------------------------------------------------- | | **Purchase Conversion Rule ID** | The numeric ID for your Purchase conversion rule | | **Add to Cart Conversion Rule ID** | The numeric ID for your Add to Cart conversion rule | | **Lead Conversion Rule ID** | The numeric ID for your Lead conversion rule | | **Sign Up Conversion Rule ID** | The numeric ID for your Sign Up conversion rule | <Warning> Each Conversion Rule ID must be a numeric value (e.g., `12345678`). If you haven't created conversion rules yet, see [How to create LinkedIn Conversion Rules](/guides/linkedin-ads/how-to-create-linkedin-conversion-rules). </Warning> **You don't need to fill in all fields.** Only configure the events you want to track. Upstack will skip events that don't have a corresponding Conversion Rule ID. </Step> <Step title="Enable Enhanced Matching (recommended)"> Toggle **Enable Enhanced Matching** to send hashed user data (email) to LinkedIn for improved ad attribution. <Note> Enhanced Matching sends SHA-256 hashed email addresses to LinkedIn. The data is hashed before it leaves your Upstack account. </Note> </Step> <Step title="Save the configuration"> Click **Create Configuration** (or **Save Changes** if editing) to save the destination. </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, navigate to **Event Destinations**. Your LinkedIn destination should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**, double-check: * Partner ID is correct (numeric, no spaces) * API Access Token is valid and hasn't expired * Conversion Rule IDs are correct (numeric values only) * Your LinkedIn user has the required permissions </Step> </Steps> ## Configuration fields reference | Field | Required | Description | | ----------------------------------- | ----------- | ----------------------------------------------- | | **Partner ID** | Yes | Your LinkedIn Partner ID from Campaign Manager | | **Enable LinkedIn Conversions API** | No | Send events server-side via the Conversions API | | **API Access Token** | Conditional | Required when Conversions API is enabled | | **Purchase Conversion Rule ID** | No | Conversion Rule ID for Purchase events | | **Add to Cart Conversion Rule ID** | No | Conversion Rule ID for Add to Cart events | | **Lead Conversion Rule ID** | No | Conversion Rule ID for Lead events | | **Sign Up Conversion Rule ID** | No | Conversion Rule ID for Sign Up events | | **Enable Enhanced Matching** | No | Send hashed email for improved attribution | <Note> **Next step:** [How to enable LinkedIn click ID tracking](/guides/linkedin-ads/how-to-enable-linkedin-click-id-tracking) </Note> # How to Create LinkedIn Conversion Rules Source: https://docs.upstackdata.com/guides/linkedin-ads/how-to-create-linkedin-conversion-rules Create LinkedIn Conversion Rules in Campaign Manager and find each Conversion Rule ID — required so Upstack Data can send server-side events to the correct conversion action. <Tip> * Sign in to [LinkedIn Campaign Manager](https://www.linkedin.com/campaignmanager/) and open **Data** → **Signals Manager** → **Conversions**. * Click **Create conversion** and choose the **Conversions API** data source. * Create one conversion rule per event type (Purchase, Add to Cart, Lead, Sign Up). * Copy each numeric **Conversion Rule ID** and map it in your Upstack LinkedIn destination. </Tip> <Warning> Unlike Meta or TikTok, LinkedIn requires a separate **Conversion Rule** for each event type you want to track. Without a Conversion Rule ID for an event, Upstack cannot forward that event — it will be skipped. </Warning> <Note> **What is a Conversion Rule ID?** A **Conversion Rule** defines a specific conversion action (e.g., a Purchase) and how it should be attributed to your campaigns. Each rule has a unique numeric **Conversion Rule ID**. LinkedIn references rules internally with the URN format `urn:lla:llaPartnerConversion:{id}`; Upstack builds this URN for you — you only need the numeric ID. </Note> ## Prerequisites Before you start, you need: * **Account Manager** or **Campaign Manager** access to your **LinkedIn Ads** account * Your **LinkedIn Partner ID** — see [How to find your LinkedIn Partner ID](/guides/linkedin-ads/how-to-find-linkedin-partner-id) * A list of the event types you want to track (commonly Purchase, Add to Cart, Lead, Sign Up) ## Steps to create LinkedIn Conversion Rules <Steps> <Step title="Sign in to Campaign Manager"> Sign in to [LinkedIn Campaign Manager](https://www.linkedin.com/campaignmanager/) and select your ad account. </Step> <Step title="Open the Conversions tab"> Click **Data** → **Signals Manager** → **Conversions**. This page lists existing conversion rules and lets you create new ones. </Step> <Step title="Create a new conversion"> Click **Create conversion**. Give the conversion a clear name that matches the event type — for example, `Upstack Purchase` or `Upstack Add to Cart`. </Step> <Step title="Choose the Conversions API data source"> When prompted for the conversion source, select **Conversions API** (server-side). This tells LinkedIn the conversion will be reported by a server-to-server integration rather than the browser Insight Tag. <Note> If you also run the Insight Tag for the same action, you can attach it to the **same** conversion rule. LinkedIn deduplicates browser and server events that share an `eventId` within a single rule. </Note> </Step> <Step title="Configure conversion settings"> Set the conversion details: | Setting | Recommended value | | ---------------------- | --------------------------------------------------------------------------- | | **Conversion type** | Match the action (e.g., Purchase, Add to Cart, Lead, Sign Up) | | **Attribution window** | Use your account default (e.g., 30-day click / 7-day view) | | **Value** | Enable if you want to report revenue (Upstack sends `value` and `currency`) | | **Campaigns** | Associate the rule with at least one active campaign | </Step> <Step title="Save and copy the Conversion Rule ID"> Save the conversion rule. Open the rule's details — the numeric **Conversion Rule ID** appears in the rule settings and in the page URL. **Example format:** `12345678` <Tip> The Conversion Rule ID is the numeric portion only. If LinkedIn displays the full URN `urn:lla:llaPartnerConversion:12345678`, you only need the `12345678` part for Upstack. </Tip> </Step> <Step title="Repeat for each event type"> Create a separate conversion rule for **every** event you want to track and record each Conversion Rule ID: * Purchase → `Purchase Conversion Rule ID` * Add to Cart → `Add to Cart Conversion Rule ID` * Lead → `Lead Conversion Rule ID` * Sign Up → `Sign Up Conversion Rule ID` </Step> <Step title="Map the IDs in Upstack Data"> In Upstack, open your **LinkedIn** destination under **Event Destinations** and paste each Conversion Rule ID into the matching field. See [How to configure the LinkedIn destination](/guides/linkedin-ads/how-to-configure-linkedin-destination-in-upstack-data). </Step> </Steps> ## Event-to-rule mapping reference | Upstack event | LinkedIn conversion type | Destination field | | ---------------------- | ------------------------ | ------------------------------ | | `Purchase` | Purchase | Purchase Conversion Rule ID | | `AddToCart` | Add to Cart | Add to Cart Conversion Rule ID | | `Lead` | Lead | Lead Conversion Rule ID | | `CompleteRegistration` | Sign Up | Sign Up Conversion Rule ID | <Note> **Next step:** [How to generate a LinkedIn Conversions API token](/guides/linkedin-ads/how-to-generate-linkedin-conversion-api-token) </Note> # How to Enable LinkedIn Click ID Tracking Source: https://docs.upstackdata.com/guides/linkedin-ads/how-to-enable-linkedin-click-id-tracking Enable LinkedIn li_fat_id click ID tracking so Upstack Data can capture the strongest LinkedIn match signal and attribute server-side conversions to ad clicks. <Tip> * Turn on **Enhanced Conversion Tracking** in your LinkedIn Insight Tag settings. * LinkedIn appends `li_fat_id` to your landing page URLs on ad clicks. * Upstack captures and stores `li_fat_id` automatically and sends it with every conversion event. * No URL changes are required — enabling the setting is enough. </Tip> <Note> **What is `li_fat_id`?** `li_fat_id` is LinkedIn's **first-party ad tracking click ID**. When a member clicks your ad, LinkedIn appends `li_fat_id` to your landing page URL. It is the strongest match signal LinkedIn supports — events that carry `li_fat_id` match to campaign data far more reliably than events matched on hashed email or IP alone. Upstack stores the value in a first-party cookie and includes it on every server-side Conversions API event. </Note> ## Prerequisites Before you start, you need: * The **LinkedIn Insight Tag** installed and active on your storefront * **Campaign Manager** access to your LinkedIn Ads account * Your LinkedIn destination already configured in Upstack — see [How to configure the LinkedIn destination](/guides/linkedin-ads/how-to-configure-linkedin-destination-in-upstack-data) ## Steps to enable click ID tracking <Steps> <Step title="Sign in to Campaign Manager"> Sign in to [LinkedIn Campaign Manager](https://www.linkedin.com/campaignmanager/) and select your ad account. </Step> <Step title="Open the Insight Tag settings"> Click **Data** → **Signals Manager** and open your **Insight Tag**. </Step> <Step title="Enable Enhanced Conversion Tracking"> Turn on **Enhanced Conversion Tracking** (sometimes labeled **First-party ad tracking** or **Enable click ID**). <Note> This setting authorizes LinkedIn to append the `li_fat_id` parameter to URLs when members click your ads. It does not require any code changes — Upstack reads the parameter automatically. </Note> </Step> <Step title="Save the changes"> Click **Save**. The setting takes effect for new ad clicks immediately. </Step> <Step title="Verify the click ID is captured"> To confirm `li_fat_id` is being captured: 1. Click one of your LinkedIn ads (or open a landing page URL containing `li_fat_id=...`). 2. In your browser's developer tools, check that a first-party cookie storing the LinkedIn click ID is set. 3. Generate a test conversion and confirm match quality improves in **Signals Manager → Signal Diagnostics** over the following days. **Example URL after an ad click:** ``` https://yourstore.com/products/widget?li_fat_id=abc123-def456-7890 ``` </Step> </Steps> ## How Upstack captures the click ID Once Enhanced Conversion Tracking is enabled: 1. **Member clicks ad** → LinkedIn appends `li_fat_id=...` to the landing page URL. 2. **Upstack Pixel loads** → captures `li_fat_id` from the URL and stores it in a first-party cookie. 3. **Visitor converts** → Upstack includes the stored `li_fat_id` with the conversion event. 4. **Event sent to LinkedIn** → LinkedIn matches the conversion to the original ad click for accurate attribution. ## Troubleshooting ### `li_fat_id` not appearing in URLs If the click ID isn't being appended after clicking an ad: 1. Confirm **Enhanced Conversion Tracking** is saved and enabled on the Insight Tag. 2. Verify the Insight Tag is firing on your landing pages (Upstack fires it alongside server-side events). 3. Allow time — the setting applies to new ad clicks, not historical traffic. ### Match quality not improving If match quality stays low after enabling click ID tracking: 1. Confirm the **Partner ID** in Upstack matches the Insight Tag's Partner ID. 2. Ensure ads link directly to your storefront so `li_fat_id` lands in the URL (avoid intermediate redirects that strip parameters). 3. Match quality builds over 1–2 weeks as more identified visitors convert. <Note> For a complete walkthrough, see the [LinkedIn onboarding guide](/guides/linkedin-ads/complete-how-to-guide-for-onboarding-linkedin-in-upstack-data). </Note> # How to Find your LinkedIn Partner ID Source: https://docs.upstackdata.com/guides/linkedin-ads/how-to-find-linkedin-partner-id Find your LinkedIn Partner ID in Campaign Manager Signals Manager — required to configure the Upstack Data LinkedIn destination for server-side conversion forwarding. <Tip> * Sign in to [LinkedIn Campaign Manager](https://www.linkedin.com/campaignmanager/) and open **Data** → **Signals Manager**. * Select your **Insight Tag** to open its details. * Copy the numeric **Partner ID** (e.g., `123456`). * Paste it into your Upstack LinkedIn destination configuration. </Tip> <Note> **What is a LinkedIn Partner ID?** Your **Partner ID** is the numeric identifier for your LinkedIn Insight Tag — the same ID used for browser-side tracking on your storefront. Upstack uses it to associate server-side Conversions API events with your ad account so LinkedIn can deduplicate them against the Insight Tag and attribute conversions to your campaigns. Each LinkedIn ad account has one Partner ID. </Note> ## Prerequisites Before you start, you need: * Access to a **LinkedIn Ads** account at [linkedin.com/campaignmanager](https://www.linkedin.com/campaignmanager/) * The **Campaign Manager** or **Account Manager** role on the ad account * The **LinkedIn Insight Tag** created in your account (or follow the create steps below) ## Steps to find your LinkedIn Partner ID <Steps> <Step title="Sign in to Campaign Manager"> Sign in to [LinkedIn Campaign Manager](https://www.linkedin.com/campaignmanager/) and select the ad account you want to track conversions for. </Step> <Step title="Open Signals Manager"> In the top navigation, click **Data** → **Signals Manager**. The Signals Manager lists your **Insight Tag** and any conversion signals associated with the account. </Step> <Step title="Find or create your Insight Tag"> **If you already have an Insight Tag**, it appears in the Signals Manager — proceed to the next step. **If you need to create one:** * Click **Create Insight Tag** * Choose **I will install the tag myself** (Upstack fires the tag for you) * Save and return to the Signals Manager </Step> <Step title="Locate your Partner ID"> Open your Insight Tag details. The **Partner ID** is displayed as a numeric value. **Example format:** `123456` You can also find it embedded in the Insight Tag code as `partner_id` (e.g., `_linkedin_partner_id = "123456";`). </Step> <Step title="Copy and paste into Upstack Data"> Copy your Partner ID and paste it into the **Partner ID** field in your Upstack LinkedIn destination setup. <Tip> Ensure there are no extra spaces before or after the ID. The Partner ID is numeric only — no letters or prefixes. </Tip> </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, navigate to **Event Destinations**. Your LinkedIn destination should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**, double-check that the Partner ID matches exactly what you see in Campaign Manager (numeric only, no whitespace). </Step> </Steps> <Note> **Next step:** [How to create LinkedIn Conversion Rules](/guides/linkedin-ads/how-to-create-linkedin-conversion-rules) </Note> # How to Generate a LinkedIn Conversions API Token Source: https://docs.upstackdata.com/guides/linkedin-ads/how-to-generate-linkedin-conversion-api-token Generate a LinkedIn Conversions API Direct Access Token in Campaign Manager — the simplest way to authenticate the Upstack Data LinkedIn destination for server-side conversion forwarding. <Tip> * Generate a **Direct Access Token** in Campaign Manager → **Data** → **Signals Manager** → **Conversions API**. * Give the token the **Manage conversions** permission and access to the correct ad account. * Set an expiry (we recommend **1 year**), then copy the token immediately — it won't be shown again. * Paste it into your Upstack LinkedIn destination's **API Access Token** field. </Tip> <Note> **What is a LinkedIn Direct Access Token?** A **Direct Access Token** is a LinkedIn-issued access token you generate directly inside Campaign Manager — no LinkedIn Developer app or OAuth flow required. It authorizes Upstack to send conversion events to LinkedIn's Conversions API on your behalf. You control which ad accounts it covers, the permission it grants (**Manage conversions**), and how long it lasts before expiring. </Note> ## Prerequisites Before you start, you need: * **Admin** or **Account Manager** access to your **LinkedIn Ads** account at [linkedin.com/campaignmanager](https://www.linkedin.com/campaignmanager/) * Your **Partner ID** and at least one **Conversion Rule** created — see [How to create LinkedIn Conversion Rules](/guides/linkedin-ads/how-to-create-linkedin-conversion-rules) ## Steps to generate your LinkedIn CAPI token <Steps> <Step title="Open Signals Manager in Campaign Manager"> Sign in to [LinkedIn Campaign Manager](https://www.linkedin.com/campaignmanager/), select your ad account, then click **Data** → **Signals Manager** in the top navigation. <Frame> <img alt="LinkedIn Campaign Manager Signals Manager with the Conversions API tab" /> </Frame> </Step> <Step title="Open the Conversions API tab"> In Signals Manager, click the **Conversions API** tab. This is where you manage Direct Access Tokens for server-side event forwarding. </Step> <Step title="Generate a token"> Click **Generate token** (or **Manage tokens** → **Generate token** if you've created tokens before). <Frame> <img alt="Generate token dialog in the LinkedIn Conversions API tab" /> </Frame> </Step> <Step title="Select the ad accounts"> Choose the **ad account(s)** the token should cover. The token can only send conversions for the accounts you select here. <Warning> The token must include the ad account that owns your Conversion Rules. Otherwise the token will be valid but events will return a `403` permission error. </Warning> </Step> <Step title="Set the permission to Manage conversions"> Set the token permission to **Manage conversions**. This is the permission Upstack needs to write conversion events to LinkedIn. | Permission | Required | Purpose | | ---------------------- | -------- | --------------------------------------------- | | **Manage conversions** | Yes | Send and manage server-side conversion events | </Step> <Step title="Set the token expiry"> Choose how long the token stays valid. We recommend setting the expiry to **1 year** to minimize how often you need to rotate it. <Tip> Set a calendar reminder a week or two before the expiry date so you can generate a replacement token before conversion forwarding is interrupted. </Tip> </Step> <Step title="Copy and save the token securely"> LinkedIn displays the generated token — a long alphanumeric string. Copy it immediately and store it somewhere secure (a password manager works well). <Warning> **The token is shown only once.** LinkedIn will not display it again after you close the dialog. If you lose it, you'll have to generate a new one. Treat it like a password and never expose it in client-side code. </Warning> </Step> <Step title="Add the token to Upstack Data"> Sign in to [Upstack Data](https://app.upstackdata.com/pixel/event-destinations) and open your **LinkedIn** destination under **Event Destinations**. Paste the token into the **API Access Token** field and save. </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, the LinkedIn destination card should show **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**: * Confirm the token was pasted in full (no truncation, no whitespace). * Confirm the token has the **Manage conversions** permission. * Confirm the token includes the ad account that owns your Conversion Rules. </Step> </Steps> ## Token expiration and renewal Direct Access Tokens expire based on the duration you set when generating them (we recommend 1 year). When a token expires: * The destination status changes to **Unhealthy** and events return a `401` error. To renew: 1. Go to Campaign Manager → **Data** → **Signals Manager** → **Conversions API**. 2. Generate a new token with the same ad accounts and **Manage conversions** permission. 3. Update the **API Access Token** field in your Upstack LinkedIn destination. <Note> **Next step:** [How to enable LinkedIn click ID tracking](/guides/linkedin-ads/how-to-enable-linkedin-click-id-tracking) </Note> # Complete How-To Guide for Onboarding Microsoft Advertising in Upstack Data Source: https://docs.upstackdata.com/guides/microsoft-ads/complete-how-to-guide-for-onboarding-microsoft-ads Onboard Microsoft Advertising (Bing Ads) in Upstack Data — locate your UET Tag ID, generate your CAPI auth token, configure the destination, and verify server-side conversion forwarding. <Info> **New to Upstack?** Follow the [getting started guide](/get-started/install-on-shopify) for a streamlined onboarding walkthrough. </Info> <Tip> * Configure the **Microsoft Advertising destination** in Upstack Data with your **UET Tag ID** and **CAPI Auth Token**. * Ensure Auto-tagging or manual `msclkid` tracking is enabled in your campaigns. * Verify events appear in **Microsoft Advertising → Tools → UET Tags → Tag Status**. * Monitor attribution improvements over 7-10 days of campaign traffic. </Tip> <Warning> **CAPI Pilot Program:** Microsoft's Conversions API is currently in pilot. Contact your Microsoft Advertising account manager to enroll before enabling server-side tracking in Upstack. </Warning> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to a **Microsoft Advertising** account * Your **UET Tag ID** from Microsoft Advertising * Enrollment in the **Conversions API pilot program** * Your **CAPI Auth Token** (generated after pilot enrollment) * Active Microsoft Advertising campaigns with msclkid tracking enabled <Steps> <Step title="Enroll in the Conversions API pilot"> Contact your Microsoft Advertising account manager or Microsoft Advertising support to request enrollment in the Conversions API pilot program. Once enrolled, the auth token generation option becomes available in your UET Tag settings. Help guide: [How to enable the Conversions API →](/guides/microsoft-ads/how-to-enable-conversions-api) </Step> <Step title="Find your UET Tag ID"> Locate your UET Tag ID in the Microsoft Advertising dashboard under Tools → UET Tags. This numeric ID identifies your tracking tag. Help guide: [How to find your UET Tag ID →](/guides/microsoft-ads/how-to-find-uet-tag-id) </Step> <Step title="Create Event Goals"> Create Event Goals in Microsoft Advertising to track specific conversion types (purchase, add\_to\_cart, etc.) that Upstack will send via CAPI. Help guide: [How to create Event Goals →](/guides/microsoft-ads/how-to-create-event-goals) </Step> <Step title="Enable msclkid tracking"> Ensure Auto-tagging is enabled or configure manual msclkid tracking in your campaigns so click IDs are captured for attribution. Help guide: [How to enable msclkid tracking →](/guides/microsoft-ads/how-to-enable-msclkid-tracking) </Step> <Step title="Configure the Microsoft Advertising destination in Upstack Data"> In the Upstack dashboard, navigate to **Event Destinations** and add a **Microsoft Advertising** destination using your **UET Tag ID** and **CAPI Auth Token**. Help guide: [How to configure the Microsoft Advertising destination →](/guides/microsoft-ads/how-to-configure-microsoft-ads-destination) </Step> <Step title="Verify the full setup is healthy"> Confirm each piece of the setup is working: * In the Upstack dashboard, **Event Destinations** shows your Microsoft Advertising destination as **Healthy** (green). * In Microsoft Advertising → **Tools** → **UET Tags** → select your tag → **Tag Status**, server-side events appear alongside browser events. * Test with a real ad click — clicking your own ad and completing a purchase should generate a tracked conversion within 5-10 minutes. If anything is unhealthy, check the corresponding help guide above for troubleshooting steps. </Step> </Steps> ## What to expect after setup ### Attribution with msclkid Microsoft Advertising attributes conversions using the `msclkid` click identifier when available, plus hashed email and phone for enhanced matching: | Scenario | Attribution | | ------------------------------------------------------ | ---------------------------------- | | User clicks ad with `msclkid`, converts same session | ✅ Attributed | | User clicks ad with `msclkid`, converts within 90 days | ✅ Attributed (if cookie persists) | | Known customer with email, no click ID | ✅ Attributed via enhanced matching | | User visits directly without ad click | ❌ Cannot be attributed | | User clears cookies between click and conversion | ⚠️ Depends on email/phone matching | ### Conversion reporting timeline * **Initial conversions** start appearing in Microsoft Advertising within 5-10 minutes of real ad clicks and purchases. * **Full attribution picture** emerges over 7-10 days as more users complete the click → conversion journey. * **Server-side events** appear with a "Server" indicator in UET Tag Status. ### Deduplication Microsoft deduplicates based on `eventId`. Upstack sends a shared `eventId` on every server-side event, and Microsoft's deduplication logic matches events by `eventId` and keeps only one. As long as the UET Tag ID in Upstack matches your browser UET Tag, you won't see duplicate conversions. <Note> **Need help?** If you encounter any issues during setup or don't see conversions appearing after confirming ad clicks, contact our [support team](/support) with your **UET Tag ID** and we'll help diagnose the problem. </Note> # How to Configure Microsoft Advertising Destination in Upstack Data Source: https://docs.upstackdata.com/guides/microsoft-ads/how-to-configure-microsoft-ads-destination Configure the Microsoft Advertising (Bing Ads) destination inside Upstack Data with your UET Tag ID and CAPI Auth Token. <Info> **Prerequisites:** You need your [UET Tag ID](/guides/microsoft-ads/how-to-find-uet-tag-id) and [CAPI Auth Token](/guides/microsoft-ads/how-to-enable-conversions-api) before configuring this destination. </Info> ## Steps <Steps> <Step title="Open Upstack Data dashboard"> Log in to [app.upstackdata.com](https://app.upstackdata.com) and select your store. </Step> <Step title="Navigate to Event Destinations"> In the left sidebar, click **Integrations** → **Event Destinations**. </Step> <Step title="Add Microsoft Advertising destination"> Click **+ Add Destination** and select **Microsoft Advertising** from the list of available destinations. </Step> <Step title="Enter your UET Tag ID"> Paste your **UET Tag ID** (numeric value) in the Tag ID field. Don't have it? [Find your UET Tag ID →](/guides/microsoft-ads/how-to-find-uet-tag-id) </Step> <Step title="Enable Conversions API (recommended)"> Toggle **Enable Conversions API** to enable server-side event delivery. When enabled, paste your **CAPI Auth Token** in the Auth Token field. Don't have it? [Generate your CAPI Auth Token →](/guides/microsoft-ads/how-to-enable-conversions-api) </Step> <Step title="Save and verify"> Click **Save** to activate the destination. The destination status should show **Healthy** (green) within a few minutes if the credentials are valid. </Step> </Steps> ## Configuration fields | Field | Required | Description | | -------------------------- | ----------------- | ----------------------------------------------- | | **UET Tag ID** | Yes | Your Microsoft Advertising UET Tag ID (numeric) | | **Enable Conversions API** | No | Toggle to enable server-side event delivery | | **CAPI Auth Token** | When CAPI enabled | Bearer token for authenticating API requests | ## Troubleshooting <AccordionGroup> <Accordion title="Destination shows Unhealthy status"> **Common causes:** * Invalid or expired CAPI Auth Token — regenerate in Microsoft Advertising * Incorrect UET Tag ID — verify in Microsoft Advertising → Tools → UET Tags * Account not enrolled in CAPI pilot — contact your Microsoft Advertising account manager </Accordion> <Accordion title="Events not appearing in Microsoft Advertising"> 1. Verify the destination status is Healthy in Upstack 2. Check that Event Goals are configured in Microsoft Advertising 3. Wait 5-10 minutes for events to propagate 4. Use the Upstack Event Debugger to confirm events are being sent </Accordion> </AccordionGroup> <Note> **Need help?** Contact our [support team](/support) with your UET Tag ID and we'll help troubleshoot. </Note> # How to Create Event Goals in Microsoft Advertising Source: https://docs.upstackdata.com/guides/microsoft-ads/how-to-create-event-goals Create Event Goals in Microsoft Advertising to track specific conversion types sent by Upstack Data via the Conversions API. **Event Goals** in Microsoft Advertising define which events count as conversions for your campaigns. Upstack sends events like `purchase`, `add_to_cart`, and `view_item` — you need corresponding Event Goals to track them. <Note> Microsoft uses **free-form event names** rather than predefined standard events. Event matching is done via Event Goals configured in the Microsoft Advertising UI. </Note> ## Steps <Steps> <Step title="Sign in to Microsoft Advertising"> Go to [ads.microsoft.com](https://ads.microsoft.com) and sign in to your account. </Step> <Step title="Navigate to Conversion Goals"> In the top navigation, click **Tools** → **Conversion Goals** (under Conversion tracking). </Step> <Step title="Create a new goal"> Click **+ Create conversion goal** and select **Event** as the goal type. </Step> <Step title="Configure the goal"> Fill in the goal settings: * **Goal name:** Use a descriptive name (e.g., "Upstack Purchase", "Upstack Add to Cart") * **Event name:** Enter the exact event name Upstack sends (see mapping table below) * **Revenue value:** Configure how revenue is tracked (use event value for purchases) * **Attribution window:** Set your desired click-through and view-through windows </Step> <Step title="Save the goal"> Click **Save** to create the Event Goal. Repeat for each event type you want to track. </Step> </Steps> ## Event name mapping Create Event Goals for these Upstack events: | Upstack event | Event name to use | Recommended settings | | ------------------ | ----------------- | -------------------------------------- | | `Purchase` | `purchase` | Revenue: Use event value, Primary goal | | `AddToCart` | `add_to_cart` | Revenue: Fixed value or event value | | `ViewContent` | `view_item` | Revenue: None or fixed value | | `InitiateCheckout` | `begin_checkout` | Revenue: Use event value | | `Lead` | `lead` | Revenue: Fixed value | | `Search` | `search` | Revenue: None | | `SignUp` | `sign_up` | Revenue: Fixed value | | `PageView` | `pageLoad` | Revenue: None | ## Goal settings recommendations ### Primary vs. secondary goals * **Primary goal:** Purchase events — these are used for campaign optimization * **Secondary goals:** Add to cart, view content — useful for analysis but don't directly influence bidding ### Attribution windows * **Click-through window:** 30 days (default) — conversions attributed to ad clicks * **View-through window:** 1 day — conversions attributed to ad impressions without clicks ### Revenue tracking For purchase events, select **Use the revenue value from conversions** to pass the actual order value from Upstack. ## Verification After creating Event Goals: 1. Wait for Upstack to send some events (may take a few hours depending on store traffic) 2. Check **Tools** → **UET Tags** → select your tag → **Tag Status** 3. Verify events appear with the correct event names <Note> **Need help?** Contact our [support team](/support) if events aren't being tracked correctly. </Note> # How to Enable the Microsoft Advertising Conversions API Source: https://docs.upstackdata.com/guides/microsoft-ads/how-to-enable-conversions-api Enroll in the Microsoft Advertising Conversions API pilot program and generate your CAPI Auth Token for server-side event delivery. Microsoft's **Conversions API (CAPI)** enables server-side event delivery alongside the browser UET Tag. Server-side events bypass ad blockers and browser restrictions, improving match rates and attribution accuracy. <Warning> **Pilot Program:** The Conversions API is currently in pilot. You must be enrolled in the pilot program before you can generate an auth token. </Warning> ## Step 1: Enroll in the CAPI pilot <Steps> <Step title="Contact Microsoft Advertising"> Reach out to your Microsoft Advertising account manager or contact [Microsoft Advertising support](https://about.ads.microsoft.com/en-us/resources/support) to request enrollment in the Conversions API pilot program. Include your: * Microsoft Advertising account ID * UET Tag ID * Business use case (server-side conversion tracking via Upstack Data) </Step> <Step title="Wait for enrollment confirmation"> Microsoft will review your request and enable CAPI access for your account. This typically takes 1-2 business days. You'll receive an email confirmation when enrolled. </Step> </Steps> ## Step 2: Generate your CAPI Auth Token Once enrolled in the pilot: <Steps> <Step title="Sign in to Microsoft Advertising"> Go to [ads.microsoft.com](https://ads.microsoft.com) and sign in to your account. </Step> <Step title="Navigate to UET Tags"> In the top navigation, click **Tools** → **UET Tags**. </Step> <Step title="Select your UET Tag"> Click on the UET Tag you want to use for server-side tracking. </Step> <Step title="Access CAPI settings"> In the tag details, look for the **Conversions API** or **Server-side tracking** section. This section only appears if your account is enrolled in the CAPI pilot. </Step> <Step title="Generate auth token"> Click **Generate token** or **Create auth token**. A Bearer token will be generated. **Copy this token immediately** — it may not be shown again. </Step> <Step title="Save the token securely"> Store the auth token securely. You'll need it when configuring the Microsoft Advertising destination in Upstack Data. </Step> </Steps> ## Token management ### Token expiration CAPI auth tokens may have an expiration date. Check your Microsoft Advertising account for token validity and regenerate if needed. ### Token rotation If you need to rotate your token: 1. Generate a new token in Microsoft Advertising 2. Update the token in your Upstack destination settings 3. The old token will continue working briefly to allow for transition ## Troubleshooting <AccordionGroup> <Accordion title="I don't see the CAPI option in UET Tag settings"> Your account is not yet enrolled in the Conversions API pilot. Contact your Microsoft Advertising account manager to request enrollment. </Accordion> <Accordion title="My token isn't working"> **Common causes:** * Token was copied incorrectly (check for extra spaces or truncation) * Token has expired — generate a new one * Account CAPI access was revoked — contact Microsoft Advertising support </Accordion> </AccordionGroup> ## Next steps Once you have your CAPI Auth Token: * [Configure the destination in Upstack Data →](/guides/microsoft-ads/how-to-configure-microsoft-ads-destination) * [Create Event Goals →](/guides/microsoft-ads/how-to-create-event-goals) # How to Enable msclkid Tracking for Microsoft Advertising Source: https://docs.upstackdata.com/guides/microsoft-ads/how-to-enable-msclkid-tracking Ensure msclkid (Microsoft Click ID) is captured and stored for attribution in Microsoft Advertising campaigns. The **msclkid** (Microsoft Click ID) is a unique identifier appended to your landing page URLs when users click on Microsoft Advertising ads. Upstack captures this click ID and includes it with server-side events for accurate attribution. ## How msclkid works 1. User clicks your Microsoft ad 2. Microsoft appends `msclkid=XXXXXXXX` to the landing page URL 3. Upstack Pixel captures the `msclkid` from the URL 4. Upstack stores the `msclkid` in a first-party cookie 5. When the user converts, Upstack sends the `msclkid` with the server-side event 6. Microsoft matches the event to the original ad click ## Enable Auto-tagging (recommended) Auto-tagging automatically appends `msclkid` to all ad click URLs. This is the recommended approach. <Steps> <Step title="Sign in to Microsoft Advertising"> Go to [ads.microsoft.com](https://ads.microsoft.com) and sign in to your account. </Step> <Step title="Navigate to Account Settings"> Click on your account name in the top navigation → **Account settings**. </Step> <Step title="Enable Auto-tagging"> Under **Tracking**, find the **Auto-tagging** option. Toggle it **ON** to automatically append msclkid to all ad URLs. </Step> <Step title="Save changes"> Click **Save** to apply the setting. </Step> </Steps> ## Manual tracking (alternative) If you need manual control over click ID tracking, add the `msclkid` parameter to your campaign tracking templates. ### Campaign-level tracking template Add to your campaign's **Tracking template** field: ``` {lpurl}?msclkid={msclkid} ``` Or if you already have URL parameters: ``` {lpurl}&msclkid={msclkid} ``` ### Account-level tracking template Apply to all campaigns by setting the template at the account level: 1. Go to **Account settings** → **Tracking** 2. Add your tracking template with the `{msclkid}` parameter ## Verify msclkid is working <Steps> <Step title="Click one of your ads"> Search for a term that triggers your ad and click through to your landing page. </Step> <Step title="Check the URL"> Look at the URL in your browser. You should see `msclkid=XXXXXXXX` as a URL parameter. Example: `https://yourstore.com/products/item?msclkid=abc123def456...` </Step> <Step title="Check Upstack Pixel Helper"> If you have the [Upstack Pixel Helper](/guides/shopify/how-to-install-upstack-data-pixel-helper) installed, open it and verify that the `msclkid` is being captured. </Step> </Steps> ## Troubleshooting <AccordionGroup> <Accordion title="msclkid not appearing in URLs"> **Common causes:** * Auto-tagging is disabled — enable it in Account settings * Final URL excludes query parameters — check your ad configuration * Landing page redirects strip parameters — ensure redirects preserve query strings </Accordion> <Accordion title="msclkid appearing but not being tracked"> **Check these:** * Upstack Pixel is installed and active on your landing page * No JavaScript errors blocking the Upstack Pixel * Cookie consent is granted (if using consent mode) </Accordion> <Accordion title="Attribution not working despite msclkid"> **Verify:** * The destination is configured with the correct UET Tag ID * Event Goals are created in Microsoft Advertising * Events are reaching Microsoft (check UET Tag Status) </Accordion> </AccordionGroup> ## Cookie persistence Upstack stores the `msclkid` in a first-party cookie to preserve attribution across sessions. The cookie persists for 90 days by default, matching Microsoft's conversion attribution window. <Note> **Privacy considerations:** First-party cookies are more resilient to browser restrictions than third-party cookies, but may still be affected by ITP (Safari) and other privacy features. Server-side delivery helps maintain attribution accuracy in these cases. </Note> ## Next steps Once msclkid tracking is enabled: * [Configure the destination in Upstack Data →](/guides/microsoft-ads/how-to-configure-microsoft-ads-destination) * [Create Event Goals →](/guides/microsoft-ads/how-to-create-event-goals) # How to Find Your UET Tag ID in Microsoft Advertising Source: https://docs.upstackdata.com/guides/microsoft-ads/how-to-find-uet-tag-id Locate your Universal Event Tracking (UET) Tag ID in Microsoft Advertising for use with Upstack Data. Your **UET Tag ID** is a numeric identifier for your Microsoft Advertising tracking tag. You'll need this ID to configure the Microsoft Advertising destination in Upstack Data. ## Steps <Steps> <Step title="Sign in to Microsoft Advertising"> Go to [ads.microsoft.com](https://ads.microsoft.com) and sign in to your account. </Step> <Step title="Navigate to UET Tags"> In the top navigation, click **Tools** → **UET Tags** (under Conversion tracking). </Step> <Step title="Find your UET Tag"> Locate your existing UET Tag in the list. If you don't have one, click **Create UET tag** to create a new one. </Step> <Step title="Copy the Tag ID"> The **Tag ID** is displayed in the list view or tag details. It's a numeric value (e.g., `12345678`). Copy this ID — you'll need it when configuring the Microsoft Advertising destination in Upstack Data. </Step> </Steps> ## Where to find the Tag ID The UET Tag ID appears in several places: * **UET Tags list:** The ID column shows the numeric Tag ID for each tag * **Tag details:** Click on a tag name to view its details, including the Tag ID * **UET Tag code snippet:** The Tag ID appears in the JavaScript snippet as part of the `uetq` initialization ## If you don't have a UET Tag If you don't have an existing UET Tag: 1. Click **Create UET tag** in the UET Tags section 2. Give your tag a descriptive name (e.g., "Upstack Tracking") 3. Optionally add a description 4. Click **Save** 5. Copy the new Tag ID <Note> **Important:** Use the same UET Tag ID for both your browser UET Tag and Upstack server-side delivery to ensure proper event deduplication. </Note> ## Next steps Once you have your UET Tag ID: * [Generate your CAPI Auth Token →](/guides/microsoft-ads/how-to-enable-conversions-api) * [Configure the destination in Upstack Data →](/guides/microsoft-ads/how-to-configure-microsoft-ads-destination) # How to migrate from Elevar to Upstack without losing tracking data Source: https://docs.upstackdata.com/guides/migrations/elevar-to-upstack Step-by-step migration guide from Elevar to Upstack Data — parallel install, event verification, cleanup, and post-migration monitoring. Switching tracking providers is risky. Done wrong, you lose conversion data, create duplicate events, or starve your ad platform algorithms of signal during the transition. This guide walks through a clean migration from Elevar to Upstack using a parallel-run approach that minimizes data gaps and gives you time to verify everything before cutting over. <Tip> **Run Elevar and Upstack in parallel for 2–3 days before disabling Elevar.** A short window of duplicate events (which Meta and most platforms deduplicate via `event_id`) is far safer than a gap in tracking. Don't shortcut this step. </Tip> ## Why brands migrate from Elevar to Upstack Understanding what's driving your move helps you prioritize what to verify after the switch. * **Identity resolution vs. GTM-based server-side.** Elevar routes events through Google Tag Manager's server container. Upstack uses a direct server-side pipeline with built-in [identity resolution](/pixel/identity-resolution) — matching visitors across devices and sessions without depending on GTM infrastructure. * **Klaviyo enhancement.** Upstack's Flows product enriches and pushes identified profiles to Klaviyo so abandonment flows trigger for visitors that Klaviyo's native tracking misses. This isn't available through Elevar's integration. * **Attribution reporting.** Upstack's Analytics product provides multi-touch attribution alongside tracking, so you can see which channels and campaigns drive conversions without relying solely on each ad platform's self-reported numbers. * **Event Match Quality.** Upstack's identity enrichment attaches more customer matching parameters (hashed email, phone, click IDs, external IDs) to each event, which can improve EMQ and give optimization algorithms stronger signal. * **Cost and consolidation.** Running separate tools for tracking, attribution, and Klaviyo enrichment adds up. Upstack combines these in a single platform. ## Prerequisites Before you begin, make sure you have: * [Shopify Admin](https://admin.shopify.com) access with permission to install apps and edit themes * An [Upstack Data](https://app.upstackdata.com) account (you'll create one during the install) * Admin access to every destination platform you'll reconnect (Meta, Google Ads, TikTok, Pinterest, Klaviyo, etc.) * Admin access to your Google Tag Manager container if Elevar uses one (GTM container ID format: `GTM-XXXXXXX`) * Your existing Elevar account access for reference during the cutover ## Pre-migration checklist Capture this before you begin. Having it written down makes verification after migration straightforward. ### Document your current Elevar setup * **Active events:** List every event Elevar is sending — both standard (PageView, ViewContent, AddToCart, InitiateCheckout, Purchase) and any custom events. * **Connected platforms:** Record which destinations Elevar sends to (Meta, Google Ads, TikTok, Pinterest, Klaviyo, etc.). * **GTM container details:** If Elevar manages a GTM container, note the container ID (format `GTM-XXXXXXX`) and which tags are Elevar-specific vs. custom tags you've added. * **Shopify theme scripts:** Note whether Elevar has added code to your Shopify theme files (`theme.liquid`, `checkout.liquid`, or via snippets in **Shopify Admin → Online Store → Themes → Edit code**). * **Shopify data sharing:** Check if Shopify's built-in Meta data sharing is enabled (Shopify Admin → **Settings → Customer events** or **Sales channels → Facebook & Instagram**). ### Save baseline metrics * **EMQ scores:** Screenshot your current Event Match Quality scores in Meta Events Manager for each event type. * **Daily event volume:** Note the average daily count for Purchase, AddToCart, and ViewContent events over the past 7 days. * **Shopify order count:** Record your average daily Shopify orders for comparison after migration. ## Migration steps The migration follows a parallel-run approach: install Upstack alongside Elevar, verify Upstack is working, then remove Elevar. Expect a brief period of duplicate events — that's normal and preferable to a gap in data. ### Phase 1 — Install Upstack alongside Elevar (Day 1) <Steps> <Step title="Install the Upstack Shopify app"> Install the Upstack Data app from the Shopify App Store. The app deploys Upstack's tracking on your store and begins capturing events immediately. Full instructions: [Install on Shopify](/get-started/install-on-shopify). </Step> <Step title="Connect your destinations in Upstack"> Connect every platform Elevar is currently sending to. Use the destination guides linked below for each one. | Platform | Setup guide | | ---------- | -------------------------------------------------- | | Meta | [Meta CAPI destination](/destinations/meta-capi) | | Google Ads | [Google Ads destination](/destinations/google-ads) | | TikTok | [TikTok destination](/destinations/tiktok) | | Klaviyo | [Klaviyo destination](/destinations/klaviyo) | | Pinterest | [Pinterest destination](/destinations/pinterest) | | Snapchat | [Snapchat destination](/destinations/snapchat) | See [Connect a destination](/get-started/connect-a-destination) for the general flow. </Step> <Step title="Connect data sources for attribution"> If you plan to use the Analytics dashboard, connect your Sources for spend data — Shopify, Meta, Google, and TikTok are available as OAuth connections. Spend from these sources powers ROAS and multi-touch attribution. </Step> </Steps> ### Phase 2 — Verify Upstack events (Days 1–3) With both tools running, confirm Upstack is correctly capturing and forwarding events. <Steps> <Step title="Check Meta Events Manager"> 1. Open [Meta Events Manager](https://business.facebook.com/events_manager). 2. Select your pixel. 3. In the **Overview** or **Test Events** tab, look for events sent via the **Conversions API** (server) channel. 4. Verify you see recent events for `PageView`, `ViewContent`, `AddToCart`, `InitiateCheckout`, and `Purchase`. During the parallel-run window, event counts will be higher than normal because both Elevar and Upstack are sending. Meta deduplicates events using `event_id` — if both tools send the same event with the same ID, Meta counts it once. </Step> <Step title="Place a test order"> 1. Place a test order on your store (or wait for a real one). 2. In Events Manager, verify a Purchase event from Upstack's CAPI source appears within a few minutes. 3. Check that the event carries the correct value, currency, and customer matching parameters. </Step> <Step title="Check EMQ scores"> After 24–48 hours of parallel running, check your EMQ scores in Events Manager. They may temporarily appear elevated due to the additional events from Upstack. This normalizes after you remove Elevar. </Step> </Steps> ### Phase 3 — Disable Elevar (Days 3–4) Once Upstack events are flowing correctly, remove Elevar. Do this methodically — Elevar leaves tracking code in multiple locations. <Warning> **Don't skip the cleanup steps.** Uninstalling the Elevar Shopify app does **not** remove its theme snippets, GTM tags, or Shopify Customer Events pixel. Leftover code is the #1 cause of duplicate events after migration. </Warning> <Steps> <Step title="Disable Elevar in your Shopify theme"> Elevar installs render snippets in your Shopify theme. Remove them from your theme code: 1. Sign in to your [Shopify Admin](https://admin.shopify.com), then navigate to **Online Store → Themes**. 2. On your live theme, click **... → Edit code**. 3. Open `theme.liquid` and search for any of these render tags: * `{% render 'elevar-head-listener' %}` * `{% render 'elevar-head' %}` * `{% render 'elevar-body-end' %}` 4. Delete each render tag you find. 5. If your theme still has a `checkout.liquid` file (legacy stores), search for and remove similar Elevar render tags there as well. 6. In the **Snippets** folder, search for files containing `elevar` in the name. Delete each Elevar snippet file. </Step> <Step title="Remove Elevar from Shopify Customer Events"> 1. In [Shopify Admin](https://admin.shopify.com), navigate to **Settings → Customer events**. 2. If Elevar has a Custom Pixel configured here, remove it or set it to inactive. </Step> <Step title="Clean up GTM (if applicable)"> If Elevar managed a Google Tag Manager container: 1. Sign in to [Google Tag Manager](https://tagmanager.google.com) and open your container (ID format `GTM-XXXXXXX`). 2. Identify all tags Elevar created — typically Meta Pixel, Google Ads conversion tracking, and any other platform-specific tags. 3. Pause or delete Elevar-specific tags. Do **not** delete custom tags you've added independently. 4. If the container was used exclusively by Elevar and you have no other tags in it, consider removing the GTM container script from your Shopify theme entirely. </Step> <Step title="Disable Shopify's native Meta data sharing"> Shopify's built-in Meta integration sends events independently. If left on alongside Upstack, it creates duplicates. 1. In [Shopify Admin](https://admin.shopify.com), navigate to **Settings → Customer events** or **Settings → Apps and sales channels → Facebook & Instagram**. 2. Disable the native data sharing / pixel integration if it's active. Full walkthrough: [Disable existing tracking](/get-started/disable-existing-tracking). </Step> <Step title="Uninstall the Elevar app"> 1. In [Shopify Admin](https://admin.shopify.com), navigate to **Settings → Apps and sales channels**. 2. Find **Elevar** in the list and click **Uninstall** (or **Remove app**). 3. Confirm the uninstallation. </Step> </Steps> ### Phase 4 — Post-migration verification (Days 4–11) <Steps> <Step title="Verify no duplicate events"> 1. Install the [Upstack Data Pixel Helper](/guides/shopify/how-to-install-upstack-data-pixel-helper) Chrome extension. 2. Browse your store — visit a product page, add to cart, and check out. 3. On each page, Pixel Helper should show events from Upstack only. If you see duplicate events, Elevar code or Shopify's native integration may still be active. </Step> <Step title="Compare event volumes"> After 48 hours running Upstack only, compare against your baseline: | Metric | Pre-migration baseline | Post-migration target | | ------------------------------------------- | ---------------------- | --------------------- | | Daily Purchase events | \[your baseline] | Equal or higher | | Daily AddToCart events | \[your baseline] | Equal or higher | | Daily ViewContent events | \[your baseline] | Equal or higher | | Shopify orders vs. Events Manager purchases | \[your baseline] | Near 1:1 | If Upstack's volumes are lower than your Elevar baseline, check that all destinations are properly connected and that no events are failing in the [Upstack dashboard](https://app.upstackdata.com). </Step> <Step title="Check EMQ after 48 hours"> EMQ scores need 48 hours to stabilize after the transition. Compare against your saved baseline: * **Improved or steady:** Migration is healthy. * **Dropped:** Confirm Upstack is sending the full set of customer matching parameters (email, phone, click IDs, browser data). If scores don't recover within 72 hours, see [Why is my Meta EMQ panel showing zeros?](/guides/facebook-ads/why-is-my-meta-emq-panel-showing-zeros-0-0-10) or contact Upstack support. </Step> <Step title="Monitor for 7 days"> Don't declare the migration complete until you've monitored for a full week. Check daily: * Event counts in [Meta Events Manager](https://business.facebook.com/events_manager) match Shopify activity. * No error events or failed deliveries in the [Upstack dashboard](https://app.upstackdata.com). * Campaign performance (CPA, ROAS) remains stable. * EMQ scores hold at pre-migration levels or better. </Step> </Steps> ## Common gotchas <AccordionGroup> <Accordion title="Elevar leaves hardcoded scripts in your theme"> Even after uninstalling the Elevar app, render tags and snippet files in your Shopify theme remain. Remove them manually (see Phase 3, Step 1). If left in place, they can cause JavaScript errors or attempt to load resources that no longer exist. </Accordion> <Accordion title="GTM container still fires Elevar tags"> If Elevar set up tags in a GTM container, uninstalling the app does **not** remove those tags. They keep firing until you manually pause or delete them in GTM. This is the most common source of duplicate events after migration. </Accordion> <Accordion title="Shopify's built-in data sharing is still on"> Shopify's native Meta integration sends events independently of any third-party tracking app. If it was enabled alongside Elevar, it stays on after Elevar is removed — and now creates duplicates with Upstack. Always check and disable this during migration. </Accordion> <Accordion title="Temporary event volume drop during cutover"> When you disable Elevar and before Upstack has fully ramped, there may be a brief window (typically a few hours) where event volume dips. This is normal and resolves as Upstack's pipeline picks up all incoming events. If the drop persists beyond 24 hours, contact Upstack support. </Accordion> <Accordion title="Checkout extensibility considerations"> Shopify has deprecated `checkout.liquid` for checkout tracking. If your Elevar setup relied on `checkout.liquid` scripts, those are already non-functional on Shopify's new checkout. Upstack's tracking works with Shopify's current Checkout Extensibility framework, so no additional checkout configuration is needed. </Accordion> <Accordion title="Historical pixel data remains"> Migrating from Elevar to Upstack does not erase your pixel's historical data. All previously recorded events, audiences, and optimization learnings in Meta, Google, and other platforms remain intact. You're changing the data pipeline, not the destination. </Accordion> </AccordionGroup> ## When to contact Upstack support Reach out if: * Events are not appearing in Events Manager after 24 hours of Upstack being active. * EMQ scores drop significantly (more than 2 points) and don't recover within 72 hours. * You see duplicate events that you can't trace to Elevar remnants or Shopify's native integration. * Your Upstack dashboard shows delivery errors for any connected destination. * You need help identifying and removing Elevar scripts from your Shopify theme. ## Frequently asked questions <AccordionGroup> <Accordion title="Will I lose my historical pixel data when I migrate?"> No. Your pixel's historical event data, custom audiences, and optimization learnings remain in Meta Events Manager (and other platforms) regardless of which tracking tool sends the events. You're changing the data pipeline, not resetting the destination. </Accordion> <Accordion title="How long should I run Elevar and Upstack in parallel?"> Two to three days is typically sufficient. You need enough time for Upstack to send events across all your standard event types (PageView through Purchase) and for you to verify them in Events Manager. A few days of slightly elevated event counts is far better than a gap in tracking data. </Accordion> <Accordion title="Will running both tools simultaneously cause duplicate events?"> Yes, temporarily. During the parallel run, both Elevar and Upstack will send events to your connected platforms. Meta and most platforms deduplicate events using `event_id`. Once you disable Elevar, duplicates stop. If you see persistent duplicates after removing Elevar, check for residual scripts in your theme, GTM tags, and Shopify's native data sharing. </Accordion> <Accordion title="Do I need to reconfigure my ad campaigns after migration?"> No. Your campaigns, ad sets, and optimization settings reference your pixel ID and conversion events — none of which change during migration. Upstack sends to the same pixel and uses the same standard event names. Your campaigns continue running without interruption. </Accordion> <Accordion title="What if my EMQ scores drop after migration?"> Give it 48–72 hours for scores to stabilize. Upstack's identity enrichment typically maintains or improves EMQ because it attaches more customer matching parameters to each event. If scores remain lower than your baseline after 72 hours, contact support to review your destination configuration. </Accordion> <Accordion title="Can I migrate if I have custom events set up in Elevar?"> Yes. Document your custom events before migration (see the pre-migration checklist) and confirm with the Upstack team that the same custom events can be configured. Standard events are supported by default. See [How to create custom event triggers in Upstack](/guides/custom-events/how-to-create-custom-event-triggers). </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Install on Shopify" icon="shopify" href="/get-started/install-on-shopify"> Get Upstack's tracking app deployed on your Shopify store. </Card> <Card title="Connect a destination" icon="plug" href="/get-started/connect-a-destination"> Connect Meta, Google, TikTok, Klaviyo, and other destinations. </Card> <Card title="Disable existing tracking" icon="ban" href="/get-started/disable-existing-tracking"> Cleanup steps for legacy pixels, GTM tags, and native Shopify integrations. </Card> <Card title="Meta CAPI destination" icon="meta" href="/destinations/meta-capi"> Configure server-side event delivery to Meta. </Card> <Card title="Google Ads destination" icon="google" href="/destinations/google-ads"> Set up Google Ads conversion delivery. </Card> <Card title="TikTok destination" icon="music" href="/destinations/tiktok"> Configure TikTok Events API delivery. </Card> <Card title="Klaviyo destination" icon="envelope" href="/destinations/klaviyo"> Set up identity-enriched profile delivery to Klaviyo. </Card> <Card title="Why is my Meta EMQ panel showing zeros?" icon="circle-question" href="/guides/facebook-ads/why-is-my-meta-emq-panel-showing-zeros-0-0-10"> Troubleshoot Event Match Quality scores after migration. </Card> </CardGroup> # Complete How-To Guide for Onboarding Omnisend in Upstack Data Source: https://docs.upstackdata.com/guides/omnisend/complete-how-to-guide-for-onboarding-omnisend-in-upstack-data Onboard Omnisend in Upstack Data — generate the Omnisend API key, configure the destination, and forward identity-enriched events to power email and SMS automation flows. <Tip> **Quick Summary** * Sign in to [Omnisend](https://app.omnisend.com) and generate an **API key** * Sign in to your [Upstack dashboard](https://app.upstackdata.com) * **Configure the Omnisend destination** using your API key * Click **Create Configuration** and verify the destination shows as **Healthy** </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to your [Omnisend](https://app.omnisend.com) account * Permission to create API keys in Omnisend ## Onboarding Steps <Steps> <Step title="Generate your Omnisend API key"> <Note> An **Omnisend API key** is a unique credential generated in your Omnisend account that allows Upstack Data to securely access and interact with your Omnisend data. It is a long alphanumeric string, typically structured as a 64-character secret followed by a `-` and a short identifier (for example, `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxx`). </Note> Help guide to complete this step: [How to Generate your Omnisend API Key →](/guides/omnisend/how-to-generate-your-omnisend-api-key) </Step> <Step title="Configure the Omnisend destination in your Upstack dashboard"> Help guide to complete this step: [How to Configure Omnisend Pixel Destination in Upstack Data →](/guides/omnisend/how-to-configure-omnisend-pixel-destination-in-upstack-data) </Step> <Step title="Verify the Omnisend destination is healthy"> In your [Upstack dashboard](https://app.upstackdata.com/pixel/event-destinations), open **Events Destination** and confirm the **Omnisend** destination shows a **Healthy** status. Then, in [Omnisend](https://app.omnisend.com), open **Audience** or **Reports** and confirm contacts and events from Upstack Data are arriving as expected. </Step> </Steps> <Note> **Need help?** If you encounter any issues during setup or don't see expected improvements after 10 days, contact our support team with your Omnisend API key and we'll help diagnose the problem. </Note> # How to Configure Omnisend Pixel Destination in Upstack Data Source: https://docs.upstackdata.com/guides/omnisend/how-to-configure-omnisend-pixel-destination-in-upstack-data Configure the Omnisend destination in Upstack Data with your Omnisend API key — forwarding browse, cart, checkout, and purchase events to power email and SMS automation triggers. <Tip> **Quick Summary** * In the Upstack dashboard, open **Events Destination** and click **+ New Destination** * Select **Omnisend** from the destination options * Enter your generated **Omnisend API key** * Click **Create Configuration** and verify the destination shows as **Healthy** </Tip> <Note> **What this setup enables** Configuring Omnisend as a destination in Upstack Data ensures accurate tracking of customer events, consolidates attribution reporting, and provides more reliable data to optimize ad performance. </Note> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to your [Omnisend](https://app.omnisend.com) account * Your Omnisend **API key** ([how to generate it](/guides/omnisend/how-to-generate-your-omnisend-api-key)) ## Configuration Steps <Steps> <Step title="Sign in to your Upstack dashboard"> Sign in to [Upstack Data](https://app.upstackdata.com) and open the [Events Destination](https://app.upstackdata.com/pixel/event-destinations) page. </Step> <Step title="Add a new Omnisend destination"> In the **Events Destination** page, click **+ New Destination** in the top-right of the page. <img alt="Add New Destination" /> In the **Select a Destination** popup, click **Omnisend**, then click **Next**. <img alt="Select a Destination popup with Omnisend option highlighted" /> </Step> <Step title="Enter your Omnisend API key"> In the configuration form, paste your generated **Omnisend API key** into the **API key** field. The API key is a long alphanumeric string, typically formatted as a 64-character secret followed by a `-` and a short identifier (for example, `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxx`). <img alt="Omnisend destination configuration form with API key field" /> </Step> <Step title="Create the configuration"> Click the **Create Configuration** button at the bottom of the form. <img alt="Create Configuration button at bottom of Omnisend destination form" /> <Note> **Success! 🎉** You should see a confirmation message and the Omnisend destination will appear as **Healthy** in your destinations list. </Note> <Note> Here's a help guide on **[How to Generate your Omnisend API Key →](/guides/omnisend/how-to-generate-your-omnisend-api-key)** </Note> </Step> <Step title="Verify the destination is sending events"> Back in the [Events Destination](https://app.upstackdata.com/pixel/event-destinations) page, confirm the new **Omnisend** destination shows a **Healthy** status. Then, in [Omnisend](https://app.omnisend.com), open **Audience** or **Reports** and confirm contacts and events from Upstack Data are arriving as expected. New events typically appear within a few minutes after a test purchase or page view. </Step> </Steps> # How to Generate your Omnisend API Key Source: https://docs.upstackdata.com/guides/omnisend/how-to-generate-your-omnisend-api-key Generate or locate your Omnisend API key in the Omnisend dashboard — required to authenticate the Upstack Data Omnisend destination and forward server-side events. <Tip> **Quick Summary** * Sign in to [Omnisend](https://app.omnisend.com) * Open **Store settings → API** * Click **+ Create API key**, name it `UpstackData`, then click **Create API key** * **Copy** the generated API key and store it securely (Omnisend only shows it once) * Paste the API key into the Omnisend destination form in your Upstack dashboard </Tip> <Note> What is an **Omnisend API key**? An **Omnisend API key** is a unique credential generated in your Omnisend account that allows Upstack Data to securely access and interact with your Omnisend data. It is a long alphanumeric string, typically structured as a 64-character secret followed by a `-` and a short identifier (for example, `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxx`). </Note> ## Prerequisites Before you start, you need: * Admin access to your [Omnisend](https://app.omnisend.com) account * Permission to create API keys in Omnisend * A secure place to store the generated API key (Omnisend only displays it once) ## Steps to Generate the API Key <Steps> <Step title="Sign in to Omnisend"> Sign in to [Omnisend](https://app.omnisend.com) to open your dashboard. In the left-hand menu, click **Store settings**, then go to the **API** tab. <img alt="Omnisend left menu with Store settings option highlighted" /> <img alt="Omnisend Store settings page with API tab selected" /> </Step> <Step title="Create a new API key"> On the **API** settings page, click the **+ Create API key** button. <img alt="Omnisend API settings page with Create API key button" /> Enter `UpstackData` as the API key name, then click **Create API key**. <img alt="Create API key dialog with UpstackData name entered" /> </Step> <Step title="Copy and save your API key"> Click the **Copy API key** button to copy the generated API key, then store it securely (for example, in a password manager). Paste the API key into the **API key** field when [configuring the Omnisend destination](/guides/omnisend/how-to-configure-omnisend-pixel-destination-in-upstack-data) in your Upstack dashboard. <Warning> This API key is only shown once — copy it immediately. The API key is sensitive: anyone with it can read and write data in your Omnisend account, so store it in a secure location and never share it. </Warning> <img alt="Omnisend API key generated with Copy API key button" /> </Step> <Step title="Verify the API key format"> Confirm the value you copied is a long alphanumeric string with no extra spaces — typically a 64-character secret followed by a `-` and a short identifier. You can paste it into the **API key** field when configuring the Omnisend destination in your Upstack dashboard. </Step> </Steps> <Note> Here's a help guide on **[How to Configure Omnisend Pixel Destination in Upstack Data →](/guides/omnisend/how-to-configure-omnisend-pixel-destination-in-upstack-data)** </Note> # Complete How-To Guide for Onboarding Outbrain in Upstack Data Source: https://docs.upstackdata.com/guides/outbrain/complete-how-to-guide-for-onboarding-outbrain-in-upstack-data Onboard Outbrain Amplify in Upstack Data — locate your Marketer ID, configure the click ID tracking, and set up the destination for server-side conversion forwarding. <Info> **New to Upstack?** Follow the [getting started guide](/get-started/install-on-shopify) for a streamlined onboarding walkthrough. </Info> <Tip> * Configure the **Outbrain destination** in Upstack Data with your **Marketer ID**. * Add `obclid={{ob_click_id}}` to your **campaign URL suffix** to capture click IDs. * Verify events appear in **Outbrain Amplify Dashboard → Conversions**. * Monitor attribution improvements over 7-10 days of campaign traffic. </Tip> <Warning> **Critical limitation:** Unlike Meta, TikTok, and Reddit, Outbrain does **NOT** support enhanced matching with hashed email or phone. Attribution relies **solely on click ID (`obclid`)**. Events from visitors without a click ID are skipped — they cannot be attributed to any campaign. </Warning> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to an **Outbrain Amplify** account * Your **Outbrain Marketer ID** from [Amplify Dashboard → Settings → Tracking](https://amplify.outbrain.com/) * Active Outbrain campaigns with click ID tracking configured <Steps> <Step title="Configure click ID tracking in your campaigns"> Add the click ID parameter to your campaign tracking URLs so Upstack can capture and store the click ID for attribution. **Add to your campaign URL suffix:** ``` obclid={{ob_click_id}} ``` Help guide: [How to configure Outbrain click ID tracking →](/guides/outbrain/how-to-configure-outbrain-click-id-tracking) </Step> <Step title="Find your Outbrain Marketer ID"> Locate your Marketer ID (also called OB\_ADV\_ID) in the Outbrain Amplify dashboard. This 32-character hexadecimal string identifies your account for conversion tracking. Help guide: [How to find your Outbrain Marketer ID →](/guides/outbrain/how-to-find-outbrain-marketer-id) </Step> <Step title="Configure the Outbrain destination in Upstack Data"> In the Upstack dashboard, navigate to **Event Destinations** and add an **Outbrain** destination using your **Marketer ID**. Help guide: [How to configure the Outbrain destination in Upstack Data →](/guides/outbrain/how-to-configure-outbrain-destination-in-upstack-data) </Step> <Step title="Verify the full setup is healthy"> Confirm each piece of the setup is working: * In the Upstack dashboard, **Event Destinations** shows your Outbrain destination as **Healthy** (green). * In [Outbrain Amplify Dashboard](https://amplify.outbrain.com/), the **Conversions** page shows recent events. * Test with a real ad click — clicking your own ad and completing a purchase should generate a tracked conversion within 5-10 minutes. If anything is unhealthy, check the corresponding help guide above for troubleshooting steps. </Step> </Steps> ## What to expect after setup ### Attribution limitations Unlike other ad platforms (Meta, TikTok, Reddit, Google), Outbrain only attributes conversions when a click ID is present: | Scenario | Attribution | | ----------------------------------------------------- | ------------------------------------------ | | User clicks ad with `obclid`, converts same session | ✅ Attributed | | User clicks ad with `obclid`, converts within 30 days | ✅ Attributed (if cookie persists) | | User visits directly without ad click | ❌ Skipped (no click ID) | | User clears cookies between click and conversion | ❌ Skipped (click ID lost) | | User clicks on mobile, converts on desktop | ❌ Skipped (different device/cookie) | | Known customer with email, no click ID | ❌ Skipped (email not used for attribution) | ### Conversion reporting timeline * **Initial conversions** start appearing in Amplify within 5-10 minutes of real ad clicks and purchases. * **Full attribution picture** emerges over 7-10 days as more users complete the click → conversion journey. * **Lower attribution rates** compared to Meta/TikTok are expected — this reflects Outbrain's click-only attribution model, not a tracking issue. ### Deduplication Outbrain deduplicates based on `orderId`. If you're running both the Outbrain browser pixel and Upstack server-side delivery, ensure both send the same `orderId` value for the same transaction to avoid double-counting. <Note> **Need help?** If you encounter any issues during setup or don't see conversions appearing after confirming ad clicks, contact our [support team](/support) with your **Outbrain Marketer ID** and we'll help diagnose the problem. </Note> # How to Configure Outbrain Click ID Tracking Source: https://docs.upstackdata.com/guides/outbrain/how-to-configure-outbrain-click-id-tracking Add the Outbrain click ID parameter to your campaign URL suffix — required for server-side conversion attribution via Upstack Data. <Tip> * Open your campaign in **Outbrain Amplify Dashboard**. * Navigate to the **Tracking** or **URL Parameters** section. * Add `obclid={{ob_click_id}}` to your **URL suffix** or tracking template. * Save and verify URLs include the click ID on ad clicks. </Tip> <Warning> **This step is critical.** Outbrain does **NOT** support enhanced matching with email or phone. Attribution relies **solely** on the click ID (`obclid`). Without this parameter in your campaign URLs, Upstack cannot attribute any conversions to Outbrain — all events will be skipped. </Warning> <Note> **What is the Outbrain click ID?** The **click ID** (also called `ob_click_id` or `obclid`) is a unique identifier that Outbrain generates for each ad click. When a user clicks your ad, Outbrain appends this ID to your landing page URL. Upstack captures and stores this ID in a first-party cookie, then includes it with every conversion event so Outbrain can match the conversion back to the original ad click. </Note> ## Prerequisites Before you start, you need: * Access to an **Outbrain Amplify** account at [amplify.outbrain.com](https://amplify.outbrain.com/) * Campaign edit permissions * Active or draft campaigns to update ## Steps to configure click ID tracking <Steps> <Step title="Sign in to Outbrain Amplify"> Sign in to Outbrain Amplify at [amplify.outbrain.com](https://amplify.outbrain.com/). </Step> <Step title="Open your campaign"> Navigate to **Campaigns** and select the campaign you want to configure. Click **Edit** or **Settings** to access the campaign configuration. </Step> <Step title="Find the URL parameters section"> Look for **Tracking**, **URL Parameters**, **URL Suffix**, or **Tracking Template** in the campaign settings. This is where you add parameters that Outbrain will append to your landing page URLs. </Step> <Step title="Add the click ID parameter"> Add the following to your URL suffix: ``` obclid={{ob_click_id}} ``` **If you already have other tracking parameters** (like UTM tags), append the click ID with an ampersand: ``` utm_source=outbrain&utm_medium=native&utm_campaign={{campaign_name}}&obclid={{ob_click_id}} ``` <Tip> The `{{ob_click_id}}` placeholder is a dynamic macro that Outbrain replaces with the actual click ID when a user clicks your ad. </Tip> </Step> <Step title="Save the campaign"> Click **Save** or **Apply** to save your changes. </Step> <Step title="Verify the configuration"> To verify the click ID is being appended: 1. Preview your ad or click on it from a test placement 2. Check the landing page URL in your browser's address bar 3. Confirm you see `obclid=v1-abc123...` (a long alphanumeric string starting with `v1-`) **Example URL after click:** ``` https://yourstore.com/products/widget?utm_source=outbrain&obclid=v1-abc123xyz789def456ghi789jkl012 ``` </Step> <Step title="Update all active campaigns"> Repeat steps 2-5 for **all your active Outbrain campaigns**. <Warning> Any campaign missing the `obclid` parameter will not have its conversions attributed. Make sure to update all campaigns, including existing ones. </Warning> </Step> </Steps> ## How Upstack captures the click ID Once your campaigns are configured: 1. **User clicks ad** → Outbrain appends `obclid=v1-...` to the landing page URL 2. **Upstack Pixel loads** → Captures the `obclid` from the URL and stores it in a first-party cookie (`_obclid`) 3. **User converts** → Upstack includes the stored click ID with the conversion event 4. **Event sent to Outbrain** → Outbrain matches the conversion to the original ad click The click ID cookie expires after 30 days, matching Outbrain's attribution window. ## Alternative parameter name Outbrain also recognizes `ob_click_id` as a URL parameter name. Both work identically: * `obclid={{ob_click_id}}` ✅ Recommended (shorter) * `ob_click_id={{ob_click_id}}` ✅ Also works Upstack captures both parameter names automatically. ## Troubleshooting ### Click ID not appearing in URL If the click ID isn't being appended after clicking your ad: 1. Verify the URL suffix is saved correctly in the campaign settings 2. Check for typos — the macro must be exactly `{{ob_click_id}}` 3. Clear your browser cache and try clicking the ad again 4. Contact Outbrain support if the issue persists ### Conversions not being attributed If you've configured the click ID but conversions aren't appearing in Amplify: 1. Verify the Upstack Pixel is loading on your landing pages (check browser dev tools) 2. Confirm the `_obclid` cookie is being set after ad clicks 3. Check that your Upstack destination shows **Healthy** status 4. Wait 5-10 minutes — conversions aren't instant <Note> **Next step:** [How to configure the Outbrain destination in Upstack Data](/guides/outbrain/how-to-configure-outbrain-destination-in-upstack-data) </Note> # How to Configure Outbrain Destination in Upstack Data Source: https://docs.upstackdata.com/guides/outbrain/how-to-configure-outbrain-destination-in-upstack-data Configure the Outbrain destination in Upstack Data to forward server-side conversion events to Outbrain's Unified Pixel API for native advertising attribution. <Tip> * Navigate to **Event Destinations** in the Upstack dashboard. * Click **Add Destination** and select **Outbrain**. * Enter your **Marketer ID** (32-character hexadecimal string from Amplify). * Save the configuration and verify the destination shows **Healthy**. </Tip> <Note> **What is the Outbrain Marketer ID?** Your **Outbrain Marketer ID** (also called **OB\_ADV\_ID** or **Pixel ID**) is a unique 32-character hexadecimal identifier that tells Upstack which Outbrain account should receive your conversion events. Find it in [Amplify Dashboard → Settings → Tracking](https://amplify.outbrain.com/). </Note> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Your **Outbrain Marketer ID** — see [How to find your Outbrain Marketer ID](/guides/outbrain/how-to-find-outbrain-marketer-id) * Click ID tracking configured in your campaigns — see [How to configure Outbrain click ID tracking](/guides/outbrain/how-to-configure-outbrain-click-id-tracking) ## Steps to configure the Outbrain destination <Steps> <Step title="Sign in to Upstack Data"> Sign in to your Upstack Data account at [app.upstackdata.com](https://app.upstackdata.com). </Step> <Step title="Navigate to Event Destinations"> In the left-hand navigation, click **Event Destinations**. </Step> <Step title="Add a new destination"> Click the **Add Destination** button in the top-right corner. In the destination picker, select **Outbrain** from the list of available destinations. </Step> <Step title="Enter your Marketer ID"> In the **Outbrain Marketer ID** field, paste your Marketer ID from the Outbrain Amplify dashboard. **Example format:** `00abc123def456789012345678901234` (32 hexadecimal characters) <Tip> Ensure there are no extra spaces before or after the ID. The value should be exactly 32 characters. </Tip> </Step> <Step title="Configure event settings (optional)"> By default, Upstack forwards **Purchase**, **Lead**, **SignUp**, and **AddToCart** events to Outbrain. High-volume events like **PageView** and **ViewContent** are disabled by default to avoid unnecessary API calls — you can enable them if needed for your use case. </Step> <Step title="Save the configuration"> Click **Create Configuration** to save the destination. </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, navigate to **Event Destinations**. Your Outbrain destination should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**, double-check: * The Marketer ID is exactly 32 hexadecimal characters * No extra whitespace or special characters * The ID matches what you see in Amplify → Settings → Tracking </Step> </Steps> <Warning> **Remember:** Outbrain only attributes conversions when a click ID (`obclid`) is present. Make sure your campaign URLs include `obclid={{ob_click_id}}` — see [How to configure Outbrain click ID tracking](/guides/outbrain/how-to-configure-outbrain-click-id-tracking). </Warning> <Note> **Next step:** [Complete onboarding guide](/guides/outbrain/complete-how-to-guide-for-onboarding-outbrain-in-upstack-data) for the full setup walkthrough. </Note> # How to Find Your Outbrain Marketer ID Source: https://docs.upstackdata.com/guides/outbrain/how-to-find-outbrain-marketer-id Find your Outbrain Marketer ID in the Amplify Dashboard — required to configure the Upstack Data Outbrain destination for server-side conversion forwarding. <Tip> * Sign in to [Outbrain Amplify Dashboard](https://amplify.outbrain.com/). * Navigate to **Settings → Tracking** (or **Account Settings → Pixel**). * Locate the **Marketer ID** (also called OB\_ADV\_ID or Pixel ID). * Copy the 32-character hexadecimal string and paste it into Upstack. </Tip> <Note> **What is an Outbrain Marketer ID?** Your **Outbrain Marketer ID** (also known as **OB\_ADV\_ID** or **Advertiser ID**) is a unique 32-character hexadecimal identifier that Upstack Data uses to send conversion data to your Outbrain account. This ID is also embedded in the Outbrain pixel code if you've installed it manually. </Note> ## Prerequisites Before you start, you need: * Access to an **Outbrain Amplify** account at [amplify.outbrain.com](https://amplify.outbrain.com/) * Account admin or campaign manager permissions ## Steps to find your Outbrain Marketer ID <Steps> <Step title="Sign in to Outbrain Amplify"> Sign in to Outbrain Amplify at [amplify.outbrain.com](https://amplify.outbrain.com/). If you have multiple accounts, select the account you want to connect to Upstack. </Step> <Step title="Navigate to Settings"> Click your account name or profile icon in the top-right corner, then select **Settings**. Alternatively, look for a **Settings** or **Account Settings** option in the navigation menu. </Step> <Step title="Open Tracking settings"> In the Settings menu, click **Tracking** or **Pixel** to view your tracking configuration. This page contains your Outbrain pixel installation code and Marketer ID. </Step> <Step title="Locate your Marketer ID"> Look for the **Marketer ID**, **OB\_ADV\_ID**, **Advertiser ID**, or **Pixel ID** field. **Example format:** `00abc123def456789012345678901234` The Marketer ID is a 32-character hexadecimal string (letters a-f and numbers 0-9 only). <Tip> If you see the pixel installation code, the Marketer ID is the value assigned to `OB_ADV_ID` in the JavaScript snippet: ```javascript theme={null} var OB_ADV_ID = '00abc123def456789012345678901234'; ``` </Tip> </Step> <Step title="Copy the Marketer ID"> Copy the full 32-character Marketer ID. <Warning> Make sure to copy the complete ID with no extra spaces or characters. The ID must be exactly 32 hexadecimal characters. </Warning> </Step> <Step title="Paste into Upstack Data"> In the Upstack dashboard, navigate to **Event Destinations → Add Destination → Outbrain**. Paste the Marketer ID into the **Outbrain Marketer ID** field. </Step> <Step title="Save and verify"> Click **Create Configuration** to save the destination. Your Outbrain destination should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**, double-check that the Marketer ID was copied correctly without extra whitespace. </Step> </Steps> ## Troubleshooting ### Can't find the Marketer ID in Settings If you don't see a Tracking or Pixel section in Settings: 1. Check if you have admin permissions — campaign-level users may not see account settings 2. Look for **Events** or **Conversions** in the navigation menu 3. Contact your Outbrain account manager if you still can't locate it ### Marketer ID validation fails in Upstack If Upstack reports an invalid Marketer ID: 1. Verify the ID is exactly 32 characters 2. Confirm it contains only hexadecimal characters (0-9, a-f) 3. Remove any extra spaces, quotes, or special characters 4. Re-copy from the Amplify dashboard <Note> **Next step:** [How to configure Outbrain click ID tracking](/guides/outbrain/how-to-configure-outbrain-click-id-tracking) — required for attribution to work. </Note> # Complete How-To Guide for Onboarding Pinterest in Upstack Data Source: https://docs.upstackdata.com/guides/pinterest-ads/complete-how-to-guide-for-onboarding-pinterest-in-upstack-data Onboard Pinterest in Upstack Data — generate the Pinterest Conversions API token, locate your Pixel and Advertiser IDs, configure the destination, and disable Shopify's duplicate Pinterest pixel. <Tip> **Quick Summary** * **Locate and copy** your **Pinterest Pixel Tag ID** and **Advertiser ID** * **Generate and copy** your **Pinterest Conversion API key** * **Create and configure** the Pinterest destination in your Upstack dashboard * **Disable Pinterest data sharing** in Shopify </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to your Pinterest Business account * A Shopify store admin account (only required for the data-sharing step) ## Onboarding Steps <Steps> <Step title="Find and copy your Pixel Tag ID"> <Note> What is a **Pinterest Pixel Tag ID?** A **Pinterest Pixel Tag ID** is a unique identifier assigned to your Pinterest Pixel, which tracks user actions (like page views, add-to-cart, or purchases) on your website. It's what you use to connect your site activity with Pinterest Ads for measurement and optimization. The ID is a 13-digit number (for example, `2613000000000`). </Note> Help guide to complete this step: [How to Find Pinterest Pixel Tag ID →](/guides/pinterest-ads/how-to-find-pinterest-pixel-tag-id) </Step> <Step title="Find and copy your Advertiser ID"> <Note> What is a **Pinterest Advertiser ID?** A **Pinterest Advertiser ID** is a unique numeric identifier assigned to your Pinterest Business advertising account. It is typically a 12-digit number (for example, `549000000000`). </Note> Help guide to complete this step: [How to Find Pinterest Advertiser ID →](/guides/pinterest-ads/how-to-find-pinterest-advertiser-id) </Step> <Step title="Generate your Conversion API key"> <Note> What is a **Pinterest Conversion API key** (access token)? A **Pinterest Conversion API key** (access token) is a secure credential that lets your server send conversion events, like purchases or sign-ups, directly to Pinterest. It improves tracking accuracy, attribution, and data security compared to the standard Pixel. The token starts with `pina_` and is roughly 90+ characters long. </Note> Help guide to complete this step: [How to Generate Pinterest Conversion API Key →](/guides/pinterest-ads/how-to-generate-pinterest-conversion-api-key-access-token) </Step> <Step title="Create and configure the Pinterest destination in your Upstack dashboard"> <Note> Integrating Pinterest with Upstack Data centralizes tracking, improves attribution, and enables better campaign optimization and reporting. </Note> Help guide to complete this step: [How to Configure Pinterest Destination in Upstack Data →](/guides/pinterest-ads/how-to-configure-pinterest-destination-in-upstack-data) </Step> <Step title="Disable Pinterest data sharing in Shopify"> <Warning> Turning off Pinterest data sharing helps avoid duplicate or conflicting conversions, keeping Upstack Data as your one reliable source of accurate performance data. </Warning> Help guide to complete this step: [How to Disable Pinterest Data Sharing →](/guides/pinterest-ads/how-to-disable-pinterest-data-sharing-in-shopify) </Step> <Step title="Verify the Pinterest destination is healthy"> In your [Upstack dashboard](https://app.upstackdata.com/pixel/event-destinations), open **Events Destination** and confirm the **Pinterest** destination shows a **Healthy** status. Then, in [Pinterest Business](https://business.pinterest.com), open **Conversions → Pinterest tag** and confirm events are arriving from your Conversions API integration. </Step> </Steps> <Note> **Need help?** If you encounter any issues during setup or don't see expected improvements after 10 days, contact our support team and we'll help diagnose the problem. </Note> # How to Configure Pinterest Destination in Upstack Data Source: https://docs.upstackdata.com/guides/pinterest-ads/how-to-configure-pinterest-destination-in-upstack-data Configure the Pinterest destination in Upstack Data with your Pinterest Conversions API key, Pixel ID, and Advertiser ID to forward server-side conversions to Pinterest CAPI. <Tip> **Quick Summary** * In the Upstack dashboard, open **Events Destination** and click **+ New Destination** * Select **Pinterest** from the destination options * Enter your **Pixel Tag ID**, **Advertiser ID**, and **Conversion API key** * Check the box to **enable Pinterest Conversions API** * Click **Create Configuration** and verify the destination shows as **Healthy** </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to your Pinterest Business account * Your Pinterest **Pixel Tag ID** ([how to find it](/guides/pinterest-ads/how-to-find-pinterest-pixel-tag-id)) * Your Pinterest **Advertiser ID** ([how to find it](/guides/pinterest-ads/how-to-find-pinterest-advertiser-id)) * Your Pinterest **Conversion API key** ([how to generate it](/guides/pinterest-ads/how-to-generate-pinterest-conversion-api-key-access-token)) ## Configuration Steps <Steps> <Step title="Sign in to your Upstack dashboard"> Sign in to [Upstack Data](https://app.upstackdata.com) and open the [Events Destination](https://app.upstackdata.com/pixel/event-destinations) page. </Step> <Step title="Add a new Pinterest destination"> In the **Events Destination** page, click **+ New Destination** in the top-right of the page. <img alt="Add New Destination" /> In the **Select a Destination** popup, click **Pinterest**, then click **Next**. <img alt="Select Pinterest from destination options in popup" /> </Step> <Step title="Enter your Pinterest credentials"> Fill out the form with the following: 1. **Pinterest Pixel Tag ID** — a 13-digit number, for example `2613000000000` 2. Check the box **Check to enable sending events via Pinterest Conversions API** 3. **Advertiser ID** — a 12-digit numeric ID, for example `549000000000` 4. **Conversion API key** — the access token starting with `pina_` <Warning> The **Conversions API checkbox must be selected** for server-side tracking to work. </Warning> <img alt="Pinterest destination form with Pixel Tag ID, Advertiser ID, and CAPI key fields" /> <Note> ***Need help finding these?*** **[How to Find Pinterest Pixel Tag ID →](/guides/pinterest-ads/how-to-find-pinterest-pixel-tag-id)** **[How to Generate Pinterest Conversion API Key →](/guides/pinterest-ads/how-to-generate-pinterest-conversion-api-key-access-token)** **[How to Find Pinterest Advertiser ID →](/guides/pinterest-ads/how-to-find-pinterest-advertiser-id)** </Note> </Step> <Step title="Create the configuration"> Click the **Create Configuration** button at the bottom of the form. <img alt="Create Configuration button to save Pinterest destination" /> <Note> **Success! 🎉** You should see a confirmation message and the Pinterest destination will appear as **Healthy** in your destinations list. </Note> </Step> <Step title="Verify the destination is sending events"> Back in the [Events Destination](https://app.upstackdata.com/pixel/event-destinations) page, confirm that the new **Pinterest** destination shows a **Healthy** status. Then, in [Pinterest Business](https://business.pinterest.com), open **Conversions → Pinterest tag** and confirm that events are being received from your Conversions API integration. New events typically appear within a few minutes after a test purchase or page view. </Step> </Steps> # How to Create a New Pinterest Pixel (Tag) ID Source: https://docs.upstackdata.com/guides/pinterest-ads/how-to-create-a-new-pinterest-pixel-tag-id Create a new Pinterest Pixel (Tag) ID in Pinterest Ads Manager — required to configure the Upstack Data Pinterest destination and forward conversions via Pinterest CAPI. <Tip> **Quick Summary** * Sign in to [Pinterest Business](https://business.pinterest.com) and open **Manage business → Conversions** * Under **Pinterest tag**, click **Tag manager** * Start the tag setup and follow the instructions for your chosen installation method * **Copy** your new **Pinterest Pixel Tag ID** * Install the tag on your website and verify it is firing </Tip> ## What is a Pinterest Pixel Tag ID? <Note> A **Pinterest Pixel Tag ID** is a unique identifier assigned to your Pinterest Pixel, which tracks user actions (like page views, add-to-cart, or purchases) on your website. It's what you use to connect your site activity with Pinterest Ads for measurement and optimization. The ID is a 13-digit number (for example, `2613000000000`). </Note> ## Prerequisites Before you start, you need: * Admin access to your Pinterest Business account * The ability to install code on your website (or admin access to a supported integration partner such as Shopify or WooCommerce) ## Steps to Create a New Pixel Tag ID <Steps> <Step title="Sign in to Pinterest Business"> Sign in to [Pinterest Business](https://business.pinterest.com). </Step> <Step title="Open Tag manager"> In the top-left of the page, click the **Menu icon** (three horizontal lines). Under **Manage business**, select **Conversions**. <img alt="" /> Under **Pinterest tag**, click **Tag manager**. <img alt="" /> </Step> <Step title="Start the tag setup"> In the **Pinterest Tag** section, click **Get Started** if this is your first tag, or click **Add code** to create an additional tag. <img alt="" /> You will be prompted to choose your installation method: * **Integration partner** (for example, Shopify, WooCommerce) * **Email instructions** to a developer * **Manual setup** (for direct code installation) Follow the setup instructions for your chosen method. <img alt="" /> <Note> **Choose Manual Setup (if applicable)** * Click **Skip** in the bottom-right of the page to proceed with manual setup. * Pinterest will generate a **base tag code snippet** for you. </Note> </Step> <Step title="Copy the Pinterest Pixel Tag ID"> Once created, your Pinterest tag will appear in **Tag manager** with a 13-digit Pixel Tag ID (for example, `2613000000000`). Copy the Pixel Tag ID — this is what you'll enter when configuring the Pinterest destination in your Upstack dashboard. </Step> <Step title="Install the tag on your website"> Paste the base tag code into the `<head>` section of every page on your website. Add **event codes** to track specific actions (for example, `AddToCart`, `Signup`, `Checkout`). </Step> <Step title="Verify the installation"> Use the [Pinterest Tag Helper Chrome Extension](https://chrome.google.com/webstore/detail/pinterest-tag-helper) to confirm your tag is firing correctly on your website. You can also confirm event delivery in **Pinterest Business → Conversions → Pinterest tag**, where new events typically appear within a few minutes. </Step> </Steps> # How to Disable Pinterest Data Sharing in Shopify Source: https://docs.upstackdata.com/guides/pinterest-ads/how-to-disable-pinterest-data-sharing-in-shopify Disable Shopify's Pinterest sales channel data sharing to stop duplicate Pinterest pixel events and let Upstack Data deliver clean server-side conversions to Pinterest CAPI. <Tip> **Quick Summary** * In Shopify admin, open **Settings → Apps and sales channels** * Find **Pinterest** and click the **three-dot (⋮) menu** * Select **Uninstall** and confirm in the popup </Tip> If you're using **Upstack Data** for Pinterest event tracking, you need to uninstall the **Pinterest Sales Channel** from your Shopify store to remove Shopify's native pixel tracking. <Warning> Disabling Pinterest data sharing is crucial to prevent duplicate events, which can distort reporting and attribution. It ensures Pinterest only receives clean, accurate data through Upstack Data for reliable insights and better ad optimization. </Warning> ## Prerequisites Before you start, you need: * Admin access to your Shopify store ([Shopify admin](https://admin.shopify.com)) * The Pinterest Sales Channel currently installed in Shopify * A configured Pinterest destination in your [Upstack dashboard](https://app.upstackdata.com/pixel/event-destinations) ([setup guide](/guides/pinterest-ads/how-to-configure-pinterest-destination-in-upstack-data)) ## Why You Should Disable Pinterest Data Sharing Shopify's Pinterest Sales Channel automatically enables both catalog and pixel tracking, without allowing you to manage them separately. It can cause duplicate events because it sends conversion data from both your browser and server. When combined with Upstack Data's server-side tracking, this may inflate conversions, ROAS, and event counts. Disabling Pinterest's own data-sharing features allows Upstack Data to: * Ensure consistent and deduplicated event tracking * Improve attribution accuracy across platforms * Maintain reliable performance reporting ## Steps to Disable Pinterest Data Sharing in Shopify <Steps> <Step title="Sign in to Shopify admin"> Sign in to [Shopify admin](https://admin.shopify.com) for the store where Pinterest is installed. </Step> <Step title="Open Apps and sales channels"> In the left-hand menu, click **Settings**, then select **Apps and sales channels**. <img alt="Shopify admin Settings menu with Apps and sales channels selected" /> </Step> <Step title="Uninstall the Pinterest sales channel"> Locate **Pinterest** in the list, click the **three-dot (⋮) menu**, then select **Uninstall**. <img alt="Pinterest sales channel with three-dot menu showing Uninstall option" /> A confirmation window will appear. Review the warning, then click **Uninstall** in the bottom-right of the dialog. <img alt="Shopify uninstall confirmation dialog for Pinterest sales channel" /> </Step> <Step title="Verify Pinterest is no longer connected"> Refresh the **Apps and sales channels** page and confirm **Pinterest** no longer appears in the list of installed channels. Then, in your [Upstack dashboard](https://app.upstackdata.com/pixel/event-destinations), confirm the **Pinterest** destination is still **Healthy** and continuing to send events through Upstack Data. </Step> </Steps> <Note> Uninstalling the Pinterest app in Shopify is important because it helps **prevent duplicate tracking and data conflicts** between Pinterest's native integration and Upstack Data. </Note> <Note> **Need Help?** If you encounter any issues during setup, contact our support team and we'll help diagnose the problem. </Note> # How to Find Pinterest Advertiser ID Source: https://docs.upstackdata.com/guides/pinterest-ads/how-to-find-pinterest-advertiser-id Find your Pinterest Advertiser ID in Pinterest Business Manager — required (alongside the Pixel ID and CAPI token) to configure the Upstack Data Pinterest destination. <Tip> **Quick Summary** * Sign in to [Pinterest Business](https://business.pinterest.com) * In the top-right of the page, click your **Business account name** and select your business * In the left-hand menu, open **Ad Accounts** * Select the ad account you want to use, then **copy** the **Advertiser ID** </Tip> ## What is a Pinterest Advertiser ID? <Note> A **Pinterest Advertiser ID** is a unique numeric identifier assigned to your Pinterest Business advertising account. It is typically a 12-digit number (for example, `549000000000`). </Note> ## Prerequisites Before you start, you need: * Admin access to your Pinterest Business account * At least one Pinterest ad account associated with your business ## Steps to Find Your Advertiser ID <Steps> <Step title="Sign in to Pinterest Business"> Sign in to [Pinterest Business](https://business.pinterest.com). </Step> <Step title="Open Ad Accounts"> In the top-right of the page, click your **Business account name**. <img alt="" /> From the dropdown, select your business name. <img alt="" /> In the left-hand menu, click **Ad Accounts**. <img alt="" /> </Step> <Step title="Copy the Advertiser ID"> Select the ad account you want to connect to Upstack Data. The **Advertiser ID** is displayed next to the ad account name as a 12-digit numeric value (for example, `549000000000`). Copy the **Advertiser ID** — you'll paste it into the Pinterest destination form in your Upstack dashboard. <img alt="" /> </Step> <Step title="Verify the Advertiser ID"> Confirm the value you copied is a 12-digit number with no extra characters or spaces. You can paste it into the **Advertiser ID** field when [configuring the Pinterest destination](/guides/pinterest-ads/how-to-configure-pinterest-destination-in-upstack-data) in your Upstack dashboard. </Step> </Steps> <Note> ***Need help finding these?*** **[How to Find Pinterest Pixel Tag ID →](/guides/pinterest-ads/how-to-find-pinterest-pixel-tag-id)** **[How to Generate Pinterest Conversion API Key →](/guides/pinterest-ads/how-to-generate-pinterest-conversion-api-key-access-token)** </Note> # How to Find Pinterest Pixel (Tag) ID Source: https://docs.upstackdata.com/guides/pinterest-ads/how-to-find-pinterest-pixel-tag-id Find your Pinterest Pixel (Tag) ID in Pinterest Ads Manager — required to configure the Upstack Data Pinterest destination for server-side conversion forwarding. <Tip> **Quick Summary** * Sign in to [Pinterest Business](https://business.pinterest.com) * Open **Manage business → Conversions**, then under **Pinterest tag** click **Tag manager** * **Locate and copy** your Pinterest Pixel Tag ID (a 13-digit number) </Tip> ## What is a Pinterest Pixel Tag ID? <Note> A **Pinterest Pixel Tag ID** is a unique identifier assigned to your Pinterest Pixel, which tracks user actions (like page views, add-to-cart, or purchases) on your website. It's what you use to connect your site activity with Pinterest Ads for measurement and optimization. The ID is a 13-digit number (for example, `2613000000000`). </Note> ## Prerequisites Before you start, you need: * Admin access to your Pinterest Business account * An existing Pinterest tag (if you don't have one yet, follow [How to Create a New Pinterest Pixel Tag ID](/guides/pinterest-ads/how-to-create-a-new-pinterest-pixel-tag-id) first) ## Steps to Find Your Pixel Tag ID <Steps> <Step title="Sign in to Pinterest Business"> Sign in to [Pinterest Business](https://business.pinterest.com). </Step> <Step title="Open Tag manager"> In the top-left of the page, click the **Menu icon** (three horizontal lines). Under **Manage business**, select **Conversions**. <img alt="" /> Under **Pinterest tag**, click **Tag manager**. <img alt="" /> </Step> <Step title="Copy your Pixel Tag ID"> If you already have a tag, you'll see it listed under **Pinterest Tag** with a 13-digit ID (for example, `2613000000000`). **Copy** the Pinterest tag — this is your **Pinterest Pixel Tag ID** for the Upstack Data integration. <img alt="" /> <Note> **No tag yet?** If you don't see a Pinterest tag listed, you need to create one first. [How to Create a New Pinterest Pixel Tag ID →](/guides/pinterest-ads/how-to-create-a-new-pinterest-pixel-tag-id) </Note> </Step> <Step title="Verify the Pixel Tag ID"> Confirm the value you copied is a 13-digit number with no extra characters or spaces. You can paste it into the **Pixel Tag ID** field when [configuring the Pinterest destination](/guides/pinterest-ads/how-to-configure-pinterest-destination-in-upstack-data) in your Upstack dashboard. </Step> </Steps> <Note> ***Need help finding these?*** **[How to Generate Pinterest Conversion API Key →](/guides/pinterest-ads/how-to-generate-pinterest-conversion-api-key-access-token)** **[How to Find Pinterest Advertiser ID →](/guides/pinterest-ads/how-to-find-pinterest-advertiser-id)** </Note> # How to Generate Pinterest Conversion API Key (Access Token) Source: https://docs.upstackdata.com/guides/pinterest-ads/how-to-generate-pinterest-conversion-api-key-access-token Generate a Pinterest Conversions API access token in Pinterest Ads Manager — required to authenticate the Upstack Data Pinterest destination and forward server-side conversions. <Tip> **Quick Summary** * Sign in to [Pinterest Business](https://business.pinterest.com) * Open **Manage business → Conversions** * Under **Conversion API**, click **Set up API** * Click **Generate new token** and copy the token (it starts with `pina_`) * Store the token securely — you will paste it into the Pinterest destination form in your Upstack dashboard </Tip> ## What is a Pinterest Conversion API key (access token)? <Note> A **Pinterest Conversion API key** (access token) is a secure credential that lets your server send conversion events, like purchases or sign-ups, directly to Pinterest. It improves tracking accuracy, attribution, and data security compared to the standard Pixel. The token starts with `pina_` and is roughly 90+ characters long (for example, `pina_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA`). </Note> ## Prerequisites Before you start, you need: * Admin access to your Pinterest Business account * At least one Pinterest ad account associated with your business * A secure place to store the generated token (Pinterest only displays it once) ## Steps to Generate the Conversion API Key <Steps> <Step title="Sign in to Pinterest Business"> Sign in to [Pinterest Business](https://business.pinterest.com). </Step> <Step title="Open the Conversions API setup"> In the top-left of the page, click the **Menu icon** (three horizontal lines). Under **Manage business**, select **Conversions**. <img alt="" /> Under **Conversion API**, click **Set up API**. <img alt="" /> </Step> <Step title="Generate the conversion access token"> Scroll to the **Generate conversion access token** section, then click **Generate new token**. <img alt="" /> </Step> <Step title="Copy and save your Conversion API key"> The generated token is your **Pinterest Conversion API key**. It starts with `pina_`. **Copy** the generated token and **store** it securely. You will paste this token into the Pinterest destination form in your Upstack dashboard. <Warning> Pinterest does not store personal tokens — copy it now and save it to a secure location such as a password manager. The same token can be reused across multiple ad accounts under your user ID. </Warning> <img alt="" /> `The generated token starts with pina_` <img alt="" /> </Step> <Step title="Verify the token format"> Confirm the value you copied starts with `pina_` and contains no extra spaces. You can paste it into the **Conversion API key** field when [configuring the Pinterest destination](/guides/pinterest-ads/how-to-configure-pinterest-destination-in-upstack-data) in your Upstack dashboard. </Step> </Steps> <Note> ***Need help finding these?*** **[How to Find Pinterest Pixel Tag ID →](/guides/pinterest-ads/how-to-find-pinterest-pixel-tag-id)** **[How to Find Pinterest Advertiser ID →](/guides/pinterest-ads/how-to-find-pinterest-advertiser-id)** </Note> # Complete How-To Guide for Onboarding Reddit Ads in Upstack Data Source: https://docs.upstackdata.com/guides/reddit-ads/complete-how-to-guide-for-onboarding-reddit-in-upstack-data Onboard Reddit Ads in Upstack Data — locate your Pixel ID, generate the Conversions API token, configure the destination, and remove duplicate Reddit pixels in Shopify. <Info> **New to Upstack?** Follow the [getting started guide](/get-started/install-on-shopify) for a streamlined onboarding walkthrough. </Info> <Tip> * Configure the **Reddit destination** in Upstack Data with your **Pixel ID** and **Conversions API access token**. * Remove duplicate **Reddit pixel installations** in Shopify to prevent inflated metrics. * Verify events appear in **Reddit Ads Manager → Events Manager** with a **Server** badge. * Monitor **Event Match Quality (EMQ)** improvements over 7-10 days. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to a **Reddit Ads** account * A configured **Reddit Pixel** in [Reddit Ads Manager Events Manager](https://ads.reddit.com/) * A **Conversions API access token** generated from that pixel — see [How to generate your Reddit CAPI token](/guides/reddit-ads/how-to-generate-reddit-conversion-api-token) * Shopify owner/staff access (for the duplicate-pixel cleanup step, if applicable) <Steps> <Step title="Configure the Reddit destination in Upstack Data"> In the Upstack dashboard, navigate to **Event Destinations** and add a **Reddit** destination using your **Pixel ID** (typically prefixed with `t2_`) and **Conversions API access token**. Help guide: [How to configure the Reddit destination in Upstack Data →](/guides/reddit-ads/how-to-configure-reddit-destination-in-upstack-data) </Step> <Step title="Remove duplicate Reddit pixel installations"> <Warning> Reddit does not have a native Shopify sales channel like Meta or TikTok, but many brands install the Reddit pixel manually via theme.liquid, Customer Events, or third-party apps. Multiple active pixels with the same Pixel ID cause inflated metrics that Reddit cannot deduplicate without a shared `conversion_id`. </Warning> Help guide: [How to remove duplicate Reddit pixel installations in Shopify →](/guides/reddit-ads/how-to-disable-existing-reddit-pixel-in-shopify) **Common installation locations to check:** * Shopify **Settings → Customer Events** for any custom Reddit pixel scripts * Theme files (`theme.liquid`, header snippets) for hardcoded `rdt('init')` calls * Third-party Reddit pixel apps in Shopify * Reddit pixel tags inside Google Tag Manager </Step> <Step title="Verify the full setup is healthy"> Confirm each piece of the setup is working: * In the Upstack dashboard, **Event Destinations** shows your Reddit destination as **Healthy** (green). * In [Reddit Ads Manager Events Manager](https://ads.reddit.com/), the pixel shows recent events with a **Server** badge for CAPI events. * The **Event Match Quality (EMQ)** column in Reddit's Events Manager shows a score for each event type — these will improve over the next 7-10 days. If anything is unhealthy, check the corresponding help guide above for troubleshooting steps. </Step> </Steps> ## What to expect after setup ### Event Match Quality timeline * **Event Match Quality (EMQ)** scores start to improve in 2-3 days and normalize over 7-10 days. * You can typically expect a 20-40% increase in tracked conversions vs. the browser pixel alone, since CAPI captures conversions lost to ad blockers and iOS restrictions. * The **Purchase** EMQ score sees the biggest improvement because checkout-time events carry the strongest match keys (hashed email, phone, address). ### Reporting differences * Your **Reddit Ads Manager ROAS** will likely **increase** after a few days as Reddit attributes more conversions to ads. Many brands discover their Reddit campaigns were performing 20-40% better than the browser-pixel data suggested. * Conversion volume may temporarily fluctuate during the first 48 hours as Reddit's deduplication logic adjusts to receiving both pixel and CAPI events. <Note> **Need help?** If you encounter any issues during setup or don't see expected EMQ improvements after 10 days, contact our [support team](/support) with your **Reddit Pixel ID** and we'll help diagnose the problem. </Note> # How to Configure Reddit Destination in Upstack Data Source: https://docs.upstackdata.com/guides/reddit-ads/how-to-configure-reddit-destination-in-upstack-data Configure the Reddit Ads destination in Upstack Data with your Pixel ID and Conversions API access token to enable dual tracking via browser pixel and server-side CAPI. <Tip> * In the Upstack dashboard, go to **Event Destinations** and click **+ New Destination**. * Select **Reddit Ads**. * Enter your **Reddit Pixel ID** (typically prefixed with `t2_`). * Paste your **Conversions API access token**. * Click **Create Configuration** and verify the destination shows **Healthy**. </Tip> <Note> **What this setup enables** Setting up the Reddit destination in Upstack Data enables dual tracking via browser pixel and server-side Conversions API (CAPI), recovering the 30-50% of conversions lost to ad blockers, iOS restrictions, and cross-device journeys. </Note> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to a **Reddit Ads** account * A configured **Reddit Pixel** in [Reddit Ads Manager Events Manager](https://ads.reddit.com/) — see [How to find your Reddit Pixel ID](/guides/reddit-ads/how-to-find-reddit-pixel-id) * A **Conversions API access token** — see [How to generate your Reddit CAPI token](/guides/reddit-ads/how-to-generate-reddit-conversion-api-token) ## Configuration steps <Steps> <Step title="Sign in to Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com/pixel/event-destinations). </Step> <Step title="Open the destination configuration"> In the Upstack dashboard, navigate to **Event Destinations**. Click **+ New Destination** in the top-right of the page. In the **Select a Destination** popup, click **Reddit Ads**, then click **Next**. </Step> <Step title="Enter your Pixel ID and CAPI token"> Fill in the form: 1. **Reddit Pixel ID** — the identifier for your Reddit pixel. Reddit Pixel IDs are typically prefixed with `t2_` (e.g., `t2_abc123def`). 2. **Conversions API access token** — a secure key generated from Reddit Ads Manager Events Manager. <Warning> The Conversions API token is a non-expiring secure key. Store it securely and never expose it client-side. If the token is compromised, generate a new one and follow the [update CAPI token guide](/guides/reddit-ads/how-to-update-reddit-conversion-api-token). </Warning> <Note> **Need help finding these?** * [How to find your Reddit Pixel ID](/guides/reddit-ads/how-to-find-reddit-pixel-id) * [How to generate your Reddit CAPI token](/guides/reddit-ads/how-to-generate-reddit-conversion-api-token) </Note> </Step> <Step title="Create the configuration"> Click the **Create Configuration** button. You should see a confirmation message and the Reddit destination will appear in your **Event Destinations** list. </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, the Reddit destination card should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**: * Confirm your **Pixel ID** is correct (typically prefixed with `t2_`, no leading/trailing spaces). * Confirm your **Conversions API token** was pasted in full (no truncation, no whitespace). * Confirm the token was generated for the same ad account as the Pixel ID. * See [How to update your Reddit CAPI token](/guides/reddit-ads/how-to-update-reddit-conversion-api-token) if your token may have been rotated. </Step> </Steps> # How to Remove Duplicate Reddit Pixel Installations in Shopify Source: https://docs.upstackdata.com/guides/reddit-ads/how-to-disable-existing-reddit-pixel-in-shopify Remove duplicate Reddit pixel installations from Shopify Customer Events, theme.liquid, and third-party apps to prevent inflated conversion metrics when activating Upstack Data. <Tip> * Reddit does **not** have a native Shopify sales channel like Meta or TikTok — Reddit pixels on Shopify are typically installed manually. * If multiple Reddit pixels with the same ID are firing, conversions get counted more than once. * Consolidate to a **single** browser pixel installation, then let Upstack handle server-side delivery via CAPI. * Reddit deduplicates the browser pixel and CAPI events automatically using the shared `conversion_id`. </Tip> <Note> **Why this matters** Unlike Meta or TikTok, Shopify does not have a native Reddit sales channel pixel. Brands typically install the Reddit pixel via Shopify Customer Events, theme.liquid edits, third-party apps, or Google Tag Manager. When **multiple** Reddit pixels with the same Pixel ID are firing on the same page, Reddit cannot deduplicate them without a shared `conversion_id`, which results in inflated conversion counts and degraded campaign optimization. Once you activate Upstack's Reddit destination, the Upstack Pixel handles browser-side capture and forwards a deduplicated server-side event to Reddit CAPI. Any **additional** Reddit pixel installations on the same store should be removed. </Note> ## Prerequisites Before you start, you need: * Shopify owner or staff access with **Customize Theme** and **Customer Events** permissions * A list of all your existing Reddit pixel installations (theme code, apps, GTM tags) * Your Reddit Pixel ID — see [How to find your Reddit Pixel ID](/guides/reddit-ads/how-to-find-reddit-pixel-id) ## Common locations to check Reddit pixels can be installed in any of these places. Check each one: | Location | How to access | | -------------------------- | ---------------------------------------------------------------------------------- | | Shopify Customer Events | **Settings → Customer Events** in Shopify admin | | Theme files | **Online Store → Themes → Edit Code** — look in `theme.liquid` and header snippets | | Third-party apps | **Apps** in Shopify admin — search for "Reddit" | | Google Tag Manager | GTM workspace → **Tags** — filter by "Reddit" | | Checkout extension scripts | Plus stores: **Settings → Checkout → Order status page additional scripts** | ## Steps to remove duplicate Reddit pixels <Steps> <Step title="Inventory all current Reddit pixel installations"> Before removing anything, document every place a Reddit pixel is firing: 1. **Customer Events**: Go to Shopify admin → **Settings → Customer Events** and check for any custom pixels referencing `rdt(` or `reddit`. 2. **Theme code**: Open **Online Store → Themes → Edit Code** and search the entire theme for `rdt(` or `redditstatic`. 3. **Apps**: Look for any Reddit-branded apps under **Apps** in the Shopify admin. 4. **GTM**: If you use Google Tag Manager, search for tags with names containing "Reddit" or scripts referencing the Reddit pixel. Make a list of every location and the Pixel ID each one references. </Step> <Step title="Identify the canonical Reddit pixel"> Decide which **single** Reddit pixel installation will remain. Recommended order of preference: 1. **Shopify Customer Events** — most reliable, fires on checkout pages, easiest to maintain. 2. **Theme.liquid** — works for older themes that don't support Customer Events. 3. **Third-party app** — only if the app provides functionality you need beyond pixel firing. All other installations will be removed in the next steps. </Step> <Step title="Remove duplicate Customer Event pixels"> In Shopify admin, go to **Settings → Customer Events**. For each Reddit-related custom pixel that is **not** your canonical installation: 1. Click the pixel to open its details. 2. Click **Disconnect** or **Delete** in the top-right. 3. Confirm the action. <Warning> Disconnecting a custom pixel stops it from firing immediately. There is no undo, so confirm you have a backup of the script if you may need it later. </Warning> </Step> <Step title="Remove Reddit pixel code from theme files"> Open **Online Store → Themes → Edit Code** and search the theme for `rdt(` and `redditstatic`. For any matches that are **not** your canonical installation: 1. Open the file containing the code. 2. Delete the Reddit pixel script block (typically wrapped in `<script>` tags). 3. Save the file. Common files to check: `theme.liquid`, `layout/theme.liquid`, `snippets/header.liquid`, `snippets/google-analytics.liquid`. </Step> <Step title="Uninstall duplicate Reddit pixel apps"> Go to **Apps** in the Shopify admin and locate any Reddit pixel apps that are not your canonical installation. Click **Delete** to uninstall the app. Confirm by reviewing app data deletion in the popup. </Step> <Step title="Remove duplicate GTM Reddit tags"> If you use Google Tag Manager, sign in to your workspace and navigate to **Tags**. Filter for "Reddit" or search for tags referencing `redditstatic.com` or `rdt(`. For each tag that duplicates your canonical pixel: 1. Click the tag to open it. 2. Click the trash icon (top-right) to delete it. 3. **Submit** and **Publish** a new GTM workspace version to deploy the change. </Step> <Step title="Verify only one Reddit pixel is firing"> Open your storefront in a new browser tab with the [Reddit Pixel Helper Chrome extension](https://chromewebstore.google.com/) installed (search "Reddit Pixel Helper" in the Chrome Web Store). Navigate through your store: home page, product page, add-to-cart, and checkout. The Pixel Helper should show **exactly one** pixel firing per event. If you see duplicates, return to the previous steps and remove the additional installation. </Step> <Step title="Activate Upstack's Reddit destination"> Once duplicates are removed, your single browser pixel and Upstack's CAPI integration will work together cleanly. Reddit will deduplicate using the shared `conversion_id`. Confirm the Upstack Reddit destination is **Healthy** in your dashboard. See [How to configure the Reddit destination](/guides/reddit-ads/how-to-configure-reddit-destination-in-upstack-data) if it isn't already set up. </Step> </Steps> <Note> **What if I want Upstack to be the only Reddit data source?** You can also remove **all** browser-side Reddit pixel installations and let Upstack handle 100% of Reddit tracking server-side. This works, but you'll lose real-time pixel signal in Reddit's Events Manager. The recommended setup is to keep one browser pixel and let Upstack add the CAPI layer on top. </Note> # How to Find your Reddit Pixel ID Source: https://docs.upstackdata.com/guides/reddit-ads/how-to-find-reddit-pixel-id Find your Reddit Pixel ID in Reddit Ads Manager Events Manager — required to configure the Upstack Data Reddit destination for server-side conversion forwarding. <Tip> * Sign in to [Reddit Ads Manager](https://ads.reddit.com/) and open the **Events Manager**. * Below **Events Overview**, locate the **Pixel ID** (typically prefixed with `t2_`). * Copy the Pixel ID and paste it into your Upstack Reddit destination configuration. </Tip> <Note> **What is a Reddit Pixel ID?** Your **Reddit Pixel ID** is a unique identifier Upstack Data uses to send conversion data to your Reddit Ads account. Reddit Pixel IDs are typically prefixed with `t2_` (e.g., `t2_abc123def`) and are sometimes referred to as your Account ID inside Reddit's developer documentation. </Note> ## Prerequisites Before you start, you need: * Access to a **Reddit Ads** account at [ads.reddit.com](https://ads.reddit.com/) or [business.reddit.com](https://business.reddit.com/) * A pixel already created in Reddit Ads Manager Events Manager (or follow the create-pixel steps below) ## Steps to find your Reddit Pixel ID <Steps> <Step title="Sign in to Reddit Ads Manager"> Sign in to Reddit Ads Manager at [ads.reddit.com](https://ads.reddit.com/) or [business.reddit.com](https://business.reddit.com/). </Step> <Step title="Open Events Manager"> Click the menu (top-left corner) and select **Ads** → **Events Manager**. Alternatively, click **Events Manager** directly in the left-hand navigation menu. </Step> <Step title="Find or create your pixel"> **If you already have a pixel**, you'll see it under **Events Overview** — proceed to the next step. **If you need to create one:** * Click **Create New Pixel** or **Set Up Pixel** * Follow Reddit's setup wizard to create a new Reddit Pixel * Once created, return to the Events Manager </Step> <Step title="Locate your Pixel ID"> Below **Events Overview** (or under your pixel's settings), locate the **Pixel ID**. **Example format:** `t2_abc123def` The Pixel ID is the same value as your Reddit Account ID and starts with the prefix `t2_`. </Step> <Step title="Copy and paste into Upstack Data"> Copy your Pixel ID and paste it into the **Pixel ID** field in your Upstack Reddit destination setup. <Tip> Ensure there are no extra spaces before or after the ID. The value should include the `t2_` prefix. </Tip> </Step> <Step title="Save the configuration"> Click **Create Configuration** to save the destination. </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, navigate to **Event Destinations**. Your Reddit destination should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**, double-check that the Pixel ID matches exactly what you see in Reddit Ads Manager (correct prefix, no whitespace). </Step> </Steps> <Note> **Next step:** [How to generate your Reddit CAPI token](/guides/reddit-ads/how-to-generate-reddit-conversion-api-token) </Note> # How to Generate your Reddit Conversions API Token Source: https://docs.upstackdata.com/guides/reddit-ads/how-to-generate-reddit-conversion-api-token Generate a Reddit Conversions API access token in Reddit Ads Manager — required to authenticate the Upstack Data Reddit destination and forward server-side conversions via Reddit CAPI. <Tip> * Sign in to [Reddit Ads Manager](https://ads.reddit.com/) and open **Events Manager**. * Click the **Conversions API** tab in the left-hand menu. * Click **+ Generate Access Token**. * Name the token (e.g., "Upstack Data") and click **Generate**. * Copy the token immediately and paste it into your Upstack Reddit destination. </Tip> <Note> **What is a Reddit Conversions API token?** A **Conversions API access token** is a non-expiring secure key that allows Upstack Data to send conversion event data to Reddit's Conversions API. The token can be used by any administrator for any ad account within your business. Reddit recommends using this token over OAuth for Conversions API access. </Note> ## Prerequisites Before you start, you need: * **Admin access** to a **Reddit Ads** account * A pixel already created in [Reddit Ads Manager Events Manager](https://ads.reddit.com/) — see [How to find your Reddit Pixel ID](/guides/reddit-ads/how-to-find-reddit-pixel-id) * An Upstack Data account ready to receive the token ([sign in](https://app.upstackdata.com)) ## Steps to generate your Reddit CAPI token <Steps> <Step title="Sign in to Reddit Ads Manager"> Sign in to Reddit Ads Manager at [ads.reddit.com](https://ads.reddit.com/) or [business.reddit.com](https://business.reddit.com/). </Step> <Step title="Open Events Manager"> Click the menu (top-left corner) and select **Ads** → **Events Manager**. </Step> <Step title="Open the Conversions API settings"> In the left-hand menu of the Events Manager, click the **Conversions API** tab. This opens the Conversions API settings page where access tokens are managed. </Step> <Step title="Generate the access token"> In the **Conversions access token** section, click the **+ Generate Access Token** button. A pop-up window will appear prompting you to name the token. </Step> <Step title="Name your token"> Enter an easily identifiable name for the token (e.g., `Upstack Data` or `Upstack CAPI`). <Tip> A descriptive name makes it easier to identify which integration the token belongs to if you generate multiple tokens for different platforms or environments. </Tip> Click **Generate** to create the token. </Step> <Step title="Copy your CAPI token"> Reddit will display the access token — a string of letters and numbers. <Warning> Copy the token immediately to a secure location. Reddit may not show the full token again after you close the dialog. If lost, you'll need to generate a new one. </Warning> The token is a **non-expiring** secure key, so it does not need to be refreshed periodically. However, you should rotate it if you suspect it has been compromised. </Step> <Step title="Add the token to Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com/pixel/event-destinations) and open your **Reddit** destination under **Event Destinations**. Paste the token into the **Conversions API access token** field. <Warning> The Conversions API token is sensitive — store it securely. Treat it like a password and never expose it in client-side code or share it publicly. </Warning> </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, the Reddit destination card should show **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**: * Confirm the token was pasted in full (no truncation, no whitespace). * Confirm the token was generated for the same Reddit Ads account as the Pixel ID. * Confirm the **Pixel ID** matches the pixel you generated the token for. </Step> </Steps> <Note> **Need help with the Pixel ID?** See [How to find your Reddit Pixel ID](/guides/reddit-ads/how-to-find-reddit-pixel-id). </Note> # How to Update your Reddit Conversions API Token Source: https://docs.upstackdata.com/guides/reddit-ads/how-to-update-reddit-conversion-api-token Rotate or update your Reddit Conversions API access token in Upstack Data to keep server-side events flowing into Reddit CAPI without breaking pixel health. <Tip> * Generate a new Reddit CAPI token in [Reddit Ads Manager Events Manager](https://ads.reddit.com/) → **Conversions API**. * Sign in to Upstack Data and open your Reddit destination under **Event Destinations**. * Replace the existing token with the new value and save. * Verify the destination shows **Healthy** within 5 minutes. </Tip> <Note> **When to update the Reddit CAPI token** Reddit Conversions API tokens are **non-expiring**, so they don't need routine rotation. Update the token only when: * The token has been compromised or accidentally exposed * An administrator has revoked the token in Reddit Ads Manager * You're consolidating multiple tokens into a single managed credential * The Upstack Reddit destination shows **Unhealthy** with an authentication error </Note> ## Prerequisites Before you start, you need: * **Admin access** to a **Reddit Ads** account * An Upstack Data account with an existing Reddit destination ([sign in](https://app.upstackdata.com)) ## Steps to update your Reddit CAPI token <Steps> <Step title="Generate a new Reddit CAPI token"> Follow the [generate Reddit CAPI token guide](/guides/reddit-ads/how-to-generate-reddit-conversion-api-token) to create a new access token in Reddit Ads Manager. Use a descriptive name like `Upstack Data (rotated YYYY-MM-DD)` to track when the token was issued. <Warning> Copy the new token immediately — Reddit may not show the full token again after you close the generation dialog. </Warning> </Step> <Step title="Open the Reddit destination in Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com/pixel/event-destinations). Navigate to **Event Destinations** and click your existing **Reddit** destination to open its configuration. </Step> <Step title="Replace the access token"> In the **Conversions API access token** field, clear the existing token and paste the new one. Do not change the **Pixel ID** unless you are also moving to a new pixel — the token must be generated for the ad account that owns the Pixel ID. </Step> <Step title="Save the updated configuration"> Click **Save** or **Update Configuration**. Upstack will validate the new token by sending a test event to Reddit's Conversions API. </Step> <Step title="Verify the destination is healthy"> The Reddit destination card should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**: * Confirm the new token was pasted in full (no truncation, no whitespace). * Confirm the token was generated for the same Reddit Ads account as the Pixel ID. * In Reddit Ads Manager → Events Manager → Conversions API, confirm the token is still listed (not revoked). </Step> <Step title="Revoke the old token (optional)"> Once the new token is verified working, return to Reddit Ads Manager → Events Manager → **Conversions API** and revoke the old token. Revoking the old token prevents accidental future use and reduces the surface area for credential leaks. </Step> </Steps> <Note> **Still seeing issues?** Contact our [support team](/support) with your **Reddit Pixel ID** and we'll help diagnose the problem. </Note> # Complete How-To Guide for Setting Up the Upstack Data App in Shopify Source: https://docs.upstackdata.com/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify This is guide is a step-by-step instructions to installing and setting up the Upstack Data app in Shopify for accurate tracking & reporting. <Info> **New to Upstack?** If you haven't already, [create your Upstack account](/get-started/create-an-account) before continuing. </Info> <Tip> * Sign up for Upstack Data and choose your plan * Connect Shopify from the Upstack dashboard (Data Sources → Shopify) * Enable Theme App Extension * Add Upstack Data Custom Pixel * Set Consent and Privacy Settings for the Upstack Data Custom Pixel * Connect Shopify Customer Events Pixel * Finish setup * Verify events </Tip> ## Overview **Upstack Data** is a first-party data pixel (CAPI) solution that enhances your Facebook (Meta), TikTok Ads, Google Ads, and Klaviyo tracking capabilities, helping you bypass iOS 14+ restrictions and improve your advertising ROAS. ## Prerequisites * Active Upstack Data account ([sign up](https://app.upstackdata.com/signup)) — [see plans and pricing](/billing/plans-and-pricing) * Active Shopify store (`your-store.myshopify.com`) * [Shopify Admin](https://admin.shopify.com) access with permission to install apps and edit themes * Facebook Business Manager account and admin access (for Meta tracking) * Ad account credentials and access for every platform you want to track ## Configuration steps ### Part 1: Connect Shopify from the Upstack dashboard Sign in to [app.upstackdata.com](https://app.upstackdata.com), navigate to **Data Sources → Shopify**, and click **Connect Shopify**. Upstack redirects you to your Shopify Admin to authorize the install. Help guide to complete this step: [How to Install the Upstack Data App in Shopify →](/guides/shopify/how-to-download-and-install-upstack-data-app-in-shopify) ### Part 2: Enable Theme App Extension <Steps> <Step title="Open the theme settings prompt"> After signing in to the Upstack Data app, a modal window will prompt you to **enable** the UpStackified Theme App Extension. Click **Enable UpStackified Theme App Extension**. <img alt="Modal prompt to enable the UpStackified Theme App Extension" /> </Step> <Step title="Enable the Theme App Extension in Shopify Admin"> In Shopify Admin, ensure the **UpStackified Theme App Extension is ENABLED**. Help guide to complete this step: [How to Ensure Upstack Data Theme App Extension is Enabled →](/guides/shopify/how-to-ensure-upstack-data-theme-app-extension-is-enabled) </Step> <Step title="Proceed to onboarding"> Click **Continue** to proceed with the onboarding. </Step> </Steps> ### Part 3: Add Custom Pixel <Steps> <Step title="Open Customer Events in the Upstack Data app"> On the Upstack Data app onboarding page, click **Customer events** and click the **Copy Pixel Code** button to copy the code to your clipboard. <img alt="Copy Pixel Code button in the Upstack Data onboarding page" /> </Step> <Step title="Add a Custom Pixel in Shopify Admin"> In your [Shopify Admin](https://admin.shopify.com), navigate to **Settings → Customer events → Add custom pixel**. <img alt="Shopify Admin Customer events page with Add custom pixel option" /> </Step> <Step title="Name the Custom Pixel"> Set the pixel name to **UpstackData** → click **Add pixel**. <img alt="Naming the custom pixel UpstackData in Shopify Admin" title="Name the custom pixel" /> </Step> </Steps> ### Part 4: Connect Shopify Customer Events Pixel <Steps> <Step title="Set consent and privacy settings"> <Warning> **Upstack Data does not sell any data.** We are a privacy-first solution and committed to adhering to the regulations for each jurisdiction. </Warning> Help guide to complete this step: [Shopify Custom Pixel - Privacy Consent Settings →](/guides/shopify/shopify-custom-pixel-privacy-consent-settings) </Step> <Step title="Paste the Pixel Code"> Paste the **Pixel Code →** click **Save →** click **Connect**. <img alt="Paste pixel code, save, and connect in Shopify Customer events" /> </Step> <Step title="Connect the Custom Pixel"> In the modal popup, click **Connect**. <img alt="Connect button in the Shopify custom pixel confirmation modal" /> </Step> </Steps> ### Part 5: Finish setup In the **Upstack Data app**, click **Continue** → then click **Finish Setup**. <img alt="Finish Setup button in the Upstack Data app onboarding" /> ### Part 6: Verify the installation Confirm everything is wired up correctly before you start running ads: * Place a test order on your store (or wait for a real one). * In the [Upstack dashboard](https://app.upstackdata.com), open **Event Health** and confirm `PageView`, `AddToCart`, `InitiateCheckout`, and `Purchase` events are arriving. * In [Shopify Admin → Settings → Customer events](https://admin.shopify.com), confirm the **UpstackData** Custom Pixel shows status **Connected**. * In [Shopify Admin → Online Store → Themes → Customize → App embeds](https://admin.shopify.com), confirm **UpStackified Pixel** is enabled. <Note> **Need help?** If you encounter any issues during setup, contact our support team and we'll help diagnose the problem. </Note> ## What's next <CardGroup> <Card title="Connect a destination" icon="plug" href="/get-started/connect-a-destination"> Forward events to Meta CAPI, TikTok, Klaviyo, or other ad platforms. </Card> <Card title="Explore the CLI" icon="terminal" href="/cli/install"> Query your data and manage dashboards from the command line or through AI agents. </Card> <Card title="View plans and pricing" icon="credit-card" href="/billing/plans-and-pricing"> See available plans and adjust your subscription as your store scales. </Card> <Card title="Troubleshoot issues" icon="wrench" href="/troubleshooting/pixel-stuck-on-waiting-for-first-events"> Common fixes if events aren't appearing after setup. </Card> </CardGroup> # How to Download and Install Upstack Data App in Shopify Source: https://docs.upstackdata.com/guides/shopify/how-to-download-and-install-upstack-data-app-in-shopify Connect your Shopify store to Upstack from the Upstack dashboard — install the Upstack app and authorize the connection in a few clicks. <Tip> * Sign in to your Upstack Data account * Navigate to **Data Sources → Shopify** * Click **Connect Shopify** * Authorize the app install in Shopify * Return to the Upstack dashboard with Shopify connected </Tip> ## Prerequisites * Active Upstack Data account ([sign up](https://app.upstackdata.com/signup)) * Active Shopify store (`your-store.myshopify.com`) * [Shopify Admin](https://admin.shopify.com) access with permission to install apps ## Configuration steps <Steps> <Step title="Sign in to Upstack Data"> Open [app.upstackdata.com](https://app.upstackdata.com) and sign in with your Upstack account credentials. If you don't have an account yet, [create one first](/get-started/create-an-account). </Step> <Step title="Open the Shopify data source"> In the Upstack dashboard, navigate to **Data Sources → Shopify**. </Step> <Step title="Connect your Shopify store"> Click **Connect Shopify**. Enter your Shopify store URL (`your-store.myshopify.com`) when prompted. Upstack redirects you to your Shopify Admin to authorize the app installation. </Step> <Step title="Approve the app installation in Shopify"> Review the permissions Upstack requests, then click **Install** in your Shopify Admin. Upstack requests read access to your orders, customers, and product catalog for event enrichment. No write permissions are requested. </Step> <Step title="Return to the Upstack dashboard"> After approving the install in Shopify, you're automatically redirected back to the Upstack dashboard. Shopify now appears as a connected data source. </Step> </Steps> ## Verify the install * In the [Upstack dashboard](https://app.upstackdata.com), confirm Shopify is listed under **Data Sources** with a **Connected** status. * In your [Shopify Admin](https://admin.shopify.com), navigate to **Settings → Apps and sales channels** and confirm **Upstack: Site Intelligence** appears in your list of installed apps. ## Next steps <CardGroup> <Card title="Enable the Theme App Extension" icon="toggle-on" href="/guides/shopify/how-to-ensure-upstack-data-theme-app-extension-is-enabled"> Activate the UpStackified theme app extension in your Shopify theme editor. </Card> <Card title="Add the Custom Pixel" icon="code" href="/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify"> Paste the Upstack pixel code into Shopify's Customer Events. </Card> <Card title="Configure privacy settings" icon="shield-halved" href="/guides/shopify/how-to-setup-upstack-custom-pixel-privacy-settings"> Set consent and privacy settings for the Upstack custom pixel. </Card> </CardGroup> <Note> ***Need help on these?*** \*\*[How to Ensure Upstack Data Theme App Extension is Enabled →](/guides/shopify/how-to-ensure-upstack-data-theme-app-extension-is-enabled) [How to Setup Upstack Custom Pixel Privacy Settings →](/guides/shopify/how-to-setup-upstack-custom-pixel-privacy-settings) [Complete How-To Guide on Setting up Upstack Data App in Shopify →](/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify)\*\* </Note> # How to Ensure Upstack Data Theme App Extension is Enabled Source: https://docs.upstackdata.com/guides/shopify/how-to-ensure-upstack-data-theme-app-extension-is-enabled Enable the Upstack Data theme app embed in your Shopify theme editor so the tracking pixel loads on every storefront page and captures events server-side. <Tip> * In Shopify Admin, navigate to **Online Store → Themes → Customize** * Click the **App embeds** icon in the theme customizer * Enable **UpStackified Pixel** and click **Save** * **Verify** with a test purchase </Tip> <Note> For your tracking events to fire correctly in Shopify, you need to ensure the **UpStackified Pixel** Theme App Extension is enabled in your live theme. Once complete, we recommend a test purchase to verify conversion tracking is working properly. </Note> ## Prerequisites * The Upstack Data app installed on your Shopify store (see [How to Download and Install Upstack Data App in Shopify](/guides/shopify/how-to-download-and-install-upstack-data-app-in-shopify)) * [Shopify Admin](https://admin.shopify.com) access with permission to edit themes * Your live theme accessible from **Online Store → Themes** ## Steps to enable Upstack Data Theme App Extension <Steps> <Step title="Sign in to Shopify Admin"> Sign in to your [Shopify Admin](https://admin.shopify.com). <img alt="Shopify Admin login page" /> </Step> <Step title="Open Themes"> In the left sidebar, navigate to **Online Store → Themes**. <img alt="Shopify Admin sidebar with Online Store and Themes selected" /> </Step> <Step title="Open the theme customizer"> On your live theme, click the **Customize** button. <img alt="Shopify Themes page with Customize button on live theme" /> </Step> <Step title="Open App embeds"> In the left sidebar of the theme customizer, click the **App embeds** icon. <img alt="Theme customizer sidebar with App embeds icon highlighted" /> </Step> <Step title="Enable UpStackified Pixel"> In the list, locate **UpStackified Pixel** and toggle the switch to **enable** it. Click **Save** at the top-right of the page to apply the changes. <img alt="UpStackified Pixel toggle in App embeds list" /> <img alt="Save button in theme customizer after enabling UpStackified Pixel" /> </Step> <Step title="Verify activation"> Once enabled, **UpStackified Pixel** will show as active with a green check mark or **Enabled** status. <img alt="UpStackified Pixel showing enabled status with green check mark" /> </Step> <Step title="Verify with a test purchase"> Place a test order on your store, then open the [Upstack dashboard](https://app.upstackdata.com) and confirm a `Purchase` event appears under **Event Health** within a few minutes. If the event does not appear, recheck that the App embed is enabled and saved on your **live** theme (not a draft). </Step> </Steps> ## Related Articles <CardGroup> <Card title="Install the Pixel Helper" href="/guides/shopify/how-to-install-upstack-data-pixel-helper" /> <Card title="Set up custom pixel privacy settings" href="/guides/shopify/how-to-setup-upstack-custom-pixel-privacy-settings" /> <Card title="Pixel stuck on waiting for first events" href="/troubleshooting/pixel-stuck-on-waiting-for-first-events" /> <Card title="Complete Shopify setup guide" href="/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify" /> </CardGroup> # How to Setup Upstack Custom Pixel Privacy Settings Source: https://docs.upstackdata.com/guides/shopify/how-to-setup-upstack-custom-pixel-privacy-settings Configure consent mode and privacy settings on the Upstack Data custom pixel in Shopify — control which events fire for opted-out shoppers while preserving attribution for opted-in shoppers. <Tip> * In Shopify Admin, navigate to **Settings → Customer events** and select your Upstack Data Custom Pixel. * For **Permission**, choose **Not required** — the pixel will always run. * For **Data sale**, choose **Data collected does not qualify as data sale** — the pixel will collect data even when a customer opts out of their data being sold. * Click **Save**. </Tip> ## Prerequisites * The Upstack Data app installed on your Shopify store * The **UpstackData** Custom Pixel already added under **Shopify Admin → Settings → Customer events** (see [Complete How-To Guide for Setting Up the Upstack Data App in Shopify](/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify)) * [Shopify Admin](https://admin.shopify.com) access with permission to manage Customer Events ## Key points to remember When configuring the Upstack Data Custom Pixel in Shopify, several options control consent mode. These settings can have a material impact on your tracking, data quality, and attribution. If you are running cookie consent banners, ensure they are properly configured to get the most accurate data. If **Permission: Required** is set, the Custom Pixel will not load or track user behavior until the consent banner is accepted. <Note> **Privacy regulations vary by jurisdiction.** This does not constitute legal advice. We recommend you consult your legal representative to determine which settings are appropriate for your business. </Note> ## Configuration steps <Steps> <Step title="Sign in to Shopify Admin"> Sign in to your [Shopify Admin](https://admin.shopify.com). </Step> <Step title="Open Customer events"> * In the bottom-left of the page, click **Settings**. * In the settings menu, click **Customer events**. <img alt="Shopify Admin sidebar showing Settings option" /> <img alt="Shopify Settings menu with Customer events option" /> </Step> <Step title="Select the UpstackData Custom Pixel"> From your list of pixels, click the **UpstackData** Custom Pixel. <img alt="Customer events list showing UpstackData custom pixel" /> </Step> <Step title="Configure privacy settings"> For maximum attribution and data quality, set the following: * **Permission:** *Not required* * **Data sale:** *Data collected does not qualify as data sale* Click **Save** to update the Upstack Data Custom Pixel privacy settings. <img alt="Privacy settings with Permission and Data sale options configured" /> <Warning> **Upstack Data does not sell any data.** We are a privacy-first solution and committed to adhering to the regulations for each jurisdiction. </Warning> </Step> <Step title="Verify the settings are saved"> * Refresh the Custom Pixel page in [Shopify Admin](https://admin.shopify.com) and confirm the **Permission** and **Data sale** values match what you selected. * In the [Upstack dashboard](https://app.upstackdata.com), open **Event Health** and confirm events continue to arrive after the change. </Step> </Steps> ## Related Articles <CardGroup> <Card title="Custom pixel privacy consent settings" href="/guides/shopify/shopify-custom-pixel-privacy-consent-settings" /> <Card title="Enable theme app extension" href="/guides/shopify/how-to-ensure-upstack-data-theme-app-extension-is-enabled" /> <Card title="Complete Shopify setup guide" href="/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify" /> <Card title="Events not in dashboard" href="/troubleshooting/events-not-in-dashboard" /> </CardGroup> # Complete How-To Guide for Onboarding Snapchat in Upstack Data Source: https://docs.upstackdata.com/guides/snapchat-ads/complete-how-to-guide-for-onboarding-snapchat-in-upstack-data Onboard Snapchat Ads in Upstack Data — locate your Snapchat Pixel ID, generate the Conversion API access token, configure the destination, and disable Shopify's duplicate Snapchat pixel. <Tip> **Quick Summary** * Locate and copy your **Snapchat Pixel ID** * Generate and copy your **Snapchat Conversion API Token** * Create and **configure the Snapchat destination** in your Upstack dashboard * **Disable Snapchat data sharing** in Shopify </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to your Snapchat Ads account ([Snapchat Ads Manager](https://ads.snapchat.com)) * A Shopify store admin account (only required for the data-sharing step) ## Onboarding Steps <Steps> <Step title="Find and copy your Snapchat Pixel ID"> <Note> A **Snapchat Pixel ID** is a unique identifier for your Snapchat Pixel in the format of a 32-character UUID, for example `00000000-0000-0000-0000-000000000000`. </Note> Help guide to complete this step: [How to Get my Snapchat Pixel ID →](/guides/snapchat-ads/how-to-get-my-snapchat-pixel-id) </Step> <Step title="Generate and copy your Conversion API Token"> <Note> A **Snapchat Conversion API Token** is a long alphanumeric secret (typically 100+ characters) that authorizes Upstack Data to send server-side events on your behalf. </Note> <Warning> Store your token on secure backend servers and do not share it. You will need it when configuring the Snapchat destination in your Upstack dashboard. When generating new tokens, remove old ones as soon as you confirm they are no longer needed. </Warning> Help guide to complete this step: [How to Generate my Snapchat Conversion API Token →](/guides/snapchat-ads/how-to-generate-my-snapchat-conversion-api-token) </Step> <Step title="Create and configure the Snapchat destination in your Upstack dashboard"> Help guide to complete this step: [How to Configure Snapchat Pixel Destination in Upstack Data →](/guides/snapchat-ads/how-to-configure-snapchat-pixel-destination-in-upstack-data) </Step> <Step title="Disable Snapchat data sharing in Shopify"> <Warning> Disabling Snapchat data sharing is crucial to prevent duplicate events, which can distort reporting and attribution. It ensures Snapchat only receives clean, accurate data through Upstack Data for reliable insights and better ad optimization. </Warning> Help guide to complete this step: [How to Disable Snapchat Data Sharing in Shopify →](/guides/snapchat-ads/how-to-disable-snapchat-data-sharing-in-shopify) </Step> <Step title="Verify the Snapchat destination is healthy"> In your [Upstack dashboard](https://app.upstackdata.com/pixel/event-destinations), open **Events Destination** and confirm the **Snapchat** destination shows a **Healthy** status. Then, in [Snapchat Ads Manager](https://ads.snapchat.com), open **Events Manager** for your pixel and confirm events are arriving from your Conversions API integration. </Step> </Steps> <Note> **Need help?** If you encounter any issues during setup or don't see expected improvements after 10 days, contact our support team with your Snapchat Pixel ID and Conversion API Token, and we'll help diagnose the problem. </Note> # How to Configure Snapchat Pixel Destination in Upstack Data Source: https://docs.upstackdata.com/guides/snapchat-ads/how-to-configure-snapchat-pixel-destination-in-upstack-data Configure the Snapchat destination in Upstack Data with your Snapchat Pixel ID and Conversion API access token to forward server-side conversions to Snapchat CAPI. <Tip> **Quick Summary** * In the Upstack dashboard, open **Events Destination** and click **+ New Destination** * Select **Snapchat** from the destination options * Enter your **Snapchat Pixel ID** and **Conversion API Token** * Check the box to **enable Snapchat Conversions API** * Click **Create Configuration** and verify the destination shows as **Healthy** </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to your Snapchat Ads account ([Snapchat Ads Manager](https://ads.snapchat.com)) * Your Snapchat **Pixel ID** ([how to get it](/guides/snapchat-ads/how-to-get-my-snapchat-pixel-id)) * Your Snapchat **Conversion API Token** ([how to generate it](/guides/snapchat-ads/how-to-generate-my-snapchat-conversion-api-token)) ## Configuration Steps <Steps> <Step title="Sign in to your Upstack dashboard"> Sign in to [Upstack Data](https://app.upstackdata.com) and open the [Events Destination](https://app.upstackdata.com/pixel/event-destinations) page. </Step> <Step title="Add a new Snapchat destination"> In the **Events Destination** page, click **+ New Destination** in the top-right of the page. <img alt="Add New Destination" /> In the **Select a Destination** popup, click **Snapchat**, then click **Next**. <img alt="Select Snapchat from destination options in popup" /> </Step> <Step title="Enter your Snapchat credentials"> Fill out the form with the following: 1. **Snapchat Pixel ID** — a 32-character UUID, for example `00000000-0000-0000-0000-000000000000` 2. Check the box **Check to enable sending events via Snapchat Conversions API** 3. **Snapchat Conversion API Token** — the long alphanumeric token (typically 100+ characters) generated in Snapchat Business Manager <Warning> The **Conversions API checkbox must be selected** for server-side tracking to work. </Warning> <img alt="Snapchat destination form with Pixel ID and CAPI token fields" /> <Note> ***Need help finding these?*** **[How to Get my Snapchat Pixel ID →](/guides/snapchat-ads/how-to-get-my-snapchat-pixel-id)** **[How to Generate my Snapchat Conversion API Token →](/guides/snapchat-ads/how-to-generate-my-snapchat-conversion-api-token)** </Note> </Step> <Step title="Create the configuration"> Click the **Create Configuration** button at the bottom of the form. <img alt="Create Configuration button to save Snapchat destination" /> <Note> **Success! 🎉** You should see a confirmation message and the Snapchat destination will appear as **Healthy** in your destinations list. </Note> </Step> <Step title="Verify the destination is sending events"> Back in the [Events Destination](https://app.upstackdata.com/pixel/event-destinations) page, confirm the new **Snapchat** destination shows a **Healthy** status. Then, in [Snapchat Ads Manager](https://ads.snapchat.com), open **Events Manager** for your pixel and confirm events are arriving from your Conversions API integration. New events typically appear within a few minutes after a test purchase or page view. </Step> </Steps> # How to Disable Snapchat Data Sharing in Shopify Source: https://docs.upstackdata.com/guides/snapchat-ads/how-to-disable-snapchat-data-sharing-in-shopify Disable Shopify's Snapchat sales channel data sharing to stop duplicate Snapchat pixel events and let Upstack Data deliver clean server-side conversions to Snapchat CAPI. <Tip> **Quick Summary** * In Shopify admin, open the **Sales channels** section * Select **Snapchat Ads**, then open the **Settings** tab * Open the **Data sharing** tab and find the **Pixel ID** section * Click **Disconnect** to unlink the Snapchat Pixel from Shopify </Tip> <Warning> Disabling Snapchat data sharing is crucial to prevent duplicate events, which can distort reporting and attribution. It ensures Snapchat only receives clean, accurate data through Upstack Data for reliable insights and better ad optimization. </Warning> ## Prerequisites Before you start, you need: * Admin access to your Shopify store ([Shopify admin](https://admin.shopify.com)) * The Snapchat Ads sales channel currently installed in Shopify * A configured Snapchat destination in your [Upstack dashboard](https://app.upstackdata.com/pixel/event-destinations) ([setup guide](/guides/snapchat-ads/how-to-configure-snapchat-pixel-destination-in-upstack-data)) ## Steps to Disable Snapchat Data Sharing in Shopify <Steps> <Step title="Sign in to Shopify admin"> Sign in to [Shopify admin](https://admin.shopify.com) for the store where the Snapchat Ads sales channel is installed. </Step> <Step title="Open the Snapchat Ads sales channel"> In the left-hand menu, click **Sales channels**, then select **Snapchat Ads**. (You can also use the search bar at the top of Shopify admin to locate the Snapchat Ads sales channel.) Make sure you are on the **Settings** tab of the Snapchat Ads sales channel. </Step> <Step title="Open the Data sharing tab"> In the Snapchat Ads settings, click the **Data sharing** tab. Scroll to the **Pixel ID** section and find your connected Snapchat Pixel. <img alt="Snapchat Ads Data sharing tab showing Pixel ID section with Disconnect option" /> </Step> <Step title="Disconnect the Snapchat Pixel from Shopify"> Click **Disconnect** next to the connected Pixel ID to unlink it from Shopify, then confirm the action in the dialog. </Step> <Step title="Verify Snapchat is no longer sharing data through Shopify"> Refresh the **Data sharing** tab and confirm the Pixel ID section no longer shows a connected pixel. Then, in your [Upstack dashboard](https://app.upstackdata.com/pixel/event-destinations), confirm the **Snapchat** destination is still **Healthy** and continuing to send events through Upstack Data. </Step> </Steps> <Note> **Need Help?** If you encounter any issues during setup, contact our support team and we'll help diagnose the problem. </Note> # How to Generate my Snapchat Conversion API Token? Source: https://docs.upstackdata.com/guides/snapchat-ads/how-to-generate-my-snapchat-conversion-api-token Generate a Snapchat Conversion API access token in Snapchat Ads Manager — required to authenticate the Upstack Data Snapchat destination for server-side conversion forwarding. <Tip> **Quick Summary** * Sign in to [Snapchat Business Manager](https://business.snapchat.com) * Open the **Business Details** page * Click **Generate Token** * **Copy and save** the generated **Conversion API Token** immediately (Snapchat only displays it once) * Paste the token into the Snapchat destination form in your Upstack dashboard </Tip> ## What is a Snapchat Conversion API Token? <Note> A **Snapchat Conversion API Token** is a secure credential generated in Snapchat Business Manager that authorizes platforms like Upstack Data to send conversion events directly to Snapchat's Conversions API. It is a long alphanumeric string, typically 100+ characters long. </Note> It enables server-side event tracking to reduce reliance on browser pixels, improves attribution by capturing conversions lost to ad blockers, privacy restrictions, or cookies, and boosts ad performance by providing Snapchat with more complete and reliable conversion data. ## Prerequisites Before you start, you need: * Admin access to your Snapchat Ads account * At least one Snapchat Pixel created ([how to create one](/guides/snapchat-ads/how-to-get-my-snapchat-pixel-id)) * A secure place to store the generated token (Snapchat only displays it once) ## Steps to Generate the Conversion API Token <Steps> <Step title="Sign in to Snapchat Business Manager"> Sign in to [Snapchat Business Manager](https://business.snapchat.com). </Step> <Step title="Open Business Details"> In the left-hand menu, click **Business Details**. <img alt="" /> </Step> <Step title="Generate the Conversion API Token"> On the **Business Details** page, click **Generate Token**. <img alt="" /> **Copy** the generated Conversion API Token immediately. Then paste it into the **Conversion API Token** field when [configuring the Snapchat destination](/guides/snapchat-ads/how-to-configure-snapchat-pixel-destination-in-upstack-data) in your Upstack dashboard. <img alt="" /> <Warning> Snapchat only shows the token once — copy it now and save it to a secure location such as a password manager. Store the token on secure backend servers and do not share it. When generating new tokens, remove old ones as soon as you confirm they are no longer needed. </Warning> </Step> <Step title="Verify the token format"> Confirm the value you copied is a long alphanumeric string (typically 100+ characters) with no extra spaces. You can paste it into the **Conversion API Token** field when configuring the Snapchat destination in your Upstack dashboard. </Step> </Steps> <Note> ***Need help finding this?*** **[How to Get my Snapchat Pixel ID →](/guides/snapchat-ads/how-to-get-my-snapchat-pixel-id)** </Note> # How to Get my Snapchat Pixel ID? Source: https://docs.upstackdata.com/guides/snapchat-ads/how-to-get-my-snapchat-pixel-id Find your Snapchat Pixel ID in Snapchat Ads Manager — required to configure the Upstack Data Snapchat destination and forward server-side conversions to Snapchat CAPI. <Tip> **Quick Summary** * Sign in to [Snapchat Ads Manager](https://ads.snapchat.com) * Open **Events Manager → Pixels** (or **Pixels** in the left-hand menu) * If a pixel exists, copy the **Pixel ID** displayed under the pixel name * If no pixel exists, click **Create Pixel**, name it `Upstack Data`, then **Create** and copy the new Pixel ID * Paste the Pixel ID into the Snapchat destination form in your Upstack dashboard </Tip> ## What is a Snapchat Pixel ID? <Note> A **Snapchat Pixel ID** is a unique identifier assigned to your Snapchat Pixel when you create it in Snapchat Ads Manager. It is a 32-character UUID, for example `00000000-0000-0000-0000-000000000000`. </Note> Its purpose is to: * **Identify your pixel** so Snapchat knows which ad account and campaigns the data belongs to * **Track on-site actions** such as page views, purchases, and sign-ups * **Send event data to Snapchat Ads Manager** for reporting, audience building, and optimization * **Improve targeting and attribution** by connecting user activity on your website with your Snapchat ads ## Prerequisites Before you start, you need: * Admin access to your Snapchat Ads account ([Snapchat Ads Manager](https://ads.snapchat.com)) * Permission to create or view pixels in your ad account ## Steps to Find Your Snapchat Pixel ID <Steps> <Step title="Sign in to Snapchat Ads Manager"> Sign in to [Snapchat Ads Manager](https://ads.snapchat.com), then open **Events Manager → Pixels** (or click **Pixels** in the left-hand menu). <img alt="Snapchat Ads Manager with Events Manager and Pixels menu" /> If you already have a pixel, find the **Pixel ID** for the pixel you want to connect with Upstack Data — it appears beneath the pixel name as a 32-character UUID. <img alt="Snapchat Pixel showing Pixel ID beneath pixel name" /> </Step> <Step title="Create a new pixel (only if you don't have one)"> From the **Pixels** page in Snapchat Ads Manager, click **Create Pixel**. <img alt="Create Pixel button in Snapchat Pixels page" /> <img alt="Create Pixel form with name field" /> Type `Upstack Data` as the pixel name, then click **Create**. <img alt="Pixel name field with Upstack Data entered" /> </Step> <Step title="Copy your Pixel ID"> The **Pixel ID** is displayed beneath the pixel name as a 32-character UUID, for example `00000000-0000-0000-0000-000000000000`. **Copy** the Pixel ID. <img alt="Pixel ID displayed beneath pixel name with copy option" /> <Warning> Keep your Snapchat Pixel ID confidential. It is a unique identifier for your account and can be used to track conversions and user behavior on your website. </Warning> </Step> <Step title="Verify the Pixel ID"> Confirm the value you copied is a 32-character UUID with no extra spaces. You can paste it into the **Snapchat Pixel ID** field when [configuring the Snapchat destination](/guides/snapchat-ads/how-to-configure-snapchat-pixel-destination-in-upstack-data) in your Upstack dashboard. </Step> </Steps> <Note> ***Need help finding this?*** **[How to Generate my Snapchat Conversion API Token →](/guides/snapchat-ads/how-to-generate-my-snapchat-conversion-api-token)** </Note> # Complete How-To Guide for Onboarding TikTok Ads in Upstack Data Source: https://docs.upstackdata.com/guides/tiktok-ads/complete-how-to-guide-for-onboarding-tiktok-ads-in-upstack-data Onboard TikTok Ads in Upstack Data — locate your TikTok Pixel ID, generate the API access token, configure the destination, and disable Shopify's duplicate TikTok sales channel pixel. <Info> **New to Upstack?** Follow the [getting started guide](/get-started/install-on-shopify) for a streamlined onboarding walkthrough. </Info> <Tip> **Quick Summary** * Create and configure the **TikTok Ads destination** in the Upstack dashboard with browser Pixel and Conversions API (CAPI). * **Disable TikTok Sales Channel data sharing in Shopify** to prevent duplicate events. * **Monitor** Event Match Quality improvements over 7–10 days. * Expect a **1–2 point increase** on upper-funnel events. * **Ignore "Update Recommended"** warnings — they are normal and require no action. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to your **TikTok Business Center** * A **TikTok Pixel** configured in TikTok Events Manager (or follow [How to Create New TikTok Ads Pixel ID →](/guides/tiktok-ads/how-to-create-new-tiktok-ads-pixel-id) first) * Admin access to your **Shopify** store (to disable the TikTok Sales Channel data sharing) <Steps> <Step title="Create and Configure TikTok Ads Pixel Destination in Upstack Data"> <Note> **Purpose:** Enable Upstack Data to send data via browser pixel and CAPI to TikTok Ads for improved tracking accuracy. </Note> Help guide to complete this step: [How to Configure TikTok Ads Pixel Destination in Upstack Data →](/guides/tiktok-ads/how-to-configure-tiktok-ads-pixel-destination-in-upstack-data) </Step> <Step title="Disable TikTok Sales Channel Data Sharing in Shopify"> <Warning> You must disable all other TikTok Ads Pixels/Integrations to prevent duplicate conversions and events. </Warning> Help guide to complete this step: [How to Disable TikTok Data Sharing in Shopify →](/guides/tiktok-ads/how-to-disable-tiktok-data-sharing-in-shopify) </Step> </Steps> ## What to Expect After Setup ### Event Match Quality Timeline * **Days 1-3: Initial Improvement** * Event Match Quality scores begin improving * Data starts flowing through both pixel and CAPI * **Days 7-10: Normalization** * Scores stabilize at improved levels * Full benefit of dual tracking realized ### Expected Score Improvements * **Upper/Mid-Funnel Events (1-2 point increase typical):** * **Page View** - Better user matching * **View Content** - Improved product tracking * **Add to Cart** - Enhanced cart data * **Purchase Event:** * **No change expected** - Already optimized since all customer data (email, name, address) is sent at purchase ### Normal Warnings **"Update Recommended" Notifications** * You may see warnings in TikTok Events Manager showing **"Update Recommended"** next to events. <Note> **This is NORMAL and NO ACTION is needed.** These appear because: * TikTok detects configuration changes * The system recognizes new data sources * The integration method has changed </Note> ## Verify the Setup After completing both steps: * In the Upstack dashboard, navigate to **Events Destination** at [app.upstackdata.com/pixel/event-destinations](https://app.upstackdata.com/pixel/event-destinations) and confirm the TikTok destination shows as **Healthy**. * In [TikTok Events Manager](https://ads.tiktok.com/i18n/events_manager/home), open your **UpstackData** Pixel and confirm events are arriving via both **Browser** and **Server (CAPI)**. * Place a test order on your store and confirm the **Purchase** event appears in TikTok Events Manager within a few minutes. If the destination shows **Unhealthy** or events do not arrive, double-check the **Pixel ID** and **Access Token** values, then contact Upstack Data support if issues persist. # How to Configure TikTok Ads Pixel Destination in Upstack Data Source: https://docs.upstackdata.com/guides/tiktok-ads/how-to-configure-tiktok-ads-pixel-destination-in-upstack-data Configure the TikTok Ads destination in Upstack Data with your Pixel ID and API access token to enable dual tracking via browser pixel and server-side Events API for higher match quality. <Tip> **Quick Summary** * Sign in to the Upstack dashboard and click **"+ New Destination"**. * Select **TikTok** from the destination options. * Enter your **TikTok Pixel ID** and **Access Token**. * Check the **"Check to enable sending events via TikTok Conversions API"** box for server-side tracking. * Click **Create Configuration** to activate the integration. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to your **TikTok Business Center** * A **TikTok Pixel** configured under **Events Manager → Data sources** (see [How to Create New TikTok Ads Pixel ID →](/guides/tiktok-ads/how-to-create-new-tiktok-ads-pixel-id)) * Your **TikTok Pixel ID** ([How to Find your TikTok Ads Pixel ID →](/guides/tiktok-ads/how-to-find-your-tiktok-ads-pixel-id)) * A generated **Access Token** ([How to Generate Your TikTok API Access Token →](/guides/tiktok-ads/how-to-generate-your-tiktok-api-access-token)) ## Configuration Steps <Steps> <Step title="Sign in to Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com). </Step> <Step title="Add a new TikTok destination"> * In the Upstack dashboard, navigate to **Events Destination** ([app.upstackdata.com/pixel/event-destinations](https://app.upstackdata.com/pixel/event-destinations)) * Click **"+ New Destination"** in the top-right corner of the page <img alt="Add New Destination" /> * In the **Select a Destination** popup, click **"TikTok"** * Click **Next** <img alt="Select Tiktok Ads destination" /> </Step> <Step title="Enter your Pixel ID and Access Token"> Fill in the form fields: 1. **TikTok Pixel ID** — 20-character alphanumeric string (e.g., `C2A3B4C5D6E7F8G9H0I1`). Also called the Dataset ID. 2. Check the box **"Check to enable sending events via TikTok Conversions API"** 3. **Access Token** — long alphanumeric string starting with letters/numbers, generated from TikTok Events Manager <Warning> The Conversions API checkbox **must be selected** for server-side tracking to work. </Warning> <img alt="TikTok destination form with Pixel ID and Access Token fields" /> <Note> ***Need help finding these?*** **[How to Find your TikTok Ads Pixel ID →](/guides/tiktok-ads/how-to-find-your-tiktok-ads-pixel-id)** **[How to Generate Your TikTok API Access Token →](/guides/tiktok-ads/how-to-generate-your-tiktok-api-access-token)** </Note> </Step> <Step title="Create the configuration"> Click the **Create Configuration** button. <img alt="Create Configuration button to save TikTok destination" /> <Note> **Success! 🎉** You should see a confirmation message and the TikTok destination will appear as **"Healthy"** in your destinations list. </Note> </Step> </Steps> ## Verify the Setup To confirm the destination is working: * In the Upstack dashboard, the TikTok destination should show **Healthy** status under **Events Destination**. * In [TikTok Events Manager](https://ads.tiktok.com/i18n/events_manager/home), open your Pixel and confirm events are arriving via both **Browser** and **Server (CAPI)**. * Place a test order on your store and check that the **Purchase** event appears in TikTok Events Manager within a few minutes. If the destination shows **Unhealthy** or no events arrive, double-check that: * The **Pixel ID** is exactly 20 characters with no spaces. * The **Access Token** was copied immediately after generation (TikTok shows it only once) and contains no leading or trailing spaces. * The Conversions API checkbox is selected. If issues persist, contact Upstack Data support. # How to Create New TikTok Ads Pixel ID Source: https://docs.upstackdata.com/guides/tiktok-ads/how-to-create-new-tiktok-ads-pixel-id Create a new TikTok Ads Pixel ID in TikTok Ads Manager to track website conversions, measure ad performance, and feed Upstack Data's TikTok Events API destination. <Tip> **Quick Summary** * In TikTok Events Manager, click **"+ Connect data source"**. * Select **Web** as the data source type. * Name your Pixel **"UpstackData"**. * Enter your website URL and complete setup. </Tip> ## Prerequisites Before you start, you need: * Admin access to your **TikTok Business Center** * A **TikTok Ads Manager** account linked to your Business Center * The URL of the website where the Pixel will be installed ## Pixel Creation Process <Steps> <Step title="Sign in to TikTok Events Manager"> * Sign in to [TikTok Events Manager](https://ads.tiktok.com/i18n/events_manager/home) * In the top navigation, click **Tools → Events** <img alt="TikTok Ads Manager with Tools and Events menu options" /> </Step> <Step title="Start creating a new Pixel"> * In TikTok Events Manager, click **"+ Connect data source"** in the upper-left corner of the page (or the **Connect Data Sources** button in the center of the screen if no data sources exist yet) * Select **Web** and click **Next** <img alt="Connect data source button in TikTok Events Manager" /> <img alt="Select Web as data source type" /> </Step> <Step title="Name your Pixel"> * Set the Pixel name to **"UpstackData"** * Click **Create** <img alt="Pixel name field with UpstackData entered" /> </Step> <Step title="Add your website"> * Enter your business website URL * Click **Next** <img alt="Website URL input field for TikTok Pixel setup" /> </Step> <Step title="Finish the Pixel setup"> * Choose an installation method (partner integration or manual code) * Configure tracking events * Install the Pixel code on your website * Verify the Pixel code using TikTok's Pixel Helper or TikTok Events Manager * When everything is confirmed, click **Finish** to complete setup <img alt="Finish button to complete TikTok Pixel setup" /> <Note> Your new TikTok Pixel is ready to integrate with Upstack Data. </Note> </Step> </Steps> ## Verify the Setup To confirm the Pixel was created: * In TikTok Events Manager, navigate to **Tools → Events → Data sources** — your **UpstackData** Pixel should appear in the list. * Open the Pixel and confirm it has a **Pixel ID** (a 20-character alphanumeric string, e.g., `C2A3B4C5D6E7F8G9H0I1`). Next steps: * [How to Find your TikTok Ads Pixel ID →](/guides/tiktok-ads/how-to-find-your-tiktok-ads-pixel-id) * [How to Generate Your TikTok API Access Token →](/guides/tiktok-ads/how-to-generate-your-tiktok-api-access-token) If the Pixel does not appear after creation, refresh the page or contact Upstack Data support. # How to Disable TikTok Data Sharing in Shopify Source: https://docs.upstackdata.com/guides/tiktok-ads/how-to-disable-tiktok-data-sharing-in-shopify Disable Shopify's TikTok sales channel pixel to stop duplicate TikTok conversion events and let Upstack Data deliver clean server-side conversions to TikTok Events API. <Tip> **Quick Summary** * Sign in to your Shopify admin and open the **Sales channels** menu. * Open the **TikTok** sales channel and click **Settings**. * In **Data sharing → Customer Data Sharing**, click **Disconnect** on the connected TikTok Pixel. * Confirm the disconnection in the popup. </Tip> ## Prerequisites Before you start, you need: * Admin access to your **Shopify** store * The **TikTok** sales channel installed in Shopify with an active TikTok Pixel connection * Your Upstack Data TikTok destination already configured ([How to Configure TikTok Ads Pixel Destination in Upstack Data →](/guides/tiktok-ads/how-to-configure-tiktok-ads-pixel-destination-in-upstack-data)) <Warning> Duplicate TikTok events typically occur when multiple TikTok Pixel integrations are active on your site. You must disable TikTok Sales Channel data sharing and ensure no other TikTok Pixel apps are installed. </Warning> ## Steps to Disable TikTok Data Sharing in Shopify <Steps> <Step title="Sign in to Shopify"> Sign in to your [Shopify admin](https://admin.shopify.com/). </Step> <Step title="Open the TikTok sales channel settings"> * In the Shopify admin sidebar, click **Sales channels** * Select **TikTok**, then click the **Settings** tab *Tip: You can also use the Shopify admin search to locate the TikTok sales channel.* <img alt="Shopify sidebar with TikTok Sales Channel Settings" /> <img alt="TikTok sales channel Settings tab in Shopify admin" /> </Step> <Step title="Open Data sharing"> In the TikTok sales channel settings, click the **Data sharing** tab in the left-hand menu. <img alt="Share Data section with Disconnect button" /> </Step> <Step title="Disconnect the TikTok Pixel"> * Scroll to the **Customer Data Sharing** section and locate your connected TikTok Pixel * Click the **Disconnect** button <img alt="Customer Data Sharing section showing connected TikTok Pixel with Disconnect button" /> </Step> <Step title="Confirm the disconnection"> * A confirmation window appears explaining how disconnecting the Pixel affects tracking * Click **Disconnect** again in the lower-right corner to confirm <img alt="Disconnect confirmation popup for TikTok Pixel" /> </Step> </Steps> ## Verify the Setup To confirm data sharing is disabled: * Return to **Sales channels → TikTok → Settings → Data sharing** in Shopify and confirm the **Customer Data Sharing** section no longer shows a connected Pixel. * Place a test order on your store and check [TikTok Events Manager](https://ads.tiktok.com/i18n/events_manager/home) — you should see exactly **one** Purchase event arriving from your Upstack Data integration (not duplicates). If duplicate events continue: * Check the Shopify **Apps** menu for any other TikTok Pixel apps and remove them. * Inspect your theme for hard-coded TikTok Pixel snippets and remove them. <Note> **Need help?** If you encounter any issues, contact our support team and we'll help diagnose the problem. </Note> # How to Find your TikTok Ads Pixel ID Source: https://docs.upstackdata.com/guides/tiktok-ads/how-to-find-your-tiktok-ads-pixel-id Find your TikTok Ads Pixel ID in TikTok Ads Manager — required to configure the Upstack Data TikTok destination for server-side conversion forwarding via TikTok Events API. <Tip> **Quick Summary** * Sign in to TikTok Events Manager. * Open **Data sources** and select your **UpstackData** Pixel. * Copy the **Pixel ID** displayed on the Pixel overview page (a 20-character alphanumeric string). </Tip> ## Prerequisites Before you start, you need: * Admin access to your **TikTok Business Center** * A **TikTok Pixel** already created (see [How to Create New TikTok Ads Pixel ID →](/guides/tiktok-ads/how-to-create-new-tiktok-ads-pixel-id) if you haven't created one yet) ## What is a TikTok Pixel ID? <Note> A **TikTok Pixel ID** is a unique identifier automatically assigned to your TikTok Pixel when you create it in TikTok Events Manager. </Note> Its purpose is to: * **Identify your Pixel** and connect it to the correct TikTok ad account and campaigns * **Track user actions on your website** such as views, clicks, sign-ups, and purchases * **Send event data back to TikTok Events Manager** for reporting, audience creation, and optimization * **Improve attribution and targeting** by linking website activity to your TikTok ads ## Configuration Steps <Steps> <Step title="Sign in to TikTok Events Manager"> * Sign in to [TikTok Events Manager](https://ads.tiktok.com/i18n/events_manager/home) * In the top navigation, click **Tools → Events** <img alt="TikTok Ads Manager with Tools and Events menu options" /> </Step> <Step title="Open your UpstackData Pixel"> * In TikTok Events Manager, click **Data sources** in the left-hand menu * Find your **UpstackData** Pixel in the list and click its name to open the Pixel overview page <img alt="TikTok Events Manager Data sources menu in left sidebar" /> <img alt="UpstackData Pixel listed in TikTok Data sources" /> <Note> **Note:** If you haven't created a Pixel yet, see [How to Create New TikTok Ads Pixel ID →](/guides/tiktok-ads/how-to-create-new-tiktok-ads-pixel-id) first. </Note> </Step> <Step title="Copy your Pixel ID"> * On the Pixel overview page, locate the **Pixel ID** at the top of the page (next to the Pixel name) * Click the copy icon to copy the **Pixel ID** to your clipboard * Paste it into the **TikTok Pixel ID** field in the Upstack dashboard at [app.upstackdata.com/pixel/event-destinations](https://app.upstackdata.com/pixel/event-destinations) <img alt="TikTok Pixel overview page showing Pixel ID with copy button" /> <Note> **Format:** The Pixel ID is a 20-character alphanumeric string (e.g., `C2A3B4C5D6E7F8G9H0I1`). </Note> </Step> </Steps> ## Verify the Setup To confirm you copied the correct value: * The **Pixel ID** should be exactly 20 characters with no spaces. * In the Upstack dashboard, after saving the destination it should show as **Healthy** under **Events Destination**. <Note> **Next step:** [How to Generate Your TikTok API Access Token →](/guides/tiktok-ads/how-to-generate-your-tiktok-api-access-token) </Note> # How to Generate Your TikTok API Access Token Source: https://docs.upstackdata.com/guides/tiktok-ads/how-to-generate-your-tiktok-api-access-token Generate a TikTok Events API access token in TikTok Ads Manager — required to authenticate the Upstack Data TikTok destination and sync server-side conversions and ads data. <Tip> **Quick Summary** * Sign in to TikTok Events Manager. * Open **Data sources** and select your **UpstackData** Pixel. * Open the **Settings** tab and scroll to **Events API**. * Click **"Generate access token"**. * Copy the **Access Token** immediately — it is shown only once. </Tip> ## Prerequisites Before you start, you need: * Admin access to your **TikTok Business Center** * A **TikTok Pixel** already created (see [How to Create New TikTok Ads Pixel ID →](/guides/tiktok-ads/how-to-create-new-tiktok-ads-pixel-id)) * Permission to manage Events API settings on the Pixel ## What is a TikTok Access Token? <Note> A **TikTok Access Token** is a secure credential that lets platforms like Upstack Data connect to your TikTok Ads account to sync performance data, enable server-side tracking via the Conversions API (CAPI), and improve attribution and optimization. </Note> ## Configuration Steps <Steps> <Step title="Sign in to TikTok Events Manager"> * Sign in to [TikTok Events Manager](https://ads.tiktok.com/i18n/events_manager/home) * In the top navigation, click **Tools → Events**, then open **Data sources** * Click your **UpstackData** Pixel to open its overview page <img alt="TikTok Events Manager showing Data sources with UpstackData Pixel" /> <Note> **Note:** If you haven't created a Pixel yet, see [How to Create New TikTok Ads Pixel ID →](/guides/tiktok-ads/how-to-create-new-tiktok-ads-pixel-id) first. </Note> </Step> <Step title="Open the Settings tab"> On the Pixel overview page, click the **Settings** tab. <img alt="TikTok Pixel Settings tab in the overview page" /> </Step> <Step title="Generate the Access Token"> On the **Settings** tab: * Scroll down to the **Events API** section * Click the **"Generate access token"** button <img alt="Events API section with Generate access token button" /> </Step> <Step title="Copy your Access Token"> * Click the copy icon next to the generated **Access Token** — it is a long alphanumeric string starting with letters/numbers * Paste it into the **Access Token** field in the Upstack dashboard at [app.upstackdata.com/pixel/event-destinations](https://app.upstackdata.com/pixel/event-destinations) <img alt="Generated TikTok access token with copy button" /> <Warning> The Access Token is shown **only once**. Copy and store it securely immediately. If you lose it, you'll need to generate a new one. </Warning> </Step> </Steps> ## Verify the Setup To confirm the Access Token works: * In the Upstack dashboard, after saving your TikTok destination it should show as **Healthy** under **Events Destination**. * In TikTok Events Manager, return to the Pixel **Settings → Events API** section — the token should be listed as active. If the destination is **Unhealthy**: * Re-check that the **Access Token** was pasted with no leading or trailing spaces. * Confirm the **Pixel ID** matches the Pixel that owns the token. * Generate a new token if needed and update it in the Upstack dashboard. <Note> **Need to find your Pixel ID?** See [How to Find your TikTok Ads Pixel ID →](/guides/tiktok-ads/how-to-find-your-tiktok-ads-pixel-id). </Note> # Headless Shopify installation Source: https://docs.upstackdata.com/installation/headless-shopify Install the Upstack tracking script on headless Shopify storefronts (Hydrogen, Next.js, custom builds) using the JavaScript SDK. If your storefront runs on Shopify Hydrogen, Next.js, Remix, or any other custom front end, the standard Shopify Theme App Extension won't load — there's no Liquid theme to inject into. Instead, install the Upstack JavaScript SDK directly in your storefront code. <Note> Server-side events (orders, refunds, fulfillment updates) are still captured automatically through Shopify webhooks regardless of your storefront architecture. This page only covers browser-side event tracking. </Note> ## Prerequisites * The Upstack Data app installed in your [Shopify Admin](https://admin.shopify.com) (so server-side webhooks are configured) * An [Upstack Data](https://app.upstackdata.com) account with subscription active * Your Upstack Pixel ID (UUID format: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`, e.g., `58284d43-85f6-41fb-b2e0-f32f8ecb4e9b`). See [How to find my Upstack Data Pixel ID](/resources/how-to-find-my-upstack-data-pixel-id) * Edit access to the headless storefront codebase (Hydrogen, Next.js, Remix, Nuxt, or other framework) * Ability to deploy changes to your storefront (CI/CD or manual deploy access) ## When to Use This Page Use the headless installation if any of the following are true: * Your storefront is built on **Shopify Hydrogen**, **Next.js**, **Remix**, **Nuxt**, or another custom framework * You serve checkout through Shopify but render product, collection, and cart pages from your own front end * You don't have a standard Liquid theme where the Shopify Theme App Extension can be enabled If your storefront uses a standard Shopify theme, follow the [standard Shopify installation guide](/get-started/install-on-shopify) instead — the Theme App Extension handles everything automatically. ## Installation Choose one of the two installation methods below depending on your storefront's build system. ### Option 1: CDN Script Tag The simplest approach is to load the Upstack pixel from our CDN. Add the following tag to the `<head>` of every page that should track events: ```html theme={null} <script src="https://cdn.upstackdata.com/pixel.js" data-pixel-id="YOUR_PIXEL_ID" async></script> ``` Replace `YOUR_PIXEL_ID` with the Pixel ID found in the [Upstack dashboard](https://app.upstackdata.com) under **Settings → Event Health** (UUID format: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`). See [How to find my Upstack Data Pixel ID](/resources/how-to-find-my-upstack-data-pixel-id) for step-by-step instructions. The `async` attribute prevents the pixel from blocking page rendering. Once loaded, the pixel automatically captures page views and listens for cart and checkout events through the Shopify Storefront API. ### Option 2: NPM Package For tighter integration with your front end framework — including programmatic event tracking and SSR support — install the Upstack npm package: ```bash theme={null} npm install @upstackdata/pixel ``` Then initialize the pixel in your storefront's entry point: ```javascript theme={null} import { Upstack } from '@upstackdata/pixel'; const upstack = new Upstack({ pixelId: 'YOUR_PIXEL_ID' }); upstack.page(); ``` Call `upstack.page()` on every route change to register a page view. For cart and checkout events, see the SDK reference for the full event API. <Tip> In framework-specific environments like Hydrogen or Next.js, initialize the pixel in your root layout or `_app` component so it's only created once per session. </Tip> ## Server-Side Events Continue to Flow Headless installation only affects browser-side tracking. Server-side events from Shopify — orders placed, orders refunded, products updated, customer changes — continue to reach Upstack through Shopify webhooks regardless of your storefront architecture. As long as the Upstack Shopify app is installed in your Shopify admin, these webhooks are configured automatically. This means your conversion data, revenue, and order-level attribution will still flow into Upstack even if you skip the browser pixel entirely. Browser tracking adds page views, product views, and pre-checkout cart events on top of the server-side baseline. ## Verify the Install Once the pixel is loaded on your storefront: 1. Open your storefront in a browser and navigate between pages. 2. Use the [Upstack Data Pixel Helper](/guides/shopify/how-to-install-upstack-data-pixel-helper) to confirm the pixel fires with your Pixel ID. 3. Open the [Upstack dashboard](https://app.upstackdata.com) and go to **Sources → Shopify**. 4. Confirm `PageView` events arrive within 1–2 minutes of activity. For more thorough event verification, see [Verify events are flowing](/get-started/verify-events). ## Related <CardGroup> <Card title="Standard Shopify install" icon="shopify" href="/get-started/install-on-shopify"> The default install path for storefronts that use a Shopify theme. </Card> <Card title="Shopify source" icon="arrow-right-to-bracket" href="/sources/shopify"> How the Shopify source ingests events through the pixel and webhooks. </Card> <Card title="Shopify webhooks" icon="webhook" href="/sources/shopify-webhooks"> Server-side events that capture automatically regardless of storefront architecture. </Card> <Card title="Verify events" icon="circle-check" href="/get-started/verify-events"> Confirm events are flowing from your storefront into Upstack. </Card> </CardGroup> # Upstack Data Documentation Source: https://docs.upstackdata.com/overview Set up Upstack Data and start sending high-quality conversion data to your ad platforms. # Get started Create an account and start sending high-quality conversion data to your marketing platforms. ## Common use cases <StripeCardGroup> <StripeCard title="Improve Meta CAPI match quality" description="Boost Event Match Quality scores by sending identity-enriched server-side events." href="/use-cases/improve-meta-match-quality" /> <StripeCard title="Track Shopify events server-side" description="Capture every storefront interaction server-side, immune to ad blockers and cookie restrictions." href="/use-cases/track-server-side-events" /> <StripeCard title="Send conversions to multiple platforms" description="Forward purchase and conversion events to Meta, TikTok, Klaviyo, and GA4 simultaneously." href="/use-cases/send-to-multiple-platforms" /> <StripeCard title="Resolve anonymous visitors to customers" description="Match anonymous sessions to known customers using deterministic and probabilistic identity signals." href="/use-cases/resolve-visitor-identities" /> <StripeCard title="Recover abandoned carts via Klaviyo" description="Trigger abandoned cart flows in Klaviyo with identity-resolved customer data." href="/use-cases/recover-abandoned-carts" /> <StripeCard title="See which campaigns drive purchases" description="Attribute revenue to marketing touchpoints with multi-touch attribution models." href="/analytics/attribution-reporting" /> </StripeCardGroup> ## Platform guides Detailed, step-by-step onboarding guides for each ad platform and integration. Start with the master onboarding hub or jump directly to a specific platform. <StripeCardGroup> <StripeCard title="Complete onboarding guide" description="Master hub covering the full Upstack Data onboarding process from start to finish." href="/guides/getting-started/complete-upstack-data-onboarding-guide" /> <StripeCard title="Facebook (Meta) onboarding" description="Set up Meta CAPI, disable duplicate pixels, and configure NC-ROAS metrics." href="/guides/facebook-ads/complete-how-to-guide-for-onboarding-facebook-meta-in-upstack-data" /> <StripeCard title="Google Ads onboarding" description="Create purchase goals, configure Enhanced Conversions, and connect Google Ads." href="/guides/google-ads/complete-how-to-guide-for-onboarding-google-ads-in-upstack-data" /> <StripeCard title="TikTok Ads onboarding" description="Set up TikTok CAPI and browser pixel with Upstack Data for improved match quality." href="/guides/tiktok-ads/complete-how-to-guide-for-onboarding-tiktok-ads-in-upstack-data" /> <StripeCard title="Klaviyo onboarding" description="Integrate Klaviyo for enhanced email tracking and 40%+ better abandonment capture." href="/guides/klaviyo/complete-how-to-guide-for-onboarding-klaviyo-in-upstack-data" /> <StripeCard title="Shopify app setup" description="Complete guide for installing and configuring the Upstack Data app in Shopify." href="/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify" /> </StripeCardGroup> ## Start building <StripeCardGroup> <StripeCard title="Install Upstack on Shopify" description="Go from zero to live events in under 10 minutes." href="/get-started/install-on-shopify" /> <StripeCard title="Connect your first destination" description="Forward enriched events to Meta CAPI, TikTok, or another platform." href="/get-started/connect-a-destination" /> <StripeCard title="Verify events are flowing" description="Confirm events appear in your dashboard and reach destinations." href="/get-started/verify-events" /> <StripeCard title="Explore the event model" description="Understand the 13 standard events Upstack tracks automatically." href="/pixel/events/taxonomy" /> <StripeCard title="Set up identity resolution" description="Learn how Upstack ID matches visitors to customers." href="/pixel/identity-resolution" /> <StripeCard title="Browse all integrations" description="See every source and destination Upstack supports." href="/sources/overview" /> </StripeCardGroup> ## Query and automate <StripeCardGroup> <StripeCard title="Analytics query guide" description="Build custom reports with measures and dimensions in the dashboard." href="/analytics/query-guide" /> <StripeCard title="Install the CLI" description="Query data and manage dashboards from the command line." href="/cli/install" /> <StripeCard title="API reference" description="Programmatic access to query, catalog, and dashboard endpoints." href="/api-reference/overview" /> </StripeCardGroup> # add_payment_info Event Source: https://docs.upstackdata.com/pixel/events/add-payment-info Track when a customer enters payment details during checkout Fires when a customer enters payment details during checkout. This is the last step before purchase and indicates very high purchase intent. <Note> **Shopify:** Automatically tracked when customers complete the payment step in checkout. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'add_payment_info', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2 } ], value: 84.97, currency: 'USD', paymentType: 'credit_card' }); ``` ## Properties | Property | Type | Required | Description | | ----------- | ------ | -------- | ---------------------------------------------------------------- | | items | array | No | Products in checkout | | value | number | No | Cart value at payment step | | currency | string | No | ISO 4217 currency code | | paymentType | string | No | Payment method (e.g., `'credit_card'`, `'paypal'`, `'shop_pay'`) | ## When to Fire * Payment form completion * Payment method selection * Before final order submission ## Related Events * [add\_shipping\_info](/pixel/events/add-shipping-info) — Previous checkout step * [purchase](/pixel/events/purchase) — When order is completed # add_shipping_info Event Source: https://docs.upstackdata.com/pixel/events/add-shipping-info Track when a customer enters shipping details during checkout Fires when a customer enters shipping details during checkout. This helps track checkout progress and identify where customers drop off. <Note> **Shopify:** Automatically tracked when customers complete the shipping step in checkout. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'add_shipping_info', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2 } ], value: 84.97, currency: 'USD', shippingTier: 'standard' }); ``` ## Properties | Property | Type | Required | Description | | ------------ | ------ | -------- | ---------------------------------------------------------------- | | items | array | No | Products in checkout | | value | number | No | Cart value at shipping step | | currency | string | No | ISO 4217 currency code | | shippingTier | string | No | Shipping method (e.g., `'standard'`, `'express'`, `'overnight'`) | ## When to Fire * Shipping form completion * Shipping method selection * Proceeding past shipping step ## Related Events * [initiate\_checkout](/pixel/events/initiate-checkout) — Starting checkout * [select\_shipping\_method](/pixel/events/select-shipping-method) — When selecting specific shipping option * [add\_payment\_info](/pixel/events/add-payment-info) — After entering payment details # add_to_cart Event Source: https://docs.upstackdata.com/pixel/events/add-to-cart Track when a visitor adds an item to their cart Fires when a visitor adds an item to their cart. This is one of the most important e-commerce events for tracking purchase intent and building audiences. <Note> **Shopify:** Automatically tracked when using standard Shopify cart functionality. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'add_to_cart', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2, variant: 'Blue / Medium', brand: 'Example Brand', category: 'Apparel/T-Shirts' } ], value: 69.98, currency: 'USD' }); ``` Minimal example: ```javascript theme={null} window._upstack('track', 'add_to_cart', { items: [{ id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 1 }], value: 34.99, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | ---------------------------------------------------------------------- | | items | array | Yes | Products added (see [Item Object](/pixel/standard-events#item-object)) | | value | number | Yes | Total value of items added | | currency | string | Yes | ISO 4217 currency code | ## When to Fire * Add-to-cart button click * Quantity increase in cart * "Buy Now" button click (before checkout) ## Related Events * [view\_content](/pixel/events/view-content) — View product before adding * [product\_removed\_from\_cart](/pixel/events/product-removed-from-cart) — When removing from cart * [view\_cart](/pixel/events/view-cart) — When viewing cart * [initiate\_checkout](/pixel/events/initiate-checkout) — When starting checkout # add_to_wishlist Event Source: https://docs.upstackdata.com/pixel/events/add-to-wishlist Track when a visitor adds a product to their wishlist Fires when a visitor adds a product to their wishlist or saves it for later. This indicates high purchase intent and is valuable for remarketing campaigns. <Note> **Shopify:** Manual implementation required. Requires a wishlist app or custom implementation. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'add_to_wishlist', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, brand: 'Example Brand' } ], value: 34.99, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | -------------------------- | | items | array | Yes | Products added to wishlist | | value | number | No | Product price | | currency | string | No | ISO 4217 currency code | ## When to Fire * Wishlist/favorite button click * Save for later action * Heart icon click on product ## Related Events * [view\_content](/pixel/events/view-content) — When viewing the product * [add\_to\_cart](/pixel/events/add-to-cart) — When adding to cart instead # book_call Event Source: https://docs.upstackdata.com/pixel/events/book-call Track when a user books a call or consultation Fires when a user books a call or consultation. This is a high-intent conversion event commonly used by B2B companies and service businesses. <Note> **Shopify:** Manual implementation required. Integrate with your scheduling tool (Calendly, etc.). </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'book_call', { callType: 'sales_consultation', value: 200.00, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | -------------------------------------------------------- | | callType | string | No | Type of call (e.g., `'sales_consultation'`, `'support'`) | | value | number | No | Estimated value of the booking | | currency | string | No | ISO 4217 currency code | ## When to Fire * Calendly booking confirmation * Meeting scheduler submission * Demo request completion ## Related Events * [schedule](/pixel/events/schedule) — For general appointment scheduling * [contact](/pixel/events/contact) — For contact form submissions * [lead](/pixel/events/lead) — For general lead capture # complete_registration Event Source: https://docs.upstackdata.com/pixel/events/complete-registration Track when a customer creates an account Fires when a customer creates an account. This is useful for tracking account signups and can be a valuable conversion event for platforms that prioritize registered users. <Note> **Shopify:** Manual implementation required. Not automatically tracked. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'complete_registration', { method: 'email', source: 'checkout_page' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------------------------------------------- | | method | string | No | Registration method (e.g., `'email'`, `'google'`, `'facebook'`) | | source | string | No | Where registration occurred | ## When to Fire * Account registration form submission * OAuth signup completion (Google, Facebook) * Post-purchase account creation ## Related Events * [sign\_up](/pixel/events/sign-up) — For simpler signup tracking * [login](/pixel/events/login) — When existing users log in * [lead](/pixel/events/lead) — For lead generation # contact Event Source: https://docs.upstackdata.com/pixel/events/contact Track when a user submits a contact form Fires when a user submits a contact form. This is useful for tracking customer inquiries and support requests as conversion events. <Note> **Shopify:** Manual implementation required. Integrate with your contact form. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'contact', { formName: 'product_inquiry', email: 'customer@example.com' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | -------------------- | | formName | string | No | Form or inquiry type | | email | string | No | Contact's email | ## When to Fire * Contact us form submission * Support request submission * Product inquiry ## Related Events * [lead](/pixel/events/lead) — For general lead capture * [book\_call](/pixel/events/book-call) — When scheduling a call # Custom Events Source: https://docs.upstackdata.com/pixel/events/custom-events Track custom events beyond standard taxonomy — wishlist adds, quiz completions, loyalty redemptions. Full pipeline support with identity resolution. Custom events let you track interactions that don't fit the standard event types. Wishlist adds, quiz completions, loyalty point redemptions, product configurator steps — any meaningful customer action can be captured as a custom event and forwarded through the Upstack pipeline. <Tip> Custom events flow through the same Capture → Resolve → Enrich → Activate pipeline as standard events. They receive identity resolution, enrichment, and destination forwarding automatically. </Tip> <Info> **Two types of custom events exist:** * **User-defined custom events** — Events you create and fire manually for business-specific interactions * **Upstack-generated events** — Events like `nc_purchase` and `rc_purchase` that Upstack fires automatically alongside standard events See [Upstack-native custom purchase events](#upstack-native-custom-purchase-events) for the automatically generated events. </Info> ## Naming Conventions Custom event names follow these rules: * Use **snake\_case**: `wishlist_add`, `quiz_complete`, `loyalty_redeem` * Keep names **descriptive and specific**: `product_config_saved` is better than `custom_action_1` * Avoid names that collide with standard events — `page_view`, `purchase`, etc. are reserved * Maximum length: **64 characters** * Allowed characters: letters, numbers, underscores <Warning> Event names are case-sensitive. `wishlist_add` and `WishlistAdd` are treated as separate events. Use snake\_case to match standard event conventions. </Warning> ## Tracking Custom Events Pass the event name and properties directly to the `track()` method: ```javascript theme={null} window._upstack('track', 'wishlist_add', { content_ids: ['8012345678'], content_name: 'Classic Cotton Tee', value: 34.99, currency: 'USD', wishlist_id: 'wl_abc123' }); ``` Upstack automatically attaches identity data (`user_data`), timestamps, and context fields. You only provide the event name and properties. For best compatibility with destinations, reuse standard property names (`content_ids`, `value`, `currency`, `content_name`) wherever they apply. ## How Custom Events Flow Through the Pipeline Custom events follow the exact same path as standard events: 1. **Capture** — The Upstack Pixel sends the event to the edge API. You can fire custom events using the JavaScript tracking API on your storefront. 2. **Resolve** — Upstack ID attaches identity data to the event. Session stitching and cross-device linking work the same as for standard events. 3. **Enrich** — UTM parameters, click IDs, and product catalog data are merged if applicable `content_ids` are present. 4. **Activate** — The event is forwarded to destinations that accept custom events. ## Destination Support Not all destinations handle custom events the same way: | Destination | Custom Event Support | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **Meta CAPI** | Supported as `Custom` event type. Meta receives the custom event name and all properties. Useful for building custom audiences and optimization. | | **TikTok Events API** | Supported. Custom events can be used for audience building but not standard optimization. | | **Klaviyo** | Fully supported. Custom events appear as distinct metric types in Klaviyo for flow triggers and segmentation. | | **GA4** | Supported. Custom event names map directly to GA4 custom events. Properties become event parameters. | | **Webhook** | Fully supported. The raw event payload is forwarded as-is. | <Note> Meta and TikTok ad optimization algorithms work best with standard events. Use custom events for audience building and measurement, but rely on standard events (Purchase, AddToCart, etc.) for campaign optimization signals. </Note> ## Firing Custom Events To fire a custom event from your storefront, use the Upstack JavaScript API: ```javascript theme={null} window._upstack('track', 'wishlist_add', { content_ids: ['8012345678'], content_name: 'Classic Cotton Tee', value: 34.99, currency: 'USD', wishlist_id: 'wl_abc123' }); ``` The Upstack Pixel handles serialization, batching, and delivery to the edge API. Identity fields (`user_data`) are attached automatically — you only need to provide the event name and `custom_data` properties. <Tip> For the full `track()` method signature with all 7 parameters including event deduplication, backdating, and `useBeacon` for page unload tracking, see the [JavaScript SDK Reference](/pixel/javascript-sdk#trackeventname-eventdata). </Tip> ## Upstack-native custom purchase events <Note> **Shopify-specific feature** — The `nc_purchase` and `rc_purchase` events are only available for Shopify stores using the Upstack Shopify app. They rely on Shopify order history to determine customer status. </Note> In addition to user-defined custom events, Upstack fires two built-in custom events that segment every order by customer status. They are sent alongside — not instead of — the standard `purchase` event. <AccordionGroup> <Accordion title="nc_purchase" icon="user-plus"> Fires when an order is placed by a customer with **no prior completed order history**. Used to optimize Meta campaigns toward new-customer acquisition instead of repeat buyers. **When it fires:** Order confirmation, when the customer has zero prior completed orders in Shopify. **Properties:** Same payload as the standard `Purchase` event (`value`, `currency`, `content_ids`, `order_id`, etc.) plus Upstack's identity enrichment (`em`, `ph`, `fn`, `ln`, `fbc`, `fbp`, `client_ip_address`, `client_user_agent`). See [Set up custom events → NC Purchase](/guides/facebook-ads/set-up-nc-and-rc-purchase-events-in-meta#new-customer-purchase-nc-purchase) for Meta setup steps. </Accordion> <Accordion title="rc_purchase" icon="rotate-right"> Fires when an order is placed by a customer with **one or more prior completed orders**. Used for retargeting audiences, retention measurement, and keeping prospecting campaigns honest about who they're actually converting. **When it fires:** Order confirmation, when the customer has at least one prior completed order in Shopify. **Properties:** Same payload as the standard `Purchase` event (`value`, `currency`, `content_ids`, `order_id`, etc.) plus Upstack's identity enrichment (`em`, `ph`, `fn`, `ln`, `fbc`, `fbp`, `client_ip_address`, `client_user_agent`). **What destinations receive (internal format):** ```json theme={null} // Internal format — Upstack fires this automatically, you don't write this code { "event_name": "rc_purchase", "event_time": "2026-02-18T14:35:20.000Z", "event_source_url": "https://example-store.com/thank-you", "user_data": { "em": "a1b2c3d4e5f6...hashed", "ph": "f6e5d4c3b2a1...hashed", "fbc": "fb.1.1708271400.AbC123", "fbp": "fb.1.1708271400.XyZ789", "external_id": "cust_12345" }, "custom_data": { "content_ids": ["8012345678"], "content_type": "product", "value": 42.00, "currency": "USD", "order_id": "#1087", "num_items": 1 } } ``` See [Set up custom events → RC Purchase](/guides/facebook-ads/set-up-nc-and-rc-purchase-events-in-meta#returning-customer-purchase-rc-purchase) for Meta setup steps. </Accordion> </AccordionGroup> <Note> The standard `purchase` event still fires for every order regardless of customer status. `nc_purchase` and `rc_purchase` fire *in addition to* `purchase`, not instead of it. </Note> ## AOV-Segmented Purchase Events Upstack automatically generates AOV (Average Order Value) segmented purchase events based on your store's order history. These events help you optimize campaigns toward high-value orders. <Warning> **Automatically generated.** You do not fire these events manually. Upstack analyzes each order against your store's historical AOV distribution and fires the appropriate event automatically. </Warning> <AccordionGroup> <Accordion title="high_aov_purchase" icon="arrow-up"> Fires when an order's value exceeds your store's historical average order value threshold. **When it fires:** Order confirmation, when `order_value > store_aov_threshold`. **Properties:** Same payload as the standard `Purchase` event. **Use case:** Optimize Meta campaigns toward customers who place high-value orders, not just any orders. </Accordion> <Accordion title="low_aov_purchase" icon="arrow-down"> Fires when an order's value falls below your store's historical average. **When it fires:** Order confirmation, when `order_value < store_aov_threshold`. **Properties:** Same payload as the standard `Purchase` event. **Use case:** Exclude from high-value optimization campaigns; analyze patterns in low-value conversions. </Accordion> <Accordion title="p70_aov_purchase" icon="chart-line"> Fires when an order's value exceeds the 70th percentile of your store's order values. **When it fires:** Order confirmation, when `order_value >= p70_threshold`. **Properties:** Same payload as the standard `Purchase` event. **Use case:** Target campaigns toward top 30% of orders by value. </Accordion> <Accordion title="p80_aov_purchase" icon="chart-line"> Fires when an order's value exceeds the 80th percentile of your store's order values. **When it fires:** Order confirmation, when `order_value >= p80_threshold`. **Properties:** Same payload as the standard `Purchase` event. **Use case:** Target campaigns toward top 20% of orders by value. </Accordion> <Accordion title="p90_aov_purchase" icon="chart-line"> Fires when an order's value exceeds the 90th percentile of your store's order values. **When it fires:** Order confirmation, when `order_value >= p90_threshold`. **Properties:** Same payload as the standard `Purchase` event. **Use case:** Target campaigns toward your highest-value orders (top 10%). </Accordion> </AccordionGroup> <Tip> Use percentile-based events (`p70_aov_purchase`, `p80_aov_purchase`, `p90_aov_purchase`) in Meta custom conversions to optimize toward different value tiers. This is more precise than the binary `high_aov_purchase`/`low_aov_purchase` split. </Tip> ## Customer Behavior Purchase Events Upstack automatically segments purchases by customer behavior patterns. <AccordionGroup> <Accordion title="upsell_purchase" icon="arrow-up-right-dots"> Fires when an order contains upsell or cross-sell items that were added after the initial product selection. **When it fires:** Order confirmation, when upsell/cross-sell items are detected in the cart. **Properties:** Same payload as the standard `Purchase` event, plus identification of which items were upsells. **Use case:** Measure upsell effectiveness; optimize campaigns toward customers likely to accept upsells. </Accordion> <Accordion title="lapsed_purchase" icon="clock-rotate-left"> Fires when a previously inactive customer returns and makes a purchase. **When it fires:** Order confirmation, when the customer has been inactive for a defined period (typically 90+ days since last order). **Properties:** Same payload as the standard `Purchase` event. **Use case:** Measure win-back campaign effectiveness; build audiences of re-engaged customers. </Accordion> </AccordionGroup> ## Related Documentation <CardGroup> <Card title="Standard Events" icon="list-check" href="/pixel/standard-events"> Review the full list of built-in events before creating a custom event. </Card> <Card title="JavaScript SDK" icon="code" href="/pixel/javascript-sdk#trackeventname-eventdata"> Full track() method reference with all 7 parameters. </Card> <Card title="Properties & Context" icon="table" href="/pixel/properties"> See all available property fields you can include in custom\_data. </Card> <Card title="Shopify Automatic Tracking" icon="shopify" href="/sources/shopify-automatic-tracking"> Events automatically tracked on Shopify stores. </Card> </CardGroup> # initiate_checkout Event Source: https://docs.upstackdata.com/pixel/events/initiate-checkout Track when a visitor starts the checkout process Fires when a visitor starts the checkout process. This event marks the transition from browsing to buying and is critical for checkout funnel analysis. <Note> **Shopify:** Automatically tracked when customers click the checkout button or land on the checkout page. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'initiate_checkout', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2 }, { id: 'SKU_67890', name: 'Running Socks', price: 14.99, quantity: 1 } ], value: 84.97, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | ---------------------- | | items | array | Yes | Products in checkout | | value | number | Yes | Cart subtotal | | currency | string | Yes | ISO 4217 currency code | ## When to Fire * Checkout button click * Checkout page load * Express checkout initiation (Shop Pay, Apple Pay) ## Related Events * [view\_cart](/pixel/events/view-cart) — Before starting checkout * [add\_shipping\_info](/pixel/events/add-shipping-info) — After entering shipping details * [add\_payment\_info](/pixel/events/add-payment-info) — After entering payment details * [purchase](/pixel/events/purchase) — When order is completed # lead Event Source: https://docs.upstackdata.com/pixel/events/lead Track when a visitor submits a lead form Fires when a visitor submits a lead form. This is the primary conversion event for lead generation businesses and is used to track form submissions, newsletter signups, and inquiries. <Note> **Shopify:** Tracked via form hooks when using compatible form/popup apps. Manual implementation may be required for custom forms. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'lead', { source: 'contact_form', email: 'prospect@example.com', value: 150.00, currency: 'USD' }); ``` Newsletter signup: ```javascript theme={null} window._upstack('track', 'lead', { source: 'newsletter_popup', email: 'subscriber@example.com' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------- | | source | string | No | Form or campaign identifier | | email | string | No | Lead's email address | | value | number | No | Estimated lead value | | currency | string | No | ISO 4217 currency code | ## When to Fire * Contact form submission * Newsletter signup * Quote request submission * Product inquiry ## Related Events * [subscribe](/pixel/events/subscribe) — For marketing opt-ins specifically * [contact](/pixel/events/contact) — For contact form submissions * [complete\_registration](/pixel/events/complete-registration) — For account signups # login Event Source: https://docs.upstackdata.com/pixel/events/login Track when a user logs into their account Fires when a user logs into their account. This helps track returning user engagement and can be used to build audience segments of active customers. <Note> **Shopify:** Manual implementation required. Not automatically tracked. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'login', { method: 'email' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | ---------------------------------------------------------------- | | method | string | No | Login method (`'email'`, `'google'`, `'facebook'`, `'shop_pay'`) | ## When to Fire * Successful login form submission * OAuth login completion * Automatic re-authentication ## Related Events * [sign\_up](/pixel/events/sign-up) — When new users create accounts * [complete\_registration](/pixel/events/complete-registration) — For registration flows # page_view Event Source: https://docs.upstackdata.com/pixel/events/page-view Track when a visitor loads a page on your site Fires when a visitor loads a page. This is the foundation of all analytics — every page load should trigger this event. <Note> **Shopify:** Automatically tracked by the Upstack Pixel on all page loads. </Note> ## JavaScript ```javascript theme={null} window._upstack('page'); ``` With custom properties: ```javascript theme={null} window._upstack('page', { pageCategory: 'product', collectionHandle: 'summer-2026' }); ``` ## Properties | Property | Type | Required | Description | | ---------------- | ------ | -------- | ------------------------------------------------------- | | pageCategory | string | No | Page type (e.g., `'product'`, `'collection'`, `'blog'`) | | collectionHandle | string | No | Collection identifier for collection pages | ## Auto-Captured The SDK automatically captures `page_url`, `page_title`, `page_referrer`, and `page_path`. ## When to Fire * On initial page load * On SPA route changes * After dynamic content loads (infinite scroll) ## Related Events * [view\_content](/pixel/events/view-content) — When viewing a specific product * [view\_category](/pixel/events/view-category) — When viewing a collection page * [search](/pixel/events/search) — When viewing search results # product_removed_from_cart Event Source: https://docs.upstackdata.com/pixel/events/product-removed-from-cart Track when a visitor removes an item from their cart Fires when a visitor removes an item from their cart. This helps identify cart friction points and understand why shoppers don't complete purchases. <Note> **Shopify:** Automatically tracked when items are removed from cart. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'product_removed_from_cart', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 1 } ], value: 34.99, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | ------------------------------------------------------------------------ | | items | array | Yes | Products removed (see [Item Object](/pixel/standard-events#item-object)) | | value | number | No | Value of removed items | | currency | string | No | ISO 4217 currency code | ## When to Fire * Remove button click * Quantity decrease to zero * Clear cart action ## Related Events * [add\_to\_cart](/pixel/events/add-to-cart) — When adding items to cart * [view\_cart](/pixel/events/view-cart) — When viewing cart contents # Address Properties Source: https://docs.upstackdata.com/pixel/events/properties/address Shipping and billing address fields — address1, city, province, country, zip for checkout and purchase events. For shipping and billing information. Pass as an array of address objects. ## Address Array Structure ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 149.99, currency: 'USD', addresses: [ { firstName: 'Jane', lastName: 'Smith', address1: '123 Main St', address2: 'Apt 4B', city: 'San Francisco', province: 'California', provinceCode: 'CA', country: 'US', zip: '94102' } ], items: [/* ... */] }); ``` ## Address Properties | Property | Type | Description | | -------------- | ------ | -------------------------------------------------------- | | `firstName` | string | First name | | `lastName` | string | Last name | | `company` | string | Company or organization name | | `address1` | string | Street address line 1 | | `address2` | string | Street address line 2 | | `city` | string | City | | `province` | string | State or province | | `provinceCode` | string | State/province code (e.g., `CA`, `NY`, `ON`) | | `country` | string | Country name | | `countryCode` | string | ISO 3166-1 alpha-2 country code (e.g., `US`, `CA`, `GB`) | | `zip` | string | ZIP or postal code | ## Privacy Address fields (city, zip, country code, state code) are normalized and SHA-256 hashed before being sent to advertising destinations. <Note> Use `province` for the full state/province name and `provinceCode` for the abbreviated code. Use `zip` for postal codes. </Note> # Auto-Captured Fields Source: https://docs.upstackdata.com/pixel/events/properties/auto-captured Fields captured automatically by the Upstack Pixel — click IDs, UTMs, device info, geo, and context. Don't set these manually. These fields are captured automatically by the Upstack Pixel and edge API. **Do not include them in your `track()` calls.** ## Click IDs Click IDs are captured automatically from URL parameters and browser cookies. Each platform's click ID is stored along with a timestamp indicating when it was collected. ### Meta (Facebook/Instagram) | Field | Source | Description | | -------- | ------------- | ------------------------------------------------------------ | | `fbc` | `_fbc` cookie | Meta click ID cookie (contains `fbclid` from ad click URL) | | `fbp` | `_fbp` cookie | Meta browser ID (first-party cookie for user identification) | | `fbclid` | URL parameter | Meta click ID from ad click URL (raw parameter value) | ### Google Ads | Field | Source | Description | | -------- | ------------- | ---------------------------------------------------- | | `gclid` | URL parameter | Google click ID (standard web campaigns) | | `gbraid` | URL parameter | Google click ID for iOS App campaigns (privacy-safe) | | `wbraid` | URL parameter | Google click ID for web-to-app measurement | ### TikTok | Field | Source | Description | | -------- | ------------- | --------------------------------------------------- | | `ttclid` | URL parameter | TikTok click ID from ad click URL | | `ttp` | `_ttp` cookie | TikTok browser ID cookie (first-party pixel cookie) | ### Snapchat | Field | Source | Description | | ------------------ | -------------- | ------------------------------------- | | `snapchatSCCid` | URL parameter | Snapchat click ID (`ScCid` parameter) | | `snapchatSCCookie` | `_scid` cookie | Snapchat browser ID cookie | ### Pinterest | Field | Source | Description | | --------------- | -------------- | ------------------------------------------ | | `pinterestEpik` | `_epik` cookie | Pinterest click ID cookie (Enhanced Match) | ### AppLovin | Field | Source | Description | | --------------- | ------------- | ---------------------------------------------- | | `applovinAxwrt` | URL parameter | AppLovin attribution token (`axwrt` parameter) | | `aleid` | URL parameter | AppLovin click ID | ### Klaviyo | Field | Source | Description | | ------------ | ------------- | --------------------------------- | | `kx` | URL parameter | Klaviyo click ID from email links | | `klaviyoCid` | URL parameter | Klaviyo campaign ID | ### Sendlane | Field | Source | Description | | ------------- | ------------- | ---------------------------------- | | `sendlaneCid` | URL parameter | Sendlane click ID from email links | ### Omnisend | Field | Source | Description | | ------------- | ------------- | ---------------------------------- | | `omnisendCid` | URL parameter | Omnisend click ID from email links | ### Reddit | Field | Source | Description | | ------------ | ------------------ | ------------------------------ | | `redditCid` | URL parameter | Reddit click ID from ad clicks | | `redditUuid` | `_rdt_uuid` cookie | Reddit browser ID cookie | ### Taboola | Field | Source | Description | | ------- | ------------- | -------------------------------------- | | `tblci` | URL parameter | Taboola click ID from native ad clicks | ### Outbrain | Field | Source | Description | | -------- | ------------- | --------------------------------------- | | `obclid` | URL parameter | Outbrain click ID from native ad clicks | ### NewsBreak | Field | Source | Description | | -------- | ------------- | --------------------------------- | | `nbclid` | URL parameter | NewsBreak click ID from ad clicks | ### LinkedIn | Field | Source | Description | | --------- | ------------- | ----------------------------------------------------------- | | `liFatId` | URL parameter | LinkedIn First-Party Ad Tracking ID (`li_fat_id` parameter) | ### Microsoft Advertising (Bing) | Field | Source | Description | | --------- | ------------- | ------------------------------ | | `msclkid` | URL parameter | Microsoft Advertising click ID | *** ## UTM Parameters Captured automatically from URL query string parameters: | Field | Description | | -------------- | --------------------------------------------------------- | | `utm_source` | Traffic source (e.g., `google`, `facebook`, `newsletter`) | | `utm_medium` | Marketing medium (e.g., `cpc`, `email`, `social`) | | `utm_campaign` | Campaign name or identifier | | `utm_content` | Ad or link variant for A/B testing | | `utm_term` | Paid search keyword | *** ## Page Context Captured automatically from the browser on every event: | Field | Description | | ---------- | ---------------------------------------------- | | `host` | Hostname of the page (e.g., `www.example.com`) | | `path` | URL path (e.g., `/products/widget`) | | `referrer` | Full referrer URL | | `search` | Query string (e.g., `?utm_source=google`) | | `title` | Page title from `document.title` | | `url` | Full page URL where the event fired | *** ## Viewport & Device Captured from the browser at page load: | Field | Description | | ------------------- | ------------------------------------------------------------ | | `viewportWidth` | Browser viewport width in CSS pixels | | `viewportHeight` | Browser viewport height in CSS pixels | | `pageHeight` | Total scrollable page height in CSS pixels | | `devicePixelRatio` | Device pixel ratio (e.g., `2` for Retina displays) | | `device_type` | Detected device type: `"mobile"`, `"desktop"`, or `"tablet"` | | `client_user_agent` | Browser user agent string | *** ## Browser Settings | Field | Description | | ----------------- | ------------------------------------------- | | `locale` | Browser locale (e.g., `en-US`) | | `timezone` | Browser timezone (e.g., `America/New_York`) | | `adBlockDetected` | `true` if an ad blocker was detected | *** ## Geographic Data (from Cloudflare) Captured server-side from Cloudflare's edge network: | Field | Description | | ------------- | -------------------------------------------------- | | `country` | ISO 3166-1 alpha-2 country code (e.g., `US`, `GB`) | | `region` | State/province name (e.g., `Texas`, `California`) | | `regionCode` | ISO 3166-2 region code (e.g., `TX`, `CA`) | | `city` | City name (e.g., `Austin`, `San Francisco`) | | `postalCode` | Postal/zip code (e.g., `78701`) | | `latitude` | Latitude coordinate | | `longitude` | Longitude coordinate | | `continent` | Continent code (e.g., `NA`, `EU`, `AS`) | | `isEUCountry` | `"1"` if the country is in the EU | | `timezone` | IANA timezone (e.g., `America/Chicago`) | *** ## Network Info (from Cloudflare) | Field | Description | | ------------------- | ----------------------------------------------------- | | `asn` | Autonomous System Number | | `asOrganization` | Organization that owns the ASN (e.g., `Google Cloud`) | | `isBot` | `true` if Cloudflare detects the request as a bot | | `client_ip_address` | Visitor's IP address (captured server-side) | *** ## Session & Event Metadata | Field | Description | | ------------------ | --------------------------------- | | `event_id` | Unique event ID for deduplication | | `event_time` | Timestamp (ISO 8601, UTC) | | `event_source_url` | Full URL where the event fired | | `session_id` | Upstack session identifier | | `pixel_id` | Your Upstack Pixel ID | # Checkout & Pricing Properties Source: https://docs.upstackdata.com/pixel/events/properties/checkout Properties for checkout and purchase events — pricing breakdown, payment methods, and shipping details. Checkout and pricing properties provide detailed order information for purchase and checkout events. ## Properties <CardGroup> <Card title="subtotalPrice" icon="receipt" href="/pixel/events/properties/subtotal-price"> Subtotal before tax/shipping. </Card> <Card title="tax" icon="percent" href="/pixel/events/properties/tax"> Tax amount applied. </Card> <Card title="shipping" icon="truck" href="/pixel/events/properties/shipping"> Shipping cost. </Card> <Card title="discount" icon="tag" href="/pixel/events/properties/discount"> Total discount amount. </Card> <Card title="coupon" icon="ticket" href="/pixel/events/properties/coupon"> Promo code used. </Card> <Card title="paymentType" icon="credit-card" href="/pixel/events/properties/payment-type"> Payment method. </Card> <Card title="shippingTier" icon="gauge-high" href="/pixel/events/properties/shipping-tier"> Shipping speed selected. </Card> </CardGroup> ## Quick Reference | Property | Type | Description | | --------------- | ------ | -------------------------------- | | `subtotalPrice` | number | Subtotal before tax and shipping | | `tax` | number | Tax amount | | `shipping` | number | Shipping cost | | `discount` | number | Total discount amount applied | | `coupon` | string | Coupon or promo code used | | `paymentType` | string | Payment method used | | `shippingTier` | string | Shipping tier selected | | `cartId` | string | Shopping cart identifier | | `affiliation` | string | Store or affiliate name | ## Example ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 134.99, currency: 'USD', subtotalPrice: 149.99, tax: 12.00, shipping: 8.00, discount: 35.00, coupon: 'SAVE25', paymentType: 'credit_card', shippingTier: 'express', items: [/* ... */] }); ``` # Complex Properties Source: https://docs.upstackdata.com/pixel/events/properties/complex Advanced property types — the items array for product data, SaaS properties for B2B tracking, and auto-captured context fields. Complex properties handle structured data, B2B/SaaS tracking, and automatically captured context. These properties support advanced use cases beyond simple key-value pairs. ## Properties <CardGroup> <Card title="Items Array" icon="list" href="/pixel/events/properties/items"> Product data for e-commerce events — id, name, price, quantity, brand, category. </Card> <Card title="SaaS Properties" icon="building" href="/pixel/events/properties/saas"> B2B/SaaS tracking — accounts, subscriptions, trials, MRR, seats. </Card> <Card title="Auto-Captured Fields" icon="wand-magic-sparkles" href="/pixel/events/properties/auto-captured"> Click IDs, UTMs, device info, geo — captured automatically. </Card> </CardGroup> ## Quick Reference | Property Type | Description | When to Use | | ------------------- | -------------------------------------------- | -------------------------------------------------------------- | | **items** | Array of product objects | All e-commerce events (view\_content, add\_to\_cart, purchase) | | **SaaS properties** | Account, subscription, trial, payment fields | B2B/SaaS event tracking | | **Auto-captured** | Click IDs, UTMs, device, geo | Automatically captured — do not set manually | ## Items Array The `items` array is required for all product-related events. Each item contains product details: ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 149.99, currency: 'USD', items: [ { id: 'SKU-001', name: 'Running Shoes', price: 89.99, quantity: 1, brand: 'Nike', category: 'Footwear', variant: 'Blue / Size 10' } ] }); ``` <Card title="Full Items Reference" icon="arrow-right" href="/pixel/events/properties/items"> See the complete items array specification with all supported fields. </Card> ## SaaS Properties For B2B and subscription-based businesses tracking accounts, subscriptions, trials, and revenue: ```javascript theme={null} window._upstack('track', 'subscription_started', { accountId: 'acct_abc123', subscriptionId: 'sub_def456', planId: 'plan_pro_monthly', planName: 'Pro Plan', mrr: 9900, billingInterval: 'month' }); ``` <Card title="Full SaaS Reference" icon="arrow-right" href="/pixel/events/properties/saas"> See all SaaS properties including trial, payment, and seat tracking fields. </Card> ## Auto-Captured Fields <Info> **Do not include auto-captured fields in your `track()` calls.** The Upstack Pixel and edge API capture these automatically. </Info> Auto-captured fields include: | Category | Examples | | ------------------ | --------------------------------------------------------------------- | | **Click IDs** | `fbclid`, `gclid`, `ttclid`, `msclkid`, `fbc`, `fbp`, `ttp` | | **UTM Parameters** | `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term` | | **Page Context** | `url`, `path`, `referrer`, `title`, `host` | | **Device** | `device_type`, `viewportWidth`, `viewportHeight`, `client_user_agent` | | **Geographic** | `country`, `region`, `city`, `postalCode`, `timezone` | | **Session** | `session_id`, `event_id`, `event_time`, `pixel_id` | <Card title="Full Auto-Captured Reference" icon="arrow-right" href="/pixel/events/properties/auto-captured"> See all click IDs (Meta, Google, TikTok, Pinterest, Snapchat, AppLovin, LinkedIn, Microsoft, Reddit, and more), UTM parameters, and context fields. </Card> # Content Properties Source: https://docs.upstackdata.com/pixel/events/properties/content Properties for content-related events — primarily search queries. Content properties are used for search and content interaction events. ## User-Input Properties | Property | Type | Description | Events | | ------------ | ------ | ---------------------------- | ------ | | `searchTerm` | string | Search query entered by user | search | <CardGroup> <Card title="searchTerm" icon="magnifying-glass" href="/pixel/events/properties/search-term"> Search query entered by the user. </Card> </CardGroup> ## Example ```javascript theme={null} window._upstack('track', 'search', { searchTerm: 'blue running shoes', items: [ { id: 'SKU-001', name: 'Running Shoes', price: 99.00 }, { id: 'SKU-002', name: 'Athletic Socks', price: 12.00 } ] }); ``` ## Auto-Derived Fields The following fields are **automatically computed** from your `items` array during event forwarding. Do not pass them directly: | Field | Derived From | Description | | -------------- | ------------------------- | -------------------------------- | | `content_ids` | `items[].id` | Array of product IDs | | `content_name` | `items[0].name` | Name of first product | | `content_type` | Inferred | `"product"` or `"product_group"` | | `num_items` | Sum of `items[].quantity` | Total item count | <Note> For product data, always use the `items` array. The platform extracts and formats the necessary fields for each advertising destination. </Note> ## Related Properties <CardGroup> <Card title="Items Array" icon="list" href="/pixel/events/properties/items"> Pass all product data here — content fields are derived automatically. </Card> <Card title="content_ids" icon="list" href="/pixel/events/properties/content-ids"> Learn how product IDs are extracted from items. </Card> </CardGroup> # content_ids Source: https://docs.upstackdata.com/pixel/events/properties/content-ids Auto-derived array of product IDs sent to advertising platforms. <Warning> `content_ids` is **not** a user-input property. It is automatically derived from your `items` array during event forwarding. </Warning> ## How It Works When you send events with an `items` array, the platform extracts product IDs and forwards them as `content_ids` to advertising platforms (Meta, TikTok, etc.). **Do this:** ```javascript theme={null} window._upstack('track', 'view_content', { items: [ { id: 'SKU-001', name: 'Running Shoes', price: 99.00 }, { id: 'SKU-002', name: 'Athletic Socks', price: 12.00 } ] }); // → Forwards content_ids: ['SKU-001', 'SKU-002'] to destinations ``` **Not this:** ```javascript theme={null} // ❌ Don't pass content_ids directly window._upstack('track', 'view_content', { content_ids: ['SKU-001', 'SKU-002'] }); ``` ## Derivation Logic The platform extracts IDs from the `items` array using this priority: 1. `item.id` (preferred) 2. `item.item_id` 3. `item.product_id` 4. `item.sku` 5. `item.variant_id` ## Related Properties <CardGroup> <Card title="Items Array" icon="list" href="/pixel/events/properties/items"> Pass product data here — IDs are extracted automatically. </Card> <Card title="searchTerm" icon="magnifying-glass" href="/pixel/events/properties/search-term"> User-input property for search queries. </Card> </CardGroup> # Core Event Properties Source: https://docs.upstackdata.com/pixel/events/properties/core Essential properties for tracking events — value, currency, transactionId, and orderName. Core properties are the foundational fields used across most tracking events. These are typically required or strongly recommended for proper attribution and reporting. ## Properties <CardGroup> <Card title="value" icon="coins" href="/pixel/events/properties/value"> Monetary value of the event. </Card> <Card title="currency" icon="dollar-sign" href="/pixel/events/properties/currency"> ISO 4217 currency code. </Card> <Card title="transactionId" icon="fingerprint" href="/pixel/events/properties/transaction-id"> Unique order identifier. </Card> <Card title="orderName" icon="hashtag" href="/pixel/events/properties/order-name"> Human-readable order number. </Card> </CardGroup> ## Quick Reference | Property | Type | Required | Description | | --------------- | ------ | --------------------------------- | ---------------------------------------------- | | `value` | number | Yes for purchase, lead, subscribe | Monetary value of the event | | `currency` | string | Yes (when value is set) | ISO 4217 currency code (USD, EUR, GBP) | | `transactionId` | string | Yes for purchase/refund | Unique order identifier | | `orderName` | string | No | Human-readable order number shown to customers | ## Example ```javascript theme={null} window._upstack('track', 'purchase', { value: 149.99, currency: 'USD', transactionId: 'ORD-2026-001', orderName: '#1042', items: [/* ... */] }); ``` <Note> For Purchase events, `value` should match the order total you want reported to ad platforms. </Note> # coupon Source: https://docs.upstackdata.com/pixel/events/properties/coupon Coupon or promo code used. Coupon or promo code used. ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 134.99, currency: 'USD', coupon: 'SAVE25' }); ``` | Type | Required | Events | | ------ | -------- | ------------------------------------------- | | string | No | purchase, initiate\_checkout, add\_to\_cart | ## Related Properties <CardGroup> <Card title="discount" icon="tag" href="/pixel/events/properties/discount"> Discount amount applied. </Card> <Card title="promotionId" icon="bullhorn" href="/pixel/events/properties/promotion-id"> Promotion identifier. </Card> </CardGroup> # creativeName Source: https://docs.upstackdata.com/pixel/events/properties/creative-name Creative or ad variant name for promotion tracking. Creative or ad variant name for promotion tracking. ```javascript theme={null} window._upstack('track', 'view_content', { items: [{ id: 'SKU_001', name: 'Running Shoes', price: 89.99 }], value: 89.99, currency: 'USD', creativeName: 'hero_banner_v2' }); ``` | Type | Required | Events | | ------ | -------- | -------------------------------------- | | string | No | view\_content, add\_to\_cart, purchase | <Tip> Use `creativeName` and `creativeSlot` to track which on-site promotions drive the most conversions. </Tip> ## Related Properties <CardGroup> <Card title="creativeSlot" icon="table-cells" href="/pixel/events/properties/creative-slot"> Placement position on page. </Card> <Card title="promotionId" icon="bullhorn" href="/pixel/events/properties/promotion-id"> Promotion identifier. </Card> </CardGroup> # creativeSlot Source: https://docs.upstackdata.com/pixel/events/properties/creative-slot Creative placement position on the page. Creative placement position on the page. ```javascript theme={null} window._upstack('track', 'view_content', { items: [{ id: 'SKU_001', name: 'Running Shoes', price: 89.99 }], value: 89.99, currency: 'USD', creativeSlot: 'homepage_hero' }); ``` | Type | Required | Events | | ------ | -------- | -------------------------------------- | | string | No | view\_content, add\_to\_cart, purchase | ## Common Values | Value | Description | | ------------------------- | ----------------------------- | | `hero` | Hero banner section | | `sidebar` | Sidebar placement | | `footer` | Footer area | | `homepage_hero` | Homepage hero banner | | `product_recommendations` | Product recommendation widget | | `cart_upsell` | Cart page upsell | ## Related Properties <CardGroup> <Card title="creativeName" icon="palette" href="/pixel/events/properties/creative-name"> Creative variant name. </Card> <Card title="locationId" icon="location-dot" href="/pixel/events/properties/location-id"> Store or location identifier. </Card> </CardGroup> # currency Source: https://docs.upstackdata.com/pixel/events/properties/currency ISO 4217 currency code. Required whenever you include value. ISO 4217 currency code. Required whenever you include `value`. ```javascript theme={null} window._upstack('track', 'add_to_cart', { value: 49.99, currency: 'USD' // USD, EUR, GBP, CAD, etc. }); ``` | Type | Required | Events | | ------ | ----------------------- | ---------------------- | | string | Yes (when value is set) | Any event with `value` | ## Common Currency Codes | Code | Currency | | ----- | ----------------- | | `USD` | US Dollar | | `EUR` | Euro | | `GBP` | British Pound | | `CAD` | Canadian Dollar | | `AUD` | Australian Dollar | | `JPY` | Japanese Yen | ## Related Properties <CardGroup> <Card title="value" icon="coins" href="/pixel/events/properties/value"> The monetary value of the event. </Card> </CardGroup> # Customer Properties Source: https://docs.upstackdata.com/pixel/events/properties/customer Properties for identifying customers — email, phone, name, and address fields for identity resolution. Customer properties are used for identity resolution and destination matching. Including these fields significantly improves match quality on advertising platforms. ## Properties <CardGroup> <Card title="email" icon="envelope" href="/pixel/events/properties/email"> Primary cross-device identifier. </Card> <Card title="phone" icon="phone" href="/pixel/events/properties/phone"> E.164 format phone number. </Card> <Card title="firstName / lastName" icon="user" href="/pixel/events/properties/name"> Customer name fields. </Card> <Card title="Address Fields" icon="location-dot" href="/pixel/events/properties/address"> Shipping and billing address. </Card> </CardGroup> ## Quick Reference | Property | Type | Required | Description | | ----------- | ------ | ----------- | --------------------------------------- | | `email` | string | Recommended | Customer's email address | | `phone` | string | No | Phone number (E.164 format recommended) | | `firstName` | string | No | Customer's first name | | `lastName` | string | No | Customer's last name | ## Example ```javascript theme={null} window._upstack('track', 'lead', { email: 'customer@example.com', phone: '+15551234567', firstName: 'Jane', lastName: 'Smith', value: 0, currency: 'USD' }); ``` <Tip> Events with email typically score EMQ 8-9 on Meta. Events with only IP address score 2-3. </Tip> ## Privacy All customer PII (email, phone, name) is normalized and SHA-256 hashed before being sent to advertising destinations. Raw values are never stored in destination platforms. # discount Source: https://docs.upstackdata.com/pixel/events/properties/discount Total discount amount applied to the order. Total discount amount applied to the order. ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 134.99, currency: 'USD', discount: 35.00 }); ``` | Type | Required | Events | | ------ | -------- | ------------------------------------------- | | number | No | purchase, initiate\_checkout, add\_to\_cart | ## Related Properties <CardGroup> <Card title="coupon" icon="ticket" href="/pixel/events/properties/coupon"> Coupon code used. </Card> <Card title="subtotalPrice" icon="receipt" href="/pixel/events/properties/subtotal-price"> Subtotal before discounts. </Card> </CardGroup> # email Source: https://docs.upstackdata.com/pixel/events/properties/email Customer's email address. Primary identifier for cross-device tracking. Customer's email address. Primary identifier for cross-device tracking and destination matching. ```javascript theme={null} // With a lead form submission window._upstack('track', 'lead', { email: 'customer@example.com', value: 0, currency: 'USD' }); // With a purchase window._upstack('track', 'purchase', { email: 'customer@example.com', transactionId: 'ORD-123', value: 99.99, currency: 'USD' }); ``` | Type | Required | Events | | ------ | ----------- | ----------------------------------- | | string | Recommended | All events (improves match quality) | ## Privacy Email addresses are normalized (lowercase, trimmed) and SHA-256 hashed before being sent to advertising destinations. Raw emails are never stored in destination platforms. <Tip> Events with email typically score EMQ 8-9 on Meta. Events with only IP address score 2-3. </Tip> ## Related Properties <CardGroup> <Card title="phone" icon="phone" href="/pixel/events/properties/phone"> Customer phone number for improved matching. </Card> <Card title="firstName / lastName" icon="user" href="/pixel/events/properties/name"> Customer name for identity resolution. </Card> </CardGroup> # Event Properties Reference Source: https://docs.upstackdata.com/pixel/events/properties/index Complete reference for all Upstack Data event properties — items array, customer data, checkout fields, and auto-captured context like click IDs and UTMs. Properties are the data you send with each tracking event. This page documents all available properties and shows how to use them in JavaScript. <Note> Use **camelCase** when sending properties — the platform automatically converts to the format each destination requires. </Note> ## Full Event Structure A complete tracking event contains the event name, timestamp, user data, custom data, and automatically captured context. ```javascript theme={null} window._upstack('track', 'purchase', { // Core identifiers transactionId: 'ORD-2026-001', orderName: '#1042', // Monetary values value: 134.99, currency: 'USD', subtotalPrice: 149.99, tax: 12.00, shipping: 8.00, discount: 35.00, // Customer data (improves match quality) email: 'customer@example.com', phone: '+15551234567', firstName: 'Jane', lastName: 'Smith', // Product items items: [ { id: 'SKU-001', name: 'Running Shoes', price: 89.99, quantity: 1, brand: 'Nike', category: 'Footwear' } ], // Optional checkout details coupon: 'SAVE25', paymentType: 'credit_card', shippingTier: 'express' }); // The platform automatically captures additional context: // - Click IDs (fbclid, gclid, ttclid, etc.) // - UTM parameters (utm_source, utm_medium, etc.) // - Device and browser information // - Geographic data // - Session and identity information ``` ## Core Properties These properties work with most events. <CardGroup> <Card title="value" icon="coins" href="/pixel/events/properties/value"> Monetary value of the event. Required for purchase, lead, subscribe. </Card> <Card title="currency" icon="dollar-sign" href="/pixel/events/properties/currency"> ISO 4217 currency code. Required with value. </Card> <Card title="transactionId" icon="fingerprint" href="/pixel/events/properties/transaction-id"> Unique order identifier. Required for purchase/refund. </Card> <Card title="orderName" icon="hashtag" href="/pixel/events/properties/order-name"> Human-readable order number shown to customers. </Card> </CardGroup> ### Quick Reference | Property | Type | Required | Events | | ---------------------------------------------------------- | ------ | --------------------------------- | ------------------------------------------------------------------------------------------- | | [`value`](/pixel/events/properties/value) | number | Yes for purchase, lead, subscribe | purchase, add\_to\_cart, view\_content, initiate\_checkout, lead, subscribe, trial\_started | | [`currency`](/pixel/events/properties/currency) | string | Yes (when value is set) | Any event with `value` | | [`transactionId`](/pixel/events/properties/transaction-id) | string | Yes for purchase/refund | purchase, refund | | `orderId` | string | No | purchase, refund | | [`orderName`](/pixel/events/properties/order-name) | string | No | purchase | <Info> `orderId` and `transactionId` are interchangeable — use whichever fits your system. If both are provided, `transactionId` takes precedence. </Info> ```javascript theme={null} window._upstack('track', 'purchase', { value: 99.99, currency: 'USD', transactionId: 'ORD-2026-001', orderName: '#1042' }); ``` *** ## Customer Properties Properties for identifying customers. Used for identity resolution and destination matching. <CardGroup> <Card title="email" icon="envelope" href="/pixel/events/properties/email"> Primary identifier for cross-device tracking. </Card> <Card title="phone" icon="phone" href="/pixel/events/properties/phone"> E.164 format for improved matching. </Card> <Card title="firstName / lastName" icon="user" href="/pixel/events/properties/name"> Customer name for identity resolution. </Card> <Card title="Address Fields" icon="location-dot" href="/pixel/events/properties/address"> Shipping and billing address properties. </Card> </CardGroup> ### Quick Reference | Property | Type | Required | Events | | -------------------------------------------- | ------ | ----------- | ----------------------------------- | | [`email`](/pixel/events/properties/email) | string | Recommended | All events (improves match quality) | | [`phone`](/pixel/events/properties/phone) | string | No | All events (improves match quality) | | [`firstName`](/pixel/events/properties/name) | string | No | All events | | [`lastName`](/pixel/events/properties/name) | string | No | All events | <Tip> Events with email typically score EMQ 8-9 on Meta. Events with only IP address score 2-3. </Tip> ```javascript theme={null} window._upstack('track', 'lead', { email: 'customer@example.com', phone: '+15551234567', firstName: 'Jane', lastName: 'Smith' }); ``` *** ## Checkout & Pricing Properties Additional properties for checkout and purchase events. <CardGroup> <Card title="subtotalPrice" icon="receipt" href="/pixel/events/properties/subtotal-price"> Subtotal before tax/shipping. </Card> <Card title="tax" icon="percent" href="/pixel/events/properties/tax"> Tax amount applied. </Card> <Card title="shipping" icon="truck" href="/pixel/events/properties/shipping"> Shipping cost. </Card> <Card title="discount" icon="tag" href="/pixel/events/properties/discount"> Total discount amount. </Card> <Card title="coupon" icon="ticket" href="/pixel/events/properties/coupon"> Promo code used. </Card> <Card title="paymentType" icon="credit-card" href="/pixel/events/properties/payment-type"> Payment method used. </Card> <Card title="shippingTier" icon="gauge-high" href="/pixel/events/properties/shipping-tier"> Shipping speed selected. </Card> </CardGroup> ### Quick Reference | Property | Type | Description | | ---------------------------------------------------------- | --------- | ---------------------------------------------------------- | | [`subtotalPrice`](/pixel/events/properties/subtotal-price) | number | Subtotal before tax and shipping | | `price` | number | Base price (distinct from `value` which is the total) | | [`tax`](/pixel/events/properties/tax) | number | Tax amount | | [`shipping`](/pixel/events/properties/shipping) | number | Shipping cost | | [`discount`](/pixel/events/properties/discount) | number | Total discount amount applied | | [`coupon`](/pixel/events/properties/coupon) | string | Coupon or promo code used | | [`paymentType`](/pixel/events/properties/payment-type) | string | Payment method (`"credit_card"`, `"paypal"`, `"shop_pay"`) | | [`shippingTier`](/pixel/events/properties/shipping-tier) | string | Shipping tier (`"standard"`, `"express"`, `"overnight"`) | | `cartId` | string | Shopping cart identifier | | `affiliation` | string | Store or affiliate name | | `orderSourceName` | string | Order source channel | | `tags` | string\[] | Array of order or event tags | | `totalUnitCost` | number | Total cost of goods sold (COGS) for profitability tracking | | `totalUnitMargin` | number | Total margin (value - totalUnitCost) | ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 134.99, currency: 'USD', subtotalPrice: 149.99, tax: 12.00, shipping: 8.00, discount: 35.00, coupon: 'SAVE25', paymentType: 'credit_card', shippingTier: 'express', items: [/* ... */] }); ``` *** ## Content Properties Properties for content-related events like search and page views. <CardGroup> <Card title="searchTerm" icon="magnifying-glass" href="/pixel/events/properties/search-term"> Search query entered by the user. </Card> <Card title="content_ids" icon="list" href="/pixel/events/properties/content-ids"> Array of product IDs from search results. </Card> </CardGroup> ### Quick Reference | Property | Type | Description | Events | | ----------------------------------------------------- | --------- | --------------------------------- | ------------------------------------------- | | [`searchTerm`](/pixel/events/properties/search-term) | string | Search query entered | search | | [`content_ids`](/pixel/events/properties/content-ids) | string\[] | Array of product IDs | view\_content, search, add\_to\_cart | | `content_type` | string | `"product"` or `"product_group"` | view\_content, add\_to\_cart, purchase | | `content_name` | string | Name of content, product, or form | view\_content, lead, complete\_registration | | `num_items` | number | Total item count | add\_to\_cart, initiate\_checkout, purchase | | `page_title` | string | Page title | page\_view | | `referrer` | string | Referring URL | page\_view | ```javascript theme={null} window._upstack('track', 'search', { searchTerm: 'blue running shoes', content_ids: ['SKU-001', 'SKU-002', 'SKU-003'] }); ``` *** ## Promotional Properties Properties for tracking promotions, campaigns, and affiliate activity. <CardGroup> <Card title="promotionId" icon="fingerprint" href="/pixel/events/properties/promotion-id"> Promotion/campaign identifier. </Card> <Card title="promotionName" icon="tag" href="/pixel/events/properties/promotion-name"> Promotion display name. </Card> <Card title="creativeName" icon="palette" href="/pixel/events/properties/creative-name"> Creative/ad variant name. </Card> <Card title="creativeSlot" icon="table-cells" href="/pixel/events/properties/creative-slot"> Placement position on page. </Card> <Card title="locationId" icon="location-dot" href="/pixel/events/properties/location-id"> Store/affiliate/location ID. </Card> </CardGroup> ### Quick Reference | Property | Type | Description | Events | | ---------------------------------------------------------- | ------ | ---------------------------------------- | -------------------------------------- | | [`promotionId`](/pixel/events/properties/promotion-id) | string | Promotion or campaign identifier | view\_content, add\_to\_cart, purchase | | [`promotionName`](/pixel/events/properties/promotion-name) | string | Promotion display name | view\_content, add\_to\_cart, purchase | | [`creativeName`](/pixel/events/properties/creative-name) | string | Creative or ad variant name | view\_content, add\_to\_cart, purchase | | [`creativeSlot`](/pixel/events/properties/creative-slot) | string | Creative placement position | view\_content, add\_to\_cart, purchase | | [`locationId`](/pixel/events/properties/location-id) | string | Store, affiliate, or location identifier | All events | ```javascript theme={null} window._upstack('track', 'view_content', { items: [{ id: 'SKU_001', name: 'Running Shoes', price: 89.99 }], value: 89.99, currency: 'USD', promotionId: 'SUMMER_SALE_2026', promotionName: 'Summer Sale 2026', creativeName: 'hero_banner_v2', creativeSlot: 'homepage_hero', locationId: 'store_nyc_001' }); ``` *** ## Detailed Property References <CardGroup> <Card title="Items Array" icon="list" href="/pixel/events/properties/items"> Product details for e-commerce events — id, name, price, quantity, brand, category, variant. </Card> <Card title="Address Properties" icon="location-dot" href="/pixel/events/properties/address"> Shipping and billing address fields — address1, city, province, country, zip. </Card> <Card title="SaaS Properties" icon="building" href="/pixel/events/properties/saas"> B2B/SaaS properties — account, subscription, trial, payment, and churn tracking. </Card> <Card title="Auto-Captured Fields" icon="wand-magic-sparkles" href="/pixel/events/properties/auto-captured"> Click IDs, UTMs, and context fields captured automatically by the pixel. </Card> </CardGroup> *** ## Naming Conventions ### Input vs Output Format Send properties in **camelCase** — the platform converts to each destination's required format automatically. | Your Input | Meta CAPI Output | GA4 Output | | --------------- | ---------------- | ------------------------- | | `transactionId` | `transaction_id` | `transaction_id` | | `firstName` | `fn` (hashed) | `first_name` | | `email` | `em` (hashed) | `user_id` (if configured) | ### Legacy Snake Case Properties Some properties use snake\_case for compatibility with Meta and GA4 conventions: | Property | Format | Notes | | -------------- | ----------- | -------------------------------------------------- | | `content_ids` | snake\_case | Array of product IDs (Meta convention) | | `content_type` | snake\_case | `"product"` or `"product_group"` (Meta convention) | | `content_name` | snake\_case | Content or product name | | `num_items` | snake\_case | Total item count | <Info> The platform accepts both formats and normalizes automatically. You can use either `contentIds` or `content_ids` — both work. </Info> ### Event Names Event names use **snake\_case** (e.g., `add_to_cart`, `initiate_checkout`, `view_content`). ```javascript theme={null} // Correct window._upstack('track', 'add_to_cart', { ... }); window._upstack('track', 'view_content', { ... }); // Incorrect window._upstack('track', 'AddToCart', { ... }); window._upstack('track', 'viewContent', { ... }); ``` # Items Array Source: https://docs.upstackdata.com/pixel/events/properties/items Product details for e-commerce events — id, name, price, quantity, brand, category, and variant properties. For events involving products, use the `items` array. Required for all product-related events. ## Items Array Structure ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 149.99, currency: 'USD', items: [ { id: 'SKU-001', // Product ID or SKU name: 'Running Shoes', // Product name price: 89.99, // Unit price quantity: 1, // Quantity (default: 1) brand: 'Nike', // Brand name category: 'Footwear', // Primary category variant: 'Blue / Size 10' // Size, color, etc. }, { id: 'SKU-002', name: 'Athletic Socks', price: 14.99, quantity: 4, brand: 'Nike', category: 'Accessories' } ] }); ``` ## Item Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ------------------------------------------------------------------ | | `id` | string | No | Product ID or SKU | | `name` | string | No | Product name | | `price` | number | No | Unit price | | `quantity` | number | No | Quantity (default: 1) | | `value` | number | No | Total value for this item (typically `price × quantity`) | | `currency` | string | No | Per-item currency override (ISO 4217 code, e.g., `"USD"`) | | `brand` | string | No | Brand name | | `category` | string | No | Primary category | | `category2` | string | No | Secondary category | | `category3` | string | No | Tertiary category | | `category4` | string | No | Fourth category level | | `category5` | string | No | Fifth category level | | `variant` | string | No | Size, color, or other variant | | `sku` | string | No | Stock keeping unit | | `discount` | number | No | Discount amount per item | | `coupon` | string | No | Item-level coupon code | | `url` | string | No | Product page URL | | `imageUrl` | string | No | Product image URL | | `content_type` | string | No | `"product"` for individual items or `"product_group"` for variants | | `index` | number | No | Zero-based index of item in the items array | | `locationId` | string | No | Per-item store or location identifier | | `unitCost` | number | No | Cost per unit (for margin calculations) | | `unitMargin` | number | No | Margin per unit (for profitability tracking) | <Note> If `value` is not provided, it is computed automatically as `price × quantity`. </Note> ## Items Array by Event ```javascript theme={null} // View a product window._upstack('track', 'view_content', { items: [{ id: 'SKU-001', name: 'Running Shoes', price: 89.99, category: 'Footwear' }] }); // Add to cart window._upstack('track', 'add_to_cart', { value: 89.99, currency: 'USD', items: [{ id: 'SKU-001', name: 'Running Shoes', price: 89.99, quantity: 1 }] }); // Begin checkout window._upstack('track', 'initiate_checkout', { value: 104.98, currency: 'USD', items: [ { id: 'SKU-001', name: 'Running Shoes', price: 89.99, quantity: 1 }, { id: 'SKU-002', name: 'Athletic Socks', price: 14.99, quantity: 1 } ] }); ``` # locationId Source: https://docs.upstackdata.com/pixel/events/properties/location-id Store, affiliate, or location identifier. Store, affiliate, or location identifier. ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 134.99, currency: 'USD', locationId: 'store_nyc_001' }); ``` | Type | Required | Events | | ------ | -------- | ---------- | | string | No | All events | ## Use Cases * **Multi-location retail**: Track which store location drove the conversion * **Affiliate tracking**: Identify which affiliate partner referred the customer * **Franchise tracking**: Attribute conversions to specific franchise locations ## Related Properties <CardGroup> <Card title="creativeSlot" icon="table-cells" href="/pixel/events/properties/creative-slot"> Creative placement position. </Card> <Card title="promotionId" icon="bullhorn" href="/pixel/events/properties/promotion-id"> Promotion identifier. </Card> </CardGroup> # firstName / lastName Source: https://docs.upstackdata.com/pixel/events/properties/name Customer's name for identity resolution and destination matching. Customer's name. Used for identity resolution and destination matching. ```javascript theme={null} window._upstack('track', 'purchase', { firstName: 'Jane', lastName: 'Smith', email: 'jane.smith@example.com', transactionId: 'ORD-123', value: 149.99, currency: 'USD' }); ``` | Type | Required | Events | | ------ | -------- | ---------- | | string | No | All events | ## Privacy Names are normalized (lowercase, trimmed) and SHA-256 hashed before being sent to advertising destinations. ## Related Properties <CardGroup> <Card title="email" icon="envelope" href="/pixel/events/properties/email"> Customer email — primary identifier. </Card> <Card title="phone" icon="phone" href="/pixel/events/properties/phone"> Customer phone number. </Card> <Card title="Address Properties" icon="location-dot" href="/pixel/events/properties/address"> Shipping and billing address fields. </Card> </CardGroup> # orderName Source: https://docs.upstackdata.com/pixel/events/properties/order-name Human-readable order name shown to customers. Human-readable order name (e.g., the order number shown to customers). ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'shopify_order_5678901234', orderName: '#1042', // What the customer sees value: 149.99, currency: 'USD' }); ``` | Type | Required | Events | | ------ | -------- | -------- | | string | No | purchase | ## Related Properties <CardGroup> <Card title="transactionId" icon="fingerprint" href="/pixel/events/properties/transaction-id"> Unique order identifier for tracking. </Card> </CardGroup> # paymentType Source: https://docs.upstackdata.com/pixel/events/properties/payment-type Payment method used for checkout. Payment method used for checkout. ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 134.99, currency: 'USD', paymentType: 'credit_card' }); ``` | Type | Required | Events | | ------ | -------- | ---------------------------- | | string | No | purchase, add\_payment\_info | ## Common Values | Value | Description | | ------------- | -------------------- | | `credit_card` | Credit or debit card | | `paypal` | PayPal | | `shop_pay` | Shop Pay (Shopify) | | `apple_pay` | Apple Pay | | `google_pay` | Google Pay | | `klarna` | Klarna | | `afterpay` | Afterpay | <Note> These are suggested values. Any string is accepted. </Note> ## Related Properties <CardGroup> <Card title="shippingTier" icon="truck" href="/pixel/events/properties/shipping-tier"> Shipping tier selected. </Card> </CardGroup> # phone Source: https://docs.upstackdata.com/pixel/events/properties/phone Customer's phone number. E.164 format recommended. Customer's phone number. E.164 format recommended for best matching. ```javascript theme={null} window._upstack('track', 'lead', { email: 'customer@example.com', phone: '+15551234567', // E.164 format: +[country][number] value: 0, currency: 'USD' }); ``` | Type | Required | Events | | ------ | -------- | ----------------------------------- | | string | No | All events (improves match quality) | ## E.164 Format The E.164 format is the international standard for phone numbers: * Start with `+` followed by country code * No spaces, dashes, or parentheses * Example: `+15551234567` (US), `+442071234567` (UK) ## Privacy Phone numbers are normalized and SHA-256 hashed before being sent to destinations. ## Related Properties <CardGroup> <Card title="email" icon="envelope" href="/pixel/events/properties/email"> Customer email — primary identifier. </Card> <Card title="firstName / lastName" icon="user" href="/pixel/events/properties/name"> Customer name for identity resolution. </Card> </CardGroup> # promotionId Source: https://docs.upstackdata.com/pixel/events/properties/promotion-id Promotion or campaign identifier. Promotion or campaign identifier. ```javascript theme={null} window._upstack('track', 'view_content', { items: [{ id: 'SKU_001', name: 'Running Shoes', price: 89.99 }], value: 89.99, currency: 'USD', promotionId: 'SUMMER_SALE_2026' }); ``` | Type | Required | Events | | ------ | -------- | -------------------------------------- | | string | No | view\_content, add\_to\_cart, purchase | ## Related Properties <CardGroup> <Card title="promotionName" icon="tag" href="/pixel/events/properties/promotion-name"> Human-readable promotion name. </Card> <Card title="creativeName" icon="palette" href="/pixel/events/properties/creative-name"> Creative variant name. </Card> <Card title="creativeSlot" icon="table-cells" href="/pixel/events/properties/creative-slot"> Placement position on page. </Card> </CardGroup> # promotionName Source: https://docs.upstackdata.com/pixel/events/properties/promotion-name Human-readable promotion display name. Human-readable promotion display name. ```javascript theme={null} window._upstack('track', 'view_content', { items: [{ id: 'SKU_001', name: 'Running Shoes', price: 89.99 }], value: 89.99, currency: 'USD', promotionId: 'SUMMER_SALE_2026', promotionName: 'Summer Sale 2026' }); ``` | Type | Required | Events | | ------ | -------- | -------------------------------------- | | string | No | view\_content, add\_to\_cart, purchase | ## Related Properties <CardGroup> <Card title="promotionId" icon="fingerprint" href="/pixel/events/properties/promotion-id"> Promotion identifier. </Card> <Card title="creativeName" icon="palette" href="/pixel/events/properties/creative-name"> Creative variant name. </Card> </CardGroup> # Promotional Properties Source: https://docs.upstackdata.com/pixel/events/properties/promotional Properties for tracking promotions, campaigns, and affiliate activity — promotion IDs, creative names, and location tracking. Promotional properties help track on-site promotions, campaigns, and affiliate activity. ## Properties <CardGroup> <Card title="promotionId" icon="fingerprint" href="/pixel/events/properties/promotion-id"> Promotion/campaign identifier. </Card> <Card title="promotionName" icon="tag" href="/pixel/events/properties/promotion-name"> Promotion display name. </Card> <Card title="creativeName" icon="palette" href="/pixel/events/properties/creative-name"> Creative/ad variant name. </Card> <Card title="creativeSlot" icon="table-cells" href="/pixel/events/properties/creative-slot"> Placement position on page. </Card> <Card title="locationId" icon="location-dot" href="/pixel/events/properties/location-id"> Store/affiliate/location ID. </Card> </CardGroup> ## Quick Reference | Property | Type | Description | Events | | --------------- | ------ | ---------------------------------------- | -------------------------------------- | | `promotionId` | string | Promotion or campaign identifier | view\_content, add\_to\_cart, purchase | | `promotionName` | string | Promotion display name | view\_content, add\_to\_cart, purchase | | `creativeName` | string | Creative or ad variant name | view\_content, add\_to\_cart, purchase | | `creativeSlot` | string | Creative placement position | view\_content, add\_to\_cart, purchase | | `locationId` | string | Store, affiliate, or location identifier | All events | ## Example ```javascript theme={null} window._upstack('track', 'view_content', { items: [{ id: 'SKU_001', name: 'Running Shoes', price: 89.99 }], value: 89.99, currency: 'USD', promotionId: 'SUMMER_SALE_2026', promotionName: 'Summer Sale 2026', creativeName: 'hero_banner_v2', creativeSlot: 'homepage_hero', locationId: 'store_nyc_001' }); ``` ## Use Cases * **On-site promotions**: Track which banners and placements drive conversions * **Affiliate tracking**: Identify which partners referred customers * **Multi-location retail**: Attribute conversions to specific store locations # SaaS Event Properties Source: https://docs.upstackdata.com/pixel/events/properties/saas B2B/SaaS properties — account, subscription, trial, payment, seat, and churn tracking fields. For B2B/SaaS applications tracking accounts, subscriptions, trials, and recurring revenue. <Card title="SaaS Events Reference" icon="building" href="/pixel/saas-events"> See the complete SaaS Events Reference for event names, timing, and usage patterns. </Card> ## Account Properties | Property | Type | Description | Events | | ------------------ | ------ | ---------------------------------------------------------------------------- | ---------------------------------------------- | | `accountId` | string | Account or organization identifier | All SaaS events | | `accountName` | string | Account or organization display name | signup\_completed, account\_\* | | `accountCreatedAt` | string | ISO 8601 timestamp when account was created | signup\_completed | | `userId` | string | User identifier | signup\_completed, user\_joined, feature\_used | | `userEmail` | string | User's email address | signup\_completed, user\_joined | | `userRole` | string | User's role in the account: `"owner"`, `"admin"`, `"manager"`, or `"member"` | user\_joined, user\_\* | ## Subscription & Revenue Properties | Property | Type | Description | Events | | ----------------- | ------ | ------------------------------------------ | ---------------------------------------------------------------------------- | | `subscriptionId` | string | Subscription identifier | subscription\_*, trial\_*, payment\_\* | | `planId` | string | Plan identifier | trial\_*, subscription\_* | | `planName` | string | Human-readable plan name | trial\_*, subscription\_* | | `mrr` | number | Monthly recurring revenue in cents | subscription\_\*, trial\_converted | | `mrrDelta` | number | MRR change in cents (positive or negative) | subscription\_upgraded, subscription\_downgraded, seat\_added, seat\_removed | | `arr` | number | Annual recurring revenue in cents | subscription\_\*, trial\_converted | | `ltv` | number | Customer lifetime value in cents | subscription\_churned, account\_\* | | `billingInterval` | string | `"month"` or `"year"` | subscription\_*, payment\_* | ## Trial Properties | Property | Type | Description | Events | | -------------------- | ------ | ---------------------------------------- | ------------------------------------------- | | `trialDaysRemaining` | number | Days until trial expires | trial\_\* | | `trialStartDate` | string | ISO 8601 timestamp when trial started | trial\_started | | `trialEndDate` | string | ISO 8601 timestamp when trial ends/ended | trial\_\*, trial\_converted, trial\_expired | ## Payment Properties | Property | Type | Description | Events | | --------------- | ------ | -------------------------- | ----------------------------------- | | `invoiceId` | string | Invoice identifier | payment\_succeeded, payment\_failed | | `amount` | number | Payment amount in cents | payment\_succeeded, payment\_failed | | `failureReason` | string | Reason for payment failure | payment\_failed | ## Seat & Team Properties | Property | Type | Description | Events | | ----------- | ------ | ------------------------------------------------------ | -------------------------- | | `seatCount` | number | Total seats after change | seat\_added, seat\_removed | | `seatDelta` | number | Number of seats added (positive) or removed (negative) | seat\_added, seat\_removed | ## Add-on Properties | Property | Type | Description | Events | | ----------- | ------ | ------------------- | ---------------------------- | | `addonId` | string | Add-on identifier | addon\_added, addon\_removed | | `addonName` | string | Add-on display name | addon\_added, addon\_removed | ## Feature & Engagement Properties | Property | Type | Description | Events | | --------------- | ------ | --------------------------------------------------------- | -------------------------------------- | | `featureId` | string | Feature identifier | feature\_used, feature\_limit\_reached | | `featureName` | string | Feature display name | feature\_used, feature\_limit\_reached | | `usageInfo` | object | Usage details: `{ currentUsage, limit, usagePercentage }` | feature\_limit\_reached, usage\_\* | | `milestoneId` | string | Milestone identifier | milestone\_reached | | `milestoneName` | string | Milestone display name | milestone\_reached | ## Churn & Cancellation Properties | Property | Type | Description | Events | | ---------------- | ------ | ------------------------------------------- | ---------------------------------------------- | | `cancelReason` | string | Reason code for cancellation | subscription\_cancelled, subscription\_churned | | `cancelFeedback` | string | Free-text feedback from cancellation survey | subscription\_cancelled | | `cancelledAt` | string | ISO 8601 timestamp of cancellation | subscription\_cancelled, subscription\_churned | | `inactiveDays` | number | Days since last activity before churn | subscription\_churned | # searchTerm Source: https://docs.upstackdata.com/pixel/events/properties/search-term Search query entered by the user. Search query entered by the user. ```javascript theme={null} window._upstack('track', 'search', { searchTerm: 'blue running shoes', content_ids: ['SKU-001', 'SKU-002', 'SKU-003'] }); ``` | Type | Required | Events | | ------ | -------------- | ------ | | string | Yes for search | search | ## Related Properties <CardGroup> <Card title="content_ids" icon="list" href="/pixel/events/properties/content-ids"> Product IDs from search results. </Card> </CardGroup> # shipping Source: https://docs.upstackdata.com/pixel/events/properties/shipping Shipping cost for the order. Shipping cost for the order. ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 134.99, currency: 'USD', shipping: 8.00 }); ``` | Type | Required | Events | | ------ | -------- | ------------------------------------------------- | | number | No | purchase, initiate\_checkout, add\_shipping\_info | ## Related Properties <CardGroup> <Card title="shippingTier" icon="gauge-high" href="/pixel/events/properties/shipping-tier"> Shipping speed/tier selected. </Card> <Card title="tax" icon="percent" href="/pixel/events/properties/tax"> Tax amount. </Card> </CardGroup> # shippingTier Source: https://docs.upstackdata.com/pixel/events/properties/shipping-tier Shipping tier selected by the customer. Shipping tier selected by the customer. ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 134.99, currency: 'USD', shippingTier: 'express' }); ``` | Type | Required | Events | | ------ | -------- | ------------------------------------------------------- | | string | No | purchase, add\_shipping\_info, select\_shipping\_method | ## Common Values | Value | Description | | ----------- | ---------------------------- | | `standard` | Standard shipping (5-7 days) | | `express` | Express shipping (2-3 days) | | `overnight` | Next-day delivery | | `free` | Free shipping | | `pickup` | In-store pickup | <Note> These are suggested values. Any string is accepted. </Note> ## Related Properties <CardGroup> <Card title="shipping" icon="dollar-sign" href="/pixel/events/properties/shipping"> Shipping cost amount. </Card> <Card title="paymentType" icon="credit-card" href="/pixel/events/properties/payment-type"> Payment method used. </Card> </CardGroup> # subtotalPrice Source: https://docs.upstackdata.com/pixel/events/properties/subtotal-price Subtotal before tax and shipping. Subtotal before tax and shipping. ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 134.99, // Final total currency: 'USD', subtotalPrice: 149.99 // Before discounts/tax/shipping }); ``` | Type | Required | Events | | ------ | -------- | ---------------------------- | | number | No | purchase, initiate\_checkout | ## Related Properties <CardGroup> <Card title="value" icon="coins" href="/pixel/events/properties/value"> Final order total. </Card> <Card title="tax" icon="percent" href="/pixel/events/properties/tax"> Tax amount. </Card> <Card title="shipping" icon="truck" href="/pixel/events/properties/shipping"> Shipping cost. </Card> <Card title="discount" icon="tag" href="/pixel/events/properties/discount"> Discount amount applied. </Card> </CardGroup> # tax Source: https://docs.upstackdata.com/pixel/events/properties/tax Tax amount applied to the order. Tax amount applied to the order. ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 134.99, currency: 'USD', tax: 12.00 }); ``` | Type | Required | Events | | ------ | -------- | ---------------------------- | | number | No | purchase, initiate\_checkout | ## Related Properties <CardGroup> <Card title="subtotalPrice" icon="receipt" href="/pixel/events/properties/subtotal-price"> Subtotal before tax and shipping. </Card> <Card title="shipping" icon="truck" href="/pixel/events/properties/shipping"> Shipping cost. </Card> </CardGroup> # transactionId / orderId Source: https://docs.upstackdata.com/pixel/events/properties/transaction-id Unique identifier for the order. Use either transactionId or orderId. Unique identifier for the order. Use either `transactionId` or `orderId` — they're interchangeable. ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-2026-001', // or orderId: 'ORD-2026-001' value: 149.99, currency: 'USD' }); ``` | Type | Required | Events | | ------ | ----------------------- | ---------------- | | string | Yes for purchase/refund | purchase, refund | <Note> For Shopify stores, this is typically the Shopify order ID (e.g., `shopify_order_5678901234`). </Note> ## Related Properties <CardGroup> <Card title="orderName" icon="hashtag" href="/pixel/events/properties/order-name"> Human-readable order number shown to customers. </Card> <Card title="value" icon="coins" href="/pixel/events/properties/value"> The monetary value of the order. </Card> </CardGroup> # value Source: https://docs.upstackdata.com/pixel/events/properties/value The monetary value of the event. Always pair with currency. The monetary value of the event. Always pair with `currency`. ```javascript theme={null} window._upstack('track', 'purchase', { value: 99.99, currency: 'USD' }); ``` | Type | Required | Events | | ------ | --------------------------------- | ------------------------------------------------------------------------------------------- | | number | Yes for purchase, lead, subscribe | purchase, add\_to\_cart, view\_content, initiate\_checkout, lead, subscribe, trial\_started | <Warning> For Purchase events, `value` should match the order total you want reported to ad platforms. Mismatched values between Shopify and your destinations are the most common attribution debugging issue. </Warning> ## Related Properties <CardGroup> <Card title="currency" icon="dollar-sign" href="/pixel/events/properties/currency"> ISO 4217 currency code — required with value. </Card> <Card title="subtotalPrice" icon="receipt" href="/pixel/events/properties/subtotal-price"> Subtotal before tax and shipping. </Card> </CardGroup> # purchase Event Source: https://docs.upstackdata.com/pixel/events/purchase Track when an order is completed Fires when an order is completed. This is the most important e-commerce event — it's used for conversion tracking, ROAS calculation, and optimization across all ad platforms. <Note> **Shopify:** Automatically tracked on the order confirmation page (thank you page) and via server-side webhooks. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'purchase', { orderId: 'ORD_12345', value: 149.99, currency: 'USD', tax: 12.50, shipping: 5.99, items: [ { id: 'SKU_001', name: 'Blue Running Shoes', price: 89.99, quantity: 1, brand: 'Nike', category: 'Shoes/Running' }, { id: 'SKU_002', name: 'Running Socks', price: 14.99, quantity: 2, brand: 'Nike', category: 'Accessories/Socks' } ], email: 'customer@example.com' }, 'ORD_12345'); ``` <Note> The third parameter (`'ORD_12345'`) is a deduplication ID. It prevents duplicate purchase events from being sent to destinations if the event fires multiple times. </Note> Minimal example: ```javascript theme={null} window._upstack('track', 'purchase', { orderId: 'ORD_12345', value: 149.99, currency: 'USD', items: [{ id: 'SKU_001', name: 'Blue Running Shoes', price: 89.99, quantity: 1 }] }, 'ORD_12345'); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | -------------------------------------------------------------------------- | | orderId | string | Yes | Unique order identifier | | value | number | Yes | Total order value | | currency | string | Yes | ISO 4217 currency code | | items | array | Yes | Products purchased (see [Item Object](/pixel/standard-events#item-object)) | | tax | number | No | Tax amount | | shipping | number | No | Shipping cost | | email | string | No | Customer email (improves identity matching) | <Warning> **Important:** The `value` property should match what you want reported to ad platforms. Discrepancies between Shopify order totals and reported CAPI revenue are the most common attribution debugging issue. </Warning> ## When to Fire * Order confirmation page load * After successful payment confirmation * Shopify `orders/create` webhook (server-side) ## Related Events * [initiate\_checkout](/pixel/events/initiate-checkout) — Starting the checkout * [add\_payment\_info](/pixel/events/add-payment-info) — Before completing purchase * [refund](/pixel/events/refund) — When order is refunded # quiz_completed Event Source: https://docs.upstackdata.com/pixel/events/quiz-completed Track when a visitor completes a quiz or assessment Fires when a visitor completes a quiz, product recommendation quiz, or assessment. This is a recommended custom event for tracking quiz funnels and product discovery flows. <Note> **Custom Event** — This event is not automatically tracked. Fire it manually using the JavaScript SDK when a quiz is completed. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'quiz_completed', { quiz_id: 'skin-type-finder', quiz_name: 'Find Your Perfect Skincare Routine', result_id: 'oily-acne-prone', result_name: 'Oily & Acne-Prone Skin', questions_answered: 8, time_to_complete: 145, value: 25.00, currency: 'USD' }); ``` Quiz with product recommendations: ```javascript theme={null} window._upstack('track', 'quiz_completed', { quiz_id: 'gift-finder', quiz_name: 'Holiday Gift Finder', result_id: 'tech-enthusiast', recommended_products: ['SKU-1234', 'SKU-5678', 'SKU-9012'], questions_answered: 5 }); ``` ## Properties | Property | Type | Required | Description | | --------------------- | --------- | -------- | --------------------------------------------- | | quiz\_id | string | Yes | Unique identifier for the quiz | | quiz\_name | string | No | Human-readable quiz title | | result\_id | string | No | Identifier for the quiz result or outcome | | result\_name | string | No | Human-readable result description | | questions\_answered | number | No | Total questions completed | | time\_to\_complete | number | No | Seconds from quiz start to completion | | recommended\_products | string\[] | No | Array of product SKUs recommended by the quiz | | value | number | No | Estimated value of the quiz completion | | currency | string | No | ISO 4217 currency code | ## When to Fire * Product recommendation quiz completion * Skin type or style finder completion * Gift guide quiz completion * Assessment or diagnostic quiz completion * Personality quiz completion ## Destination Support | Destination | Support | | --------------------- | --------------------------------------------------------------------------------- | | **Meta CAPI** | Supported as `Custom` event type. Use for building audiences of quiz completers. | | **TikTok Events API** | Supported. Use for audience building. | | **Klaviyo** | Fully supported. Triggers flows based on quiz results for personalized follow-up. | | **GA4** | Supported. Maps to custom event with parameters. | | **Webhook** | Fully supported. Raw payload forwarded. | <Tip> **Personalization tip:** Pass the `result_id` to Klaviyo to trigger personalized email flows based on quiz outcomes. Segment customers by their quiz results for targeted product recommendations. </Tip> ## Related Events * [quiz\_question\_answered](/pixel/events/quiz-question-answered) — Track individual question responses * [lead](/pixel/events/lead) — For capturing contact info during or after quiz * [view\_content](/pixel/events/view-content) — When quiz results include product views # Quiz Events Source: https://docs.upstackdata.com/pixel/events/quiz-events Track quiz funnels and product recommendation flows with quiz_completed and quiz_question_answered events. Quiz events help you track product recommendation quizzes, style finders, assessments, and other interactive quiz experiences. Use these events to understand quiz completion rates, segment customers by quiz results, and trigger personalized follow-up flows. <Note> **Custom Events** — Quiz events are not automatically tracked. Fire them manually using the JavaScript SDK at the appropriate points in your quiz flow. </Note> ## Available Events <CardGroup> <Card title="quiz_completed" icon="flag-checkered" href="/pixel/events/quiz-completed"> Fires when a visitor completes a quiz. Captures the result, recommended products, and completion time. </Card> <Card title="quiz_question_answered" icon="circle-question" href="/pixel/events/quiz-question-answered"> Fires when a visitor answers an individual question. Use for funnel analysis and drop-off tracking. </Card> </CardGroup> ## Use Cases ### Product Recommendation Quizzes Track quizzes that help customers find the right product: ```javascript theme={null} // Track each question for funnel analysis window._upstack('track', 'quiz_question_answered', { quiz_id: 'skin-type-finder', question_id: 'q1', question_text: 'What is your skin type?', answer_id: 'oily', answer_text: 'Oily', question_number: 1, total_questions: 5 }); // Track quiz completion with results window._upstack('track', 'quiz_completed', { quiz_id: 'skin-type-finder', quiz_name: 'Find Your Perfect Skincare Routine', result_id: 'oily-acne-prone', result_name: 'Oily & Acne-Prone Skin', recommended_products: ['SKU-1234', 'SKU-5678'], questions_answered: 5, time_to_complete: 120 }); ``` ### Funnel Analysis Track `quiz_question_answered` for each question to identify where users drop off: | Question | Started | Completed | Drop-off | | ------------- | ------- | --------- | --------- | | Q1: Skin Type | 1,000 | 920 | 8% | | Q2: Concerns | 920 | 850 | 7.6% | | Q3: Budget | 850 | 780 | 8.2% | | Q4: Routine | 780 | 750 | 3.8% | | Q5: Products | 750 | 720 | 4% | | **Completed** | — | 720 | 28% total | ### Klaviyo Personalization Use quiz results to trigger personalized email flows: 1. Fire `quiz_completed` with `result_id` and `result_name` 2. In Klaviyo, create a flow triggered by the `quiz_completed` event 3. Use the `result_id` property to branch into different email sequences 4. Include `recommended_products` in product recommendation blocks ## Destination Support | Destination | quiz\_completed | quiz\_question\_answered | | --------------------- | ------------------------------ | ------------------------ | | **Meta CAPI** | ✅ Custom event | ✅ Custom event | | **TikTok Events API** | ✅ Supported | ✅ Supported | | **Klaviyo** | ✅ Full support with properties | ✅ Full support | | **GA4** | ✅ Custom event | ✅ Custom event | | **Webhook** | ✅ Raw payload | ✅ Raw payload | <Tip> **Best practice:** Always include `quiz_id` on both events so you can correlate question-level data with completion data in your analytics. </Tip> ## Related * [Custom Events](/pixel/events/custom-events) — General guide for firing custom events * [lead](/pixel/events/lead) — Capture contact info during or after quiz * [view\_content](/pixel/events/view-content) — Track when quiz results show product recommendations # quiz_question_answered Event Source: https://docs.upstackdata.com/pixel/events/quiz-question-answered Track individual quiz question responses for funnel analysis Fires when a visitor answers a question in a quiz or assessment. This is a recommended custom event for tracking quiz progress, identifying drop-off points, and analyzing answer patterns. <Note> **Custom Event** — This event is not automatically tracked. Fire it manually using the JavaScript SDK after each question is answered. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'quiz_question_answered', { quiz_id: 'skin-type-finder', question_id: 'q3_skin_concerns', question_number: 3, question_text: 'What are your primary skin concerns?', answer_id: 'acne', answer_text: 'Acne & Breakouts', total_questions: 8 }); ``` Multiple-choice question with multiple answers: ```javascript theme={null} window._upstack('track', 'quiz_question_answered', { quiz_id: 'gift-finder', question_id: 'q2_interests', question_number: 2, question_text: 'What are their interests?', answer_ids: ['tech', 'outdoors', 'cooking'], answer_texts: ['Technology', 'Outdoors & Adventure', 'Cooking & Food'], total_questions: 5 }); ``` ## Properties | Property | Type | Required | Description | | ------------------ | --------- | -------- | ----------------------------------------- | | quiz\_id | string | Yes | Unique identifier for the quiz | | question\_id | string | Yes | Unique identifier for the question | | question\_number | number | No | Position of the question (1-indexed) | | question\_text | string | No | The question text displayed to the user | | answer\_id | string | No | Identifier for single-choice answer | | answer\_ids | string\[] | No | Identifiers for multiple-choice answers | | answer\_text | string | No | Display text for single-choice answer | | answer\_texts | string\[] | No | Display texts for multiple-choice answers | | total\_questions | number | No | Total number of questions in the quiz | | time\_on\_question | number | No | Seconds spent on this question | ## When to Fire * After each quiz question is submitted * When a user selects an answer (if auto-advancing) * When moving to the next question in a multi-step quiz ## Destination Support | Destination | Support | | --------------------- | ------------------------------------------------------------------------------------ | | **Meta CAPI** | Supported as `Custom` event type. Build audiences based on specific answer patterns. | | **TikTok Events API** | Supported. Use for audience building. | | **Klaviyo** | Fully supported. Track answer patterns for segmentation. | | **GA4** | Supported. Use for funnel analysis and drop-off tracking. | | **Webhook** | Fully supported. Raw payload forwarded. | <Tip> **Funnel analysis tip:** Track `question_number` and `total_questions` to identify where users drop off. High drop-off on a specific question may indicate confusing wording or too many options. </Tip> ## Related Events * [quiz\_completed](/pixel/events/quiz-completed) — Fire when the quiz is finished * [lead](/pixel/events/lead) — If capturing contact info mid-quiz # refund Event Source: https://docs.upstackdata.com/pixel/events/refund Track when an order is refunded Fires when an order is refunded. This helps maintain accurate revenue reporting and adjusts conversion data for ad platforms that support refund events. <Note> **Shopify:** Automatically tracked via the `refunds/create` webhook (server-side). </Note> ## JavaScript Full refund: ```javascript theme={null} window._upstack('track', 'refund', { orderId: 'ORD_12345', value: 149.99, currency: 'USD' }); ``` Partial refund: ```javascript theme={null} window._upstack('track', 'refund', { orderId: 'ORD_12345', value: 89.99, currency: 'USD', items: [ { id: 'SKU_001', name: 'Blue Running Shoes', price: 89.99, quantity: 1 } ] }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------------------- | | orderId | string | Yes | Original order identifier | | value | number | Yes | Refund amount | | currency | string | No | ISO 4217 currency code | | items | array | No | Products refunded (for partial refunds) | ## When to Fire * Refund processed via Shopify admin * `refunds/create` webhook (server-side) * Customer service refund action ## Related Events * [purchase](/pixel/events/purchase) — The original order event # schedule Event Source: https://docs.upstackdata.com/pixel/events/schedule Track when a user schedules an appointment Fires when a user schedules an appointment. Use this for service-based businesses where customers book appointments, fittings, or consultations. <Note> **Shopify:** Manual implementation required. Integrate with your scheduling system. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'schedule', { appointmentType: 'fitting', value: 75.00, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ---------------------- | | appointmentType | string | No | Type of appointment | | value | number | No | Service value | | currency | string | No | ISO 4217 currency code | ## When to Fire * Appointment booking confirmation * Service scheduling completion ## Related Events * [book\_call](/pixel/events/book-call) — For sales calls and consultations * [lead](/pixel/events/lead) — For general lead capture # search Event Source: https://docs.upstackdata.com/pixel/events/search Track when a visitor performs a search Fires when a visitor performs a search. This helps understand what customers are looking for and can inform product decisions and SEO strategy. <Note> **Shopify:** Automatically tracked when using Shopify's native search functionality. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'search', { searchTerm: 'blue running shoes', resultsCount: 24 }); ``` With search results: ```javascript theme={null} window._upstack('track', 'search', { searchTerm: 'blue running shoes', resultsCount: 24, items: [ { id: 'SKU_001', name: 'Blue Running Shoes', price: 89.99 }, { id: 'SKU_002', name: 'Navy Training Shoes', price: 79.99 } ] }); ``` ## Properties | Property | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------ | | searchTerm | string | Yes | The search query entered | | resultsCount | number | No | Number of results returned | | items | array | No | Top products in search results | ## When to Fire * Search results page load * Predictive search dropdown display * "No results" page (with `resultsCount: 0`) ## Related Events * [view\_content](/pixel/events/view-content) — When clicking on a search result * [view\_item\_list](/pixel/events/view-item-list) — For displaying search results as a list # select_shipping_method Event Source: https://docs.upstackdata.com/pixel/events/select-shipping-method Track when a customer selects a shipping method during checkout Fires when a customer selects a shipping method during checkout. This helps understand shipping preferences and their impact on conversion. <Note> **Shopify:** Manual implementation required. Not automatically tracked. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'select_shipping_method', { shippingTier: 'express', shipping: 12.99, currency: 'USD', value: 97.98 }); ``` With items: ```javascript theme={null} window._upstack('track', 'select_shipping_method', { shippingTier: 'overnight', shipping: 24.99, currency: 'USD', value: 109.98, items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2 } ] }); ``` ## Properties | Property | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------------------------------------- | | shippingTier | string | Yes | Shipping method selected (e.g., `'standard'`, `'express'`, `'overnight'`) | | shipping | number | No | Shipping cost | | value | number | No | Cart value at shipping selection | | currency | string | No | ISO 4217 currency code | | items | array | No | Products in checkout | ## When to Fire * Shipping method radio button selection * Shipping tier dropdown change * Before proceeding to payment ## Related Events * [add\_shipping\_info](/pixel/events/add-shipping-info) — When entering shipping address * [add\_payment\_info](/pixel/events/add-payment-info) — After entering payment details # sign_up Event Source: https://docs.upstackdata.com/pixel/events/sign-up Track when a user creates a new account Fires when a user creates a new account. Use this for simple account creation flows. <Note> **Shopify:** Manual implementation required. Not automatically tracked. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'sign_up', { method: 'email' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------------------------------- | | method | string | No | Signup method (`'email'`, `'google'`, `'facebook'`) | <Note> **sign\_up vs complete\_registration:** Use `sign_up` for initial account creation. Use `complete_registration` for multi-step registration flows or when capturing additional profile data. </Note> ## When to Fire * Account creation form submission * OAuth signup completion ## Related Events * [complete\_registration](/pixel/events/complete-registration) — For multi-step registration * [login](/pixel/events/login) — When existing users log in # submit_application Event Source: https://docs.upstackdata.com/pixel/events/submit-application Track when a user submits an application Fires when a user submits an application. Use this for wholesale applications, affiliate program signups, partnership requests, and similar high-value lead capture. <Note> **Shopify:** Manual implementation required. Integrate with your application forms. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'submit_application', { applicationType: 'wholesale_partner', value: 5000.00, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | --------------------------- | | applicationType | string | No | Application type | | value | number | No | Estimated application value | | currency | string | No | ISO 4217 currency code | ## When to Fire * Wholesale application submission * Affiliate program application * Partnership request ## Related Events * [lead](/pixel/events/lead) — For general lead capture * [complete\_registration](/pixel/events/complete-registration) — For account signups # subscribe Event Source: https://docs.upstackdata.com/pixel/events/subscribe Track when a visitor subscribes to email or SMS marketing Fires when a visitor subscribes to email or SMS marketing. This helps track marketing list growth and attribute new subscribers to campaigns. <Note> **Shopify:** Tracked via popup/form hooks when using compatible email/SMS apps. Manual implementation may be required for custom forms. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'subscribe', { channel: 'email', source: 'footer_form', value: 5.00, currency: 'USD' }); ``` SMS subscription: ```javascript theme={null} window._upstack('track', 'subscribe', { channel: 'sms', source: 'popup', phone: '+15551234567' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------------------------------------------- | | channel | string | No | Subscription channel (`'email'`, `'sms'`, `'push'`) | | source | string | No | Subscription source (e.g., `'popup'`, `'footer'`, `'checkout'`) | | value | number | No | Estimated subscriber value | | currency | string | No | ISO 4217 currency code | ## When to Fire * Newsletter signup * SMS opt-in * Push notification subscription ## Related Events * [lead](/pixel/events/lead) — For general lead capture * [complete\_registration](/pixel/events/complete-registration) — For account creation # Event Taxonomy Source: https://docs.upstackdata.com/pixel/events/taxonomy Reference for the Upstack Data event model — 25 standard events, how they flow from capture through identity resolution and enrichment to destination forwarding. Every interaction a customer has with your website generates an event. Upstack Data captures these events server-side, enriches them with identity and product data, and forwards them to your configured destinations. <Tip> Upstack tracks 25 standard events. **Shopify stores** see events tracked automatically via the theme app extension. **Custom implementations** (headless, GTM, non-Shopify platforms) can fire the same events using the [JavaScript SDK](/pixel/javascript-sdk). </Tip> ## How Events Are Captured The **Upstack Pixel** is a lightweight JavaScript snippet that runs on your website. When a visitor performs an action — viewing a page, adding a product to cart, completing a purchase — the pixel fires an event to the Upstack edge API. <Note> **Shopify stores:** The pixel is injected automatically via the theme app extension. **Custom implementations:** Add the pixel snippet to your site's `<head>` — see [Pixel Setup](/pixel/setup). </Note> From there, events flow through a four-stage pipeline: 1. **Capture** — Upstack Pixel detects the interaction and sends a structured event payload to the Cloudflare edge API. 2. **Resolve** — Upstack ID attaches identity data (email, phone, cookie, device) to the event, linking anonymous sessions to known customers. 3. **Enrich** — Product catalog data, UTM parameters, and click IDs are merged into the event. 4. **Activate** — The enriched event is forwarded to each configured destination (Meta CAPI, TikTok, Klaviyo, GA4, etc.) in the format each platform expects. ## Standard Event Taxonomy Standard events have well-defined names, properties, and semantics that all destinations understand. Using standard events ensures compatibility across your entire marketing stack. ### Page & Browse Events | Event Name | When It Fires | Key Properties | | -------------------- | -------------------------------------------------------- | ------------------------------------- | | **page\_view** | Every page load | `pageUrl`, `pageTitle`, `referrer` | | **view\_content** | Product page viewed | `items`, `value`, `currency` | | **view\_category** | Collection or category page viewed | `items`, `value`, `currency` | | **view\_item\_list** | Product list displayed (search results, recommendations) | `items`, `listId`, `listName` | | **view\_cart** | Cart page viewed | `items`, `value`, `currency` | | **search** | Site search performed | `searchTerm`, `resultsCount`, `items` | ### Cart Events | Event Name | When It Fires | Key Properties | | -------------------------------- | ---------------------- | ---------------------------- | | **add\_to\_cart** | Item added to cart | `items`, `value`, `currency` | | **product\_removed\_from\_cart** | Item removed from cart | `items`, `value`, `currency` | | **add\_to\_wishlist** | Item added to wishlist | `items`, `value`, `currency` | ### Checkout Events | Event Name | When It Fires | Key Properties | | ---------------------------- | ------------------------ | -------------------------------------------- | | **initiate\_checkout** | Checkout flow started | `items`, `value`, `currency` | | **add\_shipping\_info** | Shipping details entered | `items`, `value`, `currency`, `shippingTier` | | **select\_shipping\_method** | Shipping method selected | `items`, `value`, `currency`, `shippingTier` | | **add\_payment\_info** | Payment method entered | `items`, `value`, `currency`, `paymentType` | ### Order Events | Event Name | When It Fires | Key Properties | | ------------ | -------------------------------- | ---------------------------------------------------------- | | **purchase** | Order completed | `orderId`, `items`, `value`, `currency`, `tax`, `shipping` | | **refund** | Order refunded (full or partial) | `orderId`, `items`, `value`, `currency` | ### Conversion Events | Event Name | When It Fires | Key Properties | | ----------------------- | ------------------------- | ---------------------------------- | | **lead** | Lead form submitted | `value`, `currency`, `leadType` | | **subscribe** | Email or SMS subscription | `value`, `currency` | | **trial\_started** | Free trial initiated | `value`, `currency`, `trialLength` | | **contact** | Contact form submitted | `value`, `currency` | | **book\_call** | Call or demo booked | `value`, `currency` | | **schedule** | Appointment scheduled | `value`, `currency` | | **submit\_application** | Application submitted | `value`, `currency` | ### Account Events | Event Name | When It Fires | Key Properties | | -------------------------- | ----------------------------------- | ------------------- | | **complete\_registration** | Account created (post-verification) | `value`, `currency` | | **sign\_up** | Sign-up form submitted | `value`, `currency` | | **login** | User logged in | — | ### Quiz Events | Event Name | When It Fires | Key Properties | | ---------------------------- | --------------------------------- | -------------------------------------------- | | **quiz\_completed** | Quiz or assessment finished | `quiz_id`, `result_id`, `questions_answered` | | **quiz\_question\_answered** | Individual quiz question answered | `quiz_id`, `question_id`, `answer_id` | <Note> Quiz events are **custom events** — fire them manually using the JavaScript SDK. See [quiz\_completed](/pixel/events/quiz-completed) and [quiz\_question\_answered](/pixel/events/quiz-question-answered) for implementation details. </Note> <Note> All standard events include automatic context fields — `pageUrl`, `userAgent`, `ipAddress`, `eventTime`, and identity signals — regardless of the event type. See [Properties](/pixel/properties) for the full reference. </Note> ## How Destinations Receive Events Each destination maps standard events to its own naming convention. For example, an Upstack `purchase` event becomes: * A Meta CAPI `Purchase` event with hashed `em`, `ph`, and `fbclid` match keys * A TikTok Events API `CompletePayment` event with `ttclid` attached * A Klaviyo `Placed Order` event with full product details * A GA4 `purchase` event with `transaction_id` and line items You configure which events each destination receives in the Upstack dashboard. Upstack handles the schema transformation automatically. ## What's Next <CardGroup> <Card title="Standard Events Reference" icon="list-check" href="/pixel/standard-events"> Full specification for every standard event — required properties, optional fields, and example payloads. </Card> <Card title="SaaS & B2B Events" icon="building" href="/pixel/saas-events"> Events for subscription businesses — trials, billing, expansion, and engagement. </Card> <Card title="Custom Events" icon="code" href="/pixel/events/custom-events"> Define your own events to capture interactions beyond the standard taxonomy. </Card> <Card title="Properties & Context" icon="table" href="/pixel/properties"> Complete reference for all user data, custom data, and context fields attached to events. </Card> <Card title="Identity & Stitching" icon="link" href="/pixel/identity-stitching"> How Upstack ID enriches events with resolved identity data. </Card> </CardGroup> # trial_started Event Source: https://docs.upstackdata.com/pixel/events/trial-started Track when a visitor begins a free trial Fires when a visitor begins a free trial. This is a key conversion event for SaaS and subscription businesses to track trial signups and optimize acquisition campaigns. <Note> **Shopify:** Manual implementation required. Integrate with your subscription/trial system. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'trial_started', { planName: 'Premium Plan', trialDays: 14, value: 49.99, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | --------- | ------ | -------- | -------------------------- | | planName | string | No | Trial plan or product name | | trialDays | number | No | Trial duration in days | | value | number | No | Plan value after trial | | currency | string | No | ISO 4217 currency code | ## When to Fire * Trial signup confirmation * Trial activation ## Related Events * [sign\_up](/pixel/events/sign-up) — For account creation * [purchase](/pixel/events/purchase) — When trial converts to paid # all_purchase Event Source: https://docs.upstackdata.com/pixel/events/upstack-generated/all-purchase Track all purchases with unified customer segmentation — automatically generated by Upstack <Info> **Automatically Generated** — This event is created by Upstack backend services for Shopify customers. You do not need to fire this event manually. </Info> ## Overview The `all_purchase` event is generated for every purchase, regardless of customer type. It provides a unified purchase event that includes customer segmentation metadata, making it ideal for destinations that need a single purchase event with segmentation data attached. ## How It Works When a purchase occurs, Upstack generates an `all_purchase` event alongside the standard `purchase` event: 1. **Order received** — Shopify sends a purchase webhook to Upstack 2. **Customer analysis** — Upstack determines customer type (new, returning, lapsed, etc.) 3. **Event generation** — An `all_purchase` event is created with segmentation metadata 4. **Forwarding** — The event is sent to configured destinations This event is useful when you want all purchases sent to a destination but still need to segment by customer type in your reporting. ## Properties This event includes all properties from the original `purchase` event: | Property | Type | Description | | -------- | ------ | ---------------------------------------- | | orderId | string | Shopify order ID | | value | number | Order total value | | currency | string | ISO 4217 currency code (e.g., `USD`) | | items | array | Products purchased | | email | string | Customer email (hashed for destinations) | | phone | string | Customer phone (hashed for destinations) | ## Destination Mapping This event is forwarded to destinations as: | Destination | Event Name | Notes | | --------------------- | ----------------- | ----------------------------------------- | | **Meta CAPI** | `Purchase` | Standard purchase with all customer types | | **Google Ads** | `purchase` | Unified purchase event | | **TikTok Events API** | `CompletePayment` | All purchases | | **Klaviyo** | `Placed Order` | All orders | | **GA4** | `purchase` | Standard e-commerce purchase | ## Use Cases * **Unified reporting** — Single event stream that includes all purchase types * **Destination simplification** — Send one purchase event type instead of managing multiple * **Consistent attribution** — Ensure all purchases contribute to campaign optimization equally * **Baseline metrics** — Track total purchases before segmenting by customer type ## Relationship to Other Events The `all_purchase` event represents the union of: * `nc_purchase` — New customer purchases * `rc_purchase` — Returning customer purchases Every purchase generates both an `all_purchase` event AND one of the customer-type-specific events (`nc_purchase` or `rc_purchase`). ## Related Events * [purchase](/pixel/standard-events#purchase) — The base purchase event * [nc\_purchase](/pixel/events/upstack-generated/nc-purchase) — New customer purchases only * [rc\_purchase](/pixel/events/upstack-generated/rc-purchase) — Returning customer purchases only # AOV Purchase Events Source: https://docs.upstackdata.com/pixel/events/upstack-generated/aov-events Track purchases segmented by average order value — automatically generated by Upstack <Info> **Automatically Generated** — These events are created by Upstack backend services for Shopify customers. You do not need to fire these events manually. </Info> ## Overview Upstack automatically generates AOV (Average Order Value) segmented purchase events based on your store's order value distribution. These events help you optimize campaigns for high-value customers and understand the revenue impact of different customer segments. ## Event Types | Event Name | Description | | ------------------- | ---------------------------------------------- | | `high_aov_purchase` | Purchase with above-average order value | | `low_aov_purchase` | Purchase with below-average order value | | `p70_aov_purchase` | Purchase above the 70th percentile order value | | `p80_aov_purchase` | Purchase above the 80th percentile order value | | `p90_aov_purchase` | Purchase above the 90th percentile order value | ## How It Works When a purchase occurs, Upstack calculates AOV thresholds based on your store's historical order data: 1. **Order received** — Shopify sends a purchase webhook to Upstack 2. **Threshold calculation** — Upstack computes percentile thresholds from your order history 3. **Classification** — The order value is compared against these thresholds 4. **Event generation** — The appropriate AOV event(s) are generated 5. **Forwarding** — Events are sent to your configured destinations ### Threshold Definitions | Event | Threshold Logic | | ------------------- | ------------------------------------------- | | `high_aov_purchase` | Order value > store's average order value | | `low_aov_purchase` | Order value ≤ store's average order value | | `p70_aov_purchase` | Order value > 70th percentile of all orders | | `p80_aov_purchase` | Order value > 80th percentile of all orders | | `p90_aov_purchase` | Order value > 90th percentile of all orders | <Note> Thresholds are calculated dynamically based on your store's recent order history. As your average order value changes, the classification adjusts automatically. </Note> ## Properties These events include all properties from the original `purchase` event: | Property | Type | Description | | -------- | ------ | ---------------------------------------- | | orderId | string | Shopify order ID | | value | number | Order total value | | currency | string | ISO 4217 currency code (e.g., `USD`) | | items | array | Products purchased | | email | string | Customer email (hashed for destinations) | | phone | string | Customer phone (hashed for destinations) | ## Destination Mapping AOV events are forwarded to destinations as: | Destination | Event Name | Notes | | --------------------- | ----------------- | -------------------------------- | | **Meta CAPI** | `Purchase` | With AOV segment in custom data | | **Google Ads** | `purchase` | Filterable by event name | | **TikTok Events API** | `CompletePayment` | AOV segment included | | **Klaviyo** | `Placed Order` | Tagged with AOV tier | | **GA4** | `purchase` | Custom dimension for AOV segment | ## Use Cases ### Optimize for High-Value Customers Use `high_aov_purchase` or `p90_aov_purchase` events to train ad algorithms to find customers who spend more: * Configure Meta CAPI to optimize for `high_aov_purchase` instead of all purchases * Build lookalike audiences from high-AOV customers * Set higher bids for campaigns driving premium purchases ### Identify Discount-Driven Traffic Use `low_aov_purchase` events to understand which channels drive bargain shoppers: * Compare high vs. low AOV by traffic source * Identify campaigns that attract discount-seekers * Adjust targeting to improve order values ### Revenue-Weighted Attribution Use percentile events for more accurate revenue attribution: * `p90_aov_purchase` — Focus on your most valuable 10% of orders * `p80_aov_purchase` — Track premium customer acquisition * `p70_aov_purchase` — Identify above-average performers ## Event Overlap A single purchase may generate multiple AOV events. For example, a purchase in the 95th percentile generates: * `high_aov_purchase` (above average) * `p70_aov_purchase` (above 70th percentile) * `p80_aov_purchase` (above 80th percentile) * `p90_aov_purchase` (above 90th percentile) Choose the threshold that best matches your optimization goals. ## Related Events * [purchase](/pixel/standard-events#purchase) — The base purchase event * [nc\_purchase](/pixel/events/upstack-generated/nc-purchase) — New customer purchases * [rc\_purchase](/pixel/events/upstack-generated/rc-purchase) — Returning customer purchases * [all\_purchase](/pixel/events/upstack-generated/all-purchase) — All purchases # Upstack-Generated Events Source: https://docs.upstackdata.com/pixel/events/upstack-generated/index Events automatically generated by Upstack backend for Shopify customers — purchase segmentation, AOV tiers, and subscription tracking <Info> **Automatically Generated** — All events in this section are created by Upstack backend services for Shopify customers. You do not need to fire these events manually — they appear in your destinations automatically based on purchase data analysis. </Info> ## Overview Upstack automatically generates enriched purchase events that segment your customers beyond the standard `purchase` event. These events enable more sophisticated ad optimization, better attribution, and deeper customer insights. When a purchase occurs in your Shopify store, Upstack's backend analyzes the order and customer history to generate additional events alongside the standard `purchase` event. ## Available Events ### Customer Type Events | Event | Description | Link | | ----------------- | -------------------------------------------- | ---------------------------------------------------------------- | | `nc_purchase` | New customer purchases (first-time buyers) | [Documentation](/pixel/events/upstack-generated/nc-purchase) | | `rc_purchase` | Returning customer purchases (repeat buyers) | [Documentation](/pixel/events/upstack-generated/rc-purchase) | | `all_purchase` | All purchases (combines NC + RC) | [Documentation](/pixel/events/upstack-generated/all-purchase) | | `lapsed_purchase` | Purchases from lapsed customers who returned | [Documentation](/pixel/events/upstack-generated/lapsed-purchase) | | `upsell_purchase` | Upsell conversions | [Documentation](/pixel/events/upstack-generated/upsell-purchase) | ### AOV-Segmented Events | Event | Description | Link | | ------------------- | ----------------------------------- | ----------------------------------------------------------- | | `high_aov_purchase` | Purchases above average order value | [Documentation](/pixel/events/upstack-generated/aov-events) | | `low_aov_purchase` | Purchases below average order value | [Documentation](/pixel/events/upstack-generated/aov-events) | | `p70_aov_purchase` | Purchases above 70th percentile | [Documentation](/pixel/events/upstack-generated/aov-events) | | `p80_aov_purchase` | Purchases above 80th percentile | [Documentation](/pixel/events/upstack-generated/aov-events) | | `p90_aov_purchase` | Purchases above 90th percentile | [Documentation](/pixel/events/upstack-generated/aov-events) | ### Subscription Events | Event | Description | Link | | --------------------------------- | --------------------------------- | ----------------------------------------------------------------------------- | | `subscription_initial_purchase` | First-time subscription purchases | [Documentation](/pixel/events/upstack-generated/subscription-purchase-events) | | `subscription_recurring_purchase` | Recurring subscription renewals | [Documentation](/pixel/events/upstack-generated/subscription-purchase-events) | ## How They Work ```mermaid theme={null} flowchart LR A[Shopify Webhook] --> B[Upstack Backend] B --> C{Customer Analysis} C --> D[NC/RC Classification] C --> E[AOV Segmentation] C --> F[Subscription Detection] C --> G[Lapsed Detection] D --> H[Destination Events] E --> H F --> H G --> H ``` 1. **Shopify sends a purchase webhook** to Upstack when an order is placed 2. **Upstack analyzes** the customer's order history, order value, and subscription status 3. **Multiple events are generated** based on the analysis (e.g., both `nc_purchase` and `high_aov_purchase` for a high-value first-time buyer) 4. **Events are forwarded** to your configured destinations with proper attribution ## Why Use These Events? ### Better Ad Optimization Instead of optimizing for all purchases equally, train ad algorithms to find: * **New customers** — Reduce wasted spend on existing customers * **High-AOV customers** — Find customers who spend more * **Subscription-likely customers** — Acquire subscribers with higher LTV ### More Accurate Attribution Understand which campaigns drive: * True customer acquisition (not just repeat purchases) * Premium customers (high AOV) * Subscription sign-ups vs. one-time purchases * Win-back conversions from lapsed customers ### Deeper Insights Compare performance across customer segments: * New vs. returning customer CAC * High vs. low AOV by channel * Subscription acquisition costs * Win-back campaign effectiveness ## Destination Support All Upstack-generated events are forwarded to your configured destinations: | Destination | Support | Notes | | ----------------- | ------- | ----------------------------------------- | | Meta CAPI | ✅ Full | Event name + custom data for segmentation | | Google Ads | ✅ Full | Filterable conversion events | | TikTok Events API | ✅ Full | Event name included | | Klaviyo | ✅ Full | Tagged events for segmentation | | GA4 | ✅ Full | Custom dimensions available | ## Getting Started These events are generated automatically for Shopify stores — no additional configuration needed. To use them: 1. **Check your destinations** — Ensure you have destinations configured in Upstack 2. **Configure event mapping** — Select which generated events to send to each destination 3. **Set up conversion tracking** — Configure your ad platforms to track these specific events 4. **Build reports** — Use the Upstack dashboard to compare metrics across event types <CardGroup> <Card title="New Customer Purchases" icon="user-plus" href="/pixel/events/upstack-generated/nc-purchase"> Optimize for customer acquisition </Card> <Card title="AOV Events" icon="chart-line" href="/pixel/events/upstack-generated/aov-events"> Segment by order value </Card> <Card title="Subscription Events" icon="repeat" href="/pixel/events/upstack-generated/subscription-purchase-events"> Track subscription metrics </Card> <Card title="Lapsed Purchases" icon="user-clock" href="/pixel/events/upstack-generated/lapsed-purchase"> Measure win-back campaigns </Card> </CardGroup> # lapsed_purchase Event Source: https://docs.upstackdata.com/pixel/events/upstack-generated/lapsed-purchase Track purchases from lapsed customers who returned — automatically generated by Upstack <Info> **Automatically Generated** — This event is created by Upstack backend services for Shopify customers. You do not need to fire this event manually. </Info> ## Overview The `lapsed_purchase` event is generated when a customer who hasn't purchased in an extended period returns to make a new purchase. This event helps you measure the effectiveness of win-back campaigns and understand customer reactivation patterns. ## How It Works Upstack analyzes customer purchase history to identify lapsed customer reactivations: 1. **Order received** — Shopify sends a purchase webhook to Upstack 2. **Recency analysis** — Upstack checks the time since the customer's last purchase 3. **Lapsed classification** — If the customer hasn't purchased in the lapsed threshold period, a `lapsed_purchase` event is generated 4. **Forwarding** — The event is sent to your configured destinations ### Lapsed Customer Definition A customer is classified as "lapsed" when their last purchase occurred more than **180 days ago** (approximately 6 months). This threshold aligns with common e-commerce customer lifecycle definitions. <Note> The 180-day lapsed threshold is based on industry standards for e-commerce. It distinguishes between returning customers (recent purchasers) and lapsed customers (dormant accounts that have been reactivated). </Note> ## Properties This event includes all properties from the original `purchase` event: | Property | Type | Description | | -------- | ------ | ---------------------------------------- | | orderId | string | Shopify order ID | | value | number | Order total value | | currency | string | ISO 4217 currency code (e.g., `USD`) | | items | array | Products purchased | | email | string | Customer email (hashed for destinations) | | phone | string | Customer phone (hashed for destinations) | ## Destination Mapping This event is forwarded to destinations as: | Destination | Event Name | Notes | | --------------------- | ----------------- | ------------------------------------------- | | **Meta CAPI** | `Purchase` | With `customer_type: lapsed` in custom data | | **Google Ads** | `purchase` | Filterable by event name | | **TikTok Events API** | `CompletePayment` | Lapsed flag included | | **Klaviyo** | `Placed Order` | Tagged as lapsed customer win-back | | **GA4** | `purchase` | Custom dimension for customer lifecycle | ## Use Cases * **Measure win-back performance** — Track how effectively your reactivation campaigns bring back dormant customers * **Calculate win-back CAC** — Understand the cost to reactivate a lapsed customer vs. acquiring a new one * **Optimize win-back timing** — Identify the optimal time to reach out to customers before they become permanently churned * **Segment audiences** — Build audiences of lapsed customers for targeted reactivation campaigns ## Metrics Available In the Upstack dashboard, you can view: | Metric | Description | | ------------------------ | ------------------------------------------------- | | Lapsed Purchases | Total number of lapsed customer purchase events | | Cost per Lapsed Purchase | Average ad spend per lapsed customer reactivation | | Lapsed Purchase Value | Total revenue from reactivated customers | ## Customer Lifecycle Context The `lapsed_purchase` event fits into the broader customer lifecycle: | Lifecycle Stage | Days Since Last Purchase | Event Generated | | --------------- | ------------------------ | ----------------- | | Active | 0–90 days | `rc_purchase` | | At Risk | 90–180 days | `rc_purchase` | | Lapsed | 180–365 days | `lapsed_purchase` | | Churned | 365+ days | `lapsed_purchase` | Both "Lapsed" and "Churned" customers generate `lapsed_purchase` events when they return, as the key insight is the reactivation of a dormant account. ## Related Events * [purchase](/pixel/standard-events#purchase) — The base purchase event * [nc\_purchase](/pixel/events/upstack-generated/nc-purchase) — New customer purchases * [rc\_purchase](/pixel/events/upstack-generated/rc-purchase) — Returning customer purchases * [all\_purchase](/pixel/events/upstack-generated/all-purchase) — All purchases # nc_purchase Event Source: https://docs.upstackdata.com/pixel/events/upstack-generated/nc-purchase Track purchases from first-time customers — automatically generated by Upstack <Info> **Automatically Generated** — This event is created by Upstack backend services for Shopify customers. You do not need to fire this event manually. </Info> ## Overview The `nc_purchase` (New Customer Purchase) event is generated when Upstack detects a purchase from a first-time customer. This event fires alongside the standard `purchase` event, enabling you to segment and optimize campaigns specifically for customer acquisition. ## How It Works When a purchase occurs, Upstack's backend analyzes the customer's order history: 1. **Order received** — Shopify sends a purchase webhook to Upstack 2. **Customer lookup** — Upstack checks if this customer ID has any previous orders 3. **Classification** — If this is the customer's first order, an `nc_purchase` event is generated 4. **Forwarding** — The event is sent to your configured destinations with proper attribution The classification happens server-side using Shopify's customer order history, ensuring accurate new customer detection even when cookies are blocked or the customer uses a different device. ## Properties This event includes all properties from the original `purchase` event: | Property | Type | Description | | -------- | ------ | ---------------------------------------- | | orderId | string | Shopify order ID | | value | number | Order total value | | currency | string | ISO 4217 currency code (e.g., `USD`) | | items | array | Products purchased | | email | string | Customer email (hashed for destinations) | | phone | string | Customer phone (hashed for destinations) | No additional properties are added — the event is the purchase event with a different event name for segmentation. ## Destination Mapping This event is forwarded to destinations as: | Destination | Event Name | Notes | | --------------------- | --------------------------- | -------------------------------------------- | | **Meta CAPI** | `Purchase` with custom data | Includes `customer_type: new` in custom data | | **Google Ads** | `purchase` | Can be filtered by event name in Google Ads | | **TikTok Events API** | `CompletePayment` | Event name included for segmentation | | **Klaviyo** | `Placed Order` | Tagged as new customer | | **GA4** | `purchase` | Custom dimension for customer type | ## Use Cases * **Optimize for acquisition** — Set up Meta campaigns optimizing specifically for new customer purchases rather than all purchases * **Measure true CAC** — Calculate cost per new customer acquisition more accurately * **Exclude retargeting** — Create audiences that exclude returning customers * **A/B test acquisition strategies** — Compare campaign performance on new customers only ## Why This Matters Many brands find that optimizing for all purchases leads to over-indexing on returning customers who would have purchased anyway. By sending `nc_purchase` events to ad platforms, you can: * Train algorithms to find net-new customers * Reduce wasted spend on existing customers * Get clearer signals on acquisition campaign performance ## Related Events * [purchase](/pixel/standard-events#purchase) — The base purchase event for all orders * [rc\_purchase](/pixel/events/upstack-generated/rc-purchase) — Returning customer purchases * [all\_purchase](/pixel/events/upstack-generated/all-purchase) — All purchases (combines NC + RC) # rc_purchase Event Source: https://docs.upstackdata.com/pixel/events/upstack-generated/rc-purchase Track purchases from returning customers — automatically generated by Upstack <Info> **Automatically Generated** — This event is created by Upstack backend services for Shopify customers. You do not need to fire this event manually. </Info> ## Overview The `rc_purchase` (Returning Customer Purchase) event is generated when Upstack detects a purchase from a customer who has ordered before. This event fires alongside the standard `purchase` event, enabling you to measure retention and optimize campaigns for repeat purchases. ## How It Works When a purchase occurs, Upstack's backend analyzes the customer's order history: 1. **Order received** — Shopify sends a purchase webhook to Upstack 2. **Customer lookup** — Upstack checks if this customer ID has any previous orders 3. **Classification** — If the customer has at least one previous order, an `rc_purchase` event is generated 4. **Forwarding** — The event is sent to your configured destinations with proper attribution The classification happens server-side using Shopify's customer order history, providing accurate returning customer detection regardless of browser cookies or device changes. ## Properties This event includes all properties from the original `purchase` event: | Property | Type | Description | | -------- | ------ | ---------------------------------------- | | orderId | string | Shopify order ID | | value | number | Order total value | | currency | string | ISO 4217 currency code (e.g., `USD`) | | items | array | Products purchased | | email | string | Customer email (hashed for destinations) | | phone | string | Customer phone (hashed for destinations) | No additional properties are added — the event is the purchase event with a different event name for segmentation. ## Destination Mapping This event is forwarded to destinations as: | Destination | Event Name | Notes | | --------------------- | --------------------------- | -------------------------------------------------- | | **Meta CAPI** | `Purchase` with custom data | Includes `customer_type: returning` in custom data | | **Google Ads** | `purchase` | Can be filtered by event name in Google Ads | | **TikTok Events API** | `CompletePayment` | Event name included for segmentation | | **Klaviyo** | `Placed Order` | Tagged as returning customer | | **GA4** | `purchase` | Custom dimension for customer type | ## Use Cases * **Measure retention** — Track how well retention and loyalty campaigns drive repeat purchases * **Optimize for LTV** — Train ad algorithms to find customers likely to purchase multiple times * **Retargeting performance** — Measure the true ROI of retargeting campaigns * **Segment reporting** — Compare new vs. returning customer metrics side by side ## Why This Matters Understanding your returning customer purchase rate helps you: * Balance acquisition vs. retention spend * Identify which channels drive the most loyal customers * Calculate customer lifetime value more accurately * Optimize campaigns for long-term revenue, not just first-time purchases ## Related Events * [purchase](/pixel/standard-events#purchase) — The base purchase event for all orders * [nc\_purchase](/pixel/events/upstack-generated/nc-purchase) — New customer purchases * [all\_purchase](/pixel/events/upstack-generated/all-purchase) — All purchases (combines NC + RC) * [lapsed\_purchase](/pixel/events/upstack-generated/lapsed-purchase) — Purchases from lapsed customers who returned # Subscription Purchase Events Source: https://docs.upstackdata.com/pixel/events/upstack-generated/subscription-purchase-events Track subscription purchases — automatically generated by Upstack <Info> **Automatically Generated** — These events are created by Upstack backend services for Shopify customers. You do not need to fire these events manually. </Info> ## Overview Upstack automatically generates subscription purchase events for stores using subscription apps like Recharge, Bold Subscriptions, Skio, or native Shopify Subscriptions. These events help you measure subscription acquisition, retention, and recurring revenue. ## Event Types | Event Name | Description | | --------------------------------- | ------------------------------------------------- | | `subscription_initial_purchase` | First-time subscription purchase (new subscriber) | | `subscription_recurring_purchase` | Recurring subscription renewal | ## How It Works When a subscription order is processed, Upstack analyzes the order metadata: 1. **Order received** — Shopify sends a purchase webhook to Upstack 2. **Subscription detection** — Upstack checks for subscription app tags and order properties 3. **Classification** — The order is classified as initial or recurring based on the subscription data 4. **Event generation** — The appropriate subscription event is generated 5. **Forwarding** — Events are sent to your configured destinations ### Detection Methods Upstack identifies subscription orders through: * Order tags from subscription apps (e.g., `subscription_first_order`, `recurring_order`) * Order properties and line item properties containing subscription metadata * Subscription app-specific identifiers in the order data <Note> Subscription detection works with most major Shopify subscription apps including Recharge, Bold Subscriptions, Skio, Loop Subscriptions, and native Shopify Subscriptions. </Note> ## subscription\_initial\_purchase Generated when a customer signs up for a new subscription. This is the first order in a subscription sequence. ### Use Cases * **Measure subscriber acquisition** — Track how many new subscribers you're acquiring * **Calculate subscriber CAC** — Understand the true cost to acquire a subscriber * **Optimize acquisition campaigns** — Train ad algorithms to find subscription-likely customers * **Attribution for LTV** — Attribute the full potential LTV to the acquiring campaign ## subscription\_recurring\_purchase Generated for each recurring subscription renewal. This includes all orders after the initial subscription purchase. ### Use Cases * **Track subscription retention** — Monitor recurring revenue from existing subscribers * **Measure churn impact** — Understand when recurring purchases decline * **Attribution for retention campaigns** — Track which campaigns drive continued engagement * **Revenue forecasting** — Use recurring purchase data to predict future revenue ## Properties Both events include all properties from the original `purchase` event: | Property | Type | Description | | -------- | ------ | ---------------------------------------- | | orderId | string | Shopify order ID | | value | number | Order total value | | currency | string | ISO 4217 currency code (e.g., `USD`) | | items | array | Products purchased | | email | string | Customer email (hashed for destinations) | | phone | string | Customer phone (hashed for destinations) | ## Destination Mapping Subscription events are forwarded to destinations as: | Destination | Event Name | Notes | | --------------------- | ----------------- | --------------------------------------- | | **Meta CAPI** | `Purchase` | With `subscription_type` in custom data | | **Google Ads** | `purchase` | Filterable by event name | | **TikTok Events API** | `CompletePayment` | Subscription flag included | | **Klaviyo** | `Placed Order` | Tagged with subscription type | | **GA4** | `purchase` | Custom dimension for subscription | ## Metrics Available In the Upstack dashboard, you can view: | Metric | Description | | -------------------------------- | ------------------------------ | | Subscription Initial Purchases | New subscription sign-ups | | Cost per Subscription Initial | CAC for new subscribers | | Subscription Initial Value | Revenue from new subscriptions | | Subscription Recurring Purchases | Renewal orders | | Cost per Subscription Recurring | Cost attributed to renewals | | Subscription Recurring Value | Recurring subscription revenue | ## Subscription vs. SaaS Events <Note> **Important distinction:** These events (`subscription_initial_purchase`, `subscription_recurring_purchase`) are for e-commerce subscription boxes and recurring product purchases. For SaaS subscription lifecycle events (plan changes, trials, etc.), see [SaaS Events](/pixel/saas-events). </Note> | Event Type | Use For | | --------------------------------- | ---------------------------------------------- | | `subscription_initial_purchase` | E-commerce: First subscription box order | | `subscription_recurring_purchase` | E-commerce: Recurring subscription box renewal | | `subscription_started` | SaaS: New software subscription | | `subscription_created` | SaaS: Subscription record created | ## Related Events * [purchase](/pixel/standard-events#purchase) — The base purchase event * [nc\_purchase](/pixel/events/upstack-generated/nc-purchase) — New customer purchases * [rc\_purchase](/pixel/events/upstack-generated/rc-purchase) — Returning customer purchases * [all\_purchase](/pixel/events/upstack-generated/all-purchase) — All purchases * [SaaS Events](/pixel/saas-events) — SaaS subscription lifecycle events # upsell_purchase Event Source: https://docs.upstackdata.com/pixel/events/upstack-generated/upsell-purchase Track upsell conversions — automatically generated by Upstack <Info> **Automatically Generated** — This event is created by Upstack backend services for Shopify customers. You do not need to fire this event manually. </Info> ## Overview The `upsell_purchase` event is generated when Upstack detects a purchase that resulted from an upsell opportunity. This event helps you measure the effectiveness of upsell campaigns, post-purchase offers, and cross-sell strategies. ## How It Works Upstack analyzes purchase patterns to identify upsell conversions: 1. **Order received** — Shopify sends a purchase webhook to Upstack 2. **Upsell detection** — Upstack checks for upsell indicators (multiple items, upgraded variants, post-purchase additions) 3. **Event generation** — If upsell criteria are met, an `upsell_purchase` event is generated 4. **Forwarding** — The event is sent to your configured destinations ### Upsell Classification A purchase is classified as an upsell when: * The order contains items added through post-purchase offers * The customer upgraded to a higher-tier product variant * The order includes cross-sell items from upsell campaigns * The purchase occurred during a returning customer's session with additional items beyond their typical basket ## Properties This event includes all properties from the original `purchase` event: | Property | Type | Description | | -------- | ------ | ---------------------------------------- | | orderId | string | Shopify order ID | | value | number | Order total value | | currency | string | ISO 4217 currency code (e.g., `USD`) | | items | array | Products purchased | | email | string | Customer email (hashed for destinations) | | phone | string | Customer phone (hashed for destinations) | ## Destination Mapping This event is forwarded to destinations as: | Destination | Event Name | Notes | | --------------------- | ----------------- | ---------------------------------- | | **Meta CAPI** | `Purchase` | With `upsell: true` in custom data | | **Google Ads** | `purchase` | Filterable by event name | | **TikTok Events API** | `CompletePayment` | Upsell flag included | | **Klaviyo** | `Placed Order` | Tagged as upsell | | **GA4** | `purchase` | Custom dimension for upsell | ## Use Cases * **Measure upsell effectiveness** — Track how often upsell offers convert and their revenue impact * **Optimize upsell timing** — Identify which campaigns or touchpoints drive the most upsell conversions * **Calculate upsell ROI** — Compare ad spend to upsell revenue for campaign optimization * **A/B test offers** — Measure which upsell offers perform best by tracking conversion rates ## Metrics Available In the Upstack dashboard, you can view: | Metric | Description | | ------------------------ | -------------------------------------- | | Upsell Purchases | Total number of upsell purchase events | | Cost per Upsell Purchase | Average ad spend per upsell conversion | | Upsell Purchase Value | Total revenue from upsell purchases | ## Related Events * [purchase](/pixel/standard-events#purchase) — The base purchase event * [rc\_purchase](/pixel/events/upstack-generated/rc-purchase) — Returning customer purchases * [all\_purchase](/pixel/events/upstack-generated/all-purchase) — All purchases * [AOV Events](/pixel/events/upstack-generated/aov-events) — Purchase segmentation by order value # view_cart Event Source: https://docs.upstackdata.com/pixel/events/view-cart Track when a visitor views their shopping cart Fires when a visitor views their shopping cart. This helps track cart abandonment and build remarketing audiences for shoppers who haven't completed checkout. <Note> **Shopify:** Automatically tracked when the cart page or cart drawer is viewed. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'view_cart', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2 }, { id: 'SKU_67890', name: 'Running Socks', price: 14.99, quantity: 1 } ], value: 84.97, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | ------------------------------------------------------------------------ | | items | array | Yes | Products in cart (see [Item Object](/pixel/standard-events#item-object)) | | value | number | No | Total cart value | | currency | string | No | ISO 4217 currency code | ## When to Fire * Cart page load * Cart drawer/sidebar open * Mini-cart expansion ## Related Events * [add\_to\_cart](/pixel/events/add-to-cart) — When adding items to cart * [product\_removed\_from\_cart](/pixel/events/product-removed-from-cart) — When removing items * [initiate\_checkout](/pixel/events/initiate-checkout) — When starting checkout # view_category Event Source: https://docs.upstackdata.com/pixel/events/view-category Track when a visitor views a collection or category page Fires when a visitor views a collection or category page. Use this to track browsing behavior and build category-based audiences. <Note> **Shopify:** Automatically tracked when viewing collection pages. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'view_category', { items: [ { id: 'SKU_001', name: 'Classic Cotton Tee', price: 34.99 }, { id: 'SKU_002', name: 'Vintage Logo Hoodie', price: 59.99 }, { id: 'SKU_003', name: 'Slim Fit Jeans', price: 79.99 } ], itemListId: 'summer_collection', itemListName: 'Summer 2026 Collection' }); ``` Minimal example: ```javascript theme={null} window._upstack('track', 'view_category', { itemListId: 'mens_shirts', itemListName: 'Men\'s Shirts' }); ``` ## Properties | Property | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------------------------------------------------------------- | | itemListId | string | No | Collection/category identifier | | itemListName | string | No | Collection/category display name | | items | array | No | Products shown in the category (see [Item Object](/pixel/standard-events#item-object)) | ## When to Fire * Collection page load * Category filter applied * Browse by category navigation ## Related Events * [view\_content](/pixel/events/view-content) — When viewing an individual product * [view\_item\_list](/pixel/events/view-item-list) — For general product lists (recommendations, etc.) * [search](/pixel/events/search) — When viewing search results # view_content Event Source: https://docs.upstackdata.com/pixel/events/view-content Track when a visitor views a product or content page Fires when a visitor views a product or content page. This event is critical for remarketing audiences and conversion attribution. <Note> **Shopify:** Automatically tracked when viewing product detail pages. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'view_content', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, brand: 'Example Brand', category: 'Apparel/T-Shirts' } ], value: 34.99, currency: 'USD' }); ``` Minimal example: ```javascript theme={null} window._upstack('track', 'view_content', { items: [{ id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99 }], value: 34.99, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | ----------------------------------------------------------------------- | | items | array | Yes | Products viewed (see [Item Object](/pixel/standard-events#item-object)) | | value | number | Yes | Product price | | currency | string | Yes | ISO 4217 currency code (e.g., `'USD'`) | ## When to Fire * Product detail page load * Quick view modal open * Collection page load (with collection products) ## Related Events * [add\_to\_cart](/pixel/events/add-to-cart) — When adding the viewed product to cart * [add\_to\_wishlist](/pixel/events/add-to-wishlist) — When saving the product for later * [view\_category](/pixel/events/view-category) — When viewing a collection page # view_item_list Event Source: https://docs.upstackdata.com/pixel/events/view-item-list Track when a visitor views a list of products Fires when a visitor views a list of products. This is similar to `view_category` but more general — use it for recommendation carousels, recently viewed sections, and other product lists. <Note> **Shopify:** Manual implementation required. Not automatically tracked. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'view_item_list', { items: [ { id: 'SKU_001', name: 'Classic Cotton Tee', price: 34.99, index: 0 }, { id: 'SKU_002', name: 'Vintage Logo Hoodie', price: 59.99, index: 1 } ], itemListId: 'recommended_products', itemListName: 'Recommended For You' }); ``` ## Properties | Property | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------------------------ | | itemListId | string | No | List identifier | | itemListName | string | No | List display name | | items | array | No | Products in the list (include `index` for position tracking) | ## When to Fire * Product recommendation carousel load * "Related Products" section view * "Recently Viewed" section view * Search results page load ## Related Events * [view\_category](/pixel/events/view-category) — For collection/category pages * [view\_content](/pixel/events/view-content) — When clicking through to a product * [search](/pixel/events/search) — For search results specifically # Upstack Data Glossary: Key Terms Explained Source: https://docs.upstackdata.com/pixel/glossary Glossary of Upstack Data terminology — attribution, CAPI, EMQ, identity resolution, destinations, server-side tracking, and other key concepts explained. | Term | Definition | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Attribution** | The process of assigning credit for a conversion to one or more marketing touchpoints. | | **CAPI** | Conversions API — a server-to-server integration for sending events to ad platforms (Meta, TikTok, etc.) without relying on browser cookies. | | **Click ID** | A unique identifier appended to URLs by ad platforms (e.g., `fbclid` for Meta, `ttclid` for TikTok, `gclid` for Google) used to match conversions to ad clicks. | | **Conversion** | A completed action that represents business value, most commonly a purchase. | | **Custom event** | A merchant-defined event tracked via the Upstack JavaScript SDK, beyond the 12 standard events. | | **Destination** | A third-party platform that receives enriched event data from Upstack (e.g., Meta CAPI, Klaviyo, GA4). | | **EMQ** | Event Match Quality — Meta's score (0–10) indicating how well your server events can be matched to Facebook users. Higher EMQ = better ad optimization. | | **Enrichment** | The process of augmenting raw events with additional data: product catalog details, UTM parameters, identity signals, and session context. | | **Event** | A structured record of a customer interaction — a pageview, add-to-cart, purchase, or any custom action. | | **Identity resolution** | Matching anonymous visitor sessions to known customer profiles using deterministic (email, phone) and probabilistic (fingerprint, device) signals. | | **Identity stitching** | Linking multiple sessions and devices belonging to the same person into a unified customer profile. | | **Match rate** | The percentage of server-side events that an ad platform can match to users on its network. Higher match rates improve ad optimization. | | **PII** | Personally Identifiable Information — data like email and phone number. Upstack hashes PII (SHA-256) before sending to ad platforms. | | **Pixel** | A lightweight JavaScript snippet injected into your storefront that captures browser-side events and sends them to the Upstack edge API. | | **ROAS** | Return on Ad Spend — revenue generated divided by ad spend. Upstack helps improve ROAS by providing higher-quality conversion data to ad platforms. | | **Server-side tracking** | Capturing events via server-to-server communication rather than browser-based JavaScript, making tracking resilient to ad blockers and cookie restrictions. | | **Source** | A platform or integration that sends data into Upstack (e.g., Shopify storefront, Facebook Ads, Google Ads). | | **Standard event** | One of the 12 predefined event types that Upstack recognizes across all destinations (page\_view, purchase, add\_to\_cart, etc.). | | **UTM parameters** | URL query parameters (`utm_source`, `utm_medium`, `utm_campaign`, etc.) used to identify traffic sources and campaigns. | | **Webhook** | An HTTP callback that delivers event data to an external URL in real time. | # Understanding Identity Resolution Source: https://docs.upstackdata.com/pixel/identity-resolution Upstack ID stitches anonymous sessions into unified customer profiles via deterministic and probabilistic matching — improving CAPI match quality. Identity resolution is the process of recognizing that the person browsing on a phone, clicking an ad on a laptop, and completing a purchase on a tablet is the same customer. <Info> **This page covers conceptual understanding** — how identity resolution works, why it matters, and key terminology. For technical details about the identity fields on events and session stitching mechanics, see [Identity & Stitching](/pixel/identity-stitching). </Info> <Note> **Works on all implementations** — Identity resolution works with Shopify, headless storefronts, and custom websites. Anywhere the Upstack pixel is installed, Upstack ID can resolve identities. </Note> <Tip> Merchants using Upstack ID see 30–60% more identified sessions, which directly improves retargeting audience size and conversion API match quality. </Tip> ## Why It Matters Most website visitors browse anonymously. They arrive from an ad, view products, leave, and return days later on a different device. Without identity resolution, each visit looks like a separate person — your attribution data fragments, retargeting audiences shrink, and conversion APIs send events with weak identity signals. The problem intensifies in a privacy-first world. Third-party cookies are disappearing, mobile identifiers are gated behind consent prompts, and cross-domain tracking is increasingly blocked. Merchants need a first-party identity layer that works within these constraints while still connecting the dots across the customer journey. Strong identity resolution also compounds the value of every other part of your data stack. Enrichment becomes more accurate when attached to a unified profile. Conversion API match quality (EMQ) rises when events carry hashed email, phone, and address. Attribution models produce meaningful results only when they can follow a single customer across touchpoints. ## How It Works Upstack ID operates at the **Resolve** stage of the data pipeline, immediately after raw events are captured by Upstack Pixel. The resolution engine uses a layered matching strategy: * **Deterministic matching** — When a visitor logs in, enters an email at checkout, or clicks a Klaviyo email link, Upstack ID creates a hard link between the anonymous session cookie and the known customer identifier. These matches are exact and high-confidence. * **Session stitching** — Events within the same browsing session are grouped using the first-party cookie set by Upstack Pixel. As soon as any event in the session is identified (e.g., checkout), all prior anonymous events in that session are retroactively attributed to the same customer. * **Cross-device linking** — When the same email or phone appears across sessions on different devices, Upstack ID merges those profiles into a single identity graph node. Future events on any linked device are automatically resolved. * **Probabilistic signals** — Browser fingerprint attributes (viewport, language, timezone, installed fonts) serve as weak tiebreakers when deterministic identifiers are absent. These signals are never used alone — they only reinforce existing deterministic links. All matching happens server-side within the AWS backend, ensuring PII is never exposed to client-side scripts or third-party tags. ## Key Terms | Term | Definition | | -------------------------- | ------------------------------------------------------------------------------------------------------------------- | | **Identity graph** | A data structure that maps all known identifiers (email, phone, cookie, device) to a single customer profile. | | **Deterministic matching** | Linking sessions using exact identifiers like email or phone number. | | **Probabilistic matching** | Using weaker signals (browser attributes, timing patterns) to suggest — not confirm — an identity link. | | **Session stitching** | Retroactively attributing anonymous events to a known customer after identification occurs within the same session. | | **Cross-device linking** | Merging profiles when the same identifier appears on different devices or browsers. | ## Related Documentation <CardGroup> <Card title="Identity & Stitching" icon="link" href="/pixel/identity-stitching"> Technical details: identity fields on events, session stitching mechanics. </Card> <Card title="JavaScript SDK" icon="code" href="/pixel/javascript-sdk#identifyuserid-data"> How to call identify() to associate user identity with sessions. </Card> <Card title="Server-Side Tracking" icon="server" href="/concepts/server-side-tracking"> How Upstack Pixel captures the raw events that feed identity resolution. </Card> <Card title="Connect a Destination" icon="plug" href="/get-started/connect-a-destination"> Forward identity-enriched events to ad platforms for higher match quality. </Card> </CardGroup> # How Session Stitching Works Source: https://docs.upstackdata.com/pixel/identity-stitching How Upstack ID attaches resolved identity to events, stitches anonymous sessions retroactively, and improves destination match quality (EMQ 7-9). Every event Upstack captures starts with whatever identity signals the visitor provides — often just an IP address and browser cookie. Upstack ID enriches these events with resolved identity data, connecting anonymous sessions to known customers and dramatically improving the quality of data sent to your destinations. <Info> **This page covers technical implementation** — the identity fields on events, how session stitching works, and the impact on destination match quality. For a conceptual overview of identity resolution and how the identity graph works, see [Identity Resolution](/pixel/identity-resolution). </Info> <Tip> Events that pass through identity resolution carry 3–5x more match keys on average. This directly translates to higher EMQ scores on Meta, better audience match rates on TikTok, and more accurate attribution. </Tip> ## Identity Fields on Events After identity resolution, events carry these identity-related fields: | Field | Location | Description | | ------------------- | ----------- | ---------------------------------------------------------------------------------- | | `session_id` | Event root | Groups all events within a single browsing session. Set by the first-party cookie. | | `identity_id` | Event root | The resolved Upstack identity ID. Present once the visitor has been identified. | | `em` | `user_data` | SHA-256 hashed email address. | | `ph` | `user_data` | SHA-256 hashed phone number. | | `external_id` | `user_data` | Shopify customer ID or other external identifier. | | `fbc` | `user_data` | Meta click ID cookie linking the session to an ad click. | | `fbp` | `user_data` | Meta browser ID cookie for cross-session continuity. | | `ttclid` | `user_data` | TikTok click ID for ad attribution. | | `gclid` | `user_data` | Google click ID for ad attribution. | | `client_ip_address` | `user_data` | Visitor IP address. | | `client_user_agent` | `user_data` | Browser user agent string. | ## How Identity Attaches to Events Identity resolution happens at the **Resolve** stage of the pipeline, between event capture and destination forwarding. ### 1. First-Party Cookie Matching When a visitor lands on your store, the Upstack Pixel sets a first-party cookie. Every event in that browsing session shares the same `session_id`. If the visitor has been seen before (returning visitor), the cookie links to their existing identity profile. ### 2. Deterministic Identification When a visitor provides a hard identifier — logging in, entering an email at checkout, clicking a Klaviyo email link — Upstack ID creates a deterministic match: * The `session_id` is linked to the customer's `identity_id` * `em` (hashed email) and `ph` (hashed phone) are attached to the event * `external_id` is set from the Shopify customer ID ### 3. Session Stitching This is where the real value emerges. When identification happens mid-session (e.g., at checkout), Upstack ID retroactively enriches all **prior anonymous events in that session** with the resolved identity data. A typical session flow: | Event | Before Stitching | After Stitching | | -------------------------- | ----------------------------- | --------------------------------------------- | | PageView (homepage) | IP + user agent only | IP + user agent + `em` + `ph` + `identity_id` | | ViewContent (product page) | IP + user agent only | IP + user agent + `em` + `ph` + `identity_id` | | AddToCart | IP + user agent only | IP + user agent + `em` + `ph` + `identity_id` | | InitiateCheckout | IP + user agent + `em` + `ph` | IP + user agent + `em` + `ph` + `identity_id` | | Purchase | IP + user agent + `em` + `ph` | IP + user agent + `em` + `ph` + `identity_id` | Without stitching, the PageView, ViewContent, and AddToCart events would be forwarded to destinations with weak identity signals. With stitching, every event in the session carries the full set of match keys. <Note> Session stitching is retroactive within the session. Events are held briefly in the pipeline to allow late-arriving identity data to propagate. The hold window is short enough to maintain near-real-time forwarding. </Note> ### 4. Cross-Device Linking When the same email or phone appears across sessions on different devices, Upstack ID merges those sessions under a single `identity_id`. A shopper who browses on mobile and purchases on desktop is recognized as one customer. Cross-device linking enables: * Accurate attribution across devices * Larger retargeting audiences (one profile instead of two) * Complete customer journey visibility in analytics ## Impact on Destination Match Quality Identity resolution directly drives the match keys available for each destination: | Destination | Key Match Fields | Typical EMQ Without Stitching | Typical EMQ With Stitching | | --------------------- | ---------------------------------------- | ----------------------------- | -------------------------- | | **Meta CAPI** | `em`, `ph`, `fbc`, `fbp`, IP, user agent | 3–5 | 7–9 | | **TikTok Events API** | `em`, `ph`, `ttclid`, IP, user agent | 2–4 | 6–8 | | **Klaviyo** | `em`, `ph` | Partial profiles | Complete profiles | | **GA4** | `client_id`, `user_id` | Anonymous only | Identified users | The difference is especially pronounced for upper-funnel events (PageView, ViewContent) that typically fire before the visitor has identified themselves. Session stitching ensures these events reach destinations with full identity data. <Warning> Identity resolution depends on the visitor eventually identifying themselves within the session. Fully anonymous sessions (no login, no checkout, no email link click) cannot be resolved. The identification rate varies by store — typically 30–60% of sessions are resolved. </Warning> ## How This Connects to the Broader Pipeline Identity resolution sits between event capture and destination forwarding: 1. **Capture** — Upstack Pixel fires raw events with whatever signals are available. 2. **Resolve** — Upstack ID attaches identity, stitches sessions, and links devices. *(You are here.)* 3. **Enrich** — Product catalog data and UTM parameters are merged. 4. **Activate** — Identity-enriched events are forwarded to destinations with maximum match keys. For a deeper dive into how identity resolution works at the infrastructure level, see the [Identity Resolution](/pixel/identity-resolution) concept page. ## Related Documentation <CardGroup> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> Conceptual overview: identity graph, deterministic matching, cross-device linking. </Card> <Card title="JavaScript SDK" icon="code" href="/pixel/javascript-sdk#identifyuserid-data"> How to call identify() to associate user identity with sessions. </Card> <Card title="Properties & Context" icon="table" href="/pixel/properties"> Full reference for all identity fields, custom data, and context on events. </Card> <Card title="Standard Events" icon="list-check" href="/pixel/standard-events"> Events that carry identity data after resolution. </Card> </CardGroup> # Upstack Data Pixel: Event Tracking Overview Source: https://docs.upstackdata.com/pixel/index Track customer events, capture identity, and forward data to ad platforms with the Upstack Data JavaScript pixel. Quick setup and full SDK reference. ## Overview The Upstack Pixel is a JavaScript library that enables you to track user behavior, capture events, and identify users on your website. <Note> **Works everywhere** — The Upstack Pixel runs on Shopify stores, headless storefronts, custom websites, and any platform where you can add JavaScript. </Note> <CardGroup> <Card title="Quick Start" icon="rocket" href="/pixel/setup"> Install the pixel in 5 minutes </Card> <Card title="JavaScript SDK" icon="code" href="/pixel/javascript-sdk"> Full SDK reference </Card> <Card title="Standard Events" icon="list" href="/pixel/standard-events"> E-commerce event reference </Card> <Card title="Event Properties" icon="database" href="/pixel/properties"> All available properties </Card> </CardGroup> *** ## Feature Availability by Platform Not all features work the same across platforms. Here's what's automatic vs manual: | Feature | Shopify | Headless / Custom / GTM | | ---------------------------------- | ----------- | ------------------------------------- | | `page_view` tracking | ✅ Automatic | Manual — call `_upstack('page')` | | `view_content` on product pages | ✅ Automatic | Manual — fire on product page load | | `add_to_cart` events | ✅ Automatic | Manual — fire on cart add | | `initiate_checkout` | ✅ Automatic | Manual — fire on checkout start | | `purchase` events | ✅ Automatic | Manual — fire on order confirmation | | Form capture (Klaviyo, Postscript) | ✅ Automatic | ✅ Automatic (when both installed) | | Custom events | ✅ Manual | ✅ Manual | | Identity resolution | ✅ Automatic | ✅ Automatic (after `identify()` call) | | `nc_purchase` / `rc_purchase` | ✅ Automatic | ❌ Shopify only | <Info> **Shopify merchants:** The theme app extension handles most tracking automatically. You only need the JavaScript SDK for custom events or advanced use cases. **Custom implementations:** Use the [JavaScript SDK Reference](/pixel/javascript-sdk) and [Standard Events](/pixel/standard-events) to implement tracking manually. </Info> # Upstack Data JavaScript SDK Reference Source: https://docs.upstackdata.com/pixel/javascript-sdk Complete API reference for the Upstack Data JavaScript SDK. Covers all 6 queue commands, 2 direct client methods, TypeScript support, and usage patterns. The Upstack JavaScript SDK provides client-side event tracking, user identification, and session management. It captures browsing behavior, resolves user identity across devices, and forwards events to your configured destinations. <Warning> **Important:** The correct global is `window._upstack()` (with underscore), not `window.upstack()`. Older documentation may reference the incorrect name. </Warning> ## Installation The Upstack pixel is distributed via CDN, not npm. Add this snippet to your site's `<head>`: ```html theme={null} <script> window._upstack = window._upstack || function() { (window._upsqueue = window._upsqueue || []).push(arguments); }; _upstack('init', 'YOUR_PIXEL_ID'); </script> <script async src="https://prod2-cdn.upstackified.com/scripts/px/ups.min.js"></script> ``` **Why this works:** 1. The inline script defines `_upstack()` as a function that pushes calls to a queue 2. Calls made before the SDK loads are queued — no events are lost 3. Once the SDK loads, it processes the queue and replaces `_upstack()` with the real implementation 4. Safe to call immediately without checking load status ## API Overview | Method | Via Queue | Via Direct Client | Description | | -------------- | ---------------- | ----------------- | --------------------------------- | | `init` | ✅ (pixelId only) | ✅ | Initialize the pixel | | `page` | ✅ | ✅ | Track page views | | `track` | ✅ | ✅ | Track custom events | | `identify` | ✅ | ✅ | Associate user identity | | `metric` | ✅ | ✅ | Send metrics (currently disabled) | | `reset` | ✅ | ✅ | Clear identity state | | `isKnown` | ❌ | ✅ | Check if user is identified | | `getUpstackId` | ❌ | ✅ | Get Upstack ID object | *** ## Queue Commands These methods can be called via `_upstack('command', ...)` before or after the SDK loads. ### init(pixelId) Initialize the Upstack pixel with your pixel ID. ```typescript theme={null} function init( pixelId: string, identityTraits?: EventIdentityTraits, scriptSource?: 'js' | 'shopify_js' | 'shopify_ext' ): Promise<{ isInitialized: boolean; isDisabled: boolean }> ``` **Parameters:** | Parameter | Type | Required | Description | | ---------------- | --------------------- | -------- | ---------------------------------------------------------------- | | `pixelId` | `string` | Yes | Your Upstack pixel ID from the dashboard (starts with `px_`) | | `identityTraits` | `EventIdentityTraits` | No | Pre-populate identity on init | | `scriptSource` | `string` | No | Script origin: `'js'` (default), `'shopify_js'`, `'shopify_ext'` | <Warning> **Queue Limitation:** When using `_upstack('init', pixelId, identityTraits, scriptSource)`, only `pixelId` is passed to the init function. The `identityTraits` and `scriptSource` parameters are dropped by the queue processor. For full init with identity traits, use the direct client after the script loads. </Warning> **Examples:** ```javascript theme={null} // Basic initialization via queue (recommended) _upstack('init', 'px_abc123def456'); // Full init with identity traits (requires direct client) // Wait for script to load first if (window._upsClient) { await window._upsClient.init('px_abc123def456', { emails: ['user@example.com'] }, 'js'); } ``` *** ### page(eventData?) Track a page view. Automatically captures page URL, title, referrer, and path. ```typescript theme={null} function page(eventData?: Record<string, unknown>): void ``` **Parameters:** | Parameter | Type | Required | Description | | ----------- | -------- | -------- | ----------------------------------------------- | | `eventData` | `object` | No | Custom properties to include with the page view | **Auto-captured properties:** * `page_url` — Current page URL * `page_title` — Document title * `page_referrer` — Referring URL * `page_path` — URL path **Examples:** ```javascript theme={null} // Basic page view _upstack('page'); // With custom properties _upstack('page', { page_category: 'product', product_id: 'SKU123', collection: 'summer-2026' }); ``` *** ### track(eventName, eventData?, ...) Track a custom event. Supports 7 positional parameters plus a shorthand for `useBeacon`. ```typescript theme={null} function track( eventName: string, eventData?: Record<string, unknown>, eventId?: string, contextOverride?: Record<string, unknown>, collectedAt?: string, // ISO 8601 timestamp collectedAtEpoch?: number, // Unix epoch milliseconds options?: TrackOptions ): void interface TrackOptions { useBeacon?: boolean; // Use navigator.sendBeacon() for page unload } ``` **Parameters:** | Parameter | Type | Required | Description | | ------------------ | -------------- | -------- | --------------------------------------------------------------- | | `eventName` | `string` | Yes | Event name in snake\_case (e.g., `'add_to_cart'`, `'purchase'`) | | `eventData` | `object` | No | Event properties | | `eventId` | `string` | No | Unique ID for deduplication across destinations | | `contextOverride` | `object` | No | Override page/session context for this event | | `collectedAt` | `string` | No | ISO 8601 timestamp for backdated events | | `collectedAtEpoch` | `number` | No | Unix epoch milliseconds for backdated events | | `options` | `TrackOptions` | No | `{ useBeacon: boolean }` for page unload tracking | **Shorthand for useBeacon:** When the 4th argument is an object with `useBeacon`, it's treated as options: ```javascript theme={null} // Shorthand (recommended for useBeacon) _upstack('track', 'lead', { email: 'user@example.com' }, { useBeacon: true }); // Full positional form (7 parameters) _upstack('track', 'lead', { email: 'user@example.com' }, null, null, null, null, { useBeacon: true }); ``` **Examples:** ```javascript theme={null} // Basic tracking _upstack('track', 'add_to_cart', { items: [{ id: 'SKU123', name: 'Widget', price: 29.99, quantity: 1 }], value: 29.99, currency: 'USD' }); // With deduplication ID (prevents duplicate events at destinations) _upstack('track', 'purchase', { items: [{ id: 'SKU123', name: 'Widget', price: 29.99, quantity: 1 }], value: 29.99, order_id: 'ORD-456', currency: 'USD' }, 'ORD-456'); // Backdated event (server-side timestamp) _upstack('track', 'server_event', { value: 50 }, null, null, '2026-06-01T12:00:00Z'); // Page unload with beacon (using shorthand) window.addEventListener('visibilitychange', () => { if (document.visibilityState === 'hidden') { _upstack('track', 'page_exit', { time_on_page_seconds: Math.round((Date.now() - pageLoadTime) / 1000) }, { useBeacon: true }); } }); ``` *** ### identify(userId?, data?) Associate user identity with the current session. Used for cross-device tracking and destination matching. ```typescript theme={null} function identify( userId?: string | null, data?: EventIdentityTraits ): void interface EventIdentityTraits { emails?: string[]; // Array of email addresses phones?: string[]; // Array of phone numbers (E.164 format preferred) firstName?: string; lastName?: string; address?: { city?: string; state?: string; zip?: string; country?: string; }; } ``` **Parameters:** | Parameter | Type | Required | Description | | --------- | --------------------- | -------- | --------------------------------------------------------------------------------- | | `userId` | `string \| null` | No | Your internal user ID. Pass `null` for anonymous identification with traits only. | | `data` | `EventIdentityTraits` | No | Identity traits with `emails[]` and `phones[]` as arrays | <Note> **Important:** `emails` and `phones` are arrays, not single values. This supports users with multiple contact methods. </Note> **Examples:** ```javascript theme={null} // With userId only _upstack('identify', 'user-456'); // With full profile _upstack('identify', 'user-456', { emails: ['jane@example.com', 'jane.doe@work.com'], phones: ['+15551234567'], firstName: 'Jane', lastName: 'Doe', address: { city: 'Austin', state: 'TX', zip: '78701', country: 'US' } }); // Traits only (Shopify path — userId is null) _upstack('identify', null, { emails: ['customer@example.com'] }); // After form submission document.querySelector('form').addEventListener('submit', (e) => { const email = e.target.querySelector('[name="email"]').value; _upstack('identify', null, { emails: [email] }); }); ``` *** ### metric(metricName, metricValue, metricData?, metricId?) Send a custom metric value. ```typescript theme={null} function metric( metricName: string, metricValue: number, metricData?: Record<string, unknown>, metricId?: string ): null ``` <Warning> **Currently Disabled:** The `metric()` method is routed through the queue but returns `null` — metric forwarding is disabled in the public SDK. This method exists for future use. </Warning> **Parameters:** | Parameter | Type | Required | Description | | ------------- | -------- | -------- | --------------------------- | | `metricName` | `string` | Yes | Metric name | | `metricValue` | `number` | Yes | Numeric value | | `metricData` | `object` | No | Additional context | | `metricId` | `string` | No | Unique ID for deduplication | **Example:** ```javascript theme={null} // Currently returns null — metric forwarding disabled _upstack('metric', 'page_load_time', 1250, { page: '/checkout' }); ``` *** ### reset() Clear identity, session data, event listeners, and hooks. Call when a user logs out. ```typescript theme={null} function reset(): void ``` **Example:** ```javascript theme={null} function handleLogout() { _upstack('reset'); window.location.href = '/login'; } ``` *** ## Direct Client Methods These methods are **only available via `window._upsClient`** after initialization completes. They cannot be called through the `_upstack()` queue. ### isKnown() Check if the current user has been identified. ```typescript theme={null} function isKnown(): Promise<boolean> ``` **Returns:** Promise resolving to `true` if the user has been identified, `false` otherwise. <Warning> **Direct Client Only:** This method is NOT available via the `_upstack()` queue. You must call it directly on `window._upsClient`. </Warning> **Example:** ```javascript theme={null} // After init completes const isKnown = await window._upsClient.isKnown(); if (!isKnown) { showEmailCapturePopup(); } ``` *** ### getUpstackId() Retrieve the Upstack identity object for the current user. ```typescript theme={null} interface UpstackId { _upstackId?: string; // Persistent user ID _upstackSid?: string; // Session ID _upstackIp?: string; // IP address (if available) } function getUpstackId(): Promise<UpstackId> ``` **Returns:** Promise resolving to an `UpstackId` object (not a string). <Warning> **Direct Client Only:** This method is NOT available via the `_upstack()` queue. You must call it directly on `window._upsClient`. **Return Type:** Returns an object with identity fields, not a single string ID. </Warning> **Example:** ```javascript theme={null} // After init completes const upstackId = await window._upsClient.getUpstackId(); console.log('Upstack ID:', upstackId._upstackId); console.log('Session ID:', upstackId._upstackSid); // Use for server-side API calls fetch('/api/track', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ upstack_id: upstackId._upstackId, event: 'server_purchase', value: 99.99 }) }); ``` *** ## Waiting for SDK Ready When using direct client methods, ensure the SDK has loaded: ```javascript theme={null} function onUpstackReady(callback) { if (window._upsClient && window._upsClient._initialized) { callback(); } else { const interval = setInterval(() => { if (window._upsClient && window._upsClient._initialized) { clearInterval(interval); callback(); } }, 100); } } // Usage onUpstackReady(async () => { const isKnown = await window._upsClient.isKnown(); if (isKnown) { const upstackId = await window._upsClient.getUpstackId(); console.log('User ID:', upstackId._upstackId); } }); ``` *** ## Common Patterns ### SPA Navigation Tracking Track page views on route changes in single-page applications: ```javascript theme={null} // React Router import { useEffect } from 'react'; import { useLocation } from 'react-router-dom'; function usePageTracking() { const location = useLocation(); useEffect(() => { _upstack('page', { page_path: location.pathname, page_search: location.search }); }, [location]); } // Next.js App Router 'use client'; import { usePathname, useSearchParams } from 'next/navigation'; import { useEffect } from 'react'; export function Analytics() { const pathname = usePathname(); const searchParams = useSearchParams(); useEffect(() => { _upstack('page', { page_path: pathname, page_search: searchParams.toString() }); }, [pathname, searchParams]); return null; } ``` ### E-commerce Funnel Track the complete customer journey: ```javascript theme={null} // Product view _upstack('track', 'view_content', { items: [{ id: 'SKU123', name: 'Widget', price: 29.99 }] }); // Add to cart _upstack('track', 'add_to_cart', { items: [{ id: 'SKU123', name: 'Widget', price: 29.99, quantity: 1 }], value: 29.99, currency: 'USD' }); // Begin checkout _upstack('track', 'initiate_checkout', { items: [{ id: 'SKU123', name: 'Widget', price: 29.99, quantity: 1 }], value: 29.99, currency: 'USD' }); // Purchase (with deduplication ID) _upstack('track', 'purchase', { items: [{ id: 'SKU123', name: 'Widget', price: 29.99, quantity: 1 }], value: 29.99, order_id: 'ORD-456', currency: 'USD' }, 'ORD-456'); ``` ### Page Exit Tracking with Beacon Reliably track time on page even when the user closes the tab: ```javascript theme={null} let pageLoadTime = Date.now(); window.addEventListener('visibilitychange', () => { if (document.visibilityState === 'hidden') { const timeOnPage = Math.round((Date.now() - pageLoadTime) / 1000); _upstack('track', 'page_exit', { time_on_page_seconds: timeOnPage, page_path: window.location.pathname }, { useBeacon: true }); } }); ``` ### Form Submission Tracking Capture leads from newsletter signups: ```javascript theme={null} document.querySelector('#newsletter-form').addEventListener('submit', (e) => { e.preventDefault(); const email = e.target.querySelector('[name="email"]').value; // Identify the user _upstack('identify', null, { emails: [email] }); // Track the lead event with beacon (in case form navigates away) _upstack('track', 'lead', { source: 'newsletter_signup', email: email }, { useBeacon: true }); // Submit the form e.target.submit(); }); ``` *** ## TypeScript Support Add type declarations for TypeScript projects: ```typescript theme={null} declare global { interface Window { _upstack: (...args: unknown[]) => void; _upsqueue: unknown[]; _upsClient: { init: (pixelId: string, identityTraits?: EventIdentityTraits, scriptSource?: string) => Promise<{ isInitialized: boolean; isDisabled: boolean }>; page: (eventData?: Record<string, unknown>) => void; track: (eventName: string, eventData?: Record<string, unknown>, eventId?: string, contextOverride?: Record<string, unknown>, collectedAt?: string, collectedAtEpoch?: number, options?: TrackOptions) => void; identify: (userId?: string | null, data?: EventIdentityTraits) => void; metric: (metricName: string, metricValue: number, metricData?: Record<string, unknown>, metricId?: string) => null; reset: () => void; isKnown: () => Promise<boolean>; getUpstackId: () => Promise<UpstackId>; _initialized: boolean; }; } } interface EventIdentityTraits { emails?: string[]; phones?: string[]; firstName?: string; lastName?: string; address?: { city?: string; state?: string; zip?: string; country?: string; }; } interface TrackOptions { useBeacon?: boolean; } interface UpstackId { _upstackId?: string; _upstackSid?: string; _upstackIp?: string; } export {}; ``` *** ## Methods NOT Available The following methods are **not implemented** in the public SDK: * `consent` — Not implemented * `group` — Not implemented (stub exists) * `screen` — Not implemented (stub exists) * `alias` — Not implemented (stub exists) Internal methods (do not call directly): * `notify` — Internal hook messaging * `postInit` — Internal post-initialization ## Related Documentation <CardGroup> <Card title="Pixel Setup" icon="download" href="/pixel/setup"> Installation guide for non-Shopify websites and SPAs. </Card> <Card title="Standard Events" icon="list-check" href="/pixel/standard-events"> Complete reference for all standard events with JavaScript snippets. </Card> <Card title="Properties & Context" icon="table" href="/pixel/events/event-properties"> Reference for item arrays, customer data, and auto-captured fields. </Card> <Card title="Custom Events" icon="sparkles" href="/pixel/custom-events"> Create events beyond the standard taxonomy for your needs. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> How identify() connects sessions to customer profiles. </Card> <Card title="Shopify Automatic Tracking" icon="shopify" href="/sources/shopify-automatic-tracking"> Events tracked automatically on Shopify stores. </Card> </CardGroup> # SaaS & B2B Events Reference Source: https://docs.upstackdata.com/pixel/saas-events Track SaaS events with Upstack Data — subscription lifecycle, trials, payments, seat expansion, and user engagement with copyable JavaScript snippets. <Info> These events are designed for **B2B SaaS** and **subscription-based businesses**. If you're running an e-commerce store, see [Standard Events](/pixel/standard-events) instead. </Info> ## When to Use SaaS Events Use these events when your business model includes: * **Subscription billing** (monthly/annual plans) * **Free trials** with conversion tracking * **Seat-based pricing** with expansion revenue * **Multi-user accounts** with role-based access * **Product-led growth** with feature usage tracking *** ## Account Lifecycle Track account creation and deletion to measure growth and churn. ### account\_created Fires when a new account (organization/workspace) is created. #### JavaScript ```javascript theme={null} window._upstack('track', 'account_created', { accountId: 'acct_abc123', accountName: 'Acme Corporation', planId: 'plan_starter_monthly', planName: 'Starter', userId: 'usr_xyz789', userEmail: 'jane@acme.com' }); ``` #### Properties | Property | Type | Required | Description | | ----------- | ------ | -------- | ------------------------- | | accountId | string | Yes | Unique account identifier | | accountName | string | No | Account/organization name | | planId | string | No | Initial plan identifier | | planName | string | No | Initial plan name | | userId | string | No | Creating user's ID | | userEmail | string | No | Creating user's email | #### When to Fire * After account registration completes * After organization setup wizard finishes * After SSO provisioning creates a new workspace *** ### account\_deleted Fires when an account is permanently deleted. #### JavaScript ```javascript theme={null} window._upstack('track', 'account_deleted', { accountId: 'acct_abc123', accountName: 'Acme Corporation', cancelReason: 'no_longer_needed', cancelFeedback: 'Switching to a different solution', mrr: 9900 }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | -------------------------- | | accountId | string | Yes | Deleted account identifier | | accountName | string | No | Account name | | cancelReason | string | No | Reason code for deletion | | cancelFeedback | string | No | User-provided feedback | | mrr | number | No | Lost MRR in cents | #### When to Fire * After account deletion confirmation * After workspace removal completes * After data retention period expires *** ## Acquisition Track the lead-to-signup funnel to measure conversion rates. ### signup\_started Fires when a user begins the signup flow. #### JavaScript ```javascript theme={null} window._upstack('track', 'signup_started', { planId: 'plan_pro_monthly', source: 'pricing_page' }); ``` #### Properties | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------------- | | planId | string | No | Pre-selected plan (if applicable) | | source | string | No | Where signup was initiated | #### When to Fire * When signup form is opened * When registration page loads * When "Start Free Trial" button is clicked *** ### signup\_completed Fires when a user completes signup and creates an account. #### JavaScript ```javascript theme={null} window._upstack('track', 'signup_completed', { userId: 'usr_xyz789', accountId: 'acct_abc123', userEmail: 'jane@acme.com', planId: 'plan_pro_monthly', planName: 'Pro Plan' }); ``` #### Properties | Property | Type | Required | Description | | --------- | ------ | -------- | ---------------------- | | userId | string | Yes | New user identifier | | accountId | string | Yes | New account identifier | | userEmail | string | No | User email address | | planId | string | No | Selected plan | | planName | string | No | Plan display name | #### When to Fire * After signup form submission succeeds * After email verification completes * After OAuth signup flow finishes *** ### demo\_requested Fires when a user requests a product demo. #### JavaScript ```javascript theme={null} window._upstack('track', 'demo_requested', { userEmail: 'buyer@enterprise.com', companyName: 'Enterprise Corp', companySize: '500-1000', useCase: 'marketing_analytics' }); ``` #### Properties | Property | Type | Required | Description | | ----------- | ------ | -------- | ------------------ | | userEmail | string | No | Requester email | | companyName | string | No | Company name | | companySize | string | No | Company size range | | useCase | string | No | Primary use case | #### When to Fire * After demo request form submission * After sales call booking confirmation * After Calendly/HubSpot meeting scheduled *** ## Trial Events Track the trial lifecycle from start to conversion or expiry. ### trial\_started Fires when a user begins a free trial. #### JavaScript ```javascript theme={null} window._upstack('track', 'trial_started', { accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', trialEndDate: '2026-03-04T14:30:00.000Z', trialDaysRemaining: 14 }); ``` #### Properties | Property | Type | Required | Description | | ------------------ | ------ | -------- | ------------------------------ | | accountId | string | Yes | Account identifier | | planId | string | Yes | Trial plan identifier | | planName | string | No | Human-readable plan name | | trialEndDate | string | No | ISO 8601 trial expiration date | | trialDaysRemaining | number | No | Days until trial expires | #### When to Fire * After trial signup confirmation * After trial activation in billing system * After Stripe `customer.subscription.created` with trial *** ### trial\_activated Fires when a trial user reaches a meaningful activation milestone. #### JavaScript ```javascript theme={null} window._upstack('track', 'trial_activated', { accountId: 'acct_abc123', planId: 'plan_pro_monthly', trialDaysRemaining: 12, activationMilestone: 'first_integration_connected' }); ``` #### Properties | Property | Type | Required | Description | | ------------------- | ------ | -------- | --------------------------- | | accountId | string | Yes | Account identifier | | planId | string | No | Trial plan identifier | | trialDaysRemaining | number | No | Days remaining in trial | | activationMilestone | string | No | Which milestone was reached | #### When to Fire * After first key feature is used * After onboarding checklist is completed * After first data import succeeds *** ### trial\_extended Fires when a trial period is extended. #### JavaScript ```javascript theme={null} window._upstack('track', 'trial_extended', { accountId: 'acct_abc123', trialEndDate: '2026-03-11T14:30:00.000Z', trialDaysRemaining: 7, extensionReason: 'support_request' }); ``` #### Properties | Property | Type | Required | Description | | ------------------ | ------ | -------- | ---------------------- | | accountId | string | Yes | Account identifier | | trialEndDate | string | No | New trial end date | | trialDaysRemaining | number | No | New days remaining | | extensionReason | string | No | Why trial was extended | #### When to Fire * After support manually extends trial * After promotional extension is applied * After win-back campaign grants extension *** ### trial\_ending\_soon Fires when a trial is about to expire (typically 3 days before). #### JavaScript ```javascript theme={null} window._upstack('track', 'trial_ending_soon', { accountId: 'acct_abc123', trialDaysRemaining: 3, planId: 'plan_pro_monthly', trialEndDate: '2026-03-04T14:30:00.000Z' }); ``` #### Properties | Property | Type | Required | Description | | ------------------ | ------ | -------- | --------------------- | | accountId | string | Yes | Account identifier | | trialDaysRemaining | number | Yes | Days until expiry | | planId | string | No | Trial plan identifier | | trialEndDate | string | No | Trial expiration date | #### When to Fire * 3 days before trial expires (common) * When Stripe sends `customer.subscription.trial_will_end` * When automated warning email triggers *** ### trial\_expired Fires when a trial ends without conversion. #### JavaScript ```javascript theme={null} window._upstack('track', 'trial_expired', { accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', trialDays: 14 }); ``` #### Properties | Property | Type | Required | Description | | --------- | ------ | -------- | ------------------ | | accountId | string | Yes | Account identifier | | planId | string | No | Expired trial plan | | planName | string | No | Plan display name | | trialDays | number | No | Total trial length | #### When to Fire * When trial end date is reached without payment * When account is downgraded to free tier * When access is revoked after grace period *** ### trial\_converted Fires when a trial converts to a paid subscription. This is a key conversion event. #### JavaScript ```javascript theme={null} window._upstack('track', 'trial_converted', { accountId: 'acct_abc123', subscriptionId: 'sub_def456', planId: 'plan_pro_monthly', planName: 'Pro Plan', mrr: 9900, billingInterval: 'month' }); ``` #### Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ---------------------------------- | | accountId | string | Yes | Account identifier | | subscriptionId | string | Yes | New subscription ID | | planId | string | Yes | Converted plan identifier | | planName | string | No | Plan display name | | mrr | number | No | Monthly recurring revenue in cents | | billingInterval | string | No | `month` or `year` | #### When to Fire * After first successful payment * When Stripe subscription status changes from `trialing` to `active` * After payment method is charged successfully <Tip> Track `mrr` to measure trial-to-paid conversion value and calculate average revenue per converted trial. </Tip> *** ## Subscription Lifecycle Track the complete subscription journey from creation through churn or reactivation. ### subscription\_created Fires when a subscription record is created in your billing system. #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_created', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', billingInterval: 'month' }); ``` #### Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | --------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | Yes | Plan identifier | | planName | string | No | Plan display name | | billingInterval | string | No | `day`, `week`, `month`, or `year` | #### When to Fire * When subscription object is created in Stripe * May precede first payment (for trials) * After checkout session completes *** ### subscription\_started Fires when a new subscription begins (first billing period starts). #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_started', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', mrr: 9900, billingInterval: 'month' }); ``` #### Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ---------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | Yes | Plan identifier | | planName | string | No | Plan display name | | mrr | number | No | Monthly recurring revenue in cents | | billingInterval | string | No | Billing frequency | #### When to Fire * After first successful charge * When subscription status becomes `active` * After trial converts to paid *** ### subscription\_upgraded Fires when a customer upgrades to a higher-tier plan. #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_upgraded', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_business_monthly', planName: 'Business', previousPlanId: 'plan_pro_monthly', mrr: 19900, mrrDelta: 10000 }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | New plan identifier | | planName | string | No | New plan name | | previousPlanId | string | No | Previous plan identifier | | mrr | number | No | New MRR after upgrade in cents | | mrrDelta | number | No | MRR increase in cents (positive) | #### When to Fire * When plan changes from lower to higher tier * When Stripe subscription item is updated with higher-priced plan * After upgrade checkout completes <Tip> Track `mrrDelta` alongside `subscription_downgraded` to calculate net revenue retention. </Tip> *** ### subscription\_downgraded Fires when a customer downgrades to a lower-tier plan. #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_downgraded', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_starter_monthly', planName: 'Starter', previousPlanId: 'plan_pro_monthly', mrr: 4900, mrrDelta: -5000 }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | New plan identifier | | planName | string | No | New plan name | | previousPlanId | string | No | Previous plan identifier | | mrr | number | No | New MRR after downgrade in cents | | mrrDelta | number | No | MRR decrease in cents (negative) | #### When to Fire * When plan changes from higher to lower tier * When features are removed from subscription * When scheduled downgrade takes effect at period end *** ### subscription\_renewed <Note> This is a **custom event name**. For standard renewal tracking, consider using `payment_succeeded` or `invoice_paid` events instead. </Note> Fires when a subscription successfully renews for another billing period. #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_renewed', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', mrr: 9900, renewalCount: 6 }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ----------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Current plan identifier | | mrr | number | No | Renewed MRR in cents | | renewalCount | number | No | Number of times renewed | #### When to Fire * When recurring payment succeeds * When billing period advances * When Stripe `invoice.paid` fires for subscription *** ### subscription\_paused Fires when a subscription is paused. #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_paused', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', mrr: 9900, pauseReason: 'seasonal_business' }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | --------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Plan identifier | | mrr | number | No | Paused MRR in cents | | pauseReason | string | No | Why subscription was paused | #### When to Fire * When customer requests pause * When seasonal pause is activated * When Stripe subscription pause feature triggers *** ### subscription\_resumed Fires when a paused subscription is resumed. #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_resumed', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', mrr: 9900, pausedDays: 30 }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Plan identifier | | mrr | number | No | Resumed MRR in cents | | pausedDays | number | No | How long subscription was paused | #### When to Fire * When customer manually resumes * When pause period ends automatically * When billing restarts *** ### subscription\_cancelled Fires when a cancellation is requested (may still be active until period end). #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_cancelled', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', cancelReason: 'too_expensive', cancelFeedback: 'Budget constraints this quarter', mrr: 9900, cancelAtPeriodEnd: true }); ``` #### Properties | Property | Type | Required | Description | | ----------------- | ------- | -------- | ----------------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Cancelled plan | | cancelReason | string | No | Cancellation reason code | | cancelFeedback | string | No | User-provided feedback | | mrr | number | No | MRR being cancelled in cents | | cancelAtPeriodEnd | boolean | No | If true, cancels at end of billing period | #### When to Fire * When customer clicks cancel button * When cancellation request is submitted * When Stripe subscription is set to cancel at period end *** ### subscription\_churned Fires when a subscription ends completely (no longer billing). This is the final churn event. #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_churned', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', cancelReason: 'switched_competitor', mrr: 9900, ltv: 118800, subscriptionMonths: 12 }); ``` #### Properties | Property | Type | Required | Description | | ------------------ | ------ | -------- | -------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Churned plan | | cancelReason | string | No | Churn reason | | mrr | number | No | Lost MRR in cents | | ltv | number | No | Customer lifetime value in cents | | subscriptionMonths | number | No | How long they were subscribed | #### When to Fire * When final billing period ends * When subscription is deactivated * When Stripe `customer.subscription.deleted` fires <Warning> Use this event to calculate churn rate and analyze churn reasons. Track `ltv` to understand which customer segments have the highest lifetime value. </Warning> *** ### subscription\_initial\_purchase Fires when a customer's first subscription payment is processed (distinct from trial conversion). #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_initial_purchase', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', value: 9900, currency: 'USD', billingInterval: 'month' }); ``` #### Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ----------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Plan identifier | | planName | string | No | Plan display name | | value | number | No | Payment amount in cents | | currency | string | No | ISO 4217 currency code | | billingInterval | string | No | `month` or `year` | #### When to Fire * First subscription charge succeeds * After trial converts (first paid billing period) * When new customer's initial payment processes *** ### subscription\_recurring\_purchase Fires when a recurring subscription payment is processed (not the initial purchase). #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_recurring_purchase', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', value: 9900, currency: 'USD', billingInterval: 'month', renewalNumber: 6 }); ``` #### Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | -------------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Plan identifier | | planName | string | No | Plan display name | | value | number | No | Payment amount in cents | | currency | string | No | ISO 4217 currency code | | billingInterval | string | No | `month` or `year` | | renewalNumber | number | No | Which renewal this is (2nd, 3rd, etc.) | #### When to Fire * Each recurring billing cycle * When Stripe `invoice.paid` fires for an existing subscription * Monthly/annual renewal charge succeeds <Tip> Use `subscription_initial_purchase` for acquisition metrics and `subscription_recurring_purchase` for retention/LTV analysis. Together they give a complete picture of subscription revenue. </Tip> *** ### subscription\_reactivated Fires when a previously churned customer resubscribes. #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_reactivated', { subscriptionId: 'sub_ghi789', accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', mrr: 9900, daysSinceChurn: 45 }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ----------------------------------- | | subscriptionId | string | Yes | New subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | New plan identifier | | planName | string | No | Plan display name | | mrr | number | No | Recovered MRR in cents | | daysSinceChurn | number | No | Days between churn and reactivation | #### When to Fire * When former customer signs up again * When win-back campaign converts * When churned account starts new subscription *** ## Order Fulfillment Events Track order fulfillment and shipping for e-commerce subscription boxes, physical product deliveries, and Klaviyo flow triggers. ### order\_fulfilled Fires when an order has been completely fulfilled (all items prepared for shipment). #### JavaScript ```javascript theme={null} window._upstack('track', 'order_fulfilled', { orderId: 'ORD_12345', orderName: '#1042', value: 149.99, currency: 'USD', fulfillmentStatus: 'fulfilled', items: [ { id: 'SKU_001', name: 'Monthly Snack Box', price: 39.99, quantity: 1 } ], email: 'customer@example.com' }); ``` #### Properties | Property | Type | Required | Description | | ----------------- | ------ | -------- | ----------------------------------------------------- | | orderId | string | Yes | Order identifier | | orderName | string | No | Human-readable order name | | value | number | No | Order value | | currency | string | No | ISO 4217 currency code | | fulfillmentStatus | string | No | Fulfillment status (e.g., `'fulfilled'`, `'partial'`) | | items | array | No | Products fulfilled | | email | string | No | Customer email | #### When to Fire * When warehouse marks order as packed/ready * When Shopify fulfillment is created * When all items in an order are fulfilled *** ### order\_shipped Fires when an order has been shipped and tracking information is available. #### JavaScript ```javascript theme={null} window._upstack('track', 'order_shipped', { orderId: 'ORD_12345', orderName: '#1042', value: 149.99, currency: 'USD', trackingNumber: '1Z999AA10123456784', trackingCompany: 'UPS', trackingUrl: 'https://www.ups.com/track?tracknum=1Z999AA10123456784', estimatedDelivery: '2026-02-25T00:00:00.000Z', items: [ { id: 'SKU_001', name: 'Monthly Snack Box', price: 39.99, quantity: 1 } ], email: 'customer@example.com' }); ``` #### Properties | Property | Type | Required | Description | | ----------------- | ------ | -------- | ----------------------------------------------------- | | orderId | string | Yes | Order identifier | | orderName | string | No | Human-readable order name | | value | number | No | Order value | | currency | string | No | ISO 4217 currency code | | trackingNumber | string | No | Carrier tracking number | | trackingCompany | string | No | Shipping carrier (e.g., `'UPS'`, `'FedEx'`, `'USPS'`) | | trackingUrl | string | No | Direct link to tracking page | | estimatedDelivery | string | No | ISO 8601 estimated delivery date | | items | array | No | Products shipped | | email | string | No | Customer email | #### When to Fire * When shipping label is created with tracking * When carrier picks up package * When Shopify `fulfillment_events/create` webhook fires <Tip> **Klaviyo integration:** `order_shipped` is commonly used to trigger post-purchase flows like "Your order is on the way" emails with tracking information. </Tip> *** ## User Events Track team growth and user engagement within accounts. ### user\_invited Fires when a user is invited to join an account. #### JavaScript ```javascript theme={null} window._upstack('track', 'user_invited', { accountId: 'acct_abc123', inviteeEmail: 'newmember@acme.com', inviteeRole: 'member', invitedByUserId: 'usr_xyz789' }); ``` #### Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | --------------------- | | accountId | string | Yes | Account identifier | | inviteeEmail | string | No | Invitee email address | | inviteeRole | string | No | Assigned role | | invitedByUserId | string | No | Inviter's user ID | #### When to Fire * When team invite is sent * When collaboration request is initiated * After invite email is dispatched *** ### user\_joined Fires when an invited user accepts and joins the account. #### JavaScript ```javascript theme={null} window._upstack('track', 'user_joined', { userId: 'usr_newmember', accountId: 'acct_abc123', userEmail: 'newmember@acme.com', userRole: 'member' }); ``` #### Properties | Property | Type | Required | Description | | --------- | ------ | -------- | -------------------- | | userId | string | Yes | New user identifier | | accountId | string | Yes | Account identifier | | userEmail | string | No | User email address | | userRole | string | No | User's assigned role | #### When to Fire * When invite is accepted * When account access is granted * After user completes join flow *** ### user\_role\_changed <Note> This is a **custom event name**. Track it using the [Custom Events](/pixel/custom-events) pattern if you need role change analytics. </Note> Fires when a user's role is changed within an account. #### JavaScript ```javascript theme={null} window._upstack('track', 'user_role_changed', { userId: 'usr_xyz789', accountId: 'acct_abc123', previousRole: 'member', newRole: 'admin', changedByUserId: 'usr_admin123' }); ``` #### Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ------------------------- | | userId | string | Yes | User whose role changed | | accountId | string | Yes | Account identifier | | previousRole | string | No | Previous role | | newRole | string | No | New role | | changedByUserId | string | No | Admin who made the change | #### When to Fire * When user is promoted to admin * When permissions are modified * After role update is saved *** ## Billing Events Track payment activity for revenue analytics and dunning workflows. ### payment\_succeeded Fires when a payment is processed successfully. #### JavaScript ```javascript theme={null} window._upstack('track', 'payment_succeeded', { accountId: 'acct_abc123', invoiceId: 'inv_ghi012', subscriptionId: 'sub_def456', amount: 9900, currency: 'USD' }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ----------------------- | | accountId | string | Yes | Account identifier | | amount | number | Yes | Payment amount in cents | | invoiceId | string | No | Invoice identifier | | subscriptionId | string | No | Subscription identifier | | currency | string | No | ISO 4217 currency code | #### When to Fire * When charge succeeds * When invoice is paid * When Stripe `invoice.paid` webhook fires *** ### payment\_failed Fires when a payment attempt fails. #### JavaScript ```javascript theme={null} window._upstack('track', 'payment_failed', { accountId: 'acct_abc123', invoiceId: 'inv_ghi012', subscriptionId: 'sub_def456', amount: 9900, failureReason: 'card_declined', failureCode: 'insufficient_funds', currency: 'USD' }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ------------------------------ | | accountId | string | Yes | Account identifier | | amount | number | Yes | Failed payment amount in cents | | invoiceId | string | No | Invoice identifier | | subscriptionId | string | No | Subscription identifier | | failureReason | string | No | Failure reason code | | failureCode | string | No | Detailed failure code | | currency | string | No | ISO 4217 currency code | #### When to Fire * When card is declined * When insufficient funds error occurs * When Stripe `invoice.payment_failed` webhook fires <Warning> Track payment failures to identify at-risk customers and trigger dunning workflows. </Warning> *** ### invoice\_paid Fires when an invoice is marked as paid. #### JavaScript ```javascript theme={null} window._upstack('track', 'invoice_paid', { accountId: 'acct_abc123', invoiceId: 'inv_ghi012', subscriptionId: 'sub_def456', amount: 9900, currency: 'USD' }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ----------------------- | | accountId | string | Yes | Account identifier | | invoiceId | string | Yes | Invoice identifier | | amount | number | Yes | Paid amount in cents | | subscriptionId | string | No | Subscription identifier | | currency | string | No | ISO 4217 currency code | #### When to Fire * When payment is received * When manual reconciliation marks invoice paid * When Stripe `invoice.paid` webhook fires *** ## Expansion Events Track seat-based and add-on revenue expansion. ### seat\_added Fires when additional seats are purchased. #### JavaScript ```javascript theme={null} window._upstack('track', 'seat_added', { accountId: 'acct_abc123', subscriptionId: 'sub_def456', seatCount: 15, seatDelta: 5, mrrDelta: 2500 }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------- | | accountId | string | Yes | Account identifier | | seatCount | number | Yes | Total seats after addition | | subscriptionId | string | No | Subscription identifier | | seatDelta | number | No | Number of seats added | | mrrDelta | number | No | MRR increase from seats in cents | #### When to Fire * When seats are purchased * When user is added beyond plan limit * When Stripe subscription quantity increases *** ### seat\_removed Fires when seats are removed from the plan. #### JavaScript ```javascript theme={null} window._upstack('track', 'seat_removed', { accountId: 'acct_abc123', subscriptionId: 'sub_def456', seatCount: 10, seatDelta: -5, mrrDelta: -2500 }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ---------------------------------- | | accountId | string | Yes | Account identifier | | seatCount | number | Yes | Total seats after removal | | subscriptionId | string | No | Subscription identifier | | seatDelta | number | No | Number of seats removed (negative) | | mrrDelta | number | No | MRR decrease in cents (negative) | #### When to Fire * When seats are removed * When user is deactivated * When Stripe subscription quantity decreases *** ## Engagement Events Track user activity and product milestones. ### feature\_used Fires when a specific feature is used. Track key features to understand product adoption. #### JavaScript ```javascript theme={null} window._upstack('track', 'feature_used', { accountId: 'acct_abc123', userId: 'usr_xyz789', featureId: 'feat_export', featureName: 'CSV Export', featureCategory: 'reporting' }); ``` #### Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ------------------------- | | accountId | string | Yes | Account identifier | | featureId | string | Yes | Feature identifier | | userId | string | No | User who used the feature | | featureName | string | No | Feature display name | | featureCategory | string | No | Feature category | #### When to Fire * When key features are used * When premium features are accessed * When usage-based actions are performed *** ### milestone\_reached Fires when a key milestone is achieved. #### JavaScript ```javascript theme={null} window._upstack('track', 'milestone_reached', { accountId: 'acct_abc123', milestoneId: 'milestone_100_orders', milestoneName: '100 Orders Processed', milestoneValue: 100 }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ---------------------- | | accountId | string | Yes | Account identifier | | milestoneId | string | Yes | Milestone identifier | | milestoneName | string | No | Milestone display name | | milestoneValue | number | No | Numeric value achieved | #### When to Fire * When usage threshold is crossed * When achievement is unlocked * When significant product milestone occurs *** ## Stripe Webhook Integration If you use Stripe for billing, handle webhooks to track events automatically. <Warning> Webhook handlers run server-side where `window._upstack()` is not available. Server-side event tracking requires the Upstack Server API. Contact support for early access, or use the patterns below to queue events for client-side tracking. </Warning> ### Server-Side Helper Pattern Create a helper to queue events for server-side tracking: ```javascript theme={null} // utils/tracking.js async function trackServerEvent(eventName, properties) { // Option 1: Direct API call (requires Server API access) await fetch('https://api.getupstack.com/v1/events', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${process.env.UPSTACK_API_KEY}` }, body: JSON.stringify({ event: eventName, properties, timestamp: new Date().toISOString() }) }); // Option 2: Store in database for later sync // await db.pendingEvents.create({ eventName, properties }); } ``` ### Example Webhook Handler ```javascript theme={null} // Express.js webhook handler (server-side) app.post('/webhooks/stripe', async (req, res) => { const event = stripe.webhooks.constructEvent( req.body, req.headers['stripe-signature'], process.env.STRIPE_WEBHOOK_SECRET ); switch (event.type) { case 'customer.subscription.created': const sub = event.data.object; await trackServerEvent('subscription_created', { subscriptionId: sub.id, accountId: sub.metadata.account_id, planId: sub.items.data[0].price.id, billingInterval: sub.items.data[0].price.recurring.interval }); break; case 'customer.subscription.updated': const updated = event.data.object; const previous = event.data.previous_attributes; if (previous.items) { const newPrice = updated.items.data[0].price.unit_amount; const oldPrice = previous.items.data[0].price.unit_amount; if (newPrice > oldPrice) { await trackServerEvent('subscription_upgraded', { subscriptionId: updated.id, accountId: updated.metadata.account_id, planId: updated.items.data[0].price.id, mrrDelta: newPrice - oldPrice }); } else { await trackServerEvent('subscription_downgraded', { subscriptionId: updated.id, accountId: updated.metadata.account_id, planId: updated.items.data[0].price.id, mrrDelta: newPrice - oldPrice }); } } break; case 'customer.subscription.deleted': const deleted = event.data.object; await trackServerEvent('subscription_churned', { subscriptionId: deleted.id, accountId: deleted.metadata.account_id, planId: deleted.items.data[0].price.id, mrr: deleted.items.data[0].price.unit_amount }); break; case 'invoice.paid': const invoice = event.data.object; await trackServerEvent('payment_succeeded', { accountId: invoice.metadata.account_id, invoiceId: invoice.id, subscriptionId: invoice.subscription, amount: invoice.amount_paid, currency: invoice.currency.toUpperCase() }); break; case 'invoice.payment_failed': const failed = event.data.object; await trackServerEvent('payment_failed', { accountId: failed.metadata.account_id, invoiceId: failed.id, subscriptionId: failed.subscription, amount: failed.amount_due, failureReason: failed.last_payment_error?.code }); break; case 'customer.subscription.trial_will_end': const trial = event.data.object; await trackServerEvent('trial_ending_soon', { accountId: trial.metadata.account_id, trialDaysRemaining: 3, planId: trial.items.data[0].price.id, trialEndDate: new Date(trial.trial_end * 1000).toISOString() }); break; } res.json({ received: true }); }); ``` ### Stripe Webhook Mapping | Stripe Webhook | Upstack Event | | -------------------------------------- | --------------------------------------------------- | | `customer.subscription.created` | `subscription_created` | | `customer.subscription.updated` | `subscription_upgraded` / `subscription_downgraded` | | `customer.subscription.deleted` | `subscription_churned` | | `customer.subscription.paused` | `subscription_paused` | | `customer.subscription.resumed` | `subscription_resumed` | | `invoice.paid` | `invoice_paid`, `payment_succeeded` | | `invoice.payment_failed` | `payment_failed` | | `customer.subscription.trial_will_end` | `trial_ending_soon` | | `charge.refunded` | `payment_refunded` | *** ## What's Next <CardGroup> <Card title="Standard Events" icon="list-check" href="/pixel/standard-events"> E-commerce event reference for Shopify stores. </Card> <Card title="Custom Events" icon="code" href="/pixel/custom-events"> Define your own events beyond the standard taxonomy. </Card> <Card title="Properties & Context" icon="table" href="/pixel/events/event-properties"> Complete reference for all event fields. </Card> <Card title="Event Taxonomy" icon="sitemap" href="/pixel/events/taxonomy"> How events flow through the Upstack pipeline. </Card> </CardGroup> # account_created Event Source: https://docs.upstackdata.com/pixel/saas-events/account-created Track when a new account (organization/workspace) is created in your SaaS application. Fires when a new account (organization/workspace) is created. Use this event to measure account growth and track the top of your B2B funnel. ## JavaScript ```javascript theme={null} window._upstack('track', 'account_created', { accountId: 'acct_abc123', accountName: 'Acme Corporation', planId: 'plan_starter_monthly', planName: 'Starter', userId: 'usr_xyz789', userEmail: 'jane@acme.com' }); ``` ## Properties | Property | Type | Required | Description | | ----------- | ------ | -------- | ------------------------- | | accountId | string | Yes | Unique account identifier | | accountName | string | No | Account/organization name | | planId | string | No | Initial plan identifier | | planName | string | No | Initial plan name | | userId | string | No | Creating user's ID | | userEmail | string | No | Creating user's email | ## When to Fire * After account registration completes * After organization setup wizard finishes * After SSO provisioning creates a new workspace # account_deleted Event Source: https://docs.upstackdata.com/pixel/saas-events/account-deleted Track when an account is permanently deleted from your SaaS application. Fires when an account is permanently deleted. Track this event to measure churn and understand why customers leave. ## JavaScript ```javascript theme={null} window._upstack('track', 'account_deleted', { accountId: 'acct_abc123', accountName: 'Acme Corporation', cancelReason: 'no_longer_needed', cancelFeedback: 'Switching to a different solution', mrr: 9900 }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | -------------------------- | | accountId | string | Yes | Deleted account identifier | | accountName | string | No | Account name | | cancelReason | string | No | Reason code for deletion | | cancelFeedback | string | No | User-provided feedback | | mrr | number | No | Lost MRR in cents | ## When to Fire * After account deletion confirmation * After workspace removal completes * After data retention period expires # addon_cancelled Event Source: https://docs.upstackdata.com/pixel/saas-events/addon-cancelled Track when a customer cancels an add-on feature or service. Fires when a customer cancels an add-on feature or service. Use this event to understand add-on churn and feature value. ## JavaScript ```javascript theme={null} window._upstack('track', 'addon_cancelled', { accountId: 'acct_abc123', subscriptionId: 'sub_def456', addonId: 'addon_advanced_analytics', addonName: 'Advanced Analytics', price: 4900, currency: 'USD', cancelReason: 'not_using' }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ---------------------------- | | accountId | string | Yes | Account identifier | | addonId | string | Yes | Add-on identifier | | subscriptionId | string | No | Subscription identifier | | addonName | string | No | Human-readable add-on name | | price | number | No | Lost add-on revenue in cents | | currency | string | No | ISO 4217 currency code | | cancelReason | string | No | Reason for cancellation | ## When to Fire * When add-on is removed from subscription * When add-on cancellation is requested * When Stripe subscription item is removed # addon_purchased Event Source: https://docs.upstackdata.com/pixel/saas-events/addon-purchased Track when a customer purchases an add-on feature or service. Fires when a customer purchases an add-on feature or service. Use this event to measure add-on adoption and expansion revenue. ## JavaScript ```javascript theme={null} window._upstack('track', 'addon_purchased', { accountId: 'acct_abc123', subscriptionId: 'sub_def456', addonId: 'addon_advanced_analytics', addonName: 'Advanced Analytics', price: 4900, currency: 'USD', billingInterval: 'month' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | -------------------------- | | accountId | string | Yes | Account identifier | | addonId | string | Yes | Add-on identifier | | subscriptionId | string | No | Subscription identifier | | addonName | string | No | Human-readable add-on name | | price | number | No | Add-on price in cents | | currency | string | No | ISO 4217 currency code | | billingInterval | string | No | `month` or `year` | ## When to Fire * When add-on is purchased from settings * When add-on checkout completes * When Stripe subscription item is added # content_downloaded Event Source: https://docs.upstackdata.com/pixel/saas-events/content-downloaded Track when a user downloads gated content like whitepapers, ebooks, or case studies. Fires when a user downloads gated content. Use this event to measure content marketing effectiveness and identify marketing-qualified leads. ## JavaScript ```javascript theme={null} window._upstack('track', 'content_downloaded', { contentId: 'wp_2024_analytics_guide', contentType: 'whitepaper', contentTitle: '2024 Marketing Analytics Guide', userEmail: 'prospect@company.com', companyName: 'Prospect Corp', source: 'blog_cta' }); ``` ## Properties | Property | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------------------------------------------------- | | contentId | string | Yes | Unique content identifier | | contentType | string | No | Type of content (`whitepaper`, `ebook`, `case_study`, `template`, `guide`) | | contentTitle | string | No | Human-readable content title | | userEmail | string | No | Downloader's email address | | companyName | string | No | User's company name | | source | string | No | Where the download was initiated | ## When to Fire * After gated content form submission * After PDF/document download starts * After content access is granted via email gate # demo_requested Event Source: https://docs.upstackdata.com/pixel/saas-events/demo-requested Track when a user requests a product demo in your SaaS application. Fires when a user requests a product demo. Use this event to measure sales-qualified leads and demo conversion rates. ## JavaScript ```javascript theme={null} window._upstack('track', 'demo_requested', { userEmail: 'buyer@enterprise.com', companyName: 'Enterprise Corp', companySize: '500-1000', useCase: 'marketing_analytics' }); ``` ## Properties | Property | Type | Required | Description | | ----------- | ------ | -------- | ------------------ | | userEmail | string | No | Requester email | | companyName | string | No | Company name | | companySize | string | No | Company size range | | useCase | string | No | Primary use case | ## When to Fire * After demo request form submission * After sales call booking confirmation * After Calendly/HubSpot meeting scheduled # feature_used Event Source: https://docs.upstackdata.com/pixel/saas-events/feature-used Track when a specific feature is used to understand product adoption. Fires when a specific feature is used. Track key features to understand product adoption and identify power users. ## JavaScript ```javascript theme={null} window._upstack('track', 'feature_used', { accountId: 'acct_abc123', userId: 'usr_xyz789', featureId: 'feat_export', featureName: 'CSV Export', featureCategory: 'reporting' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ------------------------- | | accountId | string | Yes | Account identifier | | featureId | string | Yes | Feature identifier | | userId | string | No | User who used the feature | | featureName | string | No | Feature display name | | featureCategory | string | No | Feature category | ## When to Fire * When key features are used * When premium features are accessed * When usage-based actions are performed # invoice_created Event Source: https://docs.upstackdata.com/pixel/saas-events/invoice-created Track when a new invoice is created in the billing system. Fires when a new invoice is created in the billing system. Use this event to track billing cycles and invoice generation. ## JavaScript ```javascript theme={null} window._upstack('track', 'invoice_created', { accountId: 'acct_abc123', invoiceId: 'inv_ghi012', subscriptionId: 'sub_def456', amount: 9900, currency: 'USD', dueDate: '2026-03-01T00:00:00.000Z' }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ----------------------- | | accountId | string | Yes | Account identifier | | invoiceId | string | Yes | Invoice identifier | | amount | number | Yes | Invoice amount in cents | | subscriptionId | string | No | Subscription identifier | | currency | string | No | ISO 4217 currency code | | dueDate | string | No | ISO 8601 due date | ## When to Fire * When invoice is generated * When billing cycle creates new invoice * When Stripe `invoice.created` webhook fires ## Stripe Webhook Maps to `invoice.created`. # invoice_paid Event Source: https://docs.upstackdata.com/pixel/saas-events/invoice-paid Track when an invoice is marked as paid. Fires when an invoice is marked as paid. Use this event for revenue recognition and payment tracking. ## JavaScript ```javascript theme={null} window._upstack('track', 'invoice_paid', { accountId: 'acct_abc123', invoiceId: 'inv_ghi012', subscriptionId: 'sub_def456', amount: 9900, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ----------------------- | | accountId | string | Yes | Account identifier | | invoiceId | string | Yes | Invoice identifier | | amount | number | Yes | Paid amount in cents | | subscriptionId | string | No | Subscription identifier | | currency | string | No | ISO 4217 currency code | ## When to Fire * When payment is received * When manual reconciliation marks invoice paid * When Stripe `invoice.paid` webhook fires ## Stripe Webhook Maps to `invoice.paid`. # invoice_past_due Event Source: https://docs.upstackdata.com/pixel/saas-events/invoice-past-due Track when an invoice becomes past due. Fires when an invoice becomes past due. Use this event to trigger collection workflows and identify accounts at risk of involuntary churn. ## JavaScript ```javascript theme={null} window._upstack('track', 'invoice_past_due', { accountId: 'acct_abc123', invoiceId: 'inv_ghi012', subscriptionId: 'sub_def456', amount: 9900, currency: 'USD', daysOverdue: 7, attemptCount: 3 }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ------------------------------- | | accountId | string | Yes | Account identifier | | invoiceId | string | Yes | Invoice identifier | | amount | number | Yes | Past due amount in cents | | subscriptionId | string | No | Subscription identifier | | currency | string | No | ISO 4217 currency code | | daysOverdue | number | No | Days past the due date | | attemptCount | number | No | Number of payment attempts made | ## When to Fire * When invoice due date passes without payment * When Stripe marks invoice as past due * When payment retry fails ## Stripe Webhook Maps to `invoice.marked_uncollectible` or custom logic based on `invoice.payment_failed` status. <Warning> Past due invoices are an early indicator of involuntary churn. Use this event to trigger proactive outreach. </Warning> # milestone_reached Event Source: https://docs.upstackdata.com/pixel/saas-events/milestone-reached Track when a key milestone is achieved. Fires when a key milestone is achieved. Use this event to celebrate customer success and trigger engagement flows. ## JavaScript ```javascript theme={null} window._upstack('track', 'milestone_reached', { accountId: 'acct_abc123', milestoneId: 'milestone_100_orders', milestoneName: '100 Orders Processed', milestoneValue: 100 }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ---------------------- | | accountId | string | Yes | Account identifier | | milestoneId | string | Yes | Milestone identifier | | milestoneName | string | No | Milestone display name | | milestoneValue | number | No | Numeric value achieved | ## When to Fire * When usage threshold is crossed * When achievement is unlocked * When significant product milestone occurs # order_fulfilled Event Source: https://docs.upstackdata.com/pixel/saas-events/order-fulfilled Track when an order has been completely fulfilled (all items prepared for shipment). Fires when an order has been completely fulfilled (all items prepared for shipment). Use this event for subscription box businesses and physical product deliveries. ## JavaScript ```javascript theme={null} window._upstack('track', 'order_fulfilled', { orderId: 'ORD_12345', orderName: '#1042', value: 149.99, currency: 'USD', fulfillmentStatus: 'fulfilled', items: [ { id: 'SKU_001', name: 'Monthly Snack Box', price: 39.99, quantity: 1 } ], email: 'customer@example.com' }); ``` ## Properties | Property | Type | Required | Description | | ----------------- | ------ | -------- | ----------------------------------------------------- | | orderId | string | Yes | Order identifier | | orderName | string | No | Human-readable order name | | value | number | No | Order value | | currency | string | No | ISO 4217 currency code | | fulfillmentStatus | string | No | Fulfillment status (e.g., `'fulfilled'`, `'partial'`) | | items | array | No | Products fulfilled | | email | string | No | Customer email | ## When to Fire * When warehouse marks order as packed/ready * When Shopify fulfillment is created * When all items in an order are fulfilled # order_shipped Event Source: https://docs.upstackdata.com/pixel/saas-events/order-shipped Track when an order has been shipped and tracking information is available. Fires when an order has been shipped and tracking information is available. Use this event to trigger shipment notification flows. ## JavaScript ```javascript theme={null} window._upstack('track', 'order_shipped', { orderId: 'ORD_12345', orderName: '#1042', value: 149.99, currency: 'USD', trackingNumber: '1Z999AA10123456784', trackingCompany: 'UPS', trackingUrl: 'https://www.ups.com/track?tracknum=1Z999AA10123456784', estimatedDelivery: '2026-02-25T00:00:00.000Z', items: [ { id: 'SKU_001', name: 'Monthly Snack Box', price: 39.99, quantity: 1 } ], email: 'customer@example.com' }); ``` ## Properties | Property | Type | Required | Description | | ----------------- | ------ | -------- | ----------------------------------------------------- | | orderId | string | Yes | Order identifier | | orderName | string | No | Human-readable order name | | value | number | No | Order value | | currency | string | No | ISO 4217 currency code | | trackingNumber | string | No | Carrier tracking number | | trackingCompany | string | No | Shipping carrier (e.g., `'UPS'`, `'FedEx'`, `'USPS'`) | | trackingUrl | string | No | Direct link to tracking page | | estimatedDelivery | string | No | ISO 8601 estimated delivery date | | items | array | No | Products shipped | | email | string | No | Customer email | ## When to Fire * When shipping label is created with tracking * When carrier picks up package * When Shopify `fulfillment_events/create` webhook fires <Tip> **Klaviyo integration:** `order_shipped` is commonly used to trigger post-purchase flows like "Your order is on the way" emails with tracking information. </Tip> # payment_failed Event Source: https://docs.upstackdata.com/pixel/saas-events/payment-failed Track when a payment attempt fails. Fires when a payment attempt fails. Use this event to trigger dunning workflows and identify at-risk subscriptions. ## JavaScript ```javascript theme={null} window._upstack('track', 'payment_failed', { accountId: 'acct_abc123', invoiceId: 'inv_ghi012', subscriptionId: 'sub_def456', amount: 9900, failureReason: 'card_declined', failureCode: 'insufficient_funds', currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ------------------------------ | | accountId | string | Yes | Account identifier | | amount | number | Yes | Failed payment amount in cents | | invoiceId | string | No | Invoice identifier | | subscriptionId | string | No | Subscription identifier | | failureReason | string | No | Failure reason code | | failureCode | string | No | Detailed failure code | | currency | string | No | ISO 4217 currency code | ## When to Fire * When card is declined * When insufficient funds error occurs * When Stripe `invoice.payment_failed` webhook fires ## Stripe Webhook Maps to `invoice.payment_failed`. <Warning> Track payment failures to identify at-risk customers and trigger dunning workflows. </Warning> # payment_refunded Event Source: https://docs.upstackdata.com/pixel/saas-events/payment-refunded Track when a payment is refunded to the customer. Fires when a payment is refunded to the customer. Use this event to track refund rates and understand customer satisfaction issues. ## JavaScript ```javascript theme={null} window._upstack('track', 'payment_refunded', { accountId: 'acct_abc123', invoiceId: 'inv_ghi012', chargeId: 'ch_abc123', subscriptionId: 'sub_def456', amount: 9900, refundReason: 'customer_request', currency: 'USD', isPartialRefund: false }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------- | -------- | -------------------------------- | | accountId | string | Yes | Account identifier | | amount | number | Yes | Refunded amount in cents | | chargeId | string | No | Original charge identifier | | invoiceId | string | No | Invoice identifier | | subscriptionId | string | No | Subscription identifier | | refundReason | string | No | Reason for refund | | currency | string | No | ISO 4217 currency code | | isPartialRefund | boolean | No | Whether this is a partial refund | ## When to Fire * When refund is processed * When Stripe `charge.refunded` webhook fires * When support issues refund ## Stripe Webhook Maps to `charge.refunded`. # payment_succeeded Event Source: https://docs.upstackdata.com/pixel/saas-events/payment-succeeded Track when a payment is processed successfully. Fires when a payment is processed successfully. Use this event for revenue tracking and payment analytics. ## JavaScript ```javascript theme={null} window._upstack('track', 'payment_succeeded', { accountId: 'acct_abc123', invoiceId: 'inv_ghi012', subscriptionId: 'sub_def456', amount: 9900, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ----------------------- | | accountId | string | Yes | Account identifier | | amount | number | Yes | Payment amount in cents | | invoiceId | string | No | Invoice identifier | | subscriptionId | string | No | Subscription identifier | | currency | string | No | ISO 4217 currency code | ## When to Fire * When charge succeeds * When invoice is paid * When Stripe `invoice.paid` webhook fires ## Stripe Webhook Maps to `invoice.paid` or `charge.succeeded`. # seat_added Event Source: https://docs.upstackdata.com/pixel/saas-events/seat-added Track when additional seats are purchased. Fires when additional seats are purchased. Use this event to measure expansion revenue from seat-based pricing. ## JavaScript ```javascript theme={null} window._upstack('track', 'seat_added', { accountId: 'acct_abc123', subscriptionId: 'sub_def456', seatCount: 15, seatDelta: 5, mrrDelta: 2500 }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------- | | accountId | string | Yes | Account identifier | | seatCount | number | Yes | Total seats after addition | | subscriptionId | string | No | Subscription identifier | | seatDelta | number | No | Number of seats added | | mrrDelta | number | No | MRR increase from seats in cents | ## When to Fire * When seats are purchased * When user is added beyond plan limit * When Stripe subscription quantity increases ## Stripe Webhook Maps to `customer.subscription.updated` when subscription quantity increases. # seat_removed Event Source: https://docs.upstackdata.com/pixel/saas-events/seat-removed Track when seats are removed from the plan. Fires when seats are removed from the plan. Use this event to track seat contraction and understand downsizing patterns. ## JavaScript ```javascript theme={null} window._upstack('track', 'seat_removed', { accountId: 'acct_abc123', subscriptionId: 'sub_def456', seatCount: 10, seatDelta: -5, mrrDelta: -2500 }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ---------------------------------- | | accountId | string | Yes | Account identifier | | seatCount | number | Yes | Total seats after removal | | subscriptionId | string | No | Subscription identifier | | seatDelta | number | No | Number of seats removed (negative) | | mrrDelta | number | No | MRR decrease in cents (negative) | ## When to Fire * When seats are removed * When user is deactivated * When Stripe subscription quantity decreases ## Stripe Webhook Maps to `customer.subscription.updated` when subscription quantity decreases. # signed_out Event Source: https://docs.upstackdata.com/pixel/saas-events/signed-out Track when a user signs out of the application. Fires when a user signs out of the application. Use this event to understand session patterns and user behavior. ## JavaScript ```javascript theme={null} window._upstack('track', 'signed_out', { userId: 'usr_xyz789', accountId: 'acct_abc123', sessionDuration: 3600, signOutReason: 'user_initiated' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------------------------------------- | | userId | string | Yes | User identifier | | accountId | string | No | Account identifier | | sessionDuration | number | No | Session length in seconds | | signOutReason | string | No | Reason for sign out (`user_initiated`, `session_expired`, `forced`) | ## When to Fire * When user clicks sign out/logout button * When session expires * When user is forced out due to security event # signup_completed Event Source: https://docs.upstackdata.com/pixel/saas-events/signup-completed Track when a user completes signup and creates an account in your SaaS application. Fires when a user completes signup and creates an account. This is a key conversion event for measuring acquisition success. ## JavaScript ```javascript theme={null} window._upstack('track', 'signup_completed', { userId: 'usr_xyz789', accountId: 'acct_abc123', userEmail: 'jane@acme.com', planId: 'plan_pro_monthly', planName: 'Pro Plan' }); ``` ## Properties | Property | Type | Required | Description | | --------- | ------ | -------- | ---------------------- | | userId | string | Yes | New user identifier | | accountId | string | Yes | New account identifier | | userEmail | string | No | User email address | | planId | string | No | Selected plan | | planName | string | No | Plan display name | ## When to Fire * After signup form submission succeeds * After email verification completes * After OAuth signup flow finishes # signup_started Event Source: https://docs.upstackdata.com/pixel/saas-events/signup-started Track when a user begins the signup flow in your SaaS application. Fires when a user begins the signup flow. Use this event to measure signup funnel drop-off and optimize conversion. ## JavaScript ```javascript theme={null} window._upstack('track', 'signup_started', { planId: 'plan_pro_monthly', source: 'pricing_page' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------------- | | planId | string | No | Pre-selected plan (if applicable) | | source | string | No | Where signup was initiated | ## When to Fire * When signup form is opened * When registration page loads * When "Start Free Trial" button is clicked # subscription_cancelled Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-cancelled Track when a cancellation is requested (may still be active until period end). Fires when a cancellation is requested (may still be active until period end). Use this event to trigger win-back campaigns and measure cancellation reasons. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_cancelled', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', cancelReason: 'too_expensive', cancelFeedback: 'Budget constraints this quarter', mrr: 9900, cancelAtPeriodEnd: true }); ``` ## Properties | Property | Type | Required | Description | | ----------------- | ------- | -------- | ----------------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Cancelled plan | | cancelReason | string | No | Cancellation reason code | | cancelFeedback | string | No | User-provided feedback | | mrr | number | No | MRR being cancelled in cents | | cancelAtPeriodEnd | boolean | No | If true, cancels at end of billing period | ## When to Fire * When customer clicks cancel button * When cancellation request is submitted * When Stripe subscription is set to cancel at period end # subscription_churned Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-churned Track when a subscription ends completely (no longer billing). Fires when a subscription ends completely (no longer billing). This is the final churn event for calculating churn rate. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_churned', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', cancelReason: 'switched_competitor', mrr: 9900, ltv: 118800, subscriptionMonths: 12 }); ``` ## Properties | Property | Type | Required | Description | | ------------------ | ------ | -------- | -------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Churned plan | | cancelReason | string | No | Churn reason | | mrr | number | No | Lost MRR in cents | | ltv | number | No | Customer lifetime value in cents | | subscriptionMonths | number | No | How long they were subscribed | ## When to Fire * When final billing period ends * When subscription is deactivated * When Stripe `customer.subscription.deleted` fires ## Stripe Webhook Maps to `customer.subscription.deleted`. <Warning> Use this event to calculate churn rate and analyze churn reasons. Track `ltv` to understand which customer segments have the highest lifetime value. </Warning> # subscription_created Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-created Track when a subscription record is created in your billing system. Fires when a subscription record is created in your billing system. This may precede first payment for trials. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_created', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', billingInterval: 'month' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | --------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | Yes | Plan identifier | | planName | string | No | Plan display name | | billingInterval | string | No | `day`, `week`, `month`, or `year` | ## When to Fire * When subscription object is created in Stripe * May precede first payment (for trials) * After checkout session completes ## Stripe Webhook Maps to `customer.subscription.created`. # subscription_downgraded Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-downgraded Track when a customer downgrades to a lower-tier plan. Fires when a customer downgrades to a lower-tier plan. Use this event to identify at-risk accounts and measure contraction. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_downgraded', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_starter_monthly', planName: 'Starter', previousPlanId: 'plan_pro_monthly', mrr: 4900, mrrDelta: -5000 }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | New plan identifier | | planName | string | No | New plan name | | previousPlanId | string | No | Previous plan identifier | | mrr | number | No | New MRR after downgrade in cents | | mrrDelta | number | No | MRR decrease in cents (negative) | ## When to Fire * When plan changes from higher to lower tier * When features are removed from subscription * When scheduled downgrade takes effect at period end ## Stripe Webhook Maps to `customer.subscription.updated` when the new price is lower than the previous price. # subscription_initial_purchase Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-initial-purchase Track when a customer's first subscription payment is processed. Fires when a customer's first subscription payment is processed (distinct from trial conversion). Use this event for acquisition revenue metrics. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_initial_purchase', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', value: 9900, currency: 'USD', billingInterval: 'month' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ----------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Plan identifier | | planName | string | No | Plan display name | | value | number | No | Payment amount in cents | | currency | string | No | ISO 4217 currency code | | billingInterval | string | No | `month` or `year` | ## When to Fire * First subscription charge succeeds * After trial converts (first paid billing period) * When new customer's initial payment processes <Tip> Use `subscription_initial_purchase` for acquisition metrics and `subscription_recurring_purchase` for retention/LTV analysis. Together they give a complete picture of subscription revenue. </Tip> # subscription_paused Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-paused Track when a subscription is paused. Fires when a subscription is paused. Use this event to measure pause rates and understand seasonal patterns. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_paused', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', mrr: 9900, pauseReason: 'seasonal_business' }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | --------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Plan identifier | | mrr | number | No | Paused MRR in cents | | pauseReason | string | No | Why subscription was paused | ## When to Fire * When customer requests pause * When seasonal pause is activated * When Stripe subscription pause feature triggers ## Stripe Webhook Maps to `customer.subscription.paused`. # subscription_reactivated Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-reactivated Track when a previously churned customer resubscribes. Fires when a previously churned customer resubscribes. Use this event to measure win-back campaign effectiveness and recovered MRR. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_reactivated', { subscriptionId: 'sub_ghi789', accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', mrr: 9900, daysSinceChurn: 45 }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ----------------------------------- | | subscriptionId | string | Yes | New subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | New plan identifier | | planName | string | No | Plan display name | | mrr | number | No | Recovered MRR in cents | | daysSinceChurn | number | No | Days between churn and reactivation | ## When to Fire * When former customer signs up again * When win-back campaign converts * When churned account starts new subscription # subscription_recurring_purchase Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-recurring-purchase Track when a recurring subscription payment is processed (not the initial purchase). Fires when a recurring subscription payment is processed (not the initial purchase). Use this event for retention and LTV analysis. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_recurring_purchase', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', value: 9900, currency: 'USD', billingInterval: 'month', renewalNumber: 6 }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | -------------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Plan identifier | | planName | string | No | Plan display name | | value | number | No | Payment amount in cents | | currency | string | No | ISO 4217 currency code | | billingInterval | string | No | `month` or `year` | | renewalNumber | number | No | Which renewal this is (2nd, 3rd, etc.) | ## When to Fire * Each recurring billing cycle * When Stripe `invoice.paid` fires for an existing subscription * Monthly/annual renewal charge succeeds ## Stripe Webhook Maps to `invoice.paid` for existing subscriptions (not the first invoice). # subscription_resumed Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-resumed Track when a paused subscription is resumed. Fires when a paused subscription is resumed. Use this event to measure pause-to-resume rates and recovered MRR. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_resumed', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', mrr: 9900, pausedDays: 30 }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Plan identifier | | mrr | number | No | Resumed MRR in cents | | pausedDays | number | No | How long subscription was paused | ## When to Fire * When customer manually resumes * When pause period ends automatically * When billing restarts ## Stripe Webhook Maps to `customer.subscription.resumed`. # subscription_started Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-started Track when a new subscription begins (first billing period starts). Fires when a new subscription begins (first billing period starts). This marks the start of paid service. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_started', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', mrr: 9900, billingInterval: 'month' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ---------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | Yes | Plan identifier | | planName | string | No | Plan display name | | mrr | number | No | Monthly recurring revenue in cents | | billingInterval | string | No | Billing frequency | ## When to Fire * After first successful charge * When subscription status becomes `active` * After trial converts to paid # subscription_upgraded Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-upgraded Track when a customer upgrades to a higher-tier plan. Fires when a customer upgrades to a higher-tier plan. Use this event to measure expansion revenue and upsell success. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_upgraded', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_business_monthly', planName: 'Business', previousPlanId: 'plan_pro_monthly', mrr: 19900, mrrDelta: 10000 }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | New plan identifier | | planName | string | No | New plan name | | previousPlanId | string | No | Previous plan identifier | | mrr | number | No | New MRR after upgrade in cents | | mrrDelta | number | No | MRR increase in cents (positive) | ## When to Fire * When plan changes from lower to higher tier * When Stripe subscription item is updated with higher-priced plan * After upgrade checkout completes ## Stripe Webhook Maps to `customer.subscription.updated` when the new price is higher than the previous price. <Tip> Track `mrrDelta` alongside `subscription_downgraded` to calculate net revenue retention. </Tip> # trial_activated Event Source: https://docs.upstackdata.com/pixel/saas-events/trial-activated Track when a trial user reaches a meaningful activation milestone. Fires when a trial user reaches a meaningful activation milestone. Use this event to measure trial engagement and predict conversion likelihood. ## JavaScript ```javascript theme={null} window._upstack('track', 'trial_activated', { accountId: 'acct_abc123', planId: 'plan_pro_monthly', trialDaysRemaining: 12, activationMilestone: 'first_integration_connected' }); ``` ## Properties | Property | Type | Required | Description | | ------------------- | ------ | -------- | --------------------------- | | accountId | string | Yes | Account identifier | | planId | string | No | Trial plan identifier | | trialDaysRemaining | number | No | Days remaining in trial | | activationMilestone | string | No | Which milestone was reached | ## When to Fire * After first key feature is used * After onboarding checklist is completed * After first data import succeeds # trial_converted Event Source: https://docs.upstackdata.com/pixel/saas-events/trial-converted Track when a trial converts to a paid subscription. Fires when a trial converts to a paid subscription. This is a key conversion event for measuring trial success. ## JavaScript ```javascript theme={null} window._upstack('track', 'trial_converted', { accountId: 'acct_abc123', subscriptionId: 'sub_def456', planId: 'plan_pro_monthly', planName: 'Pro Plan', mrr: 9900, billingInterval: 'month' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ---------------------------------- | | accountId | string | Yes | Account identifier | | subscriptionId | string | Yes | New subscription ID | | planId | string | Yes | Converted plan identifier | | planName | string | No | Plan display name | | mrr | number | No | Monthly recurring revenue in cents | | billingInterval | string | No | `month` or `year` | ## When to Fire * After first successful payment * When Stripe subscription status changes from `trialing` to `active` * After payment method is charged successfully <Tip> Track `mrr` to measure trial-to-paid conversion value and calculate average revenue per converted trial. </Tip> # trial_ending_soon Event Source: https://docs.upstackdata.com/pixel/saas-events/trial-ending-soon Track when a trial is about to expire (typically 3 days before). Fires when a trial is about to expire (typically 3 days before). Use this event to trigger conversion campaigns and win-back flows. ## JavaScript ```javascript theme={null} window._upstack('track', 'trial_ending_soon', { accountId: 'acct_abc123', trialDaysRemaining: 3, planId: 'plan_pro_monthly', trialEndDate: '2026-03-04T14:30:00.000Z' }); ``` ## Properties | Property | Type | Required | Description | | ------------------ | ------ | -------- | --------------------- | | accountId | string | Yes | Account identifier | | trialDaysRemaining | number | Yes | Days until expiry | | planId | string | No | Trial plan identifier | | trialEndDate | string | No | Trial expiration date | ## When to Fire * 3 days before trial expires (common) * When Stripe sends `customer.subscription.trial_will_end` * When automated warning email triggers ## Stripe Webhook Maps to `customer.subscription.trial_will_end`. # trial_expired Event Source: https://docs.upstackdata.com/pixel/saas-events/trial-expired Track when a trial ends without conversion. Fires when a trial ends without conversion. Use this event to measure trial-to-paid conversion rates and identify drop-off reasons. ## JavaScript ```javascript theme={null} window._upstack('track', 'trial_expired', { accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', trialDays: 14 }); ``` ## Properties | Property | Type | Required | Description | | --------- | ------ | -------- | ------------------ | | accountId | string | Yes | Account identifier | | planId | string | No | Expired trial plan | | planName | string | No | Plan display name | | trialDays | number | No | Total trial length | ## When to Fire * When trial end date is reached without payment * When account is downgraded to free tier * When access is revoked after grace period # trial_extended Event Source: https://docs.upstackdata.com/pixel/saas-events/trial-extended Track when a trial period is extended. Fires when a trial period is extended. Use this event to track trial extensions and measure their impact on conversion. ## JavaScript ```javascript theme={null} window._upstack('track', 'trial_extended', { accountId: 'acct_abc123', trialEndDate: '2026-03-11T14:30:00.000Z', trialDaysRemaining: 7, extensionReason: 'support_request' }); ``` ## Properties | Property | Type | Required | Description | | ------------------ | ------ | -------- | ---------------------- | | accountId | string | Yes | Account identifier | | trialEndDate | string | No | New trial end date | | trialDaysRemaining | number | No | New days remaining | | extensionReason | string | No | Why trial was extended | ## When to Fire * After support manually extends trial * After promotional extension is applied * After win-back campaign grants extension # trial_started Event Source: https://docs.upstackdata.com/pixel/saas-events/trial-started Track when a user begins a free trial in your SaaS application. Fires when a user begins a free trial. This is the start of your trial-to-paid conversion funnel. ## JavaScript ```javascript theme={null} window._upstack('track', 'trial_started', { accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', trialEndDate: '2026-03-04T14:30:00.000Z', trialDaysRemaining: 14 }); ``` ## Properties | Property | Type | Required | Description | | ------------------ | ------ | -------- | ------------------------------ | | accountId | string | Yes | Account identifier | | planId | string | Yes | Trial plan identifier | | planName | string | No | Human-readable plan name | | trialEndDate | string | No | ISO 8601 trial expiration date | | trialDaysRemaining | number | No | Days until trial expires | ## When to Fire * After trial signup confirmation * After trial activation in billing system * After Stripe `customer.subscription.created` with trial ## Stripe Webhook Maps to `customer.subscription.created` when the subscription has a trial period. # user_activated Event Source: https://docs.upstackdata.com/pixel/saas-events/user-activated Track when a user reaches an activation milestone within the product. Fires when a user reaches an activation milestone within the product. Use this event to measure user onboarding success and product adoption. ## JavaScript ```javascript theme={null} window._upstack('track', 'user_activated', { userId: 'usr_xyz789', accountId: 'acct_abc123', userEmail: 'user@acme.com', activationMilestone: 'completed_onboarding', daysToActivation: 2 }); ``` ## Properties | Property | Type | Required | Description | | ------------------- | ------ | -------- | ------------------------------ | | userId | string | Yes | User identifier | | accountId | string | Yes | Account identifier | | userEmail | string | No | User email address | | activationMilestone | string | No | Which milestone was reached | | daysToActivation | number | No | Days from signup to activation | ## When to Fire * When user completes onboarding checklist * When user performs first key action * When user reaches engagement threshold # user_inactive Event Source: https://docs.upstackdata.com/pixel/saas-events/user-inactive Track when a user becomes inactive after a period of no engagement. Fires when a user becomes inactive after a period of no engagement. Use this event to trigger re-engagement campaigns and identify at-risk accounts. ## JavaScript ```javascript theme={null} window._upstack('track', 'user_inactive', { userId: 'usr_xyz789', accountId: 'acct_abc123', userEmail: 'user@acme.com', lastActiveDate: '2026-01-15T10:30:00.000Z', inactiveDays: 30 }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | --------------------------- | | userId | string | Yes | User identifier | | accountId | string | Yes | Account identifier | | userEmail | string | No | User email address | | lastActiveDate | string | No | ISO 8601 last activity date | | inactiveDays | number | No | Days since last activity | ## When to Fire * When user hasn't logged in for defined period (e.g., 30 days) * When automated inactivity check triggers * When engagement score drops below threshold # user_invited Event Source: https://docs.upstackdata.com/pixel/saas-events/user-invited Track when a user is invited to join an account. Fires when a user is invited to join an account. Use this event to measure team growth and invitation conversion rates. ## JavaScript ```javascript theme={null} window._upstack('track', 'user_invited', { accountId: 'acct_abc123', inviteeEmail: 'newmember@acme.com', inviteeRole: 'member', invitedByUserId: 'usr_xyz789' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | --------------------- | | accountId | string | Yes | Account identifier | | inviteeEmail | string | No | Invitee email address | | inviteeRole | string | No | Assigned role | | invitedByUserId | string | No | Inviter's user ID | ## When to Fire * When team invite is sent * When collaboration request is initiated * After invite email is dispatched # user_joined Event Source: https://docs.upstackdata.com/pixel/saas-events/user-joined Track when an invited user accepts and joins the account. Fires when an invited user accepts and joins the account. Use this event to measure invite-to-join conversion rates. ## JavaScript ```javascript theme={null} window._upstack('track', 'user_joined', { userId: 'usr_newmember', accountId: 'acct_abc123', userEmail: 'newmember@acme.com', userRole: 'member' }); ``` ## Properties | Property | Type | Required | Description | | --------- | ------ | -------- | -------------------- | | userId | string | Yes | New user identifier | | accountId | string | Yes | Account identifier | | userEmail | string | No | User email address | | userRole | string | No | User's assigned role | ## When to Fire * When invite is accepted * When account access is granted * After user completes join flow # user_removed Event Source: https://docs.upstackdata.com/pixel/saas-events/user-removed Track when a user is removed from an account. Fires when a user is removed from an account. Use this event to track team changes and understand user churn at the account level. ## JavaScript ```javascript theme={null} window._upstack('track', 'user_removed', { userId: 'usr_xyz789', accountId: 'acct_abc123', userEmail: 'removed@acme.com', removedByUserId: 'usr_admin123', removalReason: 'left_company' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | -------------------------------------------------------------------------- | | userId | string | Yes | Removed user identifier | | accountId | string | Yes | Account identifier | | userEmail | string | No | Removed user's email address | | removedByUserId | string | No | Admin who removed the user | | removalReason | string | No | Reason for removal (`left_company`, `role_change`, `security`, `inactive`) | ## When to Fire * When admin removes user from team * When user access is revoked * When user is deactivated from account # webinar_registered Event Source: https://docs.upstackdata.com/pixel/saas-events/webinar-registered Track when a user registers for a webinar or virtual event. Fires when a user registers for a webinar or virtual event. Use this event to measure event marketing performance and track registrant-to-attendee conversion. ## JavaScript ```javascript theme={null} window._upstack('track', 'webinar_registered', { webinarId: 'web_product_demo_2024', webinarTitle: 'Product Demo: Advanced Analytics Features', webinarDate: '2026-03-15T14:00:00.000Z', userEmail: 'attendee@company.com', companyName: 'Attendee Corp', source: 'email_campaign' }); ``` ## Properties | Property | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------ | | webinarId | string | Yes | Unique webinar identifier | | webinarTitle | string | No | Human-readable webinar title | | webinarDate | string | No | ISO 8601 scheduled date | | userEmail | string | No | Registrant's email address | | companyName | string | No | User's company name | | source | string | No | Where the registration was initiated | ## When to Fire * After webinar registration form submission * After calendar invite is sent * After registration confirmation email is delivered # How to Install the Upstack Data Tracking Pixel Source: https://docs.upstackdata.com/pixel/setup Install the Upstack Data pixel on any website in 5 minutes. Covers installation, verification, common tracking patterns, and identity capture. Get the Upstack pixel running on your site in under 5 minutes. This guide covers non-Shopify installations — if you're on Shopify, use the [Shopify app installation guide](/guides/shopify/how-to-download-and-install-upstack-data-app-in-shopify) instead. ## Installation Add this code snippet to every page you want to track, just before the closing `</head>` tag: ```html theme={null} <script> window._upstack = window._upstack || function() { (window._upsqueue = window._upsqueue || []).push(arguments); }; _upstack('init', 'YOUR_PIXEL_ID'); </script> <script async src="https://prod2-cdn.upstackified.com/scripts/px/ups.min.js"></script> ``` <Warning> Replace `YOUR_PIXEL_ID` with your actual pixel ID from the [Upstack dashboard](https://app.upstackdata.com). Your pixel ID starts with `px_`. </Warning> ### Where to Find Your Pixel ID 1. Log in to [app.upstackdata.com](https://app.upstackdata.com) 2. Navigate to **Settings** → **Pixel** 3. Copy your pixel ID (format: `px_abc123def456`) *** ## Where to Place the Code ### Standard Websites Place the snippet in your site's `<head>` section on every page: ```html theme={null} <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>My Store

# Attribution Reporting Source: https://docs.upstackdata.com/analytics/attribution-reporting Compare attribution models, understand channel credit allocation, configure lookback windows, and read the Upstack attribution dashboard. Attribution reporting answers the question every merchant asks: "Which marketing channels actually drive my revenue?" By analyzing the full customer journey from your first-party data, Upstack Analytics assigns conversion credit across channels using multiple attribution models — giving you an independent, unbiased view of performance. Most merchants discover that their true channel mix looks significantly different from what ad platforms self-report. Attribution reporting helps you reallocate budget toward the channels that genuinely drive incremental revenue. ## Available Attribution Models Upstack Analytics supports four attribution models. Each model uses the same underlying data — identity-resolved customer journeys — but distributes conversion credit differently. | Model | How Credit Is Assigned | Best For | | --------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | **First-Touch** | 100% credit to the first marketing touchpoint in the journey. | Measuring top-of-funnel acquisition. Which channels bring new customers to your store? | | **Last-Touch** | 100% credit to the final touchpoint before conversion. | Comparing with ad platform reporting (most platforms default to last-touch). | | **Linear** | Equal credit split across all touchpoints in the journey. | Balanced view of the full funnel. Surfaces mid-funnel contributors that single-touch models miss. | | **Time-Decay** | More credit to touchpoints closer to the conversion. Older touchpoints receive progressively less. | Weighted view that respects recency while acknowledging the full journey. | No single model is "correct." Each reveals a different aspect of your marketing performance. The most useful insights come from comparing models side-by-side. ## Comparing Models The attribution dashboard lets you view the same data through multiple models simultaneously. This reveals channels that look different depending on how you measure: **Example comparison for a DTC apparel store:** | Channel | First-Touch Revenue | Last-Touch Revenue | Linear Revenue | Time-Decay Revenue | | -------------- | ------------------- | ------------------ | -------------- | ------------------ | | Meta Ads | \$42,000 | \$31,000 | \$35,500 | \$33,200 | | Google Search | \$18,000 | \$28,000 | \$22,000 | \$24,800 | | Klaviyo Email | \$2,000 | \$19,000 | \$12,500 | \$15,600 | | Organic Social | \$15,000 | \$4,000 | \$9,000 | \$6,400 | | Direct | \$3,000 | \$8,000 | \$6,000 | \$7,000 | In this example, Meta Ads is the strongest acquisition channel (first-touch), Google Search and Klaviyo are strong closers (last-touch), and Organic Social is an underappreciated top-of-funnel contributor that last-touch nearly zeroes out. ## Understanding Channel Credit Channel credit is the aggregated attribution for a marketing channel across all conversions in your selected time period. ### What Counts as a Touchpoint A touchpoint is a session where the visitor arrived through a trackable marketing channel: * **Paid Social** — Session with `utm_source = facebook`, `instagram`, etc. * **Paid Search** — Session with `utm_source = google`, `bing` and `utm_medium = cpc` * **Email** — Session with `utm_source = klaviyo`, `mailchimp`, etc. * **Organic Search** — Session with referrer from a search engine and no paid UTM parameters * **Organic Social** — Session with referrer from a social platform and no paid UTM parameters * **Direct** — Session with no referrer and no UTM parameters ### How Credit Sums Work Within a single attribution model, total attributed revenue equals your actual total revenue. There is no double-counting — this is the fundamental advantage over ad platform self-reporting. If a customer journey has three touchpoints and results in a $90 purchase, the Linear model assigns $30 to each channel. The total attributed is still \$90. Attribution credit only applies to conversions (Purchase events) that occur within the selected lookback window. Changing the lookback window changes the eligible touchpoints and may shift credit between channels. ## Lookback Windows The lookback window defines how far back Upstack searches for qualifying touchpoints before a conversion. | Window | Description | When to Use | | ----------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------- | | **7 days** | Only touchpoints within the past week count. | Short consideration cycle products (impulse buys, low AOV). Fast feedback on recent campaigns. | | **14 days** | Two-week attribution window. | Moderate consideration cycles. Good default for most apparel and accessories stores. | | **28 days** | Four-week attribution window. | Longer consideration cycles (furniture, electronics, high-AOV products). | | **Custom** | Set any number of days (1–90). | When your business has a specific purchase cycle you want to match. | A shorter window gives credit to channels that drive quick conversions. A longer window captures channels that influence early in the journey but convert later. Test different windows to see how your channel mix shifts. ## Reading the Attribution Dashboard The attribution dashboard organizes data into four sections: ### Channel Overview A summary table showing each channel's attributed revenue, conversion count, and ROAS across your selected model and date range. This is your starting point for budget allocation decisions. ### Model Comparison Side-by-side view of all four models for the same time period. Use this to identify channels that vary significantly across models — those are the ones worth investigating further. ### Journey Explorer Drill into individual customer journeys to see the exact sequence of touchpoints. Filter by channel, conversion value, or number of touchpoints. Useful for understanding how your customers actually discover and buy from your store. ### Trend View Attribution credit by channel over time. See how channel performance evolves week-over-week. Identify seasonal patterns, campaign impacts, and long-term shifts in your marketing mix. ## Tips for Actionable Attribution **Start with comparison, not a single model.** Look at where models agree (strong signal) and where they disagree (needs investigation). **Match the lookback window to your product.** A 28-day window for a $15 impulse buy dilutes signal. A 7-day window for a $500 product misses the real journey. **Use first-touch for acquisition budgets.** If you're trying to grow your customer base, first-touch tells you which channels bring net-new visitors. **Use last-touch to benchmark against platforms.** Compare Upstack's last-touch to Meta's self-reported numbers. The gap reveals how much each platform over-claims. **Watch the Linear model for hidden contributors.** Channels that score low on both first-touch and last-touch but appear in Linear are mid-funnel influencers. Cutting them may quietly reduce overall conversion rates. Deeper explanation of how attribution models work and why independent measurement matters. Learn to build custom queries for more granular attribution analysis. # Custom Measures Source: https://docs.upstackdata.com/analytics/custom-measures Build your own metrics and KPIs in Upstack Analytics with a formula editor — combine revenue, spend, and order measures into custom ratios you can chart on any dashboard. Custom measures let you define your own metric from a formula over the measures Upstack already tracks — without waiting on an engineering change. Combine revenue, spend, orders, and other measures with arithmetic to create the KPI your team actually reports on, such as net margin %, profit per order, or a blended efficiency ratio. A custom measure behaves exactly like a built-in measure. It respects the dashboard's filters, date range, comparison period, and granularity, and it picks up your cost adjustments — so the number stays consistent with the rest of your report. ## How custom measures work A custom measure is a formula written over existing **base measures**. Upstack compiles that formula and computes it on the same engine that powers built-in ratio measures like ROAS and MER, so the result is calculated server-side against your data — not approximated in the browser. For example, this formula defines your marketing efficiency ratio (MER) — total revenue earned per dollar of ad spend: ```text theme={null} orders.total_revenue / channel.spend ``` Each operand (`orders.total_revenue`, `channel.spend`) is a base measure you select from a picker, so you never have to remember exact names. Set the format to **Multiplier** and the result displays as `3.2×`. ## Creating a custom measure Custom measures are scoped to a single pixel and managed from a **custom dashboard**. Creating, editing, and deleting custom measures is available to **admin and owner** roles, matching the permissions for cost settings. Viewers can still chart existing custom measures but won't see the management entry points. On a custom dashboard, click **Custom Measures** in the dashboard toolbar. You can also open it from the **Manage custom measures** link next to the **Metric** field when adding or editing a widget. Click **+ New custom measure** to open the builder. Enter a **Name** (e.g., `Marketing Efficiency Ratio`) and an optional **Short title** (e.g., `MER`) used where space is tight, such as chart legends and compact cards. Add an optional **Description** — it appears in the measure's tooltip. Set the **Format** — Number, Currency, Percentage, or Multiplier — and the value displays accordingly across charts and summary cards. Choose how the measure rolls up across the selected date range in the summary card: * **Sum** — adds each period's value (use for additive measures like revenue net of ad spend). * **Average** — recomputes the ratio over the whole period (use for ratios and percentages like MER or ad spend %). Upstack infers a sensible default from your formula; override it if needed. Type your formula, using **Insert measure** to add base measures from a searchable, grouped picker. Validation runs as you type — a valid formula shows **Formula is valid.**, and errors explain what to fix. Click **Save**. The measure is enabled by default and immediately available in the measure picker. Use the eye icon in the list to disable a measure without deleting it. ## Writing formulas Formulas support standard arithmetic over base measures and numeric constants: | Element | Allowed | | --------- | ------------------------------------------------------------------------------------ | | Operators | `+` `-` `*` `/` | | Grouping | `(` `)` | | Numbers | Literal constants (e.g., `100`, `0.3`) | | Operands | Base measures inserted from the picker (e.g., `orders.net_revenue`, `channel.spend`) | Some common patterns: | Goal | Formula | Format | | -------------------------------- | ------------------------------------------ | ---------- | | Marketing efficiency ratio (MER) | `orders.total_revenue / channel.spend` | Multiplier | | Ad spend as % of net revenue | `channel.spend / orders.net_revenue * 100` | Percentage | | Net revenue after ad spend | `orders.net_revenue - channel.spend` | Currency | | Ad cost per order | `channel.spend / orders.count` | Currency | `orders.net_revenue` is net sales (after discounts and refunds) but **before** COGS and operating costs — so `orders.net_revenue - channel.spend` is revenue net of ad spend only, not true profit. To build a margin metric that reflects fulfillment and operating costs, include the relevant cost measures from the picker and make sure your [cost settings](/get-started/cost-settings) are configured. Division by zero returns 0, and any base measure with no data in a period is treated as 0. This keeps charts continuous instead of showing gaps or errors. ## Using a custom measure on a dashboard Once saved and enabled, a custom measure appears in the **Custom** group of the measure picker when you add or edit a widget on a custom dashboard. Select it like any built-in measure — it works with Metric, Sparkline, Bar, and Area chart types. Because it runs on the same query path as built-in measures, the widget automatically reflects the dashboard's current filters, date range, comparison period, and granularity. No extra configuration is needed. ## What custom measures inherit Custom measures reuse the standard query engine, so they pick up the same context as built-in measures automatically: * **Filters** — applied per source so each operand is filtered correctly (an orders filter only affects orders measures, an ads filter only affects ad measures). * **Date range, comparison period, and granularity** — threaded through unchanged. * **Cost adjustments** — formulas that reference cost-adjusted measures are recomputed against your contribution-margin settings, matching how built-in cost measures behave. See [Cost settings](/get-started/cost-settings). ## Limitations Custom measures are designed to behave like built-in measures, which sets a few boundaries in this version: * **Base measures only.** Operands must be measures available in the picker. You can't reference already-derived measures (such as ROAS or MER), attribution-only measures, or another custom measure. * **Not attribution-adjusted.** Like other non-attribution measures on the dashboard, custom measures are not adjusted by attribution model or window. For attribution analysis, use [Attribution reporting](/analytics/attribution-reporting). * **Custom dashboards only.** Custom measures are selectable on custom dashboards; they aren't yet available in other surfaces. ## Related The base measures you build custom formulas from. Build reports with measures, dimensions, and filters. Configure costs so margin-based custom measures are accurate. Compare attribution models and channel credit allocation. # Querying Data in Upstack Analytics Source: https://docs.upstackdata.com/analytics/query-guide Query events, sessions, and attribution data in Upstack Analytics — build reports with measures and dimensions, filter by channel and campaign, and export results for further analysis. Upstack Analytics gives you direct access to your identity-resolved, enriched event data. You can explore traffic patterns, measure conversion funnels, compare channel performance, and build custom reports — all from a single dashboard backed by your first-party data. Unlike ad platform dashboards that only show their own ecosystem, Upstack Analytics queries your unified event stream. You see every channel, every touchpoint, and every conversion in one place with consistent measurement. ## What You Can Query Upstack Analytics organizes data into three primary views: ### Events Query raw events with filters and aggregations. Useful for: * Counting events by type over time (e.g., "How many AddToCart events this week?") * Filtering by event properties (e.g., "All Purchase events where `value` > \$100") * Grouping by dimensions (e.g., "PageViews by device type and country") ### Sessions Query session-level metrics that aggregate events into browsing sessions. Useful for: * Understanding engagement patterns (session duration, pages per session, bounce rate) * Comparing session quality across traffic sources * Identifying high-intent sessions that didn't convert ### Attribution Query attribution data that assigns conversion credit across marketing touchpoints. Useful for: * Comparing channel performance across attribution models * Calculating true ROAS per channel * Identifying which campaigns drive the highest-value customers ## Using the Query Builder The Upstack Analytics dashboard provides a visual query builder that lets you construct queries without writing SQL. ### 1. Select Your Measures Measures are the numeric values you want to calculate. Choose one or more: * **Total Events** — Count of events matching your filters * **Unique Visitors** — Distinct identity count * **Revenue** — Sum of Purchase event values * **Conversion Rate** — Purchases divided by sessions * **Average Order Value** — Revenue divided by purchase count See [Measures & Dimensions](/data-dictionary/measures-and-dimensions) for the full list. ### 2. Choose Your Dimensions Dimensions break down your measures into categories: * **Date** — Time-series view (daily, weekly, monthly) * **UTM Source** — Group by traffic source * **Device Type** — Compare mobile vs. desktop * **Country** — Geographic breakdown * **Event Name** — Group by event type ### 3. Set Date Range Select a predefined range or set custom start and end dates: | Preset | Range | | ------------ | ----------------------- | | Today | Current day | | Last 7 days | Rolling 7-day window | | Last 30 days | Rolling 30-day window | | This month | Calendar month to date | | Last month | Previous calendar month | | Custom | Any start and end date | All dates are in UTC. Data is available within minutes of the event occurring. ### 4. Apply Filters Narrow your results with filters on any dimension or event property: * `utm_source = facebook` — Only Facebook traffic * `device_type = mobile` — Only mobile visitors * `event_name = Purchase` — Only purchase events (use PascalCase in queries) * `country = US` — Only US visitors * `value > 50` — Only events with value above \$50 Event names in analytics queries use **PascalCase** (e.g., `Purchase`, `AddToCart`). This is the destination format used in storage. When tracking via the SDK, use **snake\_case** (e.g., `purchase`, `add_to_cart`). Filters can be combined with AND logic. Multiple values for the same field use OR logic (e.g., `utm_source = facebook OR google`). ### 5. Set Grouping Choose how to group your results. You can group by one or more dimensions: * **Single dimension:** Revenue by `utm_source` → bar chart comparing channels * **Two dimensions:** Revenue by `utm_source` and `date` → time series per channel * **No grouping:** Single aggregate number across all matching data ## Reading Results Query results are displayed as both a chart and a data table. You can: * **Toggle chart types** — Line, bar, or table view * **Export data** — Download results as CSV for further analysis * **Save as report** — Save the query configuration for quick access later * **Share** — Generate a shareable link to the report Saved reports update automatically. When you open a saved report, it re-executes the query against the latest data with the same filters, dimensions, and date range logic. ## Common Query Patterns **Conversion funnel:** Select measures for PageViews, AddToCart, InitiateCheckout, and Purchase counts. Group by date to see the funnel over time. **Channel comparison:** Select Revenue and Conversion Rate. Group by `utm_source`. Filter to last 30 days. Compare which channels drive the most efficient revenue. **Device breakdown:** Select Sessions and Bounce Rate. Group by `device_type`. Identify whether mobile experience needs optimization. **Top pages:** Select PageViews and Unique Visitors. Group by `page_path`. Sort by PageViews descending to find your highest-traffic pages. Full reference for every measure and dimension available in the query builder. Define your own metrics and KPIs from a formula over existing measures. Dive deeper into session-level and page-level metrics. Compare attribution models and understand channel credit allocation. Review the standard events that feed your analytics queries. # Session and Page Analytics Source: https://docs.upstackdata.com/analytics/session-and-page-analytics Measure session and page performance in Upstack Analytics — duration, bounce rate, engagement, scroll depth, and pageviews — to diagnose UX issues and rank top-performing content. Session and page analytics help you understand how visitors interact with your store beyond individual events. Sessions group a visitor's events into a single browsing journey. Page metrics reveal which content engages and which drops visitors off. Session analytics are especially useful for identifying where visitors disengage. A high bounce rate on product pages paired with strong AddToCart rates on collection pages might indicate your product pages need stronger calls-to-action. ## Session Metrics A **session** begins when a visitor loads their first page and ends after 30 minutes of inactivity. All events within that window are grouped under a single `session_id`. ### Available Session Metrics | Metric | Description | How It's Calculated | | ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | | **Session Duration** | Total time spent in the session. | Time between the first and last event in the session. | | **Pages per Session** | Number of distinct pages viewed. | Count of PageView events with unique `page_path` values. | | **Bounce Rate** | Percentage of single-page sessions. | Sessions with exactly one PageView and no other interaction events, divided by total sessions. | | **Engagement Score** | Composite score reflecting session quality. | Weighted combination of pages viewed, time on site, and interaction events (AddToCart, Search, etc.). Scale: 0–100. | | **Session Conversion** | Whether the session included a Purchase. | Binary: `converted` or `not_converted`. | | **Events per Session** | Total number of events fired during the session. | Count of all events in the session. | ### Filtering by Session Properties You can filter analytics data by session-level attributes to isolate specific visitor segments: * **Traffic source** — `utm_source = facebook` shows only sessions from Facebook traffic * **Device type** — `device_type = mobile` isolates mobile browsing behavior * **Geography** — `country = US` limits to US sessions * **New vs. returning** — `is_returning = true` shows only repeat visitors * **Conversion status** — `session_conversion = converted` filters to sessions that resulted in a purchase Combine session filters with any measure to answer targeted questions: * "What is the average session duration for mobile visitors from Facebook who converted?" * "What's the bounce rate for desktop visitors landing on collection pages?" ## Page Metrics Page analytics aggregate data at the `page_path` level, showing how individual pages perform across all sessions. ### Available Page Metrics | Metric | Description | How It's Calculated | | ------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | **Page Views** | Total times the page was viewed. | Count of PageView events for the `page_path`. | | **Unique Visitors** | Distinct visitors who viewed the page. | Count of unique `identity_id` or `session_id` values. | | **Time on Page** | Average time visitors spend on the page. | Difference between the PageView timestamp and the next event's timestamp within the session. | | **Scroll Depth** | How far down the page visitors scroll on average. | Percentage of page height scrolled, captured by the Upstack Pixel. | | **Exit Rate** | Percentage of sessions that ended on this page. | Sessions where this page's PageView was the last event, divided by total PageViews for this page. | | **Entry Rate** | Percentage of sessions that started on this page. | Sessions where this page's PageView was the first event, divided by total PageViews for this page. | Time on Page is calculated from the interval between consecutive events. If the visitor's session ends on a page (no subsequent event), time on page cannot be measured for that visit. These unmeasured visits are excluded from the average. ### Filtering by Page Path Page analytics support filtering by URL path patterns: * **Exact match** — `page_path = /products/classic-tee` * **Starts with** — `page_path starts with /collections/` shows all collection pages * **Contains** — `page_path contains /blog/` shows all blog content ### Common Page Analysis Patterns **Top pages by traffic:** Select Page Views and Unique Visitors. Group by `page_path`. Sort by Page Views descending. Identifies your highest-traffic content. **Landing page quality:** Select Bounce Rate and Entry Rate. Group by `page_path`. Filter to pages with high Entry Rate. A landing page with high traffic but high bounce rate needs optimization. **Product page engagement:** Filter `page_path starts with /products/`. Select Time on Page, Scroll Depth, and the AddToCart rate. Identifies which product pages drive the most engagement. **Content performance:** Filter `page_path starts with /blogs/`. Select Page Views, Time on Page, and Scroll Depth. Longer time on page and deeper scroll depth indicate content that resonates. ## Connecting Sessions to Outcomes Session and page metrics become most powerful when connected to conversion data: | Question | How to Answer | | ----------------------------------------------- | --------------------------------------------------------------------------- | | Which landing pages drive the most revenue? | Group Revenue by `page_path` (entry pages only) | | Do longer sessions convert better? | Compare Session Duration for converted vs. non-converted sessions | | What's the engagement threshold for conversion? | Compare Engagement Score distributions for converting vs. bouncing sessions | | Which pages are in the conversion path? | Look at page sequences for sessions with a Purchase event | Bounce rate can be misleading on its own. A blog post with high bounce rate might still be valuable if it drives email signups (Subscribe events). Always consider bounce rate alongside other engagement signals. Full reference for all available measures and dimensions. Understand how conversions are attributed across marketing channels. # Get order settings Source: https://docs.upstackdata.com/api-reference/account/get-order-settings /api-reference/openapi.yaml get /accounts/api/account/settings/order Return the account's order settings — count flags for pending / voided orders, refund-date attribution, and the list of exclusion filters that drop matching orders from every analytics query. Defaults are applied when the account has no stored `orderSettings` (`countPendingOrders=false`, `countVoidedOrders=false`, `refundDateAttribution=refund_date`, `exclusionFilters=[]`) so the response shape is always complete. **Required scope:** `account:read`. # Get the account Source: https://docs.upstackdata.com/api-reference/account/get-the-account /api-reference/openapi.yaml get /accounts/api/account Return the account that owns this API key — display name, active owners and admins, and the current subscription summary (when present). The authorizer resolves the account from the API key's parent pixel, so no `accountId` is in the path or body. **Required scope:** `account:read`. # Rename the account Source: https://docs.upstackdata.com/api-reference/account/rename-the-account /api-reference/openapi.yaml patch /accounts/api/account Rename the account that owns this API key. Single-field strict allowlist — `accountName` is the only accepted field; any other key in the body is rejected with 400. Emits an `accountUpdated` EventBridge event with `actor: cli:{apiKeyPk}` so downstream consumers can distinguish UI vs API-key mutations. **Required scope:** `account:write`. # Replace order settings Source: https://docs.upstackdata.com/api-reference/account/replace-order-settings /api-reference/openapi.yaml put /accounts/api/account/settings/order Replace the account's order settings in full. **PUT-the-whole-config semantics** — any existing exclusion filter not present in the body is deleted. The server assigns `id`, `createdAt`, and `updatedAt` on new filters (and on nested groups + conditions); entries that already carry an `id` preserve their `createdAt` and get a bumped `updatedAt`. Strict allowlist at every nesting level — extra keys in the body, in a filter, in a group, or in a condition are rejected with 400. Operators must be valid for the chosen field type per `ORDER_EXCLUSION_FIELD_CATALOG` (e.g. `greater_than` on `sourceName` is rejected). Emits an `accountUpdated` EventBridge event with `actor: cli:{apiKeyPk}` and `change: { kind: "orderSettings" }`. **Required scope:** `account:write`. # List channel entities with optional metrics Source: https://docs.upstackdata.com/api-reference/analytics/list-channel-entities-with-optional-metrics /api-reference/openapi.yaml post /db-mgmt/api/query-channel-details List ad accounts, campaigns, ad sets, or ads from the ads-platform integrations connected to your pixel, with optional metric aggregation over a date range. **Required scope:** `analytics:read`. # Run a cohort analysis Source: https://docs.upstackdata.com/api-reference/analytics/run-a-cohort-analysis /api-reference/openapi.yaml post /db-mgmt/api/query-cohort-analysis Cohort an audience by acquisition period and analyze retention or LTV over time. Limited to cohort-specific measures and to weekly / monthly / yearly granularity. **Required scope:** `analytics:read`. # Run an analytics query Source: https://docs.upstackdata.com/api-reference/analytics/run-an-analytics-query /api-reference/openapi.yaml post /db-mgmt/api/query Execute a measures-and-dimensions query against your event stream. Mirrors the in-app query builder. **Required scope:** `analytics:read`. See [Querying Data](/analytics/query-guide) for a guided walkthrough. # Run an attribution query Source: https://docs.upstackdata.com/api-reference/analytics/run-an-attribution-query /api-reference/openapi.yaml post /db-mgmt/api/query-attribution Attribute conversions across marketing touchpoints. Supports first-click, last-click, and any-click models with a fixed-set lookback window. **Required scope:** `analytics:read`. # List available measures Source: https://docs.upstackdata.com/api-reference/catalog/list-available-measures /api-reference/openapi.yaml get /db-mgmt/api/measures Return the catalog of measures available to your pixel — the same list the in-app query builder shows. Use this to discover canonical measure ids before constructing a query or building a dashboard. **Required scope:** `analytics:read`. # List filter fields Source: https://docs.upstackdata.com/api-reference/catalog/list-filter-fields /api-reference/openapi.yaml get /db-mgmt/api/filters Return the catalog of filterable fields available across your query endpoints — field id, label, value type, supported operators, and the endpoint contexts each field applies to. Use this to discover canonical filter ids before constructing a `filters` body on any query endpoint. **Required scope:** `analytics:read`. # Add a cost line Source: https://docs.upstackdata.com/api-reference/costs/add-a-cost-line /api-reference/openapi.yaml post /accounts/api/costs/lines Add a new cost line for one of the five line-typed cost surfaces — `order`, `gateway`, `shipping` (profile rule), `variable`, or `fixed`. The server assigns a ULID for the new line. The `line` body is discriminated by `costType` — see the per-type schemas (`OrderCostLine`, `GatewayCostLine`, `ShippingProfileCostLine`, `VariableCostLine`, `FixedCostLine`) for the shape required by each. Triggers a per-order COGS recalculation downstream — except for `variable` and `fixed`, which apply at aggregate report time and do not require per-order recalc. **Required scope:** `costs:write`. # Delete a cost line Source: https://docs.upstackdata.com/api-reference/costs/delete-a-cost-line /api-reference/openapi.yaml delete /accounts/api/costs/lines/{lineId} Remove a cost line from the named cost config by its ULID. Triggers a per-order COGS recalculation downstream — the deleted line is passed to the recalc trigger so affected orders can be identified. **Required scope:** `costs:write`. # Get cost configuration Source: https://docs.upstackdata.com/api-reference/costs/get-cost-configuration /api-reference/openapi.yaml get /accounts/api/costs Return the account's cost configuration. Use `?type=` to filter to a single cost type; omit it to get the full bag. **Required scope:** `costs:read`. # Update a cost line Source: https://docs.upstackdata.com/api-reference/costs/update-a-cost-line /api-reference/openapi.yaml put /accounts/api/costs/lines/{lineId} Partial-update an existing cost line by its ULID. Only the fields supplied in `updates` are written; omitted fields stay as-is. Triggers a per-order COGS recalculation downstream (except for `variable` and `fixed`). **Required scope:** `costs:write`. # Update shipping cost settings Source: https://docs.upstackdata.com/api-reference/costs/update-shipping-cost-settings /api-reference/openapi.yaml put /accounts/api/costs/shipping-settings Switch the shipping cost attribution method. `fixedRateAmount` is required when `method=fixed_rate`. Triggers a per-order COGS recalculation downstream. **Required scope:** `costs:write`. # Update the global product override Source: https://docs.upstackdata.com/api-reference/costs/update-the-global-product-override /api-reference/openapi.yaml put /accounts/api/costs/global-product-override Update the default COGS / handling fee applied to product variants that have no per-variant COG line. At least one of `defaultCogs`, `globalHandlingFee`, or `currency` must be supplied. Triggers a per-order COGS recalculation downstream (same SQS message the web UI emits for this change). **Required scope:** `costs:write`. # Build a dashboard from a measure list (preset) Source: https://docs.upstackdata.com/api-reference/dashboards/build-a-dashboard-from-a-measure-list-preset /api-reference/openapi.yaml post /accounts/api/dashboard/views/from-preset High-level builder — pass a list of measures, get back a finished dashboard with auto-laid-out widgets. The backend packs sparkline tiles 4-per-row in the `kpi-grid` layout and fills in sensible defaults for attribution, granularity, date range, and filters. **Required scope:** `dashboards:write`. Designed for AI-driven workflows ("make me a dashboard with NC ROAS, MER, and Facebook CPM"). The [`upstack dashboard view build`](/cli/dashboard-view) CLI command wraps this endpoint. # Create a dashboard view Source: https://docs.upstackdata.com/api-reference/dashboards/create-a-dashboard-view /api-reference/openapi.yaml post /accounts/api/dashboard/views Create a dashboard view from a full `DashboardViewConfiguration` body. For the high-level builder that auto-lays-out widgets from a measure list, see the `POST /api/dashboard/views/from-preset` endpoint. **Required scope:** `dashboards:write`. `createdBy` and `updatedBy` on the resulting record are empty strings — api-key writes intentionally don't store a fake user id. Audit info (`apiKeyPk`) is recorded in CloudWatch logs. # Delete a dashboard view Source: https://docs.upstackdata.com/api-reference/dashboards/delete-a-dashboard-view /api-reference/openapi.yaml delete /accounts/api/dashboard/views/{dashboardViewId} **Required scope:** `dashboards:write`. # Duplicate a dashboard view Source: https://docs.upstackdata.com/api-reference/dashboards/duplicate-a-dashboard-view /api-reference/openapi.yaml post /accounts/api/dashboard/views/{dashboardViewId}/copy Create a copy of an existing view. The copy inherits the source's name and order; rename via `PATCH` afterwards if needed. Body must be empty (an empty object `{}` is accepted; unknown keys are rejected). **Required scope:** `dashboards:write`. # Get a dashboard view Source: https://docs.upstackdata.com/api-reference/dashboards/get-a-dashboard-view /api-reference/openapi.yaml get /accounts/api/dashboard/views/{dashboardViewId} Fetch a single view with its full configuration. **Required scope:** `dashboards:read`. Returns 404 with `{ "message": "Dashboard view not found" }` if the view doesn't exist or belongs to a different pixel — the two paths return an identical body so cross-pixel existence isn't leaked. # List dashboard views Source: https://docs.upstackdata.com/api-reference/dashboards/list-dashboard-views /api-reference/openapi.yaml get /accounts/api/dashboard/views Return a summary list of dashboard views for the authenticated pixel. **Required scope:** `dashboards:read`. # Update a dashboard view Source: https://docs.upstackdata.com/api-reference/dashboards/update-a-dashboard-view /api-reference/openapi.yaml patch /accounts/api/dashboard/views/{dashboardViewId} Partial update — only fields supplied in the body are changed. Pass at least one of `name`, `configuration`, or `order`. Other fields are rejected by the schema. **Required scope:** `dashboards:write`. # Send server-side events Source: https://docs.upstackdata.com/api-reference/events/send-server-side-events /api-reference/openapi.yaml post /tr/api/events Send a batch of tracking events from your server. Each event is turned into Upstack's canonical event and processed exactly like a pixel event — identity resolution, enrichment, analytics, and real-time forwarding to your destinations. You always send an **array** of events (send one event as an array of one). Each event needs a `name`. An `eventId` is optional but **strongly recommended** — it makes the event idempotent (safe retries and de-duplication); everything else is optional. **Deduplication.** `eventId` is your idempotency key. If the same `eventId` is received again for a pixel within the dedup window, the duplicate is skipped during processing — so retries and webhook loops are safe. Use the same `eventId` you send from your browser Pixel for the same event so they de-duplicate across sources (e.g. Facebook). **Limits.** Up to **100 events** per request; request body up to **128 KB**. Within event data: strings up to **1024** chars, arrays up to **100** items, objects up to **50** keys (key names up to **64** chars), nested up to **4** levels deep. **Required scope:** `events:write`. # API Overview Source: https://docs.upstackdata.com/api-reference/overview Programmatic access to your Upstack Data pixel — authentication, base URLs, scopes, error format, and a curl quickstart. The Upstack Data API lets you query your event data, list the measures catalog, and manage dashboard views from anything that speaks HTTP. The same endpoints power the in-app dashboard and the [`upstack` CLI](/cli/install). If you're scripting against Upstack from a terminal, prefer the [`upstack` CLI](/cli/install) — it wraps these endpoints, handles auth, and adds ergonomics like measure-title resolution. ## Base URL All endpoints in this reference are relative to `https://api.upstackdata.com`, grouped by service path: * `/db-mgmt/api/*` — analytics queries and the measures catalog. * `/accounts/api/*` — dashboard view management. * `/tr/api/*` — server-side event ingestion. These surfaces share the same authentication. ## Authentication Every request carries two headers: | Header | Value | | ------------ | ------------------------------------------------------------------ | | `x-api-key` | Your Upstack API key. Starts with `upstack_`. | | `x-pixel-id` | The pixel id this request targets. One key is scoped to one pixel. | Mint an API key in the dashboard under **Settings → API Keys**. The raw key is shown once at creation — store it securely; we keep only a hash. ```bash theme={null} curl https://api.upstackdata.com/db-mgmt/api/measures \ -H "x-api-key: upstack_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "x-pixel-id: 5f1e6a4f-..." ``` ## Scopes API keys carry one or more scopes. The required scope per endpoint is listed on each endpoint's page. | Scope | Grants | | ------------------ | ------------------------------------------------------------------------------------------------------------------ | | `analytics:read` | `POST /api/query`, `POST /api/query-attribution`, `POST /api/query-cohort-analysis` | | `dashboards:read` | `GET /api/dashboard/views` (list and individual) | | `dashboards:write` | `POST` / `PATCH` / `DELETE` on `/api/dashboard/views`, plus `/copy` and `/from-preset`. Implies `dashboards:read`. | | `events:write` | `POST /tr/api/events` — send server-side tracking events. | The catalog endpoint (`GET /api/measures`) is ungated — any active key can read the measures list. This unblocks discovery use cases (e.g. an LLM looking up canonical measure ids before composing a query). Older keys minted before May 2026 may carry legacy scopes `db_query` or `attribution_query`. These are auto-expanded to `analytics:read` at request time, so existing keys keep working without rotation. Rotate at your convenience to switch to the modern names. ## Error format Errors are JSON responses with a `message` field and the appropriate status code. ```json theme={null} { "message": "API key does not have the dashboards:write scope" } ``` 400 responses on validated endpoints also include an `errors` array with per-field detail: ```json theme={null} { "message": "Bad Request", "errors": [ { "message": "name is required", "key": "name", "path": ["name"] } ] } ``` The server-side events API (`POST /tr/api/events`) returns a richer envelope: the same top-level `message`, plus a `requestId` and a structured `error` object with a machine-readable `code` and per-event `details`. See **Send server-side events** for the full shape. | Status | Meaning | | ------ | -------------------------------------------------------------------------------------------- | | `200` | Success. | | `400` | Validation error — see `errors` (or `error.details` on the events API). | | `401` | Missing/invalid `x-api-key` or `x-pixel-id`, revoked key, or expired key. | | `403` | Key is valid but doesn't carry the required scope. | | `404` | Resource not found (or belongs to another pixel — we return 404 rather than leak existence). | | `413` | Request body too large (server-side events API — 128 KB limit). | | `500` | Server error. Retry; if persistent, file a support ticket with the request id. | ## Quickstart Discover what measures are available, then build a dashboard from three of them. ```bash theme={null} curl https://api.upstackdata.com/db-mgmt/api/measures \ -H "x-api-key: $UPSTACK_API_KEY" \ -H "x-pixel-id: $UPSTACK_PIXEL_ID" ``` Find the keys you want (e.g. `core.new_customer_roas`, `core.new_customer_mer`, `meta.cpm`). ```bash theme={null} curl -X POST https://api.upstackdata.com/accounts/api/dashboard/views/from-preset \ -H "x-api-key: $UPSTACK_API_KEY" \ -H "x-pixel-id: $UPSTACK_PIXEL_ID" \ -H "Content-Type: application/json" \ -d '{ "name": "NC + Meta Pulse", "widgets": [ { "measure": "core.new_customer_roas", "title": "NC ROAS" }, { "measure": "core.new_customer_mer", "title": "NC MER" }, { "measure": "meta.cpm", "title": "Meta CPM" } ] }' ``` The response returns the full `DashboardView` with auto-laid-out sparkline widgets. Sign in to [app.upstackdata.com](https://app.upstackdata.com) and pick the new view from the view dropdown. For the same flow as a single CLI command, see [`upstack dashboard view build`](/cli/dashboard-view#build). # Add a COG line to a variant Source: https://docs.upstackdata.com/api-reference/products/add-a-cog-line-to-a-variant /api-reference/openapi.yaml post /accounts/api/products/{productId}/{variantId}/cogs Append a new COG line to a variant's `manualCostHistory`. The server assigns a ULID for the new line. Triggers a per-order COGS recalculation downstream. **Required scope:** `costs:write`. # Delete a COG line Source: https://docs.upstackdata.com/api-reference/products/delete-a-cog-line /api-reference/openapi.yaml delete /accounts/api/products/{productId}/{variantId}/cogs/{cogId} Remove a COG line from a variant's history. Triggers a per-order COGS recalculation downstream (the deleted line is passed through to the recalc trigger so affected-orders can be identified). **Required scope:** `costs:write`. # Get the resolved cost for a variant Source: https://docs.upstackdata.com/api-reference/products/get-the-resolved-cost-for-a-variant /api-reference/openapi.yaml get /accounts/api/products/{productId}/{variantId}/cost Returns the effective per-unit cost for a single variant, including which configuration tier supplied it (per-variant COG line, global override, or default fallback). **Required scope:** `costs:read`. # Search products Source: https://docs.upstackdata.com/api-reference/products/search-products /api-reference/openapi.yaml get /accounts/api/products/search Search products by title / SKU / variant. Cursor-paginated. **Required scope:** `costs:read`. # Set a variant's handling fee Source: https://docs.upstackdata.com/api-reference/products/set-a-variants-handling-fee /api-reference/openapi.yaml put /accounts/api/products/{productId}/{variantId}/handling-fee Set the per-variant handling fee. Triggers a per-order COGS recalculation downstream. **Required scope:** `costs:write`. # Update a COG line Source: https://docs.upstackdata.com/api-reference/products/update-a-cog-line /api-reference/openapi.yaml put /accounts/api/products/{productId}/{variantId}/cogs/{cogId} Update an existing COG line by its server-assigned ID. Only the supplied fields are updated; omitted fields stay as-is. Triggers a per-order COGS recalculation downstream. **Required scope:** `costs:write`. # Cancelling your subscription Source: https://docs.upstackdata.com/billing/cancelling-your-subscription How to cancel your Upstack Data subscription, what cancellation preserves, and how to cancel one store without affecting others. ## How do I cancel my subscription? It depends on how you're billed. To find out which billing method you have, refer to [How do I identify my billing method?](/billing/how-do-i-identify-my-billing-method). Once you've identified your billing method, see [How do I cancel my subscription?](/billing/how-do-i-cancel-my-subscription) for the cancellation steps. **Good to know** Canceling does **not** delete your Upstack Data account, pixel setup, or integrations. If you reinstall later, your account and settings are preserved. ## Does cancellation stop my next payment? Yes. Cancellation stops all future billing — once the app is uninstalled (Shopify billing) or the subscription is canceled (Stripe billing), no further charges are issued. Any charge already in motion for the current cycle will still complete. ## I have multiple stores. Can I cancel one without affecting the others? Yes. Each store has its own subscription, so canceling one store's plan does not touch your other stores. Uninstall Upstack Data or cancel your subscription from the specific store you want to cancel by following [How do I cancel my subscription?](/billing/how-do-i-cancel-my-subscription). *** ## Related Articles # How can I pause my subscription? Source: https://docs.upstackdata.com/billing/how-can-i-pause-my-subscription Upstack Data subscriptions cannot be paused, but you can stop billing temporarily or pause data collection without canceling. ## Can I pause my subscription for a week or a month? Upstack Data subscriptions cannot currently be paused. If you need to stop billing temporarily, the best option is to cancel by uninstalling the app (Shopify billing) or canceling inside the dashboard (Stripe billing), then reinstall when you're ready. Your configuration is preserved when you reconnect your Shopify store, so you don't have to redo the pixel or integrations. ## Can I pause data collection without canceling? Yes — this is different from pausing billing. If you want to temporarily stop sending events to destinations (for example, during a store freeze or campaign blackout), message us in chat and we can disable event forwarding for a set period while keeping your account active. *** ## Related Articles # How do I cancel my subscription? Source: https://docs.upstackdata.com/billing/how-do-i-cancel-my-subscription Step-by-step instructions to cancel your Upstack Data subscription, whether you're on Stripe direct billing or Shopify billing. ## Step 1: Identify your billing method Upstack Data uses two billing methods. The cancellation steps depend on which one you're on. Log in to your [Upstack Data dashboard](https://app.upstackdata.com/), then go to **Settings → Billing**. Upstack Data dashboard Settings, Billing page

Upstack Data dashboard Settings, Billing page

If you see a red **Cancel** button, you're on Stripe (direct) billing. Click **Cancel** and confirm when prompted. Once this is done, your subscription is canceled. Red Cancel button shown for Stripe direct billing

Red Cancel button shown for Stripe direct billing

If you only see plan options and no cancel link, you're on Shopify billing. Follow Step 2 below. Billing page showing only plan options, indicating Shopify billing

Billing page showing only plan options, indicating Shopify billing

*** ## Step 2: Cancel your subscription on Shopify billing If you're billed through Shopify, uninstalling the app cancels your subscription. Log in to your Shopify admin, then go to **Settings → Apps**. Shopify admin Settings, Apps page

Find **Upstack Data** in the list of installed apps. Upstack Data listed in Shopify installed apps

Click the three-dot menu next to the app name, click **Uninstall**, and confirm when prompted. Confirming uninstall of the Upstack Data app in Shopify

*** ## Related Articles # How do I identify my billing method? Source: https://docs.upstackdata.com/billing/how-do-i-identify-my-billing-method Determine whether your Upstack Data account is on Stripe direct billing or Shopify billing by checking your billing settings. Upstack Data uses two billing methods. The steps you follow for actions like canceling depend on which one you're on. Log in to your [Upstack Data dashboard](https://app.upstackdata.com/), then go to **Settings → Billing**. Upstack Data dashboard Settings, Billing page

If you see a red **Cancel** button, you're on Stripe (direct) billing. Red Cancel button shown for Stripe direct billing

If you only see plan options and no cancel link, you're on Shopify billing. Billing page showing only plan options, indicating Shopify billing

*** ## Related Articles # How do I update my payment method? Source: https://docs.upstackdata.com/billing/how-do-i-update-my-payment-method Update your card on Upstack Data, with steps for Stripe billing and Shopify billing, plus how to set a default payment method. The steps to update your payment method depend on how your account is billed. Follow the section that applies to you. ## If you're on Stripe billing Log in to your [Upstack Data account](https://app.upstackdata.com/), then go to **Settings → Billing**. Upstack Data dashboard Settings, Billing page

Click **Payment Methods**. Payment Methods section of the Upstack Data billing page

Click **Add Payment Method** and enter your new card details. Add Payment Method form for entering new card details

To use the new payment method as default, click the three dots next to the payment method you want as default, then select **Set as default**. Setting a payment method as default from the three-dot menu

Setting a payment method as default from the three-dot menu

## If you're on Shopify billing Shopify manages payment methods for apps billed through the Shopify App Store. To update your card: 1. Log in to your **Shopify admin**. 2. Go to **Settings → Billing**. 3. Update your payment method there. This change applies to all Shopify app charges, not just Upstack Data. **Not sure which billing type you're on?** Log in to your Upstack Data dashboard and go to the **Billing** page. If you see your card details and invoices listed directly, you're on Stripe billing. If the billing page does not display a payment method, your charges are handled through Shopify. If you run into any issues updating your payment method, start a chat from your dashboard and we can assist you further. *** ## Related Articles # How do I view my past invoices? Source: https://docs.upstackdata.com/billing/how-do-i-view-my-past-invoices View and download past Upstack Data invoices, with steps for Stripe billing and for charges handled through Shopify. ## If you're on Stripe billing (most accounts) Log in to your [Upstack Data account](https://app.upstackdata.com/), then go to **Settings → Billing**. Upstack Data dashboard Settings, Billing page

Click the **Billing History** tab to see all of your previous invoices. Billing History tab listing previous invoices

Click any invoice to view its details or download it as a PDF. You also receive a PDF copy of each invoice by email every billing cycle. ## If you're on Shopify billing Shopify handles invoicing for apps billed through the Shopify App Store. To view your charges: 1. Log in to your [Shopify admin](https://admin.shopify.com). 2. Go to **Settings → Billing**. 3. Select a billing cycle to see itemized app charges, including Upstack Data. **Not sure which billing type you're on?** Refer to [How do I identify my billing method?](/billing/how-do-i-identify-my-billing-method) to find out which billing method you're on. *** ## Related Articles # Payments, invoices, and billing source Source: https://docs.upstackdata.com/billing/payments-invoices-and-billing-source Manage payment methods, retry failed charges, find past invoices, and determine whether you're billed through Shopify or Stripe. ## Am I billed through Shopify or directly by Upstack Data? Both models exist today. To determine which billing method you're on, refer to [How do I identify my billing method?](/billing/how-do-i-identify-my-billing-method). We're actively migrating all customers to direct credit card billing via Stripe, which gives us better control over plan management and seasonal upgrades. If you're still on Shopify billing and want to switch, contact us at [support@upstackdata.com](mailto:support@upstackdata.com). ## My payment failed. Can you retry it? Yes — message us in chat and we'll manually retry the charge against your stored payment method. If the retry still fails, update your card under **Settings → Billing → Payment method** and we'll run it again. You can also refer to [How do I update my payment method?](/billing/how-do-i-update-my-payment-method) for the steps. ## Where do I view past invoices or charges by month? Refer to [How do I view my past invoices?](/billing/how-do-i-view-my-past-invoices) to view past invoices or charges by month. ## The app says "subscription required" but I already have an active subscription. What's happening? This usually means your account is caught between the old Shopify subscription and the new direct Stripe subscription. Log out of Upstack Data, log back in, and follow the prompts to complete Stripe billing setup. If that doesn't clear the message, contact us at [support@upstackdata.com](mailto:support@upstackdata.com) with your store URL. *** ## Related Articles # Plans and pricing Source: https://docs.upstackdata.com/billing/plans-and-pricing Learn about Upstack Data's available plans and pricing, and what happens to billing when you uninstall during a free trial. ## What plans does Upstack Data offer? For more details on our pricing plans, refer to the pricing section on our website: [upstackdata.com/pricing](https://www.upstackdata.com/pricing). *** ## I uninstalled during the free trial — why do I still see a charge on my upcoming Shopify bill? Uninstalling the app cancels the subscription going forward, but Shopify may still list a pending charge on the next bill if the uninstall happened after the billing cycle started. Contact us with your store URL and the charge amount, and we'll confirm whether it's a real charge or a pending line item that won't collect. *** ## Related Articles # Subscriptions and billing Source: https://docs.upstackdata.com/billing/subscriptions-and-billing Find answers about Upstack Data plans, billing, payments, cancellations, pauses, refunds, trials, and multi-store subscriptions. ## Overview This article answers the questions customers most often ask about Upstack Data plans, billing, payments, cancellations, pauses, refunds, trials, and multi-store subscriptions. Use the sections below to jump to the topic you need. All plan and billing controls live inside your Upstack Data dashboard under the **Billing** page. If you were set up through the Shopify App Store, some actions (like canceling) still happen inside your Shopify admin — see the relevant section below. *** ## Plans and pricing Looking for information on Upstack Data's available plans, pricing tiers, or what happens to billing when you uninstall during a free trial? The plans are listed in full on the Upstack Data pricing page, and common questions about trial charges and Shopify billing are answered separately. For more details, see [Plans and pricing](/billing/plans-and-pricing). *** ## Payments, invoices, and billing source Need help with payment methods, retrying failed charges, finding past invoices, or sorting out whether you're billed through Shopify or Stripe? See [Payments, invoices, and billing source](/billing/payments-invoices-and-billing-source) for more details. *** ## Can I upgrade or downgrade my subscription? You can upgrade or downgrade your plan at any time based on your current order volume, and choose the plan that best suits your use case. For more details, review [Upgrading and downgrading](/billing/upgrading-and-downgrading). *** ## How can I cancel my subscription? If you want to cancel your subscription because of a technical problem, onboarding experience, pricing, or another issue, give us the opportunity to address it by contacting us at [support@upstackdata.com](mailto:support@upstackdata.com). To cancel your subscription without contacting Upstack, refer to [Cancelling your subscription](/billing/cancelling-your-subscription). *** ## How can I pause my subscription? Pausing a subscription is not possible. However, there are alternative methods if you need to stop using Upstack without losing your data and pixels. Review [How can I pause my subscription?](/billing/how-can-i-pause-my-subscription) for the additional steps you can take. *** ## Refunds For inquiries regarding refunds, refer to our [Refund Policy](https://www.upstackdata.com/refund-policy). *** ## Multi-store billing ### Is each store billed separately? Yes. Each Shopify store has its own Upstack Data subscription, and each is billed independently. This also means each store's plan can be sized differently. ### Can I move my subscription from one store to a different store? We can't transfer a Shopify subscription between stores — Shopify ties each subscription to the store that approved it. The workflow is: [cancel on the old store](/billing/how-do-i-cancel-my-subscription), install Upstack Data on the new store using the [complete how-to guide for setting up the Upstack Data app in Shopify](/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify), and start a subscription there. Message us and we'll coordinate so you don't double-pay during the transition. *** ## Still have a question? **Need help?** If your question isn't answered here, start a chat from the Upstack Data dashboard and include your store URL. We'll look up your subscription and get back to you quickly. # Upgrading and downgrading Source: https://docs.upstackdata.com/billing/upgrading-and-downgrading Change your Upstack Data plan: how to upgrade, how to downgrade, and how to right-size during the Shopify to Stripe migration. ## How do I upgrade my plan? Log in to your [Upstack Data account](https://app.upstackdata.com/), then go to **Settings → Billing → Overview → Change Plan**. Pick the plan you want and click **Upgrade**. ## How do I downgrade to a lower plan? Log in to your [Upstack Data account](https://app.upstackdata.com/), then go to **Settings → Billing → Overview → Change Plan** and click **Downgrade** on the plan you want to move to. Downgrades take effect on the next billing cycle, so you keep access to your current plan's features until then. ## Can I change my plan during the Shopify to Stripe migration? Yes, and this is a good time to right-size. When you log in after uninstalling the Shopify app, you're asked to pick a plan before entering your card details. Pick the tier that matches your current order volume. *** ## Related Articles # upstack account Source: https://docs.upstackdata.com/cli/account Read and rename the Upstack account that owns the configured API key — wraps the public /api/account endpoints. Manage your Upstack account from the command line. Wraps the `/api/account` endpoints — see the [API reference](/api-reference/overview) and the **Account** group for full request/response shapes. ## Subcommands | Subcommand | Wraps | | --------------------------------------------- | --------------------------------- | | [`show`](#show) | `GET /api/account` | | [`rename`](#rename) | `PATCH /api/account` | | [`settings order show`](#settings-order-show) | `GET /api/account/settings/order` | | [`settings order set`](#settings-order-set) | `PUT /api/account/settings/order` | ## show Print the configured account as JSON — display name, creation date, active owners and admins, and the current subscription summary (when present). ```bash theme={null} upstack account show ``` Sample output: ```json theme={null} { "accountName": "Upstack Data", "createdAt": "2025-08-12T18:22:11.034Z", "owners": [ { "email": "founder@upstackdata.com", "firstName": "Alex", "lastName": "Owner" } ], "admins": [ { "email": "ops@upstackdata.com", "firstName": "Sam", "lastName": "Admin" } ], "subscription": { "plan": { "name": "Growth", "billingFrequency": "monthly", "displayPrice": "$49/mo", "discountedDisplayPrice": "$39/mo", "currency": "USD", "discount": { "code": "LAUNCH20", "type": "percentage", "value": 20, "appliesForBillingIntervals": 6 } }, "status": "active", "currentPeriodEnd": "2026-06-12T00:00:00.000Z", "cancelAtPeriodEnd": false } } ``` **Required scope:** `account:read`. ### Rendering price after a discount Render `discountedDisplayPrice ?? displayPrice` to match the web app's billing page. v2 (Stripe-native) plans may omit `discountedDisplayPrice` even when a discount is present — fall back to `displayPrice` and surface the `discount` summary for context. ## rename Rename the configured account. Prints the current → new transition and prompts for confirmation; pass `--yes` (or `-y`) to skip. ```bash theme={null} upstack account rename --name "Upstack Data" upstack account rename --name "Upstack Data" --yes ``` **Required flags:** | Flag | Description | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--name ` | New account name. 1–100 chars after trim. Control / zero-width / bidi characters rejected; unicode letters, marks, digits, punctuation, and emoji accepted. | **Optional flags:** | Flag | Description | | ----------- | ----------------------------- | | `-y, --yes` | Skip the confirmation prompt. | **Required scope:** `account:write`. The endpoint is allowlist-only — `accountName` is the single field accepted; any other key in the body is rejected with 400. Renames emit an `accountUpdated` EventBridge event with `actor: cli:{apiKeyPk}` so downstream consumers can distinguish UI vs API-key mutations. ## settings order show Print the account's order settings as JSON — count flags for pending and voided orders, refund-date attribution, and the list of exclusion filters that drop matching orders from every analytics query. ```bash theme={null} upstack account settings order show ``` Sample output: ```json theme={null} { "countPendingOrders": false, "countVoidedOrders": false, "refundDateAttribution": "refund_date", "exclusionFilters": [ { "id": "9f3e1a4f-d2c1-4f1e-9b5a-3c6d7e8f0a1b", "name": "Exclude POS", "enabled": true, "conditionGroups": [ { "id": "...", "logic": "and", "conditions": [ { "id": "...", "field": "sourceName", "operator": "not_equals", "value": "pos" } ] } ], "createdAt": "2026-05-18T10:00:00.000Z", "updatedAt": "2026-05-18T10:00:00.000Z" } ] } ``` **Required scope:** `account:read`. When the account has no stored `orderSettings`, the response is filled with the same defaults the web app uses (`countPendingOrders=false`, `countVoidedOrders=false`, `refundDateAttribution=refund_date`, `exclusionFilters=[]`). ## settings order set **PUT-the-whole-config semantics.** The file you pass replaces the stored `orderSettings` in its entirety — any existing filter not present in the file is deleted. The server assigns `id`, `createdAt`, and `updatedAt` on new filters (and on nested groups + conditions); entries that already carry an `id` preserve their `createdAt` and get a bumped `updatedAt`. ```bash theme={null} upstack account settings order show > order.json $EDITOR order.json upstack account settings order set --from-file order.json upstack account settings order set --from-file order.json --yes ``` The CLI prints a summary (counting flags, refund attribution, filter count) and asks for confirmation; `--yes` skips the prompt. **Required flags:** | Flag | Description | | -------------------- | --------------------------------------------- | | `--from-file ` | JSON file with the full `OrderSettings` body. | **Optional flags:** | Flag | Description | | ----------- | ----------------------------- | | `-y, --yes` | Skip the confirmation prompt. | Example body — "drop POS orders" filter, every `id` optional: ```json theme={null} { "countPendingOrders": false, "countVoidedOrders": false, "refundDateAttribution": "refund_date", "exclusionFilters": [ { "name": "Exclude POS", "enabled": true, "conditionGroups": [ { "logic": "and", "conditions": [ { "field": "sourceName", "operator": "not_equals", "value": "pos" } ] } ] } ] } ``` **Required scope:** `account:write`. Strict allowlist at every nesting level — extra keys in the body, or in a filter, group, or condition are rejected with 400. Operators must be valid for the chosen field type per `ORDER_EXCLUSION_FIELD_CATALOG` (e.g. `greater_than` on `sourceName` → 400). Updates emit an `accountUpdated` EventBridge event with `actor: cli:{apiKeyPk}` and `change: { kind: "orderSettings" }`. # AI agent workflow Source: https://docs.upstackdata.com/cli/ai-agent-workflow Use Claude (or another agent) in your terminal to translate natural-language intent into structured upstack CLI calls. The CLI is intentionally dumb — Claude (or another agent) running in your terminal does the natural-language parsing and constructs structured `upstack` calls. No LLM ever runs server-side in Upstack. ## Example session ```text theme={null} > Claude, make me a dashboard with NC ROAS, MER, and Facebook CPM. $ upstack measures --search "new customer roas" # confirms core.new_customer_roas $ upstack measures --search mer # core.new_customer_mer $ upstack measures --search "facebook cpm" # meta.cpm $ upstack dashboard view build \ --name "NC + Meta Pulse" \ --measures core.new_customer_roas,core.new_customer_mer,meta.cpm # → Created dashboard view 5f1e6a4f-... "NC + Meta Pulse" with 3 widget(s). # Open the dashboard app and select it from the view dropdown. ``` The agent picks measure ids using [`upstack measures`](/cli/measures), then issues a single [`build`](/cli/dashboard-view#build) call. Same result as the [API quickstart](/api-reference/overview), in one structured command. ## Filters: discover before you construct When the user asks for a scoped query — "MER for new customers only", "spend on Meta campaigns containing 'spring'", etc. — the agent should call [`upstack filters`](/cli/filters) first to enumerate valid filter fields, operators, and contexts before guessing field ids: ```text theme={null} > Claude, show me MER for new customers only, last 30 days. $ upstack filters --search customer --detail # → orders.customer_type, operators include `equals`/`in` $ upstack query \ --measures core.new_customer_mer \ --granularity day \ --date-start 2026-04-01 --date-end 2026-04-30 \ --filter '{"and":[{"field":"orders.customer_type","op":"equals","value":"new_customer"}]}' ``` The field id (`orders.customer_type`), its supported operators, and the set of applicable contexts all come from the discovery endpoint — no hard-coding. ## Why this works * **Discovery is free.** [`upstack measures`](/cli/measures) and [`upstack filters`](/cli/filters) require only `analytics:read`. An agent can introspect what's available before constructing a request. * **The CLI is structured input for the agent's structured output.** Flags are JSON-shaped (`--measures m1,m2,m3`, `--from-file payload.json`). No shell-quoting gymnastics for natural-language prompts. * **Every command can be replayed.** Pass `--from-file` to load a JSON body, then iterate via flags. The agent doesn't need to remember state — it can re-issue. ## What the agent should NOT do * Don't ask the user for their API key over chat. Credentials are already in `~/.upstackrc`; the CLI handles auth automatically. * Don't hand-construct API request bodies in chat. Use the CLI as the structured interface — it's already typed and validated. # Configuration defaults Source: https://docs.upstackdata.com/cli/config-defaults Set per-profile defaults so you don't repeat common flags on every query. Set per-profile defaults so you don't repeat common flags. Defaults are merged into every query: **file values \< defaults \< CLI flags**. ## Usage ```bash theme={null} upstack config set upstack config get [key] upstack config unset ``` ## Supported keys | Key | Description | Example | | ------------- | ------------------------------------------------ | ------------------------- | | `timezone` | IANA timezone applied to query date ranges. | `America/New_York` | | `output` | Default output format. | `json`, `table`, or `csv` | | `granularity` | Default granularity for query / cohort commands. | `day` | ## Examples ```bash theme={null} upstack config set timezone America/New_York upstack config set output table upstack config get # print all defaults for the active profile upstack config get granularity # print one key upstack config unset granularity ``` Defaults are stored under the active profile in `~/.upstackrc`: ```json theme={null} { "profiles": { "default": { "baseUrl": "...", "apiKey": "upstack_...", "pixelId": "...", "defaults": { "timezone": "America/New_York", "output": "table" } } } } ``` # upstack costs Source: https://docs.upstackdata.com/cli/costs Read and update cost configuration from the CLI — global overrides, shipping method, and per-type cost lines (order / gateway / shipping / variable / fixed). Manage cost configuration that drives every margin calculation in the dashboard. Wraps the `/api/costs*` endpoints — see the [API reference](/api-reference/overview) under the **Costs** group for full request / response shapes. Mutations trigger the same per-order COGS recalculation flow as the web UI — so CLI-driven changes update existing orders identically. ## Subcommands | Subcommand | Wraps | | --------------------------------------------- | ---------------------------------------- | | [`show`](#show) | `GET /api/costs` | | [`global-override set`](#global-override-set) | `PUT /api/costs/global-product-override` | | [`shipping set`](#shipping-set) | `PUT /api/costs/shipping-settings` | | [`lines add`](#lines-add) | `POST /api/costs/lines` | | [`lines update`](#lines-update) | `PUT /api/costs/lines/{lineId}` | | [`lines delete`](#lines-delete) | `DELETE /api/costs/lines/{lineId}` | ## show Print the full cost configuration as JSON, or filter to a single type. ```bash theme={null} upstack costs show upstack costs show --type shipping ``` `--type` values: `global_product_override`, `order`, `gateway`, `shipping`, `variable`, `fixed`. **Required scope:** `costs:read`. ## global-override set Update the default COGS / handling fee applied to product variants that have no per-variant COG line. At least one of `--default-cogs`, `--handling-fee`, or `--currency` is required. ```bash theme={null} upstack costs global-override set --default-cogs 5 --handling-fee 1.5 --currency USD upstack costs global-override set --default-cogs 0 --yes ``` The CLI prints a confirmation summary; `--yes` (or `-y`) skips it. **Required scope:** `costs:write`. ## shipping set Switch the shipping cost attribution method. ```bash theme={null} upstack costs shipping set --method fixed_rate --fixed-rate 7.5 --currency USD upstack costs shipping set --method shopify_charges --yes ``` `--method` values: `shopify_charges`, `fixed_rate`, `shipping_profiles`. `--fixed-rate` is required when `--method=fixed_rate`. **Required scope:** `costs:write`. ## lines add Add a cost line for one of the five line-typed cost surfaces — `order`, `gateway`, `shipping` (profile rule), `variable`, or `fixed`. The line body shape depends on `--type`; supply it as a JSON file via `--from-file`. The server assigns a ULID for the new line. ```bash theme={null} upstack costs lines add --type variable --from-file marketing.json upstack costs lines add --type gateway --from-file shopify-payments.json upstack costs lines add --type fixed --from-file klaviyo-subscription.json ``` Example `marketing.json` for a `variable` line ("% of ad spend"): ```json theme={null} { "name": "Google Ads — % of spend", "type": "pct_ad_spend", "percentRate": 2, "category": "marketing", "channel": "online", "currency": "USD" } ``` Example `shopify-payments.json` for a `gateway` line: ```json theme={null} { "name": "Shopify Payments", "gatewayName": "shopify_payments", "flatAmount": 0.30, "percentRate": 2.9, "currency": "USD" } ``` Example `klaviyo-subscription.json` for a `fixed` line: ```json theme={null} { "name": "Klaviyo subscription", "flatAmount": 500, "frequencyUnit": "month", "frequencyInterval": 1, "category": "opex", "currency": "USD" } ``` See the [API reference](/api-reference/overview) under **Costs** for the full field set of each cost type (`OrderCostLine`, `GatewayCostLine`, `ShippingProfileCostLine`, `VariableCostLine`, `FixedCostLine`). **Required scope:** `costs:write`. ## lines update Update an existing cost line by its server-assigned ULID. The JSON file contains a partial update — any subset of the fields valid for that cost type. Omitted fields stay as-is. ```bash theme={null} # patch.json: { "percentRate": 2.5 } upstack costs lines update --type variable --line-id 01JZX... --from-file patch.json ``` **Required scope:** `costs:write`. ## lines delete Delete a cost line by its ULID. The CLI prompts for confirmation; `--yes` (or `-y`) skips it. ```bash theme={null} upstack costs lines delete --type variable --line-id 01JZX... upstack costs lines delete --type variable --line-id 01JZX... --yes ``` **Required scope:** `costs:write`. # upstack dashboard view Source: https://docs.upstackdata.com/cli/dashboard-view Manage Upstack dashboard views from the command line — list, show, create, update, copy, delete, organize widgets into sections, pin KPIs, and the high-level preset builder. Manage Upstack dashboard views from the command line. Wraps the `/api/dashboard/views/*` endpoints — see the [API reference](/api-reference/overview) and the per-endpoint pages under the **Dashboards** group for full request/response shapes. ## Subcommands | Subcommand | Wraps | | -------------------------------- | ---------------------------------------------------------------------------- | | [`list`](#list) | `GET /api/dashboard/views` | | [`show `](#show) | `GET /api/dashboard/views/{id}` | | [`build`](#build) | `POST /api/dashboard/views/from-preset` | | [`create --from-file`](#create) | `POST /api/dashboard/views` | | [`update `](#update) | `PATCH /api/dashboard/views/{id}` | | [`copy `](#copy) | `POST /api/dashboard/views/{id}/copy` | | [`delete `](#delete) | `DELETE /api/dashboard/views/{id}` | | [`section …`](#sections) | `GET` + `PATCH /api/dashboard/views/{id}` (mutates `configuration.sections`) | | [`pin `](#pins) | `PATCH /api/dashboard/views/{id}` (adds widget to Pinned section) | | [`unpin `](#pins) | `PATCH /api/dashboard/views/{id}` (removes from Pinned section) | ## list List dashboard views for the configured pixel. ```bash theme={null} upstack dashboard view list upstack dashboard view list --type view # default upstack dashboard view list --type attribution_view ``` ## show Fetch a single view with its full configuration as JSON. ```bash theme={null} upstack dashboard view show 5f1e6a4f-... ``` ## build The high-level builder — pass a list of measures, get a finished dashboard with auto-laid-out sparkline tiles. The most common command for AI agents and quick "give me a dashboard with these KPIs" workflows. ```bash theme={null} upstack dashboard view build \ --name "NC + Meta Pulse" \ --measures core.new_customer_roas,core.new_customer_mer,meta.cpm ``` Optional flags: | Flag | Description | Default | | --------------------------------------------------- | ---------------------------------------------------- | ------------------- | | `--chart-types ` | One chart type per measure (positional pairing). | `sparkline` for all | | `--type ` | `view`, `attribution_view`, or `pnl_view`. | `view` | | `--layout ` | Auto-layout strategy. Only `kpi-grid` today. | `kpi-grid` | | `--attribution-model ` | `first_click`, `last_click`, or `any_click`. | `first_click` | | `--attribution-window ` | Attribution lookback. | `30` | | `--granularity ` | `day\|hour\|week\|month\|...` | `day` | | `--date-start --date-end ` | Date range. | last 30 days | | `--from-file ` | JSON file with any of the above. CLI flags override. | | The CLI resolves each measure's friendly `shortTitle` from `GET /api/measures` (cached) before posting, so widget titles read nicely in the web app. ## create Advanced — create a view from a full `DashboardViewConfiguration` body. Use [`build`](#build) instead unless you have a specific configuration to load (e.g. exported from another pixel). ```bash theme={null} upstack dashboard view create --from-file ./my-view.json ``` The file must contain `{ type, name, configuration, order? }`. ## update Partial update — only fields you pass are changed. ```bash theme={null} upstack dashboard view update 5f1e6a4f-... --name "Renamed" upstack dashboard view update 5f1e6a4f-... --order 3 upstack dashboard view update 5f1e6a4f-... --from-file ./partial.json ``` ## copy Duplicate a view. ```bash theme={null} upstack dashboard view copy 5f1e6a4f-... ``` ## delete Delete a view. Prompts for confirmation; `--yes` skips the prompt. ```bash theme={null} upstack dashboard view delete 5f1e6a4f-... --yes ``` ## Sections A view's widgets are grouped into **sections** — labelled blocks the web app renders with a header, optional collapse/hide, per-section density/pacing overrides, and a chosen layout mode. The CLI exposes every section operation the web app supports. Every `section` subcommand follows a `GET → mutate → PATCH` flow internally: it fetches the view's current configuration, applies the mutation locally, then sends the full new configuration back via `PATCH /api/dashboard/views/{id}`. You don't need to construct the JSON yourself. ### section list Print the sections in a view as a table (id, ordinal, layout mode, widget count, title, flags like `pinned` / `hidden` / `collapsed`). ```bash theme={null} upstack dashboard view section list 5f1e6a4f-... ``` ### section add Create a new section. By default, appends to the bottom of the non-pinned sections. ```bash theme={null} upstack dashboard view section add 5f1e6a4f-... --title "Performance" upstack dashboard view section add 5f1e6a4f-... --title "Top KPIs" --position top upstack dashboard view section add 5f1e6a4f-... --title "Detail" --after ``` | Flag | Description | Default | | ------------------------ | --------------------------------------------------------------- | ------------- | | `--title ` | Section title. | `New Section` | | `--position top\|bottom` | Where to insert among non-pinned sections. | `bottom` | | `--after <sectionId>` | Insert immediately after this section (overrides `--position`). | | ### section rename / clone / delete ```bash theme={null} upstack dashboard view section rename 5f1e6a4f-... <section-id> --title "Renamed" upstack dashboard view section clone 5f1e6a4f-... <section-id> upstack dashboard view section delete 5f1e6a4f-... <section-id> ``` `clone` deep-copies the section's widgets with fresh ids and appends the new section directly after the source. `delete` migrates any widgets from the deleted section into the first remaining non-pinned section so widgets aren't lost. The Pinned section can't be renamed, cloned, or deleted directly — it's managed via [`pin`/`unpin`](#pins). ### section reorder Move a non-pinned section to a 0-based position among the other non-pinned sections. ```bash theme={null} upstack dashboard view section reorder 5f1e6a4f-... <section-id> --to 0 ``` ### section collapse / expand / hide / unhide Toggle the display state of a section. ```bash theme={null} upstack dashboard view section collapse 5f1e6a4f-... <section-id> upstack dashboard view section expand 5f1e6a4f-... <section-id> upstack dashboard view section hide 5f1e6a4f-... <section-id> upstack dashboard view section unhide 5f1e6a4f-... <section-id> ``` `collapse` keeps the header but hides the section's widgets. `hide` removes the entire section from rendering (config is preserved). ### section layout Set the section's layout mode. Accepted values: `auto`, `1_column`, `2_columns`, `3_columns`, `4_columns` (matches the backend enum exactly; the CLI lowercases input so capitalization in your shell is fine). ```bash theme={null} upstack dashboard view section layout 5f1e6a4f-... <section-id> --mode auto upstack dashboard view section layout 5f1e6a4f-... <section-id> --mode 2_columns ``` ### section density / pacing Per-section overrides for density (`compact` or `normal`) and pacing. Pass `inherit` (density) or `--inherit` (pacing) to clear the override and fall back to view-level `defaultSettings`. ```bash theme={null} upstack dashboard view section density 5f1e6a4f-... <section-id> --density compact upstack dashboard view section density 5f1e6a4f-... <section-id> --density inherit upstack dashboard view section pacing 5f1e6a4f-... <section-id> --enabled upstack dashboard view section pacing 5f1e6a4f-... <section-id> --disabled upstack dashboard view section pacing 5f1e6a4f-... <section-id> --inherit ``` ### section move-widget Move a widget from its current section into another non-pinned section. Use [`pin`/`unpin`](#pins) instead to move widgets in and out of the Pinned section. ```bash theme={null} upstack dashboard view section move-widget 5f1e6a4f-... <widget-id> --to <target-section-id> ``` ### section migrate Legacy views created before sections were introduced have a flat `configuration.widgets` array and no `configuration.sections`. Run `migrate` to wrap those widgets in a single `Main` section so the CLI's other section commands can operate on them. ```bash theme={null} upstack dashboard view section migrate 5f1e6a4f-... ``` Safe to call on views that already have sections (no-op). ## Pins Pinning copies a widget into a dedicated **Pinned** section that always renders first in the view (it has `ordinal: -1` and `sectionType: "PINNED"`). The Pinned section is created on the first `pin` and removed when its last widget is unpinned — you never create or delete it yourself. ```bash theme={null} # Pin: creates a fresh copy in the Pinned section with a new widget id. # The copy carries `sourceWidgetId` linking it back to the original. upstack dashboard view pin 5f1e6a4f-... <widget-id> # Unpin: accepts either the pinned copy's id, or the original widget's id. # The Pinned section is removed once its last widget is unpinned. upstack dashboard view unpin 5f1e6a4f-... <widget-id> ``` Pinning the same widget twice is rejected — call `unpin` first if you want to re-pin a modified original. # upstack dimensions Source: https://docs.upstackdata.com/cli/dimensions List the dimensions available for grouping and filtering queries. Bundled with the CLI — no network call. List the dimensions available for grouping and filtering queries. Bundled with the CLI as static data — no network call. ## Usage ```bash theme={null} upstack dimensions ``` ## Flags | Flag | Description | | ------------------- | --------------------------------------------------------------------------------------------------- | | `--search <term>` | Filter by keyword (matches the dimension key). | | `--category <name>` | Filter by category (e.g. `device`, `page`, `geo`, `traffic`, `ads`, `ecommerce`, `emq`, `session`). | | `--categories` | Print category names + counts only. | ## Examples ```bash theme={null} upstack dimensions --search utm upstack dimensions --category traffic upstack dimensions --categories ``` See [Measures & Dimensions](/data-dictionary/measures-and-dimensions) for full descriptions and example values. # upstack filters Source: https://docs.upstackdata.com/cli/filters List the filter-fields catalog from the command line. Find canonical filter field ids, value types, operators, and applicable contexts before constructing a --filter. List the catalog of filter fields available across every query endpoint. Each entry declares its operators, value type, and the contexts it applies in. Useful for finding canonical filter field ids before constructing a [query](/cli/query), [attribution query](/cli/query-attribution), [cohort analysis](/cli/query-cohort), or [channel-details listing](/cli/query-channel-details). Wraps `GET /api/filters` — see the [API reference](/api-reference/overview). ## Usage ```bash theme={null} upstack filters ``` The endpoint takes no parameters — the full catalog is returned in one call. Results are cached locally for 1 hour; pass `--no-cache` to refetch. ## Flags | Flag | Description | | ----------------- | ------------------------------------------------------------------------------------- | | `--search <term>` | Filter results by keyword (matches `field` and `label`). | | `--detail` | Include label, description, value type, supported operators, and applicable contexts. | | `--operators` | Show supported operators inline next to each field. | | `--json` | Print the raw response as JSON (one object per field). | | `--no-cache` | Bypass the local 1-hour cache and refetch. | ## Examples ```bash theme={null} upstack filters upstack filters --search utm upstack filters --detail upstack filters --operators upstack filters --json | jq '.[] | select(.applicableContexts | index("attribution"))' ``` ## Narrowing by endpoint context Every entry carries an `applicableContexts` array listing which endpoints it applies to (`query_measures`, `cohort_analysis`, `products_report`, `attribution`, `channel_details`, `emq_analytics`). Use `--detail` to see them inline, or `--json` to narrow with `jq`: ```bash theme={null} # Fields valid on POST /api/query-channel-details upstack filters --json | jq '.[] | select(.applicableContexts | index("channel_details"))' ``` # upstack history Source: https://docs.upstackdata.com/cli/history Inspect or re-run previously executed queries. Every query run is logged locally. Every query run is logged locally to `~/.upstack_history/`. The CLI doesn't send history anywhere — it's purely a convenience for you. ## Usage ```bash theme={null} upstack history # last 20 entries upstack history --show <id> # inspect a single entry upstack history --rerun <id> # re-run a previous query upstack history --clear # delete all entries ``` ## Flags | Flag | Description | | -------------- | ----------------------------------------------------------------------------------------------------- | | `--show <id>` | Print the full parameters and result for one history entry. | | `--rerun <id>` | Re-run a previous query with the same parameters. Useful for "what did yesterday look like, exactly?" | | `--clear` | Delete all history entries. No confirmation. | | `--limit <n>` | Number of recent entries to list. Default `20`. | # Install the Upstack CLI Source: https://docs.upstackdata.com/cli/install Install the upstack CLI and configure it with an API key and pixel id. The `upstack` CLI is a thin wrapper around the [Upstack API](/api-reference/overview). It handles authentication, profile management, and a few ergonomics like measure-title resolution that the raw API leaves to the caller. The CLI is designed to be both a human tool and a target for AI agents. See [AI agent workflow](/cli/ai-agent-workflow) for the intended Claude-in-your-terminal use case. ## Install ```bash theme={null} npm install -g @upstackdata/upstack-cli ``` ## Configure ```bash theme={null} upstack init ``` You'll be prompted for: * **API Key** — your Upstack key (starts with `upstack_`). Mint at **Settings → API Keys** in the dashboard. * **Pixel ID** — the pixel uuid the key is scoped to. Credentials live in `~/.upstackrc` with file mode `0600`. ## Verify ```bash theme={null} upstack whoami ``` Prints the active profile, pixel id, and masked API key. If you see your pixel id, you're set — try [`upstack measures`](/cli/measures) next. ## Multiple profiles For additional environments or pixels: ```bash theme={null} upstack init --profile staging upstack init --profile client-b ``` Then pass `--profile <name>` on any command. See [Profiles](/cli/profiles) for the full reference. # upstack measures Source: https://docs.upstackdata.com/cli/measures List the measures catalog from the command line. Find canonical measure ids before building a query or dashboard. List the measures available to your pixel. Useful for finding canonical measure ids before constructing a [query](/cli/query) or [building a dashboard](/cli/dashboard-view#build). Wraps `GET /api/measures` — see the [API reference](/api-reference/overview). ## Usage ```bash theme={null} upstack measures ``` Results are cached locally for 1 hour. Pass `--no-cache` to refetch. ## Flags | Flag | Description | | ------------------- | ------------------------------------------------------------------------------- | | `--search <term>` | Filter by keyword (matches `key`, `title`, and `shortTitle`). | | `--category <name>` | Filter by category (e.g. `Core`). | | `--categories` | Print category names + counts only (no individual measures). | | `--detail` | Include title, description, formula, category, and value type for each measure. | | `--no-cache` | Bypass the local 1-hour cache and refetch. | ## Examples ```bash theme={null} upstack measures --search "new customer roas" upstack measures --category Core upstack measures --categories upstack measures --detail --search mer ``` # upstack products Source: https://docs.upstackdata.com/cli/products Browse products and manage per-variant costs — handling fee + COGS history — from the CLI. Browse products + variants in the configured catalog and manage per-variant cost data. Wraps the `/api/products*` endpoints — see the [API reference](/api-reference/overview) under the **Products** group for full request / response shapes. Mutations fire the same per-order COGS recalculation as the web UI. ## Subcommands | Subcommand | Wraps | | --------------------------------------- | ----------------------------------------------------------- | | [`search`](#search) | `GET /api/products/search` | | [`cost`](#cost) | `GET /api/products/{productId}/{variantId}/cost` | | [`handling-fee set`](#handling-fee-set) | `PUT /api/products/{productId}/{variantId}/handling-fee` | | [`cogs add`](#cogs-add) | `POST /api/products/{productId}/{variantId}/cogs` | | [`cogs update`](#cogs-update) | `PUT /api/products/{productId}/{variantId}/cogs/{cogId}` | | [`cogs delete`](#cogs-delete) | `DELETE /api/products/{productId}/{variantId}/cogs/{cogId}` | ## search Search products by title / SKU / variant. Cursor-paginated. ```bash theme={null} upstack products search -q "shirt" upstack products search -q "shirt" --page-size 50 upstack products search --cursor "<nextCursor from previous response>" ``` `--page-size` accepts 1–100 (default 20). Pass the `nextCursor` from the response into `--cursor` to page. **Required scope:** `costs:read`. ## cost Show the resolved cost breakdown for a single variant — the per-unit effective cost, handling fee, and which configuration tier supplied it (per-variant COG line, global override, or default fallback). ```bash theme={null} upstack products cost --product-id prd_123 --variant-id var_456 ``` **Required scope:** `costs:read`. ## handling-fee set Set the per-variant handling fee. Must be `>= 0`. ```bash theme={null} upstack products handling-fee set --product-id prd_123 --variant-id var_456 --fee 2 upstack products handling-fee set --product-id prd_123 --variant-id var_456 --fee 0 --yes ``` **Required scope:** `costs:write`. ## cogs add Append a new COG line to a variant's manual cost history. The server assigns a ULID for the new line. ```bash theme={null} upstack products cogs add \ --product-id prd_123 --variant-id var_456 \ --cost 5 --start 2026-01-01 \ --description "Q1 batch" upstack products cogs add \ --product-id prd_123 --variant-id var_456 \ --cost 6 --start 2026-04-01 --end 2026-06-30 ``` `--end` is optional — omit for an open-ended interval. **Required scope:** `costs:write`. ## cogs update Update an existing COG line by its server-assigned ID. Pass any combination of `--cost`, `--start`, `--end`, `--description`. Use `--end null` to clear an end date (make the line open-ended). ```bash theme={null} upstack products cogs update \ --product-id prd_123 --variant-id var_456 --cog-id cog_abc \ --cost 7 upstack products cogs update \ --product-id prd_123 --variant-id var_456 --cog-id cog_abc \ --end null ``` **Required scope:** `costs:write`. ## cogs delete Delete a COG line by its ID. The CLI prompts for confirmation; `--yes` (or `-y`) skips it. ```bash theme={null} upstack products cogs delete \ --product-id prd_123 --variant-id var_456 --cog-id cog_abc ``` **Required scope:** `costs:write`. # Profiles Source: https://docs.upstackdata.com/cli/profiles Switch between API keys, pixels, and environments using named profiles. Profiles let you keep multiple `(API key, pixel id)` configurations side-by-side — e.g. one for production and one for staging, or one per client. ## Create a profile ```bash theme={null} upstack init --profile staging upstack init --profile client-b ``` ## Use a profile Pass `--profile <name>` on any command. Without `--profile`, the `default` profile is used. ```bash theme={null} upstack --profile staging query --measures revenue \ --date-start 2026-04-01 --date-end 2026-04-30 upstack whoami --profile staging ``` ## List profiles ```bash theme={null} upstack profiles ``` Prints all configured profile names. ## Remove a profile ```bash theme={null} upstack logout --profile staging ``` Removes credentials for the named profile from `~/.upstackrc`. If it was the last profile, the file is deleted. ## Storage All profiles live in `~/.upstackrc` (mode `0600`) under a `profiles` map: ```json theme={null} { "profiles": { "default": { "baseUrl": "...", "apiKey": "upstack_...", "pixelId": "..." }, "staging": { "baseUrl": "...", "apiKey": "upstack_...", "pixelId": "..." } } } ``` # upstack query Source: https://docs.upstackdata.com/cli/query Run a measures-and-dimensions query from the command line. Wraps POST /api/query. Run a measures-and-dimensions query against your event stream. Wraps `POST /api/query` — see the [API reference](/api-reference/overview). ## Usage ```bash theme={null} upstack query \ --measures orders.gross_revenue,tracked.purchases \ --dimensions utm_source \ --date-start 2026-04-01 \ --date-end 2026-04-30 ``` ## Required flags | Flag | Description | | ----------------------------------------------------- | --------------------------------------------------------------------------------- | | `--measures <m1,m2,...>` | Comma-separated canonical measure ids (see [`upstack measures`](/cli/measures)). | | `--granularity <g>` | `none`, `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter`, or `year`. | | `--date-start <YYYY-MM-DD>` `--date-end <YYYY-MM-DD>` | Date range. | ## Optional flags | Flag | Description | Default | | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------- | | `--dimensions <d1,d2,...>` | Comma-separated dimension ids. Max 5. | | | `--filter <json>` | Canonical [Filter](/cli/filters) as JSON. See the [Filters](#filters) section below for the shape. | | | `--compare-start <YYYY-MM-DD>` `--compare-end <YYYY-MM-DD>` | Optional comparison period. Must not overlap the primary date range. | | | `--timezone <tz>` | IANA timezone (e.g. `America/New_York`). | `UTC` | ## Shared flags All query commands ([`query`](/cli/query), [`query-attribution`](/cli/query-attribution), [`query-cohort`](/cli/query-cohort)) support these: | Flag | Description | Default | | -------------------- | ----------------------------------------------------------------------- | ------- | | `-i, --interactive` | Build the query step-by-step with prompts. | | | `--output <format>` | `json`, `table`, or `csv`. | `json` | | `--file <path>` | Write output to a file instead of stdout. | | | `--from-file <path>` | Load query parameters from a JSON file. CLI flags override file values. | | ## Examples ```bash theme={null} # Gross revenue by day, last 30 days upstack query --measures orders.gross_revenue --granularity day \ --date-start 2026-04-01 --date-end 2026-04-30 # CSV output, broken down by UTM source upstack query --measures orders.gross_revenue,tracked.purchases \ --dimensions utm_source --granularity day \ --date-start 2026-04-01 --date-end 2026-04-30 \ --output csv --file ./april-by-source.csv # Scope to web/POS orders for new customers via canonical filter upstack query --measures orders.gross_revenue --granularity day \ --date-start 2026-04-01 --date-end 2026-04-30 \ --filter '{"and":[{"field":"orders.source_name","op":"in","value":["web","pos"]},{"field":"orders.customer_type","op":"equals","value":"new_customer"}]}' # Interactive upstack query -i ``` ## Filters `--filter` takes a canonical Filter JSON object. The shape is a recursive `{ and | or | not }` group tree with leaves of the form `{ field, op, value }`: ```json theme={null} { "and": [ { "field": "orders.source_name", "op": "in", "value": ["web", "pos"] }, { "field": "orders.customer_type", "op": "equals", "value": "new_customer" } ] } ``` Field ids are namespaced (`orders.*`, `channel.*`, `attribution.*`, `emq.*`) and each one is only valid in certain contexts. Run [`upstack filters --detail`](/cli/filters) to list every field with its operators and applicable contexts before constructing a filter. ## Save a query for reuse ```bash theme={null} upstack saved create morning-report --command query --from-file ./params.json upstack saved run morning-report ``` See [`upstack saved`](/cli/saved-queries) for the full reference. # upstack query-attribution Source: https://docs.upstackdata.com/cli/query-attribution Run an attribution query from the command line. Wraps POST /api/query-attribution. Run an attribution query. Wraps `POST /api/query-attribution` — see the [API reference](/api-reference/overview). ## Usage ```bash theme={null} upstack query-attribution \ --dimension utm_source \ --model first_click \ --window 30 \ --date-start 2026-04-01 \ --date-end 2026-04-30 ``` ## Required flags | Flag | Description | | ----------------------------------------------------- | ------------------------------------------------------------------------------ | | `--dimension <d>` | Dimension to attribute by (e.g. `utm_source`, `utm_campaign`). | | `--model <m>` | `first_click`, `last_click`, or `any_click`. | | `--window <days>` | Attribution window. One of `1`, `7`, `14`, `30`, `60`, `90`, `-1` (unlimited). | | `--date-start <YYYY-MM-DD>` `--date-end <YYYY-MM-DD>` | Date range. | ## Optional flags | Flag | Description | Default | | --------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------- | | `--filter <json>` | Canonical [Filter](/cli/query#filters) as JSON. `attribution.utm_*` fields and `orders.*` fields apply here. | | | `--timezone <tz>` | IANA timezone. | `UTC` | | `--value-source <s>` | `orders` or `events`. | `orders` | | `--conversion-event <name>` | Required when `--value-source=events`. | `purchase` | See [`upstack query`](/cli/query#shared-flags) for the shared output / interactive / from-file flags. ## Examples ```bash theme={null} # First-click attribution by UTM source, last 30 days upstack query-attribution \ --dimension utm_source --model first_click --window 30 \ --date-start 2026-04-01 --date-end 2026-04-30 # Last-click, unlimited window, event-based valuation upstack query-attribution \ --dimension utm_campaign --model last_click --window -1 \ --value-source events --conversion-event signup_completed \ --date-start 2026-04-01 --date-end 2026-04-30 # Scope to one UTM source via canonical filter upstack query-attribution \ --dimension utm_campaign --model last_click --window 30 \ --date-start 2026-04-01 --date-end 2026-04-30 \ --filter '{"and":[{"field":"attribution.utm_source","op":"equals","value":"google"}]}' # Interactive upstack query-attribution -i ``` Run [`upstack filters --detail`](/cli/filters) to see every field valid in the `attribution` context with its operators. # upstack query-channel-details Source: https://docs.upstackdata.com/cli/query-channel-details List ad accounts, campaigns, ad sets, or ads with optional metrics from the command line. Wraps POST /api/query-channel-details. List ad accounts, campaigns, ad sets, or ads — with optional metric aggregation — from the ads-platform integrations connected to your pixel. Wraps `POST /api/query-channel-details` — see the [API reference](/api-reference/overview). The **grain** is controlled by `--dimensions`: * omit it for **account grain** (the default; one row per ad account across every connected platform — Facebook, Google, TikTok), * pass exactly one of `campaign`, `adset`, or `ad` for that grain. When `--date-start` / `--date-end` are omitted, the response is an entity-only listing (no metric aggregation). To scope by ad platform, use a canonical filter on `channel.resource_source` (not a dimension). ## Usage ```bash theme={null} upstack query-channel-details --granularity day ``` ## Required flags | Flag | Description | | ------------------- | ------------------------------------------ | | `--granularity <g>` | `hour`, `day`, `week`, `month`, or `year`. | ## Optional flags | Flag | Description | Default | | ----------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------- | | `--dimensions <grain>` | `campaign`, `adset`, or `ad`. Omit for account grain. | (account) | | `--date-start <YYYY-MM-DD>` `--date-end <YYYY-MM-DD>` | Date range. Required together with `--measures` (entity-list-only when absent). | | | `--measures <m1,m2,...>` | Comma-separated measure ids (e.g. `channel.spend`, `channel.impressions`, `meta.cpm`). | | | `--filter <json>` | Canonical [Filter](/cli/filters) as JSON. | | | `--timezone <tz>` | IANA timezone. | `UTC` | | `--limit <n>` | Max rows returned (1–500). | `50` | | `--offset <n>` | Skip the first N rows. | `0` | | `--sort-by <field>` | One of `sourceUpdatedAt`, `sourceCreatedAt`, `resourceName`. | `sourceUpdatedAt` | | `--sort-direction <dir>` | `asc` or `desc` (case-insensitive). | `desc` | See [`upstack query`](/cli/query#shared-flags) for the shared output / from-file flags. ## Examples ```bash theme={null} # Top 50 ad accounts across all connected platforms (listing-only) upstack query-channel-details --granularity day # Campaigns with spend + impressions for April upstack query-channel-details \ --dimensions campaign \ --granularity day \ --date-start 2026-04-01 --date-end 2026-04-30 \ --measures channel.spend,channel.impressions # Scope to one Facebook ad account via canonical filter upstack query-channel-details \ --dimensions campaign --granularity day \ --filter '{"and":[{"field":"channel.account_id","op":"equals","value":"<account_id>"}]}' # Drill from a specific campaign down to its ad sets upstack query-channel-details \ --dimensions adset --granularity day \ --filter '{"and":[{"field":"channel.campaign_id","op":"equals","value":"<campaign_id>"}]}' ``` ## See also * [`upstack filters`](/cli/filters) — discover valid filter fields, operators, and applicable contexts (every `channel.*` field is valid here). * [`upstack measures`](/cli/measures) — list measure ids available across all query endpoints. # upstack query-cohort Source: https://docs.upstackdata.com/cli/query-cohort Run a cohort analysis from the command line. Wraps POST /api/query-cohort-analysis. Run a cohort analysis — cohort an audience by acquisition period and analyze retention or LTV over time. Wraps `POST /api/query-cohort-analysis` — see the [API reference](/api-reference/overview). ## Usage ```bash theme={null} upstack query-cohort \ --measures orders.ltv_cohort_gross_revenue \ --granularity week \ --date-start 2026-01-01 \ --date-end 2026-04-30 ``` ## Required flags | Flag | Description | | ----------------------------------------------------- | ---------------------------------------- | | `--measures <m1,m2,...>` | One or more cohort-specific measure ids. | | `--granularity <g>` | `week`, `month`, or `year`. | | `--date-start <YYYY-MM-DD>` `--date-end <YYYY-MM-DD>` | Date range. | ## Cohort-only measures This endpoint only accepts these measure ids: | Measure id | What it computes | | --------------------------------- | ------------------------------------- | | `orders.ltv_cohort_gross_revenue` | Cohorted gross revenue over time. | | `orders.ltv_cohort_net_revenue` | Cohorted net revenue (after refunds). | | `orders.customers_cohort` | Customer count per cohort. | | `orders.avg_order_value_cohort` | Cohort AOV. | | `orders.cohort_retention_percent` | Retention rate per cohort. | | `orders.cohort_cm1` / `cm2` | Cohort contribution margins. | ## Optional flags | Flag | Description | Default | | ----------------- | ---------------------------------------------------------------------------------------- | ------- | | `--filter <json>` | Canonical [Filter](/cli/query#filters) as JSON. `orders.*` fields apply in this context. | | | `--timezone <tz>` | IANA timezone. | `UTC` | See [`upstack query`](/cli/query#shared-flags) for the shared output / interactive / from-file flags. ## Examples ```bash theme={null} # Weekly LTV cohort upstack query-cohort \ --measures orders.ltv_cohort_gross_revenue,orders.cohort_retention_percent \ --granularity week \ --date-start 2026-01-01 --date-end 2026-04-30 # Interactive upstack query-cohort -i ``` # upstack saved Source: https://docs.upstackdata.com/cli/saved-queries Cache query parameters locally for reuse. Run, list, inspect, and delete saved queries. Cache query parameters locally for reuse. Saved queries live in `~/.upstack_saved/`, one JSON file per query. ## Subcommands ### `create <name>` ```bash theme={null} upstack saved create morning-report --command query --from-file ./params.json ``` | Flag | Description | | ---------------------- | --------------------------------------------------------------------------------------- | | `--command <c>` | Required. One of `query`, `query-attribution`, `query-cohort`, `query-channel-details`. | | `--from-file <path>` | JSON file with the query parameters. | | `--description <text>` | Optional description for the saved query. | You can also pass query parameters inline as flags (e.g. `--measures orders.gross_revenue`, `--date-start 2026-04-01`, `--filter '{"and":[...]}'`) — they're merged with the file values; flags override file values. Run [`upstack filters --detail`](/cli/filters) to discover valid filter fields before constructing a `--filter` value. ### `list` ```bash theme={null} upstack saved list ``` ### `show <name>` Inspect a saved query without running it. ```bash theme={null} upstack saved show morning-report ``` ### `run <name>` Re-run a saved query. ```bash theme={null} upstack saved run morning-report upstack saved run morning-report --output csv --file ./today.csv # override output on the fly ``` ### `delete <name>` ```bash theme={null} upstack saved delete morning-report ``` # How Attribution Models Measure Marketing Performance Source: https://docs.upstackdata.com/concepts/attribution-and-reporting Compare attribution models in Upstack Analytics — first-touch, last-touch, and multi-touch — and see how each assigns conversion credit across marketing channels for accurate ROAS reporting. Attribution is the practice of determining which marketing touchpoints deserve credit for a conversion — and by how much. <Tip> Merchants using Upstack Analytics report finding 15–30% of their ad spend allocated to channels that appear profitable in-platform but underperform when measured with independent multi-touch attribution. </Tip> ## Why It Matters Every ad platform marks itself as the hero. Meta claims the sale. Google claims the same sale. Klaviyo takes credit too. When you add up each platform's reported revenue, the total exceeds your actual revenue by 2–3x. This is the double-counting problem — and it makes budget allocation guesswork. The root cause is that ad platforms use self-attributed, last-click models scoped to their own ecosystem. They can't see the full customer journey, so they assign full credit to their own touchpoint. A shopper who clicked a Meta ad on Monday, a Google ad on Wednesday, and a Klaviyo email on Friday appears as three separate conversions across three dashboards. Independent attribution — measured from your own first-party data — eliminates double-counting. When you own the data pipeline from click to purchase, you can apply consistent models across every channel and allocate credit based on the actual customer journey, not each platform's self-serving view. ## How It Works Upstack Analytics operates at the **Understand** stage of the data pipeline. It queries the identity-resolved, enriched event stream stored in your analytics warehouse to build a unified view of each customer's journey. **Attribution models** determine how conversion credit is distributed: * **First-touch** — 100% credit goes to the touchpoint that originally acquired the customer. Useful for measuring top-of-funnel acquisition channels. * **Last-touch** — 100% credit goes to the final touchpoint before conversion. Mirrors how most ad platforms report by default. * **Linear (multi-touch)** — Credit is split equally across all touchpoints in the journey. Surfaces mid-funnel contributors that single-touch models ignore. * **Time-decay (multi-touch)** — Touchpoints closer to conversion receive more credit. Balances recency with full journey visibility. **Lookback windows** control how far back Upstack searches for qualifying touchpoints. A 7-day window attributes purchases only to clicks within the past week. A 28-day window captures longer consideration cycles common in higher-AOV stores. **Channel credit** aggregates touchpoint-level attribution up to the channel level (Meta, Google, Klaviyo, organic, direct) so you can compare true ROAS and CPA across your entire marketing mix in a single view. ## Key Terms | Term | Definition | | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | | **Attribution model** | A rule set that determines how conversion credit is divided among marketing touchpoints. | | **First-touch attribution** | Assigns all credit to the first interaction in the customer journey. | | **Last-touch attribution** | Assigns all credit to the final interaction before conversion. | | **Multi-touch attribution (MTA)** | Distributes credit across multiple touchpoints based on a weighting rule (linear, time-decay, position-based). | | **Lookback window** | The time period within which touchpoints are eligible for attribution credit. | | **ROAS (Return on Ad Spend)** | Revenue generated per dollar of ad spend — the primary efficiency metric for paid channels. | <CardGroup> <Card title="Analytics Dashboard Guide" icon="chart-line" href="/analytics/query-guide"> Walk through the Upstack Analytics dashboard and its key reports. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> Learn how Upstack ID builds the unified customer journey that attribution depends on. </Card> </CardGroup> # How Conversion API Forwarding Improves Ad Platform Signal Quality Source: https://docs.upstackdata.com/concepts/conversion-api-forwarding Forward conversion events to Meta CAPI, TikTok, Google Ads, and other ad platforms via server-to-server delivery with strong match keys — improving EMQ scores and Smart Bidding signal. Conversion API forwarding sends your store's conversion events directly from Upstack's servers to ad platform servers — bypassing the browser entirely and delivering the identity signals that algorithms need to optimize. <Tip> Merchants forwarding through Upstack Signal consistently achieve Meta Event Match Quality (EMQ) scores of 8.0+ across all standard events, compared to the 3–5 range typical of browser pixels alone. </Tip> ## Why It Matters Ad platforms like Meta and TikTok have shifted to server-side conversion APIs as the primary signal source for their bidding algorithms. Meta's Conversions API (CAPI), TikTok's Events API, and similar endpoints now carry more weight than browser pixels in auction optimization and measurement. But sending events to these APIs is only half the problem. What matters is **signal quality** — how well each event can be matched back to a user on the ad platform. Meta quantifies this as Event Match Quality (EMQ), a 1–10 score reflecting how many match keys (hashed email, phone, IP, user agent, click ID) are present on each event. A PageView with only IP and user agent might score a 3. A Purchase with hashed email, phone, and `fbclid` scores a 9. Low EMQ means the platform can't attribute conversions to ad clicks, so your reported ROAS drops, your Custom Audiences shrink, and the algorithm loses the feedback loop it needs to find more buyers. Upstack Signal solves this by combining identity-resolved events with a full set of match keys before delivery. ## How It Works Upstack Signal operates at the **Activate** stage of the data pipeline. After events have been captured (Upstack Pixel), resolved (Upstack ID), and enriched (Upstack Enrichment), Signal formats and delivers them to each configured destination. The forwarding process follows three steps: 1. **Match key assembly** — Upstack attaches every available identifier to the event: hashed email (`em`), hashed phone (`ph`), first-party click IDs (`fbclid`, `ttclid`), IP address, user agent, and external ID. Identity resolution ensures these fields are populated even for events that were originally anonymous. 2. **Schema transformation** — Each destination has its own event schema. Upstack Signal maps your canonical events to the exact format each API expects — `Purchase` becomes a Meta `Purchase` event with `value`, `currency`, and `content_ids` in the right structure. 3. **Reliable delivery** — Events are queued via SQS with automatic retry and dead-letter handling. If Meta's API returns a transient error, the event is retried with exponential backoff. Permanent failures are logged for troubleshooting without data loss. Delivery is server-to-server. No browser tag, no JavaScript, no ad blocker risk. ## Key Terms | Term | Definition | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------- | | **Conversion API (CAPI)** | A server-to-server interface for sending conversion events to an ad platform (e.g., Meta Conversions API). | | **Event Match Quality (EMQ)** | Meta's 1–10 score reflecting how well an event's identity signals match a Facebook user profile. | | **Match keys** | Hashed identity fields (email, phone, address) attached to each event to enable ad platform matching. | | **Click ID** | A platform-specific parameter (`fbclid`, `ttclid`, `gclid`) appended to ad URLs that links a click to a conversion. | | **Dead-letter queue** | A queue where events that fail delivery after all retries are stored for inspection. | <CardGroup> <Card title="Set Up Meta CAPI" icon="meta" href="/get-started/connect-a-destination"> Connect Upstack Signal to Meta's Conversions API step by step. </Card> <Card title="Destinations Overview" icon="bullseye-arrow" href="/destinations/overview"> See all supported forwarding destinations and their configuration options. </Card> </CardGroup> # How Data Enrichment Strengthens Events and Customer Profiles Source: https://docs.upstackdata.com/concepts/data-enrichment Enrich tracking events with customer metadata, identity match keys, and contextual data to improve destination match quality, attribution accuracy, and downstream analytics. Data enrichment appends additional context — customer metadata, geographic data, and behavioral attributes — to raw events and identity profiles before they reach destinations or your analytics warehouse. <Tip> Enriched events carry more match keys, which directly raises Event Match Quality (EMQ) scores on platforms like Meta — turning a 5 into an 8 without changing your tracking setup. </Tip> ## Why It Matters A raw event captured at the edge contains the basics: URL, timestamp, IP address, user agent, and whatever identifiers the visitor volunteered. That's enough to record that *something* happened, but it's not enough for downstream systems to do their best work. Conversion APIs score events based on match key completeness. An `AddToCart` event with only an IP address and user agent will match poorly on Meta. The same event enriched with hashed email, phone number, city, and zip code matches at a significantly higher rate — improving both reported conversions and algorithm optimization. Enrichment also improves your own analytics. Customer lifetime value calculations become more accurate when events carry purchase history and order frequency. Segmentation becomes more granular when profiles include geographic and behavioral attributes. Every system downstream of enrichment — forwarding, attribution, reporting — benefits from richer input data. ## How It Works Upstack Enrichment operates at the **Enrich** stage of the data pipeline, after identity resolution and before forwarding or warehouse storage. Enrichment draws from three sources: * **Identity graph** — Once Upstack ID resolves a visitor, Enrichment pulls all known identifiers associated with that profile (email, phone, address) and attaches them to the current event. An anonymous `PageView` gains match keys from a previous checkout on another device. * **Shopify customer data** — Order history, customer tags, total spend, and order count are synced from Shopify and attached to resolved profiles. These fields feed both forwarding destinations (as customer parameters) and analytics (for cohort and LTV calculations). * **Event context** — Geographic data derived from IP (city, region, country, postal code), device classification (mobile, desktop, tablet), and referrer parsing (UTM parameters, landing page) are appended to every event at processing time. Enrichment is automatic. Once Upstack Pixel is capturing events and Upstack ID is resolving identities, every event flowing through the pipeline is enriched before it reaches any destination or warehouse table. ## Key Terms | Term | Definition | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | **Match key** | A hashed identity field (email, phone, address) used by ad platforms to link a conversion event to a user profile. | | **Customer metadata** | Attributes from Shopify (total spend, order count, customer tags) attached to a resolved identity profile. | | **Event context** | Non-identity attributes appended at processing time: geography, device type, UTM parameters, referrer. | | **Profile enrichment** | The process of augmenting an identity graph node with additional data from first-party and platform sources. | | **EMQ (Event Match Quality)** | Meta's score reflecting how well an event's identity signals can be matched to a user — directly improved by enrichment. | <CardGroup> <Card title="Conversion API Forwarding" icon="arrow-right-arrow-left" href="/concepts/conversion-api-forwarding"> See how enriched events improve signal quality when forwarded to ad platforms. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> Understand the identity layer that enrichment depends on. </Card> </CardGroup> # Destinations vs data sources: a complete guide Source: https://docs.upstackdata.com/concepts/destinations-vs-data-sources Destinations send data to ad platforms and email tools; data sources pull data from them. Configure both to power unified attribution, ROAS reporting, and event enrichment in Upstack Data. Two of the most important concepts in Upstack Data are **destinations** and **data sources** (referred to in the dashboard as **Sources**). They sound similar but serve opposite functions — and understanding the difference is essential for setting up your account correctly and getting accurate attribution data. ## The core distinction <CardGroup> <Card title="Destinations" icon="arrow-right-from-bracket" href="/destinations/overview"> Platforms Upstack **sends** event data **to**. When a customer views a product, adds to cart, or purchases, Upstack captures the event, enriches it with identity data, and pushes it to your destinations via server-side APIs. </Card> <Card title="Data sources (Sources)" icon="arrow-right-to-bracket" href="/sources/overview"> Platforms Upstack **pulls** data **from** for reporting and analytics. To show which campaigns are driving revenue and at what cost, Upstack pulls in your ad spend, impressions, and click data from each platform. </Card> </CardGroup> Think of it this way: * **Destinations** = Upstack pushing data **OUT** (events going to ad platforms and marketing tools). * **Sources** = Upstack pulling data **IN** (spend and performance data for your dashboard). ## Why the distinction matters You might wonder why these are separate. After all, Meta is both a destination (Upstack sends purchase events to it) and a source (Upstack pulls spend data from it). They're configured separately because they serve different purposes and require different permissions: * **Sending events** (destination) requires write access to a platform's conversion API — like [Meta CAPI](/destinations/meta-capi) or [Google Ads](/destinations/google-ads) offline conversions. This is about feeding the ad platform real-time conversion data for optimization. * **Pulling spend data** (source) requires read access to a platform's reporting API. This is about bringing performance data into Upstack's [attribution dashboard](/concepts/attribution-and-reporting) so you can see the full picture in one place. You can connect a platform as a destination without connecting it as a source, and vice versa. But for the complete picture — events flowing out and spend data flowing in — you'll want both. ## Available destinations Destinations receive enriched event data from Upstack via server-side APIs. Each destination gets relevant ecommerce events along with identity parameters for user matching. | Destination | API used | Events sent | Identity data sent | | -------------- | ------------------------------ | ----------------------------------------------------------------- | ---------------------------------------------------------- | | **Meta CAPI** | Conversions API | Purchase, AddToCart, ViewContent, InitiateCheckout, custom events | Hashed email, phone, name, IP, user agent, `fbclid`, `fbp` | | **Google Ads** | Offline / Enhanced Conversions | Purchase, conversion events | `gclid`, hashed email, phone | | **TikTok** | Events API | Purchase, AddToCart, ViewContent, funnel events | Hashed email, phone, IP, user agent, `ttclid` | | **Pinterest** | Conversions API | Purchase, AddToCart, ViewContent | Hashed email, click ID, IP, user agent | | **Klaviyo** | Klaviyo API | Browse, cart, purchase events for flow triggering | Email, customer properties, event metadata | | **Snapchat** | Conversions API | Purchase, conversion events | Hashed email, phone, IP, click ID | | **Omnisend** | Omnisend API | Browse, cart, purchase events | Email, customer properties, event metadata | | **Webhooks** | Custom HTTP | Any configured event | Full enriched payload | <Note> GA4 is no longer a supported destination for new connections and is being deprecated. </Note> ## Available data sources Data sources provide Upstack with the information it needs to build your attribution dashboard and calculate key metrics like ROAS. | Data source | Data pulled | Used for | | ------------------------------------------------ | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | **[Shopify](/sources/shopify)** | Orders, revenue, products, customer data, refunds | Revenue attribution, order-level reporting, customer classification (new vs returning) | | **[Facebook Ads (Meta)](/sources/facebook-ads)** | Campaign spend, impressions, clicks, campaign/ad set/ad structure | ROAS calculation, spend-to-revenue comparison, campaign-level attribution | | **[Google Ads](/sources/google-ads)** | Campaign spend, impressions, clicks, campaign structure | ROAS calculation, spend-to-revenue comparison, campaign-level attribution | | **[TikTok](/sources/tiktok)** | Campaign spend, impressions, clicks, campaign structure | ROAS calculation, spend-to-revenue comparison, campaign-level attribution | ## How they work together The real power of Upstack comes from destinations and sources working in tandem: <Steps> <Step title="Events go OUT via destinations"> A customer makes a purchase. Upstack captures the event, enriches it with identity data, and sends it to Meta via CAPI, Google via offline conversions, and any other connected destinations. </Step> <Step title="Spend data comes IN via sources"> Upstack pulls your daily ad spend, campaign structure, and performance metrics from Meta, Google, TikTok, and Shopify. </Step> <Step title="The attribution dashboard combines both"> Upstack's [Analytics](/concepts/attribution-and-reporting) matches revenue from Shopify orders (attributed through its own model) against spend data from your ad platforms. This gives you a unified view: how much you spent on each channel, how much revenue each channel drove, and your true ROAS — without relying on each platform's self-reported numbers. </Step> </Steps> Without destinations connected, your ad platforms don't receive enriched conversion data and can't optimize effectively. Without sources connected, your Upstack dashboard can't show spend or calculate ROAS. You need both for the full picture. ## Setup priority order If you're configuring Upstack for the first time, here's the recommended order: <Steps> <Step title="Phase 1 — Critical (Day 1)"> 1. **Meta as a destination** — get enriched events flowing to your highest-spend platform. 2. **Google Ads as a destination** — second-highest priority for most brands. 3. **Shopify as a source** — usually connected automatically during installation. See [Connect a destination](/get-started/connect-a-destination) for the step-by-step. </Step> <Step title="Phase 2 — Important (Day 1–2)"> 4. **Meta as a source** — pull spend data so your dashboard can calculate ROAS. 5. **Google Ads as a source** — same reason. 6. **Klaviyo as a destination** — if you use Klaviyo for email/SMS marketing. </Step> <Step title="Phase 3 — Expand (Week 1)"> 7. **TikTok, Pinterest, Snapchat, Omnisend as destinations** — connect any additional platforms you advertise on or use for marketing automation. 8. **TikTok as a source** — to see TikTok spend in your dashboard alongside Meta and Google. </Step> </Steps> ## Common confusion <AccordionGroup> <Accordion title="I connected Facebook — why don't I see spend data?"> Connecting Facebook as a **destination** ([Meta CAPI](/destinations/meta-capi)) only sets up event sending. You also need to connect [Facebook Ads as a source](/sources/facebook-ads) to pull in spend and campaign data for your attribution dashboard. </Accordion> <Accordion title="My attribution dashboard shows revenue but no ROAS"> ROAS requires both revenue data (from Shopify) and spend data (from ad platform sources). If you haven't connected your ad platforms as sources, Upstack can't calculate ROAS. See [Attribution and reporting](/concepts/attribution-and-reporting). </Accordion> <Accordion title="Do I need to connect Shopify as a destination?"> No. Shopify is a **source** — Upstack pulls order data from it. Shopify isn't a destination because you don't send tracking events to Shopify; events originate from Shopify. </Accordion> </AccordionGroup> ## Frequently asked questions <AccordionGroup> <Accordion title="Can a platform be both a destination and a source?"> Yes. Meta, Google Ads, and TikTok are all both destinations (Upstack sends events to them) and sources (Upstack pulls spend data from them). They're configured separately because they use different APIs and permissions. </Accordion> <Accordion title="What happens if I only connect destinations but not sources?"> Your ad platforms will receive enriched event data and optimize more effectively, but your Upstack attribution dashboard won't be able to show spend or calculate ROAS. You'll still see revenue attribution, but without the cost side of the equation. </Accordion> <Accordion title="What happens if I only connect sources but not destinations?"> Your Upstack dashboard will show spend data, but your ad platforms won't receive enriched server-side events from Upstack. You'd miss out on improved match quality, better optimization signals, and the core value of server-side tracking. </Accordion> <Accordion title="Do sources update in real time?"> Ad spend data is typically pulled on a regular schedule (daily or more frequently) rather than in real time. There may be a short delay between when spend occurs on the ad platform and when it appears in your Upstack dashboard. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Destinations overview" icon="arrow-right-from-bracket" href="/destinations/overview"> Every supported destination and its configuration options. </Card> <Card title="Sources overview" icon="arrow-right-to-bracket" href="/sources/overview"> Every supported data source and how each one is connected. </Card> <Card title="Connect a destination" icon="plug" href="/get-started/connect-a-destination"> Step-by-step setup for your first destination. </Card> <Card title="Attribution and reporting" icon="chart-line" href="/concepts/attribution-and-reporting"> How Upstack combines event data and spend data to attribute revenue. </Card> <Card title="What are destinations?" icon="circle-question" href="/what-are-destinations"> A focused deep-dive on destinations. </Card> <Card title="What are data sources?" icon="circle-question" href="/what-are-data-sources"> A focused deep-dive on sources. </Card> </CardGroup> # How post-purchase upsells are tracked Source: https://docs.upstackdata.com/concepts/how-post-purchase-upsells-are-tracked How Upstack Data tracks post-purchase upsells, subscription renewals, quiz and lead events, and custom events without double-counting conversions. If you use a post-purchase upsell app (AfterSell, Zipify, Funnelish, and similar), the upsell creates a separate Shopify order after the original purchase. Since the purchase event has already been sent to your ad platform, its value can't be updated. Upstack Data handles this by: 1. Sending the original purchase event with the original order value at checkout. 2. Blocking the upsell order from being sent as a second purchase event. 3. Firing a separate **Upsell Purchase** custom event with only the upsell amount. This prevents double-counting while still capturing upsell value separately. <Tip> To see total ROAS including upsells, create a custom metric in Meta Ads Manager that adds Purchase value and Upsell Purchase value together, then divides by original purchase count — giving you a blended AOV and ROAS. </Tip> <Note> **Why not send the combined value?** The purchase event fires at checkout, before the upsell offer is presented. There's no way to wait for the upsell decision without losing browser-side tracking data, and sending a second standard purchase would cause duplicates. The separate event is the cleanest approach. </Note> ## How subscription renewals are tracked For stores using subscription apps (Loop, Skio, ReCharge, Bold, and similar), Upstack separates initial purchases from renewals: * **Initial subscription purchase** — sent as a standard Purchase event, attributed normally. * **Recurring payments** — automatically excluded from ad platforms. Sending them as standard purchases would inflate reported conversions and misrepresent campaign performance. In your Upstack dashboard, total revenue includes both initial and recurring payments. The exclusion only applies to what's sent to ad platforms as an attribution signal. ## Quiz funnels and custom lead events If your store uses a quiz funnel, Upstack Data can send events at each stage: * **Quiz Question Answered** — fires for each question answered. * **Quiz Completed** — fires when the visitor finishes the quiz. * **Quiz Lead** — fires when the visitor submits their email. These events help ad platforms identify high-intent visitors and find similar audiences. You can also assign dollar values to prioritize higher-value prospects. Quiz events require your developer to implement triggers on your site. Upstack Data provides the event schema; your team wires it into the quiz flow. ## Event mapping for restricted categories For stores in restricted categories (health and wellness, CBD, supplements), Facebook may flag or restrict accounts that send certain product data. Upstack Data mitigates this by stripping sensitive information — such as product titles, URLs, and product paths — from events sent to Meta. This reduces the risk of account flags while maintaining event match quality through other identifiers (email, phone, IP, External ID). ## Do I need to rebuild my campaigns for custom events? No. Custom events are sent alongside standard events, so your campaigns can continue optimizing for Purchase. Events like NC Purchase and Upsell Purchase appear as additional Ads Manager columns for reporting. You only need a new campaign if you want to optimize toward a specific custom event. <Note> Need help setting up quiz events, understanding custom event data, or configuring upsell tracking? Reach out to our support team. </Note> ## Related guides <CardGroup> <Card title="Install Upstack on Shopify" icon="shop" href="/get-started/install-on-shopify"> Set up the Upstack Data tracking pixel on your Shopify store. </Card> <Card title="Connect a destination" icon="plug" href="/get-started/connect-a-destination"> Forward upsell and purchase events to Meta, TikTok, and other ad platforms. </Card> <Card title="Custom events" icon="bolt" href="/guides/custom-events/how-to-create-custom-event-triggers"> Learn how to send custom events like quiz completions and leads. </Card> <Card title="Event taxonomy" icon="list" href="/pixel/events/taxonomy"> Understand all standard events Upstack tracks, including Purchase and Upsell Purchase. </Card> </CardGroup> # Upstack Data Platform Architecture Source: https://docs.upstackdata.com/concepts/platform-architecture A technical overview of how Upstack Data's infrastructure processes marketing events — from Cloudflare edge capture through identity resolution, enrichment, forwarding, and analytics. Upstack Data is a five-stage pipeline that captures raw storefront events, resolves visitor identities, enriches events with customer context, forwards high-quality signals to ad platforms, and stores everything in an analytics warehouse you can query. <Tip> Understanding the pipeline architecture helps you diagnose where data quality issues originate and how each Upstack product contributes to your marketing data stack. </Tip> ## Why It Matters Most marketing data stacks are assembled from disconnected tools — a pixel here, a CAPI integration there, a separate analytics platform. Each tool operates on its own copy of the data, with its own identity model, its own event schema, and its own gaps. Upstack replaces that patchwork with a single pipeline. Every event flows through the same sequence of stages, accumulating identity and context at each step. This means your conversion APIs receive the same enriched events that your attribution models analyze — no reconciliation, no duplicate schemas, no conflicting identity logic. A unified pipeline also makes debugging straightforward. If a conversion isn't appearing in Meta, you can trace the event from capture through resolution, enrichment, and forwarding to pinpoint exactly where the signal was lost. ## How It Works The pipeline has five stages, each handled by a dedicated Upstack product. ```mermaid theme={null} flowchart LR A["🏪 Shopify\nStorefront"] --> B["⚡ Upstack Pixel\n(Cloudflare Edge)"] B --> C["🔗 Upstack ID\n(Identity Resolution)"] C --> D["📦 Upstack Enrichment\n(Data Enrichment)"] D --> E["📡 Upstack Signal / Flows\n(Forwarding)"] D --> F["📊 Upstack Analytics\n(Warehouse & Reporting)"] ``` ### 1. Capture — Upstack Pixel Shopper interactions on your Shopify storefront generate events (page views, add-to-cart, checkout, purchase). The Upstack theme extension sends these as first-party requests to **Cloudflare Workers** at the edge. Bot traffic is filtered, a durable first-party cookie is set, and events are normalized into a canonical schema. Latency is sub-50 ms with zero impact on storefront performance. ### 2. Resolve — Upstack ID Raw events enter the **AWS backend** where the identity resolution engine matches anonymous sessions to known customers. Deterministic matching (email, phone, login) creates hard links. Session stitching retroactively attributes anonymous events once a visitor identifies themselves. Cross-device linking merges profiles when the same identifier appears on multiple devices. ### 3. Enrich — Upstack Enrichment Resolved events are augmented with customer metadata from Shopify (order history, LTV, customer tags), geographic context from IP geolocation, and all available identity fields from the identity graph. After this stage, events carry the full set of match keys needed for high-quality forwarding. ### 4. Activate — Upstack Signal & Upstack Flows Enriched events are queued via **Amazon SQS** and delivered server-to-server to configured destinations: Meta CAPI, TikTok Events API, Google, Klaviyo, Pinterest, Snapchat, and others. Upstack Flows handles Klaviyo-specific flow recovery. Each destination adapter transforms events into the platform's required schema. Delivery includes automatic retry with exponential backoff and dead-letter queues for failed events. ### 5. Understand — Upstack Analytics Every event is also written to **SingleStore**, a high-performance analytics database. Upstack Analytics queries this warehouse to build attribution reports, calculate ROAS by channel, and surface customer journey insights — all from the same identity-resolved, enriched events that your destinations received. ## Infrastructure Summary | Layer | Technology | Role | | ----------------------- | ------------------- | ----------------------------------------------------------- | | **Edge** | Cloudflare Workers | Event capture, bot filtering, cookie management | | **Compute** | AWS Lambda | Identity resolution, enrichment, forwarding, API handlers | | **Queue** | Amazon SQS | Async event delivery with retry and dead-letter handling | | **Identity store** | PostgreSQL, Neptune | Identity graph storage and traversal | | **Analytics warehouse** | SingleStore | High-speed analytical queries for attribution and reporting | | **Configuration** | DynamoDB | Destination configs, account settings, subscription data | ## Key Terms | Term | Definition | | --------------------- | --------------------------------------------------------------------------------------------------------------------------- | | **Edge layer** | The Cloudflare-based infrastructure that captures events close to the visitor for low-latency, high-reliability collection. | | **Canonical schema** | The standardized event format used internally across all pipeline stages. | | **Dead-letter queue** | A holding queue for events that fail delivery after all retry attempts, preserving data for debugging. | | **Identity graph** | The data structure mapping all known identifiers to unified customer profiles. | | **Match keys** | Hashed identity fields attached to events that ad platforms use to link conversions to user profiles. | <CardGroup> <Card title="Server-Side Tracking" icon="server" href="/concepts/server-side-tracking"> Deep dive into the Capture stage. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> Deep dive into the Resolve stage. </Card> <Card title="Data Enrichment" icon="layer-plus" href="/concepts/data-enrichment"> Deep dive into the Enrich stage. </Card> <Card title="Conversion API Forwarding" icon="arrow-right-arrow-left" href="/concepts/conversion-api-forwarding"> Deep dive into the Activate stage. </Card> <Card title="Attribution & Reporting" icon="chart-mixed" href="/concepts/attribution-and-reporting"> Deep dive into the Understand stage. </Card> <Card title="Install Upstack Pixel" icon="rocket" href="/get-started/install-on-shopify"> Get started with the first pipeline stage. </Card> </CardGroup> # What Is Server-Side Tracking and Why Does It Matter? Source: https://docs.upstackdata.com/concepts/server-side-tracking Server-side tracking captures accurate marketing data despite ad blockers, iOS privacy changes, and browser restrictions — outperforming client-side pixels for ad attribution and ROAS. Server-side tracking moves data collection from the visitor's browser to a server you control, eliminating the reliability problems that plague traditional JavaScript pixels. <Tip> Stores using Upstack Pixel's server-side tracking typically recover 20–40% of events that client-side scripts miss due to ad blockers and Intelligent Tracking Prevention (ITP). </Tip> ## Why It Matters Traditional client-side pixels depend on JavaScript executing inside a visitor's browser. That model is breaking. Safari's ITP caps cookie lifetimes at 7 days (or 24 hours for link-decorated traffic). Firefox blocks known trackers by default. Ad blockers strip tracking scripts before they load. iOS 14.5+ App Tracking Transparency further limits signal availability across the Apple ecosystem. For Shopify merchants, every lost event is a lost signal — attribution gaps widen, retargeting audiences shrink, and ad platform algorithms receive incomplete conversion data. The downstream cost compounds: Meta's algorithm optimizes toward the wrong audience, ROAS reporting becomes unreliable, and you over-invest in channels that only *appear* to perform. Server-side tracking sidesteps these problems entirely. Because the data collection happens at the server layer — outside the browser sandbox — ad blockers, cookie restrictions, and JavaScript failures have no effect on data capture. ## How It Works Upstack Pixel operates at the **Capture** stage of the data pipeline. When a shopper interacts with your Shopify storefront, the Upstack theme extension fires lightweight first-party requests to Cloudflare's edge network — the same infrastructure that serves your site assets. At the edge, Upstack performs three critical steps before the event enters the pipeline: 1. **Bot filtering** — Known bot signatures and suspicious traffic patterns are stripped so only human interactions proceed. 2. **First-party cookie management** — A durable first-party cookie is set under your store's domain, immune to ITP restrictions because it is issued server-side. 3. **Event normalization** — Raw interaction data is transformed into a canonical event schema, ready for identity resolution and forwarding downstream. Because Cloudflare Workers execute in the same data center region as the visitor, latency stays under 50 ms and has zero impact on storefront performance. ## Key Terms | Term | Definition | | ----------------------------------------- | ----------------------------------------------------------------------------------------------------- | | **Client-side pixel** | A JavaScript tag running in the visitor's browser — vulnerable to blockers and cookie restrictions. | | **Server-side tracking** | Data collection handled by a server, outside the browser sandbox. | | **ITP (Intelligent Tracking Prevention)** | Apple's Safari feature that limits cookie lifetimes and blocks cross-site tracking. | | **First-party cookie** | A cookie set under your store's own domain, subject to fewer restrictions than third-party cookies. | | **Bot filtering** | Automated removal of non-human traffic before events enter your data pipeline. | | **Edge network** | A globally distributed server layer (Cloudflare) where Upstack processes events close to the visitor. | <CardGroup> <Card title="Quick Start: Install Upstack Pixel" icon="rocket" href="/get-started/install-on-shopify"> Get server-side tracking running on your Shopify store in under 10 minutes. </Card> <Card title="Events Taxonomy" icon="list-tree" href="/pixel/events/taxonomy"> See every event Upstack Pixel captures and its schema. </Card> </CardGroup> # How Timezones Work in Upstack Data Source: https://docs.upstackdata.com/concepts/timezones Learn how Upstack Data handles timezones across your dashboard, reports, and integrations — and how to configure your preferred timezone. Upstack Data uses your configured timezone to display all dates and times throughout the dashboard. This ensures your analytics, reports, and date filters align with your business hours. <Tip> During onboarding, Upstack automatically detects your timezone from your Shopify store (if connected) or your browser. You can change it anytime in Settings. </Tip> ## How Timezones Affect Your Dashboard Your timezone setting determines how dates and times appear across Upstack Data: * **Date filters** — When you select "Today" or "Last 7 Days," the boundaries are calculated in your configured timezone. * **Charts and reports** — Daily metrics roll up at midnight in your timezone, so revenue attributed to "June 1" reflects orders placed between 12:00 AM and 11:59 PM in your local time. * **Event timestamps** — Individual events display in your timezone for easier interpretation. * **Scheduled reports** — Any automated reports use your timezone for "daily" boundaries. <Note> Your data is stored internally in UTC for accuracy and consistency. The timezone setting only controls how that data is displayed to you. </Note> ## Timezone Detection When you first set up Upstack Data, the system automatically detects your timezone: | Condition | Detected Timezone | | --------------------------- | ------------------------------------- | | **Shopify store connected** | Your Shopify store's timezone setting | | **No Shopify connection** | Your browser's local timezone | This automatic detection ensures your dashboard immediately reflects your business's operating hours without manual configuration. ## Configuring Your Timezone You can view and change your timezone at any time from the dashboard settings. ### Where to Find Timezone Settings 1. Click **Settings** in the left sidebar 2. Select **Dashboard** 3. Locate the **Timezone** dropdown 4. Select your preferred timezone from the list 5. Click **Save Changes** The timezone list includes all standard IANA timezone identifiers (e.g., `America/New_York`, `Europe/London`, `Asia/Tokyo`). You can search by city name or region to quickly find your timezone. ## Ad Platform Data and Timezones When Upstack Data pulls performance data from your connected ad platforms (Meta, Google, TikTok, etc.), each platform reports metrics in the ad account's configured timezone. Upstack normalizes this data to UTC internally, then displays it in your configured timezone. This means your dashboard shows a unified view regardless of how each ad platform is configured — all metrics appear in your chosen timezone. ## Common Questions <AccordionGroup> <Accordion title="What happens if I change my timezone?"> Changing your timezone updates how existing data is displayed. The underlying data remains unchanged — only the presentation shifts. For example, if you switch from Pacific Time to Eastern Time, an event that appeared at "9:00 PM" will now show as "12:00 AM" the next day. </Accordion> <Accordion title="Should my timezone match my Shopify store?"> In most cases, yes. Matching timezones ensures your Upstack revenue reports align with Shopify's reporting, making reconciliation straightforward. If your business operates across multiple timezones, choose the timezone where most decisions are made or where your headquarters is located. </Accordion> <Accordion title="Does timezone affect attribution?"> Timezone affects when conversion windows begin and end. A 7-day attribution window starting "today" uses your configured timezone to determine the boundary. For consistency, keep your timezone setting stable once configured. </Accordion> <Accordion title="Why is my data showing a different date than expected?"> This usually happens when your Upstack timezone differs from your ad platform or Shopify timezone. An order placed at 11 PM Eastern on June 1 would appear as June 2 in a Pacific Time dashboard. Aligning your timezone setting typically resolves these discrepancies. </Accordion> </AccordionGroup> <CardGroup> <Card title="Attribution Reporting" icon="chart-line" href="/analytics/attribution-reporting"> Understand how Upstack Data attributes revenue to marketing touchpoints. </Card> <Card title="Analytics Query Guide" icon="magnifying-glass-chart" href="/analytics/query-guide"> Learn how to query and analyze your marketing data. </Card> </CardGroup> # Measures and Dimensions Reference Source: https://docs.upstackdata.com/data-dictionary/measures-and-dimensions Reference of every measure (numeric metric) and dimension (groupable attribute) in Upstack Analytics — definitions, calculation logic, valid combinations, and the events each is derived from. Measures and dimensions are the building blocks of every Upstack Analytics query. **Measures** are the numeric values you calculate (revenue, event counts, conversion rates). **Dimensions** are the categories you group by (date, traffic source, device type). <Tip> Start with a measure you care about (e.g., Revenue), add a dimension to break it down (e.g., `utm_source`), and apply filters to focus your analysis. Most useful reports use 1–2 measures and 1–2 dimensions. </Tip> ## Measures Measures are aggregate calculations across your event data. Select one or more measures in the query builder to define what you want to calculate. <Tip> Need a metric that isn't listed here? Build your own from a formula over these measures with [Custom Measures](/analytics/custom-measures). </Tip> | Name | Type | Description | Unit | | ----------------------- | ------- | ------------------------------------------------------------------------------------------ | ------------------------ | | `total_events` | measure | Total count of events matching the query filters. | count | | `unique_visitors` | measure | Count of distinct resolved identities (or anonymous session IDs for unresolved visitors). | count | | `sessions` | measure | Count of distinct browsing sessions. A session ends after 30 minutes of inactivity. | count | | `page_views` | measure | Count of PageView events. | count | | `purchases` | measure | Count of Purchase events. | count | | `revenue` | measure | Sum of `value` from Purchase events. | currency (store default) | | `conversion_rate` | measure | Ratio of sessions with at least one Purchase to total sessions. Expressed as a percentage. | percentage | | `avg_order_value` | measure | Mean `value` across Purchase events. Calculated as `revenue / purchases`. | currency (store default) | | `bounce_rate` | measure | Percentage of sessions with only a single PageView and no further interaction. | percentage | | `session_duration` | measure | Average time between the first and last event in a session. | seconds | | `add_to_cart_rate` | measure | Ratio of sessions with at least one AddToCart event to total sessions. | percentage | | `cart_abandonment_rate` | measure | Ratio of sessions with AddToCart but no Purchase to sessions with AddToCart. | percentage | | `avg_pages_per_session` | measure | Mean number of PageView events per session. | count | <Note> Currency-based measures (`revenue`, `avg_order_value`) use the currency from the Purchase event's `currency` field. If your store transacts in multiple currencies, values are reported in the original currency unless you enable currency normalization in settings. </Note> ## Dimensions Dimensions define how measures are grouped and broken down. Select one or more dimensions to segment your data. ### Time Dimensions | Name | Type | Description | Granularity | | ------------- | --------- | --------------------------------------------------------------------- | ----------- | | `date` | dimension | Calendar date of the event. | day | | `week` | dimension | ISO week of the event. | week | | `month` | dimension | Calendar month of the event. | month | | `hour_of_day` | dimension | Hour (0–23) when the event occurred. Useful for time-of-day analysis. | hour | | `day_of_week` | dimension | Day of the week (Monday–Sunday). | day | ### Traffic Dimensions | Name | Type | Description | Example Values | | -------------- | --------- | -------------------------------------------------------------- | -------------------------------------------------- | | `utm_source` | dimension | UTM source parameter from the landing page URL. | `facebook`, `google`, `klaviyo` | | `utm_medium` | dimension | UTM medium parameter. | `cpc`, `email`, `organic` | | `utm_campaign` | dimension | UTM campaign parameter. | `summer_sale_2026`, `retargeting_q1` | | `utm_content` | dimension | UTM content parameter for ad-level breakdown. | `hero_banner`, `sidebar_ad` | | `utm_term` | dimension | UTM term parameter for keyword-level analysis. | `cotton+tee`, `running+shoes` | | `referrer` | dimension | HTTP referrer domain that sent the visitor. | `google.com`, `facebook.com`, `direct` | | `channel` | dimension | Aggregated traffic channel derived from UTM and referrer data. | `Paid Social`, `Organic Search`, `Email`, `Direct` | ### Content Dimensions | Name | Type | Description | Example Values | | -------------- | --------- | ------------------------------------------------------------------ | ---------------------------------------------- | | `page_path` | dimension | URL path of the page (without domain or query string). | `/products/classic-tee`, `/collections/summer` | | `event_name` | dimension | Name of the event type. Stored in PascalCase (destination format). | `PageView`, `Purchase`, `AddToCart` | | `content_type` | dimension | Type of content involved in the event. | `product`, `product_group` | <Note> **Event name formats:** When calling the SDK, use `snake_case` (e.g., `add_to_cart`). Upstack transforms these to `PascalCase` for destinations and analytics storage. </Note> ### Visitor Dimensions | Name | Type | Description | Example Values | | -------------- | --------- | -------------------------------------------------------- | --------------------------------- | | `device_type` | dimension | Device category detected from user agent. | `mobile`, `desktop`, `tablet` | | `country` | dimension | Visitor's country, derived from IP geolocation. | `US`, `GB`, `CA`, `AU` | | `region` | dimension | Visitor's state or region. | `California`, `Ontario`, `London` | | `is_returning` | dimension | Whether the visitor has been seen in a previous session. | `true`, `false` | ### Destination Dimensions | Name | Type | Description | Example Values | | ----------------- | --------- | ---------------------------------------------------------------- | --------------------------------------- | | `destination` | dimension | The forwarding destination the event was sent to. | `meta_capi`, `tiktok`, `klaviyo`, `ga4` | | `delivery_status` | dimension | Whether the event was successfully delivered to the destination. | `delivered`, `failed`, `pending` | ## Combining Measures and Dimensions Here are practical examples of how measures and dimensions work together: | Goal | Measures | Dimensions | Result | | ----------------------------- | ----------------------------------------------- | -------------- | ---------------------------------------------------- | | Daily revenue trend | `revenue` | `date` | Line chart of revenue per day | | Channel ROAS comparison | `revenue`, `purchases` | `utm_source` | Table comparing revenue and purchase count by source | | Mobile vs. desktop conversion | `conversion_rate`, `sessions` | `device_type` | Bar chart comparing conversion rates | | Top landing pages | `page_views`, `bounce_rate` | `page_path` | Table of pages sorted by traffic with bounce rate | | Hourly traffic pattern | `sessions` | `hour_of_day` | Bar chart showing when visitors arrive | | Campaign performance | `revenue`, `conversion_rate`, `avg_order_value` | `utm_campaign` | Full campaign performance table | <CardGroup> <Card title="Query Guide" icon="magnifying-glass-chart" href="/analytics/query-guide"> Learn how to build queries, set date ranges, and apply filters. </Card> <Card title="Session & Page Analytics" icon="chart-line" href="/analytics/session-and-page-analytics"> Explore session-level and page-level metrics in detail. </Card> <Card title="Custom Measures" icon="calculator" href="/analytics/custom-measures"> Define your own metrics and KPIs from a formula over these measures. </Card> </CardGroup> # AppLovin Axon Source: https://docs.upstackdata.com/destinations/applovin Send conversion events to AppLovin's Axon Conversions API for mobile and web advertising attribution — improving campaign optimization and match quality. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does AppLovin's Axon Conversions API is the server-side counterpart to the Axon Pixel. Upstack Signal forwards storefront events — page views, product views, add-to-carts, checkouts, and purchases — directly to AppLovin's servers, bypassing browser restrictions like ad blockers, ITP, and cookie limits. Server-side delivery gives AppLovin's algorithm a fuller picture of the conversions your ads actually drove, which improves campaign optimization, audience modeling, and attribution accuracy. Match rates from server-side events are consistently higher than browser-only tracking because each event carries hashed customer data and the `aleid` click identifier when available. <Note> AppLovin uses **token-based auth** instead of OAuth. You'll paste a Pixel ID (Event Key) and a Conversions API access token into the Upstack destination — there is no OAuth handshake to step through. </Note> ## How it works Upstack runs as a dual-tracking layer alongside the Axon Pixel. The Upstack Pixel captures events in the browser and forwards each event to Upstack's edge infrastructure, where it is hashed, enriched with identity and click-ID data, and sent to the Axon Conversions API as a server-side event with a shared `dedupe_id`. AppLovin deduplicates server events against matching browser Pixel events using that `dedupe_id`, so you do not double-count conversions as long as both sources use the same Pixel ID. PII (`email`, `phone`) is auto-hashed by Axon via SHA-256, though Upstack pre-hashes for consistency. <Warning> **Critical:** The `dedupe_id` field is REQUIRED for all server-side events. Events without a `dedupe_id` are rejected by the API. Additionally, if any single event in a batch is invalid, the entire batch is dropped with HTTP 400. </Warning> ## Setup guides <CardGroup> <Card title="Onboarding guide" icon="route" href="/guides/applovin-ads/complete-how-to-guide-for-onboarding-applovin-in-upstack-data"> End-to-end walkthrough for connecting AppLovin to Upstack Data. </Card> <Card title="Configure destination" icon="sliders" href="/guides/applovin-ads/how-to-configure-applovin-destination-in-upstack-data"> Configure the AppLovin Axon destination inside Upstack Data. </Card> <Card title="Find Pixel ID" icon="magnifying-glass" href="/guides/applovin-ads/how-to-find-applovin-pixel-id"> Locate your Axon Pixel ID (Event Key) in the AppLovin dashboard. </Card> <Card title="Generate API token" icon="key" href="/guides/applovin-ads/how-to-generate-applovin-conversion-api-token"> Generate the Conversions API access token Upstack uses to send events. </Card> </CardGroup> ## Event mapping Upstack maps storefront events to AppLovin Axon standard events automatically: | Upstack event | AppLovin event | Key parameters | Notes | | ------------------ | ------------------ | ----------------------------------------------------- | ---------------------------- | | `PageView` | `page_view` | `url`, `referrer` | Every page navigation | | `ViewContent` | `view_item` | `items`, `value`, `currency` | Product detail page | | `AddToCart` | `add_to_cart` | `items`, `value`, `currency` | `quantity` required per item | | `RemoveFromCart` | `remove_from_cart` | `items`, `value`, `currency` | `quantity` required per item | | `InitiateCheckout` | `begin_checkout` | `items`, `value`, `currency` | All fields required | | `AddPaymentInfo` | `add_payment_info` | `payment_type`, `value`, `currency` | Recommended event | | `Purchase` | `purchase` | `transaction_id`, `value`, `tax`, `shipping`, `items` | All fields required | | `Search` | `search` | `search_term` | `search_term` required | | `Lead` | `generate_lead` | `value`, `currency` | Both fields required | | `SignUp` | `sign_up` | `method` | `method` recommended | | `Subscribe` | `subscribe` | `value`, `currency` | Recommended event | Every event includes user data parameters (`email`, `phone`, `client_id`) when available. AppLovin click IDs (`aleid`) captured by the Upstack Pixel are included for deterministic matching. User matching requires at least one identifier: `aleid`, `axwrt`, `client_id`, `email`, `phone`, or `user_id`. ## FAQ <AccordionGroup> <Accordion title="How do I know events are reaching AppLovin?"> Open the AppLovin Axon Dashboard, navigate to your pixel's Events section, and check for recent events. Server-side events appear within 5–10 minutes of storefront activity. Upstack also surfaces delivery status inside the destination settings. </Accordion> <Accordion title="Will I see duplicate conversions if I run both the Axon Pixel and the Conversions API?"> No — as long as the Pixel ID in Upstack matches the Pixel ID firing in your storefront's Axon browser Pixel. Upstack sends a shared `dedupe_id` on every server-side event, and AppLovin's deduplication logic matches events by `dedupe_id` and keeps only one. </Accordion> <Accordion title="What if my event match rate is low?"> AppLovin's match rate depends on how much identity data each event carries. Common causes of low match quality: * **Missing `aleid`** — AppLovin ads should link directly to your storefront so the click ID lands in the URL and is captured by the Upstack Pixel. * **Anonymous visitors** — events from visitors without email or phone have fewer keys to match against. Match rates improve as more identified customers convert. * **Missing checkout fields** — make sure your Shopify checkout collects email and phone; both are strong server-side match keys. </Accordion> <Accordion title="What permissions does the Conversions API token need?"> The AppLovin Conversions API token is generated from your Axon Dashboard under Account → General → Keys. Upstack only needs permission to send events — no management or spending permissions are required. </Accordion> <Accordion title="Why are my events returning HTTP 400?"> A 400 response means the batch was rejected. AppLovin drops the **entire batch** if any single event is invalid. Common causes: * **Missing `dedupe_id`** — this field is REQUIRED on every server-side event * **Missing user identifier** — at least one of `aleid`, `axwrt`, `client_id`, `email`, `phone`, or `user_id` must be provided * **Invalid field format** — check that `event_time` is in milliseconds, `currency` is ISO 4217, etc. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="Events not appearing in AppLovin Dashboard"> If events aren't appearing after 10 minutes of confirmed store traffic, check the basics first. **Steps to fix:** 1. Go to **Integrations → Destinations → AppLovin** 2. Verify the **Pixel ID** and **Access Token** are correct (no extra spaces or truncated characters) 3. Confirm the destination status is Active (green) 4. If the token was revoked or expired, generate a new one in the Axon Dashboard and update the destination </Accordion> <Accordion title="Batch failures (HTTP 400)"> AppLovin's batch API drops the entire batch if any single event is invalid. **Steps to fix:** 1. Check CloudWatch logs for the specific validation error message 2. Verify all events include a `dedupe_id` (REQUIRED) 3. Verify all events include at least one user identifier 4. Check for malformed field values (timestamps, currencies, item arrays) 5. If one event type consistently fails, review its field mapping </Accordion> <Accordion title="Invalid API key (HTTP 401)"> The Conversions API key was rejected. **Steps to fix:** 1. Log into the AppLovin Dashboard 2. Navigate to Account → General → Keys 3. Generate a new Conversions API key 4. Update the key in your Upstack destination settings 5. Wait 5 minutes for the new key to propagate </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond AppLovin-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack matches anonymous visitors to known customers for higher match rates. </Card> <Card title="Meta CAPI destination" icon="meta" href="/destinations/meta-capi"> Set up Meta's Conversions API as another server-side destination alongside AppLovin. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Attentive Source: https://docs.upstackdata.com/destinations/attentive Forward identity-resolved customer events and profiles to Attentive to power SMS marketing automation, abandoned cart recovery, and personalized text messaging campaigns. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> Attentive is connected through **Upstack Flows**, the product that handles event delivery to marketing automation platforms. The key value: Upstack identifies visitors that Shopify and Attentive's native integrations miss — turning anonymous browse and cart abandonment sessions into actionable SMS triggers with phone numbers and emails attached. This means more abandoned cart SMS flows fire, more browse abandonment messages send, and you recover revenue through personalized text messaging. ## How It Works When a visitor takes an action on your store, Upstack: 1. Captures the event through the Upstack Pixel and matches it to a known visitor profile using Upstack's identity resolution. 2. If the visitor is identified (email available), enriches the event with the contact's email and any other known properties. 3. Sends the event to Attentive using your API key as a custom event that can trigger SMS journeys. 4. Attentive matches the email to existing subscribers and triggers the appropriate SMS flows. The result: abandoned cart and browse abandonment SMS journeys fire for visitors that Shopify's native tracking misses. ## Event Mapping | Upstack Event | Attentive Event | Key Properties | Notes | | ------------------ | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | `PageView` | `Page Viewed - Upstackified` | `productId`, `productUrl`, `name` | Tracks page visits with product context | | `ViewContent` | `Product Viewed - Upstackified` | `productId`, `productVariantId`, `productImage`, `productUrl`, `name`, `price`, `currency` | Powers browse abandonment SMS flows | | `AddToCart` | `Product Added to Cart - Upstackified` | `productId`, `productVariantId`, `productImage`, `productUrl`, `name`, `price`, `currency`, `quantity` | Powers abandoned cart SMS flows | | `InitiateCheckout` | `Checkout Started - Upstackified` | `productId`, `productUrl`, `name`, `price`, `currency`, `quantity` | Powers checkout abandonment SMS flows | | `AddShippingInfo` | `Added Shipping Info - Upstackified` | `productId`, `productUrl`, `name`, `price`, `currency` | Tracks checkout progress | | `AddPaymentInfo` | `Added Payment Info - Upstackified` | `productId`, `productUrl`, `name`, `price`, `currency` | Tracks payment step | | `Purchase` | `Product Purchased - Upstackified` | `productId`, `productVariantId`, `productImage`, `productUrl`, `name`, `price`, `currency`, `quantity`, `brand`, `tags` | Powers post-purchase SMS and win-back flows | Upstack sends events as custom events to Attentive's API. The `- Upstackified` suffix distinguishes Upstack-enriched events from native Attentive tracking, allowing you to run parallel journeys or A/B test performance. ## Set Up Attentive ### Prerequisites * An active Attentive account with API access * An Attentive API key with permission to create custom events ### Step 1: Generate Your Attentive API Key 1. Log in to your Attentive dashboard 2. Navigate to **Settings** → **API Keys** 3. Click **Create API Key** 4. Give it a descriptive name like "Upstack Data Integration" 5. Copy the API key — you'll need it in the next step <Warning> Store your API key securely. You won't be able to view it again after creation. </Warning> ### Step 2: Add Attentive Destination in Upstack 1. Open the [Upstack Data Dashboard](https://app.upstackdata.com) 2. Navigate to **Destinations** in the sidebar 3. Click **Add Destination** and select **Attentive** 4. Paste your Attentive API key 5. Click **Save** to activate the destination ### Step 3: Verify Events Are Flowing 1. Trigger a test event on your store (view a product, add to cart) 2. In Attentive, check **Analytics** → **Events** for incoming Upstackified events 3. Verify the event contains the expected properties (product info, user email) ## Use Cases ### Abandoned Cart SMS Recovery When a visitor adds items to their cart and leaves without purchasing: 1. Upstack captures the `AddToCart` event 2. Identity resolution matches the session to a known subscriber 3. Attentive receives `Product Added to Cart - Upstackified` with the subscriber's email 4. Your Attentive abandoned cart journey triggers, sending a personalized SMS with the cart contents ### Browse Abandonment SMS When a visitor views products but doesn't add to cart: 1. Upstack captures `ViewContent` events 2. Identity resolution identifies the visitor 3. Attentive receives `Product Viewed - Upstackified` 4. Your browse abandonment journey sends a follow-up SMS featuring the viewed products ### Post-Purchase SMS Flows When a customer completes a purchase: 1. Upstack captures the `Purchase` event with full order details 2. Attentive receives `Product Purchased - Upstackified` 3. Post-purchase journeys trigger — order confirmation, shipping updates, review requests, or cross-sell recommendations ## FAQ <AccordionGroup> <Accordion title="How is this different from Attentive's native Shopify integration?"> Attentive's native Shopify integration only sees visitors that Shopify has identified — typically logged-in customers or shoppers who have entered contact information. Upstack's identity resolution matches anonymous sessions to known subscriber profiles using cookies, click IDs, and cross-session behavioral data, then sends those events to Attentive with the contact's email attached. This lets your SMS journeys fire for many more visitors. </Accordion> <Accordion title="Will I get duplicate events if I keep Attentive's native Shopify integration?"> Upstack events use the `- Upstackified` suffix to distinguish them from native Attentive events. You can run both integrations in parallel and build separate journeys that trigger on Upstackified events. Alternatively, disable overlapping events in Attentive's native integration to avoid duplicates. </Accordion> <Accordion title="What permissions does the Attentive API key need?"> The Attentive API key must have permission to create custom events. Avoid using a key with excessive permissions — Upstack only needs to send event data, not manage subscribers or campaigns. </Accordion> <Accordion title="How long does it take for events to appear in Attentive?"> Once the destination is active, events typically appear in Attentive within a few minutes. You can verify by triggering a test action on your store and checking Attentive's event analytics. </Accordion> <Accordion title="Does Upstack create new subscribers in Attentive?"> No. Upstack sends events to Attentive, which then matches them to existing subscribers by email. Attentive will only trigger journeys for visitors who are already subscribed to your SMS list. This ensures compliance with SMS opt-in requirements. </Accordion> <Accordion title="What happens if no email is found for a visitor?"> Events without an identified email are skipped. Upstack only sends events to Attentive when identity resolution has successfully matched the visitor to a known profile with an email address. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="Events not appearing in Attentive"> If events are showing in the Upstack Live Event Stream but not arriving in Attentive: **Steps to fix:** 1. Confirm the Attentive destination shows **Active** (green) in the Upstack dashboard 2. Verify your API key has the required permissions for custom events 3. Check that the visitor was identified — events without email are skipped 4. In Attentive, check **Analytics → Events** and search for events containing "Upstackified" 5. If the destination status is red, disconnect and reconnect with a fresh API key </Accordion> <Accordion title="SMS journeys not triggering"> If events are arriving in Attentive but journeys aren't firing: **Steps to fix:** 1. Verify the journey is configured to trigger on Upstackified events (e.g., `Product Added to Cart - Upstackified`) 2. Check that the subscriber exists in Attentive and is opted in to SMS 3. Review journey conditions — the subscriber may be excluded by filters or suppression rules 4. Check journey analytics for any errors or blocked sends </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond Attentive-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Data Enrichment" icon="magnifying-glass-plus" href="/concepts/data-enrichment"> How Upstack Enrichment improves visitor identification — the foundation of Flows recovery. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack ID connects anonymous sessions to known customers with email addresses. </Card> <Card title="Klaviyo Destination" icon="envelope" href="/destinations/klaviyo"> Sync events and contacts to Klaviyo using the same Upstack Flows pipeline. </Card> <Card title="Events Not Reaching Destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Microsoft Advertising Conversions API Source: https://docs.upstackdata.com/destinations/bing Send conversion events to Microsoft Advertising (Bing Ads) via the Conversions API for ad campaign optimization, audience building, and attribution — powered by Upstack Signal. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does Microsoft Advertising's Conversions API (CAPI) is the server-side counterpart to the Universal Event Tracking (UET) Tag. Upstack Signal forwards storefront events — page views, product views, add-to-carts, and purchases — directly to Microsoft's servers, bypassing browser restrictions like ad blockers, ITP, and cookie limits. Server-side delivery gives Microsoft's algorithm a fuller picture of the conversions your ads actually drove, which improves campaign optimization, audience modeling, and attribution accuracy. Match rates from server-side events are consistently higher than browser-only tracking because each event carries hashed customer data and the `msclkid` click identifier when available. <Note> Microsoft's Conversions API is currently in **pilot program**. Contact your Microsoft Advertising account manager to enroll before enabling server-side tracking in Upstack. </Note> ## How it works Upstack runs as a dual-tracking layer alongside the Microsoft UET Tag. The Upstack Pixel captures events in the browser and forwards each event to Upstack's edge infrastructure, where it is hashed, enriched with identity and click-ID data, and sent to the Microsoft Conversions API as a server-side event with a shared `eventId`. Microsoft deduplicates server events against matching browser UET Tag events using that `eventId`, so you do not double-count conversions as long as both sources use the same UET Tag ID. PII (`email`, `phone`) is hashed with SHA-256 before delivery, as required by the Conversions API. <Warning> Unlike Meta and Google, Microsoft **does not support address-level enhanced matching**. Only email and phone are accepted for identity matching. </Warning> ## Setup guides <CardGroup> <Card title="Onboarding guide" icon="route" href="/guides/microsoft-ads/complete-how-to-guide-for-onboarding-microsoft-ads"> End-to-end walkthrough for connecting Microsoft Advertising to Upstack Data. </Card> <Card title="Configure destination" icon="sliders" href="/guides/microsoft-ads/how-to-configure-microsoft-ads-destination"> Configure the Microsoft Advertising destination inside Upstack Data. </Card> <Card title="Find UET Tag ID" icon="magnifying-glass" href="/guides/microsoft-ads/how-to-find-uet-tag-id"> Locate your UET Tag ID in Microsoft Advertising. </Card> <Card title="Create Event Goals" icon="bullseye" href="/guides/microsoft-ads/how-to-create-event-goals"> Create Event Goals to track specific conversion types. </Card> <Card title="Enable CAPI" icon="server" href="/guides/microsoft-ads/how-to-enable-conversions-api"> Enroll in the CAPI pilot and generate your auth token. </Card> <Card title="Enable click ID tracking" icon="link" href="/guides/microsoft-ads/how-to-enable-msclkid-tracking"> Ensure msclkid is captured and stored for attribution. </Card> </CardGroup> ## Event mapping Upstack maps storefront events to Microsoft Advertising events automatically: | Upstack event | Microsoft event | Key match data | | ------------------ | ---------------- | ----------------------------------------------- | | `PageView` | `pageLoad` | URL, referrer, user agent | | `ViewContent` | `view_item` | `itemIds`, `value`, `currency` | | `AddToCart` | `add_to_cart` | `itemIds`, `value`, `currency` | | `InitiateCheckout` | `begin_checkout` | `value`, `currency` | | `Purchase` | `purchase` | `value`, `currency`, `transactionId`, `itemIds` | | `Lead` | `lead` | `email`, `phone` | | `Search` | `search` | `searchTerm` | | `SignUp` | `sign_up` | `email` | <Note> Microsoft uses **free-form event names** rather than predefined standard events. Event matching is done via Event Goals configured in the Microsoft Advertising UI. </Note> PII is hashed with SHA-256 before it leaves Upstack. Upstack includes every available match key on every event — hashed `email`, hashed `phone`, `msclkid` (Microsoft click ID), `ip_address`, and `user_agent` — to maximize match quality. ## FAQ <AccordionGroup> <Accordion title="What is the difference between UET Tag ID and CAPI Auth Token?"> The **UET Tag ID** identifies your Microsoft Advertising tracking tag — it's the same ID used for browser-side tracking via the UET Tag. The **CAPI Auth Token** is a Bearer token that authenticates server-side API requests. You need both: the Tag ID to identify your account, and the auth token to authorize server-side event submission. </Accordion> <Accordion title="How do I enroll in the CAPI pilot program?"> Contact your Microsoft Advertising account manager or Microsoft Advertising support to request enrollment in the Conversions API pilot. Once enrolled, the auth token option becomes available in your UET Tag settings. </Accordion> <Accordion title="How do I know events are reaching Microsoft?"> Open Microsoft Advertising → **Tools** → **UET Tags** → select your tag → **Tag Status**. Server-side events appear alongside browser events. Upstack also surfaces delivery status inside the destination settings and Event Debugger. </Accordion> <Accordion title="Will I see duplicate conversions if I run both the UET Tag and Conversions API?"> No — as long as the UET Tag ID in Upstack matches your browser UET Tag. Upstack sends a shared `eventId` on every server-side event, and Microsoft's deduplication logic matches events by `eventId` and keeps only one. </Accordion> <Accordion title="Why do events need to be within 7 days?"> Microsoft's Conversions API rejects events older than 7 days. This is stricter than other platforms (Meta allows 7 days, Google allows 90 days). Ensure your event pipeline processes events promptly. </Accordion> <Accordion title="What if my event match rate is low?"> Microsoft's match rate depends on how much identity data each event carries. Common causes of low match quality: * **Missing `msclkid`** — Microsoft ads should link directly to your storefront so the click ID lands in the URL and is captured by the Upstack Pixel. * **Anonymous visitors** — events from visitors without email have fewer keys to match against. Match rates improve as more identified customers convert. * **Missing checkout fields** — make sure your Shopify checkout collects email and phone; they're the strongest server-side match keys. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="Events not appearing in Microsoft Advertising"> **Check these in order:** 1. Verify UET Tag ID is correct in Upstack destination settings 2. Verify CAPI auth token is valid (test in Event Debugger) 3. Check event timestamp is within 7 days 4. Ensure Event Goals are configured in Microsoft Advertising UI </Accordion> <Accordion title="401 Unauthorized errors"> Your CAPI auth token is invalid or expired. Generate a new token in Microsoft Advertising UET Tag settings and update your Upstack destination configuration. </Accordion> <Accordion title="400 Validation errors"> Common validation issues: * `eventType` must be "pageLoad" or "custom" * `eventTime` must be UNIX seconds (not milliseconds) within 7 days * `em` and `ph` must be valid SHA-256 hex strings (64 characters) * `eventSourceUrl` is required for pageLoad events </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Meta Conversions API" icon="meta" href="/destinations/meta-capi"> Server-side tracking for Meta (Facebook/Instagram) ads. </Card> <Card title="Google Ads" icon="google" href="/destinations/google-ads"> Send conversion events to Google Ads for campaign optimization. </Card> <Card title="TikTok Events API" icon="tiktok" href="/destinations/tiktok"> Server-side event delivery to TikTok for attribution. </Card> <Card title="Pinterest Conversions API" icon="pinterest" href="/destinations/pinterest"> Track conversions on Pinterest campaigns with server-side events. </Card> </CardGroup> # Google Analytics 4 (deprecated) Source: https://docs.upstackdata.com/destinations/ga4 The Google Analytics 4 destination has been deprecated and is no longer available for new connections. <Warning> **This destination is deprecated.** The Google Analytics 4 connection is no longer available for new setups. Existing connections will continue to function but are not actively maintained. </Warning> ## Why this was deprecated Upstack's Google Analytics 4 destination has been deprecated. We recommend using GA4's native installation through your Shopify store or Google Tag Manager for analytics tracking. ## Alternatives For server-side conversion tracking, use the platform-specific destinations that drive ad optimization: <CardGroup> <Card title="Meta Conversions API" href="/destinations/meta-capi"> Server-side conversion delivery to Meta Ads. </Card> <Card title="Google Ads" href="/destinations/google-ads"> Server-side conversion delivery to Google Ads. </Card> <Card title="Custom Webhooks" href="/destinations/webhooks"> Build custom integrations with your own analytics pipeline. </Card> <Card title="See all destinations" href="/destinations/overview"> Browse the full list of supported destinations. </Card> </CardGroup> ## Existing connections If you have an existing GA4 destination configured in Upstack, it will continue to operate. Contact [support@upstackdata.com](mailto:support@upstackdata.com) if you need to make changes to your configuration. # Google Ads Source: https://docs.upstackdata.com/destinations/google-ads Forward purchase conversions to Google Ads via server-side API with Enhanced Conversions match keys — improving Smart Bidding signal, attribution accuracy, and Performance Max optimization. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does Google Ads relies on conversion signal to power Smart Bidding, Performance Max, and any campaign that optimizes toward purchases. Upstack Signal forwards every Shopify purchase to your Google Ads account server-side, attached to a dedicated Upstack conversion goal that Google's bidder can optimize against. Server-side delivery means conversions reach Google even when the browser-side gtag is blocked by ad blockers, ITP, or cookie restrictions. Each event carries the original click identifier (`gclid` or `gbraid`/`wbraid`) plus hashed customer data, so Google can match the conversion back to the ad interaction that drove it. The result is more complete conversion data inside Google Ads, sharper Smart Bidding decisions, and reporting that reflects the conversions your campaigns actually produced. ## How it works Google Ads uses a primary/secondary conversion goal architecture. Primary goals drive bidding — Smart Bidding optimizes toward whatever is marked primary. Secondary goals are observation-only: they appear in reports but do not influence the bidder. Upstack creates its own purchase goal in your account so you can compare it side-by-side with your existing goal before promoting it to primary. Upstack hashes customer data — `email`, `phone`, `first_name`, `last_name`, `city`, `state`, `zip`, `country` — with SHA-256 before sending it to Google's API. Google uses these match keys the same way Enhanced Conversions does, so you get equivalent match-rate uplift without enabling Enhanced Conversions on the destination itself. ## Primary vs secondary conversion rollout When Upstack creates a conversion action in your Google Ads account, don't immediately make it your primary goal. Start it as a **secondary** conversion (reporting only) and run it alongside your existing setup for **7–14 days**. Compare purchase counts during this window — Upstack should track equal or higher volume due to enhanced identity matching. Once validated, promote the Upstack conversion to **primary** and demote the old one. This protects your Smart Bidding from disruption during the transition and gives the bidder a clean signal to retrain against. <Tip> Smaller accounts may need longer than 14 days to accumulate enough conversions for Smart Bidding to retrain confidently. Wait until the Upstack goal has logged conversions across a full bidding window before promoting it. </Tip> ## Setup guides <CardGroup> <Card title="Onboarding guide" icon="route" href="/guides/google-ads/complete-how-to-guide-for-onboarding-google-ads-in-upstack-data"> End-to-end walkthrough for connecting Google Ads to Upstack Data. </Card> <Card title="Configure destination" icon="sliders" href="/guides/google-ads/how-to-configure-google-ads-destination-in-upstack-data"> Configure the Google Ads destination inside Upstack Data. </Card> <Card title="Server-side Conversions API setup" icon="server" href="/guides/google-ads/how-to-set-up-google-ads-server-side-conversions-api-in-upstack-data"> Connect Google Ads with OAuth and map events to conversion actions for server-side forwarding. </Card> <Card title="Find conversion ID and label" icon="magnifying-glass" href="/guides/google-ads/how-to-get-your-google-ads-conversion-id-and-label"> Locate the conversion ID and label values Upstack needs. </Card> <Card title="Create purchase goal" icon="bullseye" href="/guides/google-ads/how-to-create-a-new-upstack-data-purchase-goal-in-google-ads"> Create the dedicated Upstack purchase conversion goal in Google Ads. </Card> <Card title="Enable primary goal" icon="circle-check" href="/guides/google-ads/how-to-enable-the-google-ads-upstack-purchase-goal-and-switch-to-primary-optimization-goal"> Promote the Upstack goal to primary so Smart Bidding optimizes against it. </Card> <Card title="Connect Google Ads account (source)" icon="plug" href="/guides/integrations/how-to-connect-your-google-ads-account-in-upstack-data-integrations"> Connect Google Ads as a campaign data source for attribution reporting. </Card> </CardGroup> ## FAQ <AccordionGroup> <Accordion title="What's the difference between primary and secondary conversion goals?"> Primary goals drive Smart Bidding — Google optimizes toward them. Secondary goals are observation-only and appear in reports but do not influence the bidder. New Upstack goals start as secondary so you can compare their volume and quality against your existing goal before switching them to primary. </Accordion> <Accordion title="Why does Upstack create a new conversion goal instead of using my existing one?"> Pointing Upstack at your existing goal would mix Upstack's server-side conversions with whatever source is already firing into it (gtag, Shopify's native tag, GTM), which makes deduplication and quality comparison impossible. A dedicated Upstack goal keeps the data clean and lets you A/B the two goals before promoting Upstack to primary. </Accordion> <Accordion title="How do I migrate from a manual conversion goal to Upstack?"> Run both goals in parallel for at least one full conversion window. Keep your existing goal as primary and Upstack as secondary, confirm the volume and value reconcile, then follow the "Enable primary goal" guide to swap them. After the swap, demote your old goal to secondary so it stops influencing Smart Bidding. </Accordion> <Accordion title="Why doesn't Upstack support Enhanced Conversions directly?"> Upstack already sends the same hashed match keys Enhanced Conversions uses (`email`, `phone`, name, address) on every server-side event, so Google's match-rate logic applies automatically. Enabling Enhanced Conversions on top of the Upstack goal would not add data, and on the wrong goal it can cause duplicate or conflicting match logic. </Accordion> <Accordion title="When should I switch the Upstack goal to primary?"> Once the Upstack goal has logged conversions across a full bidding window (typically 7–14 days) and the volume and value reconcile within a few percent of your existing goal, it is safe to promote Upstack to primary. Smaller accounts may need longer to accumulate enough signal for Smart Bidding to retrain. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Attribution and reporting" icon="chart-line" href="/concepts/attribution-and-reporting"> How Upstack attributes conversions back to the campaigns that drove them. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Klaviyo Source: https://docs.upstackdata.com/destinations/klaviyo Forward identity-resolved customer events and profiles to Klaviyo to power email and SMS automation, recover 30-50% more abandoned cart and checkout revenue with Upstack-enhanced flows. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does Klaviyo is connected through Upstack Flows, the product that handles event delivery to marketing automation platforms. Upstack Flows sends enriched event and profile data to Klaviyo so its flows — abandoned cart, browse abandonment, checkout abandonment, post-purchase — fire on a much larger pool of visitors than Shopify and Klaviyo's native integration can identify on their own. The practical impact is more recovered revenue. Anonymous visitors that Shopify cannot match to an email get matched by Upstack's identity resolution and pushed into Klaviyo as enriched profiles, which means more abandoned cart flows fire, more browse abandonment emails send, and more SMS messages reach the inbox. ## How it works Upstack Flows posts events to Klaviyo's API as **custom metrics** and creates or updates Klaviyo **profiles** with identity data resolved by Upstack ID. When the Upstack Pixel sees an anonymous visitor add to cart, identity resolution attempts to match the session to a known customer — using cookies, click IDs, and cross-session behavioral data — and attaches the email before the event is forwarded to Klaviyo. Klaviyo then has enough information to trigger flows that would otherwise never fire. Profiles synced from Upstack include standard properties (`$first_name`, `$last_name`, `$city`, `$region`) plus custom properties from Upstack's identity resolution, so they are immediately usable for segmentation. ## How Upstack works with Klaviyo Klaviyo already knows many of your customers. Upstack builds on that: anyone who clicks a Klaviyo email gets looked up and resolved through Upstack's identity engine. * **Identity enrichment.** Upstack hooks into Klaviyo to attach resolved identity data to every event it sends. * **Re-identification.** When a returning visitor can't be identified by standard Klaviyo tracking — cookies expired, new device, different browser — Upstack re-identifies them and fires enriched events back to Klaviyo. * **Backup abandonment flows.** These enriched events trigger a second set of abandonment flows that only fire for visitors Klaviyo couldn't identify on its own. * **Result.** Roughly 40% more people flow back through your abandonment sequences. <Info> The Upstack team handles Klaviyo flow setup during onboarding. They'll request access to your Klaviyo account and configure UTM tracking, flow cloning, triggers, and exclusion filters. The setup guides above describe what gets configured so you understand the setup. </Info> ## Best practices <Tip> **Expand to 5-email sequences.** Many brands run 1–2 emails per abandonment flow. Adding more touchpoints captures revenue from slower decision-makers. </Tip> <Tip> **Reduce the re-entry window.** Drop from 14 days to roughly 5 days. If someone comes back and abandons again, put them back in the flow — they're still shopping. </Tip> <Warning> **Disable flows from previous tools.** If you previously used Elevar, Triple Whale, or another tool that created secondary Klaviyo flows, disable those flows before enabling Upstack's. Running both causes duplicate emails. </Warning> ## Setup guides <CardGroup> <Card title="Klaviyo onboarding guide" icon="route" href="/guides/klaviyo/complete-how-to-guide-for-onboarding-klaviyo-in-upstack-data"> End-to-end walkthrough for connecting Klaviyo to Upstack Data. </Card> <Card title="Configure Klaviyo destination" icon="sliders" href="/guides/klaviyo/how-to-configure-klaviyo-destination-in-upstack-data"> Configure the Klaviyo destination inside Upstack Data. </Card> <Card title="Generate Klaviyo API key" icon="key" href="/guides/klaviyo/how-to-generate-klaviyo-api-key-for-upstack-data"> Create a Klaviyo private API key with the right scopes for Upstack. </Card> <Card title="Set up abandonment flows" icon="bell" href="/guides/klaviyo-abandonment-flows/complete-guide-to-setting-up-upstack-abandonment-flows-in-klaviyo"> Build the recommended Klaviyo flows powered by Upstack-enriched events. </Card> <Card title="Clone standard flows" icon="copy" href="/guides/klaviyo-abandonment-flows/how-to-clone-your-standard-flows-in-klaviyo"> Clone Klaviyo's standard flows as a starting point for Upstack-powered versions. </Card> <Card title="Cross-flow exclusion filters" icon="filter" href="/guides/klaviyo-abandonment-flows/how-to-add-cross-flow-exclusion-filters-in-klaviyo"> Prevent the same visitor from receiving overlapping flow messages. </Card> <Card title="Enable UTM tracking" icon="link" href="/guides/klaviyo-abandonment-flows/how-to-enable-utm-tracking-in-klaviyo"> Tag Klaviyo flow links with UTMs so attribution flows back into Upstack. </Card> </CardGroup> ## Event mapping | Upstack event | Klaviyo metric | Key properties | Notes | | ------------------ | ------------------ | ------------------------------------------------------------ | --------------------------------------- | | `ViewContent` | `Viewed Product` | `ProductName`, `ProductID`, `Price`, `ImageURL` | Powers browse abandonment flows | | `AddToCart` | `Added to Cart` | `ProductName`, `ProductID`, `Price`, `Quantity`, `CartValue` | Powers abandoned cart flows | | `InitiateCheckout` | `Started Checkout` | `CartValue`, `ItemCount`, `CheckoutURL` | Powers checkout abandonment flows | | `Purchase` | `Placed Order` | `OrderID`, `Revenue`, `Items`, `DiscountCodes` | Powers post-purchase and win-back flows | Upstack also syncs profile properties (`$first_name`, `$last_name`, `$city`, `$region`) plus custom properties derived from identity resolution. These are available for Klaviyo segmentation immediately after sync. ## FAQ <AccordionGroup> <Accordion title="How does Upstack increase the number of abandoned cart flows that fire?"> Shopify can only fire Klaviyo's abandoned cart flow when it knows the visitor's email — typically because the visitor logged in or reached the email step in checkout. Upstack identifies many more visitors than that by matching anonymous sessions to known customer profiles using cookies, click IDs, and cross-session behavior. When Upstack identifies an anonymous cart with an email, it forwards an enriched `Added to Cart` event to Klaviyo, which lets the abandoned cart flow fire on visitors that Shopify could not identify. </Accordion> <Accordion title="Will I see duplicate events if Klaviyo's native Shopify integration is also active?"> You can. The recommended approach is to disable the Klaviyo metrics in Shopify's native integration that overlap with the events Upstack is forwarding (`Viewed Product`, `Added to Cart`, `Started Checkout`, `Placed Order`). Keep the native integration enabled for any events Upstack is not handling. </Accordion> <Accordion title="What permissions does the Klaviyo API key need?"> Upstack only needs three scopes on the private API key: `Events: Write`, `Profiles: Write`, and `Lists: Write`. Avoid using a full-access key — least-privilege scopes keep the integration safe. The setup guide above walks through generating the key with the correct scopes. </Accordion> <Accordion title="Are new profiles created in Klaviyo, or only existing ones updated?"> Both, by default. When Upstack identifies a visitor with an email that does not yet exist in Klaviyo, it creates a new Klaviyo profile. When the email already exists, Upstack enriches the existing profile with new properties and event history. You can disable either behavior in the destination settings. </Accordion> <Accordion title="How do I know events are arriving in Klaviyo?"> In Klaviyo, open **Analytics → Metrics**. Upstack-forwarded events appear as custom metrics (for example, `Added to Cart` from Upstack) and start populating within a few minutes of storefront activity. To trace a specific visitor, find the profile in Klaviyo and check the **Activity Feed**. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="Upstack events not appearing in Klaviyo"> If events are showing in the Upstack Live Event Stream but not arriving in Klaviyo: **Steps to fix:** 1. Confirm the Klaviyo destination shows **Active** (green) in the Upstack dashboard 2. Verify your Private API key has the required scopes (`Events: Write`, `Profiles: Write`, `Lists: Write`) — read-only keys cannot receive events 3. In Klaviyo, go to **Analytics → Metrics** and search for events containing "Upstackified" — they may be arriving under a different name than expected 4. If the destination status is red, disconnect and reconnect with a fresh API key </Accordion> <Accordion title="Duplicate abandonment emails"> Customers receiving emails from both your standard flows and Upstack flows means mutual exclusion filters are missing or misconfigured. **Steps to fix:** 1. Open both the standard and Upstack versions of the flow in Klaviyo 2. Verify each flow has a cross-flow exclusion filter: "Has received email 0 times in last 7 days where Flow = \[other flow name]" 3. If filters are in place but duplicates persist, check that the flow names in the filters match exactly (including the " - Upstack Data" suffix) 4. Disable flows from previous tools (Elevar, Triple Whale) if they are still active </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond Klaviyo-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Data enrichment" icon="magnifying-glass-plus" href="/concepts/data-enrichment"> How Upstack Enrichment improves visitor identification — the foundation of Flows recovery. </Card> <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack ID connects anonymous sessions to known customers with email addresses. </Card> <Card title="Destinations overview" icon="arrow-right-from-bracket" href="/destinations/overview"> How Upstack Signal and Upstack Flows power different types of destinations. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # LinkedIn Conversions API Source: https://docs.upstackdata.com/destinations/linkedin Send conversion events to LinkedIn's Conversions API for ad campaign optimization, audience building, and attribution — powered by Upstack Signal. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does LinkedIn's Conversions API is the server-side counterpart to the LinkedIn Insight Tag. Upstack Signal forwards storefront events — page views, product views, add-to-carts, and purchases — directly to LinkedIn's servers, bypassing browser restrictions like ad blockers, ITP, and cookie limits. Server-side delivery gives LinkedIn's algorithm a fuller picture of the conversions your ads actually drove, which improves campaign optimization, audience modeling, and attribution accuracy. Match rates from server-side events are consistently higher than browser-only tracking because each event carries hashed customer data and the `li_fat_id` click identifier when available. <Note> Unlike Meta and TikTok, LinkedIn uses **Conversion Rule IDs** to track specific conversion types. You'll need to create conversion rules in Campaign Manager and map them to event types in Upstack. </Note> ## How it works Upstack runs as a dual-tracking layer alongside the LinkedIn Insight Tag. The Upstack Pixel captures events in the browser and forwards each event to Upstack's edge infrastructure, where it is hashed, enriched with identity and click-ID data, and sent to the LinkedIn Conversions API as a server-side event with a shared `eventId`. Upstack authenticates with LinkedIn using a **Direct Access Token** that you generate inside Campaign Manager → **Data** → **Signals Manager** → **Conversions API** — no LinkedIn Developer app or OAuth setup required. The token grants the **Manage conversions** permission for the ad accounts you select and lasts until the expiry you choose (we recommend 1 year). See [How to generate a LinkedIn Conversions API token](/guides/linkedin-ads/how-to-generate-linkedin-conversion-api-token). LinkedIn deduplicates server events against matching browser Insight Tag events using that `eventId`, so you do not double-count conversions as long as both sources use the same Partner ID. PII (`email`) is hashed with SHA-256 before delivery, as required by the Conversions API. ## Setup guides <CardGroup> <Card title="Onboarding guide" icon="route" href="/guides/linkedin-ads/complete-how-to-guide-for-onboarding-linkedin-in-upstack-data"> End-to-end walkthrough for connecting LinkedIn to Upstack Data. </Card> <Card title="Configure destination" icon="sliders" href="/guides/linkedin-ads/how-to-configure-linkedin-destination-in-upstack-data"> Configure the LinkedIn destination inside Upstack Data. </Card> <Card title="Find Partner ID" icon="magnifying-glass" href="/guides/linkedin-ads/how-to-find-linkedin-partner-id"> Locate your LinkedIn Partner ID in Campaign Manager. </Card> <Card title="Create Conversion Rules" icon="bullseye" href="/guides/linkedin-ads/how-to-create-linkedin-conversion-rules"> Create conversion rules for tracking specific event types. </Card> <Card title="Generate API token" icon="key" href="/guides/linkedin-ads/how-to-generate-linkedin-conversion-api-token"> Generate the Conversions API access token Upstack uses to send events. </Card> <Card title="Enable click ID tracking" icon="link" href="/guides/linkedin-ads/how-to-enable-linkedin-click-id-tracking"> Enable enhanced conversion tracking for `li_fat_id` click IDs. </Card> </CardGroup> ## Event mapping Upstack maps storefront events to LinkedIn standard events automatically: | Upstack event | LinkedIn event | Key match data | | ---------------------- | ----------------- | ---------------------------------------------- | | `PageView` | (via Insight Tag) | URL, referrer, user agent | | `ViewContent` | `VIEW_CONTENT` | `content_ids`, `value`, `currency` | | `AddToCart` | `ADD_TO_CART` | `content_ids`, `value`, `currency` | | `InitiateCheckout` | `START_CHECKOUT` | `value`, `currency`, `num_items` | | `Purchase` | `PURCHASE` | `value`, `currency`, `order_id`, `content_ids` | | `Lead` | `LEAD` | `email`, `phone` | | `CompleteRegistration` | `SIGN_UP` | `email` | PII is hashed with SHA-256 before it leaves Upstack. Upstack includes every available match key on every event — hashed `email`, `li_fat_id` (LinkedIn click ID), `ip_address`, and `user_agent` — to maximize match quality. ## FAQ <AccordionGroup> <Accordion title="What is the difference between Partner ID and Conversion Rule ID?"> The **Partner ID** identifies your LinkedIn ad account's Insight Tag — it's the same ID used for browser-side tracking. The **Conversion Rule ID** identifies a specific conversion action you want to track (e.g., Purchase, Lead, Sign Up). You'll have one Partner ID but multiple Conversion Rule IDs, one for each event type. </Accordion> <Accordion title="How do I get my API Access Token?"> Generate a **Direct Access Token** in Campaign Manager → **Data** → **Signals Manager** → **Conversions API**, then paste it into the **API Access Token** field of your Upstack LinkedIn destination. See the step-by-step [How to generate a LinkedIn Conversions API token](/guides/linkedin-ads/how-to-generate-linkedin-conversion-api-token) guide. </Accordion> <Accordion title="How long does the token last?"> Direct Access Tokens expire based on the duration you choose when generating them. We recommend setting the expiry to **1 year** to minimize rotation. When a token expires, the destination turns Unhealthy and events return a `401` error — generate a new token with the same settings and update the destination. </Accordion> <Accordion title="What permissions does the token need?"> The token needs the **Manage conversions** permission and access to the ad account that owns your Conversion Rules. Without this permission, events return a `403` error. </Accordion> <Accordion title="How do I know events are reaching LinkedIn?"> Open LinkedIn Campaign Manager → **Data** → **Signals Manager** → **Signal Diagnostics**. Server-side events appear with status "Received" and show match quality metrics. Upstack also surfaces delivery status inside the destination settings. </Accordion> <Accordion title="Will I see duplicate conversions if I run both the Insight Tag and Conversions API?"> No — as long as the Partner ID in Upstack matches the Partner ID in your Insight Tag. Upstack sends a shared `eventId` on every server-side event, and LinkedIn's deduplication logic matches events by `eventId` and keeps only one. </Accordion> <Accordion title="Why do I need separate Conversion Rules for browser and server events?"> LinkedIn's deduplication works by matching `eventId` across browser and server events **within the same Conversion Rule**. If you use the same Conversion Rule for both sources, deduplication works automatically. However, some merchants prefer separate rules for A/B testing or validation — in that case, browser events go to one rule and server events to another. </Accordion> <Accordion title="What if my event match rate is low?"> LinkedIn's match rate depends on how much identity data each event carries. Common causes of low match quality: * **Missing `li_fat_id`** — LinkedIn ads should link directly to your storefront so the click ID lands in the URL and is captured by the Upstack Pixel. * **Anonymous visitors** — events from visitors without email have fewer keys to match against. Match rates improve as more identified customers convert. * **Missing checkout fields** — make sure your Shopify checkout collects email; it's the strongest server-side match key for LinkedIn. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="Events not appearing in LinkedIn Signal Diagnostics"> If events aren't appearing after 10 minutes of confirmed store traffic, check the basics first. **Steps to fix:** 1. Go to **Integrations → Destinations → LinkedIn** 2. Verify the **Partner ID**, **API Access Token**, and **Conversion Rule IDs** are correct (no extra spaces or truncated characters) 3. Confirm the destination status is Active (green) 4. If the token was revoked or expired, generate a new one in Campaign Manager and update the destination 5. Verify conversion rules are associated with at least one active campaign </Accordion> <Accordion title="API errors (401, 403)"> | Error Code | Meaning | Solution | | ---------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | 401 | Invalid or expired token | Generate a new Direct Access Token in Campaign Manager → Data → Signals Manager → Conversions API | | 403 | Permission denied | Ensure token has "Manage conversions" permission and access to the correct ad account | | 422 | Invalid payload | Verify conversion URN format (`urn:lla:llaPartnerConversion:{id}`), timestamp is within 90 days, and at least one user identifier is present | </Accordion> <Accordion title="Token expired"> Direct Access Tokens expire based on the duration you set during generation (default 1 year). To renew: 1. Go to Campaign Manager → Data → Signals Manager → Conversions API 2. Generate a new token with same settings 3. Update the token in Upstack Data destination settings </Accordion> <Accordion title="Low match quality scores"> LinkedIn's match quality measures how well server events match to LinkedIn users. **Common causes:** * **High anonymous traffic** — Events from visitors who haven't provided contact info have fewer matching parameters. Match quality improves as more identified customers generate events. * **Missing click IDs** — Enable enhanced conversion tracking in Insight Tag settings to capture `li_fat_id` from ad clicks. * **Incorrect Partner ID** — If the Partner ID doesn't match the one associated with your ad account, events arrive but can't be matched to campaign data. Match quality typically improves over 1–2 weeks as Upstack's identity resolution builds visitor profiles. </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond LinkedIn-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack matches anonymous visitors to known customers for higher match rates. </Card> <Card title="Meta CAPI destination" icon="meta" href="/destinations/meta-capi"> Set up Meta's Conversions API as another server-side destination alongside LinkedIn. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Loops Source: https://docs.upstackdata.com/destinations/loops Forward identity-resolved customer events to Loops to trigger email automations, transactional emails, and marketing campaigns based on real-time e-commerce activity. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> Loops is connected through **Upstack Flows**, the product that handles event delivery to marketing automation platforms. Upstack identifies visitors that standard tracking misses — turning anonymous browse and cart abandonment sessions into actionable Loops contacts with email addresses attached. This means more automated email workflows fire, more transactional messages reach the right customers, and you recover revenue that would otherwise be invisible. ## How It Works When a visitor takes an action on your store, Upstack: 1. Captures the event through the Upstack Pixel and matches it to a known visitor profile using Upstack's identity resolution. 2. If the visitor is identified (email available), enriches the event with the contact's email and any other known properties. 3. Sends the event to Loops using your Loops API key as a trackable event that can trigger automations. 4. Optionally creates or updates the contact in Loops so it can be segmented and used in campaigns. The result: email automations fire for visitors that standard tracking misses. ## Supported Events | Upstack Event | Loops Event | Key Properties | Use Case | | ------------------ | ------------------ | ------------------------------------------------------------ | -------------------- | | `ViewContent` | `Viewed Product` | `ProductName`, `ProductID`, `Price`, `ImageURL` | Browse abandonment | | `AddToCart` | `Added to Cart` | `ProductName`, `ProductID`, `Price`, `Quantity`, `CartValue` | Abandoned cart | | `InitiateCheckout` | `Started Checkout` | `CartValue`, `ItemCount`, `CheckoutURL` | Checkout abandonment | | `Purchase` | `Placed Order` | `OrderID`, `Revenue`, `Items`, `DiscountCodes` | Post-purchase flows | Upstack also syncs profile properties including name, email, and location data. These are available for Loops segmentation immediately after sync. ## Credentials | Field | Required | Description | | ------- | -------- | ------------------------------------------------------------- | | API Key | Yes | Your Loops API key for authenticating event and contact syncs | <Info> Your Loops API key can be found in your Loops account under **Settings → API**. Generate a key with write access to events and contacts. </Info> ## Set Up Loops <Steps> <Step title="Get your Loops API key"> 1. Log in to your [Loops account](https://loops.so/) 2. Navigate to **Settings → API** 3. Click **Create API Key** if you don't have one 4. Copy the API key — you'll need it in the next step </Step> <Step title="Add Loops as a destination in Upstack"> 1. In the Upstack dashboard, go to **Destinations** 2. Click **Add Destination** and select **Loops** 3. Paste your Loops API key in the **API Key** field 4. Click **Save** to enable the destination </Step> <Step title="Verify events are flowing"> 1. Trigger a test action on your store (view a product, add to cart) 2. In Loops, check **Events** to see incoming events 3. In Upstack, check the Live Event Stream to confirm events show as delivered to Loops </Step> </Steps> ## FAQ <AccordionGroup> <Accordion title="What is Loops?"> Loops is an email marketing and automation platform designed for modern SaaS and e-commerce businesses. It allows you to create automated email sequences triggered by user behavior, send transactional emails, and manage marketing campaigns — all through a simple API-first interface. </Accordion> <Accordion title="How is this different from connecting Loops directly to Shopify?"> Standard Shopify integrations only see visitors that Shopify has identified — typically logged-in customers or shoppers who have entered an email at checkout. Upstack's identity resolution matches anonymous sessions to known customer profiles using cookies, click IDs, and cross-session behavioral data, then sends those events to Loops with the contact's email attached. This lets your automated workflows fire for many more visitors. </Accordion> <Accordion title="What permissions does the Loops API key need?"> The Loops API key must have permission to write events and contacts. When creating your API key in Loops, ensure it has the scopes required to send events and create or update contacts. </Accordion> <Accordion title="How long does it take for events to appear in Loops?"> Once the destination is active, events typically appear in Loops within a few minutes. You can verify by triggering a test action on your store (such as adding a product to cart) and checking the Events section in Loops. </Accordion> <Accordion title="Can I send custom events to Loops?"> Yes. Any event tracked by the Upstack Pixel can be configured to forward to Loops. Contact support if you need to send custom events beyond the standard e-commerce events. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="Events not appearing in Loops"> If events show in the Upstack Live Event Stream but aren't arriving in Loops: **Steps to fix:** 1. Confirm the Loops destination shows **Active** (green) in the Upstack dashboard 2. Verify your API key is valid — try regenerating it in Loops if you're unsure 3. Check the Events section in Loops — events may appear under a different name than expected 4. If the destination status is red, disconnect and reconnect with a fresh API key </Accordion> <Accordion title="Contacts not being created in Loops"> If events are arriving but contacts aren't being created: **Steps to fix:** 1. Ensure the API key has permission to create contacts 2. Verify that Upstack has resolved an email address for the visitor — anonymous events without an email won't create contacts 3. Check if the contact already exists in Loops under a different email or identifier </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond Loops-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Data Enrichment" icon="magnifying-glass-plus" href="/concepts/data-enrichment"> How Upstack Enrichment improves visitor identification — the foundation of Flows recovery. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack ID connects anonymous sessions to known customers with email addresses. </Card> <Card title="Klaviyo Destination" icon="envelope" href="/destinations/klaviyo"> Sync events and contacts to Klaviyo using the same Upstack Flows pipeline. </Card> <Card title="Events Not Reaching Destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Meta Conversions API (CAPI) Source: https://docs.upstackdata.com/destinations/meta-capi Send server-side conversion events to Meta Ads with Upstack Signal — improve Event Match Quality and campaign optimization. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does Meta's Conversions API (CAPI) lets you send conversion events directly from a server to Meta, instead of relying solely on the browser-side Pixel. Upstack Signal forwards every storefront event — page views, product views, add-to-carts, checkouts, and purchases — to your Meta Pixel via CAPI, enriched with hashed customer data and click identifiers. For most Shopify merchants, Meta CAPI is the highest-impact destination you can connect. Events captured server-side reach Meta even when the browser Pixel is blocked by ad blockers, ITP, or cookie restrictions, which means Meta's algorithm sees a fuller picture of the conversions your ads actually drove. The practical result is higher Event Match Quality (EMQ), more accurate ROAS reporting inside Meta Ads Manager, and stronger optimization signal for campaigns that depend on conversion events. ## How it works Upstack Signal runs as a dual-tracking layer. The Upstack Pixel captures events in the browser and forwards each one to Upstack's edge infrastructure, where it is hashed, enriched with identity and attribution data, and then sent to Meta's Conversions API as a server-side event with a shared `event_id`. Meta deduplicates against any matching browser Pixel event using that ID, so you do not double-count. Every event carries the strongest available match keys — hashed `email`, `phone`, `first_name`, `last_name`, `city`, `state`, `zip`, `country`, plus `fbc`, `fbp`, and `external_id` — so Meta can attribute the conversion to the right user and ad interaction. ## Setup guides <CardGroup> <Card title="Onboarding guide" icon="route" href="/guides/facebook-ads/complete-how-to-guide-for-onboarding-facebook-meta-in-upstack-data"> End-to-end walkthrough for connecting Meta to Upstack Data. </Card> <Card title="Configure pixel destination" icon="sliders" href="/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data"> Configure the Meta Pixel destination inside Upstack Data. </Card> <Card title="Find Pixel Dataset ID" icon="magnifying-glass" href="/guides/facebook-ads/how-do-i-find-my-facebook-ads-pixel-dataset-id"> Locate your Meta Pixel Dataset ID in Events Manager. </Card> <Card title="Generate CAPI key" icon="key" href="/guides/facebook-ads/how-to-generate-my-facebook-conversion-api-key"> Generate a Conversions API access token in Meta. </Card> <Card title="Update CAPI key" icon="rotate" href="/guides/facebook-ads/how-to-update-facebook-meta-conversion-api-key"> Rotate or replace your existing CAPI access token. </Card> <Card title="Disable Shopify FB data sharing" icon="ban" href="/guides/facebook-ads/how-to-disable-facebook-and-instagram-data-sharing-in-shopify"> Turn off Shopify's native Facebook integration to prevent duplicate events. </Card> <Card title="Approve custom events" icon="circle-check" href="/guides/facebook-ads/how-to-approve-facebook-meta-custom-events"> Approve Upstack's custom events inside Meta Events Manager. </Card> </CardGroup> ## Event mapping Upstack maps storefront events to Meta standard events automatically: | Upstack event | Meta standard event | Key match data | | ------------------ | ------------------- | -------------------------------------------------- | | `PageView` | `PageView` | URL, referrer, user agent | | `ViewContent` | `ViewContent` | `content_ids`, `content_type`, `value`, `currency` | | `AddToCart` | `AddToCart` | `content_ids`, `value`, `currency` | | `InitiateCheckout` | `InitiateCheckout` | `value`, `currency`, `num_items` | | `Purchase` | `Purchase` | `value`, `currency`, `order_id`, `content_ids` | PII is hashed with SHA-256 before it leaves Upstack. Upstack includes every available match key on every event — `em`, `ph`, `fn`, `ln`, `ct`, `st`, `zp`, `country`, `fbc`, `fbp`, `external_id` — to maximize EMQ. ## FAQ <AccordionGroup> <Accordion title="What is Event Match Quality (EMQ) and why does it matter?"> EMQ is Meta's score (1–10) for how reliably it can match a conversion event back to a Meta user. Higher EMQ means Meta's algorithm has more signal to optimize against, which lowers cost per acquisition and improves ROAS. Server-side delivery via CAPI typically lifts EMQ by 20–35% compared to a browser-only Pixel because the events carry more match keys and are not blocked by browser restrictions. </Accordion> <Accordion title="Why send events through CAPI when I already have the Meta Pixel?"> The browser Pixel is blocked or degraded by ad blockers, Safari ITP, iOS privacy features, and third-party cookie restrictions. CAPI runs server-to-server, so it is not affected by any browser-side limitation. Meta itself recommends running CAPI alongside the Pixel for redundancy and higher data quality. </Accordion> <Accordion title="Will my events be counted twice if I run both the Pixel and CAPI?"> No. Upstack sends a shared `event_id` on every server-side event, and Meta deduplicates against the matching browser Pixel event with the same ID. As long as the Pixel ID in Upstack matches the Pixel ID firing in your storefront, deduplication is automatic. </Accordion> <Accordion title="Do I need to disable Shopify's native Facebook integration?"> Yes — if Shopify is also sending purchase events to the same Meta Pixel, you'll see duplicates that Meta cannot deduplicate (Shopify does not emit a matching `event_id`). Follow the guide above to disable Facebook & Instagram data sharing in Shopify before activating Upstack's Meta destination. </Accordion> <Accordion title="How do I verify CAPI events are arriving in Meta?"> Open Meta Events Manager, select your Pixel, and check the **Overview** and **Test Events** tabs. Server-side events show up with a "Server" badge. Upstack also surfaces delivery status and EMQ inside the destination settings in your dashboard. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack matches anonymous visitors to known customers for higher match rates. </Card> <Card title="TikTok Events API" icon="tiktok" href="/destinations/tiktok"> Set up TikTok's Events API as another server-side destination alongside Meta. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # NewsBreak Ads Source: https://docs.upstackdata.com/destinations/newsbreak Send conversion events to NewsBreak's postback API for native advertising campaign optimization — powered by Upstack Signal. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does NewsBreak's Server-to-Server Postback API is the conversion tracking method for their native advertising platform. Unlike other ad platforms, NewsBreak uses a simple GET-based postback rather than a full browser pixel SDK. Upstack Signal forwards purchases, add-to-carts, and other conversion events directly to NewsBreak's servers, bypassing browser ad blockers and giving NewsBreak's algorithm stronger signal for campaign optimization. Server-side delivery means conversions reach NewsBreak even when browser tracking is blocked by ad blockers, ITP, or cookie restrictions. Each event carries the click identifier (`nbclid`) captured from ad clicks so NewsBreak can match the conversion back to the ad interaction that drove it. <Warning> **Important limitation:** Unlike Meta, TikTok, Google, Reddit, and other ad platforms, NewsBreak does **NOT** support enhanced matching via hashed email, phone, or other PII. Attribution relies **solely on the click ID (`nbclid`)** captured from ad clicks. Events without a click ID cannot be attributed and are skipped. </Warning> ## How it works Upstack Signal captures and stores the NewsBreak click ID when visitors land from a NewsBreak ad. When a visitor takes an action on your store: 1. Captures the NewsBreak click ID (`nbclid`) when the visitor lands from a NewsBreak ad. 2. Stores the click ID in a first-party cookie for attribution across sessions. 3. On conversion events, sends the event to NewsBreak's postback endpoint with the click ID. 4. Logs the response so you can monitor delivery status from the Upstack dashboard. **Attribution model:** NewsBreak uses last-click attribution based solely on the `nbclid` parameter. Cross-device conversions, cookieless conversions, and conversions from returning visitors whose cookies expired **cannot be attributed** to NewsBreak campaigns. ## Setup guides <CardGroup> <Card title="Onboarding guide" icon="route" href="/guides/newsbreak-ads/complete-how-to-guide-for-onboarding-newsbreak-in-upstack-data"> End-to-end walkthrough for connecting NewsBreak to Upstack Data. </Card> <Card title="Configure destination" icon="sliders" href="/guides/newsbreak-ads/how-to-configure-newsbreak-destination-in-upstack-data"> Configure the NewsBreak destination inside Upstack Data. </Card> <Card title="Find Pixel ID" icon="magnifying-glass" href="/guides/newsbreak-ads/how-to-find-newsbreak-pixel-id"> Locate your NewsBreak Pixel ID in the Ad Manager Event Management. </Card> <Card title="Configure click ID tracking" icon="link" href="/guides/newsbreak-ads/how-to-configure-newsbreak-click-id-tracking"> Add the click ID parameter to your campaign URL suffix. </Card> </CardGroup> ## Event mapping Upstack maps storefront events to NewsBreak postback event types automatically: | Upstack event | NewsBreak event | Key parameters | Notes | | ------------------ | ------------------- | -------------------------------- | ------------------------ | | `Purchase` | `complete_payment` | `callback`, `nb_value` (revenue) | Primary conversion event | | `NC Purchase` | `complete_payment` | `callback`, `nb_value` (revenue) | New customer purchase | | `AddToCart` | `add_to_cart` | `callback` (click ID) | Cart additions | | `InitiateCheckout` | `initiate_checkout` | `callback` (click ID) | Checkout started | | `Lead` | `submit_form` | `callback` (click ID) | Form submissions | | `SignUp` | `subscribe` | `callback` (click ID) | Account registration | | `Subscribe` | `subscribe` | `callback` (click ID) | Newsletter signup | | `AddToWishlist` | `add_to_wishlist` | `callback` (click ID) | Wishlist additions | Every event includes the NewsBreak click ID (`nbclid`) when available. **Events without a click ID are skipped** because NewsBreak cannot attribute them to any campaign. <Note> NewsBreak only supports conversion events. Page views, content views, and browsing events are not supported. Revenue is only sent for purchase events via the `nb_value` parameter. </Note> ## FAQ <AccordionGroup> <Accordion title="Why is there no browser pixel for NewsBreak?"> NewsBreak does not provide a public JavaScript SDK like Meta (`fbq`) or TikTok (`ttq`). Their recommended integration method is server-side postbacks using the click ID captured from your landing page URL. Upstack handles all server-side delivery automatically once you configure the destination. </Accordion> <Accordion title="What if a visitor doesn't have a NewsBreak click ID?"> Without a click ID, NewsBreak cannot attribute the conversion to an ad click. This typically happens when visitors arrive through organic traffic or when the `nbclid` parameter is stripped from URLs (e.g., by link shorteners or redirects). Upstack will skip sending events for visitors without a captured click ID to avoid errors. </Accordion> <Accordion title="How do I verify events are arriving in NewsBreak?"> Open NewsBreak Ad Manager, navigate to **Tools → Event Management**, and check that events are appearing. Server-side events should start appearing within 5–10 minutes of storefront activity. Note that test events won't show up in the dashboard — conversions only register when a real user clicks on your ad. </Accordion> <Accordion title="Why are my attribution rates lower than other platforms?"> NewsBreak does not support enhanced matching with hashed PII (email, phone, IP, user-agent). Attribution relies **solely** on the click ID (`nbclid`). If a visitor clears cookies, uses a different device, or the click ID expires, the conversion cannot be attributed. This is a platform limitation, not an Upstack issue. </Accordion> <Accordion title="Does NewsBreak support event deduplication?"> NewsBreak does not have built-in event deduplication like Meta or TikTok. Instead, configure your events in NewsBreak's Event Management with the appropriate counting mode: "Every" (all conversions) or "Once" (unique users only). Since Upstack is server-side only, there is no browser pixel that could fire duplicate events. </Accordion> <Accordion title="What are NewsBreak's rate limits?"> NewsBreak enforces rate limits based on your account tier: | Tier | QPS | QPM | QPD | | -------- | --- | ----- | --------- | | Basic | 10 | 600 | 864,000 | | Advanced | 20 | 1,200 | 1,728,000 | | Premium | 30 | 1,800 | 2,592,000 | Upstack automatically handles rate limiting with exponential backoff and retries failed events. For high-volume accounts, contact NewsBreak about upgrading your tier. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="No conversions appearing in NewsBreak dashboard"> If events aren't appearing after confirmed store traffic: **Steps to fix:** 1. Verify your campaign URL suffix includes `nbclid=__CALLBACK_PARAM__` 2. Confirm the Upstack destination shows **Active** (green) 3. Check that the `_nbclid` cookie is being set on your storefront (inspect browser cookies) 4. Test with a real ad click — test traffic without `nbclid` in the URL won't generate events 5. Wait up to 24 hours — NewsBreak may take time to process and display events </Accordion> <Accordion title="No conversions attributed to ads"> Conversions are showing in NewsBreak but not attributed to campaigns: **Steps to fix:** 1. Verify your NewsBreak ad URLs use the correct macro: `?nbclid=__CALLBACK_PARAM__` 2. Confirm the event type in Upstack matches the event configured in NewsBreak Event Management 3. Check that you're not using link shorteners or redirects that strip URL parameters 4. Verify the attribution window in NewsBreak hasn't expired for old click IDs </Accordion> <Accordion title="Low attribution rate compared to other platforms"> This is expected due to NewsBreak's click-ID-only attribution model. **To maximize attribution:** * Ensure all campaigns include `nbclid=__CALLBACK_PARAM__` in the URL suffix * Verify the Upstack Pixel is loading on all pages to capture click IDs * Check that first-party cookies are not being blocked by browser settings * Note that cross-device and returning-visitor conversions will not be attributed </Accordion> <Accordion title="Rate limit errors (code 4034)"> If you see rate limit errors in Upstack logs: **Steps to fix:** 1. Upstack automatically retries with exponential backoff — most rate limit errors resolve on their own 2. If errors persist during peak traffic, consider spreading campaigns across time zones 3. Contact NewsBreak support ([adsupport@newsbreak.com](mailto:adsupport@newsbreak.com)) about upgrading to Advanced or Premium tier for higher limits </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond NewsBreak-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack matches anonymous visitors to known customers for higher match rates. </Card> <Card title="Outbrain destination" icon="rectangle-ad" href="/destinations/outbrain"> Set up Outbrain — another native advertising platform with click-ID-only attribution. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Omnisend Source: https://docs.upstackdata.com/destinations/omnisend Forward identity-resolved customer events and profiles to Omnisend to power email and SMS automation, abandoned cart recovery flows, and workflow triggers via the Omnisend API. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> Omnisend is connected through **Upstack Flows**, the product that handles event delivery to marketing automation platforms. The key value: Upstack identifies visitors that Shopify and Omnisend's native integration miss — turning anonymous browse and cart abandonment sessions into actionable Omnisend contacts with email addresses attached. This means more abandoned cart workflows fire, more browse abandonment messages send, and you recover revenue that would otherwise be invisible. ## How It Works When a visitor takes an action on your store, Upstack: 1. Captures the event through the Upstack Pixel and matches it to a known visitor profile using Upstack's identity resolution. 2. If the visitor is identified (email available), enriches the event with the contact's email and any other known properties. 3. Sends the event to Omnisend using your Omnisend API key as a trackable activity that can trigger workflows. 4. Optionally creates or updates the contact in Omnisend so it can be segmented and messaged. The result: abandoned cart and browse abandonment workflows fire for visitors that Shopify's native tracking misses. ## Set Up Omnisend Follow the onboarding guide for the full end-to-end setup, or jump to a specific step. <CardGroup> <Card title="Onboarding guide" icon="book" href="/guides/omnisend/complete-how-to-guide-for-onboarding-omnisend-in-upstack-data"> Complete step-by-step walkthrough for connecting Omnisend to Upstack. </Card> <Card title="Configure destination" icon="sliders" href="/guides/omnisend/how-to-configure-omnisend-pixel-destination-in-upstack-data"> Add and configure the Omnisend destination inside the Upstack dashboard. </Card> <Card title="Generate API key" icon="key" href="/guides/omnisend/how-to-generate-your-omnisend-api-key"> Generate the Omnisend API key Upstack uses to sync events and contacts. </Card> </CardGroup> ## FAQ <AccordionGroup> <Accordion title="How is this different from Omnisend's native Shopify integration?"> Omnisend's native Shopify integration only sees visitors that Shopify has identified — typically logged-in customers or shoppers who have entered an email at checkout. Upstack's identity resolution matches anonymous sessions to known customer profiles using cookies, click IDs, and cross-session behavioral data, then sends those events to Omnisend with the contact's email attached. This lets your abandoned cart and browse abandonment workflows fire for many more visitors. </Accordion> <Accordion title="Will I get duplicate events if I keep Omnisend's native Shopify integration?"> Possibly. If both Upstack and Omnisend's native integration send the same event types, Omnisend may record both. The recommended approach is to disable the corresponding events in Omnisend's native integration for any event types Upstack is configured to send, and keep the native integration only for events you're not routing through Upstack. </Accordion> <Accordion title="What permissions does the Omnisend API key need?"> The Omnisend API key must have permission to write events and contacts. Use a key with the minimum scope required — Upstack does not need account management or billing permissions. Step-by-step instructions are in [Generate API key](/guides/omnisend/how-to-generate-your-omnisend-api-key). </Accordion> <Accordion title="How long does it take for events to appear in Omnisend?"> Once the destination is active, events typically appear in Omnisend within 5 minutes. You can verify by triggering a test action on your store (such as adding a product to cart) and checking the contact's activity feed in Omnisend. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Data Enrichment" icon="magnifying-glass-plus" href="/concepts/data-enrichment"> How Upstack Enrichment improves visitor identification — the foundation of Flows recovery. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack ID connects anonymous sessions to known customers with email addresses. </Card> <Card title="Klaviyo Destination" icon="envelope" href="/destinations/klaviyo"> Sync events and contacts to Klaviyo using the same Upstack Flows pipeline. </Card> <Card title="Events Not Reaching Destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Outbrain Amplify Source: https://docs.upstackdata.com/destinations/outbrain Send conversion events to Outbrain's Unified Pixel API for native advertising campaign optimization — powered by Upstack Signal. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does Outbrain's Unified Pixel API is the server-side counterpart to the Outbrain browser pixel. Upstack Signal forwards storefront events — page views, product views, add-to-carts, and purchases — directly to Outbrain's servers for native advertising campaign optimization. Server-side delivery means conversions reach Outbrain even when the browser-side pixel is blocked by ad blockers, ITP, or cookie restrictions. Each event carries the click identifier (`obclid`) captured from ad clicks so Outbrain can match the conversion back to the ad interaction that drove it. <Warning> **Important limitation:** Unlike Meta, TikTok, Google, Reddit, and other ad platforms, Outbrain does **NOT** support enhanced matching via hashed email, phone, or other PII. Attribution relies **solely on the click ID (`obclid`)** captured from ad clicks. Events without a click ID cannot be attributed and are skipped. </Warning> ## How it works Upstack Signal runs as a dual-tracking layer alongside the Outbrain browser pixel. The Upstack Pixel captures events in the browser and forwards each one to Upstack's edge infrastructure, where it is enriched with the Outbrain click ID from cookie storage and sent to Outbrain's Unified Pixel API as a server-side event. Unlike other ad platforms, Outbrain's deduplication relies on the `orderId` field rather than a shared `event_id`. Always include a transaction ID on purchase events to prevent double-counting when running both browser pixel and server-side delivery. **Attribution model:** Outbrain uses last-click attribution based solely on the `obclid` parameter. Cross-device conversions, cookieless conversions, and conversions from returning visitors whose cookies expired **cannot be attributed** to Outbrain campaigns. ## Setup guides <CardGroup> <Card title="Onboarding guide" icon="route" href="/guides/outbrain/complete-how-to-guide-for-onboarding-outbrain-in-upstack-data"> End-to-end walkthrough for connecting Outbrain to Upstack Data. </Card> <Card title="Configure destination" icon="sliders" href="/guides/outbrain/how-to-configure-outbrain-destination-in-upstack-data"> Configure the Outbrain destination inside Upstack Data. </Card> <Card title="Find Marketer ID" icon="magnifying-glass" href="/guides/outbrain/how-to-find-outbrain-marketer-id"> Locate your Outbrain Marketer ID in the Amplify Dashboard. </Card> <Card title="Configure click ID tracking" icon="link" href="/guides/outbrain/how-to-configure-outbrain-click-id-tracking"> Add the click ID parameter to your campaign URL suffix. </Card> </CardGroup> ## Event mapping Upstack maps storefront events to Outbrain events automatically: | Upstack event | Outbrain event | Key parameters | Notes | | ------------- | -------------- | --------------------------------------- | ---------------------------------------- | | `Purchase` | `Conversion` | `orderValue`, `currency`, `orderId` | Primary conversion event | | `Lead` | `Lead` | `orderValue`, `orderId` | Lead form submissions | | `SignUp` | `Sign_Up` | `orderId` | Account registration | | `AddToCart` | `AddToCart` | `productId`, `productValue`, `currency` | Cart additions | | `ViewContent` | `Content_View` | `productId`, `productValue` | Product page views (disabled by default) | | `PageView` | `PAGE_VIEW` | — | Page load (disabled by default) | Every event includes the Outbrain click ID (`obclid`) when available. **Events without a click ID are skipped** because Outbrain cannot attribute them to any campaign. ## Field mapping | Upstack field | Outbrain field | Type | Notes | | -------------------- | -------------- | ------ | --------------------------- | | `data.value` | `orderValue` | number | Transaction amount | | `data.currency` | `currency` | string | ISO 4217 (USD, EUR, GBP) | | `data.transactionId` | `orderId` | string | Unique ID for deduplication | | `item.id` | `productId` | string | Product SKU | | `item.name` | `productName` | string | Product name | | `item.category` | `category` | string | Product category | | `item.quantity` | `quantity` | number | Number of items | ## FAQ <AccordionGroup> <Accordion title="How do I verify events are arriving in Outbrain?"> Open Outbrain Amplify Dashboard, navigate to **Conversions**, and check that events are appearing. Server-side events should start appearing within 5–10 minutes of storefront activity. Note that test events won't show up in the dashboard — conversions only register when a real user clicks on your ad in the Outbrain widget. </Accordion> <Accordion title="Why are my attribution rates lower than other platforms?"> Outbrain does not support enhanced matching with hashed PII (email, phone, IP, user-agent). Attribution relies **solely** on the click ID (`obclid`). If a visitor clears cookies, uses a different device, or the click ID expires (after 30 days), the conversion cannot be attributed. This is a platform limitation, not an Upstack issue. </Accordion> <Accordion title="Will my events be counted twice if I run both the pixel and server-side?"> Outbrain deduplicates based on the `orderId` field. Always include a unique transaction ID on purchase events. If you're sending events from multiple sources (Upstack, GTM, direct pixel), ensure they all use the same `orderId` for the same transaction. </Accordion> <Accordion title="Do event names need to match exactly?"> Yes — event names are **case-sensitive** and must exactly match the conversion name configured in your Outbrain Amplify dashboard. `Purchase` ≠ `purchase` ≠ `PURCHASE`. Verify the exact spelling in Amplify → Conversions before configuring Upstack. </Accordion> <Accordion title="What happens if the click ID is missing?"> Events without an Outbrain click ID are **skipped** and not sent to Outbrain. This is intentional — Outbrain cannot attribute conversions without a click ID, so sending them would inflate your event volume without improving attribution. Ensure your campaign URL suffix includes `obclid={{ob_click_id}}` so the Upstack Pixel can capture click IDs. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="No conversions appearing in Outbrain dashboard"> If events aren't appearing after confirmed store traffic: **Steps to fix:** 1. Verify your campaign URL suffix includes `obclid={{ob_click_id}}` 2. Confirm the Upstack destination shows **Active** (green) 3. Check that the Marketer ID matches your Amplify account 4. Test with a real ad click — test traffic without `obclid` in the URL won't generate events </Accordion> <Accordion title="Invalid Marketer ID error"> The Marketer ID (also called OB\_ADV\_ID or Pixel ID) must be the 32-character hexadecimal string from Amplify. **Steps to fix:** 1. Go to Amplify Dashboard → Settings → Tracking 2. Copy the full Marketer ID (no spaces, no extra characters) 3. Update the destination in Upstack with the correct ID </Accordion> <Accordion title="Low attribution rate compared to other platforms"> This is expected due to Outbrain's click-ID-only attribution model. **To maximize attribution:** * Ensure all campaigns include `obclid={{ob_click_id}}` in the URL suffix * Verify the Upstack Pixel is loading on all pages to capture click IDs * Check that first-party cookies are not being blocked by browser settings * Note that cross-device and returning-visitor conversions will not be attributed </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond Outbrain-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack matches anonymous visitors to known customers for higher match rates. </Card> <Card title="Meta CAPI destination" icon="meta" href="/destinations/meta-capi"> Set up Meta's Conversions API — supports enhanced matching unlike Outbrain. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Destinations Source: https://docs.upstackdata.com/destinations/overview Send conversion events and customer data from Upstack Data to ad platforms, analytics tools, and automation systems. Destinations are integrations that receive data **from** Upstack Data. When a visitor views a product, adds to cart, or completes a purchase, Upstack forwards that event — enriched with identity and attribution data — to the platforms where you need it most. ## Browser-side vs. server-side tracking Most ad platforms support two ways of receiving conversion data: | Method | How it works | Strengths | Limitations | | ------------------------ | ------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------- | | **Browser-side (pixel)** | JavaScript tag fires in the visitor's browser | Easy to set up; real-time | Blocked by ad blockers, ITP, and cookie restrictions; limited data quality | | **Server-side (CAPI)** | Your server sends events directly to the platform's API | Resistant to ad blockers; richer data; higher match rates | Requires server infrastructure and identity resolution | Upstack destinations use **server-side delivery** — events are sent from Upstack's infrastructure directly to each platform's conversion API. This means your data reaches ad networks even when browser pixels are blocked, giving you significantly higher event match rates and more accurate optimization signals. <Tip> Upstack still installs a lightweight browser pixel on your Shopify storefront to capture events in real time. The pixel feeds events into Upstack, which then forwards them server-side to your destinations. You get the speed of browser collection **and** the reliability of server delivery. </Tip> ## Upstack products that power destinations Destinations are configured through two Upstack products depending on the platform type: * **Upstack Signal** handles conversion API forwarding to ad platforms (Meta CAPI, Google Ads, TikTok, Pinterest, Snapchat, Reddit, AppLovin, LinkedIn, Microsoft/Bing, Outbrain, Taboola, NewsBreak). Signal enriches each event with hashed PII, click IDs, and attribution parameters before delivery so platforms can match conversions to the right ad interactions. * **Upstack Flows** handles event delivery to marketing automation and data platforms (Klaviyo, Omnisend, Sendlane, Loops, Attentive, PostHog, Slack, webhooks). Flows lets you map Upstack events to platform-specific actions — for example, triggering a Klaviyo flow when a high-intent visitor abandons checkout. ## Available destinations ### Ad Platforms <CardGroup> <Card title="Meta CAPI" icon="meta" href="/destinations/meta-capi"> Send conversion events to Facebook and Instagram via the Conversions API for improved ad optimization. </Card> <Card title="Google Ads" icon="google" href="/destinations/google-ads"> Forward conversion events to Google Ads for Smart Bidding and audience building. </Card> <Card title="TikTok" icon="tiktok" href="/destinations/tiktok"> Send conversion events to TikTok via the Events API for campaign optimization and audience building. </Card> <Card title="Pinterest" icon="pinterest" href="/destinations/pinterest"> Send conversion events to Pinterest via the Conversions API for campaign optimization. </Card> <Card title="Snapchat" icon="snapchat" href="/destinations/snapchat"> Send conversion events to Snapchat via the Conversions API for campaign optimization. </Card> <Card title="Reddit Ads" icon="reddit" href="/destinations/reddit"> Forward conversion events to Reddit's Conversions API to recover ad-blocker losses and improve EMQ. </Card> <Card title="AppLovin" icon="mobile" href="/destinations/applovin"> Send conversion events to AppLovin for mobile app install campaign optimization. </Card> <Card title="LinkedIn Ads" icon="linkedin" href="/destinations/linkedin"> Forward B2B conversion events to LinkedIn's Conversions API for campaign optimization. </Card> <Card title="Microsoft/Bing Ads" icon="microsoft" href="/destinations/bing"> Send conversion events to Microsoft Advertising via the Conversions API. </Card> <Card title="Outbrain" icon="bullhorn" href="/destinations/outbrain"> Forward conversion events to Outbrain for native advertising optimization. </Card> <Card title="Taboola" icon="rectangle-ad" href="/destinations/taboola"> Send conversion events to Taboola for native advertising campaign optimization. </Card> <Card title="NewsBreak" icon="newspaper" href="/destinations/newsbreak"> Forward conversion events to NewsBreak for news feed advertising optimization. </Card> </CardGroup> ### Email & SMS Marketing <CardGroup> <Card title="Klaviyo" icon="envelope" href="/destinations/klaviyo"> Sync customer events and properties to Klaviyo for email/SMS automation, segmentation, and flow triggers. </Card> <Card title="Omnisend" icon="envelope-open-text" href="/destinations/omnisend"> Sync customer events and profiles to Omnisend for email/SMS automation and abandonment flows. </Card> <Card title="Sendlane" icon="paper-plane" href="/destinations/sendlane"> Send customer events to Sendlane for email marketing automation. </Card> <Card title="Loops" icon="rotate" href="/destinations/loops"> Send customer events to Loops for automated email marketing workflows. </Card> <Card title="Attentive" icon="mobile-screen" href="/destinations/attentive"> Sync customer events to Attentive for SMS marketing automation. </Card> </CardGroup> ### Analytics <CardGroup> <Card title="PostHog" icon="chart-simple" href="/destinations/posthog"> Send events to PostHog for product analytics and feature flags. </Card> </CardGroup> ### Notifications & Integrations <CardGroup> <Card title="Slack" icon="slack" href="/destinations/slack"> Send real-time notifications to Slack channels for orders, events, and alerts. </Card> <Card title="Webhooks" icon="webhook" href="/destinations/webhooks"> Deliver raw event payloads to any HTTP endpoint for custom integrations and data warehouses. </Card> </CardGroup> ### Deprecated <CardGroup> <Card title="Google Analytics 4" icon="chart-line" href="/destinations/ga4"> GA4 destination is deprecated. Use native GA4 installation instead. </Card> </CardGroup> ## How destination delivery works When an event enters Upstack (from a source like Shopify), the delivery pipeline runs automatically: 1. **Identity enrichment** — the event is matched to a customer profile and enriched with hashed email, phone, and any available click IDs (`fbc`, `fbp`, `ttclid`, `gclid`). 2. **Destination mapping** — Upstack maps the event to each destination's expected schema (for example, `Purchase` becomes a Meta `Purchase` event with the correct currency, value, and content IDs). 3. **Server-side delivery** — the enriched, mapped event is sent to the destination's API from Upstack's infrastructure. 4. **Delivery confirmation** — Upstack logs the response from each destination so you can monitor match rates and troubleshoot failures from the dashboard. <Note> Each destination can be independently enabled or disabled without affecting other destinations. You can also filter which events are sent to each destination from the destination's settings page. </Note> # Pinterest Ads Source: https://docs.upstackdata.com/destinations/pinterest Send conversion events to Pinterest's Conversions API for ad campaign optimization, audience building, and attribution. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> Pinterest's Conversions API is the server-side counterpart to the Pinterest Pixel. Upstack sends purchases, add-to-carts, and other conversion events directly to Pinterest from your account, bypassing browser ad blockers and giving Pinterest's algorithm stronger signal for ad optimization. Server-side delivery consistently achieves higher event match rates than browser-only tracking. Combined with the Pinterest browser pixel, the two work together — Pinterest's deduplication logic keeps only one conversion when the same event arrives from both sources. ## How It Works When a visitor takes an action on your store, Upstack: 1. Captures the event through the Upstack Pixel and matches it to a known visitor profile. 2. Enriches the event with hashed PII (email, phone) and click IDs (`epik`) when available. 3. Sends the enriched event to Pinterest's Conversions API using your Pinterest Pixel Tag ID and Conversions API access token. 4. Logs the response so you can monitor delivery and match rates from the Upstack dashboard. ## Set Up Pinterest Follow the onboarding guide for the full end-to-end setup, or jump to a specific step. <CardGroup> <Card title="Onboarding guide" icon="book" href="/guides/pinterest-ads/complete-how-to-guide-for-onboarding-pinterest-in-upstack-data"> Complete step-by-step walkthrough for connecting Pinterest to Upstack. </Card> <Card title="Configure destination" icon="sliders" href="/guides/pinterest-ads/how-to-configure-pinterest-destination-in-upstack-data"> Add and configure the Pinterest destination inside the Upstack dashboard. </Card> <Card title="Find Pixel Tag ID" icon="magnifying-glass" href="/guides/pinterest-ads/how-to-find-pinterest-pixel-tag-id"> Locate an existing Pinterest Pixel Tag ID in your Pinterest Ads account. </Card> <Card title="Create Pixel Tag ID" icon="plus" href="/guides/pinterest-ads/how-to-create-a-new-pinterest-pixel-tag-id"> Create a new Pinterest Pixel Tag if you don't already have one. </Card> <Card title="Find Advertiser ID" icon="id-card" href="/guides/pinterest-ads/how-to-find-pinterest-advertiser-id"> Locate the Pinterest Advertiser ID required to identify your ad account. </Card> <Card title="Generate API access token" icon="key" href="/guides/pinterest-ads/how-to-generate-pinterest-conversion-api-key-access-token"> Generate the Conversions API access token Upstack uses to send events. </Card> <Card title="Disable Shopify data sharing" icon="ban" href="/guides/pinterest-ads/how-to-disable-pinterest-data-sharing-in-shopify"> Turn off Shopify's native Pinterest data sharing to prevent duplicate events. </Card> </CardGroup> ## FAQ <AccordionGroup> <Accordion title="Do I still need the Pinterest browser pixel?"> You don't need the browser pixel for Upstack to send events — server-side delivery works on its own. However, running both gives Pinterest the strongest signal. As long as the Pinterest Pixel Tag ID matches between your browser pixel and the Upstack destination, Pinterest's deduplication logic prevents double-counting. </Accordion> <Accordion title="Why disable Shopify's native Pinterest data sharing?"> Shopify's built-in Pinterest integration also forwards events to Pinterest. If both Shopify and Upstack are sending the same events without coordination, Pinterest can count conversions twice. Disabling Shopify's native sharing lets Upstack handle delivery exclusively, with the browser pixel for real-time signal and the Conversions API for reliability. See [Disable Shopify data sharing](/guides/pinterest-ads/how-to-disable-pinterest-data-sharing-in-shopify). </Accordion> <Accordion title="What's the difference between the Pixel Tag ID and the Advertiser ID?"> The **Pixel Tag ID** identifies a specific tracking pixel inside your Pinterest account. The **Advertiser ID** identifies the ad account that owns the pixel. Upstack needs both: the Pixel Tag ID to attribute events to the correct pixel, and the Advertiser ID to send them on behalf of the right ad account. </Accordion> <Accordion title="How long does it take for events to appear in Pinterest?"> Once the destination is active, events typically appear in Pinterest's Events Manager within 5-10 minutes. The first events confirm the connection is working — match quality and conversion attribution build over the following 24-48 hours as Pinterest correlates events to ad clicks. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Conversion API Forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack ID matches anonymous visitors to known customers for higher match rates. </Card> <Card title="Destinations Overview" icon="arrow-right-from-bracket" href="/destinations/overview"> Browse all available destinations and how Upstack delivers data to each. </Card> <Card title="Events Not Reaching Destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # PostHog Source: https://docs.upstackdata.com/destinations/posthog Forward identity-resolved customer events to PostHog for product analytics, session recordings, and feature flags. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> PostHog is an open-source product analytics platform. Upstack forwards enriched e-commerce events to PostHog so you can analyze customer behavior, track conversion funnels, and replay user sessions — all powered by Upstack's identity resolution. ## How it works When a visitor takes an action on your store, Upstack: 1. Captures the event through the Upstack Pixel and matches it to a known visitor profile using Upstack's identity resolution. 2. Enriches the event with identity data (distinct ID, email, IP, user agent, device info). 3. Sends the event to PostHog using your Project API Key via the PostHog Capture API. 4. PostHog records the event against the visitor's distinct ID for analytics, funnels, and session replays. The result: unified product analytics where anonymous visitors are resolved to their identities, giving you cleaner funnels and more complete user journeys. ## Set up PostHog <Steps> <Step title="Get your PostHog Project API Key"> In PostHog, go to **Project Settings → Project API Key**. The key starts with `phc_` followed by alphanumeric characters. </Step> <Step title="Note your data region"> PostHog offers two data regions: * **US** — Data hosted in the United States (`us.posthog.com`) * **EU** — Data hosted in the European Union (`eu.posthog.com`) Select the region that matches where your PostHog project is hosted. </Step> <Step title="Add the destination in Upstack"> In the Upstack dashboard, go to **Destinations → Add Destination → PostHog**. Enter: * **Project API Key** — Your PostHog project API key (starts with `phc_`) * **Data Region** — Select US or EU based on your PostHog project location </Step> <Step title="Optional: Configure additional settings"> * **Enable Auto Capture** — Automatically capture pageviews and clicks * **Enable Session Recording** — Enable session recording for user replays (requires PostHog session recording to be configured) </Step> <Step title="Save and verify"> Save the destination. Visit your store, trigger an event (view a product, add to cart), and verify the event appears in PostHog under **Activity → Live Events**. </Step> </Steps> ## Credentials | Field | Required | Description | | ------------------------ | -------- | -------------------------------------------------------------------------------------------------- | | Project API Key | Yes | Your PostHog project API key. Found in **Project Settings → Project API Key**. Starts with `phc_`. | | Data Region | Yes | The region where your PostHog data is hosted: `US` or `EU`. | | Enable Auto Capture | No | Automatically capture pageviews and clicks. | | Enable Session Recording | No | Enable session recording for user replays. | ## Event mapping Upstack automatically maps e-commerce events to PostHog events with enriched properties. | Upstack event | PostHog event | Description | | ------------------ | ------------------- | -------------------------------- | | `PageView` | `$pageview` | Page view on any storefront page | | `ViewContent` | `view_item` | Product detail page view | | `ViewCategory` | `view_category` | Category or collection page view | | `ViewCart` | `$pageview` | Cart page view | | `AddToCart` | `add_to_cart` | Product added to cart | | `InitiateCheckout` | `initiate_checkout` | Checkout started | | `Purchase` | `purchase` | Order completed | | `Search` | `search` | Search performed on storefront | | `SignUp` | `sign_up` | Account created | | `Lead` | `lead` | Lead form submitted | ## Event properties Each event sent to PostHog includes enriched properties from Upstack's identity resolution: | Property | PostHog field | Description | | ---------------- | -------------- | ---------------------------------------------- | | Distinct ID | `distinct_id` | Upstack identity ID (resolved across sessions) | | Current URL | `$current_url` | Page URL where the event occurred | | Referrer | `$referrer` | Referring URL | | IP Address | `$ip` | Visitor IP address | | User Agent | `$user_agent` | Browser user agent string | | Browser | `$browser` | Browser name | | Device Type | `$device_type` | Device type (desktop, mobile, tablet) | | Operating System | `$os` | Operating system name | | Email | `email` | Customer email (when identified) | ### E-commerce properties For purchase and cart events, additional e-commerce properties are included: | Property | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `value` | Total value of the event | | `currency` | Currency code (e.g., USD) | | `order_id` | Order ID (for purchases) | | `search_query` | Search query (for search events) | | `items` | Array of product items with `product_id`, `product_name`, `product_brand`, `product_category`, `price`, `quantity`, and `variant` | ## FAQ <AccordionGroup> <Accordion title="What is the difference between Upstack and PostHog's native Shopify integration?"> PostHog's native integration only sees visitors that Shopify can identify. Upstack's identity resolution matches anonymous sessions to known customer profiles using cookies, click IDs, and cross-session behavioral data. This means your PostHog funnels and cohorts include visitors that would otherwise be anonymous. </Accordion> <Accordion title="How does Upstack identify users in PostHog?"> Upstack uses its identity resolution engine to assign a consistent `distinct_id` to each visitor. This ID persists across sessions, devices, and browsers when Upstack can resolve the visitor's identity. Anonymous visitors receive a temporary ID that Upstack attempts to merge when the visitor is later identified. </Accordion> <Accordion title="Will I see duplicate events if I also have PostHog installed via another method?"> Possibly. If you have PostHog's JavaScript snippet or another integration sending the same events, you may see duplicates. Consider disabling overlapping event types in either Upstack or your other PostHog integration to avoid duplication. </Accordion> <Accordion title="How quickly do events appear in PostHog?"> Events typically appear in PostHog within 1-2 minutes of occurring on your storefront. Check **Activity → Live Events** in PostHog to verify events are arriving. </Accordion> <Accordion title="Can I use PostHog session recordings with Upstack?"> PostHog session recordings require PostHog's JavaScript snippet to be installed on your storefront. Upstack sends server-side events to PostHog, which can be correlated with session recordings if you have both installed. Enable "Session Recording" in the Upstack destination settings to include session replay metadata. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="Events not appearing in PostHog"> If events are showing in the Upstack Live Event Stream but not arriving in PostHog: **Steps to fix:** 1. Confirm the PostHog destination shows **Active** (green) in the Upstack dashboard 2. Verify your Project API Key is correct and starts with `phc_` 3. Check that you selected the correct data region (US or EU) matching your PostHog project 4. In PostHog, go to **Activity → Live Events** and look for events from Upstack 5. If the destination status is red, disconnect and reconnect with a fresh API key </Accordion> <Accordion title="Events showing with wrong distinct_id"> If events appear in PostHog but users aren't being properly identified: **Steps to fix:** 1. Verify Upstack's identity resolution is working by checking the Live Event Stream for resolved identities 2. Check that your PostHog project's person identification settings match how Upstack sends distinct IDs 3. Allow 24-48 hours for Upstack to build identity profiles for new visitors </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond PostHog-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack ID connects anonymous sessions to known customers. </Card> <Card title="Destinations Overview" icon="arrow-right-from-bracket" href="/destinations/overview"> How Upstack Signal and Upstack Flows power different types of destinations. </Card> <Card title="Custom Events" icon="code" href="/guides/custom-events/how-to-create-custom-event-triggers"> Send custom events to PostHog and other destinations. </Card> <Card title="Events Not Reaching Destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Reddit Conversions API Source: https://docs.upstackdata.com/destinations/reddit Forward identity-resolved conversion events to the Reddit Conversions API to recover the 30-50% of conversions lost to ad blockers and improve Reddit Ads Event Match Quality and ROAS. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does Reddit's Conversions API (CAPI) is the server-side counterpart to the Reddit Pixel. The browser pixel loses 30-50% of conversion events to ad blockers, iOS privacy restrictions, and cross-device journeys. Upstack Signal forwards every storefront event — page views, product views, add-to-carts, and purchases — to Reddit's Conversions API as a server-side event with strong match keys. For DTC brands running Reddit Ads, CAPI is essential. Reddit's algorithm only optimizes on what it sees. When half the conversions never make it back, the algorithm starves and your real ROAS hides behind degraded data. Server-side delivery via Upstack restores the full conversion picture so Reddit can optimize against accurate signal. The practical result is higher Event Match Quality (EMQ), more accurate ROAS reporting inside Reddit Ads Manager, and stronger optimization signal for campaigns that depend on conversion events. ## How it works Upstack Signal runs as a dual-tracking layer. The Upstack Pixel captures events in the browser and forwards each one to Upstack's edge infrastructure, where it is hashed, enriched with identity and attribution data, and then sent to Reddit's Conversions API as a server-side event with a shared `conversion_id`. Reddit deduplicates against any matching browser Pixel event using that ID, so you do not double-count. Every event carries the strongest available match keys — hashed `email`, `phone_number`, `external_id`, plus `rdt_cid` (Reddit click ID), `user_agent`, and `ip_address` — so Reddit can attribute the conversion to the right user and ad interaction. ## Setup guides <CardGroup> <Card title="Onboarding guide" icon="route" href="/guides/reddit-ads/complete-how-to-guide-for-onboarding-reddit-in-upstack-data"> End-to-end walkthrough for connecting Reddit Ads to Upstack Data. </Card> <Card title="Configure pixel destination" icon="sliders" href="/guides/reddit-ads/how-to-configure-reddit-destination-in-upstack-data"> Configure the Reddit destination inside Upstack Data. </Card> <Card title="Find Pixel ID" icon="magnifying-glass" href="/guides/reddit-ads/how-to-find-reddit-pixel-id"> Locate your Reddit Pixel ID in Reddit Ads Manager Events Manager. </Card> <Card title="Generate CAPI token" icon="key" href="/guides/reddit-ads/how-to-generate-reddit-conversion-api-token"> Generate a Conversions API access token in Reddit Ads Manager. </Card> <Card title="Update CAPI token" icon="rotate" href="/guides/reddit-ads/how-to-update-reddit-conversion-api-token"> Rotate or replace your existing Reddit CAPI access token. </Card> <Card title="Remove duplicate Reddit pixels" icon="ban" href="/guides/reddit-ads/how-to-disable-existing-reddit-pixel-in-shopify"> Remove existing Reddit pixel installations from Shopify to prevent duplicate events. </Card> </CardGroup> ## Event mapping Upstack maps storefront events to Reddit standard events automatically: | Upstack event | Reddit standard event | Key match data | | ------------------ | ------------------------- | ------------------------------------------------ | | `PageView` | `PageVisit` | URL, referrer, user agent | | `ViewContent` | `ViewContent` | `products`, `value`, `currency` | | `AddToCart` | `AddToCart` | `products`, `value`, `currency` | | `InitiateCheckout` | `Purchase` (intermediate) | `value`, `currency`, `itemCount` | | `Purchase` | `Purchase` | `value`, `currency`, `transactionId`, `products` | PII is hashed with SHA-256 before it leaves Upstack. Upstack includes every available match key on every event — `em` (hashed email), `ph` (hashed phone), `external_id`, `rdt_cid`, `user_agent`, and `ip_address` — to maximize EMQ. ## FAQ <AccordionGroup> <Accordion title="Why does Reddit need the Conversions API?"> Reddit's browser pixel loses 30-50% of conversion events to ad blockers, iOS privacy restrictions (ITP), and cross-device buyer journeys (e.g., browse on mobile, purchase on desktop). The Conversions API runs server-to-server, bypassing browser limitations entirely. Reddit officially recommends running both Pixel and CAPI together, with CAPI providing the reliable backbone. </Accordion> <Accordion title="What is Reddit Event Match Quality (EMQ)?"> Reddit's EMQ score (visible in Reddit Ads Manager) measures how reliably Reddit can match a conversion event back to a Reddit user. Higher EMQ means better optimization, lower CPA, and higher ROAS. Server-side delivery via CAPI typically lifts EMQ scores significantly because events carry hashed PII and click IDs that browser-only events lose. </Accordion> <Accordion title="Will my events be counted twice if I run both the Pixel and CAPI?"> No. Upstack sends a shared `conversion_id` on every server-side event, and Reddit deduplicates against the matching browser Pixel event with the same ID. As long as the Pixel ID in Upstack matches the Pixel ID firing in your storefront, deduplication is automatic. </Accordion> <Accordion title="Do I need to remove my existing Reddit pixel from Shopify?"> If you already have a Reddit pixel installed via Shopify Customer Events, theme.liquid, or a third-party app, that pixel will keep firing browser-side. As long as the Pixel ID matches the one configured in Upstack, deduplication via `conversion_id` prevents double-counting. However, if you have **multiple** Reddit pixels installed (a common cause of inflated metrics), follow the [remove duplicate Reddit pixels guide](/guides/reddit-ads/how-to-disable-existing-reddit-pixel-in-shopify) to consolidate to a single pixel before activating Upstack. </Accordion> <Accordion title="How do I verify CAPI events are arriving in Reddit?"> Open Reddit Ads Manager → **Events Manager** → select your pixel. The **Overview** tab shows recent events with a **Server** badge for CAPI events and a **Browser** badge for pixel events. The **EMQ** column shows match quality scores. Upstack also surfaces delivery status and EMQ inside the destination settings in your dashboard. </Accordion> <Accordion title="What are the typical results from adding Reddit CAPI?"> Brands running Reddit Ads with Upstack's CAPI integration typically see EMQ scores climb within 7-10 days and a 20-40% increase in tracked conversions vs. browser-only pixel. This translates to more accurate ROAS reporting (often revealing campaigns that looked unprofitable were actually performing well) and stronger Reddit Ads campaign optimization. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack matches anonymous visitors to known customers for higher match rates. </Card> <Card title="Meta Conversions API" icon="meta" href="/destinations/meta-capi"> Set up Meta CAPI as another server-side destination alongside Reddit. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Sendlane Source: https://docs.upstackdata.com/destinations/sendlane Forward identity-resolved customer events to Sendlane to power email and SMS automation, abandoned cart recovery, and browse abandonment workflows. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> Sendlane is connected through **Upstack Flows**, the product that handles event delivery to marketing automation platforms. Upstack identifies visitors that Shopify and Sendlane's native tracking miss — turning anonymous browse and cart abandonment sessions into actionable Sendlane contacts. This means more abandoned cart workflows fire, more browse abandonment messages send, and you recover revenue that would otherwise be invisible. ## How It Works When a visitor takes an action on your store, Upstack: 1. Captures the event through the Upstack Pixel and matches it to a known visitor profile using Upstack's identity resolution. 2. Looks up the contact in Sendlane by email or Sendlane contact ID to verify they exist. 3. If the contact is found, enriches the event with cart/product data and sends it to Sendlane as a custom event. 4. The custom event can trigger Sendlane automations like abandoned cart flows, browse abandonment sequences, and post-purchase campaigns. The result: abandoned cart and browse abandonment workflows fire for visitors that Shopify's native tracking misses. <Info> Sendlane events are only sent for contacts that already exist in Sendlane. This ensures your automations target real, opt-in subscribers and keeps your deliverability healthy. </Info> ## Required Credentials To connect Sendlane to Upstack, you need two credentials from your Sendlane account: | Credential | Description | Where to Find | | --------------------- | --------------------------------------------- | -------------------------------------------- | | **API Access Token** | Authenticates API requests to Sendlane | Sendlane → Settings → API | | **Integration Token** | Identifies custom events for your integration | Sendlane → Integrations → Custom Integration | <Steps> <Step title="Generate API Access Token"> In Sendlane, go to **Settings → API** and generate a new API token. Copy the token — you'll need it in the next step. </Step> <Step title="Create Custom Integration"> In Sendlane, go to **Integrations → Custom Integration** and create a new integration. Copy the **Integration Token** provided. </Step> <Step title="Configure in Upstack"> In the Upstack dashboard, go to **Destinations → Add Destination → Sendlane** and paste both credentials. </Step> </Steps> ## Event Mapping Upstack forwards the following events to Sendlane as custom events: | Upstack Event | Sendlane Event | Key Properties | Use Case | | ------------------------------- | ---------------------------------------------- | ------------------------------------------------------------- | ----------------------------- | | `ViewContent` | `product-viewed-upstackified` | `product_id`, `product_name`, `product_img_url`, `variant_id` | Browse abandonment flows | | `AddToCart` | `added-to-cart-upstackified` | `line_items`, `subtotal`, `total`, `currency` | Abandoned cart flows | | `InitiateCheckout` | `checkout-started-upstackified` | `checkout_id`, `line_items`, `subtotal`, `total`, `currency` | Checkout abandonment flows | | `Purchase` | `order-placed-upstackified` | `order_id`, `line_items`, `total`, `currency`, `discounts` | Post-purchase flows, win-back | | `SubscriptionRecurringPurchase` | `subscription-recurring-purchase-upstackified` | `order_id`, `line_items`, `total`, `currency` | Subscription renewal flows | Each event includes line item details such as `product_id`, `variant_id`, `sku`, `product_name`, `quantity`, `item_price`, `product_img_url`, and `product_url`. ## Best Practices <Tip> **Build abandonment automations on Upstack events.** Create Sendlane automations triggered by the `-upstackified` events (e.g., `added-to-cart-upstackified`) to capture visitors that your standard tracking misses. </Tip> <Tip> **Use cross-flow exclusions.** If you have both standard Sendlane automations and Upstack-powered automations, add exclusion filters to prevent the same customer from receiving duplicate messages. </Tip> <Warning> **Disable overlapping integrations.** If you previously used another attribution tool that sends similar events to Sendlane, disable those integrations before enabling Upstack to avoid duplicate events and messages. </Warning> ## FAQ <AccordionGroup> <Accordion title="How is this different from Sendlane's native Shopify integration?"> Sendlane's native Shopify integration only sees visitors that Shopify has identified — typically logged-in customers or shoppers who have entered an email at checkout. Upstack's identity resolution matches anonymous sessions to known customer profiles using cookies, click IDs, and cross-session behavioral data, then sends those events to Sendlane. This lets your abandoned cart and browse abandonment workflows fire for many more visitors. </Accordion> <Accordion title="What happens if a contact doesn't exist in Sendlane?"> Upstack only sends events for contacts that already exist in Sendlane. If the visitor's email isn't found in your Sendlane account, the event is skipped. This keeps your Sendlane account clean and ensures events only target real subscribers. </Accordion> <Accordion title="Will I get duplicate events if I keep Sendlane's native Shopify integration?"> Possibly. If both Upstack and Sendlane's native integration track the same event types, Sendlane may record both. The recommended approach is to disable the corresponding events in Sendlane's native integration for any event types Upstack is configured to send. </Accordion> <Accordion title="What permissions does the Sendlane API token need?"> The Sendlane API token must have permission to read contacts and send custom events. Use a token with the minimum scope required — Upstack does not need account management or billing permissions. </Accordion> <Accordion title="How long does it take for events to appear in Sendlane?"> Once the destination is active, events typically appear in Sendlane within 5 minutes. You can verify by triggering a test action on your store (such as adding a product to cart) and checking the contact's activity feed in Sendlane. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="Events not appearing in Sendlane"> If events are showing in the Upstack Live Event Stream but not arriving in Sendlane: **Steps to fix:** 1. Confirm the Sendlane destination shows **Active** (green) in the Upstack dashboard 2. Verify your API Access Token is valid and has not expired 3. Check that the contact exists in Sendlane — events are only sent for existing contacts 4. Verify the Integration Token matches the custom integration you created in Sendlane 5. If the destination status is red, disconnect and reconnect with fresh credentials </Accordion> <Accordion title="Custom events not triggering automations"> If events are arriving in Sendlane but not triggering your automations: **Steps to fix:** 1. Verify your automation is set to trigger on the correct event name (e.g., `added-to-cart-upstackified`, not `Added to Cart`) 2. Check that the automation is active and not paused 3. Ensure the contact meets any segment or filter conditions on the automation 4. Review the contact's activity feed to confirm the event was received </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond Sendlane-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Data Enrichment" icon="magnifying-glass-plus" href="/concepts/data-enrichment"> How Upstack Enrichment improves visitor identification — the foundation of Flows recovery. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack ID connects anonymous sessions to known customers with email addresses. </Card> <Card title="Klaviyo Destination" icon="envelope" href="/destinations/klaviyo"> Similar email/SMS marketing integration for Klaviyo users. </Card> <Card title="Events Not Reaching Destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Slack Source: https://docs.upstackdata.com/destinations/slack Send real-time event notifications to Slack channels for purchases, leads, and other key conversions. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does The Slack destination sends real-time notifications to any Slack channel when events occur on your store. Get instant alerts for purchases, new leads, abandoned carts, or any custom event — delivered directly to your team's Slack workspace. Unlike ad platform destinations that optimize campaigns, Slack notifications are designed for visibility. See every high-value conversion the moment it happens, celebrate wins with your team, or monitor for unusual activity. ## How it works When a matching event occurs, Upstack: 1. Evaluates the event against your configured event templates and conditions. 2. Renders a Block Kit message using the template's placeholder values (order ID, customer email, revenue, etc.). 3. POSTs the formatted message to your Slack webhook URL. 4. Logs the delivery status to the Upstack event debugger. Each event template can have its own conditions — for example, only notify on purchases over \$100, or only alert when a specific product is purchased. ## Supported events Slack notifications can be triggered by any standard or custom event: | Event | Use case | | ------------------ | ------------------------------------------------------- | | `Purchase` | Celebrate new orders, track high-value conversions | | `InitiateCheckout` | Monitor checkout abandonment in real-time | | `AddToCart` | Track product interest and cart activity | | `Lead` | Get notified of form submissions and newsletter signups | | `ViewContent` | Monitor traffic to key pages | | Custom events | Trigger on any event you define | ## Setup instructions ### Step 1: Create a Slack Incoming Webhook 1. Go to [Slack API Apps](https://api.slack.com/apps) and click **Create New App**. 2. Choose **From scratch**, name your app (e.g., "Upstack Notifications"), and select your workspace. 3. Under **Features**, click **Incoming Webhooks** and toggle it **On**. 4. Click **Add New Webhook to Workspace** and select the channel where notifications should appear. 5. Copy the **Webhook URL** — it looks like `https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX`. ### Step 2: Configure the Slack destination in Upstack 1. In the Upstack dashboard, go to **Destinations** and click **Add Destination**. 2. Select **Slack** from the destination list. 3. Paste your **Webhook URL** from Step 1. 4. Create one or more **Event Templates** to define which events trigger notifications and how they're formatted. ### Step 3: Create event templates Each template maps a source event to a Slack message: * **Source Event**: The event type that triggers this template (e.g., `Purchase`). * **Template**: The Block Kit message structure with placeholders like `{{data.order_id}}` and `{{data.value}}`. * **Conditions** (optional): Filter criteria — only send when conditions are met. ## Example message format Slack messages use Block Kit for rich formatting. Here's an example purchase notification: ```json theme={null} { "blocks": [ { "type": "header", "text": { "type": "plain_text", "text": "🎉 New Purchase!" } }, { "type": "section", "fields": [ { "type": "mrkdwn", "text": "*Order ID:*\n{{data.order_id}}" }, { "type": "mrkdwn", "text": "*Revenue:*\n${{data.value}}" }, { "type": "mrkdwn", "text": "*Customer:*\n{{data.email}}" }, { "type": "mrkdwn", "text": "*Source:*\n{{context.utm_source}}" } ] }, { "type": "context", "elements": [ { "type": "mrkdwn", "text": "via Upstack Data" } ] } ] } ``` Placeholders like `{{data.order_id}}` are replaced with actual event values at send time. ## Use cases <CardGroup> <Card title="Purchase alerts" icon="bell"> Get notified in Slack the moment a purchase completes. Include order value, customer info, and attribution source. </Card> <Card title="Lead notifications" icon="user-plus"> Alert your sales team when a lead form is submitted. Route different lead types to different channels. </Card> <Card title="High-value order alerts" icon="trophy"> Use conditions to only notify on orders above a threshold — celebrate the big wins. </Card> <Card title="Abandoned cart monitoring" icon="cart-shopping"> Track checkout initiations in real-time to spot abandonment patterns. </Card> </CardGroup> ## FAQ <AccordionGroup> <Accordion title="Where do I find my Slack webhook URL?"> Create an Incoming Webhook in your Slack workspace settings. Go to [Slack API Apps](https://api.slack.com/apps), create or select an app, enable Incoming Webhooks, and add a new webhook to your desired channel. The URL is generated automatically. </Accordion> <Accordion title="Can I send to multiple Slack channels?"> Each Slack destination has one webhook URL (one channel). To send to multiple channels, create multiple Slack destinations with different webhook URLs and configure each with the appropriate event templates. </Accordion> <Accordion title="How do conditions work?"> Conditions let you filter which events trigger a notification. For example, you can configure a template to only fire when `data.value` is greater than 100, or when `data.currency` equals "USD". Conditions support AND/OR logic for complex filtering. </Accordion> <Accordion title="What placeholders can I use in templates?"> Any field from the tracking event is available as a placeholder. Common examples: * `{{data.order_id}}` — Order ID * `{{data.value}}` — Order value * `{{data.email}}` — Customer email * `{{data.currency}}` — Currency code * `{{context.utm_source}}` — UTM source * `{{context.page_url}}` — Page URL where event occurred </Accordion> <Accordion title="What happens if the Slack webhook fails?"> Failed deliveries are logged to the Upstack event debugger. Upstack uses SQS-based retry with exponential backoff for transient failures. If the webhook URL is invalid or the Slack app is deleted, events will fail permanently and appear in your delivery logs. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Webhooks destination" icon="webhook" href="/destinations/webhooks"> Send raw event payloads to any HTTP endpoint for custom integrations. </Card> <Card title="Standard events reference" icon="bolt" href="/pixel/standard-events"> Full reference for all event types and properties available in templates. </Card> <Card title="Custom events" icon="code" href="/guides/custom-events/how-to-create-custom-event-triggers"> Create custom events to trigger Slack notifications for any action. </Card> <Card title="Destinations overview" icon="arrow-right-from-bracket" href="/destinations/overview"> How Upstack delivers events to all destination types. </Card> </CardGroup> # Snapchat Ads Source: https://docs.upstackdata.com/destinations/snapchat Send conversion events to Snapchat's Conversions API for ad campaign optimization, audience building, and attribution. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> Snapchat's Conversions API is the server-side counterpart to the Snap Pixel. Upstack sends purchases, add-to-carts, and other conversion events directly to Snapchat from your account, bypassing browser ad blockers and giving Snap's algorithm stronger signal for ad optimization. Server-side delivery consistently achieves higher event match rates than browser-only tracking. Combined with the Snap browser pixel, the two work together — Snapchat's deduplication logic keeps only one conversion when the same event arrives from both sources. ## How It Works When a visitor takes an action on your store, Upstack: 1. Captures the event through the Upstack Pixel and matches it to a known visitor profile. 2. Enriches the event with hashed PII (email, phone) and Snap click IDs (`scclid`) when available. 3. Sends the enriched event to Snapchat's Conversions API using your Snap Pixel ID and Conversions API token. 4. Logs the response so you can monitor delivery and match rates from the Upstack dashboard. ## Set Up Snapchat Follow the onboarding guide for the full end-to-end setup, or jump to a specific step. <CardGroup> <Card title="Onboarding guide" icon="book" href="/guides/snapchat-ads/complete-how-to-guide-for-onboarding-snapchat-in-upstack-data"> Complete step-by-step walkthrough for connecting Snapchat to Upstack. </Card> <Card title="Configure destination" icon="sliders" href="/guides/snapchat-ads/how-to-configure-snapchat-pixel-destination-in-upstack-data"> Add and configure the Snapchat destination inside the Upstack dashboard. </Card> <Card title="Get Pixel ID" icon="magnifying-glass" href="/guides/snapchat-ads/how-to-get-my-snapchat-pixel-id"> Locate the Snap Pixel ID in your Snapchat Ads account. </Card> <Card title="Generate Conversion API token" icon="key" href="/guides/snapchat-ads/how-to-generate-my-snapchat-conversion-api-token"> Generate the Conversions API token Upstack uses to send events. </Card> <Card title="Disable Shopify data sharing" icon="ban" href="/guides/snapchat-ads/how-to-disable-snapchat-data-sharing-in-shopify"> Turn off Shopify's native Snapchat data sharing to prevent duplicate events. </Card> </CardGroup> ## FAQ <AccordionGroup> <Accordion title="Do I still need the Snap browser pixel?"> You don't need the browser pixel for Upstack to send events — server-side delivery works on its own. However, running both gives Snap the strongest signal. As long as the Snap Pixel ID matches between your browser pixel and the Upstack destination, Snapchat's deduplication logic prevents double-counting. </Accordion> <Accordion title="Why disable Shopify's native Snapchat data sharing?"> Shopify's built-in Snapchat integration also forwards events to Snap. If both Shopify and Upstack are sending the same events without coordination, Snapchat can count conversions twice. Disabling Shopify's native sharing lets Upstack handle delivery exclusively, with the browser pixel for real-time signal and the Conversions API for reliability. See [Disable Shopify data sharing](/guides/snapchat-ads/how-to-disable-snapchat-data-sharing-in-shopify). </Accordion> <Accordion title="How long does it take for events to appear in Snapchat?"> Once the destination is active, events typically appear in Snap Events Manager within 5-10 minutes. The first events confirm the connection is working — match quality and conversion attribution build over the following 24-48 hours as Snap correlates events to ad clicks. </Accordion> <Accordion title="What permissions does the Conversions API token need?"> The Snapchat Conversions API token must have permission to send events on behalf of your ad account. Generate the token with the minimum scope required for sending conversion events — Upstack does not need management or spending permissions. Step-by-step instructions are in [Generate Conversion API token](/guides/snapchat-ads/how-to-generate-my-snapchat-conversion-api-token). </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Conversion API Forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack ID matches anonymous visitors to known customers for higher match rates. </Card> <Card title="Destinations Overview" icon="arrow-right-from-bracket" href="/destinations/overview"> Browse all available destinations and how Upstack delivers data to each. </Card> <Card title="Events Not Reaching Destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Taboola Source: https://docs.upstackdata.com/destinations/taboola Send conversion events to Taboola's S2S API for native advertising campaign optimization — powered by Upstack Signal. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does Taboola is a native advertising platform that displays sponsored content recommendations on publisher websites. Upstack Signal forwards storefront events — page views, product views, add-to-carts, and purchases — directly to Taboola's Server-to-Server (S2S) Conversion API for campaign optimization. Server-side delivery means conversions reach Taboola even when the browser-side pixel is blocked by ad blockers, ITP, or cookie restrictions. Each event carries the click identifier (`tblci`) captured from ad clicks so Taboola can match the conversion back to the ad interaction that drove it. <Warning> **Important limitation:** Taboola does **NOT** support enhanced matching via hashed email, phone, or other PII. Attribution relies **solely on the click ID (`tblci`)** captured from ad clicks. Events without a click ID cannot be attributed and are skipped. </Warning> ## How it works Upstack Signal runs as a dual-tracking layer alongside the Taboola browser pixel. The Upstack Pixel captures events in the browser and forwards each one to Upstack's edge infrastructure, where it is enriched with the Taboola click ID from cookie storage and sent to Taboola's S2S API as a server-side event. **S2S priority for deduplication:** When both the browser pixel and S2S report the same event, Taboola keeps the S2S event and deduplicates the pixel event. This makes server-side preferred for accurate attribution. **API behavior:** Taboola's S2S API returns HTTP 204 No Content for **all** requests, including invalid ones. There is no validation feedback from the API — use Taboola Backstage Test Events for verification. **Authentication:** Unlike Meta, TikTok, and Google APIs, Taboola's S2S API is unauthenticated. Events are attributed via the click ID only. ## Setup ### Prerequisites * A Taboola Backstage account with active campaigns * The Upstack Pixel installed on your storefront * Campaign URLs configured with the `tblci` click ID parameter ### Required credentials | Field | Description | Where to find | | ---------- | ------------------------------- | --------------------------------------- | | Account ID | Your numeric Taboola Account ID | Backstage → Account dropdown → Tracking | ### Configuration steps 1. In Upstack, navigate to **Settings** → **Destinations** 2. Click **Add Destination** and select **Taboola** 3. Enter your **Account ID** (numeric only) 4. Toggle **Enable Server-Side Tracking** to send events via the S2S API 5. Click **Save** ### Configure click ID tracking For Taboola to attribute conversions, your campaign URLs must include the click ID parameter: 1. In Taboola Backstage, go to **Campaigns** → select your campaign 2. Add `?tblci={click_id}` to your destination URL (or `&tblci={click_id}` if URL already has parameters) 3. The Upstack Pixel will automatically capture and store the `tblci` value <Note> The `tblci` parameter is case-sensitive. Ensure your URL uses lowercase `tblci`. </Note> ## Event mapping Upstack maps storefront events to Taboola events automatically: | Upstack event | Taboola event | Key parameters | Notes | | ---------------------- | ----------------------- | -------------------------------- | ------------------------------ | | `Purchase` | `make_purchase` | `revenue`, `currency`, `orderid` | Primary conversion event | | `InitiateCheckout` | `start_checkout` | `revenue`, `currency` | Checkout initiation | | `AddToCart` | `add_to_cart` | `quantity` | Cart additions | | `ViewContent` | `view_content` | — | Product page views | | `PageView` | `page_view` | — | Page load | | `Lead` | `lead` | `revenue` | Lead form submissions | | `SignUp` | `complete_registration` | — | Account registration | | `CompleteRegistration` | `complete_registration` | — | Account registration | | `Search` | `search` | — | Site search | | `Subscribe` | `subscribe` | — | Newsletter/subscription signup | Every event includes the Taboola click ID (`tblci`) when available. **Events without a click ID are skipped** because Taboola cannot attribute them to any campaign. <Warning> **Event names are case-sensitive.** Taboola event names must exactly match the conversion name configured in Taboola Realize. Upstack sends lowercase snake\_case names (e.g., `make_purchase`, `add_to_cart`). </Warning> ## Field mapping | Upstack field | Taboola field | Type | Notes | | -------------------------------------- | ------------- | ------ | ----------------------------------------- | | `context.properties.click.tblci` | `click-id` | string | **Required.** Click ID from ad click | | `data.value` | `revenue` | number | Conversion value (decimal, no commas) | | `data.currency` | `currency` | string | ISO 4217 (USD, EUR, GBP) — case-sensitive | | `data.orderId` or `data.transactionId` | `orderid` | string | Transaction ID for deduplication | | Aggregated from `items` | `quantity` | number | Total quantity across all items | | Event timestamp | `timestamp` | number | Milliseconds since Unix epoch | ## FAQ <AccordionGroup> <Accordion title="How do I verify events are arriving in Taboola?"> Open Taboola Backstage, navigate to **Tracking** → **Test Events**, and check that events are appearing. Note that Taboola's API returns 204 for all requests (even invalid ones), so the Test Events view is the only way to confirm events are being processed correctly. </Accordion> <Accordion title="Why are my attribution rates lower than other platforms?"> Taboola does not support enhanced matching with hashed PII (email, phone, IP, user-agent). Attribution relies **solely** on the click ID (`tblci`). If a visitor clears cookies, uses a different device, or the click ID expires, the conversion cannot be attributed. This is a platform limitation, not an Upstack issue. </Accordion> <Accordion title="Will my events be counted twice if I run both the pixel and server-side?"> No. When both the browser pixel and S2S report the same event, Taboola keeps the S2S event and deduplicates the pixel event. Including an `orderid` on purchase events further improves deduplication. </Accordion> <Accordion title="Do event names need to match exactly?"> Yes — event names are **case-sensitive** and must exactly match the conversion name configured in Taboola Realize. Upstack sends standard lowercase snake\_case names like `make_purchase`, `add_to_cart`, etc. </Accordion> <Accordion title="What happens if the click ID is missing?"> Events without a Taboola click ID are **skipped** and not sent to Taboola. This is intentional — Taboola cannot attribute conversions without a click ID, so sending them would inflate your event volume without improving attribution. Ensure your campaign URLs include `tblci={click_id}` so the Upstack Pixel can capture click IDs. </Accordion> <Accordion title="Why does the API always return 204?"> Taboola's S2S API returns HTTP 204 No Content for **all** requests, including those with invalid data. This is by design. Use Taboola Backstage Test Events to verify events are being processed correctly. </Accordion> </AccordionGroup> ## Troubleshooting <AccordionGroup> <Accordion title="No conversions appearing in Taboola Backstage"> If events aren't appearing after confirmed store traffic: **Steps to fix:** 1. Verify your campaign URL includes `tblci={click_id}` 2. Confirm the Upstack destination shows **Active** (green) 3. Check that the Account ID matches your Backstage account 4. Test with a real ad click — test traffic without `tblci` in the URL won't generate events 5. Check Taboola Backstage → Tracking → Test Events for any incoming events </Accordion> <Accordion title="Invalid Account ID"> The Account ID must be a numeric string (digits only). **Steps to fix:** 1. Go to Taboola Backstage → Account dropdown → Tracking 2. Copy the numeric Account ID (no spaces, no extra characters) 3. Update the destination in Upstack with the correct ID </Accordion> <Accordion title="Low attribution rate compared to other platforms"> This is expected due to Taboola's click-ID-only attribution model. **To maximize attribution:** * Ensure all campaigns include `tblci={click_id}` in the URL * Verify the Upstack Pixel is loading on all pages to capture click IDs * Check that first-party cookies are not being blocked by browser settings * Note that cross-device and returning-visitor conversions will not be attributed </Accordion> <Accordion title="Events appear to send but don't show in Backstage"> Remember that Taboola's API returns 204 for all requests, even invalid ones. **Steps to fix:** 1. Verify event names match exactly what's configured in Taboola Realize (case-sensitive) 2. Ensure the `click-id` parameter is being sent correctly (hyphenated, not underscored) 3. Check that revenue values don't contain commas 4. Verify currency codes are uppercase ISO 4217 (USD, not usd) </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond Taboola-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack matches anonymous visitors to known customers for higher match rates. </Card> <Card title="Outbrain destination" icon="rectangle-ad" href="/destinations/outbrain"> Set up Outbrain's native advertising API — similar click-ID-only attribution model. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # TikTok Events API Source: https://docs.upstackdata.com/destinations/tiktok Send conversion events to TikTok via the Events API for campaign optimization, audience building, and attribution — powered by Upstack Signal. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does TikTok's Events API is the server-side counterpart to the TikTok Pixel. Upstack Signal forwards storefront events — page views, product views, add-to-carts, checkouts, and purchases — directly to TikTok's servers, bypassing browser restrictions like ad blockers, ITP, and cookie limits. Server-side delivery gives TikTok's algorithm a fuller picture of the conversions your ads actually drove, which improves campaign optimization, audience modeling, and attribution accuracy. Match rates from server-side events are consistently higher than browser-only tracking because each event carries hashed customer data and the `ttclid` click identifier when available. <Note> Unlike Meta and Google Ads, TikTok uses **token-based auth** instead of OAuth. You'll paste a Pixel ID and an Events API access token into the Upstack destination — there is no OAuth handshake to step through. </Note> ## How it works Upstack runs as a dual-tracking layer alongside the TikTok Pixel. The Upstack Pixel captures events in the browser and forwards each event to Upstack's edge infrastructure, where it is hashed, enriched with identity and click-ID data, and sent to the TikTok Events API as a server-side event with a shared `event_id`. TikTok deduplicates server events against matching browser Pixel events using that `event_id`, so you do not double-count conversions as long as both sources use the same Pixel ID. PII (`email`, `phone`, `external_id`) is hashed with SHA-256 before delivery, as required by the Events API. ## Setup guides <CardGroup> <Card title="Onboarding guide" icon="route" href="/guides/tiktok-ads/complete-how-to-guide-for-onboarding-tiktok-ads-in-upstack-data"> End-to-end walkthrough for connecting TikTok to Upstack Data. </Card> <Card title="Configure pixel destination" icon="sliders" href="/guides/tiktok-ads/how-to-configure-tiktok-ads-pixel-destination-in-upstack-data"> Configure the TikTok Pixel destination inside Upstack Data. </Card> <Card title="Find Pixel ID" icon="magnifying-glass" href="/guides/tiktok-ads/how-to-find-your-tiktok-ads-pixel-id"> Locate your existing TikTok Pixel ID in Events Manager. </Card> <Card title="Create Pixel ID" icon="plus" href="/guides/tiktok-ads/how-to-create-new-tiktok-ads-pixel-id"> Create a new TikTok Pixel for your store. </Card> <Card title="Generate API token" icon="key" href="/guides/tiktok-ads/how-to-generate-your-tiktok-api-access-token"> Generate the Events API access token Upstack uses to send events. </Card> <Card title="Disable Shopify TikTok data sharing" icon="ban" href="/guides/tiktok-ads/how-to-disable-tiktok-data-sharing-in-shopify"> Turn off Shopify's native TikTok integration to prevent duplicate events. </Card> </CardGroup> ## Event mapping Upstack maps storefront events to TikTok standard events automatically: | Upstack event | TikTok event | Key parameters | Notes | | ------------------ | ------------------ | ------------------------------------------------- | ------------------------------------------------------ | | `PageView` | `ViewContent` | `url`, `referrer` | TikTok has no generic PageView — mapped to ViewContent | | `ViewContent` | `ViewContent` | `content_id`, `content_type`, `value`, `currency` | Product page views | | `AddToCart` | `AddToCart` | `content_id`, `content_type`, `value`, `currency` | Cart additions with product details | | `InitiateCheckout` | `InitiateCheckout` | `value`, `currency`, `quantity` | Checkout started | | `Purchase` | `CompletePayment` | `content_id`, `value`, `currency`, `order_id` | Completed orders with revenue | Every event includes user data parameters (`email`, `phone`, `external_id`) when available, hashed with SHA-256. TikTok click IDs (`ttclid`) captured by the Upstack Pixel are included for deterministic matching. ## FAQ <AccordionGroup> <Accordion title="How do I know events are reaching TikTok?"> Open TikTok Events Manager, select your Pixel, and check the **Overview** and **Test Events** tabs. Server-side events appear with a "Server" source badge, typically within 5–10 minutes of storefront activity. Upstack also surfaces delivery status inside the destination settings. </Accordion> <Accordion title="Will I see duplicate conversions if I run both the TikTok Pixel and the Events API?"> No — as long as the Pixel ID in Upstack matches the Pixel ID firing in your storefront's TikTok browser Pixel (`ttq.load`). Upstack sends a shared `event_id` on every server-side event, and TikTok's deduplication logic matches events by `event_id` and keeps only one. If you see duplicates, the Pixel IDs almost always differ between the two sources. </Accordion> <Accordion title="What if my event match rate is low?"> TikTok's match rate depends on how much identity data each event carries. Common causes of low match quality: * **Missing `ttclid`** — TikTok ads should link directly to your storefront so the click ID lands in the URL and is captured by the Upstack Pixel. * **Anonymous visitors** — events from visitors without email or phone have fewer keys to match against. Match rates improve as more identified customers convert. * **Missing checkout fields** — make sure your Shopify checkout collects email and phone; both are strong server-side match keys. </Accordion> <Accordion title="Do I need to disable Shopify's native TikTok integration?"> Yes — if Shopify is also sending events to the same TikTok Pixel, you'll see duplicates that TikTok cannot deduplicate (Shopify does not emit a matching `event_id`). Follow the guide above to disable TikTok data sharing in Shopify before activating Upstack's TikTok destination. </Accordion> <Accordion title="Can I send only specific event types to TikTok?"> Yes. Each destination supports event filtering — you can choose to forward only purchases, only standard events, or any custom subset. Excluded events are dropped at the Upstack level and are not retried. </Accordion> </AccordionGroup> ## Advanced configuration <Accordion title="TikTok Shop orders"> If you sell through TikTok Shop, those orders flow into Shopify as fulfilled orders. Upstack processes them like any other Shopify order, which means they get sent to all your active destinations — including Meta. **Should you exclude TikTok Shop orders from other destinations?** Upstack gives you the option via **Settings → Order Source Exclusions**, where you can block orders by source. However, sending TikTok Shop orders to Meta is generally beneficial — more conversion data helps Meta's algorithm find similar high-value customers, regardless of where the original purchase happened. If you still want to exclude them: 1. Go to **Upstack → Settings → Order Source Exclusions**. 2. Add TikTok Shop as a blocked source. 3. Orders originating from TikTok Shop will no longer fire to other destinations. </Accordion> ## Troubleshooting <AccordionGroup> <Accordion title="Events not appearing in TikTok Events Manager"> If events aren't appearing after 10 minutes of confirmed store traffic, check the basics first. **Steps to fix:** 1. Go to **Integrations → Destinations → TikTok** 2. Verify the **Pixel ID** and **Access Token** are correct (no extra spaces or truncated characters) 3. Confirm the destination status is Active (green) 4. If the token was revoked or expired, generate a new one in TikTok Business Center and update the destination </Accordion> <Accordion title="Duplicate conversions in TikTok"> If you see inflated conversion counts, another TikTok event source is likely still active. **Steps to fix:** 1. Check for the TikTok Shopify sales channel — disable its data sharing / pixel component 2. Look for third-party pixel apps (Omega, Mega TikTok Pixel) and uninstall them 3. Inspect your theme code for manual TikTok pixel snippets in the `<head>` section 4. After removing duplicate sources, monitor TikTok Events Manager for 24 hours to confirm counts normalize </Accordion> <Accordion title="Low match quality scores"> TikTok's match quality measures how well server events match to TikTok users. **Common causes:** * **High anonymous traffic** — Events from visitors who haven't logged in or provided contact info have fewer matching parameters. Match quality improves as more identified customers generate events. * **Incorrect pixel ID** — If the pixel ID doesn't match the one associated with your ad account, events arrive but can't be matched to campaign data. Match quality typically improves over 1–2 weeks as Upstack's identity resolution builds visitor profiles. </Accordion> </AccordionGroup> <Note> For additional troubleshooting beyond TikTok-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination). </Note> ## Related <CardGroup> <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack matches anonymous visitors to known customers for higher match rates. </Card> <Card title="Meta CAPI destination" icon="meta" href="/destinations/meta-capi"> Set up Meta's Conversions API as another server-side destination alongside TikTok. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Webhooks Source: https://docs.upstackdata.com/destinations/webhooks Deliver raw event payloads to any HTTP endpoint for custom integrations, data warehouses, and internal systems. <Note> **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs. </Note> ## What it does The webhook destination delivers Upstack events as JSON payloads to any HTTPS endpoint you control. Use it to feed data warehouses, trigger internal workflows, connect platforms Upstack does not support natively, or build custom integrations on top of Upstack's enriched event stream. Every event Upstack captures — including identity-resolved customer data and attribution context — can be delivered to your endpoint in near real-time. Webhooks give you the same enriched event payload that powers Upstack's native destinations, with full schema control on your side. ## How it works Webhook deliveries are HTTP POST requests with a JSON body. Upstack signs each request with HMAC-SHA256 using a per-destination signing secret, so your endpoint can verify the payload originated from Upstack and was not tampered with. Each delivery includes standard headers (`X-Upstack-Event-Id`, `X-Upstack-Event-Type`, `X-Upstack-Signature`, `X-Upstack-Timestamp`) for routing, deduplication, and signature verification. Delivery is at-least-once with a 10-second timeout per attempt and up to 5 retries with exponential backoff (1s, 5s, 30s, 2m, 10m). Events are delivered in approximate chronological order, but strict ordering is not guaranteed — your endpoint should be idempotent and use the `event_id` to deduplicate. ## Setup guides Webhook setup is configured directly in Upstack's destination settings — endpoint URL, event filter, headers, and signing secret. There are no platform-side credentials to provision. <CardGroup> <Card title="Standard events reference" icon="bolt" href="/pixel/standard-events"> Full reference for all event types and properties included in webhook payloads. </Card> <Card title="Properties and context" icon="list" href="/pixel/events/event-properties"> Complete list of event properties and context fields available in every payload. </Card> </CardGroup> ## Payload format Every webhook delivery is an HTTP POST with a JSON body that follows Upstack's standard event schema: ```json theme={null} { "event_id": "evt_abc123def456", "event_type": "Purchase", "timestamp": "2026-02-18T14:32:01.000Z", "pixel_id": "px_your_pixel_id", "session_id": "sess_789xyz", "user": { "anonymous_id": "anon_456def", "customer_id": "cust_123abc", "email_hash": "sha256:a1b2c3...", "phone_hash": "sha256:d4e5f6..." }, "properties": { "order_id": "1234", "value": 89.99, "currency": "USD", "items": [ { "product_id": "prod_001", "title": "Classic T-Shirt", "variant_id": "var_001", "price": 29.99, "quantity": 3 } ] }, "context": { "page_url": "https://your-store.myshopify.com/checkout", "referrer": "https://www.google.com", "user_agent": "Mozilla/5.0...", "ip": "203.0.113.42", "utm_source": "google", "utm_medium": "cpc", "utm_campaign": "summer-sale" }, "attribution": { "source": "google", "medium": "cpc", "campaign": "summer-sale", "click_ids": { "gclid": "abc123", "fbclid": null, "ttclid": null } } } ``` PII fields (`email_hash`, `phone_hash`) are delivered as SHA-256 hashes by default. Raw (unhashed) PII delivery is available for endpoints you own and is subject to your data processing agreement. ### Delivery headers | Header | Value | Description | | ---------------------- | ------------------ | --------------------------------------- | | `Content-Type` | `application/json` | Payload format | | `X-Upstack-Event-Id` | `evt_abc123...` | Unique event ID for deduplication | | `X-Upstack-Event-Type` | `Purchase` | Event type | | `X-Upstack-Signature` | `sha256=...` | HMAC signature for payload verification | | `X-Upstack-Timestamp` | `1708266721` | Unix timestamp of delivery attempt | ## FAQ <AccordionGroup> <Accordion title="What does Upstack guarantee about delivery?"> Webhooks use **at-least-once** delivery. Each request has a 10-second timeout and up to 5 retries with exponential backoff (1s, 5s, 30s, 2m, 10m). After all retries fail, the event is logged as a failed delivery in your dashboard's delivery log. In rare cases (network timeouts, retries) your endpoint may receive the same event more than once — deduplicate using the `event_id` field or the `X-Upstack-Event-Id` header. </Accordion> <Accordion title="How do I verify a webhook payload actually came from Upstack?"> Every delivery includes an `X-Upstack-Signature` header containing an HMAC-SHA256 signature of the raw request body, computed with your destination's signing secret. Recompute the signature on your end over the **raw** (un-parsed, un-reformatted) request body and compare using a constant-time comparison. If the signatures match, the payload is authentic. The signing secret is shown once when you create the destination — store it securely; it can only be regenerated, not retrieved. </Accordion> <Accordion title="Can I receive only certain event types?"> Yes. Each webhook destination supports event filtering — choose all events, standard events only, or any custom subset. Excluded events are dropped at the Upstack level and are not retried. </Accordion> <Accordion title="My endpoint is timing out. What should I do?"> Accept the request immediately (return `200`) and process the payload asynchronously. The 10-second timeout is end-to-end — including any work your endpoint does before responding. The standard pattern is: validate signature, enqueue the payload to your own queue, return `200`, then process the payload separately. </Accordion> <Accordion title="Does the endpoint URL need to be HTTPS?"> Yes. HTTP endpoints are not supported. Your endpoint must be publicly reachable (Upstack delivers from its cloud infrastructure) and serve a valid TLS certificate. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Standard events reference" icon="bolt" href="/pixel/standard-events"> Full reference for all event types and properties included in webhook payloads. </Card> <Card title="Properties and context" icon="list" href="/pixel/events/event-properties"> Complete list of event properties and context fields available in every payload. </Card> <Card title="Destinations overview" icon="arrow-right-from-bracket" href="/destinations/overview"> How Upstack delivers events to all destination types. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # Frequently Asked Questions Source: https://docs.upstackdata.com/faq Answers to common questions about Upstack Data — event tracking, identity resolution, privacy, custom events, Shopify compatibility, team management, and platform concepts. <AccordionGroup> <Accordion title="What events does Upstack track automatically?"> Once the Upstack pixel is installed and Shopify is connected, the following events are captured automatically with no additional configuration: * **PageView** — every page load on your storefront * **ViewContent** — product detail page views * **AddToCart** — items added to the cart * **InitiateCheckout** — checkout started * **AddPaymentInfo** — payment method entered * **Purchase** — completed orders (captured server-side via Shopify webhooks for maximum accuracy) * **Search** — storefront search queries Shopify webhook events like `orders/refunded`, `orders/fulfilled`, and `customers/create` are also captured automatically through the server-side integration. You don't need to add any custom code for these standard events. For additional events, see [Custom Events](/pixel/custom-events). </Accordion> <Accordion title="How long does it take for events to appear?"> * **Live Event Stream:** Events appear within **30–60 seconds** of occurring on your storefront. This is the fastest way to verify your integration. * **Dashboard analytics:** Aggregated metrics update every **5–15 minutes** depending on processing load. * **Destination delivery:** Events are forwarded to destinations (Meta, TikTok, etc.) within **1–5 minutes** of capture. * **Attribution reports:** Attribution data may take up to **1 hour** to fully resolve, because Upstack waits for identity resolution to complete before finalizing attribution. If events aren't appearing after 5 minutes, see [Events Not in Dashboard](/troubleshooting/events-not-in-dashboard). </Accordion> <Accordion title="Does Upstack work with headless Shopify setups?"> Yes. Upstack supports headless Shopify storefronts using the **Upstack JavaScript SDK** instead of the Shopify app embed. For headless setups: 1. Install the Upstack SDK via npm or a `<script>` tag. 2. Initialize the SDK with your Pixel ID. 3. Call the tracking methods (`track`, `page`, `identify`) from your storefront code at the appropriate lifecycle points. Server-side event capture (orders, refunds, fulfillments) still works automatically through Shopify webhooks — no additional setup needed. See [Connect Shopify](/sources/shopify) for detailed headless integration instructions. </Accordion> <Accordion title="How does Upstack handle GDPR and privacy compliance?"> Upstack is designed with privacy in mind: * **Server-side first:** Most critical events (purchases, refunds) are captured server-side through Shopify webhooks, not browser cookies. This means tracking is more resilient to browser privacy restrictions while remaining compliant. * **Consent management:** Upstack integrates with popular consent management platforms (OneTrust, Cookiebot, Shopify's native consent API). When a visitor declines tracking, the client-side pixel respects that choice and suppresses non-essential events. * **Data processing:** Upstack processes data in accordance with GDPR, CCPA, and other applicable privacy regulations. Personal data like email and phone number is hashed (SHA-256) before being sent to ad platform destinations. * **Data retention:** You control how long event data is retained in your workspace settings. Default retention is 13 months. * **DPA:** We provide a Data Processing Agreement upon request. Contact [support@upstackdata.com](mailto:support@upstackdata.com). </Accordion> <Accordion title="Can I track custom events?"> Yes. Beyond the automatic standard events, you can track any custom event using the Upstack JavaScript SDK: ```javascript theme={null} upstack.track('WishlistAdd', { product_id: '12345', product_name: 'Blue Widget', value: 29.99, currency: 'USD' }); ``` Custom events: * Appear in the Live Event Stream and dashboards alongside standard events. * Can be forwarded to destinations — you map them in the destination's **Event Mapping** settings. * Support any JSON-serializable properties. * Are subject to the same identity resolution and enrichment as standard events. See [Custom Events](/pixel/custom-events) for naming conventions and best practices. </Accordion> <Accordion title="What happens if my pixel goes down?"> Upstack is built for resilience across multiple layers: * **Server-side backup:** Critical conversion events (purchases, refunds) are captured via Shopify webhooks regardless of pixel availability. Even if the client-side pixel fails completely, your conversion data is safe. * **Edge infrastructure:** The Upstack pixel endpoint runs on Cloudflare's global edge network with 99.99% uptime. Requests are served from the nearest edge location. * **Retry logic:** If an event fails to deliver, it's automatically retried with exponential backoff for up to 24 hours. * **Graceful degradation:** If the pixel script fails to load (due to an ad blocker or network issue), it does not break your storefront. The script is loaded asynchronously and fails silently. In practice, the most common "pixel down" scenario is an ad blocker in *your* browser during testing — your actual customers are rarely affected. </Accordion> <Accordion title="How does identity resolution affect my ad performance?"> Identity resolution is the core of what makes Upstack's server-side tracking valuable for ad platforms: 1. **Higher match rates:** When Upstack resolves an anonymous visitor to a known customer (via login, email at checkout, or cross-session fingerprinting), it enriches the event with hashed PII (email, phone). This gives ad platforms like Meta and TikTok a much higher Event Match Quality (EMQ) score. 2. **Better optimization:** Higher EMQ means the ad platform can match more conversions to ad clicks, which feeds the algorithm more signal. More signal = better audience targeting = lower CPA. 3. **Cross-device attribution:** Identity resolution stitches sessions across devices. A customer who clicks an ad on mobile but purchases on desktop is correctly attributed. Most Upstack customers see a **20–40% improvement in EMQ scores** after enabling Upstack ID compared to client-side-only tracking. Learn more in [Identity Resolution](/pixel/identity-resolution). </Accordion> <Accordion title="What Shopify plans does Upstack support?"> Upstack works with all Shopify paid plans: | Shopify Plan | Supported | Notes | | ---------------- | --------- | --------------------------------------------------------------------- | | Shopify Starter | Partial | Limited webhook support; no online store so pixel tracking is limited | | Basic Shopify | Full | All features available | | Shopify | Full | All features available | | Advanced Shopify | Full | All features available | | Shopify Plus | Full | All features available, including checkout extensibility support | Upstack does **not** support Shopify's free trial period — you must be on an active paid plan for webhooks and app embeds to function. </Accordion> <Accordion title="How do I add team members?"> You can invite team members to your Upstack workspace: 1. Go to **Settings → Team** in the Upstack dashboard. 2. Click **Add Team member** and enter their email address. 3. Choose a role: * **Admin** — full access: manage users, billing, integrations, and data. * **Owner** — account creator; only another owner can remove an owner. * **Member** — can view dashboards and event streams but cannot modify integrations or billing. 4. Click **Add Email** for each user, then click **Send Invitations**. 5. The invited user receives an email with a link to create their Upstack account (or sign in if they already have one). There's no limit on the number of team members on any plan. All roles can access the same event data — roles only control what actions a user can take. For the full walkthrough, see [How to invite a team member to your Upstack account](/resources/how-to-invite-a-team-member-to-your-upstack-account). </Accordion> <Accordion title="What's the difference between sources and destinations?"> Think of Upstack as sitting in the middle of your data flow: * **Sources** are where data comes *from*. These are the platforms that generate events and data that Upstack ingests. Examples: * **Shopify** — storefront events, orders, customers * **Facebook Ads** — ad spend and campaign data * **Google Ads** — ad spend and campaign data * **Destinations** are where data goes *to*. These are the platforms that Upstack forwards enriched event data to. Examples: * **Meta Conversions API (CAPI)** — server-side purchase and conversion events * **TikTok Events API** — server-side events for TikTok ad optimization * **Klaviyo** — customer and event data for email/SMS flows * **Google Analytics 4** — measurement protocol events The key insight: Upstack enriches events with identity resolution *between* source and destination. Raw storefront events go in, identity-resolved and enriched events come out. See [Sources overview](/sources/overview) and [Destinations overview](/destinations/overview) for the full list. </Accordion> </AccordionGroup> *** **Still stuck?** Contact [support@upstackdata.com](mailto:support@upstackdata.com) with your Pixel ID and a description of the issue. We typically respond within a few hours. # Configure contribution margin Source: https://docs.upstackdata.com/get-started/configure-contribution-margin Set up COGS, transaction fees, and marketing spend in Upstack to track CM1–CM4 contribution margins and real profitability. Upstack calculates four tiers of contribution margin so you can optimize on profit, not vanity metrics like revenue or ROAS. Each tier subtracts an additional layer of costs: | Level | What's subtracted | What it tells you | | ------- | --------------------------------------------------- | ---------------------------------------- | | **CM1** | COGS (cost of goods sold) | Gross margin | | **CM2** | + Fulfillment, transaction & gateway fees, shipping | Post-logistics margin | | **CM3** | + Marketing and ad spend | Contribution margin (most commonly used) | | **CM4** | + Operating expenses, agency fees, and other | Operating profit | ## Setup <Steps> <Step title="Enter COGS in Shopify"> Go to **Shopify Admin → Products** and select a product. For each variant, enter the **Cost per item** field. If you sell a product for $30 and it costs $5 to produce, enter \$5. Upstack pulls this in automatically — no manual sync required. <Info> After configuring COGS, allow approximately **4 hours** for historical data to backfill. CM1 values for past orders populate automatically once the backfill completes. </Info> </Step> <Step title="Configure your other costs in Upstack"> Open **Settings → Cost Overview** to add shipping, gateway fees, order costs, a fallback product margin, and fixed and variable costs. Each cost is assigned a category that maps to a contribution-margin tier: | Cost category | CM tier | | ------------------------------------------- | ------- | | COGS (product cost) | CM1 | | Fulfillment, transaction, gateway, shipping | CM2 | | Marketing and ad spend | CM3 | | Operating expenses, agency fees, other | CM4 | Fixed and variable costs land in the tier matching their category. See [Cost settings](/get-started/cost-settings) for a full walkthrough of every category. </Step> <Step title="Connect marketing spend"> Spend from **connected ad platforms** (Meta, Google, TikTok) flows in automatically. For **non-connected channels** (influencer, podcast, and similar), add it under **Settings → Cost Overview** as a fixed or variable cost so it counts toward CM3. </Step> </Steps> ## P\&L dashboard Two views are available: * **Summary** — aggregate P\&L across a date range * **Daily breakdown** — granular day-by-day performance Key metrics include Net Revenue, COGS, CM1, CM2, CM3, CM4, MER, and NCCM3. Over 250 measures are available and fully customizable. <Tip> **NCCM3** is contribution margin (CM3) for **new customers only** — net revenue minus product, fulfillment, transaction, shipping, marketing, and ad-spend costs. It's the single most useful metric for evaluating whether your prospecting spend is profitable after all variable costs. </Tip> <Accordion title="LTV cohort dashboard"> The LTV Cohort Dashboard shows customer lifetime value by acquisition cohort. Use it to measure how quickly cohorts pay back acquisition cost and identify your highest-value customer segments. This replaces standalone LTV tools like Lifetimely — the data is built directly from your Upstack event pipeline, so cohort metrics stay consistent with your P\&L and attribution data. </Accordion> ## Next step <CardGroup> <Card title="Verify end-to-end delivery" icon="arrow-right" href="/get-started/verify-end-to-end"> Confirm the complete pipeline works — from storefront event through attribution to destination delivery. </Card> </CardGroup> ## Related <CardGroup> <Card title="Cost settings" icon="coins" href="/get-started/cost-settings"> Set up product, order, shipping, gateway, fixed, and variable costs in detail. </Card> <Card title="Attribution and reporting" icon="chart-line" href="/concepts/attribution-and-reporting"> Learn how Upstack attributes conversions and calculates reporting metrics across channels. </Card> <Card title="Attribution reporting dashboard" icon="table-columns" href="/analytics/attribution-reporting"> Explore the attribution reporting dashboard and available metrics. </Card> <Card title="Custom events" icon="bolt" href="/guides/custom-events/how-to-create-custom-event-triggers"> Configure NC Purchase, subscription events, and order source exclusions for ad platform optimization. </Card> <Card title="Connect a destination" icon="plug" href="/get-started/connect-a-destination"> Set up Meta CAPI as your first server-side destination for high-quality conversion events. </Card> </CardGroup> # Connect destinations Source: https://docs.upstackdata.com/get-started/connect-a-destination Connect ad platforms and marketing tools as Upstack destinations to receive server-side conversion events with higher match quality. Destinations are the ad platforms and marketing tools that receive your conversion events. Upstack sends events server-side, bypassing browser restrictions and improving match quality. You connect once, and Upstack handles formatting, deduplication, and delivery for each platform. ## Destinations vs sources * **Destinations** receive conversion events (purchases, page views, add-to-carts) from Upstack for ad optimization * **Sources** pull ad spend and performance data *into* Upstack for unified reporting dashboards * Most platforms need both — a destination for conversion tracking and a source for spend data ## Available destinations Each destination has its own hub page with setup guides, event mapping, troubleshooting, and FAQs. Pick the platforms you use and follow the setup guide on each hub. <CardGroup> <Card title="Meta CAPI" href="/destinations/meta-capi"> Connect Meta's Conversions API for server-side event delivery to Facebook and Instagram Ads. </Card> <Card title="Google Ads" href="/destinations/google-ads"> Send purchase conversions to Google Ads with Smart Bidding-ready conversion goals. </Card> <Card title="TikTok" href="/destinations/tiktok"> Forward events to TikTok Events API with token-based auth and click-ID matching. </Card> <Card title="Klaviyo" href="/destinations/klaviyo"> Sync enriched events and profiles to Klaviyo for abandonment flows and email/SMS automation. </Card> <Card title="Pinterest" href="/destinations/pinterest"> Connect Pinterest's Conversion API for server-side conversion tracking. </Card> <Card title="Snapchat" href="/destinations/snapchat"> Send conversion events to Snapchat's Conversion API for ad optimization. </Card> <Card title="Omnisend" href="/destinations/omnisend"> Forward events to Omnisend for email automation and customer profile enrichment. </Card> <Card title="Custom Webhooks" href="/destinations/webhooks"> Stream events to any HTTPS endpoint for custom integrations and data warehousing. </Card> </CardGroup> ## Connect sources for reporting To see ad spend and ROAS in the Upstack dashboard, connect your ad accounts as sources (data integrations). This pulls spend data into Upstack — it doesn't affect conversion tracking. <CardGroup> <Card title="Connect Facebook Ads account" href="/guides/facebook-ads/how-to-connect-your-facebook-ads-account-in-upstack-data-integrations"> Pull Facebook ad spend into Upstack for unified reporting. </Card> <Card title="Connect Google Ads account" href="/guides/integrations/how-to-connect-your-google-ads-account-in-upstack-data-integrations"> Pull Google Ads spend into Upstack for unified reporting. </Card> </CardGroup> ## Next step <CardGroup> <Card title="Disable existing tracking" icon="arrow-right" href="/get-started/disable-existing-tracking"> Remove redundant browser-side tracking to prevent duplicate conversions. </Card> </CardGroup> # Set up cost settings Source: https://docs.upstackdata.com/get-started/cost-settings Configure product costs, order costs, shipping, gateway fees, and fixed and variable costs in Upstack so your contribution margin and P&L reflect real profitability. Cost settings are where you tell Upstack what it actually costs to fulfill an order. Once your costs are in, Upstack subtracts them from revenue to give you accurate contribution margin (CM1–CM4) and a real P\&L — not just revenue and ROAS. This guide walks through each cost category and how to set it up. <Info> Cost settings are available to **admin and owner** roles, and may not be enabled on every account yet. If you don't see the Costs section in Settings, contact the Upstack team. </Info> ## Where to find it Open **Settings → Cost Overview** (under the **Costs** section of the settings menu). The overview lists every cost category as a card and shows which ones you've configured. Each card links to its own page. <Tip> Two things to know before you start: * **Changes apply to past orders too.** When you add or edit a cost, Upstack recalculates matching historical orders within that cost's date range — so your reporting stays consistent. * **You can date every cost.** Most cost lines accept an effective start and end date, so a rate change from last month doesn't rewrite the months before it. </Tip> ## Where to start The overview marks **Gateways** and **Shipping** as recommended starting points — they apply to almost every order. A good first-time order: 1. **Gateways** — your payment processing fees 2. **Shipping** — what it costs to ship an order 3. **Product Defaults** — a fallback margin so every product has a cost 4. **Order Costs** — any other per-order or per-item fees Add **Product Costs**, **Fixed Costs**, and **Variable Costs** as you need them. ## Product Defaults Two settings that apply when a product is missing its own cost data: * **Default COGS %** — a percentage of the item's sale price (0–100), used as the cost of goods for any product that has no specific cost. This is the fallback when a variant has no cost. * **Global Handling Fee** — a flat amount added per line item. This is a separate handling cost that applies whenever it's set; it isn't part of the product-cost fallback. Set the Default COGS % first so no order is ever missing a product cost. ## Product Costs Per-variant cost overrides. If you maintain **Cost per item** in Shopify, Upstack syncs it automatically — those synced costs are read-only here. You can also enter your own cost for any variant, with effective date ranges; your manual entry takes precedence over the Shopify-synced value. <Note> Give each cost entry for a variant a **different start date**. If two entries share the same start date, only one of them is used for an order, and Upstack flags the duplicate so you can fix it. </Note> ## Order Costs Fees that apply per order, per line item, or per refund — beyond product cost. For each cost line you choose how it's calculated: | Type | What it does | | ------------------------------------------------ | ----------------------------------- | | Per Order / Per Line Item | A flat amount per order or per item | | Per Refund Order / Per Refund Line Item | A flat amount applied on refunds | | By Order Weight | Tiered by the order's weight | | By Order Quantity / By Line Item Quantity | Tiered by how many units | | % of COGS / Shipping / Total / Gross / Net Sales | A percentage of the chosen base | Each cost line is assigned a **category** (COGS, Fulfillment, Transaction, Marketing, Agency Fees, Opex, or Other) — which determines its contribution-margin tier — and a **channel** (Online, POS, or Both). Rich filters let you scope a cost to specific gateways, tags, vendors, product types, countries, or products. ## Shipping Choose how Upstack accounts for shipping cost, using one of three modes: | Mode | When to use it | | -------------------------------- | ------------------------------------------------------- | | **Use Shopify Shipping Charges** | Use the shipping amount already on your Shopify orders | | **Fixed Rate Per Order** | Apply one flat shipping cost to every order | | **Shipping Profiles** | Set rates by country/region — flat, or tiered by weight | With **Shipping Profiles**, each profile matches one or more countries. A profile can be a single **Flat Rate** or **Weight Tiered**, and you can set a default profile as a fallback. <Warning> If two shipping profiles cover the same country, Upstack shows an **Overlapping Shipping Profiles** warning and uses the first match. Keep country coverage distinct so the right rate always applies. </Warning> ## Gateways Payment processing fees per gateway, entered as a flat amount plus a percentage: * **Flat Fee** — a fixed amount per transaction (e.g. \$0.30) * **Percent Fee (%)** — a percentage of the order (e.g. 2.9%) Gateway names are discovered from your order history, so you only configure the ones you actually use. ## Fixed Costs Recurring overheads like rent, salaries, and software subscriptions. Set an amount and a **frequency** — Daily, Weekly, Monthly, Quarterly, or Yearly — and a **category** (Marketing, Opex, Agency Fees, or Other). Upstack averages the cost across the period so it shows up correctly in your P\&L. ## Variable Costs Costs that scale with ad spend. Today this is **% of Ad Spend** — a percentage applied to your ad spend, with an optional filter for which ad platforms it applies to, under a **Marketing** or **Opex** category. Useful for agency fees or tools billed as a percentage of spend. ## How costs roll into contribution margin Each cost's **category** decides which margin tier it reduces: | Tier | Reduced by costs in these categories | | ------- | ----------------------------------------------- | | **CM1** | Cost of goods sold (product cost) | | **CM2** | Fulfillment, transaction, gateway, and shipping | | **CM3** | Marketing — your marketing costs and ad spend | | **CM4** | Operating expenses, agency fees, and other | Fixed and variable costs land in the tier that matches the **category** you give them — a Marketing-category cost reduces CM3, while an Operating expenses, Agency fees, or Other cost reduces CM4. See [Contribution margin](/get-started/configure-contribution-margin) for how the tiers are used across the P\&L dashboard. ## Frequently asked questions <AccordionGroup> <Accordion title="Do cost changes apply to past orders?"> Yes. When you add or edit a cost, Upstack recalculates matching historical orders within that cost's effective date range. Set start and end dates to control exactly which orders a cost applies to. </Accordion> <Accordion title="What happens if a product has no cost?"> Its cost falls back to your **Default COGS %** from Product Defaults. (The Global Handling Fee is a separate cost that applies on its own, not part of this fallback.) Set the Default COGS % first so every order has a product cost. </Accordion> <Accordion title="Which costs land in which margin tier?"> A cost's category determines its tier: COGS → CM1; Fulfillment, Transaction, Gateway, and Shipping → CM2; Marketing and ad spend → CM3; Operating expenses, Agency Fees, and Other → CM4. Fixed and variable costs follow the same rule — they land in the tier matching their category. </Accordion> <Accordion title="Can I set costs in a different currency?"> Yes. You can enter a cost in its own currency, and Upstack converts it into the order's currency for you. </Accordion> <Accordion title="Who can edit cost settings?"> Admin and owner roles. The Costs section may not be enabled on every account yet — contact the Upstack team if you don't see it. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Contribution margin" icon="layer-group" href="/get-started/configure-contribution-margin"> How CM1–CM4 and the P\&L dashboard use your costs. </Card> <Card title="Manage costs from the CLI" icon="terminal" href="/cli/costs"> Read and update cost configuration with the `upstack costs` command. </Card> <Card title="Attribution and reporting" icon="chart-line" href="/concepts/attribution-and-reporting"> How Upstack attributes conversions and calculates reporting metrics. </Card> <Card title="Costs API" icon="code" href="/api-reference/overview"> Manage cost configuration programmatically. </Card> </CardGroup> # Create an Upstack Data account Source: https://docs.upstackdata.com/get-started/create-an-account Sign up for Upstack Data at app.upstackdata.com/signup to start capturing server-side events from your store. Creating an Upstack account is the first step. You'll set up your workspace, choose a plan, and connect your store. The whole process takes about 5 minutes. ## Sign up <Steps> <Step title="Go to the Upstack signup page"> Open [app.upstackdata.com/signup](https://app.upstackdata.com/signup) in your browser. </Step> <Step title="Create your account"> Enter your email and choose a password. You'll receive a verification email — click the link to confirm your address. </Step> <Step title="Set up your workspace"> Enter your company name and basic details. The workspace name appears in the Upstack dashboard and on billing receipts. </Step> <Step title="Choose a plan"> Select a plan that matches your store volume. You can [compare plans](/billing/plans-and-pricing) and change your selection later from the billing settings page. </Step> <Step title="Add a payment method"> Enter card details through Stripe. Upstack offers a 21-day free trial — your card is not charged until the trial ends. </Step> </Steps> <Tip> **Already have an account?** Sign in at [app.upstackdata.com](https://app.upstackdata.com) instead. If you previously installed Upstack Data through the Shopify App Store, your account was created during the install — sign in with the email you used. </Tip> ## What happens next Once your account is active, you'll connect your store as a data source. The next step depends on your platform: <CardGroup> <Card title="Install on Shopify" href="/get-started/install-on-shopify"> The most common path. Install the Upstack Data Shopify app and enable the tracking pixel. </Card> <Card title="Headless Shopify" href="/installation/headless-shopify"> For Hydrogen, Next.js, Remix, or other custom storefronts. </Card> <Card title="WordPress / GTM" href="/resources/implementing-upstack-data-on-landing-pages"> Install Upstack on WordPress via Google Tag Manager. </Card> <Card title="Checkout Champ" href="/resources/how-to-set-up-upstack-data-on-checkout-champ"> Install Upstack on a Checkout Champ funnel. </Card> </CardGroup> ## Next step <CardGroup> <Card title="Install on Shopify" icon="arrow-right" href="/get-started/install-on-shopify"> Connect your Shopify store and start capturing events. </Card> </CardGroup> # Disable existing tracking Source: https://docs.upstackdata.com/get-started/disable-existing-tracking Remove duplicate pixels, Elevar tags, native Shopify integrations, and third-party trackers after Upstack is confirmed firing. Running two tracking systems at the same time causes duplicate events, inflated attribution, and corrupted ad platform optimization. This is the most critical step in your migration — get the order right. <Warning> **Never disable old tracking before Upstack is confirmed working.** A gap in event data is worse than a brief overlap. Verify Upstack events are firing first (check the Upstack debug view or Meta Pixel Helper), then proceed with the steps below. </Warning> ## Order of operations <Steps> <Step title="Verify Upstack is firing"> Confirm events are flowing in the Upstack dashboard or with Meta Pixel Helper before you touch anything. If Upstack isn't sending events yet, stop here and resolve that first. </Step> <Step title="Disable old Facebook/Meta tags"> Remove or pause your previous tool's Facebook/Meta event tags. This is the highest-priority item — Meta is the most common source of duplicate conversions. </Step> <Step title="Disable old Klaviyo secondary flows"> If your previous tool (Elevar, Triple Whale, etc.) created secondary Klaviyo abandonment flows, disable them. Upstack's flows replace these. See the [Klaviyo destination hub](/destinations/klaviyo) for the replacement flow setup. </Step> <Step title="Disable old TikTok and other ad platform tags"> Pause or remove your previous tool's TikTok, Snapchat, and Google Ads event tags if Upstack is now handling those destinations. </Step> <Step title="Enable any inactive Upstack destinations"> If any Upstack destinations were set to **Inactive** during initial setup, toggle them to **Active** now. </Step> <Step title="Monitor for 24–48 hours"> Watch for duplicate events in your ad platform dashboards. Check event counts in the Upstack dashboard against what each platform reports. If counts roughly double what you expect, a legacy tag is still firing. </Step> </Steps> ## What to disable <AccordionGroup> <Accordion title="Elevar / Google Tag Manager"> Most brands migrating to Upstack are coming from Elevar. Elevar fires events through Google Tag Manager, so you'll disable tracking there. 1. Open **GTM → Tags**. 2. Find Elevar's **Meta/Facebook tags** — pause or disable them. 3. Find Elevar's **Klaviyo tags** (if present) — pause or disable them. 4. **GA4 tags:** Check whether they run through Elevar or are standalone. If standalone, leave them — Upstack does not replace GA4. 5. **Google Ads tags:** Same check. If standalone, leave them. 6. **Save and publish** the GTM container. In Klaviyo, disable Elevar's secondary abandonment flows (Browse, Cart, Checkout). Upstack's flows replace these. </Accordion> <Accordion title="Native Shopify Facebook & Instagram"> 1. In Shopify Admin, go to **Sales Channels → Facebook & Instagram**. 2. Open **Settings → Data Sharing**. 3. Turn data sharing **OFF**. You don't need to uninstall the sales channel. Shop features and your product catalog still work — you're only disabling the pixel/event tracking. For detailed steps, see [How to disable Facebook and Instagram data sharing in Shopify](/guides/facebook-ads/how-to-disable-facebook-and-instagram-data-sharing-in-shopify). </Accordion> <Accordion title="Native Shopify TikTok"> Disable the tracking and pixel features within the TikTok sales channel settings. If you're not using TikTok Shop features (product sync, in-app checkout), you can uninstall the channel entirely. For detailed steps, see [How to disable TikTok data sharing in Shopify](/guides/tiktok-ads/how-to-disable-tiktok-data-sharing-in-shopify). </Accordion> <Accordion title="Feed apps (Symprosis, etc.)"> Feed apps sometimes have tracking features enabled alongside their catalog sync function. These fire extra pixels that duplicate what Upstack sends. **Disable:** * Custom pixels within the feed app * Facebook pixel tracking within the feed app * GA4 tracking within the feed app **Keep:** * Product catalog and feed sync features — these don't conflict with Upstack </Accordion> <Accordion title="Third-party pixel apps"> Uninstall any standalone pixel management apps: * Omega TikTok Pixel * Add Naboo Pixel * Trackify * Any other app whose sole purpose is firing conversion pixels Upstack fully replaces these. </Accordion> <Accordion title="Cookie / GDPR consent banners (US-only brands)"> For stores that only sell to US customers, consider disabling Shopify's cookie consent banner. Consent banners block tracking scripts until a visitor opts in — and most visitors never do. 1. In Shopify Admin, go to **Settings → Privacy → Cookie Banner → Regions**. 2. Set the region to **None**. Removing the banner can increase trackable sessions by 25% or more on low-volume stores. <Warning> **Keep your consent banner** if you have EU or UK customers. GDPR requires consent management for those regions, and removing the banner creates legal exposure. </Warning> </Accordion> <Accordion title="Triple Whale / Northbeam"> These tools can run in parallel with Upstack during a comparison period (30 days recommended). You don't need a hard cutover. **Disable immediately:** * Triple Whale's secondary Klaviyo flows — disable as soon as Upstack's flows go live * Any server-side event forwarding to the same platform Upstack is already sending to (running both tools' CAPI events to Meta simultaneously causes double-counting) **Can keep running:** * The Triple Whale or Northbeam dashboard for attribution comparison during your evaluation period </Accordion> <Accordion title="GA4"> <Info> Upstack does **not** replace GA4. Keep GA4 connected through Shopify's native connector or your standalone GTM setup. </Info> GA4's attribution model differs fundamentally from Meta and Google Ads — the numbers will never match across these systems, and that's expected. GA4 serves a different analytical purpose than ad platform conversion tracking. </Accordion> </AccordionGroup> ## You'll know it's working when... * [ ] Old tracking tags are paused or removed in GTM / Shopify / third-party apps * [ ] Upstack destinations show **Active** status (green) in the dashboard * [ ] Ad platform event counts are stable (not doubled) over a 24–48 hour window * [ ] No duplicate conversion warnings appear in Meta Events Manager diagnostics ## Next step <CardGroup> <Card title="Set up custom events" icon="arrow-right" href="/guides/custom-events/how-to-create-custom-event-triggers"> Send new customer purchase data and other specialized signals to Meta for better optimization. </Card> </CardGroup> ## Related <CardGroup> <Card title="Disable Facebook data sharing in Shopify" icon="meta" href="/guides/facebook-ads/how-to-disable-facebook-and-instagram-data-sharing-in-shopify"> Step-by-step guide to turning off native Shopify Facebook & Instagram data sharing. </Card> <Card title="Disable TikTok data sharing in Shopify" icon="music" href="/guides/tiktok-ads/how-to-disable-tiktok-data-sharing-in-shopify"> How to disable TikTok event tracking in the Shopify sales channel. </Card> <Card title="Disable Snapchat data sharing in Shopify" icon="ghost" href="/guides/snapchat-ads/how-to-disable-snapchat-data-sharing-in-shopify"> How to disable Snapchat event tracking in Shopify. </Card> <Card title="Troubleshooting: Duplicate events" icon="wrench" href="/troubleshooting/duplicate-events"> Diagnose and resolve duplicate conversion events across your ad platforms. </Card> </CardGroup> # Health and wellness brand setup Source: https://docs.upstackdata.com/get-started/health-wellness-setup How Upstack's server-side protective container keeps health and wellness brands compliant with Meta restrictions and prevents pixel flagging. Health and wellness brands — supplements, CBD, wellness products — face unique tracking restrictions from Meta. Standard browser pixels can trigger flagging, ad account restrictions, and blocked purchase events. This guide covers what's different about the Upstack setup for H\&W brands and how the server-side protective container keeps you compliant. ## Why H\&W Brands Need a Different Setup Meta restricts or flags health and wellness brands that send certain event data through standard browser pixels. The consequences escalate quickly: * **Pixel flagging or rejection** — Meta categorizes your domain as restricted and limits event processing * **Ad account restrictions** — campaigns are paused or accounts are disabled without warning * **Purchase events blocked** — your highest-value conversion signal disappears from optimization * **CPAs spike** — costs increase with no clear cause as Meta's algorithm loses signal Upstack handles this with a server-side **protective container** that filters event payloads before Meta sees them. ## How the Protective Container Works The protective container changes the event pipeline so Meta never receives data that triggers health and wellness restrictions: 1. Upstack removes the browser pixel entirely — all events route server-side via CAPI only 2. The protective container strips restricted data fields from event payloads 3. Custom events (e.g., `upstack_hw`) replace standard purchase events for optimization 4. Meta receives clean, compliant data without triggering health and wellness restrictions <Info> You can toggle between the standard and H\&W containers at any time from the Upstack dashboard. If you're unsure which setup you need, Upstack starts with the standard container and switches to H\&W only if needed. </Info> ## Setup Differences from Standard Onboarding The H\&W setup follows the same onboarding flow with three critical differences. Everything else — Shopify install, Google Ads, Klaviyo, TikTok — works the same as standard onboarding. <Warning> **Do NOT connect the Facebook destination yourself.** Wait for Upstack to deploy the server-side protective container first. Connecting Meta before the container is live will expose your domain to flagging. Deployment typically happens the same day as your onboarding call. </Warning> <Steps> <Step title="Wait for the protective container deployment"> After your onboarding call, Upstack deploys the server-side protective container for your account. This typically happens the same day. You'll receive confirmation when the container is live and ready. Do not proceed with the Meta destination setup until you've received this confirmation. </Step> <Step title="Add your domain to Meta's verified domains"> Once the container is live, add your Shopify storefront domain to Meta's verified domains and approval list in **Meta Business Settings → Brand Safety → Domains**. For details on how the domain aliasing works with the protective container, see [How Domain Aliasing Works for Health & Wellness Tracking](/guides/facebook-ads/how-domain-aliasing-works-for-health-wellness-tracking). </Step> <Step title="Confirm before running ads"> Do not run Meta ads until the container is confirmed live and your domain is verified. Running ads before the container is active exposes your pixel to the same flagging risks you're trying to avoid. Once confirmed, Upstack configures custom event mappings that replace standard purchase events. See [Health & Wellness Custom Event Mappings](/guides/facebook-ads/health-and-wellness-custom-event-mappings) for the full mapping reference. </Step> </Steps> ## Advanced Configuration <Accordion title="Recovery timeline for flagged accounts"> If your account has already been flagged by Meta, Upstack's H\&W recovery process can restore your event pipeline: * **100% success rate** on H\&W recovery setups to date * **CPAs typically return to baseline within \~60 days** as Meta's algorithm re-learns with clean data * **Recovery process:** server-side container deployed → browser pixel removed → custom events replace standard events → Meta re-evaluates your domain The timeline depends on how severely your account was flagged. Brands with multiple flags or disabled ad accounts may take longer to fully recover, but the protective container prevents further flagging from day one. </Accordion> <Accordion title="When to use H&W vs. standard setup"> **Use the H\&W container when:** * Your domain is flagged or categorized as health and wellness by Meta * Your purchase event has been rejected * You sell supplements, CBD, wellness products, or anything Meta considers restricted * You've been flagged or restricted multiple times **Standard setup is sufficient when:** * Your brand is throttled or penalized but not categorized as H\&W * You sell products adjacent to H\&W but not in a restricted category Upstack tries the standard container first and switches to H\&W only if needed. You can toggle between standard and H\&W containers at any time. </Accordion> <Accordion title="New Business Manager strategy"> For brands with a thoroughly flagged Business Manager, starting fresh may be the fastest path to recovery: * **Create a new Business Manager** with a new pixel to get a clean slate * **Don't run two pixels from the same ad account** — the newer pixel will retarget the old pixel's funnel and steal conversions * **Recommended approach:** pause old campaigns, clone them, and relaunch with the new pixel * **Alternative:** test with one campaign first before committing to a full migration Combine the new Business Manager with Upstack's protective container to ensure the new pixel stays clean from day one. </Accordion> ## Back to Getting Started <CardGroup> <Card title="Verify End-to-End Delivery" icon="arrow-left" href="/get-started/verify-end-to-end"> Go back to the final verification step and confirm your complete pipeline is working. </Card> </CardGroup> ## Related <CardGroup> <Card title="H&W Custom Event Mappings" icon="table" href="/guides/facebook-ads/health-and-wellness-custom-event-mappings"> Reference for how standard events are remapped to custom events in the protective container. </Card> <Card title="Domain Aliasing for H&W Tracking" icon="globe" href="/guides/facebook-ads/how-domain-aliasing-works-for-health-wellness-tracking"> How Upstack's domain aliasing works alongside the protective container for health and wellness brands. </Card> <Card title="Connect a Destination" icon="plug" href="/get-started/connect-a-destination"> Standard Meta CAPI destination setup for brands not in restricted categories. </Card> <Card title="Conversion API Forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> Learn how Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> </CardGroup> # Install Upstack on Shopify Source: https://docs.upstackdata.com/get-started/install-on-shopify Connect your Shopify store to Upstack from the Upstack dashboard and start capturing server-side events in under 10 minutes. Connect Shopify from inside the Upstack dashboard — not from the Shopify App Store. Sign in to Upstack, open **Data Sources → Shopify**, then authorize the install in your Shopify Admin. From there, enable the theme app extension, add the custom pixel, and verify events. <Info> **Prerequisite:** an active Upstack Data account. If you haven't already, [create your Upstack account](/get-started/create-an-account) before continuing. </Info> <CardGroup> <Card title="Complete Shopify setup guide" icon="arrow-right" href="/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify"> Step-by-step walkthrough with screenshots covering all parts. </Card> </CardGroup> ## Individual step guides <CardGroup> <Card title="Install the app" icon="download" href="/guides/shopify/how-to-download-and-install-upstack-data-app-in-shopify"> Connect your Shopify store from the Upstack dashboard. </Card> <Card title="Enable theme extension" icon="toggle-on" href="/guides/shopify/how-to-ensure-upstack-data-theme-app-extension-is-enabled"> Verify the theme app extension is active in your Shopify theme editor. </Card> <Card title="Install Pixel Helper" icon="puzzle-piece" href="/guides/shopify/how-to-install-upstack-data-pixel-helper"> Install the browser extension to debug pixel events in real time. </Card> <Card title="Pixel privacy settings" icon="shield-halved" href="/guides/shopify/how-to-setup-upstack-custom-pixel-privacy-settings"> Configure consent and privacy settings for the Upstack custom pixel. </Card> </CardGroup> ## Headless Shopify If your storefront runs on Shopify Hydrogen, Next.js, Remix, or another custom framework, the theme app extension won't load. Use the Upstack JavaScript SDK instead. <CardGroup> <Card title="Headless Shopify installation" icon="code" href="/installation/headless-shopify"> Install the Upstack pixel via CDN script or the `@upstackdata/pixel` npm package on Hydrogen, Next.js, Remix, and other custom storefronts. </Card> </CardGroup> ## Alternative: Use the CLI Prefer working from the terminal? The Upstack CLI lets you query data, manage dashboards, and automate workflows without opening the web app. <CardGroup> <Card title="Install the CLI" icon="terminal" href="/cli/install"> Install the `upstack` CLI and configure it with your API key and pixel ID. </Card> </CardGroup> ## Next step <CardGroup> <Card title="Verify events are flowing" icon="arrow-right" href="/get-started/verify-events"> Confirm your store is sending the right events and they appear in the dashboard. </Card> </CardGroup> # Step 4: Validate End-to-End Delivery Source: https://docs.upstackdata.com/get-started/verify-end-to-end Confirm the complete pipeline works — from storefront event to Upstack dashboard to a matched conversion in Meta Events Manager. You've installed the pixel, verified events, and connected Meta CAPI. Now run a single end-to-end test to confirm the full pipeline is working: a storefront action should flow through Upstack and arrive as a matched conversion in Meta. ## What You'll Accomplish Trigger a real event on your Shopify store and trace it through every stage — from the Upstack Live Event Stream to Meta Events Manager — confirming that server-side conversion data is being delivered correctly. ## Prerequisites <Info> **Prerequisites:** * An active Shopify store * The Upstack Data app installed from the Shopify App Store * Your Pixel ID (found in the Upstack dashboard under Settings → Pixel) </Info> You should have completed [Step 3: Connect a Destination](/get-started/connect-a-destination). ## Validation Steps <Steps> <Step title="Prepare your test environment"> Open three tabs: 1. **Upstack Dashboard** — navigate to **Events → Live Event Stream** 2. **Meta Events Manager** — navigate to **Your Pixel → Test Events** and enter your storefront URL 3. **Your Shopify storefront** — use an incognito/private window for a clean session <Info> Using Meta's **Test Events** tab gives you real-time visibility into incoming server events. Events in Test Events show within seconds, while the main Overview tab can have a 20+ minute delay. </Info> </Step> <Step title="Trigger a test purchase or add-to-cart"> On your Shopify storefront, perform a complete flow: 1. Visit a product page (generates `ViewContent`) 2. Add the product to cart (generates `AddToCart`) 3. Begin checkout (generates `InitiateCheckout`) 4. If possible, complete a test purchase using Shopify's [Bogus Gateway](https://help.shopify.com/en/manual/checkout-settings/test-orders) (generates `Purchase`) <Tip> If you can't complete a test purchase, an `AddToCart` event is sufficient to validate the pipeline. The key is confirming the event appears in both Upstack and Meta. </Tip> </Step> <Step title="Confirm the event in Upstack"> Switch to the Upstack Live Event Stream tab. Within a few seconds, you should see the events you just triggered. Click on an event to expand it and verify: * **Event type** matches your action (`AddToCart`, `Purchase`, etc.) * **Pixel ID** is correct * **User data** is populated (especially if you entered shipping details at checkout) * **Destination status** shows the event was forwarded to Meta </Step> <Step title="Confirm the event in Meta Events Manager"> Switch to Meta Events Manager → Test Events. You should see the corresponding server event within 2-5 minutes. Look for: * The event name matches (e.g., `AddToCart` or `Purchase`) * The source shows **Server** (not just Browser) * The event details include user data parameters like `em` (hashed email), `ph` (hashed phone) If you see the event from both Browser and Server sources but only counted once, deduplication is working correctly. </Step> </Steps> ## You'll Know It's Working When... <Tip> Your end-to-end pipeline is validated when a single storefront action produces a matched event in both the Upstack Live Event Stream and Meta Events Manager. The Meta event should show **Server** as the source, include hashed user data parameters, and arrive within 5 minutes of the storefront action. </Tip> If any step fails, refer back to the relevant earlier step: * Events not appearing in Upstack? See [Step 2: Verify Events Are Flowing](/get-started/verify-events) * Events in Upstack but not Meta? See the troubleshooting section in [Step 3: Connect a Destination](/get-started/connect-a-destination) ## Next Step <CardGroup> <Card title="What's Next" icon="arrow-right" href="/overview"> Your core pipeline is live. Explore what to do next — add more destinations, dive into attribution, or configure advanced identity resolution. </Card> </CardGroup> ## Related <CardGroup> <Card title="Events not reaching destination" icon="triangle-exclamation" href="/troubleshooting/events-not-reaching-destination"> Troubleshoot events visible in Upstack but not arriving at Meta, TikTok, or other destinations. </Card> <Card title="Duplicate events" icon="clone" href="/troubleshooting/duplicate-events"> Fix duplicate events, inflated revenue, and doubled conversion counts in your pipeline. </Card> <Card title="EMQ showing zeros" icon="chart-line" href="/guides/facebook-ads/why-is-my-meta-emq-panel-showing-zeros-0-0-10"> Understand why your Meta Event Match Quality panel may show zero values and how to fix it. </Card> </CardGroup> # Step 2: Verify Events Are Flowing Source: https://docs.upstackdata.com/get-started/verify-events Confirm that your Shopify store is sending tracking events to the Upstack pipeline before connecting a destination. Before connecting a destination like Meta CAPI, take a minute to verify that your events are arriving correctly. This saves you from debugging destination issues that are actually source issues. ## What You'll Accomplish Confirm that storefront actions generate events in the Upstack dashboard with the expected event types, URLs, and customer data. ## Prerequisites <Info> **Prerequisites:** * An active Shopify store * The Upstack Data app installed from the Shopify App Store * Your Pixel ID (found in the Upstack dashboard under Settings → Pixel) </Info> You should have already completed [Step 1: Install the Upstack Pixel](/get-started/install-on-shopify). ## Verification Steps <Steps> <Step title="Open the Live Event Stream"> In the Upstack dashboard, navigate to **Events → Live Event Stream**. This view shows events arriving from your store in real time, with the most recent events at the top. Leave this tab open — you'll use it to confirm events as you trigger them. </Step> <Step title="Trigger a test pageview"> Open your Shopify storefront in a new browser tab (or incognito window for a clean session). Visit your store's homepage. Switch back to the Live Event Stream. Within a few seconds, you should see a `PageView` event appear with the URL of your homepage. </Step> <Step title="Trigger additional event types"> Continue browsing your store to generate a range of events: | Action | Expected Event | | --------------------- | ------------------ | | View a product page | `ViewContent` | | Add a product to cart | `AddToCart` | | Begin checkout | `InitiateCheckout` | Verify each event appears in the stream with the correct event type and a populated URL. </Step> <Step title="Inspect an event payload"> Click on any event in the Live Event Stream to expand its details. Confirm the payload includes: * **Pixel ID** — matches the Pixel ID shown in Settings → Pixel * **Event type** — correct for the action you took * **Page URL** — matches the page you visited * **Timestamp** — recent and in the correct timezone * **User data** — if you're logged in as a customer, look for email or customer ID fields </Step> </Steps> ## You'll Know It's Working When... <Tip> You should see at least three different event types (`PageView`, `ViewContent`, `AddToCart`) in the Live Event Stream, each with a valid payload containing your Pixel ID, a page URL, and a recent timestamp. If events appear within seconds of your storefront actions, your pipeline is healthy. </Tip> <Warning> **Missing events?** If you see `PageView` events but not `AddToCart` or `ViewContent`, your Shopify theme may be missing standard event hooks. Check **Shopify Admin → Online Store → Themes → Customize → App Embeds** and ensure Upstack Data is enabled. See [Troubleshooting: Events Not in Dashboard](/troubleshooting/events-not-in-dashboard) for more. </Warning> ## Next Step <CardGroup> <Card title="Step 3: Connect a Destination" icon="arrow-right" href="/get-started/connect-a-destination"> Now that events are flowing into Upstack, connect Meta as your first destination and start sending high-quality server-side conversions to your ad account. </Card> </CardGroup> ## Related <CardGroup> <Card title="Use Pixel Helper" icon="magnifying-glass" href="/guides/shopify/how-to-use-upstack-data-pixel-helper"> Learn how to use the Upstack Pixel Helper browser extension to inspect events firing on your storefront. </Card> <Card title="Install Pixel Helper" icon="puzzle-piece" href="/guides/shopify/how-to-install-upstack-data-pixel-helper"> Install the Upstack Pixel Helper browser extension to debug pixel events in real time. </Card> <Card title="Events not in dashboard" icon="triangle-exclamation" href="/troubleshooting/events-not-in-dashboard"> Troubleshoot missing events in your Upstack dashboard — covers pixel installation, browser blockers, and theme conflicts. </Card> </CardGroup> # Complete How-To Guide for Onboarding AppLovin in Upstack Data Source: https://docs.upstackdata.com/guides/applovin-ads/complete-how-to-guide-for-onboarding-applovin-in-upstack-data Onboard AppLovin Axon in Upstack Data — locate your Pixel ID (Event Key), generate the Conversions API token, and configure the destination for server-side conversion tracking. <Info> **New to Upstack?** Follow the [getting started guide](/get-started/install-on-shopify) for a streamlined onboarding walkthrough. </Info> <Tip> * Configure the **AppLovin destination** in Upstack Data with your **Pixel ID** (Event Key) and **Conversions API access token**. * Verify events appear in the **AppLovin Axon Dashboard** Events section within 5-10 minutes. * Monitor match quality improvements as more identified customers convert. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to an **AppLovin Axon** account * A configured **Axon Pixel** in the [AppLovin Dashboard](https://dash.applovin.com/) * A **Conversions API access token** generated from the Axon Dashboard — see [How to generate your AppLovin CAPI token](/guides/applovin-ads/how-to-generate-applovin-conversion-api-token) <Steps> <Step title="Locate your AppLovin Pixel ID (Event Key)"> In the AppLovin Dashboard, navigate to **Account → General → Keys** to find your **Event Key** (Pixel ID). Help guide: [How to find your AppLovin Pixel ID →](/guides/applovin-ads/how-to-find-applovin-pixel-id) </Step> <Step title="Generate a Conversions API access token"> In the AppLovin Dashboard, navigate to **Account → General → Keys** and generate a new **Conversions API Key**. Help guide: [How to generate your AppLovin CAPI token →](/guides/applovin-ads/how-to-generate-applovin-conversion-api-token) </Step> <Step title="Configure the AppLovin destination in Upstack Data"> In the Upstack dashboard, navigate to **Event Destinations** and add an **AppLovin** destination using your **Pixel ID** and **Conversions API access token**. Help guide: [How to configure the AppLovin destination in Upstack Data →](/guides/applovin-ads/how-to-configure-applovin-destination-in-upstack-data) </Step> <Step title="Verify the full setup is healthy"> Confirm each piece of the setup is working: * In the Upstack dashboard, **Event Destinations** shows your AppLovin destination as **Healthy** (green). * In the [AppLovin Axon Dashboard](https://dash.applovin.com/), the Events section shows recent events arriving via the Conversions API. * Events appear within 5-10 minutes of storefront activity. If anything is unhealthy, check the corresponding help guide above for troubleshooting steps. </Step> </Steps> ## What to expect after setup ### Event delivery timeline * **Events start appearing** in the AppLovin Dashboard within 5-10 minutes of storefront activity. * **Match quality improves** as more identified customers (with email/phone at checkout) convert. * The `dedupe_id` ensures browser Pixel events and server-side CAPI events are not double-counted. ### Reporting differences * Your **AppLovin campaign performance** will likely improve after a few days as the algorithm receives more complete conversion data. * Conversion volume may temporarily fluctuate during the first 48 hours as AppLovin's deduplication logic adjusts to receiving both pixel and CAPI events. <Warning> **Important:** AppLovin's batch API drops the **entire batch** if any single event is invalid. Ensure all events include a `dedupe_id` and at least one user identifier (`aleid`, `axwrt`, `client_id`, `email`, `phone`, or `user_id`). </Warning> <Note> **Need help?** If you encounter any issues during setup or events aren't appearing after 15 minutes, contact our [support team](/support) with your **AppLovin Pixel ID** and we'll help diagnose the problem. </Note> # How to Configure AppLovin Destination in Upstack Data Source: https://docs.upstackdata.com/guides/applovin-ads/how-to-configure-applovin-destination-in-upstack-data Configure the AppLovin Axon destination in Upstack Data with your Pixel ID and Conversions API access token to enable dual tracking via browser pixel and server-side CAPI. <Tip> * In the Upstack dashboard, go to **Event Destinations** and click **+ New Destination**. * Select **AppLovin Axon**. * Enter your **Pixel ID** (Event Key from AppLovin Dashboard). * Paste your **Conversions API access token**. * Click **Create Configuration** and verify the destination shows **Healthy**. </Tip> <Note> **What this setup enables** Setting up the AppLovin destination in Upstack Data enables dual tracking via browser pixel and server-side Conversions API (CAPI), recovering conversions lost to ad blockers, iOS restrictions, and cross-device journeys. </Note> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to an **AppLovin Axon** account * A configured **Axon Pixel** in the [AppLovin Dashboard](https://dash.applovin.com/) — see [How to find your AppLovin Pixel ID](/guides/applovin-ads/how-to-find-applovin-pixel-id) * A **Conversions API access token** — see [How to generate your AppLovin CAPI token](/guides/applovin-ads/how-to-generate-applovin-conversion-api-token) ## Configuration steps <Steps> <Step title="Sign in to Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com/pixel/event-destinations). </Step> <Step title="Open the destination configuration"> In the Upstack dashboard, navigate to **Event Destinations**. Click **+ New Destination** in the top-right of the page. In the **Select a Destination** popup, click **AppLovin Axon**, then click **Next**. </Step> <Step title="Enter your Pixel ID and CAPI token"> Fill in the form: 1. **Pixel ID** — the Event Key identifier for your Axon pixel. Find this in the AppLovin Dashboard under Account → General → Keys. 2. **Conversions API access token** — a secure key generated from the AppLovin Dashboard under Account → General → Keys. <Warning> The Conversions API token is a secure key. Store it securely and never expose it client-side. If the token is compromised, generate a new one in the AppLovin Dashboard. </Warning> <Note> **Need help finding these?** * [How to find your AppLovin Pixel ID](/guides/applovin-ads/how-to-find-applovin-pixel-id) * [How to generate your AppLovin CAPI token](/guides/applovin-ads/how-to-generate-applovin-conversion-api-token) </Note> </Step> <Step title="Configure optional settings"> **Enable Conversion API** — Toggle this on to send events to AppLovin's server-side Conversions API (recommended). **Send User Data** — Toggle this on to include hashed PII (email, phone) for improved match quality. </Step> <Step title="Create the configuration"> Click the **Create Configuration** button. You should see a confirmation message and the AppLovin destination will appear in your **Event Destinations** list. </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, the AppLovin destination card should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**: * Confirm your **Pixel ID** is correct (no leading/trailing spaces). * Confirm your **Conversions API token** was pasted in full (no truncation, no whitespace). * Confirm the token was generated for the same AppLovin account as the Pixel ID. </Step> </Steps> # How to Find your AppLovin Pixel ID Source: https://docs.upstackdata.com/guides/applovin-ads/how-to-find-applovin-pixel-id Find your AppLovin Axon Pixel ID (Event Key) in the AppLovin Dashboard — required to configure the Upstack Data AppLovin destination for server-side conversion forwarding. <Tip> * Sign in to the [AppLovin Dashboard](https://dash.applovin.com/). * Navigate to **Account → General → Keys**. * Locate your **Event Key** (this is your Pixel ID). * Copy the Event Key and paste it into your Upstack AppLovin destination configuration. </Tip> <Note> **What is an AppLovin Pixel ID?** Your **AppLovin Pixel ID** (also called the **Event Key**) is a unique identifier that Upstack Data uses to send conversion data to your AppLovin Axon account. This key is required both for browser-side pixel tracking and server-side Conversions API events. </Note> ## Prerequisites Before you start, you need: * Access to an **AppLovin** account at [dash.applovin.com](https://dash.applovin.com/) * An Axon pixel already set up (or follow the steps below to create one) ## Steps to find your AppLovin Pixel ID <Steps> <Step title="Sign in to the AppLovin Dashboard"> Sign in to the AppLovin Dashboard at [dash.applovin.com](https://dash.applovin.com/). </Step> <Step title="Navigate to Account Settings"> Click on your account menu (typically in the top-right corner) and select **Account** or navigate directly to account settings. </Step> <Step title="Open the Keys section"> In the Account settings, navigate to **General → Keys**. This section contains all your API keys including the Event Key (Pixel ID) and Conversions API Key. </Step> <Step title="Locate your Event Key (Pixel ID)"> Find the **Event Key** in the Keys section. **Example format:** A string of alphanumeric characters (e.g., `abc123def456ghi789`) This Event Key is your Pixel ID that you'll use in Upstack Data. </Step> <Step title="Copy and paste into Upstack Data"> Copy your Event Key and paste it into the **Pixel ID** field in your Upstack AppLovin destination setup. <Tip> Ensure there are no extra spaces before or after the ID. Copy the exact value shown in the dashboard. </Tip> </Step> <Step title="Save the configuration"> Click **Create Configuration** to save the destination. </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, navigate to **Event Destinations**. Your AppLovin destination should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**, double-check that the Pixel ID matches exactly what you see in the AppLovin Dashboard (correct format, no whitespace). </Step> </Steps> <Note> **Next step:** [How to generate your AppLovin CAPI token](/guides/applovin-ads/how-to-generate-applovin-conversion-api-token) </Note> # How to Generate your AppLovin Conversions API Token Source: https://docs.upstackdata.com/guides/applovin-ads/how-to-generate-applovin-conversion-api-token Generate an AppLovin Conversions API access token in the AppLovin Dashboard — required to authenticate the Upstack Data AppLovin destination and forward server-side conversions via the Axon Conversions API. <Tip> * Sign in to the [AppLovin Dashboard](https://dash.applovin.com/). * Navigate to **Account → General → Keys**. * Find or generate a **Conversions API Key**. * Copy the token immediately and paste it into your Upstack AppLovin destination. </Tip> <Note> **What is an AppLovin Conversions API token?** A **Conversions API access token** (also called the **Conversions API Key**) is a secure key that allows Upstack Data to send conversion event data to AppLovin's Axon Conversions API. This key authenticates server-side event requests. </Note> ## Prerequisites Before you start, you need: * **Admin access** to an **AppLovin** account * A configured Axon pixel in the [AppLovin Dashboard](https://dash.applovin.com/) — see [How to find your AppLovin Pixel ID](/guides/applovin-ads/how-to-find-applovin-pixel-id) * An Upstack Data account ready to receive the token ([sign in](https://app.upstackdata.com)) ## Steps to generate your AppLovin CAPI token <Steps> <Step title="Sign in to the AppLovin Dashboard"> Sign in to the AppLovin Dashboard at [dash.applovin.com](https://dash.applovin.com/). </Step> <Step title="Navigate to Account Settings"> Click on your account menu (typically in the top-right corner) and select **Account** or navigate directly to account settings. </Step> <Step title="Open the Keys section"> In the Account settings, navigate to **General → Keys**. This section contains all your API keys including the Event Key (Pixel ID) and Conversions API Key. </Step> <Step title="Find or generate the Conversions API Key"> Look for the **Conversions API Key** in the Keys section. **If you already have one**, you can use the existing key. **If you need to generate a new one:** * Click the option to generate a new Conversions API Key * Follow any prompts to complete the generation </Step> <Step title="Copy your CAPI token"> Copy the Conversions API Key — a string of letters and numbers. <Warning> Copy the token to a secure location. Treat it like a password and never expose it in client-side code or share it publicly. </Warning> </Step> <Step title="Add the token to Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com/pixel/event-destinations) and open your **AppLovin** destination under **Event Destinations**. Paste the token into the **Conversions API access token** field. <Warning> The Conversions API token is sensitive — store it securely. Never expose it in client-side code or share it publicly. </Warning> </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, the AppLovin destination card should show **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**: * Confirm the token was pasted in full (no truncation, no whitespace). * Confirm the token was generated for the same AppLovin account as the Pixel ID. * Confirm the **Pixel ID** matches the Event Key from the same account. </Step> </Steps> <Note> **Need help with the Pixel ID?** See [How to find your AppLovin Pixel ID](/guides/applovin-ads/how-to-find-applovin-pixel-id). </Note> # Destination event mappings in Upstack Source: https://docs.upstackdata.com/guides/custom-events/destination-event-mappings Fine-tune event mappings for a single destination — turn an inherited global mapping off, override it, or add a trigger that only one destination receives. [Global event mappings](/guides/custom-events/global-event-mappings) apply to every destination. When you need one destination to behave differently — skip a mapping, change its rules, or get an event no other destination receives — you do that on the destination itself. ## Prerequisites * A [destination connected](/get-started/connect-a-destination) and saved * Familiarity with [global event mappings](/guides/custom-events/global-event-mappings) (the inherited ones you'll fine-tune here) ## Open the Event Mappings tab Open the destination from **Event Destinations**, then select the **Event Mappings** tab. <Note> The Event Mappings tab appears only after a destination is saved, and it isn't available for **Google Ads** (Google Ads uses Conversion Actions instead). </Note> The tab has two sections: * **Inherited Mappings** — the global mappings this destination receives. * **Custom Triggers** — mappings that belong to this destination only. ## Adjust an inherited mapping Open the **Inherited Mappings** section to see every global mapping this destination inherits. For any one of them you can: * **Turn it off for this destination** — use the switch next to the mapping. The mapping keeps working everywhere else; this destination just stops receiving it. * **Override it** — click **Override** to make a copy you can edit just for this destination. The destination then follows your copy instead of the global version. <Info> Turning a mapping off here only affects this one destination. The global mapping still fires and still reaches your other destinations and your reporting. </Info> ## Add a destination-only custom trigger Open the **Custom Triggers** section and click **Add Custom Trigger** to create a mapping that only this destination receives. It uses the same editor as global mappings — set a **Display name**, **Base event**, **Destination event name**, optional **conditions**, and an optional **value override** — then click **Save custom event**. Each custom trigger in the list can be switched on or off, edited, or removed at any time. ## Save your changes Changes on the Event Mappings tab are staged until you save. Click **Update Configuration** to apply them to the destination. ## Which mapping wins When a destination has its own version of a mapping, that version takes over for that destination: * A **destination override** beats the inherited global mapping — for that one destination. * Everywhere else, the global mapping still applies as usual. ## Related <CardGroup> <Card title="Global event mappings" icon="globe" href="/guides/custom-events/global-event-mappings"> Create a mapping once and send it to every destination. </Card> <Card title="Custom events overview" icon="bolt" href="/guides/custom-events/how-to-create-custom-event-triggers"> What custom events are and when to use them. </Card> <Card title="Connect a destination" icon="plug" href="/get-started/connect-a-destination"> Add Meta, Google, TikTok, Klaviyo, and more. </Card> <Card title="NC & RC Purchase in Meta" icon="meta" href="/guides/facebook-ads/set-up-nc-and-rc-purchase-events-in-meta"> Set up new- and returning-customer purchase events in Meta. </Card> </CardGroup> # Global event mappings in Upstack Source: https://docs.upstackdata.com/guides/custom-events/global-event-mappings Rename or derive an event once and send it to all your connected destinations. Set conditions, add a worked example, and see how global mappings show up in your reporting. Global event mappings let you take an event that's already flowing through Upstack — like a purchase — and send it to your destinations under a new name when it meets conditions you choose. You set it up **once**, and every connected destination inherits it. It's the fastest way to create events like `high_value_purchase` or `subscription_purchase` without touching each destination one by one. ## Prerequisites * An [Upstack Data](https://app.upstackdata.com) account with the pixel installed and events flowing * At least one [destination connected](/get-started/connect-a-destination) * A clear idea of the event you want to create and when it should fire ## What a global event mapping does A mapping watches for a base event (standard or custom), and when its conditions match, it sends that event to your destinations under a new name. For example, a purchase over \$500 can be sent as `high_value_purchase`, so your ad platforms can optimize for high-value buyers specifically. A few things to know up front: * **It applies everywhere.** Every connected destination inherits your global mappings automatically. You can fine-tune or turn one off for a single destination later — see [Destination event mappings](/guides/custom-events/destination-event-mappings). * **It shows up in your reporting.** A global mapping fires as a real event, so it appears in your Upstack analytics and event debugger as well as at your destinations. * **Your standard events keep flowing.** A mapping adds a renamed event — it doesn't replace or stop the original. <Note> Google Ads is the one exception — it doesn't use event mappings. Google Ads relies on its own Conversion Action setup instead. </Note> ## Create a global event mapping <Steps> <Step title="Open Event Mappings"> Go to **Event Destinations** and click the **Event Mappings** button (globe icon) in the page header. The right-side **Global Event Mappings** panel opens, listing any mappings you already have. </Step> <Step title="Add a mapping"> Click **Add Mapping** to open the trigger editor. </Step> <Step title="Name it and pick the base event"> Give the mapping a clear **Display name** (just for you — it isn't sent to destinations). Then choose the **Base event** — pick a standard event like `purchase` from the list, or type your own custom event name. </Step> <Step title="Set the conditions (optional)"> Under **Only when…**, add the conditions that decide when the event fires. Set **Match** to **ALL** or **ANY** of your condition groups, then add conditions inside each group (for example, order value **is greater than** 500). Use **ANY** when any one rule should be enough; use **ALL** when every rule must be true. Leave it empty to fire on every base event. </Step> <Step title="Set the destination event name"> Enter the **Destination event name** — the name your destinations receive. Use lowercase with underscores, e.g. `high_value_purchase`. </Step> <Step title="Choose the value to send (optional)"> Turn on **Override event value** to send profit, margin, a fixed amount, or a custom formula instead of the event's own value — see [Set the value sent with the event](#set-the-value-sent-with-the-event) below. </Step> <Step title="Save"> Click **Save custom event**. The mapping is now live for every connected destination (except Google Ads). </Step> </Steps> ## Worked example: high-value purchases Say you want to optimize for orders over \$500. 1. **Display name:** High value purchase 2. **Base event:** `purchase` 3. **Conditions:** Match **ALL** → order value **is greater than** `500` 4. **Destination event name:** `high_value_purchase` Now whenever a purchase over \$500 comes through, your destinations also receive a `high_value_purchase` event — and it shows up in your Upstack reporting so you can confirm it's firing. <Tip> If you send a revenue event to Meta, pair it with a matching Custom Conversion in Meta Events Manager so you can select it as a campaign optimization goal. See [Approve Meta custom events](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events). </Tip> ## Conditions Conditions (the **Only when…** section) are the filters that decide when a mapping fires. Leave them empty and the mapping fires on **every** base event; add conditions and it fires **only** when they match. Each condition is a **field**, an **operator**, and a **value** — for example *order value* **is greater than** `500`. You can filter on any field the event carries: order and cart values, customer traits, page and campaign context, device, and more. **Operators** include comparisons (*is greater than*, *is at least*, *equals*), text matches (*contains*, *starts with*), list checks (*is in*, *includes any*), and existence checks (*exists*, *does not exist*). The available operators change to fit the field you pick. **Groups.** Conditions live in groups. Set **Match** to **ALL** (every condition in the group must be true) or **ANY** (one is enough). Add multiple groups for more complex logic — for example *(order value > 500)* **OR** *(customer is returning AND category is apparel)*. <Tip> Start simple. A single condition like *order value is greater than 500* covers most high‑value‑purchase mappings. Add more groups only when one rule isn't enough. </Tip> ## Set the value sent with the event By default, Upstack forwards the event's own value. Turn on **Override event value** to send profit, margin, a fixed amount, or a custom formula instead — so your ad platforms optimize on the value that matters to you. See **[Custom event value & formulas](/guides/custom-events/value-and-formulas)** for every value option, the formula builder (Simple vs Advanced), and the full operand reference. ## Frequently asked questions <AccordionGroup> <Accordion title="Do global mappings change my standard events?"> No. A mapping adds a renamed event when its conditions match — your standard events keep flowing exactly as before. </Accordion> <Accordion title="Will the mapped event appear in my reporting?"> Yes. Global mappings fire as real events, so they show up in your Upstack analytics and event debugger in addition to being sent to your destinations. </Accordion> <Accordion title="Does every destination get the mapping?"> Every connected destination inherits it automatically — except Google Ads, which uses Conversion Actions instead. You can disable or override a global mapping for a single destination from that destination's Event Mappings tab. </Accordion> <Accordion title="What if two mappings could apply to the same event?"> Each mapping is evaluated independently — every mapping whose conditions match fires. There's no priority ordering between global mappings, so if you don't want overlap, make each mapping's conditions specific enough that only one matches. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Destination event mappings" icon="sliders" href="/guides/custom-events/destination-event-mappings"> Disable or override a global mapping for a single destination, or add destination-only triggers. </Card> <Card title="Custom events overview" icon="bolt" href="/guides/custom-events/how-to-create-custom-event-triggers"> What custom events are and when to use them. </Card> <Card title="NC & RC Purchase in Meta" icon="meta" href="/guides/facebook-ads/set-up-nc-and-rc-purchase-events-in-meta"> Set up new- and returning-customer purchase events in Meta. </Card> <Card title="Approve Meta custom events" icon="check" href="/guides/facebook-ads/how-to-approve-facebook-meta-custom-events"> Approve and verify custom events in Meta Events Manager. </Card> </CardGroup> # How to create custom event triggers in Upstack Source: https://docs.upstackdata.com/guides/custom-events/how-to-create-custom-event-triggers Track specific actions beyond standard events — quiz completions, subscriptions, category-specific purchases, high-value orders. Send enriched custom events to Facebook, Google, TikTok, and more. Custom event triggers let you go beyond standard ecommerce events — page views, add-to-carts, purchases — to track the specific actions that matter most to your business. This guide explains what custom event triggers are, when to use them, and how they flow through Upstack's server-side pipeline to your ad platforms. ## Prerequisites * An [Upstack Data](https://app.upstackdata.com) account with the Upstack pixel installed and standard events flowing * At least one destination connected (see [Connect a destination](/get-started/connect-a-destination)) — Meta, Google Ads, TikTok, Klaviyo, etc. * A clear definition of the trigger condition you want to track (e.g., new customer purchase, quiz completion, high-value order) * Admin access to the destination platform's event manager (e.g., [Meta Events Manager](https://business.facebook.com/events_manager)) so you can approve custom events and create matching Custom Conversions ## What are custom event triggers? Standard ecommerce tracking covers the basics: someone views a product, adds it to their cart, begins checkout, and completes a purchase. But your business likely has actions that fall outside that flow — quiz completions, email sign-ups, subscription enrollments, or purchases from a specific product category. Custom event triggers let you define those actions as trackable events in Upstack. Once configured, they flow through the same server-side pipeline as your standard events: enriched with identity data, matched to user profiles, and forwarded to your connected destinations (Meta, Google Ads, TikTok, and others). This means you can tell Meta "this person completed a quiz" or "this was a first-time customer purchase" with the same data quality and identity enrichment your standard purchase events receive. <Info> Custom events complement standard tracking — they don't replace it. Keep sending the standard `Purchase` event alongside any custom variant like `nc_purchase`. Ad platforms rely on the standard event for baseline optimization and reporting. </Info> ## Why custom event triggers matter Custom events unlock capabilities that standard tracking cannot: * **New customer acquisition optimization.** Send a dedicated event when a first-time customer purchases, so Meta or Google can optimize for acquiring net-new buyers — not just driving repeat orders. * **Category-level optimization.** If you sell across multiple product categories (e.g., skincare and supplements), purchase events scoped per category let ad platforms optimize for the right products. * **Funnel-stage tracking.** Track mid-funnel actions like quiz completions or email captures as conversion events, giving ad platforms more signal about user intent earlier in the journey. * **High-value action identification.** Define events for actions that predict high lifetime value — subscribing, purchasing a bundle, or hitting a spend threshold. ## Common use cases <AccordionGroup> <Accordion title="New customer purchase (nc_purchase)"> Fires only when an order comes from a customer with no prior Shopify order history. The most popular custom event — it lets Meta and Google optimize for net-new customer acquisition rather than total purchases. See [Setting up new customer purchase metrics in Meta Ads Manager](/guides/facebook-ads/complete-how-to-guide-for-setting-up-new-customer-purchase-metrics-in-facebook-meta-ads-manager). </Accordion> <Accordion title="Returning customer purchase (rc_purchase)"> The complement to `nc_purchase` — fires when a customer with existing order history makes a purchase. Useful for building retargeting audiences or measuring retention campaign performance. </Accordion> <Accordion title="Category-specific purchases"> Fires when a purchase includes products from a specific collection or product type. A brand selling apparel and accessories might create `apparel_purchase` and `accessories_purchase` events to let Meta optimize separately for each category. </Accordion> <Accordion title="Quiz or form completion"> Fires when a customer completes an on-site quiz, survey, or lead capture form. Gives ad platforms a mid-funnel signal that helps them find users more likely to engage deeply with your brand. </Accordion> <Accordion title="Subscription enrollment"> Fires when a customer signs up for a subscription product. Especially valuable for brands where subscription customers have significantly higher lifetime value. </Accordion> <Accordion title="High-value purchase"> Fires when an order exceeds a specified dollar threshold (e.g., orders over \$150). Lets ad platforms optimize for higher-AOV customers. </Accordion> </AccordionGroup> ## How custom events flow through Upstack Custom events follow the same path as standard events: <Steps> <Step title="Trigger condition is met"> The action you defined occurs — a new customer makes a purchase, a quiz is completed, a high-value order is placed. </Step> <Step title="Upstack captures and enriches the event"> The event runs through Upstack's server-side pipeline, where identity resolution attaches available user data — email, phone, IP, browser fingerprint, click IDs. </Step> <Step title="Event is sent to destinations"> The enriched event is delivered to your connected destinations via their server-side APIs — Meta CAPI, Google Ads offline conversions, TikTok Events API, and others. </Step> <Step title="Ad platforms match the event"> The destination uses the identity parameters to match the event to a user profile. The richer the identity data, the higher the match quality. </Step> </Steps> Because custom events go through the same enrichment pipeline, they benefit from the same identity resolution and data quality as your standard events. ## Set them up yourself You can create and manage custom event triggers directly in Upstack — no onboarding ticket required. There are two places to do it, depending on how widely you want the event to apply: <CardGroup> <Card title="Global event mappings" icon="globe" href="/guides/custom-events/global-event-mappings"> Create a trigger once and send it to every connected destination. Best for events you want everywhere, like `high_value_purchase`. </Card> <Card title="Destination event mappings" icon="sliders" href="/guides/custom-events/destination-event-mappings"> Turn an inherited trigger off, override it, or add a trigger that only one destination receives. </Card> </CardGroup> In both places you set a display name, the base event, the destination event name, the conditions that decide when it fires, and — optionally — the [value sent with the event](/guides/custom-events/global-event-mappings#set-the-value-sent-with-the-event) (profit, margin, a fixed amount, or a custom formula). The two guides above walk through every field with examples. <Note> After your event is firing, create a matching Custom Conversion in your ad platform (for Meta, see [Approve Meta custom events](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events)) so you can select it as a campaign optimization goal. </Note> ## Best practices ### Naming conventions * Use lowercase with underscores: `nc_purchase`, `quiz_complete`, `high_value_order`. * Keep names short but descriptive — ad platform UIs have limited space for event names. * Be consistent. If you use `nc_purchase` for new customer purchase, use `rc_purchase` for returning — not `returning_customer_buy`. ### Start with high-impact events Don't create a dozen custom events on day one. Start with the one or two that will most directly improve your ad optimization: * If your primary goal is new customer acquisition, start with `nc_purchase`. * If you sell across distinct categories, start with category-specific purchase events. * If you have a quiz-driven funnel, add quiz completion early. ### Validate before scaling After creating a custom event, verify it's firing correctly and being received by your destination platforms before building ad campaigns around it: * In the [Upstack dashboard](https://app.upstackdata.com) under **Event Health**, confirm the custom event appears with the expected name and parameters. * In your destination's event manager ([Meta Events Manager](https://business.facebook.com/events_manager), Google Ads conversions, TikTok Events Manager, etc.), confirm the event is arriving with the expected parameters. * Trigger the event in a controlled test (e.g., place a test order matching your condition) and confirm it shows up end-to-end before scaling spend. ### Avoid duplicating standard events Custom events should complement standard tracking. Keep sending the standard `Purchase` event alongside any custom purchase events like `nc_purchase`. Ad platforms rely on the standard event for baseline optimization and reporting. ### Include value parameters Whenever a custom event is tied to revenue (like a purchase event), include the value and currency parameters. This lets ad platforms calculate ROAS for campaigns optimized toward that event. <Tip> **Pair every revenue-bearing custom event with a Custom Conversion in Meta.** The custom event populates Meta's pipeline; the Custom Conversion is what you actually select as a campaign optimization goal. See [How to approve Meta custom events](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events). </Tip> ## Frequently asked questions <AccordionGroup> <Accordion title="Do custom events get the same identity enrichment as standard events?"> Yes. Custom events flow through the same Upstack pipeline as standard events, receiving the same identity resolution, data enrichment, and server-side delivery. </Accordion> <Accordion title="How many custom events can I create?"> There is no hard limit in Upstack, but ad platforms have their own. Meta, for example, allows up to 100 custom conversions per ad account. Focus on the events that meaningfully improve your optimization. </Accordion> <Accordion title="Will custom events affect my Event Match Quality (EMQ)?"> Custom events are scored separately from standard events in Meta's system. They benefit from the same identity parameters Upstack attaches, so they should have similar match quality to your standard events. </Accordion> <Accordion title="Can I send the same custom event to multiple destinations?"> Yes. When you configure a custom event, you can map it to any of your connected destinations. The same event can be sent to Meta, Google Ads, TikTok, and others simultaneously. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Global event mappings" icon="globe" href="/guides/custom-events/global-event-mappings"> Create a trigger once and send it to every connected destination. </Card> <Card title="Destination event mappings" icon="sliders" href="/guides/custom-events/destination-event-mappings"> Disable, override, or add triggers for a single destination. </Card> <Card title="NC & RC Purchase in Meta" icon="meta" href="/guides/facebook-ads/set-up-nc-and-rc-purchase-events-in-meta"> Set up new- and returning-customer purchase events in Meta. </Card> <Card title="Custom events data dictionary" icon="book" href="/pixel/events/custom-events"> Reference for custom event names, parameters, and payloads. </Card> <Card title="Approve Meta custom events" icon="check" href="/guides/facebook-ads/how-to-approve-facebook-meta-custom-events"> Approve and verify custom events in Meta Events Manager. </Card> </CardGroup> # Custom event value & formulas in Upstack Source: https://docs.upstackdata.com/guides/custom-events/value-and-formulas Override the value sent with a custom event — send profit, margin, a fixed amount, or a custom formula so ad platforms optimize on the value that matters to you. By default, Upstack forwards the event's own value to your destinations. You can **override** it so your ad platforms optimize on the value that matters to you — profit instead of revenue, a fixed lead value, or a number you compute yourself. This is the foundation of value‑based bidding. You set this while creating or editing a mapping (see [Global event mappings](/guides/custom-events/global-event-mappings) and [Destination event mappings](/guides/custom-events/destination-event-mappings)). Turn on **Override event value**, then choose under **Set value to**. ## Value options | Option | What it sends | Requirements | | --------------------------- | ----------------------------------------------------------- | ------------------------------------ | | **Event value** | The value already on the event (the default — no override). | — | | **Net Revenue** | Revenue after discounts and refunds. | Shopify order data · purchase events | | **CM1 (Gross Margin)** | Net revenue minus product cost (COGS). | Shopify order data · purchase events | | **CM2 (After Fulfillment)** | CM1 minus shipping, handling, and fees. | Shopify order data · purchase events | | **Fixed value** | A set amount you choose (e.g. a flat lead value). | — | | **Custom formula** | A value you build yourself. | See below | The revenue and profit presets are computed per order from your [cost settings](/get-started/cost-settings). They require Shopify order data and apply to purchase events. Value‑bearing events like `add_to_cart` can use **Net Revenue** (revenue only — no cost). <Note> Cost- and revenue-based options need Shopify order data. On non‑Shopify accounts you can still use **Fixed value** or a **Custom formula** over your own `data.*` fields. </Note> ## Custom formula The formula builder has two modes: * **Simple builder** — start with a value, then adjust it step by step (e.g. **Event value × 0.7**). Each part is a **Metric** (a known measure), a **Field** (a custom event field, entered as `data.fieldName`), or a **Number**. Steps apply left to right, like a calculator. * **Advanced** — write the raw formula directly, with autocomplete for variables. Use `+ − * /` and parentheses. ### Operands you can reference | Operand | Meaning | Available on | | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------------- | | `data.value` | The value already on the event. | Every event | | `data.<field>` | Any custom field on the event (e.g. `data.leadValue`). | Every event | | `orders.gross_revenue` | Gross revenue before discounts and refunds. | Shopify purchase | | `orders.net_revenue` | Revenue after discounts and refunds. | Shopify purchase | | `orders.subtotal`, `orders.tax`, `orders.discount_amount`, `orders.refund_amount`, `orders.units` | Order revenue components. | Shopify purchase | | `orders.cogs`, `orders.other_cogs` | Cost of goods sold. | Shopify purchase | | `orders.shipping_cost`, `orders.handling_cost`, `orders.other_fulfillment_cost` | Fulfillment costs. | Shopify purchase | | `orders.gateway_cost`, `orders.other_transaction_cost` | Transaction/gateway fees. | Shopify purchase | Cost operands (`orders.cogs`, `orders.shipping_cost`, …) are only available on purchase events, where full order cost data exists. ### Examples | Goal | Formula | | ---------------------------------------- | ---------------------------------- | | Send 70% of the event value | `data.value * 0.7` | | Send profit (revenue minus product cost) | `orders.net_revenue - orders.cogs` | | Subtract a flat fee from the value | `data.value - 15` | | Scale a custom lead value | `data.leadValue * 0.4` | <Note> **A missing field skips the formula — it doesn't zero your value.** If an event doesn't carry a field your formula references (say `data.leadValue` on an event that didn't send it), Upstack skips the override and forwards the event's own value instead, so a missing field never overwrites a real value with `0`. A field that *is* present but genuinely `0` is used as `0`. Still, reference only fields your events reliably send, so the formula applies when you expect it to. </Note> ## Related <CardGroup> <Card title="Global event mappings" icon="globe" href="/guides/custom-events/global-event-mappings"> Create a mapping once and send it to every destination. </Card> <Card title="Cost settings" icon="calculator" href="/get-started/cost-settings"> Configure the costs behind Net Revenue, CM1, and CM2. </Card> <Card title="Custom events overview" icon="bolt" href="/guides/custom-events/how-to-create-custom-event-triggers"> What custom events are and when to use them. </Card> <Card title="Approve Meta custom events" icon="check" href="/guides/facebook-ads/how-to-approve-facebook-meta-custom-events"> Approve and verify custom events in Meta Events Manager. </Card> </CardGroup> # Complete How-To Guide for Onboarding Facebook (Meta) in Upstack Data Source: https://docs.upstackdata.com/guides/facebook-ads/complete-how-to-guide-for-onboarding-facebook-meta-in-upstack-data Onboard Facebook (Meta) Ads in Upstack Data — connect your Pixel and Conversions API, disable duplicate tracking, configure NC-ROAS, and verify events flow through to Meta Events Manager. <Info> **New to Upstack?** Follow the [getting started guide](/get-started/install-on-shopify) for a streamlined onboarding walkthrough. </Info> <Tip> * Configure the **Meta destination** in Upstack Data with your **Pixel ID** and **CAPI token**. * Disable **Facebook & Instagram data sharing** in Shopify to prevent duplicate events. * Set up the **NC Purchase** custom conversion and share it with your ad accounts. * Add **NC-ROAS** and other new-customer columns to Meta Ads Manager. * Monitor **Event Match Quality** improvements over 7–10 days. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to a **Meta Business Manager** account * A configured **Meta Pixel** in [Meta Events Manager](https://business.facebook.com/events_manager) * A **CAPI token** generated from that pixel — see [How to generate your CAPI token](/guides/facebook-ads/how-to-generate-my-facebook-conversion-api-key) * Shopify owner/staff access (for the duplicate-events cleanup step) <Steps> <Step title="Configure the Meta destination in Upstack Data"> In the Upstack dashboard, navigate to **Event Destinations** and add a **Facebook Advertising** destination using your **Pixel ID** (15–16 digit number, no prefix) and **CAPI token** (starts with `EAA`). Help guide: [How to configure the Meta Pixel destination in Upstack Data →](/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data) </Step> <Step title="Disable Facebook & Instagram data sharing in Shopify"> <Warning> You must disable all other Meta pixel integrations to prevent duplicate events. Multiple active pixels inflate conversion metrics and harm campaign optimization. </Warning> Help guide: [How to disable Facebook and Instagram data sharing in Shopify →](/guides/facebook-ads/how-to-disable-facebook-and-instagram-data-sharing-in-shopify) **Additional pixels to check and disable:** * Native Shopify Facebook & Instagram sales channel pixel * Third-party Facebook pixel apps in Shopify * Manual pixel code in your theme files (`theme.liquid`, header snippets) * Facebook pixel tags inside Google Tag Manager </Step> <Step title="Set up new-customer purchase metrics in Meta Ads Manager"> **Key metrics you'll configure:** * **NC-ROAS** (New Customer Return on Ad Spend) — revenue from new customers only * **NC-CPA** (New Customer Cost Per Acquisition) — cost to acquire each new customer Help guide: [How to set up new-customer purchase metrics in Meta Ads Manager →](/guides/facebook-ads/complete-how-to-guide-for-setting-up-new-customer-purchase-metrics-in-facebook-meta-ads-manager) </Step> <Step title="Verify the full setup is healthy"> Confirm each piece of the setup is working: * In the Upstack dashboard, **Event Destinations** shows your Meta destination as **Healthy** (green). * In [Meta Events Manager](https://business.facebook.com/events_manager), the pixel shows recent events with the **Server** connection label. * In Meta Ads Manager, the **NC Purchase** custom conversion is visible and the **NC-ROAS** custom metric appears in your column layout. If anything is unhealthy, check the corresponding help guide above for troubleshooting steps. </Step> </Steps> ## What to expect after setup ### Event Match Quality timeline * **Event Match Quality (EMQ)** scores start to improve in 2–3 days and normalize over 7–10 days. * You can typically expect a 1–2 point increase on lower-funnel events (PageView, ViewContent, AddToCart). * The **Purchase** EMQ score will remain largely unchanged — at checkout, all match parameters (email, name, address) are already being sent to Meta. ### Normal warnings and notifications **Red triangle ⚠️ warnings in Meta Events Manager** You may see new warnings appear next to your events in Meta Events Manager during the first few days. These are **normal** and **require no action**. They appear because: * Meta detects the change in data source from the Shopify sales channel to Upstack Data * Meta recognizes a different set of parameter configurations * Meta's algorithm is adjusting to the new data format <img alt="Meta Events Manager showing warning triangles during initial data adjustment" /> <Note> **What to do:** Monitor your events to confirm they're firing correctly, but avoid making changes based solely on these warnings. </Note> <Note> **Need help?** If you encounter any issues during setup or don't see expected improvements after 10 days, contact our support team with your **Meta Pixel ID** and we'll help diagnose the problem. </Note> # Complete How-To Guide for Setting up New Customer Purchase Metrics in Facebook (Meta) Ads Manager Source: https://docs.upstackdata.com/guides/facebook-ads/complete-how-to-guide-for-setting-up-new-customer-purchase-metrics-in-facebook-meta-ads-manager Set up the New Customer Purchase conversion in Facebook (Meta) Ads Manager to optimize campaigns for first-time buyers and report NC-ROAS alongside total ROAS. <Tip> * Verify the **ncPurchase** event in [Meta Events Manager](https://business.facebook.com/events_manager). * Create the **NC Purchase** custom conversion and optimize it for **Purchase**. * Share the custom conversion with every Meta ad account that needs it. * In [Meta Ads Manager](https://adsmanager.facebook.com), customize columns to add NC Purchase metrics. * Create the **NC-ROAS** custom metric: `NC Purchase Conversion Value ÷ Amount spent`. </Tip> ## Prerequisites Before you start, you need: * The **Meta destination** configured in Upstack Data — see [How to configure the Meta Pixel destination](/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data) * At least one real new-customer purchase already processed so the **ncPurchase** event appears in Meta Events Manager * Admin access to the **Meta Business Manager** that owns the pixel and to every ad account you'll share the conversion with ## What you'll achieve After completing all three parts below, **Meta Ads Manager** will display new-customer metrics — **NC-ROAS** (New Customer Return on Ad Spend), **Cost per NC Purchase**, and **Total NC Purchases** — directly in your campaigns, ad sets, and ads tables. ## Setup process overview Set up new-customer purchase tracking in three parts. Complete them in order — later steps depend on earlier ones. ### Part 1 — Verify the ncPurchase event Before you can create any custom conversions, the **ncPurchase** event must be verified in Meta Events Manager. Guide to complete this step: [How to verify the NC Purchase event in Meta Events Manager →](/guides/facebook-ads/how-to-verify-the-nc-purchase-event-in-facebook-meta-events-manager) ### Part 2 — Create and share the custom conversion Once **ncPurchase** is verified, create the **NC Purchase** custom conversion and share it with your ad accounts. Guide to complete this step: [How to create and share the NC Purchase custom conversion →](/guides/facebook-ads/how-to-create-and-share-nc-purchase-custom-conversion-in-facebook-meta) ### Part 3 — Add metrics to Meta Ads Manager Configure your Ads Manager columns to display the NC Purchase metrics and create the **NC-ROAS** custom metric. Guide to complete this step: [How to add NC Purchase metrics and NC-ROAS to Meta Ads Manager →](/guides/facebook-ads/how-to-add-nc-purchase-metrics-and-nc-roas-to-facebook-meta-ads-manager) ## Verify the setup is complete Once you've finished all three parts, confirm: * In [Meta Events Manager](https://business.facebook.com/events_manager), the **ncPurchase** event has no red triangle warning and is listed as **Active**. * In **Custom Conversions**, **NC Purchase** is shared with the ad accounts you selected. * In your Meta Ads Manager column layout, **NC Purchase (Total)**, **NC Purchase (Cost)**, and **NC-ROAS** are all visible. <Note> **Done 🎉** Initially, the new columns may show **0** or **—** because Meta does **not** retroactively attribute custom conversions from before they were created. Data starts populating for new-customer purchases that occur **after** the conversion was created and shared. Allow 24–48 hours of new traffic before judging the values. </Note> # Health and Wellness Custom Event Mappings Source: https://docs.upstackdata.com/guides/facebook-ads/health-and-wellness-custom-event-mappings Map Upstack Data events to Meta Custom Events for Health and Wellness brands so server-side conversions reach Meta CAPI without violating Meta's restricted-category rules. ## Prerequisites Before you start, you need: * A configured **Health & Wellness container** in Upstack Data (created and activated by support) * Admin access to a **Meta Business Manager** account * Your store domain **verified and approved** in [Meta Events Manager](https://business.facebook.com/events_manager) → **Domains** * Access to email so you can request aliasing activation from Upstack support ## Configuration steps ### Part 1 — Set up domain aliasing and configure the Health & Wellness container 1. **Set up and activate your Health & Wellness container.** Confirm the container has been fully created and activated by Upstack support before continuing. 2. **Verify and approve your store domain in Meta Events Manager.** * In [Meta Events Manager](https://business.facebook.com/events_manager), navigate to **Domains** in the left-hand menu. * Add your store domain and complete Meta's domain verification process (DNS or meta-tag). * Domain approval is **required** before aliasing can be applied. 3. **Apply domain aliasing (Health & Wellness scrubbing).** Once your domain has been verified, Upstack implements aliasing so events from your store are properly tracked under the Health & Wellness container. 4. **Enable custom event optimization.** After aliasing is active, you can optimize ad campaigns for the custom purchase event **`UPSTACK_HW_6117d13b`** (the Health & Wellness alias for the Purchase event). See the full mapping in Part 2 below. 5. **Request domain aliasing activation for standard funnel events.** After completing domain verification, email [support@upstackdata.com](mailto:support@upstackdata.com) and ask us to enable domain aliasing for your standard funnel events. ### Part 2 — Health & Wellness custom event mappings Below are the Health & Wellness pixel mappings. Standard event names are remapped to opaque `UPSTACK_HW_*` custom event names so Meta does not associate them with restricted Health & Wellness categories. ```text theme={null} Health & Wellness Pixel Mappings ================================ PageView -> PageView ViewContent -> ViewContent ViewCategory -> view_category AddToCart -> UPSTACK_HW_de792bda InitiateCheckout -> UPSTACK_HW_d823e4ff Purchase -> UPSTACK_HW_6117d13b Lead -> UPSTACK_HW_289161cb Schedule -> UPSTACK_HW_5a3811fb Complete Registration -> UPSTACK_HW_895b83ff Contact -> UPSTACK_HW_4c62e638 Invite Meeting Scheduled -> UPSTACK_HW_529b7e00 AddPaymentInfo -> UPSTACK_HW_9984f5f9 AddShippingInfo -> UPSTACK_HW_3c4012cc All Purchase -> UPSTACK_HW_f0e986fc NC Purchase -> UPSTACK_HW_fa2b3354 RC Purchase -> UPSTACK_HW_5ec76558 ``` ### Part 3 — Approve the custom events in Meta #### Why event approval is required <Note> Custom events showing ⚠️ red triangle warnings must be approved in Meta Events Manager. Until approved, the events won't be available for ad delivery optimization, audiences, or campaign reporting. The approval flow simply confirms that you acknowledge the custom event is legitimate for your business. </Note> Help guide to complete this step: [How to approve Meta custom events →](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events) ### Verify the setup is working After approval, confirm the Health & Wellness mappings are flowing correctly: * In [Meta Events Manager](https://business.facebook.com/events_manager), open your pixel and confirm the `UPSTACK_HW_*` events appear in the events list with the **Server** connection label. * None of the listed events should show a red triangle warning. * In **Custom Conversions**, you can now create conversions targeting `UPSTACK_HW_6117d13b` for Purchase optimization. # How do I find my Facebook Ads Pixel (Dataset) ID? Source: https://docs.upstackdata.com/guides/facebook-ads/how-do-i-find-my-facebook-ads-pixel-dataset-id Find your Facebook (Meta) Pixel/Dataset ID in Meta Events Manager to configure the Upstack Data Meta Ads destination for server-side tracking. <Tip> * Sign in to [Meta Events Manager](https://business.facebook.com/events_manager) and locate your pixel. * Click the pixel name, then open the **Settings** tab. * Copy the **Pixel ID** — a 15–16 digit number, no prefix (e.g., `123456789012345`). * Paste it into your Upstack Meta destination configuration. </Tip> <Note> **What is a Meta Pixel ID?** Your **Meta Pixel ID** (sometimes shown as "Dataset ID" inside Meta Events Manager) is a 15–16 digit number Upstack Data uses to send conversion data to your Meta ad account. Meta Pixel IDs have **no prefix** — that's how they differ from Google Ads conversion IDs (which start with `AW-`). </Note> ## Prerequisites Before you start, you need: * Access to a **Meta Business Manager** account * A pixel already created in [Meta Events Manager](https://business.facebook.com/events_manager) (or follow the create-pixel steps below) ## Steps to find your Meta Pixel ID <Steps> <Step title="Sign in to Meta Events Manager"> Sign in to Meta Events Manager at [business.facebook.com/events\_manager](https://business.facebook.com/events_manager). </Step> <Step title="Find or create your pixel"> **If you already have a pixel**, you'll see it listed in the left-hand **Data Sources** panel — proceed to the next step. **If you need to create one:** * Click the green **Connect Data Sources** button * Select **Web** * Click **Next** or **Get Started** * Follow the instructions to create a new Meta Pixel <img alt="Meta Events Manager with Connect Data Sources button" /> <img alt="Select Web as data source type in Meta Events Manager" /> </Step> <Step title="Open the pixel overview"> In the **Data Sources** list, click the pixel's name. You'll land on the pixel's **Overview** page. </Step> <Step title="Locate your Pixel ID"> On the pixel **Overview** page, click the **Settings** tab in the left-hand menu. On the **Settings** tab, locate **Dataset ID** at the top of the page. This is your **Pixel ID** — a 15–16 digit number with no prefix. <img alt="Meta Pixel Settings page showing Dataset ID at the top" /> **Example format:** `123456789012345` </Step> <Step title="Copy and paste into Upstack Data"> Copy your Pixel ID and paste it into the **Pixel ID** field in your Upstack Meta destination setup. <img alt="Upstack Meta destination configuration with Pixel ID field" /> <Tip> Ensure there are no extra spaces before or after the ID. The value should be exactly 15 or 16 digits with no `AW-` or other prefix. </Tip> </Step> <Step title="Save the configuration"> Click **Create Configuration** to save the destination. <img alt="Create Configuration button to save Meta destination setup" /> </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, navigate to **Event Destinations**. Your Meta destination should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**, double-check that the Pixel ID matches exactly what you see in Meta Events Manager (no prefix, no whitespace). </Step> </Steps> <Note> **Next step:** [How to generate your CAPI token](/guides/facebook-ads/how-to-generate-my-facebook-conversion-api-key) </Note> # How Domain Aliasing Works for Health & Wellness Tracking Source: https://docs.upstackdata.com/guides/facebook-ads/how-domain-aliasing-works-for-health-wellness-tracking Bypass Meta's Health & Wellness domain flag with Upstack's alias domain — replacing event source URLs so server-side events deliver cleanly without triggering category restrictions. ### The Short Version Meta's Health & Wellness flag lives on your **domain**, not your pixel. Any pixel that receives events from a flagged domain inherits the flag — even a brand-new pixel. Domain aliasing solves this by routing all events through a clean, unflagged domain so Meta never associates your new pixel with the restricted one. ### Why the Flag Is Domain-Level (and Why That Matters) When Meta flags a store under Health & Wellness, the flag is applied to the **root domain** (e.g., `yourstore.com`). This is a critical detail that catches many brands off guard. Here's what it means in practice: **Creating a new pixel doesn't help.** If you create a fresh pixel and start sending events from `yourstore.com`, that new pixel gets flagged too. The flag follows the domain, not the pixel ID. **Subdomains don't help.** Sending events from `shop.yourstore.com` or `checkout.yourstore.com` still traces back to the same root domain. Meta's systems resolve subdomains to their parent. **Changing your Shopify domain doesn't help (usually).** If you switch from a `.myshopify.com` domain to a custom domain, you're still operating on a domain that Meta can flag. And if the custom domain was already flagged, it stays flagged regardless of what platform it's on. **The flag doesn't expire on its own.** There is no known timeline for Meta to automatically remove a Health & Wellness flag. Some brands have reported flags persisting for months or longer, even after removing products. This is why aliasing is essential — it's the only way to present Meta with a domain that has no H\&W history. ### How Domain Aliasing Works Domain aliasing is straightforward in concept: every event sent to Meta reports a different domain as its origin. Instead of Meta seeing events from `yourstore.com`, it sees events from `youraliasdomain.com` — a clean domain with no flag history. ### The Technical Mechanics Every Conversions API event sent to Meta includes a field called `event_source_url`. This tells Meta which web page the event came from. In a normal setup, this would be something like: <Note> **Before aliasing:** `event_source_url`: [https://yourstore.com/products/daily-vitamin-pack](https://yourstore.com/products/daily-vitamin-pack) </Note> With aliasing active, Upstack replaces this field before sending the event: <Note> **After aliasing:** `event_source_url`: [https://youraliasdomain.com/](https://youraliasdomain.com/) </Note> Meta receives the event, checks the `event_source_url`, and associates it with the alias domain — which is clean, compliant, and unflagged. ### What Meta's Bot Sees Meta doesn't just accept the `event_source_url` at face value. Its compliance bot periodically visits the domain to verify what's there. When it visits your alias domain, it finds: * A simple, compliant landing page with a generic headline and an image * No health or wellness product content * No supplement terminology * No links to your flagged store This is exactly what Meta expects to see from a non-H\&W domain. The events pass through without triggering any flags. ### What Doesn't Change Aliasing only affects the `event_source_url` field in the CAPI payload. Everything else remains accurate: * **User identifiers** (hashed email, phone, click ID) still match the real customer * **Event timing** still reflects when the action actually happened * **Conversion values** still reflect real purchase amounts * **Attribution** still connects the conversion to the correct ad click The alias domain is purely a compliance layer. It doesn't affect the accuracy of your tracking or the quality of your attribution data. ### What Makes a Good Alias Domain The alias domain needs to satisfy Meta's compliance checks without raising any red flags. ### It Must Be a Root Domain `youraliasdomain.com` works. `alias.yourstore.com` does not. Meta resolves subdomains to their root, so a subdomain of a flagged domain is still associated with the flag. The alias must be an entirely separate root domain. ### It Must Be New to Meta The domain should have no prior history with Meta's ad system. Don't reuse an old domain, a domain from a previous brand, or a domain that was ever connected to a Meta pixel. Register something fresh. ### It Must Have a Compliant Landing Page When Meta's bot visits, it needs to find a page that looks like a normal, non-health website. A single page with a generic headline and a stock image is sufficient. The page does not need to be functional — no forms, no checkout, no navigation. What to avoid on the page: * Health, wellness, supplement, or medical terminology * Product images of pills, capsules, powders, or health products * Links to your real store * Any content that could be interpreted as health-related ### It Must Stay Live Meta's bot can revisit the alias domain at any time. If the domain expires or the landing page goes down, Meta may flag the events as coming from an invalid source, which could disrupt your tracking. ### How Aliasing Fits into the Full Solution Domain aliasing handles one specific problem: preventing the flagged domain from tainting your new pixel. But it works in tandem with the other three components: **Without server-side-only tracking,** the browser pixel would still fire from your real domain, sending the real `event_source_url` directly to Meta — bypassing the alias entirely. **Without data sanitization,** even though the domain looks clean, the event payload would still contain product names and URLs from your flagged store. Meta's classifiers could flag the content regardless of the source domain. **Without custom event mappings,** standard event names like "Purchase" or "AddToCart" on a store that sells health products could still draw scrutiny from automated systems. All four layers need to be in place. Aliasing is the visible "front door" — it determines what domain Meta associates with your pixel. The other three components ensure that everything behind that front door is also clean. ### Common Questions ### Will Meta eventually flag the alias domain too? As long as the alias domain's landing page stays compliant and the event data sent from it is sanitized (which Upstack handles automatically), there is no reason for Meta to flag it. The alias domain never has health/wellness content, and the events from it never contain flaggable product data. ### Can I use the same alias domain for multiple stores? Generally no. Each store should have its own alias domain to avoid cross-contamination. If Meta were to flag one store's alias domain for any reason, you wouldn't want it to affect your other stores. ### Does the alias domain need SSL/HTTPS? Yes. Meta expects `event_source_url` values to use HTTPS. Most modern hosting providers and domain registrars include free SSL certificates, so this is usually automatic. ### Can I use the alias domain for anything else? It's best to keep the alias domain dedicated solely to this purpose. Don't use it for email marketing, other ad platforms, or any purpose that could generate content Meta might scrutinize. The simpler and cleaner it stays, the better. ### What happens to the alias domain if I stop using Upstack? The alias domain is yours — you registered it. If you stop using Upstack, you can let it expire or repurpose it. However, if you plan to continue running Meta ads for a health/wellness brand, you'll need some form of domain aliasing regardless of what tracking solution you use. ### What You Need to Do You're responsible for registering the alias domain and setting up the landing page. Upstack handles the technical aliasing — replacing the `event_source_url` in every CAPI event. For step-by-step instructions: [How to Set Up an Alias Domain for Health & Wellness Tracking →](/guides/health-wellness/setup-alias-domain-health-wellness) ### Related Articles * [How Upstack Data Solves Health & Wellness Restrictions](/guides/health-wellness/how-upstack-solves-health-wellness-restrictions) * [How to Set Up an Alias Domain for Health & Wellness Tracking](/guides/health-wellness/setup-alias-domain-health-wellness) * [How to Set Up a Health & Wellness Pixel for Meta](/guides/health-wellness/setup-health-wellness-pixel-for-meta) # How to Add NC Purchase Metrics and NC-ROAS to Facebook (Meta) Ads Manager Source: https://docs.upstackdata.com/guides/facebook-ads/how-to-add-nc-purchase-metrics-and-nc-roas-to-facebook-meta-ads-manager Add NC Purchase metrics and create NC-ROAS in Facebook (Meta) Ads Manager to measure new-customer revenue and optimize campaigns for first-time buyers. <Tip> * Sign in to [Meta Ads Manager](https://adsmanager.facebook.com) and open any campaigns table. * Click **Columns → Customize columns**. * Under **Custom Conversions**, add **NC Purchase** (Total + Cost). * Click **Create custom metric** and define **NC-ROAS = NC Purchase Conversion Value ÷ Amount spent**. * Click **Apply** to save the column layout. </Tip> ## Prerequisites Before you start, you need: * The **NC Purchase** custom conversion already created **and** shared with the ad account you're configuring — see [How to create and share the NC Purchase custom conversion](/guides/facebook-ads/how-to-create-and-share-nc-purchase-custom-conversion-in-facebook-meta) * Admin or campaign-management access to the Meta ad account you want to update columns for ## What you'll achieve After completing this setup, you'll see new-customer metrics — **NC-ROAS** (New Customer Return on Ad Spend), **Cost per NC Purchase**, and **Total NC Purchases** — directly in Meta Ads Manager. ## Part 1 — Add NC Purchase metrics to columns <Steps> <Step title="Open Customize columns in Meta Ads Manager"> Sign in to Meta Ads Manager at [adsmanager.facebook.com](https://adsmanager.facebook.com), select the ad account you want to configure, then on the campaigns/ad sets/ads table click **Columns** in the toolbar above the table and select **Customize columns**. <img alt="Meta Ads Manager Columns dropdown with Customize columns option" /> </Step> <Step title="Add the NC Purchase metrics"> In the **Customize columns** dialog, scroll the left-hand category list to **Custom Conversions** and select your **NC Purchase** conversion (it may be named **NewCustomerPurchase** depending on how you created it). Check both checkboxes that appear: * **Total** — total number of new-customer purchases attributed * **Cost** — cost per new-customer purchase <img alt="Customize columns showing NC Purchase conversion with Total and Cost checkboxes" /> </Step> </Steps> ## Part 2 — Set up the NC-ROAS custom metric <Steps> <Step title="Open Create custom metric"> Inside the **Customize columns** dialog, click **Create custom metric** in the bottom-left. <img alt="Create custom metric button in Customize columns dialog" /> </Step> <Step title="Configure the NC-ROAS formula"> Fill in the new-metric form: * **Name:** `NC-ROAS` * **Formula:** `NC Purchase Conversion Value` ÷ `Amount spent` * Click **Create metric** <Warning> Check **Everyone with access to this Business** if you want the metric to be available to your whole team. </Warning> <img alt="NC-ROAS custom metric formula with conversion value divided by amount spent" /> </Step> <Step title="Add NC-ROAS to your columns and apply"> Back in **Customize columns**, find **NC-ROAS** under **Custom metrics** and check it so it appears in your table. Click **Apply** in the bottom-right of the dialog to save the column layout. <img alt="Apply button to save column layout with NC-ROAS added" /> </Step> <Step title="Verify the new columns appear"> Your Ads Manager table should now show three new columns: * **NC Purchase (Total)** — number of new customers acquired * **NC Purchase (Cost)** — cost per new customer * **NC-ROAS** — return on ad spend from new customers <Warning> Initially, the new columns may show **0** or **—** because Meta does **not** retroactively attribute custom conversions from before they were created. Data populates for conversions that occur **after** the conversion was created and shared. Allow 24–48 hours of new traffic before judging the values. </Warning> </Step> </Steps> # How to Approve Facebook (Meta) Custom Events Source: https://docs.upstackdata.com/guides/facebook-ads/how-to-approve-facebook-meta-custom-events Approve custom events in Facebook (Meta) Events Manager so they become eligible for ad campaign optimization, custom audiences, and conversion reporting. ## Why event approval is required <Note> Custom events showing the ⚠️ red triangle warning in Meta Events Manager must be approved (acknowledged and confirmed) before Meta will use them for ad delivery optimization or campaign targeting. </Note> <Tip> * Sign in to [Meta Events Manager](https://business.facebook.com/events_manager2) and open the affected pixel. * Click the **custom event** (or its red triangle icon) and choose **Manage status**. * Click **I acknowledge**, then **Confirm the custom event**, then **Confirm**. * Refresh the events list and confirm the red triangle is gone. </Tip> ## Prerequisites Before you start, you need: * Access to the same **Meta Business Manager** that owns the pixel firing the custom event * Editor or admin permissions on the pixel/dataset in Meta Events Manager * At least one fired instance of the custom event (so it appears in the events list) ## Step-by-step instructions <Steps> <Step title="Sign in to Meta Events Manager"> Sign in to Meta Events Manager at [business.facebook.com/events\_manager2](https://business.facebook.com/events_manager2) and select the pixel containing the custom event. <img alt="Meta Events Manager showing pixel with custom events" /> </Step> <Step title="Open the custom event for review"> On the pixel **Overview** tab, locate the custom event with the ⚠️ warning. Click either: * The **name** of the custom event, or * The **red triangle ⚠️** warning icon next to it Then click **Review** (or open **Manage status**). <img alt="Custom event with red triangle warning icon in events list" /> <img alt="Manage status option for reviewing custom event" /> </Step> <Step title="Acknowledge the event"> In the review dialog, click **I acknowledge**. <Note> This confirms you understand this is a custom event you've intentionally created (in this case, sent by Upstack Data). </Note> <img alt="I acknowledge button in custom event review dialog" /> </Step> <Step title="Confirm the custom event"> Complete the final approval: * Click **Confirm the custom event** * Click **Confirm** to finalize <img alt="Confirm the custom event button to finalize approval" /> </Step> <Step title="Verify the warning is cleared"> Refresh the **Overview** tab. The ⚠️ red triangle should no longer appear next to the event, and its status should read **Active**. The event is now approved and available as an optimization or targeting event in **Meta Ads Manager**. </Step> </Steps> # How to Configure Facebook (Meta) Ads Pixel Destination in Upstack Data Source: https://docs.upstackdata.com/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data Configure the Facebook (Meta) Ads destination in Upstack Data with your Pixel ID and Conversion API key to enable dual tracking via browser pixel and server-side CAPI. <Tip> * In the Upstack dashboard, go to **Event Destinations** and click **+ New Destination**. * Select **Facebook Advertising**. * Enter your **Meta Pixel ID** (15–16 digit number, no prefix). * Enable the **Conversions API** checkbox and paste your **CAPI token** (starts with `EAA`). * Click **Create Configuration** and verify the destination shows **Healthy**. </Tip> <Note> **What this setup enables** Setting up the Meta Ads Pixel destination in Upstack Data enables dual tracking via browser pixel and server-side Conversions API (CAPI), ensuring accurate conversion data despite iOS restrictions and ad blockers. </Note> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to a **Meta Business Manager** account * A configured **Meta Pixel** in [Meta Events Manager](https://business.facebook.com/events_manager) — see [How to find your Meta Pixel ID](/guides/facebook-ads/how-do-i-find-my-facebook-ads-pixel-dataset-id) * A **Conversions API access token** — see [How to generate your CAPI token](/guides/facebook-ads/how-to-generate-my-facebook-conversion-api-key) ## Configuration steps <Steps> <Step title="Sign in to Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com/pixel/event-destinations). </Step> <Step title="Open the destination configuration"> In the Upstack dashboard, navigate to **Event Destinations**. Click **+ New Destination** in the top-right of the page. <img alt="Add New Destination" /> In the **Select a Destination** popup, click **Facebook Advertising**, then click **Next**. <img alt="Facebook Pixel Configuration" /> </Step> <Step title="Enter your Pixel ID and CAPI token"> Fill in the form: 1. **Meta Pixel ID** — the 15–16 digit number, no prefix (e.g., `123456789012345`). Meta Pixel IDs do **not** have an `AW-` prefix; that prefix belongs to Google Ads. 2. Check the box **Check to enable sending events via Facebook Conversions API**. 3. **CAPI token** — starts with `EAA`, approximately 190 characters long. <Warning> The Conversions API checkbox **must be selected** for server-side tracking to work. </Warning> <img alt="Meta destination form with Pixel ID and Conversions API fields" /> <Note> **Need help finding these?** * [How to find your Meta Pixel ID](/guides/facebook-ads/how-do-i-find-my-facebook-ads-pixel-dataset-id) * [How to generate your CAPI token](/guides/facebook-ads/how-to-generate-my-facebook-conversion-api-key) </Note> </Step> <Step title="Create the configuration"> Click the **Create Configuration** button. <img alt="Create Configuration button to save Meta destination" /> You should see a confirmation message and the Meta destination will appear in your **Event Destinations** list. <img alt="Meta destination showing Healthy status in Event Destinations list" /> </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, the Meta destination card should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**: * Confirm your **Pixel ID** is correct (15–16 digits, no leading/trailing spaces, no prefix). * Confirm your **CAPI token** is the full string starting with `EAA`. * Confirm the **Conversions API** checkbox was selected. * See [How to update your CAPI token](/guides/facebook-ads/how-to-update-facebook-meta-conversion-api-key) if your token may have expired. </Step> </Steps> # How to Connect your Facebook Ads Account in Upstack Data Integrations Source: https://docs.upstackdata.com/guides/facebook-ads/how-to-connect-your-facebook-ads-account-in-upstack-data-integrations Connect your Facebook Ads account to Upstack Data so spend, impressions, and clicks pull into the dashboard for unified channel-level ROAS and attribution reporting. <Tip> * Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com) and navigate to **Data Integrations**. * On the **Facebook ads** card, open the **kebab menu** (3 dots) → click **Connect**. * Authorize with Facebook and select the **ad account** you want to connect. * Click **Save** and verify the integration shows **Healthy**. </Tip> <Note> **Purpose of this setup** Connecting your Facebook ads account is required to access performance data at the account, campaign, ad set, and ad levels, which powers your dashboards and attribution reporting. </Note> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin or advertiser access to the **Facebook ad account** you want to connect * A Facebook user account that can sign in via OAuth on this browser ## Configuration steps <Steps> <Step title="Sign in to Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com), then navigate to **Data Integrations** in the left-hand menu (or open it directly at [app.upstackdata.com/pixel/integrations](https://app.upstackdata.com/pixel/integrations)). <img alt="Upstack dashboard with Data Integrations menu option" /> </Step> <Step title="Open the Facebook ads connector"> On the **Data Integrations** page, find the **Facebook ads** card and click the **kebab menu** (3 dots) in the top-right of the card, then click **Connect**. <img alt="Facebook ads card with kebab menu showing Connect option" /> If the Facebook account shown is correct, click **Connect** or **Reconnect**. <img alt="Facebook account confirmation with Connect button" /> If the Facebook account shown is **not** the one that has access to your ad account, click **Log into another account**. <img alt="Log into another account option for different Facebook user" /> </Step> <Step title="Select the Facebook ad account"> A popup displays every ad account linked to your Facebook user. Select the **Facebook ad account** you want Upstack Data to read performance data from. <img alt="Facebook ad account selection popup with available accounts" /> </Step> <Step title="Save the configuration"> Click the **Save** button. <img alt="Save button to confirm Facebook ads connection" /> <img alt="Facebook ads integration showing successful connection" /> </Step> <Step title="Verify the integration is healthy"> In the Upstack dashboard, the **Facebook ads** integration card should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy** or **Reconnect required**: * Confirm the Facebook user that authorized the connection still has access to the ad account. * Re-run the **Connect** flow and re-grant all requested permissions when prompted. </Step> </Steps> # How to Create and Share NC Purchase Custom Conversion in Facebook (Meta) Source: https://docs.upstackdata.com/guides/facebook-ads/how-to-create-and-share-nc-purchase-custom-conversion-in-facebook-meta Create and share an NC Purchase custom conversion in Facebook (Meta) Events Manager to attribute new-customer revenue to ads and share the metric across ad accounts. <Tip> * Sign in to [Meta Events Manager](https://business.facebook.com/events_manager) and open **Custom Conversions → Create custom conversion**. * Name the conversion **NC Purchase** and select the **ncPurchase** event. * Choose **Purchase** as the optimization event and add a URL rule of **doesn't contain `doesnotexist`**. * Share the conversion with every ad account that needs to use it. </Tip> <Note> **What you'll create** A custom conversion that tracks **new-customer** purchases, so you can optimize campaigns for customer acquisition rather than repeat purchases. </Note> ## Prerequisites Before you start, you need: * The **Meta destination** configured in Upstack Data — see [How to configure the Meta Pixel destination](/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data) * The **ncPurchase** event verified in Meta Events Manager — see [How to verify the NC Purchase event](/guides/facebook-ads/how-to-verify-the-nc-purchase-event-in-facebook-meta-events-manager) * Admin access to the Meta Business Manager and to every ad account you plan to share the conversion with ## Part 1 — Create the NC Purchase custom conversion <Steps> <Step title="Sign in to Meta Events Manager"> Sign in to Meta Events Manager at [business.facebook.com/events\_manager](https://business.facebook.com/events_manager). </Step> <Step title="Open Custom Conversions"> In the left-hand menu, click **Custom Conversions**, then click **Create custom conversion** in the top-right. <img alt="Meta Events Manager Custom Conversions page with Create button" /> </Step> <Step title="Name and select the event"> In the **Create a custom conversion** dialog: * **Name:** `NC Purchase` * **Event:** select **ncPurchase** <Note> If you don't see **ncPurchase** in the Event dropdown, return to Meta Events Manager and verify the event first. See [How to verify the NC Purchase event](/guides/facebook-ads/how-to-verify-the-nc-purchase-event-in-facebook-meta-events-manager). </Note> </Step> <Step title="Set the optimization event"> In the **Choose a standard event for optimization** field, select **Purchase**. This tells Meta to optimize delivery using its Purchase model when this custom conversion is used. </Step> <Step title="Configure URL rules"> Under **Rules**: 1. Choose **URL** as the parameter 2. Select **doesn't contain** as the condition 3. Type `doesnotexist` in the value field 4. Press **Enter** until the value becomes a light-grey tag 5. Click **Create** <Note> **Why this rule?** Since no URL on your store contains `doesnotexist`, this rule effectively matches every page — so the custom conversion fires for the **ncPurchase** event across your entire site. </Note> <img alt="Custom conversion URL rule configuration with doesnotexist condition" /> </Step> </Steps> ## Part 2 — Share with ad accounts <Steps> <Step title="Open the share menu"> On the **Custom Conversions** page, find the **NC Purchase** conversion you just created. Click the **dropdown** (kebab menu) on the right of the row, then click **Share**. <img alt="NC Purchase conversion row with kebab menu showing Share option" /> </Step> <Step title="Choose Share with an Ad Account"> In the share dialog, click **Share with an Ad Account**. <img alt="Share dialog with Share with an Ad Account option" /> </Step> <Step title="Select the ad accounts"> Check every ad account that needs to use this custom conversion. <img alt="Ad account selection list with checkboxes" /> <img alt="Multiple ad accounts selected for sharing" /> </Step> <Step title="Confirm sharing"> Click **Share Custom Conversion** to confirm. <img alt="Share Custom Conversion button to confirm sharing" /> </Step> <Step title="Verify the conversion is shared and active"> Back on the **Custom Conversions** page, the **NC Purchase** row should show: * **Status:** Active (no warning icon) * **Shared with:** the ad accounts you selected Open one of those ad accounts in **Ads Manager** and confirm **NC Purchase** appears in the **Custom Conversions** list when you customize columns or pick a conversion event for a campaign. </Step> </Steps> ## What's next? After creating and sharing the conversion, set up reporting: [Set up NC-ROAS metrics in Ads Manager →](/guides/facebook-ads/how-to-add-nc-purchase-metrics-and-nc-roas-to-facebook-meta-ads-manager) # How to Disable Facebook and Instagram Data Sharing in Shopify Source: https://docs.upstackdata.com/guides/facebook-ads/how-to-disable-facebook-and-instagram-data-sharing-in-shopify Disable Shopify's Facebook and Instagram sales channel pixel to stop duplicate Meta Pixel events and let Upstack Data deliver clean server-side conversions to Meta CAPI. <Tip> * Sign in to your Shopify admin at [admin.shopify.com](https://admin.shopify.com). * Open **Sales channels → Facebook & Instagram → Settings**. * Under **Share data**, click **Change**. * Toggle **Share data** to **Off** and click **Save**. </Tip> <Warning> Most causes of duplicate events are because you have more than one Facebook integration active on your site. Disable the **Facebook & Instagram sales channel data sharing** in Shopify and confirm no other Facebook pixel apps (or theme-injected pixels) are installed. </Warning> ## Prerequisites Before you start, you need: * Owner or staff access to your **Shopify admin** with permission to edit sales channels * The **Facebook & Instagram sales channel** installed in Shopify (if it's not installed, there's nothing to disable) * A configured Meta destination in Upstack Data so the pixel keeps firing after you disable Shopify's native integration — see [How to configure the Meta Pixel destination](/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data) ## Steps to disable Facebook and Instagram data sharing in Shopify <Steps> <Step title="Sign in to Shopify"> Sign in to your Shopify admin at [admin.shopify.com](https://admin.shopify.com). </Step> <Step title="Open the Facebook & Instagram sales channel"> In the Shopify admin, click **Sales channels** in the left-hand menu, select **Facebook & Instagram**, then click the **Settings** tab. *Tip: You can also use the top search bar to jump directly to the Facebook & Instagram sales channel.* <img alt="Shopify admin with Facebook & Instagram sales channel selected" /> </Step> <Step title="Open the Share data settings"> On the Facebook & Instagram **Settings** page, locate the **Share data** section and click **Change**. <img alt="Facebook & Instagram Settings page with Share data section and Change button" /> </Step> <Step title="Toggle off data sharing"> Toggle **Share data** to **Off**. <img alt="Share data toggle switched to Off position" /> </Step> <Step title="Save your changes"> With **Share data** now set to **Off**, click the **Save** button at the bottom of the page. <img alt="Save button to confirm Share data changes" /> </Step> <Step title="Verify data sharing is disabled"> After saving, the Facebook & Instagram **Settings** page should now show **Share data: Off**. <img alt="Facebook & Instagram Settings showing Share data Off confirmation" /> Within 24 hours, you should also see duplicate-event warnings clear in **Meta Events Manager**. If duplicates persist, also check for: * Third-party Facebook pixel apps in Shopify * Manual pixel code in your theme files (`theme.liquid`, header snippets) * Facebook pixel tags inside Google Tag Manager </Step> </Steps> <Note> **Need help?** If duplicate events continue after disabling Shopify's native integration, contact our support team with your Pixel ID and we'll help diagnose the source. </Note> ## Related Articles <CardGroup> <Card title="Configure Meta Pixel destination" href="/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data" /> <Card title="Duplicate events troubleshooting" href="/troubleshooting/duplicate-events" /> <Card title="Enable theme app extension" href="/guides/shopify/how-to-ensure-upstack-data-theme-app-extension-is-enabled" /> <Card title="Complete Meta onboarding guide" href="/guides/facebook-ads/complete-how-to-guide-for-onboarding-facebook-meta-in-upstack-data" /> </CardGroup> # How to Generate my Facebook Conversion API Key? Source: https://docs.upstackdata.com/guides/facebook-ads/how-to-generate-my-facebook-conversion-api-key Generate a Facebook (Meta) Conversion API access token in Meta Events Manager and paste it into Upstack Data to enable server-side conversion forwarding via CAPI. <Tip> * Sign in to [Meta Events Manager](https://business.facebook.com/events_manager) and open your pixel. * Open the **Settings** tab and scroll to the **Conversions API** section. * Click **Generate access token** and copy the token immediately — it is shown only once. * Paste the **CAPI token** (starts with `EAA`) into your Upstack Meta destination. </Tip> <Note> **What is a CAPI token?** A **Conversions API (CAPI) token** is a Meta access token that lets Upstack Data send conversions from your server to Meta, improving accuracy for iOS users and ad-blocked traffic. </Note> ## Prerequisites Before you start, you need: * **Admin access** (or full access) to a **Meta Business Manager** account * A pixel already created in [Meta Events Manager](https://business.facebook.com/events_manager) — see [How to find your Meta Pixel ID](/guides/facebook-ads/how-do-i-find-my-facebook-ads-pixel-dataset-id) * An Upstack Data account ready to receive the token ([sign in](https://app.upstackdata.com)) ## Steps to generate your CAPI token <Steps> <Step title="Sign in to Meta Events Manager"> Sign in to Meta Events Manager at [business.facebook.com/events\_manager](https://business.facebook.com/events_manager). </Step> <Step title="Find or create your pixel"> **If you already have a pixel**, you'll see it listed in the **Data Sources** panel — proceed to the next step. **If you need to create one:** * Click the green **Connect Data Sources** button * Select **Web** * Click **Next** or **Get Started** * Follow the instructions to create a new Meta Pixel <img alt="Meta Events Manager with Connect Data Sources button" /> <img alt="Select Web as data source type in Meta Events Manager" /> </Step> <Step title="Open the pixel overview"> In the **Data Sources** list, click your pixel's name. You'll land on the pixel's **Overview** page. </Step> <Step title="Navigate to the Settings tab"> On the pixel **Overview** page, click the **Settings** tab in the left-hand menu. <img alt="Meta Pixel Settings tab in left-hand navigation" /> </Step> <Step title="Generate the access token"> On the **Settings** tab, scroll down to the **Conversions API** section and click **Generate access token**. <img alt="Conversions API section with Generate access token button" /> </Step> <Step title="Copy your CAPI token"> Copy the value of the access token shown in the dialog. This is your **CAPI token**. <Warning> The token is shown **only once** — copy it immediately to a secure location. If you close the dialog without copying, you'll need to generate a new one. </Warning> <img alt="Generated CAPI access token dialog with copy option" /> **Token format:** starts with `EAA`, approximately 190 characters long (e.g., `EAAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx...`). </Step> <Step title="Add the token to Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com/pixel/event-destinations) and open your **Meta** destination under **Event Destinations**. Paste the token into the **Conversions API token** field. <Note> Make sure the **Check to enable sending events via Facebook Conversions API** checkbox is selected. </Note> <img alt="Upstack Meta destination with Conversions API token field" /> <Warning> The CAPI token is sensitive — store it securely. The token is tied to a single Meta ad account and cannot be reused across accounts. </Warning> </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, the Meta destination card should show **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**: * Confirm the token starts with `EAA` and was pasted in full (no truncation, no whitespace). * Confirm the **Conversions API** checkbox is selected. * Confirm the Pixel ID matches the pixel you generated the token for. </Step> </Steps> <Note> **Need help with the Pixel ID?** See [How to find your Meta Pixel ID](/guides/facebook-ads/how-do-i-find-my-facebook-ads-pixel-dataset-id). </Note> ## Related Articles <CardGroup> <Card title="Find your Meta Pixel ID" href="/guides/facebook-ads/how-do-i-find-my-facebook-ads-pixel-dataset-id" /> <Card title="Configure Meta Pixel destination" href="/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data" /> <Card title="Update Facebook CAPI key" href="/guides/facebook-ads/how-to-update-facebook-meta-conversion-api-key" /> <Card title="Connection errors and disconnections" href="/troubleshooting/integration-connection-errors-and-disconnections" /> </CardGroup> # How to Update Facebook (Meta) Conversion API Key? Source: https://docs.upstackdata.com/guides/facebook-ads/how-to-update-facebook-meta-conversion-api-key Rotate or update your Facebook (Meta) Conversion API access token in Upstack Data to keep server-side events flowing into Meta CAPI without breaking pixel health. ## Overview <Note> If you've seen warnings like *"My Conversions API is not getting any events"* or received an email that your *Meta Pixel is unhealthy*, it means your CAPI token needs to be refreshed. This guide walks you through updating your Meta CAPI token in Upstack Data so events flow correctly, attribution stays accurate, and your pixel remains healthy. </Note> <Tip> * Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com/pixel/event-destinations) and open **Event Destinations**. * Click your **Meta destination** to edit it. * Paste a fresh **CAPI token** (starts with `EAA`) into the **Conversions API token** field. * Click **Update Configuration** and verify the destination shows **Healthy**. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account with a Meta destination already configured * A new **CAPI token** generated from [Meta Events Manager](https://business.facebook.com/events_manager) — see [How to generate your CAPI token](/guides/facebook-ads/how-to-generate-my-facebook-conversion-api-key) * The token copied to your clipboard (it is shown only once when generated) ## Configuration steps <Steps> <Step title="Sign in to Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com/pixel/event-destinations). In the Upstack dashboard, navigate to **Event Destinations**. <img alt="Upstack dashboard Event Destinations page" /> </Step> <Step title="Open your Meta destination"> In the **Event Destinations** list, click your **Meta destination** to edit it. <img alt="Meta destination card in Event Destinations list" /> Confirm the **Check to enable sending events via Facebook Conversions API** checkbox is selected, then paste your new **CAPI token** into the **Conversions API token** field. Replace the existing value entirely. <img alt="Meta destination edit form with CAPI token field" /> <Note> The CAPI token starts with `EAA` and is approximately 190 characters long. Leave the **Pixel ID** unchanged (15–16 digit number, no prefix). </Note> <Note> **Need help finding these?** * [How to generate your CAPI token](/guides/facebook-ads/how-to-generate-my-facebook-conversion-api-key) * [How to find your Meta Pixel ID](/guides/facebook-ads/how-do-i-find-my-facebook-ads-pixel-dataset-id) </Note> </Step> <Step title="Save the updated configuration"> Click **Update Configuration** to save the change. <img alt="Update Configuration button to save Meta destination changes" /> </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, the Meta destination card should display **Healthy** with a green status indicator within 5 minutes. If the status still shows **Unhealthy**: * Confirm the new CAPI token starts with `EAA` and was pasted in full (no truncation or whitespace). * Confirm the user who generated the token has admin access to the Meta Business Manager that owns the pixel. * See [Why is my Meta EMQ panel showing zeros?](/guides/facebook-ads/why-is-my-meta-emq-panel-showing-zeros-0-0-10) for token-permission troubleshooting. </Step> </Steps> # How to Verify the NC Purchase Event in Facebook (Meta) Events Manager Source: https://docs.upstackdata.com/guides/facebook-ads/how-to-verify-the-nc-purchase-event-in-facebook-meta-events-manager Verify the NC Purchase event arrives in Facebook (Meta) Events Manager from Upstack Data — confirm event match quality, deduplication, and new-customer attribution before enabling optimization. <Tip> * Sign in to [Meta Events Manager](https://business.facebook.com/events_manager) and open the pixel connected to Upstack Data. * On the **Overview** tab, find the **ncPurchase** event in the events list. * Hover over the event to reveal **Review**, or open **Manage status** and click **Review**. * Acknowledge and confirm the event so the red triangle warning clears. </Tip> <Note> **What is the New Customer (NC) Purchase event?** The **NC Purchase** (`ncPurchase`) event is a custom event sent by Upstack Data that fires when a first-time customer makes a purchase. The event must be verified in Meta Events Manager before you can create custom conversions or track new-customer metrics in Meta Ads Manager. </Note> ## Prerequisites Before you start, you need: * The **Meta destination** configured in Upstack Data — see [How to configure the Meta Pixel destination](/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data) * At least one real new-customer purchase already processed so the **ncPurchase** event is visible in Meta Events Manager * Access to the same Meta Business Manager that owns the pixel ## Steps to verify the ncPurchase event <Steps> <Step title="Sign in to Meta Events Manager"> Sign in to Meta Events Manager at [business.facebook.com/events\_manager](https://business.facebook.com/events_manager) and open the pixel that Upstack Data is sending events to. </Step> <Step title="Locate the ncPurchase event"> On the pixel **Overview** tab, scroll the events list until you see **ncPurchase**. If you don't see it, wait a few hours after your first new-customer purchase or contact support. </Step> <Step title="Open the review flow"> Use either of the following: * **Option A:** Hover over the **ncPurchase** row to reveal the **Review** button, then click **Review**. <img alt="ncPurchase event row with Review button on hover" /> * **Option B:** Click **Manage status** in the top-right of the events list, then click **Review** next to **ncPurchase**. <img alt="Manage status dropdown with Review option for ncPurchase" /> </Step> <Step title="Acknowledge and confirm"> In the review dialog, click **I acknowledge**, then click **Confirm the custom event** and **Confirm** to finalize. See [How to approve Meta custom events](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events) for the full approval flow with screenshots. </Step> <Step title="Verify the event is approved"> Refresh the **Overview** tab. The red triangle warning next to **ncPurchase** should be gone, and the event status should read **Active** (or no warning icon). Once verified, you can use **ncPurchase** when creating custom conversions in Meta. </Step> </Steps> ## What's next? After verifying the ncPurchase event, you can: * [Create and share the NC Purchase custom conversion](/guides/facebook-ads/how-to-create-and-share-nc-purchase-custom-conversion-in-facebook-meta) * [Set up NC-ROAS metrics in Ads Manager](/guides/facebook-ads/how-to-add-nc-purchase-metrics-and-nc-roas-to-facebook-meta-ads-manager) # "Low Rate of Pixel Events Covered by Conversions API" in Meta Events Manager Source: https://docs.upstackdata.com/guides/facebook-ads/low-rate-of-pixel-events-covered-by-conversions-api-in-meta-events-manager Why this Meta Events Manager warning is normal for Upstack customers, why no action is needed, and why you should not set up the Conversions API Gateway. <Note> **Short answer: this is normal and you can disregard it.** No action is needed. Your events are already being sent through the Conversions API by Upstack Data. Do not click "Review solution" and do not set up Meta's Conversions API Gateway — doing so will cause duplicate events. </Note> ### What You're Seeing In **Meta Events Manager**, under "Top errors affecting your performance" (or the Diagnostics tab), you see a warning that looks like this: <img alt="Meta Events Manager warning showing low rate of pixel events covered by Conversions API" /> <Note> Insert the Events Manager screenshot showing the "Low rate of pixel events covered by Conversions API" warning here. </Note> The warning reads: <Note> **Low rate of pixel events covered by Conversions API** Try the Conversions API Gateway demo to improve your coverage rate and get better reporting accuracy. Advertisers with a 75 percent coverage rate saw lower cost per result versus Pixel alone for events. </Note> Next to it there is a blue **Review solution** button. ### Why You Don't Need to Do Anything This is one of Meta's standard recommendations, shown across many ad accounts, and for Upstack Data customers it's a false positive. Here's why you can safely ignore it: * **Upstack is already sending your events through the Conversions API.** Every event we track is sent twice — once from the browser pixel and once server-side through CAPI — with a shared `event_id` so Meta deduplicates them into a single event. * **The "Review solution" flow is designed for advertisers who don't have CAPI set up.** That is not you. Meta shows the same prompt to every account that dips below their target coverage rate, regardless of whether a CAPI integration is already running. * **Your reporting, attribution, and optimization are unaffected.** The warning does not impact how Meta counts your conversions or optimizes your ad delivery. ### What You Should NOT Do <Warning> Do NOT set up any additional Conversions API integration on top of Upstack. This includes: </Warning> * **Do not click "Review solution"** or start Meta's Conversions API Gateway demo * **Do not install Meta's Conversions API Gateway** (the Cloudflare-hosted CAPI forwarder) * **Do not enable CAPI through the Shopify Facebook & Instagram sales channel** * **Do not install any third-party CAPI app** (for example, other tracking tools that also offer server-side Meta events) Adding another CAPI sender alongside Upstack will cause the **same event to be sent twice without matching deduplication IDs**. Meta will count those as separate events, which inflates your reported conversions, distorts cost per result, and can confuse ad delivery optimization. ### Why Meta Shows This Warning Anyway Meta's "coverage rate" compares two event streams on the same pixel: browser events (fired by the Meta Pixel JavaScript) and server events (sent via the Conversions API). When the ratio of matched browser-to-server events drops below roughly 75 percent on a rolling window, Meta surfaces this warning. A few reasons you can see this warning even though Upstack is working correctly: * **Measurement noise.** Meta's coverage math is not always perfect, especially on low-volume days or when events arrive out of order. Short dips below the threshold are common and self-correct over time. * **Rolling window lag.** The metric is calculated over a trailing 7-day window, so recent fixes (new token, new setup) take a few days to show up in the score. * **Browser events from non-Upstack sources.** If another tool on your site is firing browser pixel events that Upstack doesn't see — for example, a raw pixel in your Shopify theme, a GTM tag, or a landing page builder — those events have no matching server-side pair, which lowers coverage. See "When to contact us" below. None of these require you to add more CAPI coverage. They require (at most) cleaning up duplicate browser-side sources, which we can help with. ### When to Contact Us You only need to reach out if you see one of the following, which would suggest a real issue rather than normal measurement drift: * Your Meta destination inside Upstack Data is flagged as **"needs attention"** or shows as unhealthy * Your **Event Match Quality (EMQ) scores** drop sharply in the Upstack dashboard * Your reported Meta conversions are meaningfully different from your actual orders in Shopify or WooCommerce * You suspect another pixel is firing alongside Upstack and want help identifying it Otherwise, no action is required — the warning can stay in your Events Manager without affecting your performance. ### Related Articles * [Why is my Meta EMQ Panel Showing Zeros (0.0/10)?](/guides/facebook-ads/why-is-my-meta-emq-panel-showing-zeros-0-0-10) * [How to Configure Facebook (Meta) Ads Pixel Destination in Upstack Data](/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data) * [How to Generate my Facebook Conversion API Key](/guides/facebook-ads/how-to-generate-my-facebook-conversion-api-key) * [How to Update Facebook (Meta) Conversion API Key](/guides/facebook-ads/how-to-update-facebook-meta-conversion-api-key) <Note> **Still have questions?** If you're unsure whether the warning in your account is normal or something to worry about, message our support team with your Pixel ID and store URL. We'll check your CAPI event stream and confirm everything is healthy. </Note> # Set up NC & RC Purchase events in Meta Source: https://docs.upstackdata.com/guides/facebook-ads/set-up-nc-and-rc-purchase-events-in-meta Configure NC Purchase, RC Purchase, and subscription events in Meta Events Manager and Ads Manager to optimize for new customer acquisition and retention. Custom events give ad platforms more specific signals to optimize against. The most impactful is **NC Purchase** — it tells Meta to find buyers who've never purchased from you before, instead of optimizing toward repeat customers. Without it, Meta's algorithm treats a first-time buyer and a fifth-time buyer as equally valuable conversions. ## New customer purchase (NC Purchase) NC Purchase fires only when an order comes from a customer with no prior Shopify order history. This enables NC CPA and NC ROAS reporting directly in Meta Ads Manager — two metrics that separate prospecting performance from retargeting performance. ### Set up in Facebook <Steps> <Step title="Wait for the first event"> Once Upstack is live, the first NC Purchase event appears in Meta Events Manager within minutes for active stores. You need at least one event before you can proceed. See [How to verify the NC Purchase event in Facebook Events Manager](/guides/facebook-ads/how-to-verify-the-nc-purchase-event-in-facebook-meta-events-manager) for a walkthrough. </Step> <Step title="Acknowledge the event"> Go to **Events Manager → find NC Purchase → Review → Acknowledge/Confirm**. This tells Meta to start processing NC Purchase as a recognized event. </Step> <Step title="Create a custom conversion"> In Events Manager, go to **Custom Conversions → Create**. Set the event to **NC Purchase** and give it a clear name (e.g., "Upstack NC Purchase"). See [How to create and share NC Purchase custom conversion in Facebook](/guides/facebook-ads/how-to-create-and-share-nc-purchase-custom-conversion-in-facebook-meta) for detailed steps. <Info> You need **Business Manager admin access** (not just ad account admin) to create custom conversions. If you run ads through an agency ad account, switch the Events Manager view to your own Business Manager before creating the conversion. </Info> </Step> <Step title="Add reporting columns"> In Ads Manager, add **NC CPA** and **NC ROAS** as columns in your reporting view. These metrics let you evaluate prospecting performance independently from retargeting. See [How to add NC Purchase metrics and NC ROAS to Facebook Ads Manager](/guides/facebook-ads/how-to-add-nc-purchase-metrics-and-nc-roas-to-facebook-meta-ads-manager) for column configuration. </Step> </Steps> <Note> Attribution is forward-looking only — Meta does not backfill historical data for new event types. NC Purchase metrics start populating from the moment the custom conversion is created. </Note> For the complete end-to-end walkthrough, see [Complete guide to setting up NC Purchase metrics in Facebook Ads Manager](/guides/facebook-ads/complete-how-to-guide-for-setting-up-new-customer-purchase-metrics-in-facebook-meta-ads-manager). <Accordion title="When to use NC Purchase vs. standard Purchase"> Custom purchase events supplement the standard `Purchase` event — they don't replace it. Keep standard `Purchase` active alongside the custom events so Meta's baseline models still receive every order. | Scenario | Recommended event | | ---------------------------------------------- | ------------------------------------ | | General ROAS optimization | Standard `Purchase` | | Scaling new customer acquisition | `nc_purchase` | | Prospecting campaigns targeting cold audiences | `nc_purchase` | | Retargeting campaigns for existing customers | `rc_purchase` or standard `Purchase` | | Brand awareness / top-of-funnel | Standard `Purchase` (broader signal) | | Measuring retention campaign performance | `rc_purchase` | **Allow a learning phase.** When you switch an ad set from standard Purchase to `nc_purchase`, it re-enters Meta's learning phase. Meta needs roughly 50 optimization events per week to exit learning, so start with your highest-spend or highest-volume campaign first if new-customer volume is low. **Compare before shifting budget.** Run `nc_purchase`-optimized campaigns alongside standard Purchase-optimized campaigns for 2–4 weeks and compare new-customer rate, CAC, and ROAS before committing. </Accordion> ## Returning customer purchase (RC Purchase) RC Purchase is the inverse of NC Purchase: it fires only when an order comes from a customer **with existing Shopify order history**. Together, the two events partition every order into acquisition vs. retention signals, which you can use separately in audience building, retargeting, and retention measurement. Classification uses the same Shopify-order-history check as NC Purchase — if the customer has zero prior completed orders, Upstack fires `nc_purchase`; if they have one or more, it fires `rc_purchase`. The standard `Purchase` event still fires for every order regardless of customer status, so baseline reporting is unaffected. ### Why it matters * **Build retargeting audiences that exclude first-time buyers.** Feed `rc_purchase` into custom audiences of recent repeat customers for win-back campaigns, loyalty offers, or cross-sells. * **Measure retention, not just acquisition.** Treat `rc_purchase` volume and value as a direct signal of how well retention campaigns (email, SMS, paid retargeting) are performing. * **Avoid over-indexing on repeat buyers in prospecting.** Pairing `rc_purchase` with `nc_purchase` makes it obvious when a "Purchase-optimized" campaign is really just retargeting existing customers. ### Set it up RC Purchase uses the **same four steps as NC Purchase above** — wait for the first event, acknowledge it, create a custom conversion, and add it to your reporting. Only two things differ: * **Creating the custom conversion:** select **RC Purchase** as the event (name it e.g. "Upstack RC Purchase"), set the category to **Purchase**, and leave the value at its default so Meta uses the order value sent with the event. * **Using it:** make the RC Purchase custom conversion the optimization event for **retargeting and retention** ad sets, or add it as a measurement column alongside NC CPA / NC ROAS to see acquisition and retention side by side. <Tip> Enable `nc_purchase` and `rc_purchase` together — running only one leaves half the acquisition-vs-retention segmentation on the table. </Tip> ## Subscription events For subscription brands, Upstack handles subscription events automatically. No manual setup is required. | Event | When it fires | Sent to Meta? | | ---------------------- | ------------------------ | --------------------------- | | Subscription Initial | First subscription order | Yes — counted as a purchase | | Subscription Recurring | Renewal orders | No — excluded from Meta | <Warning> **Why recurring subscriptions are excluded from Meta:** Sending renewal orders as purchase events tells Meta's algorithm that existing customers are converting. This shifts optimization toward retargeting instead of prospecting — the algorithm learns to chase people who were going to buy anyway. Only the initial subscription triggers a purchase event so Meta stays focused on finding new subscribers. </Warning> ## Advanced configuration <Accordion title="Category-specific events"> If you sell across multiple product categories (e.g., apparel and skincare), you can fire purchase events scoped to each category — `apparel_purchase`, `skincare_purchase`, and so on — then create a category-specific custom conversion in Meta for each and optimize ad sets per product line. Set these up yourself with [global event mappings](/guides/custom-events/global-event-mappings): add a condition on the product category and map it to a new event name. </Accordion> <Accordion title="Order source exclusions"> Not every order should feed back into Meta or Google's optimization. Some sources would pollute your conversion data. To configure exclusions, go to **Settings → Order Source Exclusions** and select the sources you want to block: * **TikTok Shop orders** * **Loop** (returns/exchanges) * **Matrixify** (bulk imports) * **Draft Orders** * **POS** (in-store transactions) Recurring subscription orders are excluded automatically. Initial subscription orders **are** sent — these represent genuine new-customer acquisitions. Sources only appear in the exclusion list if you have orders from them. If you don't see a source listed, you haven't had any orders from it yet. <Tip> Send more data to Facebook, not less. Even TikTok Shop orders help Meta find similar customers — the algorithm benefits from volume. Only exclude a source if the orders don't represent real customer acquisition (e.g., wholesale imports) or would actively mislead optimization (e.g., POS sales unrelated to your online ad spend). </Tip> </Accordion> ## Next step <CardGroup> <Card title="Configure contribution margin" icon="arrow-right" href="/get-started/configure-contribution-margin"> Set up COGS, transaction fees, and marketing spend so the P\&L dashboard reflects real profitability. </Card> </CardGroup> ## Related <CardGroup> <Card title="Complete NC Purchase setup guide" icon="book" href="/guides/facebook-ads/complete-how-to-guide-for-setting-up-new-customer-purchase-metrics-in-facebook-meta-ads-manager"> End-to-end walkthrough for NC Purchase, custom conversions, and reporting columns in Meta Ads Manager. </Card> <Card title="Verify NC Purchase events" icon="circle-check" href="/guides/facebook-ads/how-to-verify-the-nc-purchase-event-in-facebook-meta-events-manager"> Confirm NC Purchase events are arriving in Meta Events Manager and recognized correctly. </Card> <Card title="Connect a destination" icon="plug" href="/get-started/connect-a-destination"> Set up Meta CAPI as your first server-side destination for high-quality conversion events. </Card> <Card title="Verify end-to-end delivery" icon="list-check" href="/get-started/verify-end-to-end"> Confirm the complete pipeline works — from storefront event to destination delivery. </Card> </CardGroup> # What is FBC / Facebook Click ID? Source: https://docs.upstackdata.com/guides/facebook-ads/what-is-fbc-facebook-click-id Learn what Facebook's FBC and FBP cookies are, how Upstack sends them via the Conversions API, why FBC expires, and what causes missing or modified values. When someone clicks a Facebook ad, Facebook appends `fbclid` to the URL (for example, `?fbclid=abc123`). Facebook's pixel script reads it and stores it as a first-party cookie (`_fbc`) with a version prefix, timestamp, and click ID value. * **FBCLID** is the URL parameter. * **FBC** is the cookie that stores it. Upstack includes the FBC cookie value when sending events via the Conversions API (CAPI). Facebook compares it against its records — mismatches trigger diagnostics warnings. <Tip> Upstack also preserves click IDs across sessions and devices via its identity graph. A visitor who clicked a Facebook ad last week and returns today via Google can still have their original click ID restored. </Tip> ## FBC expiry Facebook click IDs are valid for 90 days. After that, Facebook considers them expired. Upstack stores click IDs beyond this window so returning visitors can still be matched, but if Facebook no longer recognizes the value, it may trigger a "Modified FBC" diagnostic. ## FBP (Facebook Browser ID) FBC ties to a specific ad click, but Facebook also sets a second first-party cookie called `_fbp`. FBP identifies the browser regardless of whether the visitor came from an ad. Both are sent with every Conversions API event. ## FBC is one of Facebook's strongest matching signals FBC directly links a conversion back to a specific ad click, which is why it carries more weight than email or phone for attribution. A high percentage of missing or modified FBC values can reduce your Event Match Quality score in Events Manager. ## Common reasons FBC goes missing * **Redirects** (age gates, A/B tests, language selectors) can strip the `fbclid` parameter before the pixel reads it. * **Ad blockers** can prevent the cookie from being set in the browser — which is why Upstack also sends events server-side. ## Related Articles <CardGroup> <Card title="Modified FBC value warning" href="/troubleshooting/server-sending-modified-fbc-value-in-events-manager" /> <Card title="Generate Facebook CAPI key" href="/guides/facebook-ads/how-to-generate-my-facebook-conversion-api-key" /> <Card title="Configure Meta Pixel destination" href="/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data" /> <Card title="Attribution mismatch troubleshooting" href="/troubleshooting/attribution-mismatch" /> </CardGroup> # Why is my Meta EMQ Panel Showing Zeros (0.0/10)? Source: https://docs.upstackdata.com/guides/facebook-ads/why-is-my-meta-emq-panel-showing-zeros-0-0-10 Fix Meta EMQ panel zero scores (0.0/10) in Upstack — caused by an access token missing Dataset Quality API permissions. Generate a new token with the right scopes to restore EMQ visibility. # Symptom Your **Meta Event Match Quality (EMQ) panel** inside Upstack Data is showing **0.0/10** across all events (Purchase, Initiate Checkout, View Content, etc.), even though events may still be flowing through to Meta and attribution looks normal. You may also see a notification in Upstack reading something like: <Note> **Meta Pixel destination needs attention. Please check your Meta destination configuration.** </Note> # Why this happens In most cases, a 0.0/10 EMQ score is a **timing issue** — Meta hasn't calculated a score yet. Upstack polls Meta's **Dataset Quality API** hourly to read EMQ scores and display them in the UI, and if Meta has nothing to return, Upstack shows `0.0`. But a persistent 0.0/10 can also indicate a configuration problem — a missing permission on your Meta access token, a pixel ID mismatch, or events not reaching Meta at all. The accordions below cover every cause we see, ordered roughly from most to least common. ## Possible causes <AccordionGroup> <Accordion title="You just connected the destination (most common)"> Meta does not calculate EMQ scores instantly. After you connect your Meta pixel as a destination in Upstack, it takes **24 to 48 hours** for Meta to receive enough events, process them, and generate a score. During this window, EMQ will read 0.0/10 — this is normal and not a sign of a broken configuration. **Fix:** Wait 48 hours after connecting before troubleshooting. If events are visible in [Meta Events Manager](https://business.facebook.com/events_manager) with the "Server" connection label, EMQ will populate on Meta's schedule. </Accordion> <Accordion title="No purchase events have occurred since connecting"> EMQ is calculated per event type, and the Purchase event is the one most people check first. If your store hasn't had any real orders since Upstack was connected, there are no purchase events for Meta to score — so the Purchase EMQ will stay at 0.0/10. **Fix:** Wait for real customer orders to flow through. Test orders and draft orders generally don't trigger the same scoring behavior as real checkouts, so don't rely on them for EMQ evaluation. </Accordion> <Accordion title="Low event volume — Meta hasn't generated a score yet"> Even when events are arriving at Meta, the scoring system needs a minimum volume before it will produce an EMQ reading. New or low-traffic stores can sit at 0.0/10 for longer than 48 hours simply because Meta doesn't have enough data points. **Fix:** If server events are visible in Events Manager but EMQ is still 0.0, continue to let volume build up. Scores typically appear once a handful of events per event type have been processed. </Accordion> <Accordion title="The Pixel ID is misconfigured"> If the Facebook Pixel ID configured in Upstack doesn't match a valid pixel in your Meta Business Manager, events are either rejected or sent to the wrong pixel — and no EMQ score will appear for the pixel you're watching. **Fix:** Verify the pixel ID in both places: 1. In [Meta Events Manager](https://business.facebook.com/events_manager), go to **Data Sources** and confirm the ID of the pixel you expect to receive events. 2. Compare it to the Pixel ID saved on your Upstack Meta destination. 3. If the two don't match, update the ID in Upstack and save the destination. </Accordion> <Accordion title="Events aren't reaching Meta at all"> A 0.0/10 across every event type — with **no server events visible in Events Manager** — usually means events aren't being delivered, not that scoring hasn't happened. Common causes: the destination isn't fully connected, the access token is invalid, or Shopify's native Facebook integration is interfering with Upstack's pipeline. **Fix:** 1. In [Events Manager](https://business.facebook.com/events_manager), open the **Overview** tab and filter for **Server** events. If none are arriving, the issue is upstream of EMQ scoring. 2. Confirm the Upstack Meta destination is saved, active, and not flagged as unhealthy. 3. If Shopify's native Facebook data sharing is enabled, disable it — Upstack handles server-side delivery with stronger identity enrichment, and running both can cause conflicts. </Accordion> <Accordion title="Access token is missing ads_read / ads_management scopes"> This is the most common *configuration* cause (as opposed to a timing cause). Events are flowing and attribution works normally, but Upstack can't read EMQ scores back from Meta because the access token doesn't have the permissions required by the Dataset Quality API. When this happens, the token is **valid and refreshing successfully**, but Meta returns an empty/permission-denied response to the EMQ read call and Upstack stores `0.0` as the last known score. After two consecutive failed hourly pulls, Upstack's destination health manager flags the destination as unhealthy and fires the "needs attention" notification. **Which permissions are required** Per [Meta's Dataset Quality API documentation](https://developers.facebook.com/docs/marketing-api/conversions-api/dataset-quality-api/), the access token used to read EMQ data must include, at minimum: * `ads_read` * Either `ads_management` **or** `business_management` In addition, the **user (or system user) that generated the token** must have the **Partial access → Use events dataset** permission on the pixel/dataset inside Meta Business Manager. Tokens generated with only the basic Conversions API scope (enough to *send* events) will **not** be enough to *read* Dataset Quality metrics. This is especially common on tokens generated a long time ago or generated by a user who no longer has full access to the Business Manager. **Fix: generate a new CAPI token and update the destination** <Steps> <Step title="Generate a new CAPI token in Meta Events Manager"> * Sign in to [Meta Events Manager](https://business.facebook.com/events_manager) at `business.facebook.com/events_manager`. * In the **Data Sources** panel, select the **pixel/dataset** that is showing zeros in Upstack. * Click **Settings** in the left-hand menu inside the pixel. * Scroll to the **Conversions API** section. * Click **Generate access token**. * Copy the token immediately — Meta only shows it once. The token starts with `EAA` and is approximately 190 characters long. <Warning> The user generating the token **must be an admin** (or have full access) on the Meta Business Manager that owns the pixel. If the token is generated by a user with only partial or assigned access, it may still be missing the `ads_read` / `ads_management` scopes and the EMQ panel will continue to read zero. </Warning> </Step> <Step title="Update the CAPI token in the Upstack dashboard"> * Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com/pixel/event-destinations). * Navigate to **Event Destinations** and open your **Meta** destination. * Paste the new token into the **Conversions API token** field, replacing the existing value. * Leave the **Pixel ID** unchanged (15–16 digit number, no prefix). * Click **Update Configuration**. </Step> <Step title="Wait for the next hourly pull and verify"> Upstack queries Meta's Dataset Quality API **once per hour**. After saving the new token, your EMQ scores should populate on the next scheduled pull (within 1–2 hours). After 1–2 hours, in the Upstack dashboard: * The **EMQ panel** should display non-zero scores (typically 6.0–10.0/10). * The Meta destination card should show **Healthy** with a green status indicator. * The **"Meta Pixel destination needs attention"** notification should clear. If the scores are still 0.0/10 after 2 hours, contact support so we can trigger a manual refresh and verify the token permissions. </Step> </Steps> </Accordion> </AccordionGroup> # How to confirm the fix worked * The EMQ panel inside Upstack should now show **non-zero scores** (typically 6.0–10.0/10 depending on the richness of your event data) * The **"Meta Pixel destination needs attention"** notification should clear * The destination health indicator should return to **healthy/green** # Related Articles [How to find my Upstack Data Pixel ID?](/resources/how-to-find-my-upstack-data-pixel-id) <Note> **Still seeing zeros?** If you've generated a new token from an admin account and the EMQ panel is still reading 0.0/10 after a couple of hours, contact our support team. The most common edge cases are: (1) the token was generated by a user without full Business Manager access, (2) the pixel is owned by a different Business Manager than the one the token is scoped to, or (3) your app doesn't have the Dataset Quality API feature enabled. We can diagnose all of these quickly. </Note> # Complete Upstack Data Onboarding Guide Source: https://docs.upstackdata.com/guides/getting-started/complete-upstack-data-onboarding-guide Complete onboarding guide — install Upstack Data on Shopify, set up your pixel, connect ad and email platforms, and configure data integrations for accurate tracking and attribution. ## Prerequisites Before you start, make sure you have: * An active Shopify store (`your-store.myshopify.com`) and [Shopify Admin](https://admin.shopify.com) access with permission to install apps and edit themes. * Admin access to every ad platform you'll connect (Meta, Google Ads, TikTok, Snapchat, Pinterest). * Admin access to your email/CRM platform (Klaviyo, Omnisend) if you plan to enrich those flows. * A valid payment method on the Shopify account that will install Upstack Data — [see plans and pricing](/billing/plans-and-pricing). * Access to the email inbox you'll use for your [Upstack Data](https://app.upstackdata.com) account (a verification code is sent during sign-up). ## Part 1: Install and set up Upstack Data in Shopify In this step, you will install the Upstack Data app from the Shopify App Store and complete the initial setup. This connects your Shopify store to Upstack Data, enabling pixel tracking, event collection, and data integration needed for accurate reporting and attribution. Help guide to complete this step: [Complete How-To Guide for Setting Up the Upstack Data App in Shopify](/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify) ## Part 2: Connect ad platforms In this step, you will connect your ad platforms (Meta, Google Ads, Snapchat, Pinterest, and TikTok) as destinations in [Upstack Data](https://app.upstackdata.com). This enables syncing of performance data and sending server-side conversion events for more accurate tracking and attribution. ### 2.1. Facebook (Meta) Ads [Complete How-To Guide for Onboarding Facebook (Meta) in Upstack Data](/guides/facebook-ads/complete-how-to-guide-for-onboarding-facebook-meta-in-upstack-data) ### 2.2. Google Ads [Complete How-To Guide for Onboarding Google Ads in Upstack Data](/guides/google-ads/complete-how-to-guide-for-onboarding-google-ads-in-upstack-data) ### 2.3. Snapchat Ads [Complete How-To Guide for Onboarding Snapchat in Upstack Data](/guides/snapchat-ads/complete-how-to-guide-for-onboarding-snapchat-in-upstack-data) ### 2.4. Pinterest Ads [Complete How-To Guide for Onboarding Pinterest in Upstack Data](/guides/pinterest-ads/complete-how-to-guide-for-onboarding-pinterest-in-upstack-data) ### 2.5. Tiktok Ads [Complete How-To Guide for Onboarding TikTok Ads in Upstack Data](/guides/tiktok-ads/complete-how-to-guide-for-onboarding-tiktok-ads-in-upstack-data) ## Part 3: Connect email & CRM platforms In this step, you'll connect your email and CRM platforms (such as Klaviyo and Omnisend) to [Upstack Data](https://app.upstackdata.com). This syncs customer data and events, enabling enriched reporting and more effective marketing automation. ### 3.1. Klaviyo #### 3.1.1. Klaviyo Integration Setup [Complete How-To Guide for Onboarding Klaviyo in Upstack Data](/guides/klaviyo/complete-how-to-guide-for-onboarding-klaviyo-in-upstack-data) #### 3.1.2. Upstack Abandonment Flows Setup [Complete Guide to Setting Up Upstack Abandonment Flows in Klaviyo](/guides/klaviyo-abandonment-flows/complete-guide-to-setting-up-upstack-abandonment-flows-in-klaviyo) ### 3.2 Omnisend [Complete How-To Guide for Onboarding Omnisend in Upstack Data](/guides/omnisend/complete-how-to-guide-for-onboarding-omnisend-in-upstack-data) ## Part 4: Data Integrations setup In this step, you'll configure Data Integrations in the [Upstack dashboard](https://app.upstackdata.com/pixel/integrations) to unify tracking across platforms. This ensures accurate event collection, consistent attribution, and reliable reporting. ### 4.1. Facebook (Meta) Ads [How to Connect your Facebook Ads Account in Upstack Data Integrations](/guides/facebook-ads/how-to-connect-your-facebook-ads-account-in-upstack-data-integrations) ### 4.2. Google Ads [How to Connect your Google Ads Account in Upstack Data Integrations](/guides/integrations/how-to-connect-your-google-ads-account-in-upstack-data-integrations) ## Part 5: Verify the install After completing the previous parts, confirm everything is wired up correctly before scaling spend: * In [Shopify Admin → Settings → Customer events](https://admin.shopify.com), confirm the **UpstackData** Custom Pixel is **Connected**. * In [Shopify Admin → Online Store → Themes → Customize → App embeds](https://admin.shopify.com), confirm **UpStackified Pixel** is enabled on your live theme. * In the [Upstack dashboard](https://app.upstackdata.com), open **Event Health** and confirm `PageView`, `AddToCart`, `InitiateCheckout`, and `Purchase` events are arriving. * On the [Data Integrations](https://app.upstackdata.com/pixel/integrations) page, confirm every connected destination shows status **Healthy**. * In each destination platform's event manager (e.g., [Meta Events Manager](https://business.facebook.com/events_manager), Google Ads conversions), confirm events are arriving via the server-side / CAPI channel. <Note> **Need help?** If you encounter any issues during setup, contact our support team and we'll help diagnose the problem. </Note> ## What's next <CardGroup> <Card title="Explore analytics" icon="chart-line" href="/analytics/query-guide"> Build custom reports with the analytics dashboard and query builder. </Card> <Card title="Use the CLI" icon="terminal" href="/cli/install"> Query data and automate workflows from the command line. </Card> <Card title="Troubleshoot issues" icon="wrench" href="/troubleshooting/pixel-stuck-on-waiting-for-first-events"> Common fixes if events aren't appearing after setup. </Card> <Card title="Manage billing" icon="credit-card" href="/billing/subscriptions-and-billing"> View invoices, upgrade plans, and manage your subscription. </Card> </CardGroup> # How to get the most out of Upstack Data: a complete guide Source: https://docs.upstackdata.com/guides/getting-started/get-the-most-out-of-upstack-data A complete guide to setting up Upstack Data: connecting destinations, configuring sources, improving event match quality, and using attribution insights. Upstack Data gives Shopify brands three capabilities in one platform: server-side event tracking, multi-touch attribution, and Klaviyo data enrichment. This guide walks you through everything you need to do after installation to get the most value from the platform — from connecting your ad accounts to understanding your attribution dashboard. ## Prerequisites * The Upstack Data app installed in your [Shopify Admin](https://admin.shopify.com) (see [Install on Shopify](/get-started/install-on-shopify)) * An [Upstack Data](https://app.upstackdata.com) account with subscription active * Admin access to each destination you'll connect (Meta, Google Ads, TikTok, Klaviyo, etc.) * Admin access to each source you'll connect for reporting (Shopify, Meta, Google Ads, TikTok) ## Upstack's three products <CardGroup> <Card title="Signal — server-side tracking" icon="satellite-dish"> Sends Shopify events (page views, add-to-carts, checkouts, purchases) to ad platforms via server-side APIs (Meta CAPI, Google Ads, TikTok Events API). Each event is enriched with identity data before delivery for higher match rates and better optimization signal. </Card> <Card title="Analytics — attribution and reporting" icon="chart-line"> Pulls spend data from your ad platforms and combines it with Shopify revenue data to show which channels, campaigns, and ads are driving results. Gives you a unified view that doesn't rely solely on any single ad platform's self-reported numbers. </Card> <Card title="Flows — marketing automation enrichment" icon="envelope"> Sends enriched event data to Klaviyo and Omnisend, giving your abandonment flows and segments more complete customer profiles. Abandoned cart emails, browse abandonment, and win-back campaigns trigger more often and personalize better. </Card> </CardGroup> ## First 48 hours after installation Your first two days are about getting data flowing. Here's what to prioritize: <Steps> <Step title="Day 1 — Connect your primary destinations"> 1. **Connect [Meta CAPI](/destinations/meta-capi).** This is typically the highest-priority destination. You'll need your Pixel ID and ad account access. See [Connect a destination](/get-started/connect-a-destination). 2. **Connect [Google Ads](/destinations/google-ads).** Enter your conversion action ID and connect your Google Ads account. 3. **Connect any additional destinations** ([TikTok](/destinations/tiktok), [Pinterest](/destinations/pinterest), [Klaviyo](/destinations/klaviyo), [Snapchat](/destinations/snapchat), [Omnisend](/destinations/omnisend)) you actively advertise on. </Step> <Step title="Day 1–2 — Connect your sources"> 1. **Connect [Shopify](/sources/shopify)** (typically done automatically during [app installation](/get-started/install-on-shopify)). 2. **Connect ad platform spend data** for [Meta](/sources/facebook-ads), [Google](/sources/google-ads), and [TikTok](/sources/tiktok) so your attribution dashboard has complete spend data. </Step> <Step title="Day 2 — Verify data is flowing"> 1. Open [Meta Events Manager](https://business.facebook.com/events_manager) and confirm events are arriving from Upstack via the **Conversions API** channel. 2. Open the [Upstack dashboard](https://app.upstackdata.com) and confirm event activity under **Event Health**. 3. **Don't panic if EMQ shows 0.0** — Meta takes 24–48 hours to calculate Event Match Quality scores. See [Why is my Meta EMQ panel showing zeros?](/guides/facebook-ads/why-is-my-meta-emq-panel-showing-zeros-0-0-10). </Step> </Steps> <Tip> Don't forget to [disable existing tracking](/get-started/disable-existing-tracking) (Shopify's native Facebook/Google data sharing) once Upstack is sending server-side events. Leaving both enabled can cause duplicate events and less accurate optimization. </Tip> ## Setting up all destinations Destinations are the platforms Upstack sends event data to. Set up every platform you actively advertise on or use for marketing automation. | Destination | What Upstack sends | Priority | | -------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------- | | [Meta CAPI](/destinations/meta-capi) | Purchase, Add to Cart, View Content, Initiate Checkout, custom events via CAPI | High | | [Google Ads](/destinations/google-ads) | Purchase and conversion events via offline conversions | High | | [TikTok](/destinations/tiktok) | Purchase and funnel events via Events API | Medium | | [Klaviyo](/destinations/klaviyo) | Browse, cart, and purchase events for flow triggering | Medium–High | | [Pinterest](/destinations/pinterest) | Conversion events via Conversions API | Medium | | [Snapchat](/destinations/snapchat) | Conversion events via Conversions API | Lower | | [Omnisend](/destinations/omnisend) | Browse, cart, and purchase events for flow triggering | Medium (if you use Omnisend) | | [Webhooks](/destinations/webhooks) | Any configured event to a custom HTTP endpoint | As needed | For the full list and configuration options, see the [destinations overview](/destinations/overview). ## Setting up sources for reporting Sources feed your attribution dashboard. Without them, Analytics can show your Shopify revenue but can't calculate ROAS or compare channel performance. | Source | What it provides | | -------------------------------------------- | ---------------------------------------------------------- | | [Shopify](/sources/shopify) | Order data, revenue, product details, customer information | | [Meta (Facebook Ads)](/sources/facebook-ads) | Ad spend, campaign structure, impressions, clicks | | [Google Ads](/sources/google-ads) | Ad spend, campaign structure, impressions, clicks | | [TikTok](/sources/tiktok) | Ad spend, campaign structure, impressions, clicks | Connect every platform where you're spending ad budget so your attribution dashboard has complete data. See the [sources overview](/sources/overview). ## Understanding your attribution dashboard Once destinations and sources are connected, your Analytics dashboard will begin populating with attribution data. Here's how to read it: * **Revenue data** comes from Shopify orders and is attributed to channels based on Upstack's attribution model. * **Spend data** comes from your connected ad platform sources. * **ROAS (Return on Ad Spend)** is calculated by dividing attributed revenue by ad spend for each channel. * **Attribution windows** determine how far back Upstack looks to credit a touchpoint. The default window is typically 7 days for clicks and 1 day for views, configurable by plan. See [Attribution and reporting](/concepts/attribution-and-reporting) for a full walkthrough. ## Configuring costs for accurate P\&L For your attribution dashboard to show accurate profitability, it needs your complete cost picture: 1. **Ad spend** is pulled automatically from connected sources (Meta, Google, TikTok). 2. **Product costs (COGS)** may need to be configured depending on your plan. See [Configure contribution margin](/get-started/configure-contribution-margin). 3. **Shipping and handling costs** may be available through Shopify order data. ## Optimizing Klaviyo flows with Upstack Flows If you use Klaviyo for email and SMS, [Upstack Flows](/destinations/klaviyo) can significantly improve your flow performance: <Steps> <Step title="Connect Klaviyo as a destination"> Use your Klaviyo API key. See the [Klaviyo destination guide](/destinations/klaviyo). </Step> <Step title="Confirm enriched events are flowing"> Browse and cart events flow to Klaviyo with more complete customer profiles, meaning your abandonment flows trigger for more visitors — not just those already identified by Klaviyo's on-site tracking. </Step> <Step title="Review your flow triggers"> Ensure your abandoned cart, browse abandonment, and other flows are set up to use the events coming from Upstack. </Step> <Step title="Monitor flow performance"> After connecting, you should see an increase in flow recipients and improved conversion rates from those flows. </Step> </Steps> ## Monitoring EMQ and pixel health Event Match Quality (EMQ) is Meta's 0–10 score measuring how well your event data matches to real Facebook users. Upstack's identity enrichment is designed to improve your EMQ compared to browser-only tracking. <Info> **EMQ benchmarks** * **7.0+** is considered good. * **9.0+** is excellent and indicates strong identity matching. * **Below 5.0** suggests missing identity parameters or configuration issues. </Info> ### How to check 1. View your EMQ score in the [Upstack dashboard](https://app.upstackdata.com) under **Event Health**. 2. Cross-reference in [Meta Events Manager](https://business.facebook.com/events_manager) under your pixel's event details. 3. If EMQ is lower than expected, verify all identity parameters are being sent (email, phone, name, address data). For troubleshooting, see [Why is my Meta EMQ panel showing zeros?](/guides/facebook-ads/why-is-my-meta-emq-panel-showing-zeros-0-0-10). ## Custom events for advanced optimization Once your standard tracking is running, consider adding [custom events](/guides/custom-events/how-to-create-custom-event-triggers) to improve ad platform optimization: * **`nc_purchase` (new customer purchase)** — lets Meta and Google optimize for acquiring new buyers specifically. This is the most popular and impactful custom event for most brands. * **Category-specific purchases** — optimize for purchases in specific product categories. * **Quiz or form completions** — give ad platforms mid-funnel signals. ## When to contact support vs. self-serve <AccordionGroup> <Accordion title="Self-serve tasks"> * Adding or removing destinations * Connecting new sources * Viewing attribution reports * Checking EMQ scores * Creating custom events </Accordion> <Accordion title="Contact Upstack support"> * EMQ remains at 0.0 after 48+ hours with confirmed purchases * Events are not appearing in your ad platform's event manager after 24 hours * Discrepancies between Upstack attribution and Shopify revenue * Questions about which attribution model is right for your business * Issues with Shopify app permissions or installation * Billing or plan questions </Accordion> </AccordionGroup> ## Frequently asked questions <AccordionGroup> <Accordion title="How long does it take to see data after connecting Upstack?"> Events begin flowing to destinations within minutes of connecting. Attribution data in the Analytics dashboard depends on having both event data and spend data connected, and may take 24–48 hours to fully populate. EMQ scores from Meta take 24–48 hours to calculate. </Accordion> <Accordion title="Do I need to disable my existing Facebook pixel?"> No. Upstack's server-side tracking works alongside your existing browser-side pixel. However, you should [disable Facebook's built-in data sharing](/get-started/disable-existing-tracking) within Shopify's settings, as Upstack replaces that functionality with better-enriched server-side events. </Accordion> <Accordion title="Which destination should I connect first?"> Connect the platform where you spend the most ad budget first. For most Shopify brands, this is Meta. Getting high-quality data flowing to your largest spend platform produces the biggest impact on ad performance. </Accordion> <Accordion title="Can I use Upstack with agencies managing my ads?"> Yes. Share your Upstack dashboard access with your agency so they can see attribution data. Your agency will also see improved event data quality in the ad platforms they manage, which benefits their optimization. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Install on Shopify" icon="shopify" href="/get-started/install-on-shopify"> Get the Upstack app installed and configured in your store. </Card> <Card title="Connect a destination" icon="plug" href="/get-started/connect-a-destination"> Step-by-step setup for your first destination. </Card> <Card title="Disable existing tracking" icon="ban" href="/get-started/disable-existing-tracking"> Turn off Shopify's built-in pixel sharing to avoid duplicate events. </Card> <Card title="Custom events" icon="code" href="/guides/custom-events/how-to-create-custom-event-triggers"> Add custom events like `nc_purchase` for advanced optimization. </Card> <Card title="Destinations overview" icon="arrow-right-from-bracket" href="/destinations/overview"> Every supported destination. </Card> <Card title="Sources overview" icon="arrow-right-to-bracket" href="/sources/overview"> Every supported source. </Card> <Card title="Why is my Meta EMQ showing zeros?" icon="circle-question" href="/guides/facebook-ads/why-is-my-meta-emq-panel-showing-zeros-0-0-10"> Troubleshoot EMQ scores stuck at 0.0. </Card> </CardGroup> # Complete How-To Guide for Onboarding Google Ads in Upstack Data Source: https://docs.upstackdata.com/guides/google-ads/complete-how-to-guide-for-onboarding-google-ads-in-upstack-data Onboard Google Ads in Upstack Data — create a purchase goal with Enhanced Conversions, connect your account, and forward server-side conversions for accurate Smart Bidding signal. <Info> **New to Upstack?** Follow the [getting started guide](/get-started/install-on-shopify) for a streamlined onboarding walkthrough. </Info> <Tip> **Quick Summary** * Create a new Purchase conversion goal named **"Purchase - UpstackData"** in [Google Ads](https://ads.google.com). * Configure the goal with a **30-day click-through window and Enhanced Conversions enabled**. * Set up the Google Ads destination in the Upstack dashboard with your **Conversion ID and Conversion Label**. * Switch the goal to **Primary optimization** after 4–7 days. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * **Admin** or **Manager** access to a **Google Ads** account * Permission to create or edit **conversion actions** in Google Ads <Steps> <Step title="Create a New Purchase Conversion Goal"> Help guide to complete this step: [How to Create a New Upstack Data Purchase Goal in Google Ads →](/guides/google-ads/how-to-create-a-new-upstack-data-purchase-goal-in-google-ads) </Step> <Step title="Create and Configure Google Ads Pixel Destination in Upstack Data"> Help guide to complete this step: [How to Configure Google Ads Pixel Destination in Upstack Data →](/guides/google-ads/how-to-configure-google-ads-destination-in-upstack-data) Where to find your Google Conversion ID and Label: [How to Get Your Google Ads Conversion ID and Label →](/guides/google-ads/how-to-get-your-google-ads-conversion-id-and-label) </Step> <Step title="Enable the Google Ads Upstack Purchase Goal and Switch to Primary Optimization Goal"> <Note> When creating a new Purchase Goal in Google Ads (Purchase - Upstack Data), we initially will set this as the secondary goal, for observation only. We advise to make this goal Primary after 4-7 days to allow the Goal to become active. All other Purchase goals are then set to secondary when Upstack becomes **Primary.** </Note> Help guide to complete this step: [How to Enable the Google Ads Upstack Purchase Goal and Switch to Primary Optimization Goal →](/guides/google-ads/how-to-enable-the-google-ads-upstack-purchase-goal-and-switch-to-primary-optimization-goal) </Step> </Steps> <Tip> **Optional: enable server-side forwarding.** For maximum coverage, also turn on the Google Ads Conversions API so Upstack forwards events server-side even when the browser pixel is blocked. See [How to Set Up Google Ads Server-Side Conversions API in Upstack Data →](/guides/google-ads/how-to-set-up-google-ads-server-side-conversions-api-in-upstack-data). </Tip> ## Verify the Setup After completing all three steps: * In the Upstack dashboard, navigate to **Events Destination** at [app.upstackdata.com/pixel/event-destinations](https://app.upstackdata.com/pixel/event-destinations) and confirm the Google Ads destination shows as **Healthy**. * In Google Ads, go to **Goals → Conversions → Summary** and confirm **"Purchase - UpstackData"** is listed and (after 4–7 days) marked **Primary**. * Place a test order on your store and check that the conversion appears in Google Ads within 24–48 hours. <Note> **Need help?** If you encounter any issues during setup or don't see expected improvements after 10 days, contact our support team with your Google Ads **Conversion ID** and **Conversion Label** and we'll help diagnose the problem. </Note> # How to Configure Google Ads Destination in Upstack Data Source: https://docs.upstackdata.com/guides/google-ads/how-to-configure-google-ads-destination-in-upstack-data Configure the Google Ads destination in Upstack Data with your Conversion ID and Conversion Label to forward server-side purchases with Enhanced Conversions match keys. <Tip> **Quick Summary** * In the Upstack dashboard, click **"+ New Destination"** and select Google Ads. * In Google Ads, find your conversion under **Goals → Conversions → Summary**. * Open **Tag Setup** to reveal your **Conversion ID** and **Conversion Label**. * Paste both values into the Upstack dashboard and **Create Configuration**. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * **Admin** or **Manager** access to a **Google Ads** account * An existing **Purchase conversion action** in Google Ads (or follow [How to Create a New Upstack Data Purchase Goal in Google Ads](/guides/google-ads/how-to-create-a-new-upstack-data-purchase-goal-in-google-ads) first) ## Configuration Steps <Steps> <Step title="Sign in to Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com). </Step> <Step title="Add a new Google Ads destination"> * In the Upstack dashboard, navigate to **Events Destination** ([app.upstackdata.com/pixel/event-destinations](https://app.upstackdata.com/pixel/event-destinations)) * Click **"+ New Destination"** in the top-right corner of the page <img alt="Add New Destination" /> * In the **Select a Destination** popup, click **"Google Ads"** * Click **Next** <img alt="Select Google Ads destinations" /> </Step> <Step title="Find your conversion in Google Ads"> * In a new tab, sign in to [Google Ads](https://ads.google.com) * In the left-hand menu, navigate to **Goals → Conversions → Summary** <img alt="Google Ads menu with Goals and Conversions Summary options" /> *`Google Ads Conversions Summary Page`* Find your primary Purchase conversion (usually named **"Purchase - UpstackData"**) and click to open it. <img alt="Primary Purchase conversion event in Google Ads Conversions list" /> *`Example Primary Conversion Event`* <Note> **Note:** Your conversion may be named differently. Look for the primary event linked to your purchase conversion. </Note> </Step> <Step title="Open Tag Setup to reveal your IDs"> On the conversion detail page, scroll down to the **Tag Setup** section and click **"Use Google Tag Manager"**. <Note> For a step-by-step walkthrough, see [How to Get Your Google Ads Conversion ID and Label →](/guides/google-ads/how-to-get-your-google-ads-conversion-id-and-label). </Note> <img alt="Tag Setup section with Use Google Tag Manager option" /> Google Ads displays your **Conversion ID** and **Conversion Label**. * **Conversion ID** — starts with `AW-` followed by 9–10 digits (e.g., `AW-123456789`) * **Conversion Label** — 11-character alphanumeric string (e.g., `ABc1d2EFG3h`) <img alt="Google Tag Manager showing Conversion ID and Conversion Label values" /> </Step> <Step title="Enter your Conversion ID and Conversion Label"> Back in the Upstack dashboard: * In the **Conversion ID** field, paste your full Conversion ID from Google Ads (e.g., `AW-123456789`). The `AW-` prefix is required. * In the **Conversion Label** field, paste your Conversion Label from Google Ads (e.g., `ABc1d2EFG3h`). <img alt="Upstack Google Ads destination form with Conversion ID and Label fields" /> </Step> <Step title="Create the configuration"> Click the **Create Configuration** button to save the setup. <img alt="Create Configuration button to save Google Ads destination" /> <Note> **Success! 🎉** You should see a confirmation message and the Google Ads destination will appear as **"Healthy"** in your destinations list. </Note> <img alt="Google Ads destination showing Healthy status in destinations list" /> </Step> </Steps> ## Verify the Setup To confirm the destination is working: * In the Upstack dashboard, the Google Ads destination should show **Healthy** status under **Events Destination**. * Place a test order on your store and check Google Ads **Goals → Conversions → Summary** within 24–48 hours to confirm the conversion is recorded. If the destination shows **Unhealthy** or no conversions arrive, double-check that: * The **Conversion ID** starts with `AW-` and matches the value shown in Google Ads. * The **Conversion Label** was copied without leading or trailing spaces. * The conversion action in Google Ads is enabled and not paused. If issues persist, contact Upstack Data support with your **Conversion ID** and **Conversion Label**. # How to Create a New Upstack Data Purchase Goal in Google Ads Source: https://docs.upstackdata.com/guides/google-ads/how-to-create-a-new-upstack-data-purchase-goal-in-google-ads Create an Upstack Data purchase conversion goal in Google Ads with Enhanced Conversions enabled — required for server-side conversion forwarding from Upstack to Google. <Tip> **Quick Summary** * In Google Ads, navigate to **Goals → Conversions → Summary** and click **"+ Create conversion action"**. * Select **Conversions on a website**. * Choose **Purchase** as the goal type and select **Set up manually using a code**. * Name the conversion **"Purchase - UpstackData"**, set **Click-through conversion window** to **30 days**, and enable **Enhanced Conversions**. * **Save** to generate your Conversion ID and Conversion Label. </Tip> ## Prerequisites Before you start, you need: * **Admin** or **Manager** access to a **Google Ads** account * Permission to create conversion actions in Google Ads ## Step-by-Step Instructions <Steps> <Step title="Sign in to Google Ads"> Sign in to [Google Ads](https://ads.google.com). </Step> <Step title="Open the Conversions summary"> In the left-hand menu, navigate to **Goals → Conversions → Summary**. <img alt="Google Ads left menu with Goals, Conversions, and Summary navigation" /> </Step> <Step title="Create a new conversion action"> * Click the **"+ Create conversion action"** button * Select **"Conversions on a website"** by ticking the checkbox on the right side of the panel * Click **Save and continue** <img alt="Create conversion action button in Conversions Summary" /> <img alt="Select Conversions on a website option with checkbox" /> </Step> <Step title="Configure the Purchase goal"> * Select **"Purchase"** as the goal/conversion action * In the **"Choose an event to measure Purchase"** panel, under **"Create a new conversion action"**, select **"Set up manually using a code"** * Click **"Conversion settings"** to expand the section * Set the **Conversion name** to **"Purchase - UpstackData"** * Set **Click-through conversion window** to **30 days** <img alt="Set up manually using a code option with Purchase goal selected" /> `Example - select **Set up manually using a code** and **Purchase** as the Goal/Conversion action` <img alt="Conversion name field with Purchase UpstackData and 30 day window" /> `Example - Conversion name: **Purchase - UpstackData** and Click-through conversion window: **30 days**` </Step> <Step title="Enable Enhanced Conversions"> Check the **"Use enhanced conversion for conversion action"** option to enable **Enhanced Conversions**. Click **Done** to save the changes and close the panel. <img alt="Enhanced Conversions checkbox enabled for conversion action" /> <Note> **Note:** Enhanced Conversions improves match rates by using first-party customer data securely. </Note> </Step> <Step title="Save the configuration"> Click **Save and Continue** to complete the setup. <img alt="Save and Continue button to complete conversion setup" /> <Note> *If your Google Ads interface looks different, see:* \*\*[How to Create a Purchase Goal in Google Ads Using the Google Ads Tag (For Different Interface) →](/guides/google-ads/how-to-create-a-purchase-goal-in-google-ads-using-the-google-ads-tag-for-different-interface)\*\* </Note> </Step> </Steps> ## What You'll Receive After saving, Google Ads displays: * **Conversion ID** — starts with `AW-` followed by 9–10 digits (e.g., `AW-123456789`) * **Conversion Label** — 11-character alphanumeric string (e.g., `ABc1d2EFG3h`) Use these values in your Upstack Data destination configuration. ## Verify the Setup To confirm the goal was created correctly: * Return to **Goals → Conversions → Summary** in Google Ads — the new **"Purchase - UpstackData"** conversion should appear in the list with a status of **Inactive** (it will become **Active** once it receives data). * Confirm the **Click-through conversion window** is **30 days** and **Enhanced Conversions** is enabled on the conversion's detail page. If the conversion is missing, refresh the page and check that you saved the action. If issues persist, contact Upstack Data support. # How to Enable the Google Ads Upstack Purchase Goal and Switch to Primary Optimization Goal Source: https://docs.upstackdata.com/guides/google-ads/how-to-enable-the-google-ads-upstack-purchase-goal-and-switch-to-primary-optimization-goal Promote the Upstack Data purchase goal from secondary to primary in Google Ads after 4–7 days of data — switching optimization to server-side conversions for better Smart Bidding performance. <Tip> **Quick Summary** * Wait 4–7 days after creating the **"Purchase - UpstackData"** goal so Google can collect baseline data. * In Google Ads, navigate to **Goals → Summary** and click **Edit goals**. * Open the **Conversion action optimization** section. * Set **"Purchase - UpstackData"** as **Primary** and switch all other Purchase goals to **Secondary**. * Click **Save**. </Tip> ## Prerequisites Before you start, you need: * **Admin** or **Manager** access to the **Google Ads** account * The **"Purchase - UpstackData"** conversion already created and live for **4–7 days** (see [How to Create a New Upstack Data Purchase Goal in Google Ads →](/guides/google-ads/how-to-create-a-new-upstack-data-purchase-goal-in-google-ads)) ## Importance of this Step <Note> When creating the **"Purchase - UpstackData"** goal in Google Ads, we initially set it as **Secondary** for observation only. This allows Google to collect baseline data without disrupting current optimization. After 4–7 days, switching to **Primary** activates the goal as the optimization target with sufficient data. </Note> ## Steps to Switch Your Purchase Goal <Steps> <Step title="Sign in to Google Ads"> Sign in to [Google Ads](https://ads.google.com). </Step> <Step title="Open the Goals summary"> In the left-hand menu, navigate to **Goals → Summary**. <img alt="Google Ads left menu with Goals and Summary navigation selected" /> </Step> <Step title="Find the Purchase conversions list"> On the Goals Summary page, scroll down to the **Purchase** conversion list. <img alt="Google Ads Goals Summary page showing Purchase conversion list" /> </Step> <Step title="Open the goal settings"> Click **Edit goals** to open the goal settings panel. <img alt="Edit goals button in Google Ads conversion settings" /> </Step> <Step title="Expand Conversion action optimization"> Click **"Conversion action optimization"** to expand the section. <img alt="Conversion action optimization section expanded in goal settings" /> </Step> <Step title="Set Purchase - UpstackData as Primary"> Set **"Purchase - UpstackData"** as **Primary**. <img alt="Purchase UpstackData goal set as Primary conversion action" /> </Step> <Step title="Set other Purchase goals to Secondary"> Set all other Purchase goals to **Secondary**. <Warning> Ensure only **one Primary** Purchase conversion goal is active at a time. </Warning> <img alt="Other Purchase goals switched to Secondary status" /> <img alt="Goal list showing Purchase UpstackData as Primary with others as Secondary" /> `Example: Purchase - UpstackData is Primary and other Purchase conversions are Secondary` </Step> <Step title="Save the changes"> Click **Save** to apply the new settings. <img alt="Save button to apply goal optimization changes in Google Ads" /> </Step> </Steps> ## Verify the Setup To confirm the switch was applied: * Return to **Goals → Summary** in Google Ads — **"Purchase - UpstackData"** should be labelled **Primary** and all other Purchase goals should be labelled **Secondary**. * Open one of your active Search or Performance Max campaigns and confirm it is optimizing against the new Primary goal. If the goal still appears as Secondary, refresh the page and re-open **Edit goals** to confirm the change saved. If issues persist, contact Upstack Data support. # How to Get Your Google Ads Conversion ID and Label Source: https://docs.upstackdata.com/guides/google-ads/how-to-get-your-google-ads-conversion-id-and-label Find your Google Ads Conversion ID and Conversion Label from an existing purchase conversion — both required to configure the Upstack Data Google Ads destination. <Tip> **Quick Summary** * In Google Ads, navigate to **Goals → Conversions → Summary**. * Click your **Purchase conversion** to open its detail page. * Scroll to **Tag Setup** and click **"Use Google Tag Manager"**. * Copy the **Conversion ID** (`AW-` followed by 9–10 digits) and the **Conversion Label** (11-character alphanumeric string). </Tip> ## Prerequisites Before you start, you need: * **Admin** or **Manager** access to a **Google Ads** account * An existing Purchase conversion action (e.g., **"Purchase - UpstackData"**). If you haven't created one yet, see [How to Create a New Upstack Data Purchase Goal in Google Ads →](/guides/google-ads/how-to-create-a-new-upstack-data-purchase-goal-in-google-ads). ## Steps to Find Your Conversion ID and Label <Steps> <Step title="Sign in to Google Ads"> Sign in to [Google Ads](https://ads.google.com). </Step> <Step title="Open the Conversions summary"> In the left-hand menu, navigate to **Goals → Conversions → Summary**. <img alt="Google Ads left menu with Goals, Conversions, and Summary options" /> </Step> <Step title="Open your Purchase conversion"> Find and click your **"Purchase - UpstackData"** conversion (or your existing purchase conversion). <img alt="Purchase UpstackData conversion in Conversions Summary list" /> </Step> <Step title="Scroll to Tag Setup"> On the conversion detail page, scroll down to the **Tag Setup** section. <img alt="Tag Setup section" /> </Step> <Step title="Click Use Google Tag Manager"> Click **"Use Google Tag Manager"**. <img alt="Use Google Tag Manager button in Tag Setup section" /> `Use Google Tag Manager button` </Step> <Step title="Copy your Conversion ID and Conversion Label"> Google Ads displays: * **Conversion ID** — starts with `AW-` followed by 9–10 digits (e.g., `AW-123456789`) * **Conversion Label** — 11-character alphanumeric string (e.g., `ABc1d2EFG3h`) <img alt="Conversion ID and Conversion Label values displayed in GTM setup" /> Copy both values, then paste them into your Google Ads destination in the Upstack dashboard ([app.upstackdata.com/pixel/event-destinations](https://app.upstackdata.com/pixel/event-destinations)). Click **Create Configuration** in the Upstack dashboard to save the setup. <img alt="Upstack Google Ads destination form with ID and Label fields filled" /> </Step> </Steps> ## Verify the Setup To confirm you copied the correct values: * The **Conversion ID** should match the format `AW-` + 9–10 digits. * The **Conversion Label** should be exactly 11 characters (letters and digits, no spaces). * After saving in the Upstack dashboard, the Google Ads destination should appear as **Healthy** under **Events Destination**. If the destination shows **Unhealthy**, re-open the **Tag Setup** in Google Ads to confirm both values were copied without leading or trailing spaces. If issues persist, contact Upstack Data support. # How to Set Up Google Ads Server-Side Conversions API in Upstack Data Source: https://docs.upstackdata.com/guides/google-ads/how-to-set-up-google-ads-server-side-conversions-api-in-upstack-data Connect Google Ads with OAuth and map your tracked events to conversion actions so Upstack forwards purchases server-side via the Google Ads Conversions API — independent of the browser pixel. <Tip> **Quick Summary** * Open your Google Ads destination in Upstack and turn on **Enable Conversion API**. * Click **Connect Google Ads** and grant Upstack offline access during the Google consent screen. * Select the **Google Ads account** you want to forward conversions to. * In **Event Conversion Mappings**, link each tracked event to a conversion action — use **Create & Link** to create dedicated Upstack conversion actions automatically. * Save the configuration and confirm the destination shows **Healthy**. </Tip> ## What the Conversions API path adds The browser pixel (Conversion ID and Conversion Label) tracks your **primary** conversion from the visitor's browser. The server-side **Conversions API** runs alongside it: Upstack sends each tracked event directly to Google Ads server-to-server, attached to its own dedicated conversion action. Server-side delivery reaches Google even when the browser pixel is blocked by ad blockers, ITP, or cookie restrictions, and it carries the original click identifier (`gclid`, `gbraid`, or `wbraid`) plus SHA-256 hashed customer data for Enhanced Conversions match-rate uplift. <Note> The Conversions API and the browser pixel run **independently and in parallel**. Enabling server-side forwarding does not change or disable your pixel — the pixel keeps tracking your primary conversion using the **Conversion ID** on the destination. </Note> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * An existing **Google Ads destination** in Upstack with the **Conversion ID** and **Pixel ID** already filled in. If you haven't set those yet, follow [How to Configure Google Ads Destination in Upstack Data →](/guides/google-ads/how-to-configure-google-ads-destination-in-upstack-data) first. * **Admin** or **Manager** access to a **Google Ads** account, with permission to create or edit **conversion actions** * The Google account you sign in with during OAuth must have access to the Google Ads account you want to forward to (including the manager/MCC account, if you use one) ## Setup Steps <Steps> <Step title="Open your Google Ads destination"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com), navigate to **Events Destination** ([app.upstackdata.com/pixel/event-destinations](https://app.upstackdata.com/pixel/event-destinations)), and open your **Google Ads** destination. If you haven't created the destination yet, add it first using [How to Configure Google Ads Destination in Upstack Data →](/guides/google-ads/how-to-configure-google-ads-destination-in-upstack-data). </Step> <Step title="Enable the Conversion API"> Turn on the **Enable Conversion API** toggle on the destination. The server-side connection panel appears below the pixel fields. </Step> <Step title="Connect Google Ads with OAuth"> In the **Connect Google Ads** card, click **Connect Google Ads**. A Google consent screen opens. Sign in with a Google account that has access to your Google Ads account and grant the requested permissions. <Warning> You must grant **offline access** so Google returns a refresh token. If you skip or revoke that permission, Upstack shows the error *"Google did not return a refresh token. Make sure you grant offline access."* — reconnect and accept all requested scopes. </Warning> On success the panel updates to **Google Ads Server-Side Connected** with the connection timestamp. </Step> <Step title="Select your Google Ads account"> Under **Google Ads Account**, choose the account you want to forward conversions to. The dropdown lists every account your connected Google login can access, shown as **Account Name (10-digit ID)**. <Note> If you manage accounts through a manager (MCC) account, pick the individual advertising account that owns the conversions — not the manager account itself. </Note> </Step> <Step title="Map events to conversion actions"> The **Event Conversion Mappings** table loads pre-filled with common events so you can map them quickly: * **Purchase** * **NC Purchase** (new customer purchase) * **Subscription Initial Purchase** * **Subscription Recurring Purchase** * **Add to Cart** * **Initiate Checkout** For each row, set the **Conversion Action** the event should report to: * **Pick an existing action** from the dropdown, or * Choose **+ Create new in Google Ads** to create a dedicated conversion action for that event (named *" - Upstack (Server-side)"*). Use **+ Add Mapping** to add a row for a custom event (type the event name into the event combobox), and the trash icon to remove any event you don't want to forward. <Tip> To set up everything at once, fill in the event names you want and click **Create & Link**. Upstack creates a dedicated Google Ads conversion action for every row that doesn't have one yet and links it for server-side forwarding. Remove any rows you don't need **before** clicking it. </Tip> </Step> <Step title="Save the configuration"> Save the destination. You need at least one complete mapping (an event name **and** a conversion action) for server-side forwarding to start. <Note> If no row has both an event and a conversion action, Upstack shows *"No server-side events will be forwarded yet."* The pixel keeps running regardless — only server-side forwarding is paused until you complete a mapping. </Note> </Step> </Steps> ## Promote new conversion actions carefully Conversion actions that Upstack creates start as **secondary** (observation-only) goals. As with any new Google Ads conversion, run them alongside your existing setup for **7–14 days** and confirm the volume reconciles before promoting one to **primary**. See [How to Enable the Google Ads Upstack Purchase Goal and Switch to Primary Optimization Goal →](/guides/google-ads/how-to-enable-the-google-ads-upstack-purchase-goal-and-switch-to-primary-optimization-goal). ## Verify the Setup After saving: * The Google Ads destination should show **Healthy** under **Events Destination** in the Upstack dashboard. * Place a test order on your store, then check **Goals → Conversions → Summary** in Google Ads within 24–48 hours and confirm the mapped conversion action records the event. ## FAQ & Troubleshooting <AccordionGroup> <Accordion title="Do I still need the pixel Conversion ID and Pixel ID?"> Yes. The Conversion ID and Pixel ID power the browser pixel, which tracks your primary conversion and remains required on the destination. The Conversions API is an additional server-side path that forwards events to their own conversion actions — it does not replace the pixel. </Accordion> <Accordion title="Why does Upstack create separate conversion actions instead of using my pixel conversion?"> Sending server-side events into the same conversion the pixel fires would mix two sources into one goal and make deduplication and quality comparison impossible. Dedicated server-side conversion actions keep the data clean and let you compare them against your existing goals before promoting any to primary. </Accordion> <Accordion title="I got an error that the conversion action name already exists."> Google reserves the names of conversion actions even after they're removed, so creating *"Purchase - Upstack (Server-side)"* can fail if one existed before (*"A Google Ads conversion action named … already exists in this account"*). Give the action a different display name and try again. </Accordion> <Accordion title="A conversion action shows '— removed in Google Ads'."> The action was deleted on the Google Ads side after it was mapped in Upstack. Pick a different existing action or create a new one for that event, then save. </Accordion> <Accordion title="I use a manager (MCC) account — does that work?"> Yes. Connect with a Google login that can access the account through the manager account, then select the individual advertising account that owns the conversions. Upstack handles the manager-account context when it forwards events. </Accordion> <Accordion title="How do I turn off server-side forwarding?"> Click **Disconnect** in the connection panel, or turn off **Enable Conversion API**. This clears the stored OAuth connection, the selected account, and all event mappings. The browser pixel keeps tracking your primary conversion. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Configure destination" icon="sliders" href="/guides/google-ads/how-to-configure-google-ads-destination-in-upstack-data"> Set the pixel Conversion ID and Pixel ID on the Google Ads destination. </Card> <Card title="Enable primary goal" icon="circle-check" href="/guides/google-ads/how-to-enable-the-google-ads-upstack-purchase-goal-and-switch-to-primary-optimization-goal"> Promote a conversion to primary so Smart Bidding optimizes against it. </Card> <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding"> How Upstack Signal forwards events to ad platforms via server-to-server APIs. </Card> <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination"> End-to-end diagnostic guide when events aren't arriving at any destination. </Card> </CardGroup> # [DRAFT] How Custom Event Mappings Work for Health & Wellness Stores Source: https://docs.upstackdata.com/guides/health-wellness/custom-event-mappings-health-wellness Learn why Upstack replaces standard Meta event names with custom events, how to use them in Ads Manager, and the full mapping reference. ### The Short Version Upstack's Health & Wellness container replaces standard Meta events (like Purchase and AddToCart) with **custom-named events** (like `UPSTACK_HW_6117d13b`). This prevents Meta's automated flagging systems from recognizing and restricting your conversion events. The custom events work identically for campaign optimization — you just need to approve them in Events Manager and select them when setting up your ad sets. ### Why Standard Event Names Are a Problem Meta defines a set of standard events — Purchase, AddToCart, InitiateCheckout, ViewContent, and others — that are used across millions of advertisers. These event names are deeply integrated into Meta's advertising system for optimization, reporting, and audience building. For Health & Wellness flagged stores, this is a problem. When Meta sees a Purchase event coming from a domain or pixel that's flagged as H\&W, it applies additional restrictions to that event: * **The event may be blocked from optimization.** Meta can prevent you from using Purchase as an optimization objective in your campaigns. * **The event may be downgraded.** Even if not fully blocked, Meta may give less weight to the event in its delivery algorithm. * **The event triggers automated review.** Standard events on flagged accounts are scrutinized more heavily by Meta's compliance systems. The standard event names essentially act as labels that Meta's flagging system monitors. By replacing them with custom event names that Meta's system doesn't recognize as health-related, the events pass through without triggering these restrictions. ### How Custom Event Mappings Work ### What Changes Every standard Meta event is remapped to a unique custom event name. The mapping is consistent — the same standard event always maps to the same custom event — so Meta can learn and optimize on the custom events just like it would with standard ones. For example: * When a customer makes a purchase, instead of sending a `Purchase` event, Upstack sends `UPSTACK_HW_6117d13b` * When a customer adds an item to their cart, instead of `AddToCart`, Upstack sends `UPSTACK_HW_de792bda` The custom event names are deterministic hashes — they look random but map consistently to the same standard event. This means `UPSTACK_HW_6117d13b` always means "Purchase" across all Upstack H\&W customers. ### What Stays the Same The custom event carries all the same data as the standard event it replaces: * **Value and currency** — still attached for conversion value optimization * **User identifiers** — still hashed and sent for attribution * **Event timing** — still accurate The only thing that changes is the `event_name` field. From Meta's perspective, it's receiving a custom conversion event with value data — exactly like any other custom event an advertiser might define. ### Full Event Mapping Reference <table><tbody><tr><td><p><b>Standard Event</b></p></td><td><p><b>H\&W Custom Event</b></p></td><td><p><b>Notes</b></p></td></tr><tr><td><p>PageView</p></td><td><p>PageView</p></td><td><p>Unchanged — not flagged</p></td></tr><tr><td><p>ViewContent</p></td><td><p>ViewContent</p></td><td><p>Unchanged — not flagged</p></td></tr><tr><td><p>ViewCategory</p></td><td><p>view\_category</p></td><td><p>Minor rename</p></td></tr><tr><td><p>AddToCart</p></td><td><p>UPSTACK\_HW\_de792bda</p></td><td /></tr><tr><td><p>InitiateCheckout</p></td><td><p>UPSTACK\_HW\_d823e4ff</p></td><td /></tr><tr><td><p>Purchase</p></td><td><p>UPSTACK\_HW\_6117d13b</p></td><td><p>Primary optimization event</p></td></tr><tr><td><p>Lead</p></td><td><p>UPSTACK\_HW\_289161cb</p></td><td /></tr><tr><td><p>Schedule</p></td><td><p>UPSTACK\_HW\_5a3811fb</p></td><td /></tr><tr><td><p>Complete Registration</p></td><td><p>UPSTACK\_HW\_895b83ff</p></td><td /></tr><tr><td><p>Contact</p></td><td><p>UPSTACK\_HW\_4c62e638</p></td><td /></tr><tr><td><p>Invite Meeting Sched.</p></td><td><p>UPSTACK\_HW\_529b7e00</p></td><td /></tr><tr><td><p>AddPaymentInfo</p></td><td><p>UPSTACK\_HW\_9984f5f9</p></td><td /></tr><tr><td><p>AddShippingInfo</p></td><td><p>UPSTACK\_HW\_3c4012cc</p></td><td /></tr><tr><td><p>All Purchase</p></td><td><p>UPSTACK\_HW\_f0e986fc</p></td><td><p>All purchases (new + returning)</p></td></tr><tr><td><p>NC Purchase</p></td><td><p>UPSTACK\_HW\_fa2b3354</p></td><td><p>New customer purchases only</p></td></tr><tr><td><p>RC Purchase</p></td><td><p>UPSTACK\_HW\_5ec76558</p></td><td><p>Returning customer purchases only</p></td></tr></tbody></table> Note that **PageView** and **ViewContent** are sent with their standard names. These top-of-funnel events are generally not restricted by the H\&W flag, and keeping them standard helps with audience building and funnel reporting in Meta. ### Approving Custom Events in Meta Events Manager When custom events first appear in Meta Events Manager, they show a **red triangle warning** (⚠️). This is normal — Meta flags any new custom event that hasn't been explicitly approved by the account owner. Until you approve them, the events are tracked but **cannot be used for campaign optimization**. This means you must approve the events before you can set up ad sets that optimize toward them. ### How to Approve <Steps> <Step title="Open Meta Events Manager"> Sign in to [Meta Events Manager](https://business.facebook.com/events_manager) and select your new (clean) pixel. You'll see the custom events listed with red triangle icons. </Step> <Step title="Review each event"> For each event, click the event name or the warning icon, then click **Review** or **Manage Status**. </Step> <Step title="Confirm the event"> Click **I acknowledge**, then click **Confirm the custom event → Confirm**. </Step> </Steps> The red triangle disappears and the event becomes available for optimization. For detailed steps with screenshots: [How to Approve Facebook (Meta) Custom Events →](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events) ### Using Custom Events in Ads Manager Once approved, custom events work exactly like standard events in your campaign setup. ### Setting Up Campaigns When creating or editing an ad set, you'll choose your optimization event. Instead of selecting "Purchase" from the standard events dropdown, you'll: <Steps> <Step title="Find Custom Events in the optimization dropdown"> In Meta Ads Manager, on the ad set screen, open the **Performance Goal / Conversion Event** dropdown and scroll to **Custom Events** (or the custom events section). </Step> <Step title="Select the Purchase event"> Choose `UPSTACK_HW_6117d13b` (this is your Purchase event). </Step> <Step title="Continue with campaign settings"> Continue with your normal campaign settings. Everything else — budget, audience targeting, bidding strategy, creative — stays exactly the same. </Step> </Steps> ### Reporting and Columns In Ads Manager reporting, custom events appear as their custom names. To make reporting easier: * **Add custom columns** for your key H\&W events (especially `UPSTACK_HW_6117d13b` for Purchase). * **Create saved column presets** so you don't have to reconfigure reporting views each time. * **Use custom conversions** if you want to create more readable names in reporting (e.g., create a custom conversion called "H\&W Purchase" based on the `UPSTACK_HW_6117d13b` event). ### Value Optimization Because the custom Purchase event still carries value and currency data, you can use **value-based optimization** (ROAS bidding) with H\&W events. This works identically to optimizing toward a standard Purchase event with value. ### Why Not Just Use Custom Conversions Instead? You might wonder why Upstack sends entirely different event names rather than sending a standard Purchase event and relying on Meta's custom conversions feature to filter. The reason is that Meta's restriction layer operates at the **event level**, not the custom conversion level: * A standard `Purchase` event from a flagged source is restricted **before** it reaches the optimization layer. * A custom event name like `UPSTACK_HW_6117d13b` is not in Meta's restriction list, so it passes through normally. Custom conversions are a reporting/optimization feature that sits on top of events. They can't bypass restrictions that are applied to the underlying event itself. ### NC Purchase vs. RC Purchase vs. All Purchase Upstack's H\&W mappings include three Purchase variants: **All Purchase (`UPSTACK_HW_f0e986fc`)** — Every purchase, regardless of customer type. This is the broadest purchase event. **NC Purchase (`UPSTACK_HW_fa2b3354`)** — New customer purchases only. Fires only when the purchaser is identified as a first-time buyer. Use this when you want to optimize specifically for customer acquisition. **RC Purchase (`UPSTACK_HW_5ec76558`)** — Returning customer purchases only. Fires when an existing customer makes a repeat purchase. **Purchase (`UPSTACK_HW_6117d13b`)** — The primary purchase event, equivalent to Meta's standard Purchase. This is the recommended default for campaign optimization. Which one you optimize toward depends on your business goals. Most brands start with the primary Purchase event and layer in NC/RC optimization as they scale. ### What You Need to Do 1. **Approve all custom events** in Meta Events Manager (the red triangle step). 2. **Update your campaign optimization** to point to `UPSTACK_HW_6117d13b` for Purchase. 3. **Update your Ads Manager reporting columns** to include the custom events you care about. Upstack handles the mapping automatically — you never need to configure which events map to which names. That's built into the H\&W container. ### Related Articles * [Global Event Mappings](/guides/custom-events/global-event-mappings) — set up your own event mappings for any destination * [Health & Wellness Custom Event Mappings](/guides/facebook-ads/health-and-wellness-custom-event-mappings) * [How to Approve Facebook (Meta) Custom Events](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events) * [How Upstack Data Solves Health & Wellness Restrictions](/guides/health-wellness/how-upstack-solves-health-wellness-restrictions) * [How to Set Up a Health & Wellness Pixel for Meta](/guides/health-wellness/setup-health-wellness-pixel-for-meta) # [DRAFT] How Data Sanitization Protects Health & Wellness Stores Source: https://docs.upstackdata.com/guides/health-wellness/data-sanitization-health-wellness Learn what data Upstack scrubs before sending events to Meta, why each piece matters, and exactly what Meta still receives for optimization. ### The Short Version Before any event reaches Meta, Upstack's Health & Wellness container runs it through a **sanitization layer** that strips out product names, URLs, SKUs, and any other content that could contain health or wellness keywords. Meta still gets everything it needs for attribution and optimization — event type, value, currency, and user identifiers — but none of the content that causes flags. ### Why Sanitization Is Necessary Meta's Health & Wellness flagging system doesn't just look at your domain once and make a decision. It continuously evaluates the data your pixel sends. Every event that arrives at Meta carries metadata — and that metadata can contain the keywords, product names, and URLs that trigger or reinforce the flag. Here's what a typical unsanitized Purchase event looks like when sent to Meta: <Note> **Example: Unsanitized event payload** `event_name`: Purchase `event_source_url`: [https://yourstore.com/checkout/thank-you](https://yourstore.com/checkout/thank-you) `content_ids`: \["sup-ashwagandha-60ct"] `content_name`: "Organic Ashwagandha Supplement - 60 Capsules" `content_category`: "Supplements > Adaptogens" `value`: 59.99 | `currency`: USD </Note> Look at what's embedded in that payload: the product is called "Organic Ashwagandha Supplement," the category is "Supplements > Adaptogens," and the content ID contains "sup-ashwagandha." Every one of these fields is a signal to Meta's automated systems that this store sells health and wellness products. ### What Gets Stripped Upstack's sanitization layer removes or neutralizes the following fields before any event is sent to Meta: ### Product Names (content\_name) Any text that identifies what the customer bought or viewed. This is the most common source of flaggable keywords — product titles like "Collagen Peptides Powder" or "Vitamin D3 5000 IU" are exactly what Meta's classifiers look for. **Before:** `"content_name": "Organic Ashwagandha Supplement - 60 Capsules"` **After:** Field removed entirely. ### Product IDs and SKUs (content\_ids) Even encoded or abbreviated product identifiers can contain flaggable terms. A SKU like `CBD-TINCTURE-30ML` or a product ID like `probiotic-daily-60` carries the same signal as the full product name. **Before:** `"content_ids": ["sup-ashwagandha-60ct"]` **After:** Field removed entirely. ### Product Categories (content\_category) Category paths often contain the broadest and most obvious health/wellness terms: "Supplements," "Vitamins," "Health," "Wellness," "CBD," etc. **Before:** `"content_category": "Supplements > Adaptogens"` **After:** Field removed entirely. ### Page URLs (event\_source\_url) The URL where the event occurred is replaced with a URL from the clean alias domain. This prevents Meta from seeing paths like `/products/organic-turmeric-capsules` or `/collections/immune-support`. **Before:** `"event_source_url": "https://yourstore.com/products/organic-ashwagandha"` **After:** `"event_source_url": "https://youraliasdomain.com/"` ### What Still Gets Sent After sanitization, the event that reaches Meta looks like this: <Note> **Example: Sanitized event payload** `event_name`: UPSTACK\_HW\_6117d13b `event_source_url`: [https://youraliasdomain.com/](https://youraliasdomain.com/) `user_data`: hashed email, hashed phone, fbclid, fbp, IP, user agent `value`: 59.99 | `currency`: USD </Note> Here's what each remaining field does: * **event\_name** — Mapped to a custom H\&W event. Tells Meta what action occurred without using flagged standard event names. * **event\_source\_url** — The alias domain URL. Meta's bot can visit this domain and see a compliant page. * **user\_data** — Hashed email, hashed phone, Facebook click ID, browser ID, IP address, and user agent. These are the identity signals Meta uses to match the event to a user. They contain no product or health information. * **value and currency** — The monetary value of the conversion. Essential for ROAS optimization and value-based bidding. ### Why This Level of Scrubbing Is Necessary You might wonder: "Can't we just rename the products or change the URLs?" In practice, partial measures don't hold up: **Meta's classifiers are broad.** They don't just look for the word "supplement." They flag terms like "capsules," "extract," "daily," "formula," "blend," and dozens of other words common across health product catalogs. Trying to rename everything to be compliant is a losing game. **The flag is persistent.** Once a domain is flagged, Meta's systems are primed to look for health-related content from that source. Even mildly suggestive terminology can reinforce the classification. Clean scrubbing removes the ambiguity entirely. **You can't control every surface.** Product data shows up in URLs, page titles, meta tags, structured data, Open Graph tags, and more. The browser pixel can read all of these. Server-side sanitization is the only way to ensure nothing slips through. **Future-proofing.** If you add a new product line or a new employee adds products with flaggable names, the sanitization layer catches it automatically. You don't need to audit every SKU before launching. ### How Sanitization Interacts with Other Components Data sanitization doesn't work alone — it's one piece of the four-part H\&W solution: * **Server-side-only tracking** ensures the browser pixel never sends unsanitized data directly to Meta. * **Data sanitization** cleans the event payload before it leaves Upstack's servers. * **Domain aliasing** replaces the flagged domain in the event\_source\_url field. * **Custom event mappings** replace standard event names with non-flaggable custom names. All four layers work together. If you removed sanitization but kept the other three, product data in the event payload could still trigger a re-flag. If you kept sanitization but sent from the flagged domain, Meta's domain-level restrictions would still apply. ### What You Need to Do Nothing — sanitization is handled automatically by Upstack's Health & Wellness container. There is no configuration required on your end. <Note> **Note on product-level reporting:** Since product IDs and names are stripped, you won't see per-product conversion breakdowns in Meta Ads Manager. You can still get this data from Shopify analytics, the [Upstack dashboard](https://app.upstackdata.com), or third-party attribution tools like Triple Whale (which receives unsanitized data since it's not sending to Meta). </Note> ### Related Articles * [How Upstack Data Solves Health & Wellness Restrictions](/guides/health-wellness/how-upstack-solves-health-wellness-restrictions) * [How to Set Up a Health & Wellness Pixel for Meta](/guides/health-wellness/setup-health-wellness-pixel-for-meta) # [DRAFT] How Upstack Data Solves Health & Wellness Restrictions Source: https://docs.upstackdata.com/guides/health-wellness/how-upstack-solves-health-wellness-restrictions Restore accurate Meta tracking for Health & Wellness brands with Upstack's protective container — server-side-only delivery, data sanitization, domain aliasing, and custom event mappings. Learn how Upstack's Health & Wellness container restores accurate Meta tracking using server-side-only delivery, data sanitization, domain aliasing, and custom event mappings. ### Overview When Meta flags your store under Health & Wellness, standard tracking breaks down. Upstack Data implements a specialized **Health & Wellness container** that works around these restrictions while staying fully compliant. The result: Meta receives high-quality conversion data for optimization, and your store avoids being re-flagged. The solution has four components that work together. ### 1. Server-Side-Only Tracking For Health & Wellness stores, Upstack **removes the Facebook browser pixel entirely** and operates server-side only via Meta's Conversions API (CAPI). **Why this matters:** The browser pixel (JavaScript) has a mind of its own — it sits on your website and grabs data automatically, including product names, URLs, and page content that may contain flaggable keywords. Upstack cannot control what the browser pixel pulls, and it runs in the background independently. By going server-side only through CAPI, Upstack has complete control over every piece of data sent to Meta with **100% guaranteed delivery**. The entire Upstack platform is built around ensuring redundancy without the browser pixel. ### 2. Data Sanitization Before sending any data to Meta, Upstack pre-processes it to remove anything that could trigger a flag: * **Product names** containing health/wellness keywords are stripped — for example, a product like "Magnesium Supplement for Cramping" would be flagged because "cramping" is a medical condition in that context. * **Product URLs** with flaggable terms are cleaned. * **Product descriptions** that could indicate medical conditions are filtered. * **SKUs, product IDs, and titles** are removed or anonymized. * Only **essential data** is sent: event type, purchase value, currency, and user identifiers (email, phone, click ID). Meta still receives everything it needs for accurate attribution and optimization — without the content that causes flags. ### 3. Domain Aliasing All events are sent from a **clean alias domain** instead of your flagged primary domain. This prevents new pixels from inheriting the flag. How it works: * The alias domain is a separate root domain (not a subdomain) that you register. * It has a simple, compliant landing page — just a headline and an image. * No real traffic is ever sent to this domain. It exists so Meta's compliance bot sees a clean page. * All CAPI events are reported as originating from this alias domain. Since the Health & Wellness flag is attached to your domain (not your pixel), aliasing is what makes the entire solution work. The alias domain prevents Meta from connecting the event data you're sending to anything that has previously been flagged on their backend. Domain aliasing has **no negative performance impact** — it is purely a safety measure. ### 4. Custom Event Mappings Standard Meta events (AddToCart, Purchase, etc.) are mapped to **Upstack Health & Wellness custom events** to avoid triggering Meta's automated flagging systems. For example, the Purchase event becomes `UPSTACK_HW_6117d13b` and AddToCart becomes `UPSTACK_HW_de792bda`. These custom events must be approved in Meta Events Manager before they can be used for campaign optimization. For the full mapping table: [Health & Wellness Custom Event Mappings →](/guides/facebook-ads/health-and-wellness-custom-event-mappings) For instructions on approving custom events: [How to Approve Facebook (Meta) Custom Events →](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events) ### Dual-Pixel Transition Strategy When switching to a new pixel, Upstack supports a **dual-pixel approach**: * Data feeds to **both your existing pixel and the new clean pixel** simultaneously. * Your current campaigns continue running on the existing pixel while the new pixel builds up data. * Once the new pixel has enough data (typically about a week), you can begin migrating campaigns. * How fast you switch depends on your current ad performance — if things are painful, switch quickly; if performance is acceptable, train the new pixel with data first and transition gradually. If your existing pixel has not been flagged and retains its audience data, you may be able to continue using it instead of creating a new one. Discuss this with the Upstack team during onboarding. ### Ongoing Protection Once set up with the Health & Wellness container: * **No re-flagging** as long as all Meta events are sent through Upstack (no direct browser pixel, no data from the flagged domain). This approach has a **100% success rate** in preventing re-flagging. * **The alias domain stays in place permanently** — the registration fee and hosting cost are the only ongoing expenses. * **Theme changes don't break tracking** since everything is server-side (no Theme App Extension dependency for Meta events). * **No extra cost** — the Health & Wellness container, implementation, and ongoing support are all included in your Upstack subscription. ### Get Started Ready to set up the Health & Wellness solution? Follow the step-by-step guide: [How to Set Up a Health & Wellness Pixel for Meta →](/guides/health-wellness/setup-health-wellness-pixel-for-meta) ### Related Articles * [Understanding Meta's Health & Wellness Flag](/guides/health-wellness/understanding-meta-health-wellness-flag) * [How to Set Up a Health & Wellness Pixel for Meta](/guides/health-wellness/setup-health-wellness-pixel-for-meta) * [Health & Wellness Custom Event Mappings](/guides/facebook-ads/health-and-wellness-custom-event-mappings) * [How to Approve Facebook (Meta) Custom Events](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events) # [DRAFT] How Server-Side-Only Tracking Protects Health & Wellness Stores Source: https://docs.upstackdata.com/guides/health-wellness/server-side-tracking-health-wellness-protection Learn why Upstack removes the Meta browser pixel entirely for Health & Wellness flagged stores and sends all data through the Conversions API instead. ### The Short Version For stores flagged under Meta's Health & Wellness category, Upstack Data operates in **server-side-only mode** — meaning the Facebook browser pixel (the JavaScript snippet that normally runs on your website) is completely removed. All event data is sent directly from Upstack's servers to Meta through the Conversions API (CAPI). This gives Upstack complete control over what data reaches Meta, which is the foundation of the entire Health & Wellness solution. ### Why the Browser Pixel Is a Problem for H\&W Stores The standard Meta pixel is a JavaScript snippet that runs in your customer's browser. When someone visits your store, the pixel automatically reads information from the page and sends it to Meta. This includes: * The **page URL** (e.g., `yourstore.com/products/organic-ashwagandha-supplement`) * The **page title** (e.g., "Organic Ashwagandha Supplement - 60 Capsules") * **Product data** embedded in the page (names, descriptions, categories) * **Referrer URLs** that may contain health-related search terms * **Content IDs** and other metadata tied to your product catalog The problem is that this happens automatically. The browser pixel scrapes whatever is on the page and sends it along with the event. For a Health & Wellness flagged store, this means Meta is constantly receiving data full of the exact keywords and content that triggered the flag in the first place — product names with words like "supplement," "vitamin," "collagen," "probiotic," or "CBD." Even if you've already been flagged, continuing to send this kind of data through the browser pixel can: * **Reinforce the flag**, making it harder to resolve * **Trigger a re-flag** if you've set up a new pixel * **Reduce Event Match Quality** as Meta discards or downgrades events it considers non-compliant You cannot selectively control what the browser pixel sends. It reads the DOM (the page content) and transmits what it finds. This is by design — Meta wants as much signal as possible for optimization. But for H\&W stores, that same signal is what causes the restrictions. ### How Server-Side-Only Mode Works When Upstack activates the Health & Wellness container, the tracking flow changes completely: ### Standard Tracking (Browser + Server) In a normal Upstack setup, events are sent two ways: 1. **Browser pixel** fires in the customer's browser and sends data directly to Meta 2. **Server-side (CAPI)** sends the same event from Upstack's servers to Meta Both carry a shared `event_id` so Meta deduplicates them into a single event. This redundancy improves match rates and ensures events aren't lost to ad blockers or browser restrictions. ### Health & Wellness Mode (Server-Only) In H\&W mode, the Meta browser pixel is removed entirely: <Steps> <Step title="Customer actions are captured"> Customer actions (page views, add to cart, purchases) are captured by Upstack's Theme App Extension on your store. </Step> <Step title="Data is sent to Upstack"> Event data is sent to **Upstack's servers** — not to Meta. </Step> <Step title="Data is sanitized"> Upstack **processes and sanitizes** the data (see the [Data Sanitization](/guides/health-wellness/data-sanitization-health-wellness) article). </Step> <Step title="Clean event is sent to Meta"> The clean event is sent to Meta via the **Conversions API only**. </Step> </Steps> No JavaScript from Meta ever runs on your site. Meta never sees your page content, URLs, or product data directly. ### What Data Gets Sent to Meta In server-side-only mode, Upstack sends only what Meta needs for attribution and optimization: **Always sent:** * **Event type** — the action that occurred (mapped to a custom H\&W event name) * **Event time** — when the action happened * **User identifiers** — hashed email, hashed phone number, Facebook click ID (`fbclid`), and browser ID (`fbp`) for matching the event to a Meta user * **Event source URL** — the alias domain URL (not your real store URL) **Sent for conversion events (Purchase, Add to Cart, etc.):** * **Value** — the purchase amount or cart value * **Currency** — e.g., USD **Never sent:** * Product names, descriptions, or categories * Real page URLs from your flagged domain * SKUs, product IDs, or catalog data * Any content that could contain health/wellness keywords This is enough data for Meta to attribute conversions to your ads, optimize delivery, and build audiences — without exposing any content that would trigger or reinforce the H\&W flag. ### Why CAPI-Only Still Works for Optimization A common concern is that removing the browser pixel will hurt performance. In practice, for H\&W flagged stores, the opposite is true. **The browser pixel was already compromised.** Once a store is flagged, Meta restricts what it does with browser pixel data from that domain. In many cases, browser events are partially or fully ignored for optimization. Removing a data source that Meta is already discounting doesn't hurt you — it removes a liability. **CAPI events are treated as higher quality.** Server-side events carry hashed first-party data (email, phone) that provides stronger identity matching than cookies alone. Meta's own documentation recommends CAPI as the primary data source, with the browser pixel as a supplement. **Event Match Quality stays strong.** EMQ depends on the quality of user identifiers (email, phone, click ID), not on the transmission method. Upstack captures these identifiers at key moments (checkout, account creation) and sends them via CAPI. Most Upstack H\&W customers see EMQ scores comparable to or better than their pre-flag performance. **The flag was the real performance killer.** The biggest optimization hit comes from the flag itself — restricted audiences, blocked events, degraded delivery. By going server-side only with clean data from an unflagged domain, you're restoring what the flag took away. ### How This Differs from Standard CAPI Setups Not all server-side tracking is the same. Here's how Upstack's H\&W implementation differs from a standard CAPI setup: <table><tbody><tr><td><p><b>Feature</b></p></td><td><p><b>Standard CAPI</b></p></td><td><p><b>Upstack H\&W (Server-Only)</b></p></td></tr><tr><td><p>Browser pixel active</p></td><td><p>Yes (redundant tracking)</p></td><td><p>No (completely removed)</p></td></tr><tr><td><p>Data sanitization</p></td><td><p>No</p></td><td><p>Yes (keywords, URLs, product data stripped)</p></td></tr><tr><td><p>Event source URL</p></td><td><p>Your real domain</p></td><td><p>Clean alias domain</p></td></tr><tr><td><p>Event names</p></td><td><p>Standard Meta events</p></td><td><p>Custom H\&W event mappings</p></td></tr><tr><td><p>Product data sent</p></td><td><p>Yes (content\_ids, content\_name)</p></td><td><p>No (stripped before sending)</p></td></tr></tbody></table> A standard CAPI setup still relies on the browser pixel running alongside it. For H\&W stores, that browser pixel is the source of the problem. Upstack's approach eliminates it entirely and controls every byte of data that reaches Meta. ### What You Need to Do Nothing — Upstack handles this automatically when the Health & Wellness container is activated during your onboarding call. The browser pixel removal, CAPI-only routing, and data processing all happen on Upstack's side. <Note> **Watch for other tracking tools.** Any active browser pixel — from Shopify's native integration, Triple Whale Sonar, Elevar, or hardcoded JavaScript — will send unsanitized data to Meta and undermine the server-side-only approach. Make sure all other Meta pixel sources are disabled. </Note> [How to Disable Facebook and Instagram Data Sharing in Shopify →](/guides/facebook-ads/how-to-disable-facebook-and-instagram-data-sharing-in-shopify) ### Related Articles * [How Upstack Data Solves Health & Wellness Restrictions](/guides/health-wellness/how-upstack-solves-health-wellness-restrictions) * [How to Set Up a Health & Wellness Pixel for Meta](/guides/health-wellness/setup-health-wellness-pixel-for-meta) * [How to Disable Facebook and Instagram Data Sharing in Shopify](/guides/facebook-ads/how-to-disable-facebook-and-instagram-data-sharing-in-shopify) # [DRAFT] How to Set Up an Alias Domain for Health & Wellness Tracking Source: https://docs.upstackdata.com/guides/health-wellness/setup-alias-domain-health-wellness Step-by-step instructions for registering a clean alias domain and building a compliant landing page for Meta's Health & Wellness tracking solution. Step-by-step instructions for registering a clean alias domain and building a compliant landing page for Meta's Health & Wellness tracking solution. ### Prerequisites * An [Upstack Data](https://app.upstackdata.com) account in good standing (subscription active) * Admin access to your [Meta Business Manager](https://business.facebook.com) and the (new, unflagged) pixel you'll use for H\&W tracking * A new domain registrar account (Namecheap, GoDaddy, Cloudflare, etc.) for purchasing the alias domain * Access to a hosting provider or landing page builder (Carrd, Unbounce, Instapage, or any static host) * A means to contact the Upstack team (your shared Slack channel or `support@upstackdata.com`) ### Why You Need an Alias Domain Meta's Health & Wellness flag is attached to your domain. Any pixel receiving events from a flagged domain will also get flagged — even a brand-new pixel. The alias domain gives your new pixel a clean origin so it stays unflagged. The alias domain is a separate root domain with a simple landing page. No real traffic goes to it. It exists solely so that Meta's compliance bot sees a clean, compliant page when it checks the event source. ### Requirements Your alias domain must meet all of the following: **Must be a new root domain.** For example, `mybrandwellness.com`. It cannot be a subdomain like `safe.mybrand.com` — Meta flags at the root domain level. **Must have no history with Meta.** Register a brand-new domain that has never been used with a Meta pixel or ad account. **Must never receive real ad traffic.** Do not run ads pointing to this domain. It is only for Meta's bot to visit. **Must have a simple, compliant landing page.** A headline and an image — nothing that references health, wellness, or supplement products. **Must be hosted somewhere accessible.** Any cheap hosting option works: Carrd, Unbounce, Instapage, or simple static hosting. ### Setup Steps <Steps> <Step title="Register the domain"> Purchase a new root domain from any registrar (Namecheap, GoDaddy, Cloudflare, etc.). Choose something brand-adjacent but generic — avoid words like "health," "wellness," "supplements," or "vitamins" in the domain name itself. **Good examples:** `mybrandshop.com`, `shopbrandname.com`, `brandlifestyle.com`, `getbrandname.com`, `trybrandname.com` **Bad examples:** `mybrandsupplements.com`, `brandwellnessstore.com`, `brandvitamins.com` A common pattern is to take your existing domain and add a prefix like "get" or "shop." For example, if your store is `tryanomalyhealth.com`, your alias could be `getanomalyhealth.com`. </Step> <Step title="Build the landing page"> The landing page needs to be simple and compliant. Here's what to include: **What to put on the page:** * A generic headline (e.g., an advertorial-style headline that does not mention supplements, health, wellness, or medical terms) * A stock image * That's it — no forms, no product listings, no links to your real store The page can be as simple as a single image — nobody will ever see it. Some brands repurpose an existing landing page and just remove any medical or health terminology. A listicle-style page with broad lifestyle content also works well. **What NOT to put on the page:** * Any health or wellness product names, descriptions, or keywords (e.g., "osteoporosis," "cramping," "supplement," "vitamin") * Links to your flagged store * Supplement, vitamin, or medical terminology * Real product content of any kind You can use any landing page builder. Carrd (\$19/year) or a single HTML file on static hosting are the simplest options. </Step> <Step title="Verify the domain in Meta Events Manager"> Once the landing page is live: 1. Sign in to [Meta Events Manager](https://business.facebook.com/events_manager). 2. Select your new (unflagged) pixel. 3. Open **Settings → Domains**, add the alias domain, and complete the domain verification process Meta provides (typically a DNS TXT record or `meta-tag` upload). 4. Wait for domain approval — this is required before Upstack can activate aliasing. </Step> <Step title="Request aliasing activation"> After the domain is approved in Meta Events Manager, contact the Upstack team to enable domain aliasing: * **Slack:** Post in your shared Slack channel. * **Email:** [support@upstackdata.com](mailto:support@upstackdata.com). Upstack will configure aliasing so all events report from the clean alias domain instead of your flagged primary domain. </Step> <Step title="Verify aliasing is live"> After Upstack confirms the alias is live: 1. Trigger a test event (e.g., place a test order or load a tracked page). 2. In [Meta Events Manager](https://business.facebook.com/events_manager) → your new pixel → **Test Events** or **Overview**, confirm the **Event Source URL** matches your alias domain (not your flagged primary domain). 3. In the [Upstack dashboard](https://app.upstackdata.com), confirm events continue to flow under **Event Health**. </Step> </Steps> ### Ongoing Maintenance The alias domain stays in place permanently. The only ongoing costs are: * **Domain registration renewal** (typically \$10–15/year) * **Hosting** (free to minimal, depending on provider) Do not let the domain registration expire or take down the landing page — Meta's bot may revisit the domain at any time. ### Need Help? If you'd like the Upstack team to review your landing page before going live, post it in your shared Slack channel for a quick sign-off. ### Related Articles * [How to Set Up a Health & Wellness Pixel for Meta](/guides/health-wellness/setup-health-wellness-pixel-for-meta) * [Understanding Meta's Health & Wellness Flag](/guides/health-wellness/understanding-meta-health-wellness-flag) * [How Upstack Data Solves Health & Wellness Restrictions](/guides/health-wellness/how-upstack-solves-health-wellness-restrictions) # [DRAFT] How to Set Up a Health & Wellness Pixel for Meta Source: https://docs.upstackdata.com/guides/health-wellness/setup-health-wellness-pixel-for-meta Step-by-step guide for setting up Upstack Data's Health & Wellness tracking solution for Meta-flagged stores. Each step links to a focused article with detailed instructions. This guide walks you through setting up Upstack Data's Health & Wellness tracking solution for stores flagged by Meta. Each step links to a focused article with detailed instructions. ### Quick Summary * Upstack restores accurate Meta tracking for stores flagged under Health & Wellness restrictions. * Setup requires a **clean alias domain**, a **new Meta pixel**, and an **Upstack Data account**. * All tracking runs **server-side only** — the browser pixel is removed entirely. * Standard events are mapped to **custom H\&W events** that must be approved in Meta Events Manager. * After setup, migrate your ad campaigns to the new pixel and optimize toward the H\&W Purchase event. ### What Is the Health & Wellness Flag? Meta restricts stores that sell supplements, wellness products, or health-related goods. Once flagged, your pixel loses the ability to fully track and optimize bottom-funnel events like AddToCart and Purchase — leading to weaker campaign performance and declining ROAS. **The flag is attached to your domain, not your pixel.** Creating a new pixel on the same domain will also get flagged. That's why Upstack uses a different approach. [Understanding Meta's Health & Wellness Flag →](/guides/health-wellness/understanding-meta-health-wellness-flag) ### How Upstack Data Solves This Upstack deploys a specialized Health & Wellness container with four components: server-side-only tracking (no browser pixel), data sanitization to strip flaggable content, domain aliasing from a clean domain, and custom event mappings that avoid Meta's automated flagging. [How Upstack Data Solves Health & Wellness Restrictions →](/guides/health-wellness/how-upstack-solves-health-wellness-restrictions) ### Prerequisites Have the following ready before booking your onboarding call: * An **active Shopify store** (`your-store.myshopify.com`) with [Shopify Admin](https://admin.shopify.com) access * A **[Meta Business Manager](https://business.facebook.com)** account with admin access * A **new, clean root domain** for aliasing (see Step 1) * A **new Meta pixel** created but not connected to anything (see Step 2). Meta Pixel ID format: a 15–16 digit number such as `123456789012345` * An **Upstack Data account** at [app.upstackdata.com](https://app.upstackdata.com) with a subscription and payment method on file. Your Upstack Pixel ID format: `XXXX-XXXX-XXXXX-XXXX` (e.g., `58284d43-85f6-41fb-b2e0-f32f8ecb4e9b`) ### Setup Steps <Steps> <Step title="Create your alias domain and landing page"> You'll need a brand-new root domain (not a subdomain) with a simple, compliant page — just a headline and an image. No health/wellness product names, supplement terms, or links to your store. This domain exists solely for Meta's compliance bot. No real ad traffic should ever go to it. [How to Set Up an Alias Domain for Health & Wellness Tracking →](/guides/health-wellness/setup-alias-domain-health-wellness) </Step> <Step title="Create a new Meta pixel"> Create a fresh pixel in Meta Business Manager. **Do not send any data to it from your flagged domain** — even one event will flag the new pixel. 1. Sign in to [Meta Events Manager](https://business.facebook.com/events_manager). 2. Click **Connect Data Sources** (top-left of the page) and create a new **Pixel / Dataset**. 3. Name it (e.g., `Brand Name - Clean Pixel`). 4. Do not configure or connect it to anything yet — just note the Pixel ID (15–16 digits). [How to Configure Facebook (Meta) Ads Pixel Destination in Upstack Data →](/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data) </Step> <Step title="Set up your Upstack Data account"> Sign up, select a plan, and enter your payment information. [How to Download and Install Upstack Data App in Shopify →](/guides/shopify/how-to-download-and-install-upstack-data-app-in-shopify) </Step> <Step title="Book your onboarding call"> With the alias domain, new pixel, and Upstack account ready, book an onboarding call (typically 30–45 minutes). The Upstack team will handle: * Standard Shopify setup * Health & Wellness container activation (the "protective layer") * Domain aliasing configuration * Meta destination setup with CAPI in server-side-only mode The H\&W container typically takes the Upstack team an afternoon to configure and push live after the onboarding call. <Warning> Do not connect your Facebook Ads or send any data to Meta until the Upstack team confirms the Health & Wellness protective layer has been deployed. Connecting before the container is active increases your risk of getting flagged or banned. </Warning> [Complete Upstack Data Onboarding Guide →](/guides/getting-started/complete-upstack-data-onboarding-guide) </Step> <Step title="Approve the alias domain in Meta Events Manager"> During or after onboarding: 1. Sign in to [Meta Events Manager](https://business.facebook.com/events_manager) and select your new pixel. 2. Open **Settings → Domains** and add the alias domain. 3. Complete the domain verification process Meta prompts you through. <Warning> Domain approval is required before aliasing can be activated. </Warning> </Step> <Step title="Activate domain aliasing"> Contact the Upstack team via your shared Slack channel or [support@upstackdata.com](mailto:support@upstackdata.com) to enable domain aliasing. Once activated, all events will report from the clean alias domain instead of your flagged domain. </Step> <Step title="Approve custom events in Meta Events Manager"> Custom H\&W events will appear with red triangle warnings in Events Manager. Each must be acknowledged and confirmed before it can be used for optimization. **Key event for campaign optimization:** `UPSTACK_HW_6117d13b` (Purchase) [How to Approve Facebook (Meta) Custom Events →](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events) For the full event mapping reference: [Health & Wellness Custom Event Mappings →](/guides/facebook-ads/health-and-wellness-custom-event-mappings) </Step> <Step title="Disable conflicting tracking"> Turn off all other sources sending events to Meta to prevent duplicate events and avoid re-flagging: * **Shopify Facebook & Instagram data sharing** — disable under [Shopify Admin → Settings → Apps and sales channels → Facebook & Instagram](https://admin.shopify.com). * **Third-party tracking apps** (Triple Whale Sonar, Elevar, etc.) — disable Meta event sending in each app. * **Hardcoded Meta pixel code** — remove from your Shopify theme (`theme.liquid` and any custom snippets). [How to Disable Facebook and Instagram Data Sharing in Shopify →](/guides/facebook-ads/how-to-disable-facebook-and-instagram-data-sharing-in-shopify) </Step> <Step title="Migrate campaigns to the new pixel"> During the transition, Upstack feeds data to **both your existing pixel and the new clean pixel** simultaneously. This lets the new pixel build up audience data before you switch campaigns. Your media buyers will need to: 1. Create new campaigns (or duplicate existing ones) pointing to the new pixel. 2. Optimize toward the H\&W custom Purchase event: `UPSTACK_HW_6117d13b`. 3. Gradually shift spend from the old pixel to the new one. 4. Monitor performance as the new pixel exits Meta's learning phase. Migration speed depends on your ad spend, risk tolerance, and how painful your current ad performance is. If performance has degraded significantly, you may want to switch quickly. If performance is still acceptable, consider training the new pixel with about a week of data before transitioning. Some brands cut over immediately; others run both pixels in parallel for 1–2 weeks. <Note> If your existing pixel has not been flagged and retains its audience data, you may be able to continue using it rather than creating a new one. Discuss this with the Upstack team during onboarding. </Note> </Step> <Step title="Verify the H&W setup is working"> Once the container is live and campaigns are pointed at the clean pixel: 1. Place a test order on your store. 2. In [Meta Events Manager](https://business.facebook.com/events_manager) → your new pixel → **Test Events** or **Overview**, confirm the test event arrives via the **Conversions API** channel and the **Event Source URL** is your alias domain (not your flagged primary domain). 3. Confirm the event uses the H\&W custom event name (e.g., `UPSTACK_HW_6117d13b` for Purchase) — not the standard `Purchase` event. 4. In the [Upstack dashboard](https://app.upstackdata.com) → **Event Health**, confirm the event is listed and shows status **Sent**. 5. Confirm there are no events being sent to Meta from any other source (no browser pixel from Shopify, no Triple Whale, no Elevar, no hardcoded scripts). </Step> </Steps> ### What to Expect After Setup <table><tbody><tr><td><p>Milestone</p></td><td><p>Timeframe</p></td></tr><tr><td><p>Events start flowing via CAPI</p></td><td><p>Immediately</p></td></tr><tr><td><p>EMQ improvements visible</p></td><td><p>Within 72 hours</p></td></tr><tr><td><p>Full optimization impact</p></td><td><p>14–21 days</p></td></tr><tr><td><p>Campaign performance recovery</p></td><td><p>Varies by brand</p></td></tr></tbody></table> Once set up, you should never get re-flagged as long as all Meta events flow through Upstack. **Using a third-party checkout?** (e.g., Phoenix, Checkout Champ) Let the Upstack team know before going live so tracking can be configured for your checkout platform. ### Need Help? Reach out via your shared Slack channel or contact support with your Meta Pixel ID. ### Related Articles * [Health & Wellness Custom Event Mappings](/guides/facebook-ads/health-and-wellness-custom-event-mappings) * [How to Approve Facebook (Meta) Custom Events](/guides/facebook-ads/how-to-approve-facebook-meta-custom-events) * [How to Configure Facebook (Meta) Ads Pixel Destination in Upstack Data](/guides/facebook-ads/how-to-configure-facebook-meta-ads-pixel-destination-in-upstack-data) * [How to Disable Facebook and Instagram Data Sharing in Shopify](/guides/facebook-ads/how-to-disable-facebook-and-instagram-data-sharing-in-shopify) * [Complete How-To Guide for Setting Up the Upstack Data App in Shopify](/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify) * [Complete Upstack Data Onboarding Guide](/guides/getting-started/complete-upstack-data-onboarding-guide) # [DRAFT] Understanding Meta's Health & Wellness Flag Source: https://docs.upstackdata.com/guides/health-wellness/understanding-meta-health-wellness-flag Learn what Meta's Health & Wellness flag is, how it affects your ad performance, and why standard fixes like creating a new pixel don't work. Learn what Meta's Health & Wellness flag is, how it affects your ad performance, and why standard fixes like creating a new pixel don't work. ### What Is the Health & Wellness Flag? Meta categorizes certain stores — those selling supplements, wellness products, or health-related goods — under a restricted "Health & Wellness" category. Once your store is flagged, Meta applies stricter privacy and content policies that limit what data your pixel can collect and use for optimization. There is no notification from Meta when the flag is applied. Most brands discover it when they see unexplained performance declines or when events stop being accepted for optimization. ### Why Meta Created the Health & Wellness Category The policy originated after Hims & Hers gained public visibility through their IPO filings, which revealed how much they were spending on Facebook ads. Because their products are medical in nature, every customer who purchased through Facebook was effectively listed in Meta's database as buying a medical product — creating what amounts to a medical patient profile. Meta realized it was collecting protected health information at scale without the facilities to manage it, and faced significant legal liability. In response, Meta implemented a new layer of rules specifically around the **data** advertisers send back, on top of existing creative and landing page compliance requirements. The fundamental stance is "don't ask, don't tell" — Meta doesn't want to collect potentially problematic health data, and as long as you don't send it, there's no problem. ### How It Impacts Performance There is no uniform severity — Meta doesn't expose "levels" of the flag. However, brands typically see one of three patterns: **Minimal impact.** The flag appears but the brand sees no noticeable performance change. Everything continues to work as normal. **Steep drop-off.** Performance drops sharply right after the flag. Ad spend goes to near-zero or CPA spikes dramatically. **Slow decline.** A gradual decline over weeks or months. CPMs may rise (or sometimes drop to unrealistically low levels). Targeting degrades because Meta is optimizing on partial data. Eventually performance stabilizes at a lower baseline that becomes very hard to escape. ### What Gets Restricted The specifics vary, but common restrictions include: * **Loss of Purchase event optimization.** In some cases, brands lose the ability to optimize toward Purchase events entirely. Meta has an internal setting called **"core setup"** that is either on or off. When core setup is **on**, you typically cannot optimize toward Purchase events at all — this is the most severe level. * **Browser pixel data rejection.** Meta may restrict or ignore data sent from the browser pixel on the flagged domain. * **Reduced audience building.** With less event data flowing, custom audiences and lookalike audiences degrade over time. Meta flags specific keywords in context. For example, a term like "cramping" in the context of a magnesium supplement would be flagged because "cramping" is a medical condition. Product names, descriptions, SKUs, and URLs containing these terms all contribute to flagging. ### Can You Appeal the Flag? Yes, you can contest the flag through Meta's support channels, and some brands do win their appeal. However, winning an appeal does not guarantee a full resolution. There is a known issue where a **lingering overlay** can remain on your account even after a successful appeal — essentially a residual penalty on Meta's backend that continues to affect performance. The only way to remove this overlay is to work directly with a Meta representative, which typically costs between **$2,000 and $5,000**. Because of this uncertainty, many brands choose to implement a compliance solution (like Upstack's) rather than relying solely on the appeal process. ### The Key Fact: The Flag Is on Your Domain This is the most important thing to understand: **The Health & Wellness flag is attached to your domain, not your pixel.** Creating a new pixel and sending data from the same flagged domain will result in the new pixel also getting flagged. This is why simply swapping pixels doesn't solve the problem — and why domain aliasing is a core part of Upstack's solution. ### Next Steps Now that you understand the flag, learn how Upstack solves it: [How Upstack Data Solves Health & Wellness Restrictions →](/guides/health-wellness/how-upstack-solves-health-wellness-restrictions) Ready to get started? Follow the complete setup process: [How to Set Up a Health & Wellness Pixel for Meta →](/guides/health-wellness/setup-health-wellness-pixel-for-meta) ### Related Articles * [How Upstack Data Solves Health & Wellness Restrictions](/guides/health-wellness/how-upstack-solves-health-wellness-restrictions) * [How to Set Up a Health & Wellness Pixel for Meta](/guides/health-wellness/setup-health-wellness-pixel-for-meta) * [Health & Wellness Custom Event Mappings](/guides/facebook-ads/health-and-wellness-custom-event-mappings) # Automatic Form Capture Source: https://docs.upstackdata.com/guides/integrations/form-capture-integrations Automatic lead capture from Klaviyo, Postscript, Attentive, Omnisend, Sendlane, Recart, Listrak, Justuno, Alia, Octane AI, and Loop Subscriptions. Upstack Data detects form submissions and fires Lead events automatically. Upstack automatically detects and captures form submissions from popular email and SMS platforms. When a visitor submits a form on one of these platforms, we capture their email and/or phone number and fire appropriate tracking events. <Note> **Works on any website** — these integrations work on Shopify stores, headless storefronts, and custom websites. As long as the Upstack pixel and the third-party tool are both installed, form capture is automatic. </Note> <Tip> **No configuration required** — these integrations work automatically when both Upstack and the third-party tool are installed on your site. </Tip> ## How It Works When a visitor submits a signup form from a supported platform: 1. **Upstack detects the submission** automatically when both apps are installed 2. **Captures email and/or phone** from the form data 3. **Fires a `Lead` event** with the captured information 4. **Associates the session** with the captured identity 5. **Forwards to destinations** (Meta, TikTok, Klaviyo, etc.) *** ## Supported Platforms Upstack automatically captures signups from the following platforms: | Platform | Supported Forms | | ---------------------- | ------------------------------- | | **Klaviyo** | Popups, embedded forms, flyouts | | **Postscript** | SMS opt-in popups and forms | | **Attentive** | Two-tap creative, email capture | | **Omnisend** | Popups, signup boxes, wheels | | **Sendlane** | Popups and embedded forms | | **Recart** | Opt-in popups and tools | | **Listrak** | Email and SMS capture forms | | **Justuno** | Popups and embedded forms | | **Alia** | Signup popups | | **Octane AI** | Quiz lead capture | | **Loop Subscriptions** | Subscription management events | *** ## Events Fired When a visitor interacts with a supported form, the following events may fire: | Event | When It Fires | | ----------------------------- | ------------------------------------------------ | | `email_opt_in_form_displayed` | Popup or form becomes visible to visitor | | `Lead` | Visitor submits email and/or phone | | `email_opt_in_form_submitted` | Same as Lead — fired alongside for compatibility | | `email_opt_in_form_declined` | Visitor dismisses the form without submitting | All events include captured email/phone for identity resolution when available. *** ## Platform Details ### Recart Upstack automatically captures leads from Recart opt-in tools. **Events Captured:** * `recart:optin-tool:email-captured` * `recart:optin-tool:phone-number-captured` **Data Captured:** * Email address * Phone number * Opt-in tool ID * Opt-in tool name **Upstack Event Fired:** `Lead` *** ### Listrak Upstack automatically captures leads from Listrak forms. **Events Captured:** * `ltkEmailIdentityEvent` * `ltkPhoneIdentityEvent` **Data Captured:** * Email address * Phone number **Upstack Event Fired:** `Lead` *** ### Justuno Upstack automatically captures leads from Justuno popups and forms. **Detection Method:** Monitors form field changes for `ju_hidden_email` and `ju_hidden_sms` fields. **Data Captured:** * Email address (from `ju_hidden_email` field) * Phone number (from `ju_hidden_sms` field) **Upstack Event Fired:** `Lead` *** ### Alia Upstack automatically captures leads from Alia signup popups. **Events Captured:** * `alia:signup` **Data Captured:** * Email address * Phone number * Popup ID **Upstack Event Fired:** `Lead` *** ### Octane AI Quiz Upstack automatically tracks quiz interactions from Octane AI, including question responses, quiz completion, and lead capture. **Events Captured:** | Octane Event | Upstack Event | | ------------------------------ | --------------------------------------------------- | | `octane.quiz.questionAnswered` | `quiz_question_answered` | | `octane.quiz.completed` | `quiz_completed` + `Lead` (if email/phone captured) | | `octane.quiz.accessed` | `view_quiz_results` | **Data Captured:** * Quiz answer details * Email address (from lead capture step) * Phone number (from lead capture step) * Quiz completion status <Info> The `Lead` event fires automatically when email or phone is captured during quiz completion. </Info> *** ### Loop Subscriptions Upstack tracks subscription management events from Loop Subscriptions, enabling attribution for subscription-related cart actions. **Events Captured:** | Loop Event | Upstack Event | | ---------------------------------- | --------------------------- | | `loopAddAsOneTime` | `add_to_cart` | | `loopAddAsSubscription` | `add_to_cart` | | `loopBundleAddAsOneTime` | `add_to_cart` | | `loopBundleAddAsSubscription` | `add_to_cart` | | `loopItemAddToBundleSuccessEvent` | `add_to_cart` | | `loopByobAddToCartSuccessEvent` | `add_to_cart` | | `loopPresetAddToCartSuccessEvent` | `add_to_cart` | | `loopRemoveForOneTime` | `product_removed_from_cart` | | `loopRemoveFromSubscription` | `product_removed_from_cart` | | `loopBundleRemoveForOneTime` | `product_removed_from_cart` | | `loopBundleRemoveFromSubscription` | `product_removed_from_cart` | **Data Captured:** * Product ID * Variant ID * Product title * Price * Quantity <Note> Loop also fires additional subscription management events (pause, resume, cancel, etc.) that are tracked for analytics but not mapped to standard e-commerce events. </Note> *** ### What Destinations Receive When a form submission is detected, Upstack automatically forwards the event to your connected destinations: ```json theme={null} // Destination wire format (what Meta CAPI receives) { "event_name": "Lead", "event_time": "2026-02-18T14:39:00.000Z", "event_source_url": "https://example-store.com/", "user_data": { "em": "a1b2c3d4e5f6...hashed", "ph": "f6e5d4c3b2a1...hashed", "client_ip_address": "203.0.113.42", "client_user_agent": "Mozilla/5.0..." }, "custom_data": { "content_name": "Newsletter Signup" } } ``` <Note> You don't need to write any code for form capture integrations — Upstack detects and processes these automatically. </Note> *** ## Destination Forwarding Form submissions are automatically forwarded to your enabled destinations: | Destination | Event Received | Lead Data | | --------------------- | ----------------------- | ------------------------------ | | **Meta CAPI** | `Lead` | Email (hashed), phone (hashed) | | **TikTok Events API** | `SubmitForm` | Email (hashed), phone (hashed) | | **Google Ads** | `generate_lead` | Enhanced conversions data | | **Klaviyo** | Profile created/updated | Full PII | | **Attentive** | Subscriber created | Phone, email | <Note> Lead events are valuable for building audiences and measuring top-of-funnel performance, even if you don't optimize directly for leads. </Note> *** ## Identity Resolution When a form is submitted: 1. **Email is captured** and used as primary identifier 2. **Phone is captured** if provided (E.164 format) 3. **Session is associated** with the captured identity 4. **Cross-device matching** becomes possible for repeat visitors This means when a visitor who previously submitted a form returns to your site, Upstack can recognize them and attribute their behavior to the original touchpoint — even if they're on a different device. <Info> Identity resolution works across all form capture integrations and connects with data from [checkout identity capture](/sources/shopify-automatic-tracking#identity-capture). </Info> *** ## Troubleshooting <AccordionGroup> <Accordion title="Form submissions not tracking"> **Verify both apps are installed:** 1. Confirm Upstack is installed and active (check for events in the dashboard) 2. Confirm the third-party tool (Klaviyo, Postscript, etc.) is installed on your storefront 3. Test by submitting a form and checking the Live Event Stream in your Upstack dashboard **Check browser console:** Open browser DevTools (F12) and look for JavaScript errors that might prevent form detection. **Contact support:** If the form is from a supported platform but not tracking, contact support with the form URL for investigation. </Accordion> <Accordion title="Identity not resolving"> **Verify data format:** * Email must be a valid email format * Phone should be in E.164 format (e.g., `+14155551234`) **Check consent settings:** If the visitor hasn't granted analytics consent, identity resolution may be limited. **Allow time for resolution:** Identity stitching happens asynchronously. Check back in a few minutes if the identity doesn't appear immediately. </Accordion> <Accordion title="Events not forwarding to destinations"> **Check destination configuration:** 1. Go to **Integrations → Destinations** in your Upstack dashboard 2. Verify the destination is connected and active 3. Check that Lead events are enabled for that destination **Review event mapping:** Some destinations may map Lead events to different event names. Check the destination-specific documentation for details. </Accordion> </AccordionGroup> *** ## Related <CardGroup> <Card title="Standard Events" icon="list-check" href="/pixel/standard-events"> Full reference for Lead and other standard events. </Card> <Card title="Shopify Automatic Tracking" icon="shopify" href="/sources/shopify-automatic-tracking"> How checkout and storefront events are captured. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack connects visitor sessions across devices. </Card> <Card title="Meta CAPI" icon="meta" href="/destinations/meta-capi"> Configure Lead event forwarding to Meta. </Card> </CardGroup> # How to Connect your Google Ads Account in Upstack Data Integrations Source: https://docs.upstackdata.com/guides/integrations/how-to-connect-your-google-ads-account-in-upstack-data-integrations Connect your Google Ads account to Upstack Data so spend, impressions, and clicks pull into the dashboard for unified channel-level ROAS and attribution reporting. <Tip> **Quick Summary** * Sign in to [Upstack Data](https://app.upstackdata.com) and navigate to **[Data Integrations](https://app.upstackdata.com/pixel/integrations)**. * On the Google Ads row, click the **kebab menu** (3 dots) → **Connect**. * **Select the Google Ads account** you want to connect. </Tip> <Note> **Purpose of this setup** Connecting your Google Ads account is required to access performance data at the account, campaign, ad set, and ad levels, which powers your Upstack dashboards and attribution reporting. </Note> ## Prerequisites * An [Upstack Data](https://app.upstackdata.com) account with subscription active * A Google account with admin access to the Google Ads account you want to connect (Customer ID format: `123-456-7890`) * No active Google Ads OAuth session that conflicts with the account you want to connect (sign out of unrelated Google accounts in your browser if needed) ## Configuration Steps <Steps> <Step title="Sign in to Upstack Data"> Sign in to your [Upstack Data](https://app.upstackdata.com) account and navigate to **[Data Integrations](https://app.upstackdata.com/pixel/integrations)**. <img alt="Upstack Data dashboard with Data Integrations page open" /> </Step> <Step title="Start the Google Ads connection"> On the Data Integrations page, click the **kebab menu** (3 dots) on the Google Ads row → click **Connect**. <img alt="Google Ads row with kebab menu showing Connect option" /> **Choose the Google account** you want to connect with Upstack Data. <img alt="Google account selection screen for OAuth connection" /> Click **Continue**. <img alt="Google OAuth consent screen with Continue button" /> </Step> <Step title="Select the Google Ads account"> A popup displays all ad accounts linked to your Google account. **Select the Google Ads account** you want to connect. <img alt="Google Ads account selection popup with available ad accounts" /> </Step> <Step title="Save the configuration"> Click the **Save** button. <img alt="Save button to confirm Google Ads account connection" /> <Note> **Success!** You should see a confirmation message and the Google integration will appear as **Healthy** in your Data Integrations list. </Note> <img alt="Google Ads integration showing Healthy status in Data Integrations" /> </Step> <Step title="Verify the connection"> * On the [Data Integrations](https://app.upstackdata.com/pixel/integrations) page, confirm the Google Ads row shows status **Healthy**. * Open your Upstack dashboard reporting and confirm Google Ads spend and campaign data appear within 24 hours of connecting. </Step> </Steps> # How to boost Klaviyo abandonment revenue with Upstack Source: https://docs.upstackdata.com/guides/klaviyo-abandonment-flows/boost-klaviyo-abandonment-revenue Recover 30-40% more abandoned cart, browse, and checkout sessions by enabling Upstack's identity resolution alongside Klaviyo's native tracking. Upstack's Klaviyo identity enrichment identifies returning visitors that Klaviyo's native tracking misses, then pushes those profiles to Klaviyo in real time so your abandonment flows trigger for sessions that would otherwise be lost. Brands using this setup typically see 30–40% more profiles entering abandonment flows, directly increasing revenue from browse, cart, and checkout abandonment emails. This guide explains how the enrichment works, how to set up the "waterfall" flow architecture alongside your existing Klaviyo flows, and best practices for maximizing incremental revenue without over-messaging customers. ## The problem: Klaviyo misses returning visitors Klaviyo's abandonment flows are among the highest-revenue automated flows for DTC brands. But they only trigger when Klaviyo can identify who the visitor is, and Klaviyo's native tracking has significant blind spots. ### When Klaviyo loses identity * **Cross-device sessions.** A customer clicks your Instagram ad on their phone, browses products, then switches to their laptop. Klaviyo's browser cookie on the phone has no connection to the laptop session — that session is anonymous and no flow triggers. * **Cookie expiration.** Safari and most iOS browsers expire first-party cookies set via JavaScript within 7 days. A customer who visited 8 days ago and returns today looks like a brand-new anonymous visitor. * **In-app browser to default browser.** A customer taps a link in the Instagram or Facebook app, which opens an in-app browser with isolated cookie storage. When they later open Safari or Chrome on the same device, the session doesn't carry over. * **Ad blocker interference.** Klaviyo's client-side tracking JavaScript can be blocked by ad blockers, which roughly 30% of desktop users run. These visitors are completely invisible to Klaviyo's identification system. The cumulative effect: Klaviyo's native tracking typically identifies only 60–70% of visitors who could be matched to a known profile. The remaining 30–40% browse, add to cart, or start checkout — and leave without triggering any abandonment flow. ## How Upstack's Klaviyo identity enrichment works Upstack's [identity resolution](/pixel/identity-resolution) engine operates server-side, independent of the visitor's browser. It identifies returning visitors using signals that survive the limitations Klaviyo's client-side tracking faces: <Steps> <Step title="Server-side identity matching"> When a visitor arrives, Upstack matches server-side signals — IP address, user agent, device fingerprint, and hashed identifiers from previous sessions — against its identity graph. This works even when cookies are expired, the device is different, or the browser is blocking tracking scripts. </Step> <Step title="Session stitching"> Upstack connects fragmented sessions across devices and browsers into a single identity. The customer who browsed on their phone and returned on their laptop is recognized as the same person. </Step> <Step title="Real-time profile push to Klaviyo"> When Upstack identifies a visitor that Klaviyo doesn't recognize, it pushes the resolved profile — including email, browsing activity, and cart contents — to Klaviyo via API in real time. This enables Klaviyo flows to trigger for sessions that would otherwise be anonymous. </Step> </Steps> The result: abandonment flows fire for a significantly larger pool of identified sessions, without changing anything about your email content or flow logic. ## The "waterfall" flow architecture The recommended setup runs Upstack-triggered flows alongside your existing Klaviyo-native flows — not instead of them. Klaviyo's native tracking catches what it can, and Upstack catches what Klaviyo misses. <Tip> **Don't replace your native Klaviyo flows.** They serve different visitor pools. The goal is to add incremental coverage, not swap one set of flows for another. </Tip> ### How it works ``` Visitor arrives on your store │ ├── Klaviyo identifies them (cookie match, logged in, etc.) │ └── Native Klaviyo flow triggers → abandonment email sent │ └── Klaviyo does NOT identify them └── Upstack identifies them server-side └── Pushes profile to Klaviyo └── Upstack-triggered flow fires → abandonment email sent ``` Both paths lead to the same outcome — an abandonment email — but they catch different pools of visitors. The mutual exclusion window (covered below) prevents anyone from receiving both. ## Setup steps For complete onboarding, see [Onboarding Klaviyo in Upstack Data](/guides/klaviyo/complete-how-to-guide-for-onboarding-klaviyo-in-upstack-data) and [Setting up Upstack abandonment flows in Klaviyo](/guides/klaviyo-abandonment-flows/complete-guide-to-setting-up-upstack-abandonment-flows-in-klaviyo). The summary below covers the conceptual setup. <Steps> <Step title="Connect Klaviyo as a destination in Upstack"> Configure the Klaviyo destination so Upstack can push identified profiles and event data. Full instructions: [Klaviyo destination](/destinations/klaviyo). Once connected, Upstack begins sending identified profiles and their event data to Klaviyo when it resolves visitors that Klaviyo's native tracking missed. </Step> <Step title="Clone your Browse Abandonment flow"> 1. In Klaviyo, navigate to **Flows** and find your existing Browse Abandonment flow. 2. Clone the flow. 3. Rename the clone with the **` - Upstack Data`** suffix — for example, `Browse Abandonment - Upstack Data` — so you can distinguish it from the standard flow. Detailed walkthrough: [How to clone your standard flows in Klaviyo](/guides/klaviyo-abandonment-flows/how-to-clone-your-standard-flows-in-klaviyo). </Step> <Step title="Change the trigger to the Upstackified Klaviyo metric"> In the cloned flow, edit the trigger and change the source to the matching Upstack-emitted Klaviyo metric: * Browse Abandonment → **Viewed Product - Upstackified** * Cart Abandonment → **Added to Cart - Upstackified** * Checkout Abandonment → **Started Checkout - Upstackified** * Site Abandonment → **Active on Site - Upstackified** Upstack pushes these events to Klaviyo for sessions identified server-side rather than by Klaviyo's native tracking. </Step> <Step title="Add a 30-minute delay offset"> In the Upstack copy of the flow, add **+30 minutes** to the first wait step compared to the standard flow (for example, `1 hour` becomes `1 hour 30 minutes`). This serves two purposes: * It gives Klaviyo's native tracking time to identify the visitor on its own. If Klaviyo picks them up within those 30 minutes, the mutual exclusion filter (next step) prevents the Upstack flow from sending. * It aligns with the typical window in which visitors are most likely to return on their own, before the abandonment email is most effective. </Step> <Step title="Set mutual exclusion filters"> Add a profile filter on each flow's trigger so visitors don't receive abandonment emails from both flows: 1. On the **standard** flow, add: **Has received email 0 times in last 7 days where Flow = `[Upstack copy of the flow]`** (for example, `Abandoned Cart - Upstack Data`). 2. On the **Upstack copy** of the flow, add the reverse filter: **Has received email 0 times in last 7 days where Flow = `[Standard flow]`** (for example, `Abandoned Cart`). This 7-day mutual exclusion window prevents over-messaging. Detailed walkthrough: [Add cross-flow exclusion filters in Klaviyo](/guides/klaviyo-abandonment-flows/how-to-add-cross-flow-exclusion-filters-in-klaviyo). </Step> <Step title="Repeat for Cart, Checkout, and Site Abandonment"> Follow the same process for your Cart Abandonment, Checkout Abandonment, and Site Abandonment flows: clone with the ` - Upstack Data` suffix, change the trigger to the corresponding `*- Upstackified` event, add the 30-minute delay offset, and set mutual exclusion filters in both directions. </Step> <Step title="Match email content and step structure"> Your Upstack-triggered flows should use the same email templates, timing between steps, and step statuses (live/draft/manual) as your native flows. The visitor experience should be identical regardless of which flow they entered through — the only difference is how they were identified. </Step> <Step title="Set flows live and monitor"> 1. Set each Upstack flow to **Live** status. 2. Monitor performance over the first 7 days to verify events are flowing and emails are sending. </Step> </Steps> <Warning> **Mutual exclusion filters are required.** Without them, a customer identified by both Klaviyo and Upstack will receive duplicate abandonment emails. Always configure the 7-day exclusion in both directions. </Warning> ## Expected results Brands implementing the waterfall setup typically see: | Metric | Before enrichment | After enrichment | | ----------------------------------- | ----------------- | ---------------- | | Profiles entering abandonment flows | Baseline | +30–40% | | Browse abandonment flow revenue | Baseline | +25–35% | | Cart abandonment flow revenue | Baseline | +20–30% | | Total email-attributed revenue | Baseline | Measurable lift | The exact lift depends on your existing Klaviyo identification rate, traffic volume, and how much of your audience shops across multiple devices or returns after cookie expiration. Brands with high mobile and social media traffic see the largest improvement because those channels produce the most cross-device and in-app browser sessions. ## Best practices ### Run both flow sets in parallel — indefinitely Don't turn off your native Klaviyo flows when Upstack flows are running. They serve different visitor pools. Disabling native flows means you lose coverage for the visitors Klaviyo already identifies successfully. ### Track attribution separately Use UTM parameters to distinguish Upstack-triggered emails from native Klaviyo emails: * Native flow: `utm_source=klaviyo&utm_medium=email&utm_campaign=browse_abandon` * Upstack flow: `utm_source=klaviyo&utm_medium=email&utm_campaign=browse_abandon_upstack` This lets you measure incremental revenue contribution separately from your existing Klaviyo revenue — critical for understanding ROI. ### Monitor flow performance weekly In your first month, check these metrics weekly for each Upstack flow: * **Flow entry rate.** How many profiles are entering the Upstack flows? If it's near zero, the Klaviyo connection or trigger configuration may need attention. * **Email open and click rates.** These should be comparable to your native flows. If significantly lower, the identified profiles may be lower quality or the timing may need adjustment. * **Revenue per recipient.** The key metric. Compare this between native and Upstack flows to understand incremental value. * **Unsubscribe rate.** Monitor closely in the first two weeks. If Upstack flows show elevated unsubscribes, consider extending the delay or tightening exclusion filters. ### Adjust the delay window if needed The 30-minute delay is a starting point. If you find significant overlap between native and Upstack flows (visible as a high exclusion filter rate on the Upstack side), extend the delay to 45 or 60 minutes. If you're seeing very little overlap, you can shorten it to 15 minutes to trigger faster. ## Frequently asked questions <AccordionGroup> <Accordion title="Will Upstack replace my existing Klaviyo flows?"> No. Upstack's Klaviyo enrichment is designed to run alongside your existing flows, not replace them. Your native Klaviyo flows continue to catch visitors that Klaviyo identifies on its own. Upstack flows catch the visitors Klaviyo misses. Both run in parallel with mutual exclusion filters to prevent overlap. </Accordion> <Accordion title="How does Upstack identify visitors that Klaviyo can't?"> Upstack uses server-side identity resolution — matching visitors through a combination of server-side signals (IP, user agent, device fingerprint, hashed identifiers) against an identity graph built from previous sessions. This works independent of browser cookies, so it survives cross-device transitions, cookie expiration, and in-app browser isolation that break Klaviyo's client-side tracking. </Accordion> <Accordion title="Will this cause customers to receive duplicate emails?"> Not if you set up mutual exclusion filters correctly. The 7-day exclusion window ensures that a customer identified by both Klaviyo and Upstack only receives one abandonment email. The 30-minute delay on Upstack flows gives Klaviyo's native tracking first priority. </Accordion> <Accordion title="How long does it take to see results?"> You should see profiles entering Upstack flows within 24 hours of going live. Meaningful revenue data typically requires 7–14 days of flow activity, depending on your traffic volume and conversion rates. </Accordion> <Accordion title="Can I use Upstack identity enrichment for flows other than abandonment?"> Yes. While abandonment flows are the highest-impact use case, Upstack's identified profiles can trigger any Klaviyo flow — win-back campaigns, post-purchase sequences, or custom flows based on specific browsing behavior. The same waterfall principle applies. </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Klaviyo destination" icon="plug" href="/destinations/klaviyo"> Configure the Klaviyo destination to enable identity-enriched profile delivery. </Card> <Card title="Onboarding Klaviyo in Upstack" icon="rocket" href="/guides/klaviyo/complete-how-to-guide-for-onboarding-klaviyo-in-upstack-data"> End-to-end Klaviyo onboarding inside Upstack. </Card> <Card title="Set up Upstack abandonment flows" icon="bolt" href="/guides/klaviyo-abandonment-flows/complete-guide-to-setting-up-upstack-abandonment-flows-in-klaviyo"> Step-by-step Klaviyo flow setup with cloning, delays, and exclusions. </Card> <Card title="Clone your standard flows" icon="copy" href="/guides/klaviyo-abandonment-flows/how-to-clone-your-standard-flows-in-klaviyo"> Detailed clone procedure for each standard abandonment flow. </Card> <Card title="Cross-flow exclusion filters" icon="filter" href="/guides/klaviyo-abandonment-flows/how-to-add-cross-flow-exclusion-filters-in-klaviyo"> Configure mutual exclusion between native and Upstack flows. </Card> <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution"> How Upstack's server-side identity engine works. </Card> </CardGroup> # Complete Guide to Setting Up Upstack Abandonment Flows in Klaviyo Source: https://docs.upstackdata.com/guides/klaviyo-abandonment-flows/complete-guide-to-setting-up-upstack-abandonment-flows-in-klaviyo Set up Upstack-enhanced abandonment flows in Klaviyo — clone standard flows, swap triggers, add cross-flow exclusions, and recover 30-50% more browse, cart, and checkout abandonment revenue. <Tip> **Quick Summary** * In Klaviyo, enable account-wide UTM tracking under **Account → Settings → Other → UTM Tracking** * Locate the **standard abandonment flow** in **Flows** * **Enable UTM tracking for every Email and SMS node** inside the standard flow * **Clone** the standard flow * Rename the clone with the **` - Upstack Data`** suffix → switch trigger to the corresponding `*- Upstackified` Klaviyo metric * Open the standard and Upstack copies of the flow **side-by-side** * **Add a 30-minute delay** to the Upstack copy * Set cross-flow exclusion filters to **7 days** (or 14 days if preferred) * Adjust re-entry timing to **7 days** * Set the Upstack copy of the flow to **Live** * **Match the live/draft status of every step** in the Upstack copy to the standard flow </Tip> ## Prerequisites Before you start, you need: * The **Klaviyo destination configured in Upstack Data** ([learn how](/guides/klaviyo/how-to-configure-klaviyo-destination-in-upstack-data)) * Existing **standard abandonment flows** in your Klaviyo account (Browse, Cart, Checkout, Site) * **Admin (manager) access** to the store's Klaviyo account * Confirm the following Upstack-emitted events appear in Klaviyo under **Analytics → Metrics**: * **Viewed Product - Upstackified** * **Added to Cart - Upstackified** * **Started Checkout - Upstackified** * **Active on Site - Upstackified** ## Important Terms <Note> * **Standard flow** → the existing abandonment flow already in the brand/store's Klaviyo account. * **Upstack copy of the flow** → the cloned and modified version triggered by Upstack Data's `*- Upstackified` events. Always identifiable by the ` - Upstack Data` name suffix. </Note> ## Configuration Steps <Steps> <Step title="Sign in to Klaviyo"> Sign in to **[Klaviyo](https://www.klaviyo.com/login)**. </Step> <Step title="Enable account-wide UTM tracking"> In Klaviyo, click your **profile icon** in the bottom-left navigation and go to **Settings → Other → UTM Tracking**, then ensure UTM tracking is toggled on. Detailed walkthrough: [How to enable UTM tracking in Klaviyo](/guides/klaviyo-abandonment-flows/how-to-enable-utm-tracking-in-klaviyo). </Step> <Step title="Locate the standard abandonment flows"> * In Klaviyo, go to **Flows** in the left navigation. * Use the search bar and type **`abandon`**. * Identify the four standard abandonment flows: * **Cart Abandonment** * **Browse Abandonment** * **Site Abandonment** * **Checkout Abandonment** <img alt="Klaviyo Flows page showing search results for abandonment flows" /> </Step> <Step title="Enable UTM tracking on every Email and SMS node"> <Note> Before cloning, make sure **Enable UTM Tracking** is checked on **every Email and SMS node** inside the standard flow. The setting is copied into the clone, so enabling it now saves rework. </Note> * In **Flows**, open the standard flow. <img alt="Klaviyo standard abandonment flow open in flow editor" /> * Click an **Email** or **SMS** node. * In the right-hand details panel, check **Enable UTM Tracking**. * Click **Save**. <img alt="Email node settings panel with Enable UTM Tracking checkbox" /> <Warning> Repeat this step for **every Email and SMS node** inside the standard flow. </Warning> </Step> <Step title="Clone the standard flow"> Clone each standard flow and rename the clone with the ` - Upstack Data` suffix (for example, `Abandoned Cart - Upstack Data`). When cloning, change the trigger to the corresponding `*- Upstackified` event: * Browse Abandonment → **Viewed Product - Upstackified** * Cart Abandonment → **Added to Cart - Upstackified** * Checkout Abandonment → **Started Checkout - Upstackified** * Site Abandonment → **Active on Site - Upstackified** Detailed walkthrough: [How to clone your standard flows in Klaviyo](/guides/klaviyo-abandonment-flows/how-to-clone-your-standard-flows-in-klaviyo). </Step> <Step title="Open the standard and Upstack copies side-by-side"> To make comparing settings easier, keep: * The **standard flow** in one browser tab. * The **Upstack copy of the flow** in another tab. </Step> <Step title="Add a 30-minute delay to the Upstack copy"> In the **Upstack copy of the flow**, add **+30 minutes** to the first wait step compared to the standard flow. *Example: `1 hour` → `1 hour 30 minutes`* <img alt="Wait step configured with 1 hour 30 minutes delay in Upstack flow" /> </Step> <Step title="Add cross-flow exclusion filters"> <Note> **Purpose:** Prevent someone from entering both the standard and Upstack copies within a 7-day window, which would result in duplicate emails. </Note> Add a filter on each flow's trigger: * On the **standard flow**: **Has received email 0 times in last 7 days where Flow = `[Upstack copy of the flow]`** * On the **Upstack copy of the flow**: **Has received email 0 times in last 7 days where Flow = `[Standard flow]`** Detailed walkthrough: [How to add cross-flow exclusion filters in Klaviyo](/guides/klaviyo-abandonment-flows/how-to-add-cross-flow-exclusion-filters-in-klaviyo). </Step> <Step title="Turn on the Upstack copy of the flow"> * Open the **Upstack copy of the flow**. * In the top-right of the page, click the **Review and turn on** button. <img alt="Review and turn on button in Klaviyo flow editor" /> * In the right-side panel that appears, set **Flow status** to **Live**. * Select **Update status now**. * Click **Save**. <img alt="Flow status panel with Live option selected and Save button" /> </Step> <Step title="Match step statuses to the standard flow"> * In the **standard flow**, note which steps are **Live** vs **Draft / Manual**. * In the **Upstack copy of the flow**, set each corresponding step to the **same status**. * Double-check that every step's status matches the standard flow before continuing. </Step> <Step title="Verify the setup"> * Confirm the Upstack copy of the flow is **Live** and that step statuses mirror the standard flow exactly. * In Klaviyo, open **Analytics → Metrics** and confirm the corresponding `*- Upstackified` event is recording activity (within minutes of live traffic). * In **Flows**, open the Upstack copy and check the **Analytics** tab over the first 24–48 hours to confirm profiles are entering the flow. * Spot-check a recipient profile to confirm they did **not** also receive the standard flow's email within the same 7-day window. </Step> </Steps> ## Best Practices * Always confirm timing and messaging changes between the standard flow and the Upstack copy. * Test triggers to ensure the `*- Upstackified` events are firing correctly. * Monitor reporting weekly after launch to assess performance. <Warning> **Repeat every step** for **each** standard abandonment flow: Cart, Browse, Site, and Checkout Abandonment. </Warning> <Note> **Need help or found an issue?** If you encounter any issues or have questions while following this guide, you may reach out to us at **[support@upstackdata.com](mailto:support@upstackdata.com)** </Note> # How to Add Cross-Flow Exclusion Filters in Klaviyo Source: https://docs.upstackdata.com/guides/klaviyo-abandonment-flows/how-to-add-cross-flow-exclusion-filters-in-klaviyo Add cross-flow exclusion filters in Klaviyo so the same shopper can't enter multiple Upstack abandonment flows within overlapping windows — preventing over-emailing and duplicate sends. ## Why this Step Matters <Note> The purpose of cross-flow exclusion filters is to **prevent someone from entering both the standard flow and the Upstack copy of the flow within a set timeframe.** This avoids overlapping or duplicate messages, ensuring a smoother customer experience, reducing message fatigue, and keeping your reporting data clean. </Note> ## Prerequisites Before you start, you need: * The **Klaviyo destination configured in Upstack Data** * **Existing standard abandonment flows** in your Klaviyo account (Browse, Cart, Checkout, Site) * The **Upstack copy of each abandonment flow** already cloned and renamed with the ` - Upstack Data` suffix ([learn how](/guides/klaviyo-abandonment-flows/how-to-clone-your-standard-flows-in-klaviyo)) * Admin (manager) access to the store's Klaviyo account <Note> **Key terms used below:** * **Standard flow** → the original abandonment flow in your Klaviyo account (for example, `Abandoned Cart`). * **Upstack copy of the flow** → the cloned version triggered by Upstack Data's `*- Upstackified` events, named with the ` - Upstack Data` suffix (for example, `Abandoned Cart - Upstack Data`). </Note> ## Part 1: Add the exclusion filter to the standard flow * Open the **standard flow** (for example, `Abandoned Cart`) in Klaviyo. * Click the **Trigger** card at the top of the flow. <img alt="Klaviyo flow editor with Trigger card selected at top of flow" /> * Go to **Profile filters** and click **Edit**. * Scroll to the bottom of the existing profile filters and click **+ AND**. <img alt="Profile filters section with Edit button and AND condition option" /> * Select the condition: **What someone has done (or not done)**. * Choose **Person has** → **Received Email**. * Set the count and timeframe: **zero times** → **in the last 7 days** *(or 14 days if preferred)*. * Click **Where** and add: **Flow** **equals** the **Upstack copy of this flow**. For example: `Flow equals Abandoned Cart - Upstack Data`. Read as: **Has received email 0 times in last 7 days where Flow = `Abandoned Cart - Upstack Data`**. * Click **Save**. <img alt="Cross-flow exclusion filter configured with zero emails in last 7 days" /> ## Part 2: Add the reverse exclusion filter to the Upstack copy of the flow * Open the **Upstack copy of the flow** (for example, `Abandoned Cart - Upstack Data`) in Klaviyo. * Click the **Trigger** card at the top of the flow. <img alt="Upstack copy of flow with Trigger card selected for editing" /> * Go to **Profile filters** and click **Edit**. * Scroll to the bottom of the existing profile filters and click **+ AND**. <img alt="Profile filters Edit panel with AND condition button" /> * Select the condition: **What someone has done (or not done)**. * Choose **Person has** → **Received Email**. * Set the count and timeframe: **zero times** → **in the last 7 days** *(or 14 days if preferred)*. * Click **Where** and add: **Flow** **equals** the **standard flow**. For example: `Flow equals Abandoned Cart`. Read as: **Has received email 0 times in last 7 days where Flow = `Abandoned Cart`**. * Click **Save**. <img alt="Reverse exclusion filter referencing the standard flow name" /> ## Part 3: Verify both filters are in place * On the **standard flow** trigger, confirm the profile filter references the **Upstack copy** name (for example, `Abandoned Cart - Upstack Data`). * On the **Upstack copy of the flow** trigger, confirm the profile filter references the **standard flow** name (for example, `Abandoned Cart`). * Spot-check a recipient profile after going live: confirm they only receive an email from one of the two flows within the 7-day window. <Note> **Done 🎉** Repeat both Part 1 and Part 2 for **each** abandonment flow pair: Cart, Browse, Site, and Checkout. For the full setup walkthrough, see [How to set up your Upstack abandonment flows in Klaviyo](/guides/klaviyo-abandonment-flows/complete-guide-to-setting-up-upstack-abandonment-flows-in-klaviyo). </Note> <Note> **Need help or found an issue?** If you encounter any issues or have questions while following this guide, reach out to us at **[support@upstackdata.com](mailto:support@upstackdata.com)**. </Note> # How to Clone your Standard Flows in Klaviyo Source: https://docs.upstackdata.com/guides/klaviyo-abandonment-flows/how-to-clone-your-standard-flows-in-klaviyo Clone your existing Klaviyo standard abandonment flows so the Upstack-enhanced versions inherit your branding, copy, and timing — preserving your design while triggering on Upstack events. ## Prerequisites Before you start, you need: * The **Klaviyo destination configured in Upstack Data** * **Existing standard abandonment flows** in your Klaviyo account (Browse, Cart, Checkout, Site) * **Admin (manager) access** to the store's Klaviyo account * The following Upstack-emitted events present in Klaviyo (under **Analytics → Metrics**): * **Viewed Product - Upstackified** * **Added to Cart - Upstackified** * **Started Checkout - Upstackified** * **Active on Site - Upstackified** <Note> **Key terms:** * **Standard flow** → the existing abandonment flow in the brand/store's Klaviyo account (for example, `Abandoned Cart`). * **Upstack copy of the flow** → the cloned and modified version triggered by Upstack Data's `*- Upstackified` events. Always identifiable by the ` - Upstack Data` name suffix (for example, `Abandoned Cart - Upstack Data`). </Note> ## Trigger mapping Use this mapping when changing the trigger on the cloned flow: | Standard flow | Upstack trigger event | | -------------------- | ----------------------------------- | | Browse Abandonment | **Viewed Product - Upstackified** | | Cart Abandonment | **Added to Cart - Upstackified** | | Checkout Abandonment | **Started Checkout - Upstackified** | | Site Abandonment | **Active on Site - Upstackified** | ## Configuration Steps <Steps> <Step title="Sign in to Klaviyo"> Sign in to **[Klaviyo](https://www.klaviyo.com/login)**. </Step> <Step title="Clone the standard flow"> * In the left navigation, go to **Flows** and open the **standard flow** you want to clone. * In the far-right column of the flow's row, click the **vertical three-dot (kebab) menu** and select **Clone**. <img alt="Klaviyo flows list with kebab menu showing Clone option for a flow" /> * A right-side panel will slide in, prompting you to specify the **new flow name** for the clone. * Name the clone the same as the original, plus the **` - Upstack Data`** suffix. For example: `ABC | Pre | Added to Cart | Flow | Abandoned Cart` becomes `ABC | Pre | Added to Cart | Flow | Abandoned Cart - Upstack Data`. * Click **Continue**. <img alt="Clone flow panel with name field showing Upstack Data suffix" /> * Change the **Trigger** to the matching `*- Upstackified` Klaviyo metric using the **Trigger mapping** table above (for example, **Viewed Product - Upstackified** for Browse Abandonment). * Save by clicking **Clone Flow**. <img alt="Clone Flow button with Upstackified trigger event selected" /> * A confirmation modal will let you know you'll receive a notification once the cloned flow is ready to edit. Click **Got it** to proceed. <img alt="Confirmation modal indicating cloned flow will be ready to edit" /> </Step> <Step title="Verify the clone"> * Once Klaviyo finishes cloning, open the new flow and confirm: * The flow name ends with **` - Upstack Data`**. * The **Trigger** is set to the correct `*- Upstackified` event from the trigger mapping table above. * The flow is in **Draft** status (you'll set it Live later in the [setup guide](/guides/klaviyo-abandonment-flows/complete-guide-to-setting-up-upstack-abandonment-flows-in-klaviyo)). </Step> </Steps> <Note> **Done 🎉** Repeat these steps for **each** standard abandonment flow: **Cart, Browse, Site, and Checkout Abandonment**. For the full setup walkthrough, see [How to set up your Upstack abandonment flows in Klaviyo](/guides/klaviyo-abandonment-flows/complete-guide-to-setting-up-upstack-abandonment-flows-in-klaviyo). </Note> <Note> **Need help or found an issue?** If you encounter any issues or have questions while following this guide, reach out to us at **[support@upstackdata.com](mailto:support@upstackdata.com)**. </Note> # How to Enable UTM Tracking in Klaviyo Source: https://docs.upstackdata.com/guides/klaviyo-abandonment-flows/how-to-enable-utm-tracking-in-klaviyo Enable UTM tracking in Klaviyo so emails sent from Upstack-enhanced abandonment flows attribute their conversions correctly back to the email channel in Upstack Analytics. ## Prerequisites Before you start, you need: * The **Klaviyo destination configured in Upstack Data** * **Admin (manager) access** to the store's Klaviyo account * The following Upstack-emitted events present in Klaviyo (under **Analytics → Metrics**): * **Viewed Product - Upstackified** * **Added to Cart - Upstackified** * **Started Checkout - Upstackified** * **Active on Site - Upstackified** ## Configuration Steps <Steps> <Step title="Sign in to Klaviyo"> Sign in to **[Klaviyo](https://www.klaviyo.com/login)**. </Step> <Step title="Open the UTM Tracking settings"> * In Klaviyo, click your **profile icon / account name** in the bottom-left navigation. * Go to **Settings → Other → UTM Tracking**. <img alt="Klaviyo Settings menu with UTM Tracking option under Other section" /> </Step> <Step title="Enable account-wide UTM tracking"> * At the bottom of the UTM parameter list, toggle on **Automatically add UTM parameters to links**. * Click the **Add UTM parameter** button. * Set **UTM Parameter Name** to **`up_kprofile_id`**, then set both the **Campaign value** and the **Flow value** to **Klaviyo profile id**. * Confirm the UTM parameter named **Campaign (`utm_campaign`)** is enabled, with **Campaign value** set to **Campaign name** and **Flow value** set to **Flow name**. * Confirm the UTM parameter named **Id (`utm_id`)** is enabled, with **Campaign value** set to **Campaign name (campaign id)** and **Flow value** set to **Flow message name (flow message id)**. * Click **Save** in the top-right of the page. <img alt="Klaviyo UTM Tracking settings with up_kprofile_id parameter configured" /> </Step> <Step title="Verify UTM tracking is enabled"> * Reload the **Settings → Other → UTM Tracking** page and confirm: * **Automatically add UTM parameters to links** is toggled **on**. * The **`up_kprofile_id`**, **`utm_campaign`**, and **`utm_id`** parameters are all enabled with the values configured above. * Send yourself a test email from any flow and confirm the links in the email contain `up_kprofile_id`, `utm_campaign`, and `utm_id` query parameters. </Step> </Steps> <Note> **Done 🎉** Continue with the full setup walkthrough: [How to set up your Upstack abandonment flows in Klaviyo](/guides/klaviyo-abandonment-flows/complete-guide-to-setting-up-upstack-abandonment-flows-in-klaviyo). </Note> <Note> **Need help or found an issue?** If you encounter any issues or have questions while following this guide, reach out to us at **[support@upstackdata.com](mailto:support@upstackdata.com)**. </Note> # Complete How-To Guide for Onboarding Klaviyo in Upstack Data Source: https://docs.upstackdata.com/guides/klaviyo/complete-how-to-guide-for-onboarding-klaviyo-in-upstack-data Onboard Klaviyo in Upstack Data — generate the Private API key, configure the destination, and clone abandonment flows to lift triggered abandoned cart, checkout, and browse revenue 40%+. <Info> **New to Upstack?** Follow the [getting started guide](/get-started/install-on-shopify) for a streamlined onboarding walkthrough. </Info> <Tip> **Quick Summary** Complete Klaviyo integration requires three essential steps plus a critical follow-up for maximum value from your setup. * Generate a **Klaviyo Private API key** with Full Access in Klaviyo. * Connect Klaviyo in the **[Upstack dashboard](https://app.upstackdata.com/pixel/event-destinations)** using the Klaviyo Private API key. * Contact **[support@upstackdata.com](mailto:support@upstackdata.com)** to activate Upstack abandonment flows. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to a **Klaviyo** account * The ability to generate a **Klaviyo Private API key** with Full Access ([learn how to generate one](/guides/klaviyo/how-to-generate-klaviyo-api-key-for-upstack-data)) ## Part 1: Generate a Klaviyo Private API key * Sign in to **[Klaviyo](https://www.klaviyo.com/login)**. * Click your **profile icon** in the bottom-left navigation. * Go to **Settings → Account → API Keys**. * Click the **Create Private API Key** button. * Name the new key **`UpstackData`**. * Under *Select Access Level*, choose **Full Access Key**. * Click **Create**. * Copy and save the Klaviyo Private API key immediately. It starts with `pk_` followed by alphanumeric characters (for example, `pk_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678`). <img alt="Klaviyo API Keys page with Create Private API Key button" /> **`Important:`** `This key will only be shown once.` Need a more detailed walkthrough? See [How to generate a Klaviyo Private API key for Upstack Data](/guides/klaviyo/how-to-generate-klaviyo-api-key-for-upstack-data). ## Part 2: Configure the Klaviyo destination in the Upstack dashboard * Sign in to **[Upstack Data](https://app.upstackdata.com)**. * In the Upstack dashboard, navigate to **[Pixel → Event Destinations](https://app.upstackdata.com/pixel/event-destinations)**. * Click **+ New Destination** in the top-right of the page. * In the *Select a Destination* popup, choose **Klaviyo** and click **Next**. * Paste your **Klaviyo Private API key** into the *Private API Key* field. * Click **Create Configuration**. <img alt="Upstack Event Destinations page with Klaviyo configuration form" /> **`Success!`** `Klaviyo is now connected to Upstack Data.` Need a more detailed walkthrough? See [How to configure the Klaviyo destination in Upstack Data](/guides/klaviyo/how-to-configure-klaviyo-destination-in-upstack-data). ## Part 3: Verify the connection * In the Upstack dashboard, go to **Pixel → Event Destinations**. * Confirm the **Klaviyo** destination is listed with a **Healthy** status. * In Klaviyo, go to **Analytics → Metrics** and confirm Upstack-emitted events (for example, **Viewed Product - Upstackified**, **Added to Cart - Upstackified**, **Started Checkout - Upstackified**, **Active on Site - Upstackified**) begin appearing within a few minutes of live traffic. <Warning> After completing the Klaviyo setup, contact **[support@upstackdata.com](mailto:support@upstackdata.com)** to request your Upstack abandonment flows be set up. These additive flows improve your abandonment capture by **up to 40% or more**. </Warning> # How to Configure Klaviyo Destination in Upstack Data Source: https://docs.upstackdata.com/guides/klaviyo/how-to-configure-klaviyo-destination-in-upstack-data Configure the Klaviyo destination in Upstack Data with your Klaviyo Private API key and verify identity-resolved events sync to power abandonment flow recovery. <Tip> **Quick Summary** * In the **[Upstack dashboard](https://app.upstackdata.com/pixel/event-destinations)**, go to **Pixel → Event Destinations** and click **+ New Destination** * Select **Klaviyo** from the destination options * Enter your **Klaviyo Private API key** * Click **Create Configuration** and verify the destination is **Healthy** </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to a **Klaviyo** account * A **Klaviyo Private API key** with Full Access ([learn how to generate one](/guides/klaviyo/how-to-generate-klaviyo-api-key-for-upstack-data)) ## Configuration Steps <Steps> <Step title="Sign in to Upstack Data"> Sign in to **[Upstack Data](https://app.upstackdata.com)**. </Step> <Step title="Open the Event Destinations page"> * In the Upstack dashboard, navigate to **Pixel → Event Destinations** (or open it directly: **[Event Destinations](https://app.upstackdata.com/pixel/event-destinations)**). * Click **+ New Destination** in the top-right of the page. <img alt="Add New Destination" /> * In the *Select a Destination* popup, click **Klaviyo**. * Click **Next**. <img alt="Select Klaviyo as Destination" /> </Step> <Step title="Enter your Klaviyo Private API key"> Paste your **Klaviyo Private API key** into the *Private API Key* field. The key starts with `pk_` followed by alphanumeric characters (for example, `pk_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678`). <img alt="Klaviyo destination configuration form with Private API Key field" /> `Important: Ensure there are no extra spaces before or after the key.` <Note> Need to generate the key first? See [How to generate a Klaviyo Private API key for Upstack Data](/guides/klaviyo/how-to-generate-klaviyo-api-key-for-upstack-data). </Note> </Step> <Step title="Create the configuration"> Click the **Create Configuration** button to save the setup. <img alt="Create Configuration button to save Klaviyo destination setup" /> <Note> **Success! 🎉** You should see a confirmation message and the Klaviyo destination will appear as **Healthy** in your destinations list. </Note> <img alt="Klaviyo destination showing Healthy status in destinations list" /> </Step> <Step title="Verify events are flowing to Klaviyo"> * In the Upstack dashboard, return to **Pixel → Event Destinations** and confirm the **Klaviyo** row shows a **Healthy** status. * In Klaviyo, navigate to **Analytics → Metrics** and confirm Upstack-emitted events (for example, **Viewed Product - Upstackified**, **Added to Cart - Upstackified**, **Started Checkout - Upstackified**, **Active on Site - Upstackified**) appear within a few minutes of live traffic on your store. </Step> </Steps> <Warning> After completing setup, contact **[support@upstackdata.com](mailto:support@upstackdata.com)** to request your Upstack abandonment flows be set up. These additive flows improve your abandonment capture by **up to 40% or more**. </Warning> # How to Generate Klaviyo API Key for Upstack Data Source: https://docs.upstackdata.com/guides/klaviyo/how-to-generate-klaviyo-api-key-for-upstack-data Generate a Klaviyo Private API key with Full Access permissions to authenticate the Upstack Data Klaviyo destination and enable identity-enriched event sync. <Tip> **Quick Summary** * In Klaviyo, navigate to **Settings → Account → [API Keys](https://www.klaviyo.com/create-private-api-key)** * Click **Create Private API Key** * Name it **`UpstackData`** and select **Full Access Key** * **Copy and save** the key securely (it starts with `pk_`) </Tip> ## Prerequisites Before you start, you need: * Admin access to a **Klaviyo** account (required to create Private API keys) * Permission to grant **Full Access** to API keys ## Steps to Generate the Klaviyo Private API key <Steps> <Step title="Sign in to Klaviyo"> Sign in to **[Klaviyo](https://www.klaviyo.com/login)**. </Step> <Step title="Open the API Keys settings"> * Click your **profile icon** in the bottom-left navigation. * Go to **Settings → Account → [API Keys](https://www.klaviyo.com/create-private-api-key)**. <img alt="Klaviyo profile icon and Settings menu in bottom-left navigation" /> `Settings menu` <img alt="Klaviyo Account settings with API Keys option" /> `API keys menu` </Step> <Step title="Create a new Private API key"> Click the **Create Private API Key** button. <img alt="Create Private API Key button in Klaviyo" /> </Step> <Step title="Configure key name and access level"> * Name your Klaviyo Private API key **`UpstackData`**. * Under *Select Access Level*, choose **Full Access Key**. * Click the **Create** button. <img alt="API key creation form with name field and Full Access Key selected" /> <Warning> Full Access is required for all Upstack Data features to work properly. </Warning> </Step> <Step title="Copy and save your Klaviyo Private API key"> Copy the generated key immediately. It starts with `pk_` followed by alphanumeric characters (for example, `pk_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678`). <img alt="Generated Klaviyo Private API key with copy button" /> <Warning> This key will only be shown once. Store it securely — you will need it to configure the Klaviyo destination in the Upstack dashboard. </Warning> </Step> <Step title="Verify the key was created"> * Return to **Settings → Account → API Keys** in Klaviyo. * Confirm the new **`UpstackData`** key appears in the list with **Full Access** permissions. * Continue to [How to configure the Klaviyo destination in Upstack Data](/guides/klaviyo/how-to-configure-klaviyo-destination-in-upstack-data) to paste the key into the Upstack dashboard. </Step> </Steps> # Klaviyo integration and abandonment flows Source: https://docs.upstackdata.com/guides/klaviyo/klaviyo-integration-and-abandonment-flows How the Upstack Klaviyo integration works, why Klaviyo misses some visitors, how cloned abandonment flows recover more revenue, and how to troubleshoot them. ## How does the Klaviyo integration work? Upstack connects to Klaviyo through a private API key — create a full-access key in Klaviyo and add it in the Upstack dashboard. That's the entire connection step. Once connected, Upstack: 1. Uses Klaviyo profile data to enrich events sent to Meta, improving Event Match Quality scores. 2. Re-identifies returning visitors that Klaviyo no longer recognizes, putting them back through your abandonment flows. ## Why does Klaviyo miss some visitors? When someone opts in (for example, enters their email for a discount), Klaviyo records their identity in that browser session. If they return later in a different browser — say they clicked an ad in the Instagram app and come back in Safari — Klaviyo treats them as unknown, and their activity won't trigger an abandonment flow. Upstack's identity resolution reconnects that visitor to their known profile and sends the information back to Klaviyo, which then triggers the flow as expected. ## How do the cloned abandonment flows work? The Upstack team clones your existing flows and sets them up in a waterfall: 1. Your standard Klaviyo flow fires first (unchanged). 2. After a 30-minute delay, the Upstack flow fires. 3. Anyone who received one flow is excluded from the other. No duplicate emails. The cloned flows use the same content, design, and steps as your originals — the only differences are the trigger event, the delay, and the exclusion filters. ## Which flows are cloned? Up to four, depending on your setup: browse abandonment, cart abandonment, site abandonment, and checkout abandonment. After setup, you'll have two versions of each in Klaviyo — the standard one and the Upstack Data one. ## What improvement should I expect? Most stores see a 30–40% increase in abandonment flow volume — meaning that many more people are identified and entering flows. This translates directly to additional recovered revenue from emails that wouldn't have been sent otherwise. The improvement compounds over time as Upstack builds a larger visitor profile. ## Who sets up the flows? The Upstack team handles flow cloning for you. During onboarding, you invite the team to your Klaviyo account. Setup is typically completed within 48 to 72 hours. Your existing flows remain unchanged. ## Troubleshooting * **Flows not sending emails** — Verify both the standard and Upstack flows are set to Live in Klaviyo, and that each email step matches the status of the original. * **Low volume on Upstack flows** — Expected in the first few days. If volume stays low after two weeks, confirm no other tool (for example, Triple Whale) is running conflicting flows. If you run into issues, reach out to [support@upstackdata.com](mailto:support@upstackdata.com). * **Duplicate emails** — Check that exclusion windows are set correctly (recommended: 7 days) and that both flows reference each other in their filters. # Complete How-To Guide for Onboarding LinkedIn Ads in Upstack Data Source: https://docs.upstackdata.com/guides/linkedin-ads/complete-how-to-guide-for-onboarding-linkedin-in-upstack-data Onboard LinkedIn Ads in Upstack Data — locate your Partner ID, create conversion rules, generate the Conversions API token, configure the destination, and enable click ID tracking. <Info> **New to Upstack?** Follow the [getting started guide](/get-started/install-on-shopify) for a streamlined onboarding walkthrough. </Info> <Tip> * Configure the **LinkedIn destination** in Upstack Data with your **Partner ID**, **API Access Token**, and **Conversion Rule IDs**. * Create **Conversion Rules** in LinkedIn Campaign Manager for each event type you want to track. * Enable **Enhanced Conversion Tracking** to capture `li_fat_id` click IDs. * Verify events appear in **LinkedIn Campaign Manager → Data → Signal Diagnostics**. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to a **LinkedIn Ads** account with the **Campaign Manager** role * The **LinkedIn Insight Tag** installed on your storefront (Upstack will fire it alongside server-side events) * Shopify owner/staff access (if applicable) <Steps> <Step title="Find your LinkedIn Partner ID"> Your **Partner ID** identifies your LinkedIn ad account and Insight Tag installation. You'll need this to configure the Upstack destination. Help guide: [How to find your LinkedIn Partner ID →](/guides/linkedin-ads/how-to-find-linkedin-partner-id) </Step> <Step title="Create Conversion Rules in Campaign Manager"> Unlike Meta or TikTok, LinkedIn requires you to create **Conversion Rules** for each event type you want to track. Each rule gets a unique **Conversion Rule ID** that Upstack uses to send events to the correct conversion action. <Warning> You must create separate Conversion Rules for **Purchase**, **Add to Cart**, **Lead**, and any other events you want to track. Without a Conversion Rule ID, Upstack cannot send events for that action. </Warning> Help guide: [How to create LinkedIn Conversion Rules →](/guides/linkedin-ads/how-to-create-linkedin-conversion-rules) </Step> <Step title="Generate a Conversions API access token"> Upstack needs a **Direct Access Token** with the **Manage conversions** permission to send events to LinkedIn's Conversions API. You generate it directly in Campaign Manager — no LinkedIn Developer app required. Help guide: [How to generate a LinkedIn Conversions API token →](/guides/linkedin-ads/how-to-generate-linkedin-conversion-api-token) </Step> <Step title="Configure the LinkedIn destination in Upstack Data"> In the Upstack dashboard, navigate to **Event Destinations** and add a **LinkedIn Ads** destination using your **Partner ID**, **API Access Token**, and **Conversion Rule IDs**. Help guide: [How to configure the LinkedIn destination in Upstack Data →](/guides/linkedin-ads/how-to-configure-linkedin-destination-in-upstack-data) </Step> <Step title="Enable LinkedIn click ID tracking"> <Note> **Optional but recommended.** Enabling enhanced conversion tracking allows LinkedIn to capture the `li_fat_id` click ID, which significantly improves match rates. </Note> Help guide: [How to enable LinkedIn click ID tracking →](/guides/linkedin-ads/how-to-enable-linkedin-click-id-tracking) </Step> <Step title="Verify the full setup is healthy"> Confirm each piece of the setup is working: * In the Upstack dashboard, **Event Destinations** shows your LinkedIn destination as **Healthy** (green). * In [LinkedIn Campaign Manager](https://www.linkedin.com/campaignmanager/) → **Data** → **Signals Manager** → **Signal Diagnostics**, events appear with status "Received." * The **Match Quality** column shows match rates — these will improve over the next 1-2 weeks. If anything is unhealthy, check the corresponding help guide above for troubleshooting steps. </Step> </Steps> ## What to expect after setup ### Match quality timeline * **Match quality** scores start to improve in 2-3 days and normalize over 1-2 weeks. * You can typically expect a 20-40% increase in tracked conversions vs. the browser Insight Tag alone, since CAPI captures conversions lost to ad blockers and iOS restrictions. * The **Purchase** match quality sees the biggest improvement because checkout-time events carry the strongest match keys (hashed email, LinkedIn click ID). ### Reporting differences * Your **LinkedIn Campaign Manager ROAS** will likely **increase** after a few days as LinkedIn attributes more conversions to ads. Many brands discover their LinkedIn campaigns were performing better than the browser-only data suggested. * Conversion volume may temporarily fluctuate during the first 48 hours as LinkedIn's deduplication logic adjusts to receiving both Insight Tag and CAPI events. ### B2B-specific benefits LinkedIn's Conversions API supports **B2B match keys** that other platforms don't: * **Company name** — match events to LinkedIn Company Pages * **Job title** — improve targeting for professional audiences * **First-party click ID (`li_fat_id`)** — the strongest match signal for LinkedIn <Note> **Need help?** If you encounter any issues during setup or don't see expected match quality improvements after 2 weeks, contact our [support team](/support) with your **LinkedIn Partner ID** and we'll help diagnose the problem. </Note> # How to Configure LinkedIn Destination in Upstack Data Source: https://docs.upstackdata.com/guides/linkedin-ads/how-to-configure-linkedin-destination-in-upstack-data Configure the LinkedIn Ads destination in Upstack Data — enter your Partner ID, API Access Token, and Conversion Rule IDs to enable server-side conversion forwarding. <Tip> * Navigate to **Event Destinations** in your Upstack dashboard. * Add a **LinkedIn Ads** destination with your **Partner ID**, **API Access Token**, and **Conversion Rule IDs**. * Enable **Enhanced Matching** to send hashed user data for improved attribution. * Verify the destination shows **Healthy** status after saving. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Your **LinkedIn Partner ID** — see [How to find your LinkedIn Partner ID](/guides/linkedin-ads/how-to-find-linkedin-partner-id) * A **Conversions API access token** — see [How to generate a LinkedIn Conversions API token](/guides/linkedin-ads/how-to-generate-linkedin-conversion-api-token) * **Conversion Rule IDs** for each event type — see [How to create LinkedIn Conversion Rules](/guides/linkedin-ads/how-to-create-linkedin-conversion-rules) ## Steps to configure the LinkedIn destination <Steps> <Step title="Open Event Destinations in Upstack"> Sign in to your [Upstack Data dashboard](https://app.upstackdata.com) and navigate to **Event Destinations** from the left sidebar. </Step> <Step title="Add a new destination"> Click **+ Add Destination** and select **LinkedIn Ads** from the destination catalog. </Step> <Step title="Enter your Partner ID"> Paste your **LinkedIn Partner ID** into the **Partner ID** field. <Tip> Your Partner ID is a numeric value (e.g., `123456`) found in LinkedIn Campaign Manager → Data → Signals Manager. Ensure there are no extra spaces. </Tip> </Step> <Step title="Enable the Conversions API"> Toggle **Enable LinkedIn Conversions API** to send server-side events in addition to the Insight Tag. <Note> When enabled, Upstack sends events directly to LinkedIn's Conversions API, bypassing browser restrictions. We recommend keeping this enabled for maximum match quality. </Note> </Step> <Step title="Enter your API Access Token"> Paste your **Conversions API access token** into the **API Access Token** field. This is the **Direct Access Token** you generate in Campaign Manager with the **Manage conversions** permission. If you haven't generated one yet, see [How to generate a LinkedIn Conversions API token](/guides/linkedin-ads/how-to-generate-linkedin-conversion-api-token). </Step> <Step title="Map Conversion Rule IDs"> Enter the **Conversion Rule ID** for each event type you want to track: | Field | Description | | ---------------------------------- | --------------------------------------------------- | | **Purchase Conversion Rule ID** | The numeric ID for your Purchase conversion rule | | **Add to Cart Conversion Rule ID** | The numeric ID for your Add to Cart conversion rule | | **Lead Conversion Rule ID** | The numeric ID for your Lead conversion rule | | **Sign Up Conversion Rule ID** | The numeric ID for your Sign Up conversion rule | <Warning> Each Conversion Rule ID must be a numeric value (e.g., `12345678`). If you haven't created conversion rules yet, see [How to create LinkedIn Conversion Rules](/guides/linkedin-ads/how-to-create-linkedin-conversion-rules). </Warning> **You don't need to fill in all fields.** Only configure the events you want to track. Upstack will skip events that don't have a corresponding Conversion Rule ID. </Step> <Step title="Enable Enhanced Matching (recommended)"> Toggle **Enable Enhanced Matching** to send hashed user data (email) to LinkedIn for improved ad attribution. <Note> Enhanced Matching sends SHA-256 hashed email addresses to LinkedIn. The data is hashed before it leaves your Upstack account. </Note> </Step> <Step title="Save the configuration"> Click **Create Configuration** (or **Save Changes** if editing) to save the destination. </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, navigate to **Event Destinations**. Your LinkedIn destination should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**, double-check: * Partner ID is correct (numeric, no spaces) * API Access Token is valid and hasn't expired * Conversion Rule IDs are correct (numeric values only) * Your LinkedIn user has the required permissions </Step> </Steps> ## Configuration fields reference | Field | Required | Description | | ----------------------------------- | ----------- | ----------------------------------------------- | | **Partner ID** | Yes | Your LinkedIn Partner ID from Campaign Manager | | **Enable LinkedIn Conversions API** | No | Send events server-side via the Conversions API | | **API Access Token** | Conditional | Required when Conversions API is enabled | | **Purchase Conversion Rule ID** | No | Conversion Rule ID for Purchase events | | **Add to Cart Conversion Rule ID** | No | Conversion Rule ID for Add to Cart events | | **Lead Conversion Rule ID** | No | Conversion Rule ID for Lead events | | **Sign Up Conversion Rule ID** | No | Conversion Rule ID for Sign Up events | | **Enable Enhanced Matching** | No | Send hashed email for improved attribution | <Note> **Next step:** [How to enable LinkedIn click ID tracking](/guides/linkedin-ads/how-to-enable-linkedin-click-id-tracking) </Note> # How to Create LinkedIn Conversion Rules Source: https://docs.upstackdata.com/guides/linkedin-ads/how-to-create-linkedin-conversion-rules Create LinkedIn Conversion Rules in Campaign Manager and find each Conversion Rule ID — required so Upstack Data can send server-side events to the correct conversion action. <Tip> * Sign in to [LinkedIn Campaign Manager](https://www.linkedin.com/campaignmanager/) and open **Data** → **Signals Manager** → **Conversions**. * Click **Create conversion** and choose the **Conversions API** data source. * Create one conversion rule per event type (Purchase, Add to Cart, Lead, Sign Up). * Copy each numeric **Conversion Rule ID** and map it in your Upstack LinkedIn destination. </Tip> <Warning> Unlike Meta or TikTok, LinkedIn requires a separate **Conversion Rule** for each event type you want to track. Without a Conversion Rule ID for an event, Upstack cannot forward that event — it will be skipped. </Warning> <Note> **What is a Conversion Rule ID?** A **Conversion Rule** defines a specific conversion action (e.g., a Purchase) and how it should be attributed to your campaigns. Each rule has a unique numeric **Conversion Rule ID**. LinkedIn references rules internally with the URN format `urn:lla:llaPartnerConversion:{id}`; Upstack builds this URN for you — you only need the numeric ID. </Note> ## Prerequisites Before you start, you need: * **Account Manager** or **Campaign Manager** access to your **LinkedIn Ads** account * Your **LinkedIn Partner ID** — see [How to find your LinkedIn Partner ID](/guides/linkedin-ads/how-to-find-linkedin-partner-id) * A list of the event types you want to track (commonly Purchase, Add to Cart, Lead, Sign Up) ## Steps to create LinkedIn Conversion Rules <Steps> <Step title="Sign in to Campaign Manager"> Sign in to [LinkedIn Campaign Manager](https://www.linkedin.com/campaignmanager/) and select your ad account. </Step> <Step title="Open the Conversions tab"> Click **Data** → **Signals Manager** → **Conversions**. This page lists existing conversion rules and lets you create new ones. </Step> <Step title="Create a new conversion"> Click **Create conversion**. Give the conversion a clear name that matches the event type — for example, `Upstack Purchase` or `Upstack Add to Cart`. </Step> <Step title="Choose the Conversions API data source"> When prompted for the conversion source, select **Conversions API** (server-side). This tells LinkedIn the conversion will be reported by a server-to-server integration rather than the browser Insight Tag. <Note> If you also run the Insight Tag for the same action, you can attach it to the **same** conversion rule. LinkedIn deduplicates browser and server events that share an `eventId` within a single rule. </Note> </Step> <Step title="Configure conversion settings"> Set the conversion details: | Setting | Recommended value | | ---------------------- | --------------------------------------------------------------------------- | | **Conversion type** | Match the action (e.g., Purchase, Add to Cart, Lead, Sign Up) | | **Attribution window** | Use your account default (e.g., 30-day click / 7-day view) | | **Value** | Enable if you want to report revenue (Upstack sends `value` and `currency`) | | **Campaigns** | Associate the rule with at least one active campaign | </Step> <Step title="Save and copy the Conversion Rule ID"> Save the conversion rule. Open the rule's details — the numeric **Conversion Rule ID** appears in the rule settings and in the page URL. **Example format:** `12345678` <Tip> The Conversion Rule ID is the numeric portion only. If LinkedIn displays the full URN `urn:lla:llaPartnerConversion:12345678`, you only need the `12345678` part for Upstack. </Tip> </Step> <Step title="Repeat for each event type"> Create a separate conversion rule for **every** event you want to track and record each Conversion Rule ID: * Purchase → `Purchase Conversion Rule ID` * Add to Cart → `Add to Cart Conversion Rule ID` * Lead → `Lead Conversion Rule ID` * Sign Up → `Sign Up Conversion Rule ID` </Step> <Step title="Map the IDs in Upstack Data"> In Upstack, open your **LinkedIn** destination under **Event Destinations** and paste each Conversion Rule ID into the matching field. See [How to configure the LinkedIn destination](/guides/linkedin-ads/how-to-configure-linkedin-destination-in-upstack-data). </Step> </Steps> ## Event-to-rule mapping reference | Upstack event | LinkedIn conversion type | Destination field | | ---------------------- | ------------------------ | ------------------------------ | | `Purchase` | Purchase | Purchase Conversion Rule ID | | `AddToCart` | Add to Cart | Add to Cart Conversion Rule ID | | `Lead` | Lead | Lead Conversion Rule ID | | `CompleteRegistration` | Sign Up | Sign Up Conversion Rule ID | <Note> **Next step:** [How to generate a LinkedIn Conversions API token](/guides/linkedin-ads/how-to-generate-linkedin-conversion-api-token) </Note> # How to Enable LinkedIn Click ID Tracking Source: https://docs.upstackdata.com/guides/linkedin-ads/how-to-enable-linkedin-click-id-tracking Enable LinkedIn li_fat_id click ID tracking so Upstack Data can capture the strongest LinkedIn match signal and attribute server-side conversions to ad clicks. <Tip> * Turn on **Enhanced Conversion Tracking** in your LinkedIn Insight Tag settings. * LinkedIn appends `li_fat_id` to your landing page URLs on ad clicks. * Upstack captures and stores `li_fat_id` automatically and sends it with every conversion event. * No URL changes are required — enabling the setting is enough. </Tip> <Note> **What is `li_fat_id`?** `li_fat_id` is LinkedIn's **first-party ad tracking click ID**. When a member clicks your ad, LinkedIn appends `li_fat_id` to your landing page URL. It is the strongest match signal LinkedIn supports — events that carry `li_fat_id` match to campaign data far more reliably than events matched on hashed email or IP alone. Upstack stores the value in a first-party cookie and includes it on every server-side Conversions API event. </Note> ## Prerequisites Before you start, you need: * The **LinkedIn Insight Tag** installed and active on your storefront * **Campaign Manager** access to your LinkedIn Ads account * Your LinkedIn destination already configured in Upstack — see [How to configure the LinkedIn destination](/guides/linkedin-ads/how-to-configure-linkedin-destination-in-upstack-data) ## Steps to enable click ID tracking <Steps> <Step title="Sign in to Campaign Manager"> Sign in to [LinkedIn Campaign Manager](https://www.linkedin.com/campaignmanager/) and select your ad account. </Step> <Step title="Open the Insight Tag settings"> Click **Data** → **Signals Manager** and open your **Insight Tag**. </Step> <Step title="Enable Enhanced Conversion Tracking"> Turn on **Enhanced Conversion Tracking** (sometimes labeled **First-party ad tracking** or **Enable click ID**). <Note> This setting authorizes LinkedIn to append the `li_fat_id` parameter to URLs when members click your ads. It does not require any code changes — Upstack reads the parameter automatically. </Note> </Step> <Step title="Save the changes"> Click **Save**. The setting takes effect for new ad clicks immediately. </Step> <Step title="Verify the click ID is captured"> To confirm `li_fat_id` is being captured: 1. Click one of your LinkedIn ads (or open a landing page URL containing `li_fat_id=...`). 2. In your browser's developer tools, check that a first-party cookie storing the LinkedIn click ID is set. 3. Generate a test conversion and confirm match quality improves in **Signals Manager → Signal Diagnostics** over the following days. **Example URL after an ad click:** ``` https://yourstore.com/products/widget?li_fat_id=abc123-def456-7890 ``` </Step> </Steps> ## How Upstack captures the click ID Once Enhanced Conversion Tracking is enabled: 1. **Member clicks ad** → LinkedIn appends `li_fat_id=...` to the landing page URL. 2. **Upstack Pixel loads** → captures `li_fat_id` from the URL and stores it in a first-party cookie. 3. **Visitor converts** → Upstack includes the stored `li_fat_id` with the conversion event. 4. **Event sent to LinkedIn** → LinkedIn matches the conversion to the original ad click for accurate attribution. ## Troubleshooting ### `li_fat_id` not appearing in URLs If the click ID isn't being appended after clicking an ad: 1. Confirm **Enhanced Conversion Tracking** is saved and enabled on the Insight Tag. 2. Verify the Insight Tag is firing on your landing pages (Upstack fires it alongside server-side events). 3. Allow time — the setting applies to new ad clicks, not historical traffic. ### Match quality not improving If match quality stays low after enabling click ID tracking: 1. Confirm the **Partner ID** in Upstack matches the Insight Tag's Partner ID. 2. Ensure ads link directly to your storefront so `li_fat_id` lands in the URL (avoid intermediate redirects that strip parameters). 3. Match quality builds over 1–2 weeks as more identified visitors convert. <Note> For a complete walkthrough, see the [LinkedIn onboarding guide](/guides/linkedin-ads/complete-how-to-guide-for-onboarding-linkedin-in-upstack-data). </Note> # How to Find your LinkedIn Partner ID Source: https://docs.upstackdata.com/guides/linkedin-ads/how-to-find-linkedin-partner-id Find your LinkedIn Partner ID in Campaign Manager Signals Manager — required to configure the Upstack Data LinkedIn destination for server-side conversion forwarding. <Tip> * Sign in to [LinkedIn Campaign Manager](https://www.linkedin.com/campaignmanager/) and open **Data** → **Signals Manager**. * Select your **Insight Tag** to open its details. * Copy the numeric **Partner ID** (e.g., `123456`). * Paste it into your Upstack LinkedIn destination configuration. </Tip> <Note> **What is a LinkedIn Partner ID?** Your **Partner ID** is the numeric identifier for your LinkedIn Insight Tag — the same ID used for browser-side tracking on your storefront. Upstack uses it to associate server-side Conversions API events with your ad account so LinkedIn can deduplicate them against the Insight Tag and attribute conversions to your campaigns. Each LinkedIn ad account has one Partner ID. </Note> ## Prerequisites Before you start, you need: * Access to a **LinkedIn Ads** account at [linkedin.com/campaignmanager](https://www.linkedin.com/campaignmanager/) * The **Campaign Manager** or **Account Manager** role on the ad account * The **LinkedIn Insight Tag** created in your account (or follow the create steps below) ## Steps to find your LinkedIn Partner ID <Steps> <Step title="Sign in to Campaign Manager"> Sign in to [LinkedIn Campaign Manager](https://www.linkedin.com/campaignmanager/) and select the ad account you want to track conversions for. </Step> <Step title="Open Signals Manager"> In the top navigation, click **Data** → **Signals Manager**. The Signals Manager lists your **Insight Tag** and any conversion signals associated with the account. </Step> <Step title="Find or create your Insight Tag"> **If you already have an Insight Tag**, it appears in the Signals Manager — proceed to the next step. **If you need to create one:** * Click **Create Insight Tag** * Choose **I will install the tag myself** (Upstack fires the tag for you) * Save and return to the Signals Manager </Step> <Step title="Locate your Partner ID"> Open your Insight Tag details. The **Partner ID** is displayed as a numeric value. **Example format:** `123456` You can also find it embedded in the Insight Tag code as `partner_id` (e.g., `_linkedin_partner_id = "123456";`). </Step> <Step title="Copy and paste into Upstack Data"> Copy your Partner ID and paste it into the **Partner ID** field in your Upstack LinkedIn destination setup. <Tip> Ensure there are no extra spaces before or after the ID. The Partner ID is numeric only — no letters or prefixes. </Tip> </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, navigate to **Event Destinations**. Your LinkedIn destination should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**, double-check that the Partner ID matches exactly what you see in Campaign Manager (numeric only, no whitespace). </Step> </Steps> <Note> **Next step:** [How to create LinkedIn Conversion Rules](/guides/linkedin-ads/how-to-create-linkedin-conversion-rules) </Note> # How to Generate a LinkedIn Conversions API Token Source: https://docs.upstackdata.com/guides/linkedin-ads/how-to-generate-linkedin-conversion-api-token Generate a LinkedIn Conversions API Direct Access Token in Campaign Manager — the simplest way to authenticate the Upstack Data LinkedIn destination for server-side conversion forwarding. <Tip> * Generate a **Direct Access Token** in Campaign Manager → **Data** → **Signals Manager** → **Conversions API**. * Give the token the **Manage conversions** permission and access to the correct ad account. * Set an expiry (we recommend **1 year**), then copy the token immediately — it won't be shown again. * Paste it into your Upstack LinkedIn destination's **API Access Token** field. </Tip> <Note> **What is a LinkedIn Direct Access Token?** A **Direct Access Token** is a LinkedIn-issued access token you generate directly inside Campaign Manager — no LinkedIn Developer app or OAuth flow required. It authorizes Upstack to send conversion events to LinkedIn's Conversions API on your behalf. You control which ad accounts it covers, the permission it grants (**Manage conversions**), and how long it lasts before expiring. </Note> ## Prerequisites Before you start, you need: * **Admin** or **Account Manager** access to your **LinkedIn Ads** account at [linkedin.com/campaignmanager](https://www.linkedin.com/campaignmanager/) * Your **Partner ID** and at least one **Conversion Rule** created — see [How to create LinkedIn Conversion Rules](/guides/linkedin-ads/how-to-create-linkedin-conversion-rules) ## Steps to generate your LinkedIn CAPI token <Steps> <Step title="Open Signals Manager in Campaign Manager"> Sign in to [LinkedIn Campaign Manager](https://www.linkedin.com/campaignmanager/), select your ad account, then click **Data** → **Signals Manager** in the top navigation. <Frame> <img alt="LinkedIn Campaign Manager Signals Manager with the Conversions API tab" /> </Frame> </Step> <Step title="Open the Conversions API tab"> In Signals Manager, click the **Conversions API** tab. This is where you manage Direct Access Tokens for server-side event forwarding. </Step> <Step title="Generate a token"> Click **Generate token** (or **Manage tokens** → **Generate token** if you've created tokens before). <Frame> <img alt="Generate token dialog in the LinkedIn Conversions API tab" /> </Frame> </Step> <Step title="Select the ad accounts"> Choose the **ad account(s)** the token should cover. The token can only send conversions for the accounts you select here. <Warning> The token must include the ad account that owns your Conversion Rules. Otherwise the token will be valid but events will return a `403` permission error. </Warning> </Step> <Step title="Set the permission to Manage conversions"> Set the token permission to **Manage conversions**. This is the permission Upstack needs to write conversion events to LinkedIn. | Permission | Required | Purpose | | ---------------------- | -------- | --------------------------------------------- | | **Manage conversions** | Yes | Send and manage server-side conversion events | </Step> <Step title="Set the token expiry"> Choose how long the token stays valid. We recommend setting the expiry to **1 year** to minimize how often you need to rotate it. <Tip> Set a calendar reminder a week or two before the expiry date so you can generate a replacement token before conversion forwarding is interrupted. </Tip> </Step> <Step title="Copy and save the token securely"> LinkedIn displays the generated token — a long alphanumeric string. Copy it immediately and store it somewhere secure (a password manager works well). <Warning> **The token is shown only once.** LinkedIn will not display it again after you close the dialog. If you lose it, you'll have to generate a new one. Treat it like a password and never expose it in client-side code. </Warning> </Step> <Step title="Add the token to Upstack Data"> Sign in to [Upstack Data](https://app.upstackdata.com/pixel/event-destinations) and open your **LinkedIn** destination under **Event Destinations**. Paste the token into the **API Access Token** field and save. </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, the LinkedIn destination card should show **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**: * Confirm the token was pasted in full (no truncation, no whitespace). * Confirm the token has the **Manage conversions** permission. * Confirm the token includes the ad account that owns your Conversion Rules. </Step> </Steps> ## Token expiration and renewal Direct Access Tokens expire based on the duration you set when generating them (we recommend 1 year). When a token expires: * The destination status changes to **Unhealthy** and events return a `401` error. To renew: 1. Go to Campaign Manager → **Data** → **Signals Manager** → **Conversions API**. 2. Generate a new token with the same ad accounts and **Manage conversions** permission. 3. Update the **API Access Token** field in your Upstack LinkedIn destination. <Note> **Next step:** [How to enable LinkedIn click ID tracking](/guides/linkedin-ads/how-to-enable-linkedin-click-id-tracking) </Note> # Complete How-To Guide for Onboarding Microsoft Advertising in Upstack Data Source: https://docs.upstackdata.com/guides/microsoft-ads/complete-how-to-guide-for-onboarding-microsoft-ads Onboard Microsoft Advertising (Bing Ads) in Upstack Data — locate your UET Tag ID, generate your CAPI auth token, configure the destination, and verify server-side conversion forwarding. <Info> **New to Upstack?** Follow the [getting started guide](/get-started/install-on-shopify) for a streamlined onboarding walkthrough. </Info> <Tip> * Configure the **Microsoft Advertising destination** in Upstack Data with your **UET Tag ID** and **CAPI Auth Token**. * Ensure Auto-tagging or manual `msclkid` tracking is enabled in your campaigns. * Verify events appear in **Microsoft Advertising → Tools → UET Tags → Tag Status**. * Monitor attribution improvements over 7-10 days of campaign traffic. </Tip> <Warning> **CAPI Pilot Program:** Microsoft's Conversions API is currently in pilot. Contact your Microsoft Advertising account manager to enroll before enabling server-side tracking in Upstack. </Warning> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to a **Microsoft Advertising** account * Your **UET Tag ID** from Microsoft Advertising * Enrollment in the **Conversions API pilot program** * Your **CAPI Auth Token** (generated after pilot enrollment) * Active Microsoft Advertising campaigns with msclkid tracking enabled <Steps> <Step title="Enroll in the Conversions API pilot"> Contact your Microsoft Advertising account manager or Microsoft Advertising support to request enrollment in the Conversions API pilot program. Once enrolled, the auth token generation option becomes available in your UET Tag settings. Help guide: [How to enable the Conversions API →](/guides/microsoft-ads/how-to-enable-conversions-api) </Step> <Step title="Find your UET Tag ID"> Locate your UET Tag ID in the Microsoft Advertising dashboard under Tools → UET Tags. This numeric ID identifies your tracking tag. Help guide: [How to find your UET Tag ID →](/guides/microsoft-ads/how-to-find-uet-tag-id) </Step> <Step title="Create Event Goals"> Create Event Goals in Microsoft Advertising to track specific conversion types (purchase, add\_to\_cart, etc.) that Upstack will send via CAPI. Help guide: [How to create Event Goals →](/guides/microsoft-ads/how-to-create-event-goals) </Step> <Step title="Enable msclkid tracking"> Ensure Auto-tagging is enabled or configure manual msclkid tracking in your campaigns so click IDs are captured for attribution. Help guide: [How to enable msclkid tracking →](/guides/microsoft-ads/how-to-enable-msclkid-tracking) </Step> <Step title="Configure the Microsoft Advertising destination in Upstack Data"> In the Upstack dashboard, navigate to **Event Destinations** and add a **Microsoft Advertising** destination using your **UET Tag ID** and **CAPI Auth Token**. Help guide: [How to configure the Microsoft Advertising destination →](/guides/microsoft-ads/how-to-configure-microsoft-ads-destination) </Step> <Step title="Verify the full setup is healthy"> Confirm each piece of the setup is working: * In the Upstack dashboard, **Event Destinations** shows your Microsoft Advertising destination as **Healthy** (green). * In Microsoft Advertising → **Tools** → **UET Tags** → select your tag → **Tag Status**, server-side events appear alongside browser events. * Test with a real ad click — clicking your own ad and completing a purchase should generate a tracked conversion within 5-10 minutes. If anything is unhealthy, check the corresponding help guide above for troubleshooting steps. </Step> </Steps> ## What to expect after setup ### Attribution with msclkid Microsoft Advertising attributes conversions using the `msclkid` click identifier when available, plus hashed email and phone for enhanced matching: | Scenario | Attribution | | ------------------------------------------------------ | ---------------------------------- | | User clicks ad with `msclkid`, converts same session | ✅ Attributed | | User clicks ad with `msclkid`, converts within 90 days | ✅ Attributed (if cookie persists) | | Known customer with email, no click ID | ✅ Attributed via enhanced matching | | User visits directly without ad click | ❌ Cannot be attributed | | User clears cookies between click and conversion | ⚠️ Depends on email/phone matching | ### Conversion reporting timeline * **Initial conversions** start appearing in Microsoft Advertising within 5-10 minutes of real ad clicks and purchases. * **Full attribution picture** emerges over 7-10 days as more users complete the click → conversion journey. * **Server-side events** appear with a "Server" indicator in UET Tag Status. ### Deduplication Microsoft deduplicates based on `eventId`. Upstack sends a shared `eventId` on every server-side event, and Microsoft's deduplication logic matches events by `eventId` and keeps only one. As long as the UET Tag ID in Upstack matches your browser UET Tag, you won't see duplicate conversions. <Note> **Need help?** If you encounter any issues during setup or don't see conversions appearing after confirming ad clicks, contact our [support team](/support) with your **UET Tag ID** and we'll help diagnose the problem. </Note> # How to Configure Microsoft Advertising Destination in Upstack Data Source: https://docs.upstackdata.com/guides/microsoft-ads/how-to-configure-microsoft-ads-destination Configure the Microsoft Advertising (Bing Ads) destination inside Upstack Data with your UET Tag ID and CAPI Auth Token. <Info> **Prerequisites:** You need your [UET Tag ID](/guides/microsoft-ads/how-to-find-uet-tag-id) and [CAPI Auth Token](/guides/microsoft-ads/how-to-enable-conversions-api) before configuring this destination. </Info> ## Steps <Steps> <Step title="Open Upstack Data dashboard"> Log in to [app.upstackdata.com](https://app.upstackdata.com) and select your store. </Step> <Step title="Navigate to Event Destinations"> In the left sidebar, click **Integrations** → **Event Destinations**. </Step> <Step title="Add Microsoft Advertising destination"> Click **+ Add Destination** and select **Microsoft Advertising** from the list of available destinations. </Step> <Step title="Enter your UET Tag ID"> Paste your **UET Tag ID** (numeric value) in the Tag ID field. Don't have it? [Find your UET Tag ID →](/guides/microsoft-ads/how-to-find-uet-tag-id) </Step> <Step title="Enable Conversions API (recommended)"> Toggle **Enable Conversions API** to enable server-side event delivery. When enabled, paste your **CAPI Auth Token** in the Auth Token field. Don't have it? [Generate your CAPI Auth Token →](/guides/microsoft-ads/how-to-enable-conversions-api) </Step> <Step title="Save and verify"> Click **Save** to activate the destination. The destination status should show **Healthy** (green) within a few minutes if the credentials are valid. </Step> </Steps> ## Configuration fields | Field | Required | Description | | -------------------------- | ----------------- | ----------------------------------------------- | | **UET Tag ID** | Yes | Your Microsoft Advertising UET Tag ID (numeric) | | **Enable Conversions API** | No | Toggle to enable server-side event delivery | | **CAPI Auth Token** | When CAPI enabled | Bearer token for authenticating API requests | ## Troubleshooting <AccordionGroup> <Accordion title="Destination shows Unhealthy status"> **Common causes:** * Invalid or expired CAPI Auth Token — regenerate in Microsoft Advertising * Incorrect UET Tag ID — verify in Microsoft Advertising → Tools → UET Tags * Account not enrolled in CAPI pilot — contact your Microsoft Advertising account manager </Accordion> <Accordion title="Events not appearing in Microsoft Advertising"> 1. Verify the destination status is Healthy in Upstack 2. Check that Event Goals are configured in Microsoft Advertising 3. Wait 5-10 minutes for events to propagate 4. Use the Upstack Event Debugger to confirm events are being sent </Accordion> </AccordionGroup> <Note> **Need help?** Contact our [support team](/support) with your UET Tag ID and we'll help troubleshoot. </Note> # How to Create Event Goals in Microsoft Advertising Source: https://docs.upstackdata.com/guides/microsoft-ads/how-to-create-event-goals Create Event Goals in Microsoft Advertising to track specific conversion types sent by Upstack Data via the Conversions API. **Event Goals** in Microsoft Advertising define which events count as conversions for your campaigns. Upstack sends events like `purchase`, `add_to_cart`, and `view_item` — you need corresponding Event Goals to track them. <Note> Microsoft uses **free-form event names** rather than predefined standard events. Event matching is done via Event Goals configured in the Microsoft Advertising UI. </Note> ## Steps <Steps> <Step title="Sign in to Microsoft Advertising"> Go to [ads.microsoft.com](https://ads.microsoft.com) and sign in to your account. </Step> <Step title="Navigate to Conversion Goals"> In the top navigation, click **Tools** → **Conversion Goals** (under Conversion tracking). </Step> <Step title="Create a new goal"> Click **+ Create conversion goal** and select **Event** as the goal type. </Step> <Step title="Configure the goal"> Fill in the goal settings: * **Goal name:** Use a descriptive name (e.g., "Upstack Purchase", "Upstack Add to Cart") * **Event name:** Enter the exact event name Upstack sends (see mapping table below) * **Revenue value:** Configure how revenue is tracked (use event value for purchases) * **Attribution window:** Set your desired click-through and view-through windows </Step> <Step title="Save the goal"> Click **Save** to create the Event Goal. Repeat for each event type you want to track. </Step> </Steps> ## Event name mapping Create Event Goals for these Upstack events: | Upstack event | Event name to use | Recommended settings | | ------------------ | ----------------- | -------------------------------------- | | `Purchase` | `purchase` | Revenue: Use event value, Primary goal | | `AddToCart` | `add_to_cart` | Revenue: Fixed value or event value | | `ViewContent` | `view_item` | Revenue: None or fixed value | | `InitiateCheckout` | `begin_checkout` | Revenue: Use event value | | `Lead` | `lead` | Revenue: Fixed value | | `Search` | `search` | Revenue: None | | `SignUp` | `sign_up` | Revenue: Fixed value | | `PageView` | `pageLoad` | Revenue: None | ## Goal settings recommendations ### Primary vs. secondary goals * **Primary goal:** Purchase events — these are used for campaign optimization * **Secondary goals:** Add to cart, view content — useful for analysis but don't directly influence bidding ### Attribution windows * **Click-through window:** 30 days (default) — conversions attributed to ad clicks * **View-through window:** 1 day — conversions attributed to ad impressions without clicks ### Revenue tracking For purchase events, select **Use the revenue value from conversions** to pass the actual order value from Upstack. ## Verification After creating Event Goals: 1. Wait for Upstack to send some events (may take a few hours depending on store traffic) 2. Check **Tools** → **UET Tags** → select your tag → **Tag Status** 3. Verify events appear with the correct event names <Note> **Need help?** Contact our [support team](/support) if events aren't being tracked correctly. </Note> # How to Enable the Microsoft Advertising Conversions API Source: https://docs.upstackdata.com/guides/microsoft-ads/how-to-enable-conversions-api Enroll in the Microsoft Advertising Conversions API pilot program and generate your CAPI Auth Token for server-side event delivery. Microsoft's **Conversions API (CAPI)** enables server-side event delivery alongside the browser UET Tag. Server-side events bypass ad blockers and browser restrictions, improving match rates and attribution accuracy. <Warning> **Pilot Program:** The Conversions API is currently in pilot. You must be enrolled in the pilot program before you can generate an auth token. </Warning> ## Step 1: Enroll in the CAPI pilot <Steps> <Step title="Contact Microsoft Advertising"> Reach out to your Microsoft Advertising account manager or contact [Microsoft Advertising support](https://about.ads.microsoft.com/en-us/resources/support) to request enrollment in the Conversions API pilot program. Include your: * Microsoft Advertising account ID * UET Tag ID * Business use case (server-side conversion tracking via Upstack Data) </Step> <Step title="Wait for enrollment confirmation"> Microsoft will review your request and enable CAPI access for your account. This typically takes 1-2 business days. You'll receive an email confirmation when enrolled. </Step> </Steps> ## Step 2: Generate your CAPI Auth Token Once enrolled in the pilot: <Steps> <Step title="Sign in to Microsoft Advertising"> Go to [ads.microsoft.com](https://ads.microsoft.com) and sign in to your account. </Step> <Step title="Navigate to UET Tags"> In the top navigation, click **Tools** → **UET Tags**. </Step> <Step title="Select your UET Tag"> Click on the UET Tag you want to use for server-side tracking. </Step> <Step title="Access CAPI settings"> In the tag details, look for the **Conversions API** or **Server-side tracking** section. This section only appears if your account is enrolled in the CAPI pilot. </Step> <Step title="Generate auth token"> Click **Generate token** or **Create auth token**. A Bearer token will be generated. **Copy this token immediately** — it may not be shown again. </Step> <Step title="Save the token securely"> Store the auth token securely. You'll need it when configuring the Microsoft Advertising destination in Upstack Data. </Step> </Steps> ## Token management ### Token expiration CAPI auth tokens may have an expiration date. Check your Microsoft Advertising account for token validity and regenerate if needed. ### Token rotation If you need to rotate your token: 1. Generate a new token in Microsoft Advertising 2. Update the token in your Upstack destination settings 3. The old token will continue working briefly to allow for transition ## Troubleshooting <AccordionGroup> <Accordion title="I don't see the CAPI option in UET Tag settings"> Your account is not yet enrolled in the Conversions API pilot. Contact your Microsoft Advertising account manager to request enrollment. </Accordion> <Accordion title="My token isn't working"> **Common causes:** * Token was copied incorrectly (check for extra spaces or truncation) * Token has expired — generate a new one * Account CAPI access was revoked — contact Microsoft Advertising support </Accordion> </AccordionGroup> ## Next steps Once you have your CAPI Auth Token: * [Configure the destination in Upstack Data →](/guides/microsoft-ads/how-to-configure-microsoft-ads-destination) * [Create Event Goals →](/guides/microsoft-ads/how-to-create-event-goals) # How to Enable msclkid Tracking for Microsoft Advertising Source: https://docs.upstackdata.com/guides/microsoft-ads/how-to-enable-msclkid-tracking Ensure msclkid (Microsoft Click ID) is captured and stored for attribution in Microsoft Advertising campaigns. The **msclkid** (Microsoft Click ID) is a unique identifier appended to your landing page URLs when users click on Microsoft Advertising ads. Upstack captures this click ID and includes it with server-side events for accurate attribution. ## How msclkid works 1. User clicks your Microsoft ad 2. Microsoft appends `msclkid=XXXXXXXX` to the landing page URL 3. Upstack Pixel captures the `msclkid` from the URL 4. Upstack stores the `msclkid` in a first-party cookie 5. When the user converts, Upstack sends the `msclkid` with the server-side event 6. Microsoft matches the event to the original ad click ## Enable Auto-tagging (recommended) Auto-tagging automatically appends `msclkid` to all ad click URLs. This is the recommended approach. <Steps> <Step title="Sign in to Microsoft Advertising"> Go to [ads.microsoft.com](https://ads.microsoft.com) and sign in to your account. </Step> <Step title="Navigate to Account Settings"> Click on your account name in the top navigation → **Account settings**. </Step> <Step title="Enable Auto-tagging"> Under **Tracking**, find the **Auto-tagging** option. Toggle it **ON** to automatically append msclkid to all ad URLs. </Step> <Step title="Save changes"> Click **Save** to apply the setting. </Step> </Steps> ## Manual tracking (alternative) If you need manual control over click ID tracking, add the `msclkid` parameter to your campaign tracking templates. ### Campaign-level tracking template Add to your campaign's **Tracking template** field: ``` {lpurl}?msclkid={msclkid} ``` Or if you already have URL parameters: ``` {lpurl}&msclkid={msclkid} ``` ### Account-level tracking template Apply to all campaigns by setting the template at the account level: 1. Go to **Account settings** → **Tracking** 2. Add your tracking template with the `{msclkid}` parameter ## Verify msclkid is working <Steps> <Step title="Click one of your ads"> Search for a term that triggers your ad and click through to your landing page. </Step> <Step title="Check the URL"> Look at the URL in your browser. You should see `msclkid=XXXXXXXX` as a URL parameter. Example: `https://yourstore.com/products/item?msclkid=abc123def456...` </Step> <Step title="Check Upstack Pixel Helper"> If you have the [Upstack Pixel Helper](/guides/shopify/how-to-install-upstack-data-pixel-helper) installed, open it and verify that the `msclkid` is being captured. </Step> </Steps> ## Troubleshooting <AccordionGroup> <Accordion title="msclkid not appearing in URLs"> **Common causes:** * Auto-tagging is disabled — enable it in Account settings * Final URL excludes query parameters — check your ad configuration * Landing page redirects strip parameters — ensure redirects preserve query strings </Accordion> <Accordion title="msclkid appearing but not being tracked"> **Check these:** * Upstack Pixel is installed and active on your landing page * No JavaScript errors blocking the Upstack Pixel * Cookie consent is granted (if using consent mode) </Accordion> <Accordion title="Attribution not working despite msclkid"> **Verify:** * The destination is configured with the correct UET Tag ID * Event Goals are created in Microsoft Advertising * Events are reaching Microsoft (check UET Tag Status) </Accordion> </AccordionGroup> ## Cookie persistence Upstack stores the `msclkid` in a first-party cookie to preserve attribution across sessions. The cookie persists for 90 days by default, matching Microsoft's conversion attribution window. <Note> **Privacy considerations:** First-party cookies are more resilient to browser restrictions than third-party cookies, but may still be affected by ITP (Safari) and other privacy features. Server-side delivery helps maintain attribution accuracy in these cases. </Note> ## Next steps Once msclkid tracking is enabled: * [Configure the destination in Upstack Data →](/guides/microsoft-ads/how-to-configure-microsoft-ads-destination) * [Create Event Goals →](/guides/microsoft-ads/how-to-create-event-goals) # How to Find Your UET Tag ID in Microsoft Advertising Source: https://docs.upstackdata.com/guides/microsoft-ads/how-to-find-uet-tag-id Locate your Universal Event Tracking (UET) Tag ID in Microsoft Advertising for use with Upstack Data. Your **UET Tag ID** is a numeric identifier for your Microsoft Advertising tracking tag. You'll need this ID to configure the Microsoft Advertising destination in Upstack Data. ## Steps <Steps> <Step title="Sign in to Microsoft Advertising"> Go to [ads.microsoft.com](https://ads.microsoft.com) and sign in to your account. </Step> <Step title="Navigate to UET Tags"> In the top navigation, click **Tools** → **UET Tags** (under Conversion tracking). </Step> <Step title="Find your UET Tag"> Locate your existing UET Tag in the list. If you don't have one, click **Create UET tag** to create a new one. </Step> <Step title="Copy the Tag ID"> The **Tag ID** is displayed in the list view or tag details. It's a numeric value (e.g., `12345678`). Copy this ID — you'll need it when configuring the Microsoft Advertising destination in Upstack Data. </Step> </Steps> ## Where to find the Tag ID The UET Tag ID appears in several places: * **UET Tags list:** The ID column shows the numeric Tag ID for each tag * **Tag details:** Click on a tag name to view its details, including the Tag ID * **UET Tag code snippet:** The Tag ID appears in the JavaScript snippet as part of the `uetq` initialization ## If you don't have a UET Tag If you don't have an existing UET Tag: 1. Click **Create UET tag** in the UET Tags section 2. Give your tag a descriptive name (e.g., "Upstack Tracking") 3. Optionally add a description 4. Click **Save** 5. Copy the new Tag ID <Note> **Important:** Use the same UET Tag ID for both your browser UET Tag and Upstack server-side delivery to ensure proper event deduplication. </Note> ## Next steps Once you have your UET Tag ID: * [Generate your CAPI Auth Token →](/guides/microsoft-ads/how-to-enable-conversions-api) * [Configure the destination in Upstack Data →](/guides/microsoft-ads/how-to-configure-microsoft-ads-destination) # How to migrate from Elevar to Upstack without losing tracking data Source: https://docs.upstackdata.com/guides/migrations/elevar-to-upstack Step-by-step migration guide from Elevar to Upstack Data — parallel install, event verification, cleanup, and post-migration monitoring. Switching tracking providers is risky. Done wrong, you lose conversion data, create duplicate events, or starve your ad platform algorithms of signal during the transition. This guide walks through a clean migration from Elevar to Upstack using a parallel-run approach that minimizes data gaps and gives you time to verify everything before cutting over. <Tip> **Run Elevar and Upstack in parallel for 2–3 days before disabling Elevar.** A short window of duplicate events (which Meta and most platforms deduplicate via `event_id`) is far safer than a gap in tracking. Don't shortcut this step. </Tip> ## Why brands migrate from Elevar to Upstack Understanding what's driving your move helps you prioritize what to verify after the switch. * **Identity resolution vs. GTM-based server-side.** Elevar routes events through Google Tag Manager's server container. Upstack uses a direct server-side pipeline with built-in [identity resolution](/pixel/identity-resolution) — matching visitors across devices and sessions without depending on GTM infrastructure. * **Klaviyo enhancement.** Upstack's Flows product enriches and pushes identified profiles to Klaviyo so abandonment flows trigger for visitors that Klaviyo's native tracking misses. This isn't available through Elevar's integration. * **Attribution reporting.** Upstack's Analytics product provides multi-touch attribution alongside tracking, so you can see which channels and campaigns drive conversions without relying solely on each ad platform's self-reported numbers. * **Event Match Quality.** Upstack's identity enrichment attaches more customer matching parameters (hashed email, phone, click IDs, external IDs) to each event, which can improve EMQ and give optimization algorithms stronger signal. * **Cost and consolidation.** Running separate tools for tracking, attribution, and Klaviyo enrichment adds up. Upstack combines these in a single platform. ## Prerequisites Before you begin, make sure you have: * [Shopify Admin](https://admin.shopify.com) access with permission to install apps and edit themes * An [Upstack Data](https://app.upstackdata.com) account (you'll create one during the install) * Admin access to every destination platform you'll reconnect (Meta, Google Ads, TikTok, Pinterest, Klaviyo, etc.) * Admin access to your Google Tag Manager container if Elevar uses one (GTM container ID format: `GTM-XXXXXXX`) * Your existing Elevar account access for reference during the cutover ## Pre-migration checklist Capture this before you begin. Having it written down makes verification after migration straightforward. ### Document your current Elevar setup * **Active events:** List every event Elevar is sending — both standard (PageView, ViewContent, AddToCart, InitiateCheckout, Purchase) and any custom events. * **Connected platforms:** Record which destinations Elevar sends to (Meta, Google Ads, TikTok, Pinterest, Klaviyo, etc.). * **GTM container details:** If Elevar manages a GTM container, note the container ID (format `GTM-XXXXXXX`) and which tags are Elevar-specific vs. custom tags you've added. * **Shopify theme scripts:** Note whether Elevar has added code to your Shopify theme files (`theme.liquid`, `checkout.liquid`, or via snippets in **Shopify Admin → Online Store → Themes → Edit code**). * **Shopify data sharing:** Check if Shopify's built-in Meta data sharing is enabled (Shopify Admin → **Settings → Customer events** or **Sales channels → Facebook & Instagram**). ### Save baseline metrics * **EMQ scores:** Screenshot your current Event Match Quality scores in Meta Events Manager for each event type. * **Daily event volume:** Note the average daily count for Purchase, AddToCart, and ViewContent events over the past 7 days. * **Shopify order count:** Record your average daily Shopify orders for comparison after migration. ## Migration steps The migration follows a parallel-run approach: install Upstack alongside Elevar, verify Upstack is working, then remove Elevar. Expect a brief period of duplicate events — that's normal and preferable to a gap in data. ### Phase 1 — Install Upstack alongside Elevar (Day 1) <Steps> <Step title="Install the Upstack Shopify app"> Install the Upstack Data app from the Shopify App Store. The app deploys Upstack's tracking on your store and begins capturing events immediately. Full instructions: [Install on Shopify](/get-started/install-on-shopify). </Step> <Step title="Connect your destinations in Upstack"> Connect every platform Elevar is currently sending to. Use the destination guides linked below for each one. | Platform | Setup guide | | ---------- | -------------------------------------------------- | | Meta | [Meta CAPI destination](/destinations/meta-capi) | | Google Ads | [Google Ads destination](/destinations/google-ads) | | TikTok | [TikTok destination](/destinations/tiktok) | | Klaviyo | [Klaviyo destination](/destinations/klaviyo) | | Pinterest | [Pinterest destination](/destinations/pinterest) | | Snapchat | [Snapchat destination](/destinations/snapchat) | See [Connect a destination](/get-started/connect-a-destination) for the general flow. </Step> <Step title="Connect data sources for attribution"> If you plan to use the Analytics dashboard, connect your Sources for spend data — Shopify, Meta, Google, and TikTok are available as OAuth connections. Spend from these sources powers ROAS and multi-touch attribution. </Step> </Steps> ### Phase 2 — Verify Upstack events (Days 1–3) With both tools running, confirm Upstack is correctly capturing and forwarding events. <Steps> <Step title="Check Meta Events Manager"> 1. Open [Meta Events Manager](https://business.facebook.com/events_manager). 2. Select your pixel. 3. In the **Overview** or **Test Events** tab, look for events sent via the **Conversions API** (server) channel. 4. Verify you see recent events for `PageView`, `ViewContent`, `AddToCart`, `InitiateCheckout`, and `Purchase`. During the parallel-run window, event counts will be higher than normal because both Elevar and Upstack are sending. Meta deduplicates events using `event_id` — if both tools send the same event with the same ID, Meta counts it once. </Step> <Step title="Place a test order"> 1. Place a test order on your store (or wait for a real one). 2. In Events Manager, verify a Purchase event from Upstack's CAPI source appears within a few minutes. 3. Check that the event carries the correct value, currency, and customer matching parameters. </Step> <Step title="Check EMQ scores"> After 24–48 hours of parallel running, check your EMQ scores in Events Manager. They may temporarily appear elevated due to the additional events from Upstack. This normalizes after you remove Elevar. </Step> </Steps> ### Phase 3 — Disable Elevar (Days 3–4) Once Upstack events are flowing correctly, remove Elevar. Do this methodically — Elevar leaves tracking code in multiple locations. <Warning> **Don't skip the cleanup steps.** Uninstalling the Elevar Shopify app does **not** remove its theme snippets, GTM tags, or Shopify Customer Events pixel. Leftover code is the #1 cause of duplicate events after migration. </Warning> <Steps> <Step title="Disable Elevar in your Shopify theme"> Elevar installs render snippets in your Shopify theme. Remove them from your theme code: 1. Sign in to your [Shopify Admin](https://admin.shopify.com), then navigate to **Online Store → Themes**. 2. On your live theme, click **... → Edit code**. 3. Open `theme.liquid` and search for any of these render tags: * `{% render 'elevar-head-listener' %}` * `{% render 'elevar-head' %}` * `{% render 'elevar-body-end' %}` 4. Delete each render tag you find. 5. If your theme still has a `checkout.liquid` file (legacy stores), search for and remove similar Elevar render tags there as well. 6. In the **Snippets** folder, search for files containing `elevar` in the name. Delete each Elevar snippet file. </Step> <Step title="Remove Elevar from Shopify Customer Events"> 1. In [Shopify Admin](https://admin.shopify.com), navigate to **Settings → Customer events**. 2. If Elevar has a Custom Pixel configured here, remove it or set it to inactive. </Step> <Step title="Clean up GTM (if applicable)"> If Elevar managed a Google Tag Manager container: 1. Sign in to [Google Tag Manager](https://tagmanager.google.com) and open your container (ID format `GTM-XXXXXXX`). 2. Identify all tags Elevar created — typically Meta Pixel, Google Ads conversion tracking, and any other platform-specific tags. 3. Pause or delete Elevar-specific tags. Do **not** delete custom tags you've added independently. 4. If the container was used exclusively by Elevar and you have no other tags in it, consider removing the GTM container script from your Shopify theme entirely. </Step> <Step title="Disable Shopify's native Meta data sharing"> Shopify's built-in Meta integration sends events independently. If left on alongside Upstack, it creates duplicates. 1. In [Shopify Admin](https://admin.shopify.com), navigate to **Settings → Customer events** or **Settings → Apps and sales channels → Facebook & Instagram**. 2. Disable the native data sharing / pixel integration if it's active. Full walkthrough: [Disable existing tracking](/get-started/disable-existing-tracking). </Step> <Step title="Uninstall the Elevar app"> 1. In [Shopify Admin](https://admin.shopify.com), navigate to **Settings → Apps and sales channels**. 2. Find **Elevar** in the list and click **Uninstall** (or **Remove app**). 3. Confirm the uninstallation. </Step> </Steps> ### Phase 4 — Post-migration verification (Days 4–11) <Steps> <Step title="Verify no duplicate events"> 1. Install the [Upstack Data Pixel Helper](/guides/shopify/how-to-install-upstack-data-pixel-helper) Chrome extension. 2. Browse your store — visit a product page, add to cart, and check out. 3. On each page, Pixel Helper should show events from Upstack only. If you see duplicate events, Elevar code or Shopify's native integration may still be active. </Step> <Step title="Compare event volumes"> After 48 hours running Upstack only, compare against your baseline: | Metric | Pre-migration baseline | Post-migration target | | ------------------------------------------- | ---------------------- | --------------------- | | Daily Purchase events | \[your baseline] | Equal or higher | | Daily AddToCart events | \[your baseline] | Equal or higher | | Daily ViewContent events | \[your baseline] | Equal or higher | | Shopify orders vs. Events Manager purchases | \[your baseline] | Near 1:1 | If Upstack's volumes are lower than your Elevar baseline, check that all destinations are properly connected and that no events are failing in the [Upstack dashboard](https://app.upstackdata.com). </Step> <Step title="Check EMQ after 48 hours"> EMQ scores need 48 hours to stabilize after the transition. Compare against your saved baseline: * **Improved or steady:** Migration is healthy. * **Dropped:** Confirm Upstack is sending the full set of customer matching parameters (email, phone, click IDs, browser data). If scores don't recover within 72 hours, see [Why is my Meta EMQ panel showing zeros?](/guides/facebook-ads/why-is-my-meta-emq-panel-showing-zeros-0-0-10) or contact Upstack support. </Step> <Step title="Monitor for 7 days"> Don't declare the migration complete until you've monitored for a full week. Check daily: * Event counts in [Meta Events Manager](https://business.facebook.com/events_manager) match Shopify activity. * No error events or failed deliveries in the [Upstack dashboard](https://app.upstackdata.com). * Campaign performance (CPA, ROAS) remains stable. * EMQ scores hold at pre-migration levels or better. </Step> </Steps> ## Common gotchas <AccordionGroup> <Accordion title="Elevar leaves hardcoded scripts in your theme"> Even after uninstalling the Elevar app, render tags and snippet files in your Shopify theme remain. Remove them manually (see Phase 3, Step 1). If left in place, they can cause JavaScript errors or attempt to load resources that no longer exist. </Accordion> <Accordion title="GTM container still fires Elevar tags"> If Elevar set up tags in a GTM container, uninstalling the app does **not** remove those tags. They keep firing until you manually pause or delete them in GTM. This is the most common source of duplicate events after migration. </Accordion> <Accordion title="Shopify's built-in data sharing is still on"> Shopify's native Meta integration sends events independently of any third-party tracking app. If it was enabled alongside Elevar, it stays on after Elevar is removed — and now creates duplicates with Upstack. Always check and disable this during migration. </Accordion> <Accordion title="Temporary event volume drop during cutover"> When you disable Elevar and before Upstack has fully ramped, there may be a brief window (typically a few hours) where event volume dips. This is normal and resolves as Upstack's pipeline picks up all incoming events. If the drop persists beyond 24 hours, contact Upstack support. </Accordion> <Accordion title="Checkout extensibility considerations"> Shopify has deprecated `checkout.liquid` for checkout tracking. If your Elevar setup relied on `checkout.liquid` scripts, those are already non-functional on Shopify's new checkout. Upstack's tracking works with Shopify's current Checkout Extensibility framework, so no additional checkout configuration is needed. </Accordion> <Accordion title="Historical pixel data remains"> Migrating from Elevar to Upstack does not erase your pixel's historical data. All previously recorded events, audiences, and optimization learnings in Meta, Google, and other platforms remain intact. You're changing the data pipeline, not the destination. </Accordion> </AccordionGroup> ## When to contact Upstack support Reach out if: * Events are not appearing in Events Manager after 24 hours of Upstack being active. * EMQ scores drop significantly (more than 2 points) and don't recover within 72 hours. * You see duplicate events that you can't trace to Elevar remnants or Shopify's native integration. * Your Upstack dashboard shows delivery errors for any connected destination. * You need help identifying and removing Elevar scripts from your Shopify theme. ## Frequently asked questions <AccordionGroup> <Accordion title="Will I lose my historical pixel data when I migrate?"> No. Your pixel's historical event data, custom audiences, and optimization learnings remain in Meta Events Manager (and other platforms) regardless of which tracking tool sends the events. You're changing the data pipeline, not resetting the destination. </Accordion> <Accordion title="How long should I run Elevar and Upstack in parallel?"> Two to three days is typically sufficient. You need enough time for Upstack to send events across all your standard event types (PageView through Purchase) and for you to verify them in Events Manager. A few days of slightly elevated event counts is far better than a gap in tracking data. </Accordion> <Accordion title="Will running both tools simultaneously cause duplicate events?"> Yes, temporarily. During the parallel run, both Elevar and Upstack will send events to your connected platforms. Meta and most platforms deduplicate events using `event_id`. Once you disable Elevar, duplicates stop. If you see persistent duplicates after removing Elevar, check for residual scripts in your theme, GTM tags, and Shopify's native data sharing. </Accordion> <Accordion title="Do I need to reconfigure my ad campaigns after migration?"> No. Your campaigns, ad sets, and optimization settings reference your pixel ID and conversion events — none of which change during migration. Upstack sends to the same pixel and uses the same standard event names. Your campaigns continue running without interruption. </Accordion> <Accordion title="What if my EMQ scores drop after migration?"> Give it 48–72 hours for scores to stabilize. Upstack's identity enrichment typically maintains or improves EMQ because it attaches more customer matching parameters to each event. If scores remain lower than your baseline after 72 hours, contact support to review your destination configuration. </Accordion> <Accordion title="Can I migrate if I have custom events set up in Elevar?"> Yes. Document your custom events before migration (see the pre-migration checklist) and confirm with the Upstack team that the same custom events can be configured. Standard events are supported by default. See [How to create custom event triggers in Upstack](/guides/custom-events/how-to-create-custom-event-triggers). </Accordion> </AccordionGroup> ## Related <CardGroup> <Card title="Install on Shopify" icon="shopify" href="/get-started/install-on-shopify"> Get Upstack's tracking app deployed on your Shopify store. </Card> <Card title="Connect a destination" icon="plug" href="/get-started/connect-a-destination"> Connect Meta, Google, TikTok, Klaviyo, and other destinations. </Card> <Card title="Disable existing tracking" icon="ban" href="/get-started/disable-existing-tracking"> Cleanup steps for legacy pixels, GTM tags, and native Shopify integrations. </Card> <Card title="Meta CAPI destination" icon="meta" href="/destinations/meta-capi"> Configure server-side event delivery to Meta. </Card> <Card title="Google Ads destination" icon="google" href="/destinations/google-ads"> Set up Google Ads conversion delivery. </Card> <Card title="TikTok destination" icon="music" href="/destinations/tiktok"> Configure TikTok Events API delivery. </Card> <Card title="Klaviyo destination" icon="envelope" href="/destinations/klaviyo"> Set up identity-enriched profile delivery to Klaviyo. </Card> <Card title="Why is my Meta EMQ panel showing zeros?" icon="circle-question" href="/guides/facebook-ads/why-is-my-meta-emq-panel-showing-zeros-0-0-10"> Troubleshoot Event Match Quality scores after migration. </Card> </CardGroup> # Complete How-To Guide for Onboarding Omnisend in Upstack Data Source: https://docs.upstackdata.com/guides/omnisend/complete-how-to-guide-for-onboarding-omnisend-in-upstack-data Onboard Omnisend in Upstack Data — generate the Omnisend API key, configure the destination, and forward identity-enriched events to power email and SMS automation flows. <Tip> **Quick Summary** * Sign in to [Omnisend](https://app.omnisend.com) and generate an **API key** * Sign in to your [Upstack dashboard](https://app.upstackdata.com) * **Configure the Omnisend destination** using your API key * Click **Create Configuration** and verify the destination shows as **Healthy** </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to your [Omnisend](https://app.omnisend.com) account * Permission to create API keys in Omnisend ## Onboarding Steps <Steps> <Step title="Generate your Omnisend API key"> <Note> An **Omnisend API key** is a unique credential generated in your Omnisend account that allows Upstack Data to securely access and interact with your Omnisend data. It is a long alphanumeric string, typically structured as a 64-character secret followed by a `-` and a short identifier (for example, `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxx`). </Note> Help guide to complete this step: [How to Generate your Omnisend API Key →](/guides/omnisend/how-to-generate-your-omnisend-api-key) </Step> <Step title="Configure the Omnisend destination in your Upstack dashboard"> Help guide to complete this step: [How to Configure Omnisend Pixel Destination in Upstack Data →](/guides/omnisend/how-to-configure-omnisend-pixel-destination-in-upstack-data) </Step> <Step title="Verify the Omnisend destination is healthy"> In your [Upstack dashboard](https://app.upstackdata.com/pixel/event-destinations), open **Events Destination** and confirm the **Omnisend** destination shows a **Healthy** status. Then, in [Omnisend](https://app.omnisend.com), open **Audience** or **Reports** and confirm contacts and events from Upstack Data are arriving as expected. </Step> </Steps> <Note> **Need help?** If you encounter any issues during setup or don't see expected improvements after 10 days, contact our support team with your Omnisend API key and we'll help diagnose the problem. </Note> # How to Configure Omnisend Pixel Destination in Upstack Data Source: https://docs.upstackdata.com/guides/omnisend/how-to-configure-omnisend-pixel-destination-in-upstack-data Configure the Omnisend destination in Upstack Data with your Omnisend API key — forwarding browse, cart, checkout, and purchase events to power email and SMS automation triggers. <Tip> **Quick Summary** * In the Upstack dashboard, open **Events Destination** and click **+ New Destination** * Select **Omnisend** from the destination options * Enter your generated **Omnisend API key** * Click **Create Configuration** and verify the destination shows as **Healthy** </Tip> <Note> **What this setup enables** Configuring Omnisend as a destination in Upstack Data ensures accurate tracking of customer events, consolidates attribution reporting, and provides more reliable data to optimize ad performance. </Note> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to your [Omnisend](https://app.omnisend.com) account * Your Omnisend **API key** ([how to generate it](/guides/omnisend/how-to-generate-your-omnisend-api-key)) ## Configuration Steps <Steps> <Step title="Sign in to your Upstack dashboard"> Sign in to [Upstack Data](https://app.upstackdata.com) and open the [Events Destination](https://app.upstackdata.com/pixel/event-destinations) page. </Step> <Step title="Add a new Omnisend destination"> In the **Events Destination** page, click **+ New Destination** in the top-right of the page. <img alt="Add New Destination" /> In the **Select a Destination** popup, click **Omnisend**, then click **Next**. <img alt="Select a Destination popup with Omnisend option highlighted" /> </Step> <Step title="Enter your Omnisend API key"> In the configuration form, paste your generated **Omnisend API key** into the **API key** field. The API key is a long alphanumeric string, typically formatted as a 64-character secret followed by a `-` and a short identifier (for example, `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxx`). <img alt="Omnisend destination configuration form with API key field" /> </Step> <Step title="Create the configuration"> Click the **Create Configuration** button at the bottom of the form. <img alt="Create Configuration button at bottom of Omnisend destination form" /> <Note> **Success! 🎉** You should see a confirmation message and the Omnisend destination will appear as **Healthy** in your destinations list. </Note> <Note> Here's a help guide on **[How to Generate your Omnisend API Key →](/guides/omnisend/how-to-generate-your-omnisend-api-key)** </Note> </Step> <Step title="Verify the destination is sending events"> Back in the [Events Destination](https://app.upstackdata.com/pixel/event-destinations) page, confirm the new **Omnisend** destination shows a **Healthy** status. Then, in [Omnisend](https://app.omnisend.com), open **Audience** or **Reports** and confirm contacts and events from Upstack Data are arriving as expected. New events typically appear within a few minutes after a test purchase or page view. </Step> </Steps> # How to Generate your Omnisend API Key Source: https://docs.upstackdata.com/guides/omnisend/how-to-generate-your-omnisend-api-key Generate or locate your Omnisend API key in the Omnisend dashboard — required to authenticate the Upstack Data Omnisend destination and forward server-side events. <Tip> **Quick Summary** * Sign in to [Omnisend](https://app.omnisend.com) * Open **Store settings → API** * Click **+ Create API key**, name it `UpstackData`, then click **Create API key** * **Copy** the generated API key and store it securely (Omnisend only shows it once) * Paste the API key into the Omnisend destination form in your Upstack dashboard </Tip> <Note> What is an **Omnisend API key**? An **Omnisend API key** is a unique credential generated in your Omnisend account that allows Upstack Data to securely access and interact with your Omnisend data. It is a long alphanumeric string, typically structured as a 64-character secret followed by a `-` and a short identifier (for example, `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxx`). </Note> ## Prerequisites Before you start, you need: * Admin access to your [Omnisend](https://app.omnisend.com) account * Permission to create API keys in Omnisend * A secure place to store the generated API key (Omnisend only displays it once) ## Steps to Generate the API Key <Steps> <Step title="Sign in to Omnisend"> Sign in to [Omnisend](https://app.omnisend.com) to open your dashboard. In the left-hand menu, click **Store settings**, then go to the **API** tab. <img alt="Omnisend left menu with Store settings option highlighted" /> <img alt="Omnisend Store settings page with API tab selected" /> </Step> <Step title="Create a new API key"> On the **API** settings page, click the **+ Create API key** button. <img alt="Omnisend API settings page with Create API key button" /> Enter `UpstackData` as the API key name, then click **Create API key**. <img alt="Create API key dialog with UpstackData name entered" /> </Step> <Step title="Copy and save your API key"> Click the **Copy API key** button to copy the generated API key, then store it securely (for example, in a password manager). Paste the API key into the **API key** field when [configuring the Omnisend destination](/guides/omnisend/how-to-configure-omnisend-pixel-destination-in-upstack-data) in your Upstack dashboard. <Warning> This API key is only shown once — copy it immediately. The API key is sensitive: anyone with it can read and write data in your Omnisend account, so store it in a secure location and never share it. </Warning> <img alt="Omnisend API key generated with Copy API key button" /> </Step> <Step title="Verify the API key format"> Confirm the value you copied is a long alphanumeric string with no extra spaces — typically a 64-character secret followed by a `-` and a short identifier. You can paste it into the **API key** field when configuring the Omnisend destination in your Upstack dashboard. </Step> </Steps> <Note> Here's a help guide on **[How to Configure Omnisend Pixel Destination in Upstack Data →](/guides/omnisend/how-to-configure-omnisend-pixel-destination-in-upstack-data)** </Note> # Complete How-To Guide for Onboarding Outbrain in Upstack Data Source: https://docs.upstackdata.com/guides/outbrain/complete-how-to-guide-for-onboarding-outbrain-in-upstack-data Onboard Outbrain Amplify in Upstack Data — locate your Marketer ID, configure the click ID tracking, and set up the destination for server-side conversion forwarding. <Info> **New to Upstack?** Follow the [getting started guide](/get-started/install-on-shopify) for a streamlined onboarding walkthrough. </Info> <Tip> * Configure the **Outbrain destination** in Upstack Data with your **Marketer ID**. * Add `obclid={{ob_click_id}}` to your **campaign URL suffix** to capture click IDs. * Verify events appear in **Outbrain Amplify Dashboard → Conversions**. * Monitor attribution improvements over 7-10 days of campaign traffic. </Tip> <Warning> **Critical limitation:** Unlike Meta, TikTok, and Reddit, Outbrain does **NOT** support enhanced matching with hashed email or phone. Attribution relies **solely on click ID (`obclid`)**. Events from visitors without a click ID are skipped — they cannot be attributed to any campaign. </Warning> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to an **Outbrain Amplify** account * Your **Outbrain Marketer ID** from [Amplify Dashboard → Settings → Tracking](https://amplify.outbrain.com/) * Active Outbrain campaigns with click ID tracking configured <Steps> <Step title="Configure click ID tracking in your campaigns"> Add the click ID parameter to your campaign tracking URLs so Upstack can capture and store the click ID for attribution. **Add to your campaign URL suffix:** ``` obclid={{ob_click_id}} ``` Help guide: [How to configure Outbrain click ID tracking →](/guides/outbrain/how-to-configure-outbrain-click-id-tracking) </Step> <Step title="Find your Outbrain Marketer ID"> Locate your Marketer ID (also called OB\_ADV\_ID) in the Outbrain Amplify dashboard. This 32-character hexadecimal string identifies your account for conversion tracking. Help guide: [How to find your Outbrain Marketer ID →](/guides/outbrain/how-to-find-outbrain-marketer-id) </Step> <Step title="Configure the Outbrain destination in Upstack Data"> In the Upstack dashboard, navigate to **Event Destinations** and add an **Outbrain** destination using your **Marketer ID**. Help guide: [How to configure the Outbrain destination in Upstack Data →](/guides/outbrain/how-to-configure-outbrain-destination-in-upstack-data) </Step> <Step title="Verify the full setup is healthy"> Confirm each piece of the setup is working: * In the Upstack dashboard, **Event Destinations** shows your Outbrain destination as **Healthy** (green). * In [Outbrain Amplify Dashboard](https://amplify.outbrain.com/), the **Conversions** page shows recent events. * Test with a real ad click — clicking your own ad and completing a purchase should generate a tracked conversion within 5-10 minutes. If anything is unhealthy, check the corresponding help guide above for troubleshooting steps. </Step> </Steps> ## What to expect after setup ### Attribution limitations Unlike other ad platforms (Meta, TikTok, Reddit, Google), Outbrain only attributes conversions when a click ID is present: | Scenario | Attribution | | ----------------------------------------------------- | ------------------------------------------ | | User clicks ad with `obclid`, converts same session | ✅ Attributed | | User clicks ad with `obclid`, converts within 30 days | ✅ Attributed (if cookie persists) | | User visits directly without ad click | ❌ Skipped (no click ID) | | User clears cookies between click and conversion | ❌ Skipped (click ID lost) | | User clicks on mobile, converts on desktop | ❌ Skipped (different device/cookie) | | Known customer with email, no click ID | ❌ Skipped (email not used for attribution) | ### Conversion reporting timeline * **Initial conversions** start appearing in Amplify within 5-10 minutes of real ad clicks and purchases. * **Full attribution picture** emerges over 7-10 days as more users complete the click → conversion journey. * **Lower attribution rates** compared to Meta/TikTok are expected — this reflects Outbrain's click-only attribution model, not a tracking issue. ### Deduplication Outbrain deduplicates based on `orderId`. If you're running both the Outbrain browser pixel and Upstack server-side delivery, ensure both send the same `orderId` value for the same transaction to avoid double-counting. <Note> **Need help?** If you encounter any issues during setup or don't see conversions appearing after confirming ad clicks, contact our [support team](/support) with your **Outbrain Marketer ID** and we'll help diagnose the problem. </Note> # How to Configure Outbrain Click ID Tracking Source: https://docs.upstackdata.com/guides/outbrain/how-to-configure-outbrain-click-id-tracking Add the Outbrain click ID parameter to your campaign URL suffix — required for server-side conversion attribution via Upstack Data. <Tip> * Open your campaign in **Outbrain Amplify Dashboard**. * Navigate to the **Tracking** or **URL Parameters** section. * Add `obclid={{ob_click_id}}` to your **URL suffix** or tracking template. * Save and verify URLs include the click ID on ad clicks. </Tip> <Warning> **This step is critical.** Outbrain does **NOT** support enhanced matching with email or phone. Attribution relies **solely** on the click ID (`obclid`). Without this parameter in your campaign URLs, Upstack cannot attribute any conversions to Outbrain — all events will be skipped. </Warning> <Note> **What is the Outbrain click ID?** The **click ID** (also called `ob_click_id` or `obclid`) is a unique identifier that Outbrain generates for each ad click. When a user clicks your ad, Outbrain appends this ID to your landing page URL. Upstack captures and stores this ID in a first-party cookie, then includes it with every conversion event so Outbrain can match the conversion back to the original ad click. </Note> ## Prerequisites Before you start, you need: * Access to an **Outbrain Amplify** account at [amplify.outbrain.com](https://amplify.outbrain.com/) * Campaign edit permissions * Active or draft campaigns to update ## Steps to configure click ID tracking <Steps> <Step title="Sign in to Outbrain Amplify"> Sign in to Outbrain Amplify at [amplify.outbrain.com](https://amplify.outbrain.com/). </Step> <Step title="Open your campaign"> Navigate to **Campaigns** and select the campaign you want to configure. Click **Edit** or **Settings** to access the campaign configuration. </Step> <Step title="Find the URL parameters section"> Look for **Tracking**, **URL Parameters**, **URL Suffix**, or **Tracking Template** in the campaign settings. This is where you add parameters that Outbrain will append to your landing page URLs. </Step> <Step title="Add the click ID parameter"> Add the following to your URL suffix: ``` obclid={{ob_click_id}} ``` **If you already have other tracking parameters** (like UTM tags), append the click ID with an ampersand: ``` utm_source=outbrain&utm_medium=native&utm_campaign={{campaign_name}}&obclid={{ob_click_id}} ``` <Tip> The `{{ob_click_id}}` placeholder is a dynamic macro that Outbrain replaces with the actual click ID when a user clicks your ad. </Tip> </Step> <Step title="Save the campaign"> Click **Save** or **Apply** to save your changes. </Step> <Step title="Verify the configuration"> To verify the click ID is being appended: 1. Preview your ad or click on it from a test placement 2. Check the landing page URL in your browser's address bar 3. Confirm you see `obclid=v1-abc123...` (a long alphanumeric string starting with `v1-`) **Example URL after click:** ``` https://yourstore.com/products/widget?utm_source=outbrain&obclid=v1-abc123xyz789def456ghi789jkl012 ``` </Step> <Step title="Update all active campaigns"> Repeat steps 2-5 for **all your active Outbrain campaigns**. <Warning> Any campaign missing the `obclid` parameter will not have its conversions attributed. Make sure to update all campaigns, including existing ones. </Warning> </Step> </Steps> ## How Upstack captures the click ID Once your campaigns are configured: 1. **User clicks ad** → Outbrain appends `obclid=v1-...` to the landing page URL 2. **Upstack Pixel loads** → Captures the `obclid` from the URL and stores it in a first-party cookie (`_obclid`) 3. **User converts** → Upstack includes the stored click ID with the conversion event 4. **Event sent to Outbrain** → Outbrain matches the conversion to the original ad click The click ID cookie expires after 30 days, matching Outbrain's attribution window. ## Alternative parameter name Outbrain also recognizes `ob_click_id` as a URL parameter name. Both work identically: * `obclid={{ob_click_id}}` ✅ Recommended (shorter) * `ob_click_id={{ob_click_id}}` ✅ Also works Upstack captures both parameter names automatically. ## Troubleshooting ### Click ID not appearing in URL If the click ID isn't being appended after clicking your ad: 1. Verify the URL suffix is saved correctly in the campaign settings 2. Check for typos — the macro must be exactly `{{ob_click_id}}` 3. Clear your browser cache and try clicking the ad again 4. Contact Outbrain support if the issue persists ### Conversions not being attributed If you've configured the click ID but conversions aren't appearing in Amplify: 1. Verify the Upstack Pixel is loading on your landing pages (check browser dev tools) 2. Confirm the `_obclid` cookie is being set after ad clicks 3. Check that your Upstack destination shows **Healthy** status 4. Wait 5-10 minutes — conversions aren't instant <Note> **Next step:** [How to configure the Outbrain destination in Upstack Data](/guides/outbrain/how-to-configure-outbrain-destination-in-upstack-data) </Note> # How to Configure Outbrain Destination in Upstack Data Source: https://docs.upstackdata.com/guides/outbrain/how-to-configure-outbrain-destination-in-upstack-data Configure the Outbrain destination in Upstack Data to forward server-side conversion events to Outbrain's Unified Pixel API for native advertising attribution. <Tip> * Navigate to **Event Destinations** in the Upstack dashboard. * Click **Add Destination** and select **Outbrain**. * Enter your **Marketer ID** (32-character hexadecimal string from Amplify). * Save the configuration and verify the destination shows **Healthy**. </Tip> <Note> **What is the Outbrain Marketer ID?** Your **Outbrain Marketer ID** (also called **OB\_ADV\_ID** or **Pixel ID**) is a unique 32-character hexadecimal identifier that tells Upstack which Outbrain account should receive your conversion events. Find it in [Amplify Dashboard → Settings → Tracking](https://amplify.outbrain.com/). </Note> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Your **Outbrain Marketer ID** — see [How to find your Outbrain Marketer ID](/guides/outbrain/how-to-find-outbrain-marketer-id) * Click ID tracking configured in your campaigns — see [How to configure Outbrain click ID tracking](/guides/outbrain/how-to-configure-outbrain-click-id-tracking) ## Steps to configure the Outbrain destination <Steps> <Step title="Sign in to Upstack Data"> Sign in to your Upstack Data account at [app.upstackdata.com](https://app.upstackdata.com). </Step> <Step title="Navigate to Event Destinations"> In the left-hand navigation, click **Event Destinations**. </Step> <Step title="Add a new destination"> Click the **Add Destination** button in the top-right corner. In the destination picker, select **Outbrain** from the list of available destinations. </Step> <Step title="Enter your Marketer ID"> In the **Outbrain Marketer ID** field, paste your Marketer ID from the Outbrain Amplify dashboard. **Example format:** `00abc123def456789012345678901234` (32 hexadecimal characters) <Tip> Ensure there are no extra spaces before or after the ID. The value should be exactly 32 characters. </Tip> </Step> <Step title="Configure event settings (optional)"> By default, Upstack forwards **Purchase**, **Lead**, **SignUp**, and **AddToCart** events to Outbrain. High-volume events like **PageView** and **ViewContent** are disabled by default to avoid unnecessary API calls — you can enable them if needed for your use case. </Step> <Step title="Save the configuration"> Click **Create Configuration** to save the destination. </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, navigate to **Event Destinations**. Your Outbrain destination should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**, double-check: * The Marketer ID is exactly 32 hexadecimal characters * No extra whitespace or special characters * The ID matches what you see in Amplify → Settings → Tracking </Step> </Steps> <Warning> **Remember:** Outbrain only attributes conversions when a click ID (`obclid`) is present. Make sure your campaign URLs include `obclid={{ob_click_id}}` — see [How to configure Outbrain click ID tracking](/guides/outbrain/how-to-configure-outbrain-click-id-tracking). </Warning> <Note> **Next step:** [Complete onboarding guide](/guides/outbrain/complete-how-to-guide-for-onboarding-outbrain-in-upstack-data) for the full setup walkthrough. </Note> # How to Find Your Outbrain Marketer ID Source: https://docs.upstackdata.com/guides/outbrain/how-to-find-outbrain-marketer-id Find your Outbrain Marketer ID in the Amplify Dashboard — required to configure the Upstack Data Outbrain destination for server-side conversion forwarding. <Tip> * Sign in to [Outbrain Amplify Dashboard](https://amplify.outbrain.com/). * Navigate to **Settings → Tracking** (or **Account Settings → Pixel**). * Locate the **Marketer ID** (also called OB\_ADV\_ID or Pixel ID). * Copy the 32-character hexadecimal string and paste it into Upstack. </Tip> <Note> **What is an Outbrain Marketer ID?** Your **Outbrain Marketer ID** (also known as **OB\_ADV\_ID** or **Advertiser ID**) is a unique 32-character hexadecimal identifier that Upstack Data uses to send conversion data to your Outbrain account. This ID is also embedded in the Outbrain pixel code if you've installed it manually. </Note> ## Prerequisites Before you start, you need: * Access to an **Outbrain Amplify** account at [amplify.outbrain.com](https://amplify.outbrain.com/) * Account admin or campaign manager permissions ## Steps to find your Outbrain Marketer ID <Steps> <Step title="Sign in to Outbrain Amplify"> Sign in to Outbrain Amplify at [amplify.outbrain.com](https://amplify.outbrain.com/). If you have multiple accounts, select the account you want to connect to Upstack. </Step> <Step title="Navigate to Settings"> Click your account name or profile icon in the top-right corner, then select **Settings**. Alternatively, look for a **Settings** or **Account Settings** option in the navigation menu. </Step> <Step title="Open Tracking settings"> In the Settings menu, click **Tracking** or **Pixel** to view your tracking configuration. This page contains your Outbrain pixel installation code and Marketer ID. </Step> <Step title="Locate your Marketer ID"> Look for the **Marketer ID**, **OB\_ADV\_ID**, **Advertiser ID**, or **Pixel ID** field. **Example format:** `00abc123def456789012345678901234` The Marketer ID is a 32-character hexadecimal string (letters a-f and numbers 0-9 only). <Tip> If you see the pixel installation code, the Marketer ID is the value assigned to `OB_ADV_ID` in the JavaScript snippet: ```javascript theme={null} var OB_ADV_ID = '00abc123def456789012345678901234'; ``` </Tip> </Step> <Step title="Copy the Marketer ID"> Copy the full 32-character Marketer ID. <Warning> Make sure to copy the complete ID with no extra spaces or characters. The ID must be exactly 32 hexadecimal characters. </Warning> </Step> <Step title="Paste into Upstack Data"> In the Upstack dashboard, navigate to **Event Destinations → Add Destination → Outbrain**. Paste the Marketer ID into the **Outbrain Marketer ID** field. </Step> <Step title="Save and verify"> Click **Create Configuration** to save the destination. Your Outbrain destination should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**, double-check that the Marketer ID was copied correctly without extra whitespace. </Step> </Steps> ## Troubleshooting ### Can't find the Marketer ID in Settings If you don't see a Tracking or Pixel section in Settings: 1. Check if you have admin permissions — campaign-level users may not see account settings 2. Look for **Events** or **Conversions** in the navigation menu 3. Contact your Outbrain account manager if you still can't locate it ### Marketer ID validation fails in Upstack If Upstack reports an invalid Marketer ID: 1. Verify the ID is exactly 32 characters 2. Confirm it contains only hexadecimal characters (0-9, a-f) 3. Remove any extra spaces, quotes, or special characters 4. Re-copy from the Amplify dashboard <Note> **Next step:** [How to configure Outbrain click ID tracking](/guides/outbrain/how-to-configure-outbrain-click-id-tracking) — required for attribution to work. </Note> # Complete How-To Guide for Onboarding Pinterest in Upstack Data Source: https://docs.upstackdata.com/guides/pinterest-ads/complete-how-to-guide-for-onboarding-pinterest-in-upstack-data Onboard Pinterest in Upstack Data — generate the Pinterest Conversions API token, locate your Pixel and Advertiser IDs, configure the destination, and disable Shopify's duplicate Pinterest pixel. <Tip> **Quick Summary** * **Locate and copy** your **Pinterest Pixel Tag ID** and **Advertiser ID** * **Generate and copy** your **Pinterest Conversion API key** * **Create and configure** the Pinterest destination in your Upstack dashboard * **Disable Pinterest data sharing** in Shopify </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to your Pinterest Business account * A Shopify store admin account (only required for the data-sharing step) ## Onboarding Steps <Steps> <Step title="Find and copy your Pixel Tag ID"> <Note> What is a **Pinterest Pixel Tag ID?** A **Pinterest Pixel Tag ID** is a unique identifier assigned to your Pinterest Pixel, which tracks user actions (like page views, add-to-cart, or purchases) on your website. It's what you use to connect your site activity with Pinterest Ads for measurement and optimization. The ID is a 13-digit number (for example, `2613000000000`). </Note> Help guide to complete this step: [How to Find Pinterest Pixel Tag ID →](/guides/pinterest-ads/how-to-find-pinterest-pixel-tag-id) </Step> <Step title="Find and copy your Advertiser ID"> <Note> What is a **Pinterest Advertiser ID?** A **Pinterest Advertiser ID** is a unique numeric identifier assigned to your Pinterest Business advertising account. It is typically a 12-digit number (for example, `549000000000`). </Note> Help guide to complete this step: [How to Find Pinterest Advertiser ID →](/guides/pinterest-ads/how-to-find-pinterest-advertiser-id) </Step> <Step title="Generate your Conversion API key"> <Note> What is a **Pinterest Conversion API key** (access token)? A **Pinterest Conversion API key** (access token) is a secure credential that lets your server send conversion events, like purchases or sign-ups, directly to Pinterest. It improves tracking accuracy, attribution, and data security compared to the standard Pixel. The token starts with `pina_` and is roughly 90+ characters long. </Note> Help guide to complete this step: [How to Generate Pinterest Conversion API Key →](/guides/pinterest-ads/how-to-generate-pinterest-conversion-api-key-access-token) </Step> <Step title="Create and configure the Pinterest destination in your Upstack dashboard"> <Note> Integrating Pinterest with Upstack Data centralizes tracking, improves attribution, and enables better campaign optimization and reporting. </Note> Help guide to complete this step: [How to Configure Pinterest Destination in Upstack Data →](/guides/pinterest-ads/how-to-configure-pinterest-destination-in-upstack-data) </Step> <Step title="Disable Pinterest data sharing in Shopify"> <Warning> Turning off Pinterest data sharing helps avoid duplicate or conflicting conversions, keeping Upstack Data as your one reliable source of accurate performance data. </Warning> Help guide to complete this step: [How to Disable Pinterest Data Sharing →](/guides/pinterest-ads/how-to-disable-pinterest-data-sharing-in-shopify) </Step> <Step title="Verify the Pinterest destination is healthy"> In your [Upstack dashboard](https://app.upstackdata.com/pixel/event-destinations), open **Events Destination** and confirm the **Pinterest** destination shows a **Healthy** status. Then, in [Pinterest Business](https://business.pinterest.com), open **Conversions → Pinterest tag** and confirm events are arriving from your Conversions API integration. </Step> </Steps> <Note> **Need help?** If you encounter any issues during setup or don't see expected improvements after 10 days, contact our support team and we'll help diagnose the problem. </Note> # How to Configure Pinterest Destination in Upstack Data Source: https://docs.upstackdata.com/guides/pinterest-ads/how-to-configure-pinterest-destination-in-upstack-data Configure the Pinterest destination in Upstack Data with your Pinterest Conversions API key, Pixel ID, and Advertiser ID to forward server-side conversions to Pinterest CAPI. <Tip> **Quick Summary** * In the Upstack dashboard, open **Events Destination** and click **+ New Destination** * Select **Pinterest** from the destination options * Enter your **Pixel Tag ID**, **Advertiser ID**, and **Conversion API key** * Check the box to **enable Pinterest Conversions API** * Click **Create Configuration** and verify the destination shows as **Healthy** </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to your Pinterest Business account * Your Pinterest **Pixel Tag ID** ([how to find it](/guides/pinterest-ads/how-to-find-pinterest-pixel-tag-id)) * Your Pinterest **Advertiser ID** ([how to find it](/guides/pinterest-ads/how-to-find-pinterest-advertiser-id)) * Your Pinterest **Conversion API key** ([how to generate it](/guides/pinterest-ads/how-to-generate-pinterest-conversion-api-key-access-token)) ## Configuration Steps <Steps> <Step title="Sign in to your Upstack dashboard"> Sign in to [Upstack Data](https://app.upstackdata.com) and open the [Events Destination](https://app.upstackdata.com/pixel/event-destinations) page. </Step> <Step title="Add a new Pinterest destination"> In the **Events Destination** page, click **+ New Destination** in the top-right of the page. <img alt="Add New Destination" /> In the **Select a Destination** popup, click **Pinterest**, then click **Next**. <img alt="Select Pinterest from destination options in popup" /> </Step> <Step title="Enter your Pinterest credentials"> Fill out the form with the following: 1. **Pinterest Pixel Tag ID** — a 13-digit number, for example `2613000000000` 2. Check the box **Check to enable sending events via Pinterest Conversions API** 3. **Advertiser ID** — a 12-digit numeric ID, for example `549000000000` 4. **Conversion API key** — the access token starting with `pina_` <Warning> The **Conversions API checkbox must be selected** for server-side tracking to work. </Warning> <img alt="Pinterest destination form with Pixel Tag ID, Advertiser ID, and CAPI key fields" /> <Note> ***Need help finding these?*** **[How to Find Pinterest Pixel Tag ID →](/guides/pinterest-ads/how-to-find-pinterest-pixel-tag-id)** **[How to Generate Pinterest Conversion API Key →](/guides/pinterest-ads/how-to-generate-pinterest-conversion-api-key-access-token)** **[How to Find Pinterest Advertiser ID →](/guides/pinterest-ads/how-to-find-pinterest-advertiser-id)** </Note> </Step> <Step title="Create the configuration"> Click the **Create Configuration** button at the bottom of the form. <img alt="Create Configuration button to save Pinterest destination" /> <Note> **Success! 🎉** You should see a confirmation message and the Pinterest destination will appear as **Healthy** in your destinations list. </Note> </Step> <Step title="Verify the destination is sending events"> Back in the [Events Destination](https://app.upstackdata.com/pixel/event-destinations) page, confirm that the new **Pinterest** destination shows a **Healthy** status. Then, in [Pinterest Business](https://business.pinterest.com), open **Conversions → Pinterest tag** and confirm that events are being received from your Conversions API integration. New events typically appear within a few minutes after a test purchase or page view. </Step> </Steps> # How to Create a New Pinterest Pixel (Tag) ID Source: https://docs.upstackdata.com/guides/pinterest-ads/how-to-create-a-new-pinterest-pixel-tag-id Create a new Pinterest Pixel (Tag) ID in Pinterest Ads Manager — required to configure the Upstack Data Pinterest destination and forward conversions via Pinterest CAPI. <Tip> **Quick Summary** * Sign in to [Pinterest Business](https://business.pinterest.com) and open **Manage business → Conversions** * Under **Pinterest tag**, click **Tag manager** * Start the tag setup and follow the instructions for your chosen installation method * **Copy** your new **Pinterest Pixel Tag ID** * Install the tag on your website and verify it is firing </Tip> ## What is a Pinterest Pixel Tag ID? <Note> A **Pinterest Pixel Tag ID** is a unique identifier assigned to your Pinterest Pixel, which tracks user actions (like page views, add-to-cart, or purchases) on your website. It's what you use to connect your site activity with Pinterest Ads for measurement and optimization. The ID is a 13-digit number (for example, `2613000000000`). </Note> ## Prerequisites Before you start, you need: * Admin access to your Pinterest Business account * The ability to install code on your website (or admin access to a supported integration partner such as Shopify or WooCommerce) ## Steps to Create a New Pixel Tag ID <Steps> <Step title="Sign in to Pinterest Business"> Sign in to [Pinterest Business](https://business.pinterest.com). </Step> <Step title="Open Tag manager"> In the top-left of the page, click the **Menu icon** (three horizontal lines). Under **Manage business**, select **Conversions**. <img alt="" /> Under **Pinterest tag**, click **Tag manager**. <img alt="" /> </Step> <Step title="Start the tag setup"> In the **Pinterest Tag** section, click **Get Started** if this is your first tag, or click **Add code** to create an additional tag. <img alt="" /> You will be prompted to choose your installation method: * **Integration partner** (for example, Shopify, WooCommerce) * **Email instructions** to a developer * **Manual setup** (for direct code installation) Follow the setup instructions for your chosen method. <img alt="" /> <Note> **Choose Manual Setup (if applicable)** * Click **Skip** in the bottom-right of the page to proceed with manual setup. * Pinterest will generate a **base tag code snippet** for you. </Note> </Step> <Step title="Copy the Pinterest Pixel Tag ID"> Once created, your Pinterest tag will appear in **Tag manager** with a 13-digit Pixel Tag ID (for example, `2613000000000`). Copy the Pixel Tag ID — this is what you'll enter when configuring the Pinterest destination in your Upstack dashboard. </Step> <Step title="Install the tag on your website"> Paste the base tag code into the `<head>` section of every page on your website. Add **event codes** to track specific actions (for example, `AddToCart`, `Signup`, `Checkout`). </Step> <Step title="Verify the installation"> Use the [Pinterest Tag Helper Chrome Extension](https://chrome.google.com/webstore/detail/pinterest-tag-helper) to confirm your tag is firing correctly on your website. You can also confirm event delivery in **Pinterest Business → Conversions → Pinterest tag**, where new events typically appear within a few minutes. </Step> </Steps> # How to Disable Pinterest Data Sharing in Shopify Source: https://docs.upstackdata.com/guides/pinterest-ads/how-to-disable-pinterest-data-sharing-in-shopify Disable Shopify's Pinterest sales channel data sharing to stop duplicate Pinterest pixel events and let Upstack Data deliver clean server-side conversions to Pinterest CAPI. <Tip> **Quick Summary** * In Shopify admin, open **Settings → Apps and sales channels** * Find **Pinterest** and click the **three-dot (⋮) menu** * Select **Uninstall** and confirm in the popup </Tip> If you're using **Upstack Data** for Pinterest event tracking, you need to uninstall the **Pinterest Sales Channel** from your Shopify store to remove Shopify's native pixel tracking. <Warning> Disabling Pinterest data sharing is crucial to prevent duplicate events, which can distort reporting and attribution. It ensures Pinterest only receives clean, accurate data through Upstack Data for reliable insights and better ad optimization. </Warning> ## Prerequisites Before you start, you need: * Admin access to your Shopify store ([Shopify admin](https://admin.shopify.com)) * The Pinterest Sales Channel currently installed in Shopify * A configured Pinterest destination in your [Upstack dashboard](https://app.upstackdata.com/pixel/event-destinations) ([setup guide](/guides/pinterest-ads/how-to-configure-pinterest-destination-in-upstack-data)) ## Why You Should Disable Pinterest Data Sharing Shopify's Pinterest Sales Channel automatically enables both catalog and pixel tracking, without allowing you to manage them separately. It can cause duplicate events because it sends conversion data from both your browser and server. When combined with Upstack Data's server-side tracking, this may inflate conversions, ROAS, and event counts. Disabling Pinterest's own data-sharing features allows Upstack Data to: * Ensure consistent and deduplicated event tracking * Improve attribution accuracy across platforms * Maintain reliable performance reporting ## Steps to Disable Pinterest Data Sharing in Shopify <Steps> <Step title="Sign in to Shopify admin"> Sign in to [Shopify admin](https://admin.shopify.com) for the store where Pinterest is installed. </Step> <Step title="Open Apps and sales channels"> In the left-hand menu, click **Settings**, then select **Apps and sales channels**. <img alt="Shopify admin Settings menu with Apps and sales channels selected" /> </Step> <Step title="Uninstall the Pinterest sales channel"> Locate **Pinterest** in the list, click the **three-dot (⋮) menu**, then select **Uninstall**. <img alt="Pinterest sales channel with three-dot menu showing Uninstall option" /> A confirmation window will appear. Review the warning, then click **Uninstall** in the bottom-right of the dialog. <img alt="Shopify uninstall confirmation dialog for Pinterest sales channel" /> </Step> <Step title="Verify Pinterest is no longer connected"> Refresh the **Apps and sales channels** page and confirm **Pinterest** no longer appears in the list of installed channels. Then, in your [Upstack dashboard](https://app.upstackdata.com/pixel/event-destinations), confirm the **Pinterest** destination is still **Healthy** and continuing to send events through Upstack Data. </Step> </Steps> <Note> Uninstalling the Pinterest app in Shopify is important because it helps **prevent duplicate tracking and data conflicts** between Pinterest's native integration and Upstack Data. </Note> <Note> **Need Help?** If you encounter any issues during setup, contact our support team and we'll help diagnose the problem. </Note> # How to Find Pinterest Advertiser ID Source: https://docs.upstackdata.com/guides/pinterest-ads/how-to-find-pinterest-advertiser-id Find your Pinterest Advertiser ID in Pinterest Business Manager — required (alongside the Pixel ID and CAPI token) to configure the Upstack Data Pinterest destination. <Tip> **Quick Summary** * Sign in to [Pinterest Business](https://business.pinterest.com) * In the top-right of the page, click your **Business account name** and select your business * In the left-hand menu, open **Ad Accounts** * Select the ad account you want to use, then **copy** the **Advertiser ID** </Tip> ## What is a Pinterest Advertiser ID? <Note> A **Pinterest Advertiser ID** is a unique numeric identifier assigned to your Pinterest Business advertising account. It is typically a 12-digit number (for example, `549000000000`). </Note> ## Prerequisites Before you start, you need: * Admin access to your Pinterest Business account * At least one Pinterest ad account associated with your business ## Steps to Find Your Advertiser ID <Steps> <Step title="Sign in to Pinterest Business"> Sign in to [Pinterest Business](https://business.pinterest.com). </Step> <Step title="Open Ad Accounts"> In the top-right of the page, click your **Business account name**. <img alt="" /> From the dropdown, select your business name. <img alt="" /> In the left-hand menu, click **Ad Accounts**. <img alt="" /> </Step> <Step title="Copy the Advertiser ID"> Select the ad account you want to connect to Upstack Data. The **Advertiser ID** is displayed next to the ad account name as a 12-digit numeric value (for example, `549000000000`). Copy the **Advertiser ID** — you'll paste it into the Pinterest destination form in your Upstack dashboard. <img alt="" /> </Step> <Step title="Verify the Advertiser ID"> Confirm the value you copied is a 12-digit number with no extra characters or spaces. You can paste it into the **Advertiser ID** field when [configuring the Pinterest destination](/guides/pinterest-ads/how-to-configure-pinterest-destination-in-upstack-data) in your Upstack dashboard. </Step> </Steps> <Note> ***Need help finding these?*** **[How to Find Pinterest Pixel Tag ID →](/guides/pinterest-ads/how-to-find-pinterest-pixel-tag-id)** **[How to Generate Pinterest Conversion API Key →](/guides/pinterest-ads/how-to-generate-pinterest-conversion-api-key-access-token)** </Note> # How to Find Pinterest Pixel (Tag) ID Source: https://docs.upstackdata.com/guides/pinterest-ads/how-to-find-pinterest-pixel-tag-id Find your Pinterest Pixel (Tag) ID in Pinterest Ads Manager — required to configure the Upstack Data Pinterest destination for server-side conversion forwarding. <Tip> **Quick Summary** * Sign in to [Pinterest Business](https://business.pinterest.com) * Open **Manage business → Conversions**, then under **Pinterest tag** click **Tag manager** * **Locate and copy** your Pinterest Pixel Tag ID (a 13-digit number) </Tip> ## What is a Pinterest Pixel Tag ID? <Note> A **Pinterest Pixel Tag ID** is a unique identifier assigned to your Pinterest Pixel, which tracks user actions (like page views, add-to-cart, or purchases) on your website. It's what you use to connect your site activity with Pinterest Ads for measurement and optimization. The ID is a 13-digit number (for example, `2613000000000`). </Note> ## Prerequisites Before you start, you need: * Admin access to your Pinterest Business account * An existing Pinterest tag (if you don't have one yet, follow [How to Create a New Pinterest Pixel Tag ID](/guides/pinterest-ads/how-to-create-a-new-pinterest-pixel-tag-id) first) ## Steps to Find Your Pixel Tag ID <Steps> <Step title="Sign in to Pinterest Business"> Sign in to [Pinterest Business](https://business.pinterest.com). </Step> <Step title="Open Tag manager"> In the top-left of the page, click the **Menu icon** (three horizontal lines). Under **Manage business**, select **Conversions**. <img alt="" /> Under **Pinterest tag**, click **Tag manager**. <img alt="" /> </Step> <Step title="Copy your Pixel Tag ID"> If you already have a tag, you'll see it listed under **Pinterest Tag** with a 13-digit ID (for example, `2613000000000`). **Copy** the Pinterest tag — this is your **Pinterest Pixel Tag ID** for the Upstack Data integration. <img alt="" /> <Note> **No tag yet?** If you don't see a Pinterest tag listed, you need to create one first. [How to Create a New Pinterest Pixel Tag ID →](/guides/pinterest-ads/how-to-create-a-new-pinterest-pixel-tag-id) </Note> </Step> <Step title="Verify the Pixel Tag ID"> Confirm the value you copied is a 13-digit number with no extra characters or spaces. You can paste it into the **Pixel Tag ID** field when [configuring the Pinterest destination](/guides/pinterest-ads/how-to-configure-pinterest-destination-in-upstack-data) in your Upstack dashboard. </Step> </Steps> <Note> ***Need help finding these?*** **[How to Generate Pinterest Conversion API Key →](/guides/pinterest-ads/how-to-generate-pinterest-conversion-api-key-access-token)** **[How to Find Pinterest Advertiser ID →](/guides/pinterest-ads/how-to-find-pinterest-advertiser-id)** </Note> # How to Generate Pinterest Conversion API Key (Access Token) Source: https://docs.upstackdata.com/guides/pinterest-ads/how-to-generate-pinterest-conversion-api-key-access-token Generate a Pinterest Conversions API access token in Pinterest Ads Manager — required to authenticate the Upstack Data Pinterest destination and forward server-side conversions. <Tip> **Quick Summary** * Sign in to [Pinterest Business](https://business.pinterest.com) * Open **Manage business → Conversions** * Under **Conversion API**, click **Set up API** * Click **Generate new token** and copy the token (it starts with `pina_`) * Store the token securely — you will paste it into the Pinterest destination form in your Upstack dashboard </Tip> ## What is a Pinterest Conversion API key (access token)? <Note> A **Pinterest Conversion API key** (access token) is a secure credential that lets your server send conversion events, like purchases or sign-ups, directly to Pinterest. It improves tracking accuracy, attribution, and data security compared to the standard Pixel. The token starts with `pina_` and is roughly 90+ characters long (for example, `pina_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA`). </Note> ## Prerequisites Before you start, you need: * Admin access to your Pinterest Business account * At least one Pinterest ad account associated with your business * A secure place to store the generated token (Pinterest only displays it once) ## Steps to Generate the Conversion API Key <Steps> <Step title="Sign in to Pinterest Business"> Sign in to [Pinterest Business](https://business.pinterest.com). </Step> <Step title="Open the Conversions API setup"> In the top-left of the page, click the **Menu icon** (three horizontal lines). Under **Manage business**, select **Conversions**. <img alt="" /> Under **Conversion API**, click **Set up API**. <img alt="" /> </Step> <Step title="Generate the conversion access token"> Scroll to the **Generate conversion access token** section, then click **Generate new token**. <img alt="" /> </Step> <Step title="Copy and save your Conversion API key"> The generated token is your **Pinterest Conversion API key**. It starts with `pina_`. **Copy** the generated token and **store** it securely. You will paste this token into the Pinterest destination form in your Upstack dashboard. <Warning> Pinterest does not store personal tokens — copy it now and save it to a secure location such as a password manager. The same token can be reused across multiple ad accounts under your user ID. </Warning> <img alt="" /> `The generated token starts with pina_` <img alt="" /> </Step> <Step title="Verify the token format"> Confirm the value you copied starts with `pina_` and contains no extra spaces. You can paste it into the **Conversion API key** field when [configuring the Pinterest destination](/guides/pinterest-ads/how-to-configure-pinterest-destination-in-upstack-data) in your Upstack dashboard. </Step> </Steps> <Note> ***Need help finding these?*** **[How to Find Pinterest Pixel Tag ID →](/guides/pinterest-ads/how-to-find-pinterest-pixel-tag-id)** **[How to Find Pinterest Advertiser ID →](/guides/pinterest-ads/how-to-find-pinterest-advertiser-id)** </Note> # Complete How-To Guide for Onboarding Reddit Ads in Upstack Data Source: https://docs.upstackdata.com/guides/reddit-ads/complete-how-to-guide-for-onboarding-reddit-in-upstack-data Onboard Reddit Ads in Upstack Data — locate your Pixel ID, generate the Conversions API token, configure the destination, and remove duplicate Reddit pixels in Shopify. <Info> **New to Upstack?** Follow the [getting started guide](/get-started/install-on-shopify) for a streamlined onboarding walkthrough. </Info> <Tip> * Configure the **Reddit destination** in Upstack Data with your **Pixel ID** and **Conversions API access token**. * Remove duplicate **Reddit pixel installations** in Shopify to prevent inflated metrics. * Verify events appear in **Reddit Ads Manager → Events Manager** with a **Server** badge. * Monitor **Event Match Quality (EMQ)** improvements over 7-10 days. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to a **Reddit Ads** account * A configured **Reddit Pixel** in [Reddit Ads Manager Events Manager](https://ads.reddit.com/) * A **Conversions API access token** generated from that pixel — see [How to generate your Reddit CAPI token](/guides/reddit-ads/how-to-generate-reddit-conversion-api-token) * Shopify owner/staff access (for the duplicate-pixel cleanup step, if applicable) <Steps> <Step title="Configure the Reddit destination in Upstack Data"> In the Upstack dashboard, navigate to **Event Destinations** and add a **Reddit** destination using your **Pixel ID** (typically prefixed with `t2_`) and **Conversions API access token**. Help guide: [How to configure the Reddit destination in Upstack Data →](/guides/reddit-ads/how-to-configure-reddit-destination-in-upstack-data) </Step> <Step title="Remove duplicate Reddit pixel installations"> <Warning> Reddit does not have a native Shopify sales channel like Meta or TikTok, but many brands install the Reddit pixel manually via theme.liquid, Customer Events, or third-party apps. Multiple active pixels with the same Pixel ID cause inflated metrics that Reddit cannot deduplicate without a shared `conversion_id`. </Warning> Help guide: [How to remove duplicate Reddit pixel installations in Shopify →](/guides/reddit-ads/how-to-disable-existing-reddit-pixel-in-shopify) **Common installation locations to check:** * Shopify **Settings → Customer Events** for any custom Reddit pixel scripts * Theme files (`theme.liquid`, header snippets) for hardcoded `rdt('init')` calls * Third-party Reddit pixel apps in Shopify * Reddit pixel tags inside Google Tag Manager </Step> <Step title="Verify the full setup is healthy"> Confirm each piece of the setup is working: * In the Upstack dashboard, **Event Destinations** shows your Reddit destination as **Healthy** (green). * In [Reddit Ads Manager Events Manager](https://ads.reddit.com/), the pixel shows recent events with a **Server** badge for CAPI events. * The **Event Match Quality (EMQ)** column in Reddit's Events Manager shows a score for each event type — these will improve over the next 7-10 days. If anything is unhealthy, check the corresponding help guide above for troubleshooting steps. </Step> </Steps> ## What to expect after setup ### Event Match Quality timeline * **Event Match Quality (EMQ)** scores start to improve in 2-3 days and normalize over 7-10 days. * You can typically expect a 20-40% increase in tracked conversions vs. the browser pixel alone, since CAPI captures conversions lost to ad blockers and iOS restrictions. * The **Purchase** EMQ score sees the biggest improvement because checkout-time events carry the strongest match keys (hashed email, phone, address). ### Reporting differences * Your **Reddit Ads Manager ROAS** will likely **increase** after a few days as Reddit attributes more conversions to ads. Many brands discover their Reddit campaigns were performing 20-40% better than the browser-pixel data suggested. * Conversion volume may temporarily fluctuate during the first 48 hours as Reddit's deduplication logic adjusts to receiving both pixel and CAPI events. <Note> **Need help?** If you encounter any issues during setup or don't see expected EMQ improvements after 10 days, contact our [support team](/support) with your **Reddit Pixel ID** and we'll help diagnose the problem. </Note> # How to Configure Reddit Destination in Upstack Data Source: https://docs.upstackdata.com/guides/reddit-ads/how-to-configure-reddit-destination-in-upstack-data Configure the Reddit Ads destination in Upstack Data with your Pixel ID and Conversions API access token to enable dual tracking via browser pixel and server-side CAPI. <Tip> * In the Upstack dashboard, go to **Event Destinations** and click **+ New Destination**. * Select **Reddit Ads**. * Enter your **Reddit Pixel ID** (typically prefixed with `t2_`). * Paste your **Conversions API access token**. * Click **Create Configuration** and verify the destination shows **Healthy**. </Tip> <Note> **What this setup enables** Setting up the Reddit destination in Upstack Data enables dual tracking via browser pixel and server-side Conversions API (CAPI), recovering the 30-50% of conversions lost to ad blockers, iOS restrictions, and cross-device journeys. </Note> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to a **Reddit Ads** account * A configured **Reddit Pixel** in [Reddit Ads Manager Events Manager](https://ads.reddit.com/) — see [How to find your Reddit Pixel ID](/guides/reddit-ads/how-to-find-reddit-pixel-id) * A **Conversions API access token** — see [How to generate your Reddit CAPI token](/guides/reddit-ads/how-to-generate-reddit-conversion-api-token) ## Configuration steps <Steps> <Step title="Sign in to Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com/pixel/event-destinations). </Step> <Step title="Open the destination configuration"> In the Upstack dashboard, navigate to **Event Destinations**. Click **+ New Destination** in the top-right of the page. In the **Select a Destination** popup, click **Reddit Ads**, then click **Next**. </Step> <Step title="Enter your Pixel ID and CAPI token"> Fill in the form: 1. **Reddit Pixel ID** — the identifier for your Reddit pixel. Reddit Pixel IDs are typically prefixed with `t2_` (e.g., `t2_abc123def`). 2. **Conversions API access token** — a secure key generated from Reddit Ads Manager Events Manager. <Warning> The Conversions API token is a non-expiring secure key. Store it securely and never expose it client-side. If the token is compromised, generate a new one and follow the [update CAPI token guide](/guides/reddit-ads/how-to-update-reddit-conversion-api-token). </Warning> <Note> **Need help finding these?** * [How to find your Reddit Pixel ID](/guides/reddit-ads/how-to-find-reddit-pixel-id) * [How to generate your Reddit CAPI token](/guides/reddit-ads/how-to-generate-reddit-conversion-api-token) </Note> </Step> <Step title="Create the configuration"> Click the **Create Configuration** button. You should see a confirmation message and the Reddit destination will appear in your **Event Destinations** list. </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, the Reddit destination card should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**: * Confirm your **Pixel ID** is correct (typically prefixed with `t2_`, no leading/trailing spaces). * Confirm your **Conversions API token** was pasted in full (no truncation, no whitespace). * Confirm the token was generated for the same ad account as the Pixel ID. * See [How to update your Reddit CAPI token](/guides/reddit-ads/how-to-update-reddit-conversion-api-token) if your token may have been rotated. </Step> </Steps> # How to Remove Duplicate Reddit Pixel Installations in Shopify Source: https://docs.upstackdata.com/guides/reddit-ads/how-to-disable-existing-reddit-pixel-in-shopify Remove duplicate Reddit pixel installations from Shopify Customer Events, theme.liquid, and third-party apps to prevent inflated conversion metrics when activating Upstack Data. <Tip> * Reddit does **not** have a native Shopify sales channel like Meta or TikTok — Reddit pixels on Shopify are typically installed manually. * If multiple Reddit pixels with the same ID are firing, conversions get counted more than once. * Consolidate to a **single** browser pixel installation, then let Upstack handle server-side delivery via CAPI. * Reddit deduplicates the browser pixel and CAPI events automatically using the shared `conversion_id`. </Tip> <Note> **Why this matters** Unlike Meta or TikTok, Shopify does not have a native Reddit sales channel pixel. Brands typically install the Reddit pixel via Shopify Customer Events, theme.liquid edits, third-party apps, or Google Tag Manager. When **multiple** Reddit pixels with the same Pixel ID are firing on the same page, Reddit cannot deduplicate them without a shared `conversion_id`, which results in inflated conversion counts and degraded campaign optimization. Once you activate Upstack's Reddit destination, the Upstack Pixel handles browser-side capture and forwards a deduplicated server-side event to Reddit CAPI. Any **additional** Reddit pixel installations on the same store should be removed. </Note> ## Prerequisites Before you start, you need: * Shopify owner or staff access with **Customize Theme** and **Customer Events** permissions * A list of all your existing Reddit pixel installations (theme code, apps, GTM tags) * Your Reddit Pixel ID — see [How to find your Reddit Pixel ID](/guides/reddit-ads/how-to-find-reddit-pixel-id) ## Common locations to check Reddit pixels can be installed in any of these places. Check each one: | Location | How to access | | -------------------------- | ---------------------------------------------------------------------------------- | | Shopify Customer Events | **Settings → Customer Events** in Shopify admin | | Theme files | **Online Store → Themes → Edit Code** — look in `theme.liquid` and header snippets | | Third-party apps | **Apps** in Shopify admin — search for "Reddit" | | Google Tag Manager | GTM workspace → **Tags** — filter by "Reddit" | | Checkout extension scripts | Plus stores: **Settings → Checkout → Order status page additional scripts** | ## Steps to remove duplicate Reddit pixels <Steps> <Step title="Inventory all current Reddit pixel installations"> Before removing anything, document every place a Reddit pixel is firing: 1. **Customer Events**: Go to Shopify admin → **Settings → Customer Events** and check for any custom pixels referencing `rdt(` or `reddit`. 2. **Theme code**: Open **Online Store → Themes → Edit Code** and search the entire theme for `rdt(` or `redditstatic`. 3. **Apps**: Look for any Reddit-branded apps under **Apps** in the Shopify admin. 4. **GTM**: If you use Google Tag Manager, search for tags with names containing "Reddit" or scripts referencing the Reddit pixel. Make a list of every location and the Pixel ID each one references. </Step> <Step title="Identify the canonical Reddit pixel"> Decide which **single** Reddit pixel installation will remain. Recommended order of preference: 1. **Shopify Customer Events** — most reliable, fires on checkout pages, easiest to maintain. 2. **Theme.liquid** — works for older themes that don't support Customer Events. 3. **Third-party app** — only if the app provides functionality you need beyond pixel firing. All other installations will be removed in the next steps. </Step> <Step title="Remove duplicate Customer Event pixels"> In Shopify admin, go to **Settings → Customer Events**. For each Reddit-related custom pixel that is **not** your canonical installation: 1. Click the pixel to open its details. 2. Click **Disconnect** or **Delete** in the top-right. 3. Confirm the action. <Warning> Disconnecting a custom pixel stops it from firing immediately. There is no undo, so confirm you have a backup of the script if you may need it later. </Warning> </Step> <Step title="Remove Reddit pixel code from theme files"> Open **Online Store → Themes → Edit Code** and search the theme for `rdt(` and `redditstatic`. For any matches that are **not** your canonical installation: 1. Open the file containing the code. 2. Delete the Reddit pixel script block (typically wrapped in `<script>` tags). 3. Save the file. Common files to check: `theme.liquid`, `layout/theme.liquid`, `snippets/header.liquid`, `snippets/google-analytics.liquid`. </Step> <Step title="Uninstall duplicate Reddit pixel apps"> Go to **Apps** in the Shopify admin and locate any Reddit pixel apps that are not your canonical installation. Click **Delete** to uninstall the app. Confirm by reviewing app data deletion in the popup. </Step> <Step title="Remove duplicate GTM Reddit tags"> If you use Google Tag Manager, sign in to your workspace and navigate to **Tags**. Filter for "Reddit" or search for tags referencing `redditstatic.com` or `rdt(`. For each tag that duplicates your canonical pixel: 1. Click the tag to open it. 2. Click the trash icon (top-right) to delete it. 3. **Submit** and **Publish** a new GTM workspace version to deploy the change. </Step> <Step title="Verify only one Reddit pixel is firing"> Open your storefront in a new browser tab with the [Reddit Pixel Helper Chrome extension](https://chromewebstore.google.com/) installed (search "Reddit Pixel Helper" in the Chrome Web Store). Navigate through your store: home page, product page, add-to-cart, and checkout. The Pixel Helper should show **exactly one** pixel firing per event. If you see duplicates, return to the previous steps and remove the additional installation. </Step> <Step title="Activate Upstack's Reddit destination"> Once duplicates are removed, your single browser pixel and Upstack's CAPI integration will work together cleanly. Reddit will deduplicate using the shared `conversion_id`. Confirm the Upstack Reddit destination is **Healthy** in your dashboard. See [How to configure the Reddit destination](/guides/reddit-ads/how-to-configure-reddit-destination-in-upstack-data) if it isn't already set up. </Step> </Steps> <Note> **What if I want Upstack to be the only Reddit data source?** You can also remove **all** browser-side Reddit pixel installations and let Upstack handle 100% of Reddit tracking server-side. This works, but you'll lose real-time pixel signal in Reddit's Events Manager. The recommended setup is to keep one browser pixel and let Upstack add the CAPI layer on top. </Note> # How to Find your Reddit Pixel ID Source: https://docs.upstackdata.com/guides/reddit-ads/how-to-find-reddit-pixel-id Find your Reddit Pixel ID in Reddit Ads Manager Events Manager — required to configure the Upstack Data Reddit destination for server-side conversion forwarding. <Tip> * Sign in to [Reddit Ads Manager](https://ads.reddit.com/) and open the **Events Manager**. * Below **Events Overview**, locate the **Pixel ID** (typically prefixed with `t2_`). * Copy the Pixel ID and paste it into your Upstack Reddit destination configuration. </Tip> <Note> **What is a Reddit Pixel ID?** Your **Reddit Pixel ID** is a unique identifier Upstack Data uses to send conversion data to your Reddit Ads account. Reddit Pixel IDs are typically prefixed with `t2_` (e.g., `t2_abc123def`) and are sometimes referred to as your Account ID inside Reddit's developer documentation. </Note> ## Prerequisites Before you start, you need: * Access to a **Reddit Ads** account at [ads.reddit.com](https://ads.reddit.com/) or [business.reddit.com](https://business.reddit.com/) * A pixel already created in Reddit Ads Manager Events Manager (or follow the create-pixel steps below) ## Steps to find your Reddit Pixel ID <Steps> <Step title="Sign in to Reddit Ads Manager"> Sign in to Reddit Ads Manager at [ads.reddit.com](https://ads.reddit.com/) or [business.reddit.com](https://business.reddit.com/). </Step> <Step title="Open Events Manager"> Click the menu (top-left corner) and select **Ads** → **Events Manager**. Alternatively, click **Events Manager** directly in the left-hand navigation menu. </Step> <Step title="Find or create your pixel"> **If you already have a pixel**, you'll see it under **Events Overview** — proceed to the next step. **If you need to create one:** * Click **Create New Pixel** or **Set Up Pixel** * Follow Reddit's setup wizard to create a new Reddit Pixel * Once created, return to the Events Manager </Step> <Step title="Locate your Pixel ID"> Below **Events Overview** (or under your pixel's settings), locate the **Pixel ID**. **Example format:** `t2_abc123def` The Pixel ID is the same value as your Reddit Account ID and starts with the prefix `t2_`. </Step> <Step title="Copy and paste into Upstack Data"> Copy your Pixel ID and paste it into the **Pixel ID** field in your Upstack Reddit destination setup. <Tip> Ensure there are no extra spaces before or after the ID. The value should include the `t2_` prefix. </Tip> </Step> <Step title="Save the configuration"> Click **Create Configuration** to save the destination. </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, navigate to **Event Destinations**. Your Reddit destination should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**, double-check that the Pixel ID matches exactly what you see in Reddit Ads Manager (correct prefix, no whitespace). </Step> </Steps> <Note> **Next step:** [How to generate your Reddit CAPI token](/guides/reddit-ads/how-to-generate-reddit-conversion-api-token) </Note> # How to Generate your Reddit Conversions API Token Source: https://docs.upstackdata.com/guides/reddit-ads/how-to-generate-reddit-conversion-api-token Generate a Reddit Conversions API access token in Reddit Ads Manager — required to authenticate the Upstack Data Reddit destination and forward server-side conversions via Reddit CAPI. <Tip> * Sign in to [Reddit Ads Manager](https://ads.reddit.com/) and open **Events Manager**. * Click the **Conversions API** tab in the left-hand menu. * Click **+ Generate Access Token**. * Name the token (e.g., "Upstack Data") and click **Generate**. * Copy the token immediately and paste it into your Upstack Reddit destination. </Tip> <Note> **What is a Reddit Conversions API token?** A **Conversions API access token** is a non-expiring secure key that allows Upstack Data to send conversion event data to Reddit's Conversions API. The token can be used by any administrator for any ad account within your business. Reddit recommends using this token over OAuth for Conversions API access. </Note> ## Prerequisites Before you start, you need: * **Admin access** to a **Reddit Ads** account * A pixel already created in [Reddit Ads Manager Events Manager](https://ads.reddit.com/) — see [How to find your Reddit Pixel ID](/guides/reddit-ads/how-to-find-reddit-pixel-id) * An Upstack Data account ready to receive the token ([sign in](https://app.upstackdata.com)) ## Steps to generate your Reddit CAPI token <Steps> <Step title="Sign in to Reddit Ads Manager"> Sign in to Reddit Ads Manager at [ads.reddit.com](https://ads.reddit.com/) or [business.reddit.com](https://business.reddit.com/). </Step> <Step title="Open Events Manager"> Click the menu (top-left corner) and select **Ads** → **Events Manager**. </Step> <Step title="Open the Conversions API settings"> In the left-hand menu of the Events Manager, click the **Conversions API** tab. This opens the Conversions API settings page where access tokens are managed. </Step> <Step title="Generate the access token"> In the **Conversions access token** section, click the **+ Generate Access Token** button. A pop-up window will appear prompting you to name the token. </Step> <Step title="Name your token"> Enter an easily identifiable name for the token (e.g., `Upstack Data` or `Upstack CAPI`). <Tip> A descriptive name makes it easier to identify which integration the token belongs to if you generate multiple tokens for different platforms or environments. </Tip> Click **Generate** to create the token. </Step> <Step title="Copy your CAPI token"> Reddit will display the access token — a string of letters and numbers. <Warning> Copy the token immediately to a secure location. Reddit may not show the full token again after you close the dialog. If lost, you'll need to generate a new one. </Warning> The token is a **non-expiring** secure key, so it does not need to be refreshed periodically. However, you should rotate it if you suspect it has been compromised. </Step> <Step title="Add the token to Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com/pixel/event-destinations) and open your **Reddit** destination under **Event Destinations**. Paste the token into the **Conversions API access token** field. <Warning> The Conversions API token is sensitive — store it securely. Treat it like a password and never expose it in client-side code or share it publicly. </Warning> </Step> <Step title="Verify the destination is healthy"> In the Upstack dashboard, the Reddit destination card should show **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**: * Confirm the token was pasted in full (no truncation, no whitespace). * Confirm the token was generated for the same Reddit Ads account as the Pixel ID. * Confirm the **Pixel ID** matches the pixel you generated the token for. </Step> </Steps> <Note> **Need help with the Pixel ID?** See [How to find your Reddit Pixel ID](/guides/reddit-ads/how-to-find-reddit-pixel-id). </Note> # How to Update your Reddit Conversions API Token Source: https://docs.upstackdata.com/guides/reddit-ads/how-to-update-reddit-conversion-api-token Rotate or update your Reddit Conversions API access token in Upstack Data to keep server-side events flowing into Reddit CAPI without breaking pixel health. <Tip> * Generate a new Reddit CAPI token in [Reddit Ads Manager Events Manager](https://ads.reddit.com/) → **Conversions API**. * Sign in to Upstack Data and open your Reddit destination under **Event Destinations**. * Replace the existing token with the new value and save. * Verify the destination shows **Healthy** within 5 minutes. </Tip> <Note> **When to update the Reddit CAPI token** Reddit Conversions API tokens are **non-expiring**, so they don't need routine rotation. Update the token only when: * The token has been compromised or accidentally exposed * An administrator has revoked the token in Reddit Ads Manager * You're consolidating multiple tokens into a single managed credential * The Upstack Reddit destination shows **Unhealthy** with an authentication error </Note> ## Prerequisites Before you start, you need: * **Admin access** to a **Reddit Ads** account * An Upstack Data account with an existing Reddit destination ([sign in](https://app.upstackdata.com)) ## Steps to update your Reddit CAPI token <Steps> <Step title="Generate a new Reddit CAPI token"> Follow the [generate Reddit CAPI token guide](/guides/reddit-ads/how-to-generate-reddit-conversion-api-token) to create a new access token in Reddit Ads Manager. Use a descriptive name like `Upstack Data (rotated YYYY-MM-DD)` to track when the token was issued. <Warning> Copy the new token immediately — Reddit may not show the full token again after you close the generation dialog. </Warning> </Step> <Step title="Open the Reddit destination in Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com/pixel/event-destinations). Navigate to **Event Destinations** and click your existing **Reddit** destination to open its configuration. </Step> <Step title="Replace the access token"> In the **Conversions API access token** field, clear the existing token and paste the new one. Do not change the **Pixel ID** unless you are also moving to a new pixel — the token must be generated for the ad account that owns the Pixel ID. </Step> <Step title="Save the updated configuration"> Click **Save** or **Update Configuration**. Upstack will validate the new token by sending a test event to Reddit's Conversions API. </Step> <Step title="Verify the destination is healthy"> The Reddit destination card should display **Healthy** with a green status indicator within 5 minutes. If the status shows **Unhealthy**: * Confirm the new token was pasted in full (no truncation, no whitespace). * Confirm the token was generated for the same Reddit Ads account as the Pixel ID. * In Reddit Ads Manager → Events Manager → Conversions API, confirm the token is still listed (not revoked). </Step> <Step title="Revoke the old token (optional)"> Once the new token is verified working, return to Reddit Ads Manager → Events Manager → **Conversions API** and revoke the old token. Revoking the old token prevents accidental future use and reduces the surface area for credential leaks. </Step> </Steps> <Note> **Still seeing issues?** Contact our [support team](/support) with your **Reddit Pixel ID** and we'll help diagnose the problem. </Note> # Complete How-To Guide for Setting Up the Upstack Data App in Shopify Source: https://docs.upstackdata.com/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify This is guide is a step-by-step instructions to installing and setting up the Upstack Data app in Shopify for accurate tracking & reporting. <Info> **New to Upstack?** If you haven't already, [create your Upstack account](/get-started/create-an-account) before continuing. </Info> <Tip> * Sign up for Upstack Data and choose your plan * Connect Shopify from the Upstack dashboard (Data Sources → Shopify) * Enable Theme App Extension * Add Upstack Data Custom Pixel * Set Consent and Privacy Settings for the Upstack Data Custom Pixel * Connect Shopify Customer Events Pixel * Finish setup * Verify events </Tip> ## Overview **Upstack Data** is a first-party data pixel (CAPI) solution that enhances your Facebook (Meta), TikTok Ads, Google Ads, and Klaviyo tracking capabilities, helping you bypass iOS 14+ restrictions and improve your advertising ROAS. ## Prerequisites * Active Upstack Data account ([sign up](https://app.upstackdata.com/signup)) — [see plans and pricing](/billing/plans-and-pricing) * Active Shopify store (`your-store.myshopify.com`) * [Shopify Admin](https://admin.shopify.com) access with permission to install apps and edit themes * Facebook Business Manager account and admin access (for Meta tracking) * Ad account credentials and access for every platform you want to track ## Configuration steps ### Part 1: Connect Shopify from the Upstack dashboard Sign in to [app.upstackdata.com](https://app.upstackdata.com), navigate to **Data Sources → Shopify**, and click **Connect Shopify**. Upstack redirects you to your Shopify Admin to authorize the install. Help guide to complete this step: [How to Install the Upstack Data App in Shopify →](/guides/shopify/how-to-download-and-install-upstack-data-app-in-shopify) ### Part 2: Enable Theme App Extension <Steps> <Step title="Open the theme settings prompt"> After signing in to the Upstack Data app, a modal window will prompt you to **enable** the UpStackified Theme App Extension. Click **Enable UpStackified Theme App Extension**. <img alt="Modal prompt to enable the UpStackified Theme App Extension" /> </Step> <Step title="Enable the Theme App Extension in Shopify Admin"> In Shopify Admin, ensure the **UpStackified Theme App Extension is ENABLED**. Help guide to complete this step: [How to Ensure Upstack Data Theme App Extension is Enabled →](/guides/shopify/how-to-ensure-upstack-data-theme-app-extension-is-enabled) </Step> <Step title="Proceed to onboarding"> Click **Continue** to proceed with the onboarding. </Step> </Steps> ### Part 3: Add Custom Pixel <Steps> <Step title="Open Customer Events in the Upstack Data app"> On the Upstack Data app onboarding page, click **Customer events** and click the **Copy Pixel Code** button to copy the code to your clipboard. <img alt="Copy Pixel Code button in the Upstack Data onboarding page" /> </Step> <Step title="Add a Custom Pixel in Shopify Admin"> In your [Shopify Admin](https://admin.shopify.com), navigate to **Settings → Customer events → Add custom pixel**. <img alt="Shopify Admin Customer events page with Add custom pixel option" /> </Step> <Step title="Name the Custom Pixel"> Set the pixel name to **UpstackData** → click **Add pixel**. <img alt="Naming the custom pixel UpstackData in Shopify Admin" title="Name the custom pixel" /> </Step> </Steps> ### Part 4: Connect Shopify Customer Events Pixel <Steps> <Step title="Set consent and privacy settings"> <Warning> **Upstack Data does not sell any data.** We are a privacy-first solution and committed to adhering to the regulations for each jurisdiction. </Warning> Help guide to complete this step: [Shopify Custom Pixel - Privacy Consent Settings →](/guides/shopify/shopify-custom-pixel-privacy-consent-settings) </Step> <Step title="Paste the Pixel Code"> Paste the **Pixel Code →** click **Save →** click **Connect**. <img alt="Paste pixel code, save, and connect in Shopify Customer events" /> </Step> <Step title="Connect the Custom Pixel"> In the modal popup, click **Connect**. <img alt="Connect button in the Shopify custom pixel confirmation modal" /> </Step> </Steps> ### Part 5: Finish setup In the **Upstack Data app**, click **Continue** → then click **Finish Setup**. <img alt="Finish Setup button in the Upstack Data app onboarding" /> ### Part 6: Verify the installation Confirm everything is wired up correctly before you start running ads: * Place a test order on your store (or wait for a real one). * In the [Upstack dashboard](https://app.upstackdata.com), open **Event Health** and confirm `PageView`, `AddToCart`, `InitiateCheckout`, and `Purchase` events are arriving. * In [Shopify Admin → Settings → Customer events](https://admin.shopify.com), confirm the **UpstackData** Custom Pixel shows status **Connected**. * In [Shopify Admin → Online Store → Themes → Customize → App embeds](https://admin.shopify.com), confirm **UpStackified Pixel** is enabled. <Note> **Need help?** If you encounter any issues during setup, contact our support team and we'll help diagnose the problem. </Note> ## What's next <CardGroup> <Card title="Connect a destination" icon="plug" href="/get-started/connect-a-destination"> Forward events to Meta CAPI, TikTok, Klaviyo, or other ad platforms. </Card> <Card title="Explore the CLI" icon="terminal" href="/cli/install"> Query your data and manage dashboards from the command line or through AI agents. </Card> <Card title="View plans and pricing" icon="credit-card" href="/billing/plans-and-pricing"> See available plans and adjust your subscription as your store scales. </Card> <Card title="Troubleshoot issues" icon="wrench" href="/troubleshooting/pixel-stuck-on-waiting-for-first-events"> Common fixes if events aren't appearing after setup. </Card> </CardGroup> # How to Download and Install Upstack Data App in Shopify Source: https://docs.upstackdata.com/guides/shopify/how-to-download-and-install-upstack-data-app-in-shopify Connect your Shopify store to Upstack from the Upstack dashboard — install the Upstack app and authorize the connection in a few clicks. <Tip> * Sign in to your Upstack Data account * Navigate to **Data Sources → Shopify** * Click **Connect Shopify** * Authorize the app install in Shopify * Return to the Upstack dashboard with Shopify connected </Tip> ## Prerequisites * Active Upstack Data account ([sign up](https://app.upstackdata.com/signup)) * Active Shopify store (`your-store.myshopify.com`) * [Shopify Admin](https://admin.shopify.com) access with permission to install apps ## Configuration steps <Steps> <Step title="Sign in to Upstack Data"> Open [app.upstackdata.com](https://app.upstackdata.com) and sign in with your Upstack account credentials. If you don't have an account yet, [create one first](/get-started/create-an-account). </Step> <Step title="Open the Shopify data source"> In the Upstack dashboard, navigate to **Data Sources → Shopify**. </Step> <Step title="Connect your Shopify store"> Click **Connect Shopify**. Enter your Shopify store URL (`your-store.myshopify.com`) when prompted. Upstack redirects you to your Shopify Admin to authorize the app installation. </Step> <Step title="Approve the app installation in Shopify"> Review the permissions Upstack requests, then click **Install** in your Shopify Admin. Upstack requests read access to your orders, customers, and product catalog for event enrichment. No write permissions are requested. </Step> <Step title="Return to the Upstack dashboard"> After approving the install in Shopify, you're automatically redirected back to the Upstack dashboard. Shopify now appears as a connected data source. </Step> </Steps> ## Verify the install * In the [Upstack dashboard](https://app.upstackdata.com), confirm Shopify is listed under **Data Sources** with a **Connected** status. * In your [Shopify Admin](https://admin.shopify.com), navigate to **Settings → Apps and sales channels** and confirm **Upstack: Site Intelligence** appears in your list of installed apps. ## Next steps <CardGroup> <Card title="Enable the Theme App Extension" icon="toggle-on" href="/guides/shopify/how-to-ensure-upstack-data-theme-app-extension-is-enabled"> Activate the UpStackified theme app extension in your Shopify theme editor. </Card> <Card title="Add the Custom Pixel" icon="code" href="/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify"> Paste the Upstack pixel code into Shopify's Customer Events. </Card> <Card title="Configure privacy settings" icon="shield-halved" href="/guides/shopify/how-to-setup-upstack-custom-pixel-privacy-settings"> Set consent and privacy settings for the Upstack custom pixel. </Card> </CardGroup> <Note> ***Need help on these?*** \*\*[How to Ensure Upstack Data Theme App Extension is Enabled →](/guides/shopify/how-to-ensure-upstack-data-theme-app-extension-is-enabled) [How to Setup Upstack Custom Pixel Privacy Settings →](/guides/shopify/how-to-setup-upstack-custom-pixel-privacy-settings) [Complete How-To Guide on Setting up Upstack Data App in Shopify →](/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify)\*\* </Note> # How to Ensure Upstack Data Theme App Extension is Enabled Source: https://docs.upstackdata.com/guides/shopify/how-to-ensure-upstack-data-theme-app-extension-is-enabled Enable the Upstack Data theme app embed in your Shopify theme editor so the tracking pixel loads on every storefront page and captures events server-side. <Tip> * In Shopify Admin, navigate to **Online Store → Themes → Customize** * Click the **App embeds** icon in the theme customizer * Enable **UpStackified Pixel** and click **Save** * **Verify** with a test purchase </Tip> <Note> For your tracking events to fire correctly in Shopify, you need to ensure the **UpStackified Pixel** Theme App Extension is enabled in your live theme. Once complete, we recommend a test purchase to verify conversion tracking is working properly. </Note> ## Prerequisites * The Upstack Data app installed on your Shopify store (see [How to Download and Install Upstack Data App in Shopify](/guides/shopify/how-to-download-and-install-upstack-data-app-in-shopify)) * [Shopify Admin](https://admin.shopify.com) access with permission to edit themes * Your live theme accessible from **Online Store → Themes** ## Steps to enable Upstack Data Theme App Extension <Steps> <Step title="Sign in to Shopify Admin"> Sign in to your [Shopify Admin](https://admin.shopify.com). <img alt="Shopify Admin login page" /> </Step> <Step title="Open Themes"> In the left sidebar, navigate to **Online Store → Themes**. <img alt="Shopify Admin sidebar with Online Store and Themes selected" /> </Step> <Step title="Open the theme customizer"> On your live theme, click the **Customize** button. <img alt="Shopify Themes page with Customize button on live theme" /> </Step> <Step title="Open App embeds"> In the left sidebar of the theme customizer, click the **App embeds** icon. <img alt="Theme customizer sidebar with App embeds icon highlighted" /> </Step> <Step title="Enable UpStackified Pixel"> In the list, locate **UpStackified Pixel** and toggle the switch to **enable** it. Click **Save** at the top-right of the page to apply the changes. <img alt="UpStackified Pixel toggle in App embeds list" /> <img alt="Save button in theme customizer after enabling UpStackified Pixel" /> </Step> <Step title="Verify activation"> Once enabled, **UpStackified Pixel** will show as active with a green check mark or **Enabled** status. <img alt="UpStackified Pixel showing enabled status with green check mark" /> </Step> <Step title="Verify with a test purchase"> Place a test order on your store, then open the [Upstack dashboard](https://app.upstackdata.com) and confirm a `Purchase` event appears under **Event Health** within a few minutes. If the event does not appear, recheck that the App embed is enabled and saved on your **live** theme (not a draft). </Step> </Steps> ## Related Articles <CardGroup> <Card title="Install the Pixel Helper" href="/guides/shopify/how-to-install-upstack-data-pixel-helper" /> <Card title="Set up custom pixel privacy settings" href="/guides/shopify/how-to-setup-upstack-custom-pixel-privacy-settings" /> <Card title="Pixel stuck on waiting for first events" href="/troubleshooting/pixel-stuck-on-waiting-for-first-events" /> <Card title="Complete Shopify setup guide" href="/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify" /> </CardGroup> # How to Setup Upstack Custom Pixel Privacy Settings Source: https://docs.upstackdata.com/guides/shopify/how-to-setup-upstack-custom-pixel-privacy-settings Configure consent mode and privacy settings on the Upstack Data custom pixel in Shopify — control which events fire for opted-out shoppers while preserving attribution for opted-in shoppers. <Tip> * In Shopify Admin, navigate to **Settings → Customer events** and select your Upstack Data Custom Pixel. * For **Permission**, choose **Not required** — the pixel will always run. * For **Data sale**, choose **Data collected does not qualify as data sale** — the pixel will collect data even when a customer opts out of their data being sold. * Click **Save**. </Tip> ## Prerequisites * The Upstack Data app installed on your Shopify store * The **UpstackData** Custom Pixel already added under **Shopify Admin → Settings → Customer events** (see [Complete How-To Guide for Setting Up the Upstack Data App in Shopify](/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify)) * [Shopify Admin](https://admin.shopify.com) access with permission to manage Customer Events ## Key points to remember When configuring the Upstack Data Custom Pixel in Shopify, several options control consent mode. These settings can have a material impact on your tracking, data quality, and attribution. If you are running cookie consent banners, ensure they are properly configured to get the most accurate data. If **Permission: Required** is set, the Custom Pixel will not load or track user behavior until the consent banner is accepted. <Note> **Privacy regulations vary by jurisdiction.** This does not constitute legal advice. We recommend you consult your legal representative to determine which settings are appropriate for your business. </Note> ## Configuration steps <Steps> <Step title="Sign in to Shopify Admin"> Sign in to your [Shopify Admin](https://admin.shopify.com). </Step> <Step title="Open Customer events"> * In the bottom-left of the page, click **Settings**. * In the settings menu, click **Customer events**. <img alt="Shopify Admin sidebar showing Settings option" /> <img alt="Shopify Settings menu with Customer events option" /> </Step> <Step title="Select the UpstackData Custom Pixel"> From your list of pixels, click the **UpstackData** Custom Pixel. <img alt="Customer events list showing UpstackData custom pixel" /> </Step> <Step title="Configure privacy settings"> For maximum attribution and data quality, set the following: * **Permission:** *Not required* * **Data sale:** *Data collected does not qualify as data sale* Click **Save** to update the Upstack Data Custom Pixel privacy settings. <img alt="Privacy settings with Permission and Data sale options configured" /> <Warning> **Upstack Data does not sell any data.** We are a privacy-first solution and committed to adhering to the regulations for each jurisdiction. </Warning> </Step> <Step title="Verify the settings are saved"> * Refresh the Custom Pixel page in [Shopify Admin](https://admin.shopify.com) and confirm the **Permission** and **Data sale** values match what you selected. * In the [Upstack dashboard](https://app.upstackdata.com), open **Event Health** and confirm events continue to arrive after the change. </Step> </Steps> ## Related Articles <CardGroup> <Card title="Custom pixel privacy consent settings" href="/guides/shopify/shopify-custom-pixel-privacy-consent-settings" /> <Card title="Enable theme app extension" href="/guides/shopify/how-to-ensure-upstack-data-theme-app-extension-is-enabled" /> <Card title="Complete Shopify setup guide" href="/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify" /> <Card title="Events not in dashboard" href="/troubleshooting/events-not-in-dashboard" /> </CardGroup> # Complete How-To Guide for Onboarding Snapchat in Upstack Data Source: https://docs.upstackdata.com/guides/snapchat-ads/complete-how-to-guide-for-onboarding-snapchat-in-upstack-data Onboard Snapchat Ads in Upstack Data — locate your Snapchat Pixel ID, generate the Conversion API access token, configure the destination, and disable Shopify's duplicate Snapchat pixel. <Tip> **Quick Summary** * Locate and copy your **Snapchat Pixel ID** * Generate and copy your **Snapchat Conversion API Token** * Create and **configure the Snapchat destination** in your Upstack dashboard * **Disable Snapchat data sharing** in Shopify </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to your Snapchat Ads account ([Snapchat Ads Manager](https://ads.snapchat.com)) * A Shopify store admin account (only required for the data-sharing step) ## Onboarding Steps <Steps> <Step title="Find and copy your Snapchat Pixel ID"> <Note> A **Snapchat Pixel ID** is a unique identifier for your Snapchat Pixel in the format of a 32-character UUID, for example `00000000-0000-0000-0000-000000000000`. </Note> Help guide to complete this step: [How to Get my Snapchat Pixel ID →](/guides/snapchat-ads/how-to-get-my-snapchat-pixel-id) </Step> <Step title="Generate and copy your Conversion API Token"> <Note> A **Snapchat Conversion API Token** is a long alphanumeric secret (typically 100+ characters) that authorizes Upstack Data to send server-side events on your behalf. </Note> <Warning> Store your token on secure backend servers and do not share it. You will need it when configuring the Snapchat destination in your Upstack dashboard. When generating new tokens, remove old ones as soon as you confirm they are no longer needed. </Warning> Help guide to complete this step: [How to Generate my Snapchat Conversion API Token →](/guides/snapchat-ads/how-to-generate-my-snapchat-conversion-api-token) </Step> <Step title="Create and configure the Snapchat destination in your Upstack dashboard"> Help guide to complete this step: [How to Configure Snapchat Pixel Destination in Upstack Data →](/guides/snapchat-ads/how-to-configure-snapchat-pixel-destination-in-upstack-data) </Step> <Step title="Disable Snapchat data sharing in Shopify"> <Warning> Disabling Snapchat data sharing is crucial to prevent duplicate events, which can distort reporting and attribution. It ensures Snapchat only receives clean, accurate data through Upstack Data for reliable insights and better ad optimization. </Warning> Help guide to complete this step: [How to Disable Snapchat Data Sharing in Shopify →](/guides/snapchat-ads/how-to-disable-snapchat-data-sharing-in-shopify) </Step> <Step title="Verify the Snapchat destination is healthy"> In your [Upstack dashboard](https://app.upstackdata.com/pixel/event-destinations), open **Events Destination** and confirm the **Snapchat** destination shows a **Healthy** status. Then, in [Snapchat Ads Manager](https://ads.snapchat.com), open **Events Manager** for your pixel and confirm events are arriving from your Conversions API integration. </Step> </Steps> <Note> **Need help?** If you encounter any issues during setup or don't see expected improvements after 10 days, contact our support team with your Snapchat Pixel ID and Conversion API Token, and we'll help diagnose the problem. </Note> # How to Configure Snapchat Pixel Destination in Upstack Data Source: https://docs.upstackdata.com/guides/snapchat-ads/how-to-configure-snapchat-pixel-destination-in-upstack-data Configure the Snapchat destination in Upstack Data with your Snapchat Pixel ID and Conversion API access token to forward server-side conversions to Snapchat CAPI. <Tip> **Quick Summary** * In the Upstack dashboard, open **Events Destination** and click **+ New Destination** * Select **Snapchat** from the destination options * Enter your **Snapchat Pixel ID** and **Conversion API Token** * Check the box to **enable Snapchat Conversions API** * Click **Create Configuration** and verify the destination shows as **Healthy** </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to your Snapchat Ads account ([Snapchat Ads Manager](https://ads.snapchat.com)) * Your Snapchat **Pixel ID** ([how to get it](/guides/snapchat-ads/how-to-get-my-snapchat-pixel-id)) * Your Snapchat **Conversion API Token** ([how to generate it](/guides/snapchat-ads/how-to-generate-my-snapchat-conversion-api-token)) ## Configuration Steps <Steps> <Step title="Sign in to your Upstack dashboard"> Sign in to [Upstack Data](https://app.upstackdata.com) and open the [Events Destination](https://app.upstackdata.com/pixel/event-destinations) page. </Step> <Step title="Add a new Snapchat destination"> In the **Events Destination** page, click **+ New Destination** in the top-right of the page. <img alt="Add New Destination" /> In the **Select a Destination** popup, click **Snapchat**, then click **Next**. <img alt="Select Snapchat from destination options in popup" /> </Step> <Step title="Enter your Snapchat credentials"> Fill out the form with the following: 1. **Snapchat Pixel ID** — a 32-character UUID, for example `00000000-0000-0000-0000-000000000000` 2. Check the box **Check to enable sending events via Snapchat Conversions API** 3. **Snapchat Conversion API Token** — the long alphanumeric token (typically 100+ characters) generated in Snapchat Business Manager <Warning> The **Conversions API checkbox must be selected** for server-side tracking to work. </Warning> <img alt="Snapchat destination form with Pixel ID and CAPI token fields" /> <Note> ***Need help finding these?*** **[How to Get my Snapchat Pixel ID →](/guides/snapchat-ads/how-to-get-my-snapchat-pixel-id)** **[How to Generate my Snapchat Conversion API Token →](/guides/snapchat-ads/how-to-generate-my-snapchat-conversion-api-token)** </Note> </Step> <Step title="Create the configuration"> Click the **Create Configuration** button at the bottom of the form. <img alt="Create Configuration button to save Snapchat destination" /> <Note> **Success! 🎉** You should see a confirmation message and the Snapchat destination will appear as **Healthy** in your destinations list. </Note> </Step> <Step title="Verify the destination is sending events"> Back in the [Events Destination](https://app.upstackdata.com/pixel/event-destinations) page, confirm the new **Snapchat** destination shows a **Healthy** status. Then, in [Snapchat Ads Manager](https://ads.snapchat.com), open **Events Manager** for your pixel and confirm events are arriving from your Conversions API integration. New events typically appear within a few minutes after a test purchase or page view. </Step> </Steps> # How to Disable Snapchat Data Sharing in Shopify Source: https://docs.upstackdata.com/guides/snapchat-ads/how-to-disable-snapchat-data-sharing-in-shopify Disable Shopify's Snapchat sales channel data sharing to stop duplicate Snapchat pixel events and let Upstack Data deliver clean server-side conversions to Snapchat CAPI. <Tip> **Quick Summary** * In Shopify admin, open the **Sales channels** section * Select **Snapchat Ads**, then open the **Settings** tab * Open the **Data sharing** tab and find the **Pixel ID** section * Click **Disconnect** to unlink the Snapchat Pixel from Shopify </Tip> <Warning> Disabling Snapchat data sharing is crucial to prevent duplicate events, which can distort reporting and attribution. It ensures Snapchat only receives clean, accurate data through Upstack Data for reliable insights and better ad optimization. </Warning> ## Prerequisites Before you start, you need: * Admin access to your Shopify store ([Shopify admin](https://admin.shopify.com)) * The Snapchat Ads sales channel currently installed in Shopify * A configured Snapchat destination in your [Upstack dashboard](https://app.upstackdata.com/pixel/event-destinations) ([setup guide](/guides/snapchat-ads/how-to-configure-snapchat-pixel-destination-in-upstack-data)) ## Steps to Disable Snapchat Data Sharing in Shopify <Steps> <Step title="Sign in to Shopify admin"> Sign in to [Shopify admin](https://admin.shopify.com) for the store where the Snapchat Ads sales channel is installed. </Step> <Step title="Open the Snapchat Ads sales channel"> In the left-hand menu, click **Sales channels**, then select **Snapchat Ads**. (You can also use the search bar at the top of Shopify admin to locate the Snapchat Ads sales channel.) Make sure you are on the **Settings** tab of the Snapchat Ads sales channel. </Step> <Step title="Open the Data sharing tab"> In the Snapchat Ads settings, click the **Data sharing** tab. Scroll to the **Pixel ID** section and find your connected Snapchat Pixel. <img alt="Snapchat Ads Data sharing tab showing Pixel ID section with Disconnect option" /> </Step> <Step title="Disconnect the Snapchat Pixel from Shopify"> Click **Disconnect** next to the connected Pixel ID to unlink it from Shopify, then confirm the action in the dialog. </Step> <Step title="Verify Snapchat is no longer sharing data through Shopify"> Refresh the **Data sharing** tab and confirm the Pixel ID section no longer shows a connected pixel. Then, in your [Upstack dashboard](https://app.upstackdata.com/pixel/event-destinations), confirm the **Snapchat** destination is still **Healthy** and continuing to send events through Upstack Data. </Step> </Steps> <Note> **Need Help?** If you encounter any issues during setup, contact our support team and we'll help diagnose the problem. </Note> # How to Generate my Snapchat Conversion API Token? Source: https://docs.upstackdata.com/guides/snapchat-ads/how-to-generate-my-snapchat-conversion-api-token Generate a Snapchat Conversion API access token in Snapchat Ads Manager — required to authenticate the Upstack Data Snapchat destination for server-side conversion forwarding. <Tip> **Quick Summary** * Sign in to [Snapchat Business Manager](https://business.snapchat.com) * Open the **Business Details** page * Click **Generate Token** * **Copy and save** the generated **Conversion API Token** immediately (Snapchat only displays it once) * Paste the token into the Snapchat destination form in your Upstack dashboard </Tip> ## What is a Snapchat Conversion API Token? <Note> A **Snapchat Conversion API Token** is a secure credential generated in Snapchat Business Manager that authorizes platforms like Upstack Data to send conversion events directly to Snapchat's Conversions API. It is a long alphanumeric string, typically 100+ characters long. </Note> It enables server-side event tracking to reduce reliance on browser pixels, improves attribution by capturing conversions lost to ad blockers, privacy restrictions, or cookies, and boosts ad performance by providing Snapchat with more complete and reliable conversion data. ## Prerequisites Before you start, you need: * Admin access to your Snapchat Ads account * At least one Snapchat Pixel created ([how to create one](/guides/snapchat-ads/how-to-get-my-snapchat-pixel-id)) * A secure place to store the generated token (Snapchat only displays it once) ## Steps to Generate the Conversion API Token <Steps> <Step title="Sign in to Snapchat Business Manager"> Sign in to [Snapchat Business Manager](https://business.snapchat.com). </Step> <Step title="Open Business Details"> In the left-hand menu, click **Business Details**. <img alt="" /> </Step> <Step title="Generate the Conversion API Token"> On the **Business Details** page, click **Generate Token**. <img alt="" /> **Copy** the generated Conversion API Token immediately. Then paste it into the **Conversion API Token** field when [configuring the Snapchat destination](/guides/snapchat-ads/how-to-configure-snapchat-pixel-destination-in-upstack-data) in your Upstack dashboard. <img alt="" /> <Warning> Snapchat only shows the token once — copy it now and save it to a secure location such as a password manager. Store the token on secure backend servers and do not share it. When generating new tokens, remove old ones as soon as you confirm they are no longer needed. </Warning> </Step> <Step title="Verify the token format"> Confirm the value you copied is a long alphanumeric string (typically 100+ characters) with no extra spaces. You can paste it into the **Conversion API Token** field when configuring the Snapchat destination in your Upstack dashboard. </Step> </Steps> <Note> ***Need help finding this?*** **[How to Get my Snapchat Pixel ID →](/guides/snapchat-ads/how-to-get-my-snapchat-pixel-id)** </Note> # How to Get my Snapchat Pixel ID? Source: https://docs.upstackdata.com/guides/snapchat-ads/how-to-get-my-snapchat-pixel-id Find your Snapchat Pixel ID in Snapchat Ads Manager — required to configure the Upstack Data Snapchat destination and forward server-side conversions to Snapchat CAPI. <Tip> **Quick Summary** * Sign in to [Snapchat Ads Manager](https://ads.snapchat.com) * Open **Events Manager → Pixels** (or **Pixels** in the left-hand menu) * If a pixel exists, copy the **Pixel ID** displayed under the pixel name * If no pixel exists, click **Create Pixel**, name it `Upstack Data`, then **Create** and copy the new Pixel ID * Paste the Pixel ID into the Snapchat destination form in your Upstack dashboard </Tip> ## What is a Snapchat Pixel ID? <Note> A **Snapchat Pixel ID** is a unique identifier assigned to your Snapchat Pixel when you create it in Snapchat Ads Manager. It is a 32-character UUID, for example `00000000-0000-0000-0000-000000000000`. </Note> Its purpose is to: * **Identify your pixel** so Snapchat knows which ad account and campaigns the data belongs to * **Track on-site actions** such as page views, purchases, and sign-ups * **Send event data to Snapchat Ads Manager** for reporting, audience building, and optimization * **Improve targeting and attribution** by connecting user activity on your website with your Snapchat ads ## Prerequisites Before you start, you need: * Admin access to your Snapchat Ads account ([Snapchat Ads Manager](https://ads.snapchat.com)) * Permission to create or view pixels in your ad account ## Steps to Find Your Snapchat Pixel ID <Steps> <Step title="Sign in to Snapchat Ads Manager"> Sign in to [Snapchat Ads Manager](https://ads.snapchat.com), then open **Events Manager → Pixels** (or click **Pixels** in the left-hand menu). <img alt="Snapchat Ads Manager with Events Manager and Pixels menu" /> If you already have a pixel, find the **Pixel ID** for the pixel you want to connect with Upstack Data — it appears beneath the pixel name as a 32-character UUID. <img alt="Snapchat Pixel showing Pixel ID beneath pixel name" /> </Step> <Step title="Create a new pixel (only if you don't have one)"> From the **Pixels** page in Snapchat Ads Manager, click **Create Pixel**. <img alt="Create Pixel button in Snapchat Pixels page" /> <img alt="Create Pixel form with name field" /> Type `Upstack Data` as the pixel name, then click **Create**. <img alt="Pixel name field with Upstack Data entered" /> </Step> <Step title="Copy your Pixel ID"> The **Pixel ID** is displayed beneath the pixel name as a 32-character UUID, for example `00000000-0000-0000-0000-000000000000`. **Copy** the Pixel ID. <img alt="Pixel ID displayed beneath pixel name with copy option" /> <Warning> Keep your Snapchat Pixel ID confidential. It is a unique identifier for your account and can be used to track conversions and user behavior on your website. </Warning> </Step> <Step title="Verify the Pixel ID"> Confirm the value you copied is a 32-character UUID with no extra spaces. You can paste it into the **Snapchat Pixel ID** field when [configuring the Snapchat destination](/guides/snapchat-ads/how-to-configure-snapchat-pixel-destination-in-upstack-data) in your Upstack dashboard. </Step> </Steps> <Note> ***Need help finding this?*** **[How to Generate my Snapchat Conversion API Token →](/guides/snapchat-ads/how-to-generate-my-snapchat-conversion-api-token)** </Note> # Complete How-To Guide for Onboarding TikTok Ads in Upstack Data Source: https://docs.upstackdata.com/guides/tiktok-ads/complete-how-to-guide-for-onboarding-tiktok-ads-in-upstack-data Onboard TikTok Ads in Upstack Data — locate your TikTok Pixel ID, generate the API access token, configure the destination, and disable Shopify's duplicate TikTok sales channel pixel. <Info> **New to Upstack?** Follow the [getting started guide](/get-started/install-on-shopify) for a streamlined onboarding walkthrough. </Info> <Tip> **Quick Summary** * Create and configure the **TikTok Ads destination** in the Upstack dashboard with browser Pixel and Conversions API (CAPI). * **Disable TikTok Sales Channel data sharing in Shopify** to prevent duplicate events. * **Monitor** Event Match Quality improvements over 7–10 days. * Expect a **1–2 point increase** on upper-funnel events. * **Ignore "Update Recommended"** warnings — they are normal and require no action. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to your **TikTok Business Center** * A **TikTok Pixel** configured in TikTok Events Manager (or follow [How to Create New TikTok Ads Pixel ID →](/guides/tiktok-ads/how-to-create-new-tiktok-ads-pixel-id) first) * Admin access to your **Shopify** store (to disable the TikTok Sales Channel data sharing) <Steps> <Step title="Create and Configure TikTok Ads Pixel Destination in Upstack Data"> <Note> **Purpose:** Enable Upstack Data to send data via browser pixel and CAPI to TikTok Ads for improved tracking accuracy. </Note> Help guide to complete this step: [How to Configure TikTok Ads Pixel Destination in Upstack Data →](/guides/tiktok-ads/how-to-configure-tiktok-ads-pixel-destination-in-upstack-data) </Step> <Step title="Disable TikTok Sales Channel Data Sharing in Shopify"> <Warning> You must disable all other TikTok Ads Pixels/Integrations to prevent duplicate conversions and events. </Warning> Help guide to complete this step: [How to Disable TikTok Data Sharing in Shopify →](/guides/tiktok-ads/how-to-disable-tiktok-data-sharing-in-shopify) </Step> </Steps> ## What to Expect After Setup ### Event Match Quality Timeline * **Days 1-3: Initial Improvement** * Event Match Quality scores begin improving * Data starts flowing through both pixel and CAPI * **Days 7-10: Normalization** * Scores stabilize at improved levels * Full benefit of dual tracking realized ### Expected Score Improvements * **Upper/Mid-Funnel Events (1-2 point increase typical):** * **Page View** - Better user matching * **View Content** - Improved product tracking * **Add to Cart** - Enhanced cart data * **Purchase Event:** * **No change expected** - Already optimized since all customer data (email, name, address) is sent at purchase ### Normal Warnings **"Update Recommended" Notifications** * You may see warnings in TikTok Events Manager showing **"Update Recommended"** next to events. <Note> **This is NORMAL and NO ACTION is needed.** These appear because: * TikTok detects configuration changes * The system recognizes new data sources * The integration method has changed </Note> ## Verify the Setup After completing both steps: * In the Upstack dashboard, navigate to **Events Destination** at [app.upstackdata.com/pixel/event-destinations](https://app.upstackdata.com/pixel/event-destinations) and confirm the TikTok destination shows as **Healthy**. * In [TikTok Events Manager](https://ads.tiktok.com/i18n/events_manager/home), open your **UpstackData** Pixel and confirm events are arriving via both **Browser** and **Server (CAPI)**. * Place a test order on your store and confirm the **Purchase** event appears in TikTok Events Manager within a few minutes. If the destination shows **Unhealthy** or events do not arrive, double-check the **Pixel ID** and **Access Token** values, then contact Upstack Data support if issues persist. # How to Configure TikTok Ads Pixel Destination in Upstack Data Source: https://docs.upstackdata.com/guides/tiktok-ads/how-to-configure-tiktok-ads-pixel-destination-in-upstack-data Configure the TikTok Ads destination in Upstack Data with your Pixel ID and API access token to enable dual tracking via browser pixel and server-side Events API for higher match quality. <Tip> **Quick Summary** * Sign in to the Upstack dashboard and click **"+ New Destination"**. * Select **TikTok** from the destination options. * Enter your **TikTok Pixel ID** and **Access Token**. * Check the **"Check to enable sending events via TikTok Conversions API"** box for server-side tracking. * Click **Create Configuration** to activate the integration. </Tip> ## Prerequisites Before you start, you need: * An active Upstack Data account ([sign up](https://app.upstackdata.com)) * Admin access to your **TikTok Business Center** * A **TikTok Pixel** configured under **Events Manager → Data sources** (see [How to Create New TikTok Ads Pixel ID →](/guides/tiktok-ads/how-to-create-new-tiktok-ads-pixel-id)) * Your **TikTok Pixel ID** ([How to Find your TikTok Ads Pixel ID →](/guides/tiktok-ads/how-to-find-your-tiktok-ads-pixel-id)) * A generated **Access Token** ([How to Generate Your TikTok API Access Token →](/guides/tiktok-ads/how-to-generate-your-tiktok-api-access-token)) ## Configuration Steps <Steps> <Step title="Sign in to Upstack Data"> Sign in to Upstack Data at [app.upstackdata.com](https://app.upstackdata.com). </Step> <Step title="Add a new TikTok destination"> * In the Upstack dashboard, navigate to **Events Destination** ([app.upstackdata.com/pixel/event-destinations](https://app.upstackdata.com/pixel/event-destinations)) * Click **"+ New Destination"** in the top-right corner of the page <img alt="Add New Destination" /> * In the **Select a Destination** popup, click **"TikTok"** * Click **Next** <img alt="Select Tiktok Ads destination" /> </Step> <Step title="Enter your Pixel ID and Access Token"> Fill in the form fields: 1. **TikTok Pixel ID** — 20-character alphanumeric string (e.g., `C2A3B4C5D6E7F8G9H0I1`). Also called the Dataset ID. 2. Check the box **"Check to enable sending events via TikTok Conversions API"** 3. **Access Token** — long alphanumeric string starting with letters/numbers, generated from TikTok Events Manager <Warning> The Conversions API checkbox **must be selected** for server-side tracking to work. </Warning> <img alt="TikTok destination form with Pixel ID and Access Token fields" /> <Note> ***Need help finding these?*** **[How to Find your TikTok Ads Pixel ID →](/guides/tiktok-ads/how-to-find-your-tiktok-ads-pixel-id)** **[How to Generate Your TikTok API Access Token →](/guides/tiktok-ads/how-to-generate-your-tiktok-api-access-token)** </Note> </Step> <Step title="Create the configuration"> Click the **Create Configuration** button. <img alt="Create Configuration button to save TikTok destination" /> <Note> **Success! 🎉** You should see a confirmation message and the TikTok destination will appear as **"Healthy"** in your destinations list. </Note> </Step> </Steps> ## Verify the Setup To confirm the destination is working: * In the Upstack dashboard, the TikTok destination should show **Healthy** status under **Events Destination**. * In [TikTok Events Manager](https://ads.tiktok.com/i18n/events_manager/home), open your Pixel and confirm events are arriving via both **Browser** and **Server (CAPI)**. * Place a test order on your store and check that the **Purchase** event appears in TikTok Events Manager within a few minutes. If the destination shows **Unhealthy** or no events arrive, double-check that: * The **Pixel ID** is exactly 20 characters with no spaces. * The **Access Token** was copied immediately after generation (TikTok shows it only once) and contains no leading or trailing spaces. * The Conversions API checkbox is selected. If issues persist, contact Upstack Data support. # How to Create New TikTok Ads Pixel ID Source: https://docs.upstackdata.com/guides/tiktok-ads/how-to-create-new-tiktok-ads-pixel-id Create a new TikTok Ads Pixel ID in TikTok Ads Manager to track website conversions, measure ad performance, and feed Upstack Data's TikTok Events API destination. <Tip> **Quick Summary** * In TikTok Events Manager, click **"+ Connect data source"**. * Select **Web** as the data source type. * Name your Pixel **"UpstackData"**. * Enter your website URL and complete setup. </Tip> ## Prerequisites Before you start, you need: * Admin access to your **TikTok Business Center** * A **TikTok Ads Manager** account linked to your Business Center * The URL of the website where the Pixel will be installed ## Pixel Creation Process <Steps> <Step title="Sign in to TikTok Events Manager"> * Sign in to [TikTok Events Manager](https://ads.tiktok.com/i18n/events_manager/home) * In the top navigation, click **Tools → Events** <img alt="TikTok Ads Manager with Tools and Events menu options" /> </Step> <Step title="Start creating a new Pixel"> * In TikTok Events Manager, click **"+ Connect data source"** in the upper-left corner of the page (or the **Connect Data Sources** button in the center of the screen if no data sources exist yet) * Select **Web** and click **Next** <img alt="Connect data source button in TikTok Events Manager" /> <img alt="Select Web as data source type" /> </Step> <Step title="Name your Pixel"> * Set the Pixel name to **"UpstackData"** * Click **Create** <img alt="Pixel name field with UpstackData entered" /> </Step> <Step title="Add your website"> * Enter your business website URL * Click **Next** <img alt="Website URL input field for TikTok Pixel setup" /> </Step> <Step title="Finish the Pixel setup"> * Choose an installation method (partner integration or manual code) * Configure tracking events * Install the Pixel code on your website * Verify the Pixel code using TikTok's Pixel Helper or TikTok Events Manager * When everything is confirmed, click **Finish** to complete setup <img alt="Finish button to complete TikTok Pixel setup" /> <Note> Your new TikTok Pixel is ready to integrate with Upstack Data. </Note> </Step> </Steps> ## Verify the Setup To confirm the Pixel was created: * In TikTok Events Manager, navigate to **Tools → Events → Data sources** — your **UpstackData** Pixel should appear in the list. * Open the Pixel and confirm it has a **Pixel ID** (a 20-character alphanumeric string, e.g., `C2A3B4C5D6E7F8G9H0I1`). Next steps: * [How to Find your TikTok Ads Pixel ID →](/guides/tiktok-ads/how-to-find-your-tiktok-ads-pixel-id) * [How to Generate Your TikTok API Access Token →](/guides/tiktok-ads/how-to-generate-your-tiktok-api-access-token) If the Pixel does not appear after creation, refresh the page or contact Upstack Data support. # How to Disable TikTok Data Sharing in Shopify Source: https://docs.upstackdata.com/guides/tiktok-ads/how-to-disable-tiktok-data-sharing-in-shopify Disable Shopify's TikTok sales channel pixel to stop duplicate TikTok conversion events and let Upstack Data deliver clean server-side conversions to TikTok Events API. <Tip> **Quick Summary** * Sign in to your Shopify admin and open the **Sales channels** menu. * Open the **TikTok** sales channel and click **Settings**. * In **Data sharing → Customer Data Sharing**, click **Disconnect** on the connected TikTok Pixel. * Confirm the disconnection in the popup. </Tip> ## Prerequisites Before you start, you need: * Admin access to your **Shopify** store * The **TikTok** sales channel installed in Shopify with an active TikTok Pixel connection * Your Upstack Data TikTok destination already configured ([How to Configure TikTok Ads Pixel Destination in Upstack Data →](/guides/tiktok-ads/how-to-configure-tiktok-ads-pixel-destination-in-upstack-data)) <Warning> Duplicate TikTok events typically occur when multiple TikTok Pixel integrations are active on your site. You must disable TikTok Sales Channel data sharing and ensure no other TikTok Pixel apps are installed. </Warning> ## Steps to Disable TikTok Data Sharing in Shopify <Steps> <Step title="Sign in to Shopify"> Sign in to your [Shopify admin](https://admin.shopify.com/). </Step> <Step title="Open the TikTok sales channel settings"> * In the Shopify admin sidebar, click **Sales channels** * Select **TikTok**, then click the **Settings** tab *Tip: You can also use the Shopify admin search to locate the TikTok sales channel.* <img alt="Shopify sidebar with TikTok Sales Channel Settings" /> <img alt="TikTok sales channel Settings tab in Shopify admin" /> </Step> <Step title="Open Data sharing"> In the TikTok sales channel settings, click the **Data sharing** tab in the left-hand menu. <img alt="Share Data section with Disconnect button" /> </Step> <Step title="Disconnect the TikTok Pixel"> * Scroll to the **Customer Data Sharing** section and locate your connected TikTok Pixel * Click the **Disconnect** button <img alt="Customer Data Sharing section showing connected TikTok Pixel with Disconnect button" /> </Step> <Step title="Confirm the disconnection"> * A confirmation window appears explaining how disconnecting the Pixel affects tracking * Click **Disconnect** again in the lower-right corner to confirm <img alt="Disconnect confirmation popup for TikTok Pixel" /> </Step> </Steps> ## Verify the Setup To confirm data sharing is disabled: * Return to **Sales channels → TikTok → Settings → Data sharing** in Shopify and confirm the **Customer Data Sharing** section no longer shows a connected Pixel. * Place a test order on your store and check [TikTok Events Manager](https://ads.tiktok.com/i18n/events_manager/home) — you should see exactly **one** Purchase event arriving from your Upstack Data integration (not duplicates). If duplicate events continue: * Check the Shopify **Apps** menu for any other TikTok Pixel apps and remove them. * Inspect your theme for hard-coded TikTok Pixel snippets and remove them. <Note> **Need help?** If you encounter any issues, contact our support team and we'll help diagnose the problem. </Note> # How to Find your TikTok Ads Pixel ID Source: https://docs.upstackdata.com/guides/tiktok-ads/how-to-find-your-tiktok-ads-pixel-id Find your TikTok Ads Pixel ID in TikTok Ads Manager — required to configure the Upstack Data TikTok destination for server-side conversion forwarding via TikTok Events API. <Tip> **Quick Summary** * Sign in to TikTok Events Manager. * Open **Data sources** and select your **UpstackData** Pixel. * Copy the **Pixel ID** displayed on the Pixel overview page (a 20-character alphanumeric string). </Tip> ## Prerequisites Before you start, you need: * Admin access to your **TikTok Business Center** * A **TikTok Pixel** already created (see [How to Create New TikTok Ads Pixel ID →](/guides/tiktok-ads/how-to-create-new-tiktok-ads-pixel-id) if you haven't created one yet) ## What is a TikTok Pixel ID? <Note> A **TikTok Pixel ID** is a unique identifier automatically assigned to your TikTok Pixel when you create it in TikTok Events Manager. </Note> Its purpose is to: * **Identify your Pixel** and connect it to the correct TikTok ad account and campaigns * **Track user actions on your website** such as views, clicks, sign-ups, and purchases * **Send event data back to TikTok Events Manager** for reporting, audience creation, and optimization * **Improve attribution and targeting** by linking website activity to your TikTok ads ## Configuration Steps <Steps> <Step title="Sign in to TikTok Events Manager"> * Sign in to [TikTok Events Manager](https://ads.tiktok.com/i18n/events_manager/home) * In the top navigation, click **Tools → Events** <img alt="TikTok Ads Manager with Tools and Events menu options" /> </Step> <Step title="Open your UpstackData Pixel"> * In TikTok Events Manager, click **Data sources** in the left-hand menu * Find your **UpstackData** Pixel in the list and click its name to open the Pixel overview page <img alt="TikTok Events Manager Data sources menu in left sidebar" /> <img alt="UpstackData Pixel listed in TikTok Data sources" /> <Note> **Note:** If you haven't created a Pixel yet, see [How to Create New TikTok Ads Pixel ID →](/guides/tiktok-ads/how-to-create-new-tiktok-ads-pixel-id) first. </Note> </Step> <Step title="Copy your Pixel ID"> * On the Pixel overview page, locate the **Pixel ID** at the top of the page (next to the Pixel name) * Click the copy icon to copy the **Pixel ID** to your clipboard * Paste it into the **TikTok Pixel ID** field in the Upstack dashboard at [app.upstackdata.com/pixel/event-destinations](https://app.upstackdata.com/pixel/event-destinations) <img alt="TikTok Pixel overview page showing Pixel ID with copy button" /> <Note> **Format:** The Pixel ID is a 20-character alphanumeric string (e.g., `C2A3B4C5D6E7F8G9H0I1`). </Note> </Step> </Steps> ## Verify the Setup To confirm you copied the correct value: * The **Pixel ID** should be exactly 20 characters with no spaces. * In the Upstack dashboard, after saving the destination it should show as **Healthy** under **Events Destination**. <Note> **Next step:** [How to Generate Your TikTok API Access Token →](/guides/tiktok-ads/how-to-generate-your-tiktok-api-access-token) </Note> # How to Generate Your TikTok API Access Token Source: https://docs.upstackdata.com/guides/tiktok-ads/how-to-generate-your-tiktok-api-access-token Generate a TikTok Events API access token in TikTok Ads Manager — required to authenticate the Upstack Data TikTok destination and sync server-side conversions and ads data. <Tip> **Quick Summary** * Sign in to TikTok Events Manager. * Open **Data sources** and select your **UpstackData** Pixel. * Open the **Settings** tab and scroll to **Events API**. * Click **"Generate access token"**. * Copy the **Access Token** immediately — it is shown only once. </Tip> ## Prerequisites Before you start, you need: * Admin access to your **TikTok Business Center** * A **TikTok Pixel** already created (see [How to Create New TikTok Ads Pixel ID →](/guides/tiktok-ads/how-to-create-new-tiktok-ads-pixel-id)) * Permission to manage Events API settings on the Pixel ## What is a TikTok Access Token? <Note> A **TikTok Access Token** is a secure credential that lets platforms like Upstack Data connect to your TikTok Ads account to sync performance data, enable server-side tracking via the Conversions API (CAPI), and improve attribution and optimization. </Note> ## Configuration Steps <Steps> <Step title="Sign in to TikTok Events Manager"> * Sign in to [TikTok Events Manager](https://ads.tiktok.com/i18n/events_manager/home) * In the top navigation, click **Tools → Events**, then open **Data sources** * Click your **UpstackData** Pixel to open its overview page <img alt="TikTok Events Manager showing Data sources with UpstackData Pixel" /> <Note> **Note:** If you haven't created a Pixel yet, see [How to Create New TikTok Ads Pixel ID →](/guides/tiktok-ads/how-to-create-new-tiktok-ads-pixel-id) first. </Note> </Step> <Step title="Open the Settings tab"> On the Pixel overview page, click the **Settings** tab. <img alt="TikTok Pixel Settings tab in the overview page" /> </Step> <Step title="Generate the Access Token"> On the **Settings** tab: * Scroll down to the **Events API** section * Click the **"Generate access token"** button <img alt="Events API section with Generate access token button" /> </Step> <Step title="Copy your Access Token"> * Click the copy icon next to the generated **Access Token** — it is a long alphanumeric string starting with letters/numbers * Paste it into the **Access Token** field in the Upstack dashboard at [app.upstackdata.com/pixel/event-destinations](https://app.upstackdata.com/pixel/event-destinations) <img alt="Generated TikTok access token with copy button" /> <Warning> The Access Token is shown **only once**. Copy and store it securely immediately. If you lose it, you'll need to generate a new one. </Warning> </Step> </Steps> ## Verify the Setup To confirm the Access Token works: * In the Upstack dashboard, after saving your TikTok destination it should show as **Healthy** under **Events Destination**. * In TikTok Events Manager, return to the Pixel **Settings → Events API** section — the token should be listed as active. If the destination is **Unhealthy**: * Re-check that the **Access Token** was pasted with no leading or trailing spaces. * Confirm the **Pixel ID** matches the Pixel that owns the token. * Generate a new token if needed and update it in the Upstack dashboard. <Note> **Need to find your Pixel ID?** See [How to Find your TikTok Ads Pixel ID →](/guides/tiktok-ads/how-to-find-your-tiktok-ads-pixel-id). </Note> # Headless Shopify installation Source: https://docs.upstackdata.com/installation/headless-shopify Install the Upstack tracking script on headless Shopify storefronts (Hydrogen, Next.js, custom builds) using the JavaScript SDK. If your storefront runs on Shopify Hydrogen, Next.js, Remix, or any other custom front end, the standard Shopify Theme App Extension won't load — there's no Liquid theme to inject into. Instead, install the Upstack JavaScript SDK directly in your storefront code. <Note> Server-side events (orders, refunds, fulfillment updates) are still captured automatically through Shopify webhooks regardless of your storefront architecture. This page only covers browser-side event tracking. </Note> ## Prerequisites * The Upstack Data app installed in your [Shopify Admin](https://admin.shopify.com) (so server-side webhooks are configured) * An [Upstack Data](https://app.upstackdata.com) account with subscription active * Your Upstack Pixel ID (UUID format: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`, e.g., `58284d43-85f6-41fb-b2e0-f32f8ecb4e9b`). See [How to find my Upstack Data Pixel ID](/resources/how-to-find-my-upstack-data-pixel-id) * Edit access to the headless storefront codebase (Hydrogen, Next.js, Remix, Nuxt, or other framework) * Ability to deploy changes to your storefront (CI/CD or manual deploy access) ## When to Use This Page Use the headless installation if any of the following are true: * Your storefront is built on **Shopify Hydrogen**, **Next.js**, **Remix**, **Nuxt**, or another custom framework * You serve checkout through Shopify but render product, collection, and cart pages from your own front end * You don't have a standard Liquid theme where the Shopify Theme App Extension can be enabled If your storefront uses a standard Shopify theme, follow the [standard Shopify installation guide](/get-started/install-on-shopify) instead — the Theme App Extension handles everything automatically. ## Installation Choose one of the two installation methods below depending on your storefront's build system. ### Option 1: CDN Script Tag The simplest approach is to load the Upstack pixel from our CDN. Add the following tag to the `<head>` of every page that should track events: ```html theme={null} <script src="https://cdn.upstackdata.com/pixel.js" data-pixel-id="YOUR_PIXEL_ID" async></script> ``` Replace `YOUR_PIXEL_ID` with the Pixel ID found in the [Upstack dashboard](https://app.upstackdata.com) under **Settings → Event Health** (UUID format: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`). See [How to find my Upstack Data Pixel ID](/resources/how-to-find-my-upstack-data-pixel-id) for step-by-step instructions. The `async` attribute prevents the pixel from blocking page rendering. Once loaded, the pixel automatically captures page views and listens for cart and checkout events through the Shopify Storefront API. ### Option 2: NPM Package For tighter integration with your front end framework — including programmatic event tracking and SSR support — install the Upstack npm package: ```bash theme={null} npm install @upstackdata/pixel ``` Then initialize the pixel in your storefront's entry point: ```javascript theme={null} import { Upstack } from '@upstackdata/pixel'; const upstack = new Upstack({ pixelId: 'YOUR_PIXEL_ID' }); upstack.page(); ``` Call `upstack.page()` on every route change to register a page view. For cart and checkout events, see the SDK reference for the full event API. <Tip> In framework-specific environments like Hydrogen or Next.js, initialize the pixel in your root layout or `_app` component so it's only created once per session. </Tip> ## Server-Side Events Continue to Flow Headless installation only affects browser-side tracking. Server-side events from Shopify — orders placed, orders refunded, products updated, customer changes — continue to reach Upstack through Shopify webhooks regardless of your storefront architecture. As long as the Upstack Shopify app is installed in your Shopify admin, these webhooks are configured automatically. This means your conversion data, revenue, and order-level attribution will still flow into Upstack even if you skip the browser pixel entirely. Browser tracking adds page views, product views, and pre-checkout cart events on top of the server-side baseline. ## Verify the Install Once the pixel is loaded on your storefront: 1. Open your storefront in a browser and navigate between pages. 2. Use the [Upstack Data Pixel Helper](/guides/shopify/how-to-install-upstack-data-pixel-helper) to confirm the pixel fires with your Pixel ID. 3. Open the [Upstack dashboard](https://app.upstackdata.com) and go to **Sources → Shopify**. 4. Confirm `PageView` events arrive within 1–2 minutes of activity. For more thorough event verification, see [Verify events are flowing](/get-started/verify-events). ## Related <CardGroup> <Card title="Standard Shopify install" icon="shopify" href="/get-started/install-on-shopify"> The default install path for storefronts that use a Shopify theme. </Card> <Card title="Shopify source" icon="arrow-right-to-bracket" href="/sources/shopify"> How the Shopify source ingests events through the pixel and webhooks. </Card> <Card title="Shopify webhooks" icon="webhook" href="/sources/shopify-webhooks"> Server-side events that capture automatically regardless of storefront architecture. </Card> <Card title="Verify events" icon="circle-check" href="/get-started/verify-events"> Confirm events are flowing from your storefront into Upstack. </Card> </CardGroup> # Upstack Data Documentation Source: https://docs.upstackdata.com/overview Set up Upstack Data and start sending high-quality conversion data to your ad platforms. # Get started Create an account and start sending high-quality conversion data to your marketing platforms. ## Common use cases <StripeCardGroup> <StripeCard title="Improve Meta CAPI match quality" description="Boost Event Match Quality scores by sending identity-enriched server-side events." href="/use-cases/improve-meta-match-quality" /> <StripeCard title="Track Shopify events server-side" description="Capture every storefront interaction server-side, immune to ad blockers and cookie restrictions." href="/use-cases/track-server-side-events" /> <StripeCard title="Send conversions to multiple platforms" description="Forward purchase and conversion events to Meta, TikTok, Klaviyo, and GA4 simultaneously." href="/use-cases/send-to-multiple-platforms" /> <StripeCard title="Resolve anonymous visitors to customers" description="Match anonymous sessions to known customers using deterministic and probabilistic identity signals." href="/use-cases/resolve-visitor-identities" /> <StripeCard title="Recover abandoned carts via Klaviyo" description="Trigger abandoned cart flows in Klaviyo with identity-resolved customer data." href="/use-cases/recover-abandoned-carts" /> <StripeCard title="See which campaigns drive purchases" description="Attribute revenue to marketing touchpoints with multi-touch attribution models." href="/analytics/attribution-reporting" /> </StripeCardGroup> ## Platform guides Detailed, step-by-step onboarding guides for each ad platform and integration. Start with the master onboarding hub or jump directly to a specific platform. <StripeCardGroup> <StripeCard title="Complete onboarding guide" description="Master hub covering the full Upstack Data onboarding process from start to finish." href="/guides/getting-started/complete-upstack-data-onboarding-guide" /> <StripeCard title="Facebook (Meta) onboarding" description="Set up Meta CAPI, disable duplicate pixels, and configure NC-ROAS metrics." href="/guides/facebook-ads/complete-how-to-guide-for-onboarding-facebook-meta-in-upstack-data" /> <StripeCard title="Google Ads onboarding" description="Create purchase goals, configure Enhanced Conversions, and connect Google Ads." href="/guides/google-ads/complete-how-to-guide-for-onboarding-google-ads-in-upstack-data" /> <StripeCard title="TikTok Ads onboarding" description="Set up TikTok CAPI and browser pixel with Upstack Data for improved match quality." href="/guides/tiktok-ads/complete-how-to-guide-for-onboarding-tiktok-ads-in-upstack-data" /> <StripeCard title="Klaviyo onboarding" description="Integrate Klaviyo for enhanced email tracking and 40%+ better abandonment capture." href="/guides/klaviyo/complete-how-to-guide-for-onboarding-klaviyo-in-upstack-data" /> <StripeCard title="Shopify app setup" description="Complete guide for installing and configuring the Upstack Data app in Shopify." href="/guides/shopify/complete-how-to-guide-for-setting-up-the-upstack-data-app-in-shopify" /> </StripeCardGroup> ## Start building <StripeCardGroup> <StripeCard title="Install Upstack on Shopify" description="Go from zero to live events in under 10 minutes." href="/get-started/install-on-shopify" /> <StripeCard title="Connect your first destination" description="Forward enriched events to Meta CAPI, TikTok, or another platform." href="/get-started/connect-a-destination" /> <StripeCard title="Verify events are flowing" description="Confirm events appear in your dashboard and reach destinations." href="/get-started/verify-events" /> <StripeCard title="Explore the event model" description="Understand the 13 standard events Upstack tracks automatically." href="/pixel/events/taxonomy" /> <StripeCard title="Set up identity resolution" description="Learn how Upstack ID matches visitors to customers." href="/pixel/identity-resolution" /> <StripeCard title="Browse all integrations" description="See every source and destination Upstack supports." href="/sources/overview" /> </StripeCardGroup> ## Query and automate <StripeCardGroup> <StripeCard title="Analytics query guide" description="Build custom reports with measures and dimensions in the dashboard." href="/analytics/query-guide" /> <StripeCard title="Install the CLI" description="Query data and manage dashboards from the command line." href="/cli/install" /> <StripeCard title="API reference" description="Programmatic access to query, catalog, and dashboard endpoints." href="/api-reference/overview" /> </StripeCardGroup> # add_payment_info Event Source: https://docs.upstackdata.com/pixel/events/add-payment-info Track when a customer enters payment details during checkout Fires when a customer enters payment details during checkout. This is the last step before purchase and indicates very high purchase intent. <Note> **Shopify:** Automatically tracked when customers complete the payment step in checkout. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'add_payment_info', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2 } ], value: 84.97, currency: 'USD', paymentType: 'credit_card' }); ``` ## Properties | Property | Type | Required | Description | | ----------- | ------ | -------- | ---------------------------------------------------------------- | | items | array | No | Products in checkout | | value | number | No | Cart value at payment step | | currency | string | No | ISO 4217 currency code | | paymentType | string | No | Payment method (e.g., `'credit_card'`, `'paypal'`, `'shop_pay'`) | ## When to Fire * Payment form completion * Payment method selection * Before final order submission ## Related Events * [add\_shipping\_info](/pixel/events/add-shipping-info) — Previous checkout step * [purchase](/pixel/events/purchase) — When order is completed # add_shipping_info Event Source: https://docs.upstackdata.com/pixel/events/add-shipping-info Track when a customer enters shipping details during checkout Fires when a customer enters shipping details during checkout. This helps track checkout progress and identify where customers drop off. <Note> **Shopify:** Automatically tracked when customers complete the shipping step in checkout. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'add_shipping_info', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2 } ], value: 84.97, currency: 'USD', shippingTier: 'standard' }); ``` ## Properties | Property | Type | Required | Description | | ------------ | ------ | -------- | ---------------------------------------------------------------- | | items | array | No | Products in checkout | | value | number | No | Cart value at shipping step | | currency | string | No | ISO 4217 currency code | | shippingTier | string | No | Shipping method (e.g., `'standard'`, `'express'`, `'overnight'`) | ## When to Fire * Shipping form completion * Shipping method selection * Proceeding past shipping step ## Related Events * [initiate\_checkout](/pixel/events/initiate-checkout) — Starting checkout * [select\_shipping\_method](/pixel/events/select-shipping-method) — When selecting specific shipping option * [add\_payment\_info](/pixel/events/add-payment-info) — After entering payment details # add_to_cart Event Source: https://docs.upstackdata.com/pixel/events/add-to-cart Track when a visitor adds an item to their cart Fires when a visitor adds an item to their cart. This is one of the most important e-commerce events for tracking purchase intent and building audiences. <Note> **Shopify:** Automatically tracked when using standard Shopify cart functionality. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'add_to_cart', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2, variant: 'Blue / Medium', brand: 'Example Brand', category: 'Apparel/T-Shirts' } ], value: 69.98, currency: 'USD' }); ``` Minimal example: ```javascript theme={null} window._upstack('track', 'add_to_cart', { items: [{ id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 1 }], value: 34.99, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | ---------------------------------------------------------------------- | | items | array | Yes | Products added (see [Item Object](/pixel/standard-events#item-object)) | | value | number | Yes | Total value of items added | | currency | string | Yes | ISO 4217 currency code | ## When to Fire * Add-to-cart button click * Quantity increase in cart * "Buy Now" button click (before checkout) ## Related Events * [view\_content](/pixel/events/view-content) — View product before adding * [product\_removed\_from\_cart](/pixel/events/product-removed-from-cart) — When removing from cart * [view\_cart](/pixel/events/view-cart) — When viewing cart * [initiate\_checkout](/pixel/events/initiate-checkout) — When starting checkout # add_to_wishlist Event Source: https://docs.upstackdata.com/pixel/events/add-to-wishlist Track when a visitor adds a product to their wishlist Fires when a visitor adds a product to their wishlist or saves it for later. This indicates high purchase intent and is valuable for remarketing campaigns. <Note> **Shopify:** Manual implementation required. Requires a wishlist app or custom implementation. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'add_to_wishlist', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, brand: 'Example Brand' } ], value: 34.99, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | -------------------------- | | items | array | Yes | Products added to wishlist | | value | number | No | Product price | | currency | string | No | ISO 4217 currency code | ## When to Fire * Wishlist/favorite button click * Save for later action * Heart icon click on product ## Related Events * [view\_content](/pixel/events/view-content) — When viewing the product * [add\_to\_cart](/pixel/events/add-to-cart) — When adding to cart instead # book_call Event Source: https://docs.upstackdata.com/pixel/events/book-call Track when a user books a call or consultation Fires when a user books a call or consultation. This is a high-intent conversion event commonly used by B2B companies and service businesses. <Note> **Shopify:** Manual implementation required. Integrate with your scheduling tool (Calendly, etc.). </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'book_call', { callType: 'sales_consultation', value: 200.00, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | -------------------------------------------------------- | | callType | string | No | Type of call (e.g., `'sales_consultation'`, `'support'`) | | value | number | No | Estimated value of the booking | | currency | string | No | ISO 4217 currency code | ## When to Fire * Calendly booking confirmation * Meeting scheduler submission * Demo request completion ## Related Events * [schedule](/pixel/events/schedule) — For general appointment scheduling * [contact](/pixel/events/contact) — For contact form submissions * [lead](/pixel/events/lead) — For general lead capture # complete_registration Event Source: https://docs.upstackdata.com/pixel/events/complete-registration Track when a customer creates an account Fires when a customer creates an account. This is useful for tracking account signups and can be a valuable conversion event for platforms that prioritize registered users. <Note> **Shopify:** Manual implementation required. Not automatically tracked. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'complete_registration', { method: 'email', source: 'checkout_page' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------------------------------------------- | | method | string | No | Registration method (e.g., `'email'`, `'google'`, `'facebook'`) | | source | string | No | Where registration occurred | ## When to Fire * Account registration form submission * OAuth signup completion (Google, Facebook) * Post-purchase account creation ## Related Events * [sign\_up](/pixel/events/sign-up) — For simpler signup tracking * [login](/pixel/events/login) — When existing users log in * [lead](/pixel/events/lead) — For lead generation # contact Event Source: https://docs.upstackdata.com/pixel/events/contact Track when a user submits a contact form Fires when a user submits a contact form. This is useful for tracking customer inquiries and support requests as conversion events. <Note> **Shopify:** Manual implementation required. Integrate with your contact form. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'contact', { formName: 'product_inquiry', email: 'customer@example.com' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | -------------------- | | formName | string | No | Form or inquiry type | | email | string | No | Contact's email | ## When to Fire * Contact us form submission * Support request submission * Product inquiry ## Related Events * [lead](/pixel/events/lead) — For general lead capture * [book\_call](/pixel/events/book-call) — When scheduling a call # Custom Events Source: https://docs.upstackdata.com/pixel/events/custom-events Track custom events beyond standard taxonomy — wishlist adds, quiz completions, loyalty redemptions. Full pipeline support with identity resolution. Custom events let you track interactions that don't fit the standard event types. Wishlist adds, quiz completions, loyalty point redemptions, product configurator steps — any meaningful customer action can be captured as a custom event and forwarded through the Upstack pipeline. <Tip> Custom events flow through the same Capture → Resolve → Enrich → Activate pipeline as standard events. They receive identity resolution, enrichment, and destination forwarding automatically. </Tip> <Info> **Two types of custom events exist:** * **User-defined custom events** — Events you create and fire manually for business-specific interactions * **Upstack-generated events** — Events like `nc_purchase` and `rc_purchase` that Upstack fires automatically alongside standard events See [Upstack-native custom purchase events](#upstack-native-custom-purchase-events) for the automatically generated events. </Info> ## Naming Conventions Custom event names follow these rules: * Use **snake\_case**: `wishlist_add`, `quiz_complete`, `loyalty_redeem` * Keep names **descriptive and specific**: `product_config_saved` is better than `custom_action_1` * Avoid names that collide with standard events — `page_view`, `purchase`, etc. are reserved * Maximum length: **64 characters** * Allowed characters: letters, numbers, underscores <Warning> Event names are case-sensitive. `wishlist_add` and `WishlistAdd` are treated as separate events. Use snake\_case to match standard event conventions. </Warning> ## Tracking Custom Events Pass the event name and properties directly to the `track()` method: ```javascript theme={null} window._upstack('track', 'wishlist_add', { content_ids: ['8012345678'], content_name: 'Classic Cotton Tee', value: 34.99, currency: 'USD', wishlist_id: 'wl_abc123' }); ``` Upstack automatically attaches identity data (`user_data`), timestamps, and context fields. You only provide the event name and properties. For best compatibility with destinations, reuse standard property names (`content_ids`, `value`, `currency`, `content_name`) wherever they apply. ## How Custom Events Flow Through the Pipeline Custom events follow the exact same path as standard events: 1. **Capture** — The Upstack Pixel sends the event to the edge API. You can fire custom events using the JavaScript tracking API on your storefront. 2. **Resolve** — Upstack ID attaches identity data to the event. Session stitching and cross-device linking work the same as for standard events. 3. **Enrich** — UTM parameters, click IDs, and product catalog data are merged if applicable `content_ids` are present. 4. **Activate** — The event is forwarded to destinations that accept custom events. ## Destination Support Not all destinations handle custom events the same way: | Destination | Custom Event Support | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **Meta CAPI** | Supported as `Custom` event type. Meta receives the custom event name and all properties. Useful for building custom audiences and optimization. | | **TikTok Events API** | Supported. Custom events can be used for audience building but not standard optimization. | | **Klaviyo** | Fully supported. Custom events appear as distinct metric types in Klaviyo for flow triggers and segmentation. | | **GA4** | Supported. Custom event names map directly to GA4 custom events. Properties become event parameters. | | **Webhook** | Fully supported. The raw event payload is forwarded as-is. | <Note> Meta and TikTok ad optimization algorithms work best with standard events. Use custom events for audience building and measurement, but rely on standard events (Purchase, AddToCart, etc.) for campaign optimization signals. </Note> ## Firing Custom Events To fire a custom event from your storefront, use the Upstack JavaScript API: ```javascript theme={null} window._upstack('track', 'wishlist_add', { content_ids: ['8012345678'], content_name: 'Classic Cotton Tee', value: 34.99, currency: 'USD', wishlist_id: 'wl_abc123' }); ``` The Upstack Pixel handles serialization, batching, and delivery to the edge API. Identity fields (`user_data`) are attached automatically — you only need to provide the event name and `custom_data` properties. <Tip> For the full `track()` method signature with all 7 parameters including event deduplication, backdating, and `useBeacon` for page unload tracking, see the [JavaScript SDK Reference](/pixel/javascript-sdk#trackeventname-eventdata). </Tip> ## Upstack-native custom purchase events <Note> **Shopify-specific feature** — The `nc_purchase` and `rc_purchase` events are only available for Shopify stores using the Upstack Shopify app. They rely on Shopify order history to determine customer status. </Note> In addition to user-defined custom events, Upstack fires two built-in custom events that segment every order by customer status. They are sent alongside — not instead of — the standard `purchase` event. <AccordionGroup> <Accordion title="nc_purchase" icon="user-plus"> Fires when an order is placed by a customer with **no prior completed order history**. Used to optimize Meta campaigns toward new-customer acquisition instead of repeat buyers. **When it fires:** Order confirmation, when the customer has zero prior completed orders in Shopify. **Properties:** Same payload as the standard `Purchase` event (`value`, `currency`, `content_ids`, `order_id`, etc.) plus Upstack's identity enrichment (`em`, `ph`, `fn`, `ln`, `fbc`, `fbp`, `client_ip_address`, `client_user_agent`). See [Set up custom events → NC Purchase](/guides/facebook-ads/set-up-nc-and-rc-purchase-events-in-meta#new-customer-purchase-nc-purchase) for Meta setup steps. </Accordion> <Accordion title="rc_purchase" icon="rotate-right"> Fires when an order is placed by a customer with **one or more prior completed orders**. Used for retargeting audiences, retention measurement, and keeping prospecting campaigns honest about who they're actually converting. **When it fires:** Order confirmation, when the customer has at least one prior completed order in Shopify. **Properties:** Same payload as the standard `Purchase` event (`value`, `currency`, `content_ids`, `order_id`, etc.) plus Upstack's identity enrichment (`em`, `ph`, `fn`, `ln`, `fbc`, `fbp`, `client_ip_address`, `client_user_agent`). **What destinations receive (internal format):** ```json theme={null} // Internal format — Upstack fires this automatically, you don't write this code { "event_name": "rc_purchase", "event_time": "2026-02-18T14:35:20.000Z", "event_source_url": "https://example-store.com/thank-you", "user_data": { "em": "a1b2c3d4e5f6...hashed", "ph": "f6e5d4c3b2a1...hashed", "fbc": "fb.1.1708271400.AbC123", "fbp": "fb.1.1708271400.XyZ789", "external_id": "cust_12345" }, "custom_data": { "content_ids": ["8012345678"], "content_type": "product", "value": 42.00, "currency": "USD", "order_id": "#1087", "num_items": 1 } } ``` See [Set up custom events → RC Purchase](/guides/facebook-ads/set-up-nc-and-rc-purchase-events-in-meta#returning-customer-purchase-rc-purchase) for Meta setup steps. </Accordion> </AccordionGroup> <Note> The standard `purchase` event still fires for every order regardless of customer status. `nc_purchase` and `rc_purchase` fire *in addition to* `purchase`, not instead of it. </Note> ## AOV-Segmented Purchase Events Upstack automatically generates AOV (Average Order Value) segmented purchase events based on your store's order history. These events help you optimize campaigns toward high-value orders. <Warning> **Automatically generated.** You do not fire these events manually. Upstack analyzes each order against your store's historical AOV distribution and fires the appropriate event automatically. </Warning> <AccordionGroup> <Accordion title="high_aov_purchase" icon="arrow-up"> Fires when an order's value exceeds your store's historical average order value threshold. **When it fires:** Order confirmation, when `order_value > store_aov_threshold`. **Properties:** Same payload as the standard `Purchase` event. **Use case:** Optimize Meta campaigns toward customers who place high-value orders, not just any orders. </Accordion> <Accordion title="low_aov_purchase" icon="arrow-down"> Fires when an order's value falls below your store's historical average. **When it fires:** Order confirmation, when `order_value < store_aov_threshold`. **Properties:** Same payload as the standard `Purchase` event. **Use case:** Exclude from high-value optimization campaigns; analyze patterns in low-value conversions. </Accordion> <Accordion title="p70_aov_purchase" icon="chart-line"> Fires when an order's value exceeds the 70th percentile of your store's order values. **When it fires:** Order confirmation, when `order_value >= p70_threshold`. **Properties:** Same payload as the standard `Purchase` event. **Use case:** Target campaigns toward top 30% of orders by value. </Accordion> <Accordion title="p80_aov_purchase" icon="chart-line"> Fires when an order's value exceeds the 80th percentile of your store's order values. **When it fires:** Order confirmation, when `order_value >= p80_threshold`. **Properties:** Same payload as the standard `Purchase` event. **Use case:** Target campaigns toward top 20% of orders by value. </Accordion> <Accordion title="p90_aov_purchase" icon="chart-line"> Fires when an order's value exceeds the 90th percentile of your store's order values. **When it fires:** Order confirmation, when `order_value >= p90_threshold`. **Properties:** Same payload as the standard `Purchase` event. **Use case:** Target campaigns toward your highest-value orders (top 10%). </Accordion> </AccordionGroup> <Tip> Use percentile-based events (`p70_aov_purchase`, `p80_aov_purchase`, `p90_aov_purchase`) in Meta custom conversions to optimize toward different value tiers. This is more precise than the binary `high_aov_purchase`/`low_aov_purchase` split. </Tip> ## Customer Behavior Purchase Events Upstack automatically segments purchases by customer behavior patterns. <AccordionGroup> <Accordion title="upsell_purchase" icon="arrow-up-right-dots"> Fires when an order contains upsell or cross-sell items that were added after the initial product selection. **When it fires:** Order confirmation, when upsell/cross-sell items are detected in the cart. **Properties:** Same payload as the standard `Purchase` event, plus identification of which items were upsells. **Use case:** Measure upsell effectiveness; optimize campaigns toward customers likely to accept upsells. </Accordion> <Accordion title="lapsed_purchase" icon="clock-rotate-left"> Fires when a previously inactive customer returns and makes a purchase. **When it fires:** Order confirmation, when the customer has been inactive for a defined period (typically 90+ days since last order). **Properties:** Same payload as the standard `Purchase` event. **Use case:** Measure win-back campaign effectiveness; build audiences of re-engaged customers. </Accordion> </AccordionGroup> ## Related Documentation <CardGroup> <Card title="Standard Events" icon="list-check" href="/pixel/standard-events"> Review the full list of built-in events before creating a custom event. </Card> <Card title="JavaScript SDK" icon="code" href="/pixel/javascript-sdk#trackeventname-eventdata"> Full track() method reference with all 7 parameters. </Card> <Card title="Properties & Context" icon="table" href="/pixel/properties"> See all available property fields you can include in custom\_data. </Card> <Card title="Shopify Automatic Tracking" icon="shopify" href="/sources/shopify-automatic-tracking"> Events automatically tracked on Shopify stores. </Card> </CardGroup> # initiate_checkout Event Source: https://docs.upstackdata.com/pixel/events/initiate-checkout Track when a visitor starts the checkout process Fires when a visitor starts the checkout process. This event marks the transition from browsing to buying and is critical for checkout funnel analysis. <Note> **Shopify:** Automatically tracked when customers click the checkout button or land on the checkout page. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'initiate_checkout', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2 }, { id: 'SKU_67890', name: 'Running Socks', price: 14.99, quantity: 1 } ], value: 84.97, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | ---------------------- | | items | array | Yes | Products in checkout | | value | number | Yes | Cart subtotal | | currency | string | Yes | ISO 4217 currency code | ## When to Fire * Checkout button click * Checkout page load * Express checkout initiation (Shop Pay, Apple Pay) ## Related Events * [view\_cart](/pixel/events/view-cart) — Before starting checkout * [add\_shipping\_info](/pixel/events/add-shipping-info) — After entering shipping details * [add\_payment\_info](/pixel/events/add-payment-info) — After entering payment details * [purchase](/pixel/events/purchase) — When order is completed # lead Event Source: https://docs.upstackdata.com/pixel/events/lead Track when a visitor submits a lead form Fires when a visitor submits a lead form. This is the primary conversion event for lead generation businesses and is used to track form submissions, newsletter signups, and inquiries. <Note> **Shopify:** Tracked via form hooks when using compatible form/popup apps. Manual implementation may be required for custom forms. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'lead', { source: 'contact_form', email: 'prospect@example.com', value: 150.00, currency: 'USD' }); ``` Newsletter signup: ```javascript theme={null} window._upstack('track', 'lead', { source: 'newsletter_popup', email: 'subscriber@example.com' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------- | | source | string | No | Form or campaign identifier | | email | string | No | Lead's email address | | value | number | No | Estimated lead value | | currency | string | No | ISO 4217 currency code | ## When to Fire * Contact form submission * Newsletter signup * Quote request submission * Product inquiry ## Related Events * [subscribe](/pixel/events/subscribe) — For marketing opt-ins specifically * [contact](/pixel/events/contact) — For contact form submissions * [complete\_registration](/pixel/events/complete-registration) — For account signups # login Event Source: https://docs.upstackdata.com/pixel/events/login Track when a user logs into their account Fires when a user logs into their account. This helps track returning user engagement and can be used to build audience segments of active customers. <Note> **Shopify:** Manual implementation required. Not automatically tracked. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'login', { method: 'email' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | ---------------------------------------------------------------- | | method | string | No | Login method (`'email'`, `'google'`, `'facebook'`, `'shop_pay'`) | ## When to Fire * Successful login form submission * OAuth login completion * Automatic re-authentication ## Related Events * [sign\_up](/pixel/events/sign-up) — When new users create accounts * [complete\_registration](/pixel/events/complete-registration) — For registration flows # page_view Event Source: https://docs.upstackdata.com/pixel/events/page-view Track when a visitor loads a page on your site Fires when a visitor loads a page. This is the foundation of all analytics — every page load should trigger this event. <Note> **Shopify:** Automatically tracked by the Upstack Pixel on all page loads. </Note> ## JavaScript ```javascript theme={null} window._upstack('page'); ``` With custom properties: ```javascript theme={null} window._upstack('page', { pageCategory: 'product', collectionHandle: 'summer-2026' }); ``` ## Properties | Property | Type | Required | Description | | ---------------- | ------ | -------- | ------------------------------------------------------- | | pageCategory | string | No | Page type (e.g., `'product'`, `'collection'`, `'blog'`) | | collectionHandle | string | No | Collection identifier for collection pages | ## Auto-Captured The SDK automatically captures `page_url`, `page_title`, `page_referrer`, and `page_path`. ## When to Fire * On initial page load * On SPA route changes * After dynamic content loads (infinite scroll) ## Related Events * [view\_content](/pixel/events/view-content) — When viewing a specific product * [view\_category](/pixel/events/view-category) — When viewing a collection page * [search](/pixel/events/search) — When viewing search results # product_removed_from_cart Event Source: https://docs.upstackdata.com/pixel/events/product-removed-from-cart Track when a visitor removes an item from their cart Fires when a visitor removes an item from their cart. This helps identify cart friction points and understand why shoppers don't complete purchases. <Note> **Shopify:** Automatically tracked when items are removed from cart. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'product_removed_from_cart', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 1 } ], value: 34.99, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | ------------------------------------------------------------------------ | | items | array | Yes | Products removed (see [Item Object](/pixel/standard-events#item-object)) | | value | number | No | Value of removed items | | currency | string | No | ISO 4217 currency code | ## When to Fire * Remove button click * Quantity decrease to zero * Clear cart action ## Related Events * [add\_to\_cart](/pixel/events/add-to-cart) — When adding items to cart * [view\_cart](/pixel/events/view-cart) — When viewing cart contents # Address Properties Source: https://docs.upstackdata.com/pixel/events/properties/address Shipping and billing address fields — address1, city, province, country, zip for checkout and purchase events. For shipping and billing information. Pass as an array of address objects. ## Address Array Structure ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 149.99, currency: 'USD', addresses: [ { firstName: 'Jane', lastName: 'Smith', address1: '123 Main St', address2: 'Apt 4B', city: 'San Francisco', province: 'California', provinceCode: 'CA', country: 'US', zip: '94102' } ], items: [/* ... */] }); ``` ## Address Properties | Property | Type | Description | | -------------- | ------ | -------------------------------------------------------- | | `firstName` | string | First name | | `lastName` | string | Last name | | `company` | string | Company or organization name | | `address1` | string | Street address line 1 | | `address2` | string | Street address line 2 | | `city` | string | City | | `province` | string | State or province | | `provinceCode` | string | State/province code (e.g., `CA`, `NY`, `ON`) | | `country` | string | Country name | | `countryCode` | string | ISO 3166-1 alpha-2 country code (e.g., `US`, `CA`, `GB`) | | `zip` | string | ZIP or postal code | ## Privacy Address fields (city, zip, country code, state code) are normalized and SHA-256 hashed before being sent to advertising destinations. <Note> Use `province` for the full state/province name and `provinceCode` for the abbreviated code. Use `zip` for postal codes. </Note> # Auto-Captured Fields Source: https://docs.upstackdata.com/pixel/events/properties/auto-captured Fields captured automatically by the Upstack Pixel — click IDs, UTMs, device info, geo, and context. Don't set these manually. These fields are captured automatically by the Upstack Pixel and edge API. **Do not include them in your `track()` calls.** ## Click IDs Click IDs are captured automatically from URL parameters and browser cookies. Each platform's click ID is stored along with a timestamp indicating when it was collected. ### Meta (Facebook/Instagram) | Field | Source | Description | | -------- | ------------- | ------------------------------------------------------------ | | `fbc` | `_fbc` cookie | Meta click ID cookie (contains `fbclid` from ad click URL) | | `fbp` | `_fbp` cookie | Meta browser ID (first-party cookie for user identification) | | `fbclid` | URL parameter | Meta click ID from ad click URL (raw parameter value) | ### Google Ads | Field | Source | Description | | -------- | ------------- | ---------------------------------------------------- | | `gclid` | URL parameter | Google click ID (standard web campaigns) | | `gbraid` | URL parameter | Google click ID for iOS App campaigns (privacy-safe) | | `wbraid` | URL parameter | Google click ID for web-to-app measurement | ### TikTok | Field | Source | Description | | -------- | ------------- | --------------------------------------------------- | | `ttclid` | URL parameter | TikTok click ID from ad click URL | | `ttp` | `_ttp` cookie | TikTok browser ID cookie (first-party pixel cookie) | ### Snapchat | Field | Source | Description | | ------------------ | -------------- | ------------------------------------- | | `snapchatSCCid` | URL parameter | Snapchat click ID (`ScCid` parameter) | | `snapchatSCCookie` | `_scid` cookie | Snapchat browser ID cookie | ### Pinterest | Field | Source | Description | | --------------- | -------------- | ------------------------------------------ | | `pinterestEpik` | `_epik` cookie | Pinterest click ID cookie (Enhanced Match) | ### AppLovin | Field | Source | Description | | --------------- | ------------- | ---------------------------------------------- | | `applovinAxwrt` | URL parameter | AppLovin attribution token (`axwrt` parameter) | | `aleid` | URL parameter | AppLovin click ID | ### Klaviyo | Field | Source | Description | | ------------ | ------------- | --------------------------------- | | `kx` | URL parameter | Klaviyo click ID from email links | | `klaviyoCid` | URL parameter | Klaviyo campaign ID | ### Sendlane | Field | Source | Description | | ------------- | ------------- | ---------------------------------- | | `sendlaneCid` | URL parameter | Sendlane click ID from email links | ### Omnisend | Field | Source | Description | | ------------- | ------------- | ---------------------------------- | | `omnisendCid` | URL parameter | Omnisend click ID from email links | ### Reddit | Field | Source | Description | | ------------ | ------------------ | ------------------------------ | | `redditCid` | URL parameter | Reddit click ID from ad clicks | | `redditUuid` | `_rdt_uuid` cookie | Reddit browser ID cookie | ### Taboola | Field | Source | Description | | ------- | ------------- | -------------------------------------- | | `tblci` | URL parameter | Taboola click ID from native ad clicks | ### Outbrain | Field | Source | Description | | -------- | ------------- | --------------------------------------- | | `obclid` | URL parameter | Outbrain click ID from native ad clicks | ### NewsBreak | Field | Source | Description | | -------- | ------------- | --------------------------------- | | `nbclid` | URL parameter | NewsBreak click ID from ad clicks | ### LinkedIn | Field | Source | Description | | --------- | ------------- | ----------------------------------------------------------- | | `liFatId` | URL parameter | LinkedIn First-Party Ad Tracking ID (`li_fat_id` parameter) | ### Microsoft Advertising (Bing) | Field | Source | Description | | --------- | ------------- | ------------------------------ | | `msclkid` | URL parameter | Microsoft Advertising click ID | *** ## UTM Parameters Captured automatically from URL query string parameters: | Field | Description | | -------------- | --------------------------------------------------------- | | `utm_source` | Traffic source (e.g., `google`, `facebook`, `newsletter`) | | `utm_medium` | Marketing medium (e.g., `cpc`, `email`, `social`) | | `utm_campaign` | Campaign name or identifier | | `utm_content` | Ad or link variant for A/B testing | | `utm_term` | Paid search keyword | *** ## Page Context Captured automatically from the browser on every event: | Field | Description | | ---------- | ---------------------------------------------- | | `host` | Hostname of the page (e.g., `www.example.com`) | | `path` | URL path (e.g., `/products/widget`) | | `referrer` | Full referrer URL | | `search` | Query string (e.g., `?utm_source=google`) | | `title` | Page title from `document.title` | | `url` | Full page URL where the event fired | *** ## Viewport & Device Captured from the browser at page load: | Field | Description | | ------------------- | ------------------------------------------------------------ | | `viewportWidth` | Browser viewport width in CSS pixels | | `viewportHeight` | Browser viewport height in CSS pixels | | `pageHeight` | Total scrollable page height in CSS pixels | | `devicePixelRatio` | Device pixel ratio (e.g., `2` for Retina displays) | | `device_type` | Detected device type: `"mobile"`, `"desktop"`, or `"tablet"` | | `client_user_agent` | Browser user agent string | *** ## Browser Settings | Field | Description | | ----------------- | ------------------------------------------- | | `locale` | Browser locale (e.g., `en-US`) | | `timezone` | Browser timezone (e.g., `America/New_York`) | | `adBlockDetected` | `true` if an ad blocker was detected | *** ## Geographic Data (from Cloudflare) Captured server-side from Cloudflare's edge network: | Field | Description | | ------------- | -------------------------------------------------- | | `country` | ISO 3166-1 alpha-2 country code (e.g., `US`, `GB`) | | `region` | State/province name (e.g., `Texas`, `California`) | | `regionCode` | ISO 3166-2 region code (e.g., `TX`, `CA`) | | `city` | City name (e.g., `Austin`, `San Francisco`) | | `postalCode` | Postal/zip code (e.g., `78701`) | | `latitude` | Latitude coordinate | | `longitude` | Longitude coordinate | | `continent` | Continent code (e.g., `NA`, `EU`, `AS`) | | `isEUCountry` | `"1"` if the country is in the EU | | `timezone` | IANA timezone (e.g., `America/Chicago`) | *** ## Network Info (from Cloudflare) | Field | Description | | ------------------- | ----------------------------------------------------- | | `asn` | Autonomous System Number | | `asOrganization` | Organization that owns the ASN (e.g., `Google Cloud`) | | `isBot` | `true` if Cloudflare detects the request as a bot | | `client_ip_address` | Visitor's IP address (captured server-side) | *** ## Session & Event Metadata | Field | Description | | ------------------ | --------------------------------- | | `event_id` | Unique event ID for deduplication | | `event_time` | Timestamp (ISO 8601, UTC) | | `event_source_url` | Full URL where the event fired | | `session_id` | Upstack session identifier | | `pixel_id` | Your Upstack Pixel ID | # Checkout & Pricing Properties Source: https://docs.upstackdata.com/pixel/events/properties/checkout Properties for checkout and purchase events — pricing breakdown, payment methods, and shipping details. Checkout and pricing properties provide detailed order information for purchase and checkout events. ## Properties <CardGroup> <Card title="subtotalPrice" icon="receipt" href="/pixel/events/properties/subtotal-price"> Subtotal before tax/shipping. </Card> <Card title="tax" icon="percent" href="/pixel/events/properties/tax"> Tax amount applied. </Card> <Card title="shipping" icon="truck" href="/pixel/events/properties/shipping"> Shipping cost. </Card> <Card title="discount" icon="tag" href="/pixel/events/properties/discount"> Total discount amount. </Card> <Card title="coupon" icon="ticket" href="/pixel/events/properties/coupon"> Promo code used. </Card> <Card title="paymentType" icon="credit-card" href="/pixel/events/properties/payment-type"> Payment method. </Card> <Card title="shippingTier" icon="gauge-high" href="/pixel/events/properties/shipping-tier"> Shipping speed selected. </Card> </CardGroup> ## Quick Reference | Property | Type | Description | | --------------- | ------ | -------------------------------- | | `subtotalPrice` | number | Subtotal before tax and shipping | | `tax` | number | Tax amount | | `shipping` | number | Shipping cost | | `discount` | number | Total discount amount applied | | `coupon` | string | Coupon or promo code used | | `paymentType` | string | Payment method used | | `shippingTier` | string | Shipping tier selected | | `cartId` | string | Shopping cart identifier | | `affiliation` | string | Store or affiliate name | ## Example ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 134.99, currency: 'USD', subtotalPrice: 149.99, tax: 12.00, shipping: 8.00, discount: 35.00, coupon: 'SAVE25', paymentType: 'credit_card', shippingTier: 'express', items: [/* ... */] }); ``` # Complex Properties Source: https://docs.upstackdata.com/pixel/events/properties/complex Advanced property types — the items array for product data, SaaS properties for B2B tracking, and auto-captured context fields. Complex properties handle structured data, B2B/SaaS tracking, and automatically captured context. These properties support advanced use cases beyond simple key-value pairs. ## Properties <CardGroup> <Card title="Items Array" icon="list" href="/pixel/events/properties/items"> Product data for e-commerce events — id, name, price, quantity, brand, category. </Card> <Card title="SaaS Properties" icon="building" href="/pixel/events/properties/saas"> B2B/SaaS tracking — accounts, subscriptions, trials, MRR, seats. </Card> <Card title="Auto-Captured Fields" icon="wand-magic-sparkles" href="/pixel/events/properties/auto-captured"> Click IDs, UTMs, device info, geo — captured automatically. </Card> </CardGroup> ## Quick Reference | Property Type | Description | When to Use | | ------------------- | -------------------------------------------- | -------------------------------------------------------------- | | **items** | Array of product objects | All e-commerce events (view\_content, add\_to\_cart, purchase) | | **SaaS properties** | Account, subscription, trial, payment fields | B2B/SaaS event tracking | | **Auto-captured** | Click IDs, UTMs, device, geo | Automatically captured — do not set manually | ## Items Array The `items` array is required for all product-related events. Each item contains product details: ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 149.99, currency: 'USD', items: [ { id: 'SKU-001', name: 'Running Shoes', price: 89.99, quantity: 1, brand: 'Nike', category: 'Footwear', variant: 'Blue / Size 10' } ] }); ``` <Card title="Full Items Reference" icon="arrow-right" href="/pixel/events/properties/items"> See the complete items array specification with all supported fields. </Card> ## SaaS Properties For B2B and subscription-based businesses tracking accounts, subscriptions, trials, and revenue: ```javascript theme={null} window._upstack('track', 'subscription_started', { accountId: 'acct_abc123', subscriptionId: 'sub_def456', planId: 'plan_pro_monthly', planName: 'Pro Plan', mrr: 9900, billingInterval: 'month' }); ``` <Card title="Full SaaS Reference" icon="arrow-right" href="/pixel/events/properties/saas"> See all SaaS properties including trial, payment, and seat tracking fields. </Card> ## Auto-Captured Fields <Info> **Do not include auto-captured fields in your `track()` calls.** The Upstack Pixel and edge API capture these automatically. </Info> Auto-captured fields include: | Category | Examples | | ------------------ | --------------------------------------------------------------------- | | **Click IDs** | `fbclid`, `gclid`, `ttclid`, `msclkid`, `fbc`, `fbp`, `ttp` | | **UTM Parameters** | `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term` | | **Page Context** | `url`, `path`, `referrer`, `title`, `host` | | **Device** | `device_type`, `viewportWidth`, `viewportHeight`, `client_user_agent` | | **Geographic** | `country`, `region`, `city`, `postalCode`, `timezone` | | **Session** | `session_id`, `event_id`, `event_time`, `pixel_id` | <Card title="Full Auto-Captured Reference" icon="arrow-right" href="/pixel/events/properties/auto-captured"> See all click IDs (Meta, Google, TikTok, Pinterest, Snapchat, AppLovin, LinkedIn, Microsoft, Reddit, and more), UTM parameters, and context fields. </Card> # Content Properties Source: https://docs.upstackdata.com/pixel/events/properties/content Properties for content-related events — primarily search queries. Content properties are used for search and content interaction events. ## User-Input Properties | Property | Type | Description | Events | | ------------ | ------ | ---------------------------- | ------ | | `searchTerm` | string | Search query entered by user | search | <CardGroup> <Card title="searchTerm" icon="magnifying-glass" href="/pixel/events/properties/search-term"> Search query entered by the user. </Card> </CardGroup> ## Example ```javascript theme={null} window._upstack('track', 'search', { searchTerm: 'blue running shoes', items: [ { id: 'SKU-001', name: 'Running Shoes', price: 99.00 }, { id: 'SKU-002', name: 'Athletic Socks', price: 12.00 } ] }); ``` ## Auto-Derived Fields The following fields are **automatically computed** from your `items` array during event forwarding. Do not pass them directly: | Field | Derived From | Description | | -------------- | ------------------------- | -------------------------------- | | `content_ids` | `items[].id` | Array of product IDs | | `content_name` | `items[0].name` | Name of first product | | `content_type` | Inferred | `"product"` or `"product_group"` | | `num_items` | Sum of `items[].quantity` | Total item count | <Note> For product data, always use the `items` array. The platform extracts and formats the necessary fields for each advertising destination. </Note> ## Related Properties <CardGroup> <Card title="Items Array" icon="list" href="/pixel/events/properties/items"> Pass all product data here — content fields are derived automatically. </Card> <Card title="content_ids" icon="list" href="/pixel/events/properties/content-ids"> Learn how product IDs are extracted from items. </Card> </CardGroup> # content_ids Source: https://docs.upstackdata.com/pixel/events/properties/content-ids Auto-derived array of product IDs sent to advertising platforms. <Warning> `content_ids` is **not** a user-input property. It is automatically derived from your `items` array during event forwarding. </Warning> ## How It Works When you send events with an `items` array, the platform extracts product IDs and forwards them as `content_ids` to advertising platforms (Meta, TikTok, etc.). **Do this:** ```javascript theme={null} window._upstack('track', 'view_content', { items: [ { id: 'SKU-001', name: 'Running Shoes', price: 99.00 }, { id: 'SKU-002', name: 'Athletic Socks', price: 12.00 } ] }); // → Forwards content_ids: ['SKU-001', 'SKU-002'] to destinations ``` **Not this:** ```javascript theme={null} // ❌ Don't pass content_ids directly window._upstack('track', 'view_content', { content_ids: ['SKU-001', 'SKU-002'] }); ``` ## Derivation Logic The platform extracts IDs from the `items` array using this priority: 1. `item.id` (preferred) 2. `item.item_id` 3. `item.product_id` 4. `item.sku` 5. `item.variant_id` ## Related Properties <CardGroup> <Card title="Items Array" icon="list" href="/pixel/events/properties/items"> Pass product data here — IDs are extracted automatically. </Card> <Card title="searchTerm" icon="magnifying-glass" href="/pixel/events/properties/search-term"> User-input property for search queries. </Card> </CardGroup> # Core Event Properties Source: https://docs.upstackdata.com/pixel/events/properties/core Essential properties for tracking events — value, currency, transactionId, and orderName. Core properties are the foundational fields used across most tracking events. These are typically required or strongly recommended for proper attribution and reporting. ## Properties <CardGroup> <Card title="value" icon="coins" href="/pixel/events/properties/value"> Monetary value of the event. </Card> <Card title="currency" icon="dollar-sign" href="/pixel/events/properties/currency"> ISO 4217 currency code. </Card> <Card title="transactionId" icon="fingerprint" href="/pixel/events/properties/transaction-id"> Unique order identifier. </Card> <Card title="orderName" icon="hashtag" href="/pixel/events/properties/order-name"> Human-readable order number. </Card> </CardGroup> ## Quick Reference | Property | Type | Required | Description | | --------------- | ------ | --------------------------------- | ---------------------------------------------- | | `value` | number | Yes for purchase, lead, subscribe | Monetary value of the event | | `currency` | string | Yes (when value is set) | ISO 4217 currency code (USD, EUR, GBP) | | `transactionId` | string | Yes for purchase/refund | Unique order identifier | | `orderName` | string | No | Human-readable order number shown to customers | ## Example ```javascript theme={null} window._upstack('track', 'purchase', { value: 149.99, currency: 'USD', transactionId: 'ORD-2026-001', orderName: '#1042', items: [/* ... */] }); ``` <Note> For Purchase events, `value` should match the order total you want reported to ad platforms. </Note> # coupon Source: https://docs.upstackdata.com/pixel/events/properties/coupon Coupon or promo code used. Coupon or promo code used. ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 134.99, currency: 'USD', coupon: 'SAVE25' }); ``` | Type | Required | Events | | ------ | -------- | ------------------------------------------- | | string | No | purchase, initiate\_checkout, add\_to\_cart | ## Related Properties <CardGroup> <Card title="discount" icon="tag" href="/pixel/events/properties/discount"> Discount amount applied. </Card> <Card title="promotionId" icon="bullhorn" href="/pixel/events/properties/promotion-id"> Promotion identifier. </Card> </CardGroup> # creativeName Source: https://docs.upstackdata.com/pixel/events/properties/creative-name Creative or ad variant name for promotion tracking. Creative or ad variant name for promotion tracking. ```javascript theme={null} window._upstack('track', 'view_content', { items: [{ id: 'SKU_001', name: 'Running Shoes', price: 89.99 }], value: 89.99, currency: 'USD', creativeName: 'hero_banner_v2' }); ``` | Type | Required | Events | | ------ | -------- | -------------------------------------- | | string | No | view\_content, add\_to\_cart, purchase | <Tip> Use `creativeName` and `creativeSlot` to track which on-site promotions drive the most conversions. </Tip> ## Related Properties <CardGroup> <Card title="creativeSlot" icon="table-cells" href="/pixel/events/properties/creative-slot"> Placement position on page. </Card> <Card title="promotionId" icon="bullhorn" href="/pixel/events/properties/promotion-id"> Promotion identifier. </Card> </CardGroup> # creativeSlot Source: https://docs.upstackdata.com/pixel/events/properties/creative-slot Creative placement position on the page. Creative placement position on the page. ```javascript theme={null} window._upstack('track', 'view_content', { items: [{ id: 'SKU_001', name: 'Running Shoes', price: 89.99 }], value: 89.99, currency: 'USD', creativeSlot: 'homepage_hero' }); ``` | Type | Required | Events | | ------ | -------- | -------------------------------------- | | string | No | view\_content, add\_to\_cart, purchase | ## Common Values | Value | Description | | ------------------------- | ----------------------------- | | `hero` | Hero banner section | | `sidebar` | Sidebar placement | | `footer` | Footer area | | `homepage_hero` | Homepage hero banner | | `product_recommendations` | Product recommendation widget | | `cart_upsell` | Cart page upsell | ## Related Properties <CardGroup> <Card title="creativeName" icon="palette" href="/pixel/events/properties/creative-name"> Creative variant name. </Card> <Card title="locationId" icon="location-dot" href="/pixel/events/properties/location-id"> Store or location identifier. </Card> </CardGroup> # currency Source: https://docs.upstackdata.com/pixel/events/properties/currency ISO 4217 currency code. Required whenever you include value. ISO 4217 currency code. Required whenever you include `value`. ```javascript theme={null} window._upstack('track', 'add_to_cart', { value: 49.99, currency: 'USD' // USD, EUR, GBP, CAD, etc. }); ``` | Type | Required | Events | | ------ | ----------------------- | ---------------------- | | string | Yes (when value is set) | Any event with `value` | ## Common Currency Codes | Code | Currency | | ----- | ----------------- | | `USD` | US Dollar | | `EUR` | Euro | | `GBP` | British Pound | | `CAD` | Canadian Dollar | | `AUD` | Australian Dollar | | `JPY` | Japanese Yen | ## Related Properties <CardGroup> <Card title="value" icon="coins" href="/pixel/events/properties/value"> The monetary value of the event. </Card> </CardGroup> # Customer Properties Source: https://docs.upstackdata.com/pixel/events/properties/customer Properties for identifying customers — email, phone, name, and address fields for identity resolution. Customer properties are used for identity resolution and destination matching. Including these fields significantly improves match quality on advertising platforms. ## Properties <CardGroup> <Card title="email" icon="envelope" href="/pixel/events/properties/email"> Primary cross-device identifier. </Card> <Card title="phone" icon="phone" href="/pixel/events/properties/phone"> E.164 format phone number. </Card> <Card title="firstName / lastName" icon="user" href="/pixel/events/properties/name"> Customer name fields. </Card> <Card title="Address Fields" icon="location-dot" href="/pixel/events/properties/address"> Shipping and billing address. </Card> </CardGroup> ## Quick Reference | Property | Type | Required | Description | | ----------- | ------ | ----------- | --------------------------------------- | | `email` | string | Recommended | Customer's email address | | `phone` | string | No | Phone number (E.164 format recommended) | | `firstName` | string | No | Customer's first name | | `lastName` | string | No | Customer's last name | ## Example ```javascript theme={null} window._upstack('track', 'lead', { email: 'customer@example.com', phone: '+15551234567', firstName: 'Jane', lastName: 'Smith', value: 0, currency: 'USD' }); ``` <Tip> Events with email typically score EMQ 8-9 on Meta. Events with only IP address score 2-3. </Tip> ## Privacy All customer PII (email, phone, name) is normalized and SHA-256 hashed before being sent to advertising destinations. Raw values are never stored in destination platforms. # discount Source: https://docs.upstackdata.com/pixel/events/properties/discount Total discount amount applied to the order. Total discount amount applied to the order. ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 134.99, currency: 'USD', discount: 35.00 }); ``` | Type | Required | Events | | ------ | -------- | ------------------------------------------- | | number | No | purchase, initiate\_checkout, add\_to\_cart | ## Related Properties <CardGroup> <Card title="coupon" icon="ticket" href="/pixel/events/properties/coupon"> Coupon code used. </Card> <Card title="subtotalPrice" icon="receipt" href="/pixel/events/properties/subtotal-price"> Subtotal before discounts. </Card> </CardGroup> # email Source: https://docs.upstackdata.com/pixel/events/properties/email Customer's email address. Primary identifier for cross-device tracking. Customer's email address. Primary identifier for cross-device tracking and destination matching. ```javascript theme={null} // With a lead form submission window._upstack('track', 'lead', { email: 'customer@example.com', value: 0, currency: 'USD' }); // With a purchase window._upstack('track', 'purchase', { email: 'customer@example.com', transactionId: 'ORD-123', value: 99.99, currency: 'USD' }); ``` | Type | Required | Events | | ------ | ----------- | ----------------------------------- | | string | Recommended | All events (improves match quality) | ## Privacy Email addresses are normalized (lowercase, trimmed) and SHA-256 hashed before being sent to advertising destinations. Raw emails are never stored in destination platforms. <Tip> Events with email typically score EMQ 8-9 on Meta. Events with only IP address score 2-3. </Tip> ## Related Properties <CardGroup> <Card title="phone" icon="phone" href="/pixel/events/properties/phone"> Customer phone number for improved matching. </Card> <Card title="firstName / lastName" icon="user" href="/pixel/events/properties/name"> Customer name for identity resolution. </Card> </CardGroup> # Event Properties Reference Source: https://docs.upstackdata.com/pixel/events/properties/index Complete reference for all Upstack Data event properties — items array, customer data, checkout fields, and auto-captured context like click IDs and UTMs. Properties are the data you send with each tracking event. This page documents all available properties and shows how to use them in JavaScript. <Note> Use **camelCase** when sending properties — the platform automatically converts to the format each destination requires. </Note> ## Full Event Structure A complete tracking event contains the event name, timestamp, user data, custom data, and automatically captured context. ```javascript theme={null} window._upstack('track', 'purchase', { // Core identifiers transactionId: 'ORD-2026-001', orderName: '#1042', // Monetary values value: 134.99, currency: 'USD', subtotalPrice: 149.99, tax: 12.00, shipping: 8.00, discount: 35.00, // Customer data (improves match quality) email: 'customer@example.com', phone: '+15551234567', firstName: 'Jane', lastName: 'Smith', // Product items items: [ { id: 'SKU-001', name: 'Running Shoes', price: 89.99, quantity: 1, brand: 'Nike', category: 'Footwear' } ], // Optional checkout details coupon: 'SAVE25', paymentType: 'credit_card', shippingTier: 'express' }); // The platform automatically captures additional context: // - Click IDs (fbclid, gclid, ttclid, etc.) // - UTM parameters (utm_source, utm_medium, etc.) // - Device and browser information // - Geographic data // - Session and identity information ``` ## Core Properties These properties work with most events. <CardGroup> <Card title="value" icon="coins" href="/pixel/events/properties/value"> Monetary value of the event. Required for purchase, lead, subscribe. </Card> <Card title="currency" icon="dollar-sign" href="/pixel/events/properties/currency"> ISO 4217 currency code. Required with value. </Card> <Card title="transactionId" icon="fingerprint" href="/pixel/events/properties/transaction-id"> Unique order identifier. Required for purchase/refund. </Card> <Card title="orderName" icon="hashtag" href="/pixel/events/properties/order-name"> Human-readable order number shown to customers. </Card> </CardGroup> ### Quick Reference | Property | Type | Required | Events | | ---------------------------------------------------------- | ------ | --------------------------------- | ------------------------------------------------------------------------------------------- | | [`value`](/pixel/events/properties/value) | number | Yes for purchase, lead, subscribe | purchase, add\_to\_cart, view\_content, initiate\_checkout, lead, subscribe, trial\_started | | [`currency`](/pixel/events/properties/currency) | string | Yes (when value is set) | Any event with `value` | | [`transactionId`](/pixel/events/properties/transaction-id) | string | Yes for purchase/refund | purchase, refund | | `orderId` | string | No | purchase, refund | | [`orderName`](/pixel/events/properties/order-name) | string | No | purchase | <Info> `orderId` and `transactionId` are interchangeable — use whichever fits your system. If both are provided, `transactionId` takes precedence. </Info> ```javascript theme={null} window._upstack('track', 'purchase', { value: 99.99, currency: 'USD', transactionId: 'ORD-2026-001', orderName: '#1042' }); ``` *** ## Customer Properties Properties for identifying customers. Used for identity resolution and destination matching. <CardGroup> <Card title="email" icon="envelope" href="/pixel/events/properties/email"> Primary identifier for cross-device tracking. </Card> <Card title="phone" icon="phone" href="/pixel/events/properties/phone"> E.164 format for improved matching. </Card> <Card title="firstName / lastName" icon="user" href="/pixel/events/properties/name"> Customer name for identity resolution. </Card> <Card title="Address Fields" icon="location-dot" href="/pixel/events/properties/address"> Shipping and billing address properties. </Card> </CardGroup> ### Quick Reference | Property | Type | Required | Events | | -------------------------------------------- | ------ | ----------- | ----------------------------------- | | [`email`](/pixel/events/properties/email) | string | Recommended | All events (improves match quality) | | [`phone`](/pixel/events/properties/phone) | string | No | All events (improves match quality) | | [`firstName`](/pixel/events/properties/name) | string | No | All events | | [`lastName`](/pixel/events/properties/name) | string | No | All events | <Tip> Events with email typically score EMQ 8-9 on Meta. Events with only IP address score 2-3. </Tip> ```javascript theme={null} window._upstack('track', 'lead', { email: 'customer@example.com', phone: '+15551234567', firstName: 'Jane', lastName: 'Smith' }); ``` *** ## Checkout & Pricing Properties Additional properties for checkout and purchase events. <CardGroup> <Card title="subtotalPrice" icon="receipt" href="/pixel/events/properties/subtotal-price"> Subtotal before tax/shipping. </Card> <Card title="tax" icon="percent" href="/pixel/events/properties/tax"> Tax amount applied. </Card> <Card title="shipping" icon="truck" href="/pixel/events/properties/shipping"> Shipping cost. </Card> <Card title="discount" icon="tag" href="/pixel/events/properties/discount"> Total discount amount. </Card> <Card title="coupon" icon="ticket" href="/pixel/events/properties/coupon"> Promo code used. </Card> <Card title="paymentType" icon="credit-card" href="/pixel/events/properties/payment-type"> Payment method used. </Card> <Card title="shippingTier" icon="gauge-high" href="/pixel/events/properties/shipping-tier"> Shipping speed selected. </Card> </CardGroup> ### Quick Reference | Property | Type | Description | | ---------------------------------------------------------- | --------- | ---------------------------------------------------------- | | [`subtotalPrice`](/pixel/events/properties/subtotal-price) | number | Subtotal before tax and shipping | | `price` | number | Base price (distinct from `value` which is the total) | | [`tax`](/pixel/events/properties/tax) | number | Tax amount | | [`shipping`](/pixel/events/properties/shipping) | number | Shipping cost | | [`discount`](/pixel/events/properties/discount) | number | Total discount amount applied | | [`coupon`](/pixel/events/properties/coupon) | string | Coupon or promo code used | | [`paymentType`](/pixel/events/properties/payment-type) | string | Payment method (`"credit_card"`, `"paypal"`, `"shop_pay"`) | | [`shippingTier`](/pixel/events/properties/shipping-tier) | string | Shipping tier (`"standard"`, `"express"`, `"overnight"`) | | `cartId` | string | Shopping cart identifier | | `affiliation` | string | Store or affiliate name | | `orderSourceName` | string | Order source channel | | `tags` | string\[] | Array of order or event tags | | `totalUnitCost` | number | Total cost of goods sold (COGS) for profitability tracking | | `totalUnitMargin` | number | Total margin (value - totalUnitCost) | ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 134.99, currency: 'USD', subtotalPrice: 149.99, tax: 12.00, shipping: 8.00, discount: 35.00, coupon: 'SAVE25', paymentType: 'credit_card', shippingTier: 'express', items: [/* ... */] }); ``` *** ## Content Properties Properties for content-related events like search and page views. <CardGroup> <Card title="searchTerm" icon="magnifying-glass" href="/pixel/events/properties/search-term"> Search query entered by the user. </Card> <Card title="content_ids" icon="list" href="/pixel/events/properties/content-ids"> Array of product IDs from search results. </Card> </CardGroup> ### Quick Reference | Property | Type | Description | Events | | ----------------------------------------------------- | --------- | --------------------------------- | ------------------------------------------- | | [`searchTerm`](/pixel/events/properties/search-term) | string | Search query entered | search | | [`content_ids`](/pixel/events/properties/content-ids) | string\[] | Array of product IDs | view\_content, search, add\_to\_cart | | `content_type` | string | `"product"` or `"product_group"` | view\_content, add\_to\_cart, purchase | | `content_name` | string | Name of content, product, or form | view\_content, lead, complete\_registration | | `num_items` | number | Total item count | add\_to\_cart, initiate\_checkout, purchase | | `page_title` | string | Page title | page\_view | | `referrer` | string | Referring URL | page\_view | ```javascript theme={null} window._upstack('track', 'search', { searchTerm: 'blue running shoes', content_ids: ['SKU-001', 'SKU-002', 'SKU-003'] }); ``` *** ## Promotional Properties Properties for tracking promotions, campaigns, and affiliate activity. <CardGroup> <Card title="promotionId" icon="fingerprint" href="/pixel/events/properties/promotion-id"> Promotion/campaign identifier. </Card> <Card title="promotionName" icon="tag" href="/pixel/events/properties/promotion-name"> Promotion display name. </Card> <Card title="creativeName" icon="palette" href="/pixel/events/properties/creative-name"> Creative/ad variant name. </Card> <Card title="creativeSlot" icon="table-cells" href="/pixel/events/properties/creative-slot"> Placement position on page. </Card> <Card title="locationId" icon="location-dot" href="/pixel/events/properties/location-id"> Store/affiliate/location ID. </Card> </CardGroup> ### Quick Reference | Property | Type | Description | Events | | ---------------------------------------------------------- | ------ | ---------------------------------------- | -------------------------------------- | | [`promotionId`](/pixel/events/properties/promotion-id) | string | Promotion or campaign identifier | view\_content, add\_to\_cart, purchase | | [`promotionName`](/pixel/events/properties/promotion-name) | string | Promotion display name | view\_content, add\_to\_cart, purchase | | [`creativeName`](/pixel/events/properties/creative-name) | string | Creative or ad variant name | view\_content, add\_to\_cart, purchase | | [`creativeSlot`](/pixel/events/properties/creative-slot) | string | Creative placement position | view\_content, add\_to\_cart, purchase | | [`locationId`](/pixel/events/properties/location-id) | string | Store, affiliate, or location identifier | All events | ```javascript theme={null} window._upstack('track', 'view_content', { items: [{ id: 'SKU_001', name: 'Running Shoes', price: 89.99 }], value: 89.99, currency: 'USD', promotionId: 'SUMMER_SALE_2026', promotionName: 'Summer Sale 2026', creativeName: 'hero_banner_v2', creativeSlot: 'homepage_hero', locationId: 'store_nyc_001' }); ``` *** ## Detailed Property References <CardGroup> <Card title="Items Array" icon="list" href="/pixel/events/properties/items"> Product details for e-commerce events — id, name, price, quantity, brand, category, variant. </Card> <Card title="Address Properties" icon="location-dot" href="/pixel/events/properties/address"> Shipping and billing address fields — address1, city, province, country, zip. </Card> <Card title="SaaS Properties" icon="building" href="/pixel/events/properties/saas"> B2B/SaaS properties — account, subscription, trial, payment, and churn tracking. </Card> <Card title="Auto-Captured Fields" icon="wand-magic-sparkles" href="/pixel/events/properties/auto-captured"> Click IDs, UTMs, and context fields captured automatically by the pixel. </Card> </CardGroup> *** ## Naming Conventions ### Input vs Output Format Send properties in **camelCase** — the platform converts to each destination's required format automatically. | Your Input | Meta CAPI Output | GA4 Output | | --------------- | ---------------- | ------------------------- | | `transactionId` | `transaction_id` | `transaction_id` | | `firstName` | `fn` (hashed) | `first_name` | | `email` | `em` (hashed) | `user_id` (if configured) | ### Legacy Snake Case Properties Some properties use snake\_case for compatibility with Meta and GA4 conventions: | Property | Format | Notes | | -------------- | ----------- | -------------------------------------------------- | | `content_ids` | snake\_case | Array of product IDs (Meta convention) | | `content_type` | snake\_case | `"product"` or `"product_group"` (Meta convention) | | `content_name` | snake\_case | Content or product name | | `num_items` | snake\_case | Total item count | <Info> The platform accepts both formats and normalizes automatically. You can use either `contentIds` or `content_ids` — both work. </Info> ### Event Names Event names use **snake\_case** (e.g., `add_to_cart`, `initiate_checkout`, `view_content`). ```javascript theme={null} // Correct window._upstack('track', 'add_to_cart', { ... }); window._upstack('track', 'view_content', { ... }); // Incorrect window._upstack('track', 'AddToCart', { ... }); window._upstack('track', 'viewContent', { ... }); ``` # Items Array Source: https://docs.upstackdata.com/pixel/events/properties/items Product details for e-commerce events — id, name, price, quantity, brand, category, and variant properties. For events involving products, use the `items` array. Required for all product-related events. ## Items Array Structure ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 149.99, currency: 'USD', items: [ { id: 'SKU-001', // Product ID or SKU name: 'Running Shoes', // Product name price: 89.99, // Unit price quantity: 1, // Quantity (default: 1) brand: 'Nike', // Brand name category: 'Footwear', // Primary category variant: 'Blue / Size 10' // Size, color, etc. }, { id: 'SKU-002', name: 'Athletic Socks', price: 14.99, quantity: 4, brand: 'Nike', category: 'Accessories' } ] }); ``` ## Item Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ------------------------------------------------------------------ | | `id` | string | No | Product ID or SKU | | `name` | string | No | Product name | | `price` | number | No | Unit price | | `quantity` | number | No | Quantity (default: 1) | | `value` | number | No | Total value for this item (typically `price × quantity`) | | `currency` | string | No | Per-item currency override (ISO 4217 code, e.g., `"USD"`) | | `brand` | string | No | Brand name | | `category` | string | No | Primary category | | `category2` | string | No | Secondary category | | `category3` | string | No | Tertiary category | | `category4` | string | No | Fourth category level | | `category5` | string | No | Fifth category level | | `variant` | string | No | Size, color, or other variant | | `sku` | string | No | Stock keeping unit | | `discount` | number | No | Discount amount per item | | `coupon` | string | No | Item-level coupon code | | `url` | string | No | Product page URL | | `imageUrl` | string | No | Product image URL | | `content_type` | string | No | `"product"` for individual items or `"product_group"` for variants | | `index` | number | No | Zero-based index of item in the items array | | `locationId` | string | No | Per-item store or location identifier | | `unitCost` | number | No | Cost per unit (for margin calculations) | | `unitMargin` | number | No | Margin per unit (for profitability tracking) | <Note> If `value` is not provided, it is computed automatically as `price × quantity`. </Note> ## Items Array by Event ```javascript theme={null} // View a product window._upstack('track', 'view_content', { items: [{ id: 'SKU-001', name: 'Running Shoes', price: 89.99, category: 'Footwear' }] }); // Add to cart window._upstack('track', 'add_to_cart', { value: 89.99, currency: 'USD', items: [{ id: 'SKU-001', name: 'Running Shoes', price: 89.99, quantity: 1 }] }); // Begin checkout window._upstack('track', 'initiate_checkout', { value: 104.98, currency: 'USD', items: [ { id: 'SKU-001', name: 'Running Shoes', price: 89.99, quantity: 1 }, { id: 'SKU-002', name: 'Athletic Socks', price: 14.99, quantity: 1 } ] }); ``` # locationId Source: https://docs.upstackdata.com/pixel/events/properties/location-id Store, affiliate, or location identifier. Store, affiliate, or location identifier. ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 134.99, currency: 'USD', locationId: 'store_nyc_001' }); ``` | Type | Required | Events | | ------ | -------- | ---------- | | string | No | All events | ## Use Cases * **Multi-location retail**: Track which store location drove the conversion * **Affiliate tracking**: Identify which affiliate partner referred the customer * **Franchise tracking**: Attribute conversions to specific franchise locations ## Related Properties <CardGroup> <Card title="creativeSlot" icon="table-cells" href="/pixel/events/properties/creative-slot"> Creative placement position. </Card> <Card title="promotionId" icon="bullhorn" href="/pixel/events/properties/promotion-id"> Promotion identifier. </Card> </CardGroup> # firstName / lastName Source: https://docs.upstackdata.com/pixel/events/properties/name Customer's name for identity resolution and destination matching. Customer's name. Used for identity resolution and destination matching. ```javascript theme={null} window._upstack('track', 'purchase', { firstName: 'Jane', lastName: 'Smith', email: 'jane.smith@example.com', transactionId: 'ORD-123', value: 149.99, currency: 'USD' }); ``` | Type | Required | Events | | ------ | -------- | ---------- | | string | No | All events | ## Privacy Names are normalized (lowercase, trimmed) and SHA-256 hashed before being sent to advertising destinations. ## Related Properties <CardGroup> <Card title="email" icon="envelope" href="/pixel/events/properties/email"> Customer email — primary identifier. </Card> <Card title="phone" icon="phone" href="/pixel/events/properties/phone"> Customer phone number. </Card> <Card title="Address Properties" icon="location-dot" href="/pixel/events/properties/address"> Shipping and billing address fields. </Card> </CardGroup> # orderName Source: https://docs.upstackdata.com/pixel/events/properties/order-name Human-readable order name shown to customers. Human-readable order name (e.g., the order number shown to customers). ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'shopify_order_5678901234', orderName: '#1042', // What the customer sees value: 149.99, currency: 'USD' }); ``` | Type | Required | Events | | ------ | -------- | -------- | | string | No | purchase | ## Related Properties <CardGroup> <Card title="transactionId" icon="fingerprint" href="/pixel/events/properties/transaction-id"> Unique order identifier for tracking. </Card> </CardGroup> # paymentType Source: https://docs.upstackdata.com/pixel/events/properties/payment-type Payment method used for checkout. Payment method used for checkout. ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 134.99, currency: 'USD', paymentType: 'credit_card' }); ``` | Type | Required | Events | | ------ | -------- | ---------------------------- | | string | No | purchase, add\_payment\_info | ## Common Values | Value | Description | | ------------- | -------------------- | | `credit_card` | Credit or debit card | | `paypal` | PayPal | | `shop_pay` | Shop Pay (Shopify) | | `apple_pay` | Apple Pay | | `google_pay` | Google Pay | | `klarna` | Klarna | | `afterpay` | Afterpay | <Note> These are suggested values. Any string is accepted. </Note> ## Related Properties <CardGroup> <Card title="shippingTier" icon="truck" href="/pixel/events/properties/shipping-tier"> Shipping tier selected. </Card> </CardGroup> # phone Source: https://docs.upstackdata.com/pixel/events/properties/phone Customer's phone number. E.164 format recommended. Customer's phone number. E.164 format recommended for best matching. ```javascript theme={null} window._upstack('track', 'lead', { email: 'customer@example.com', phone: '+15551234567', // E.164 format: +[country][number] value: 0, currency: 'USD' }); ``` | Type | Required | Events | | ------ | -------- | ----------------------------------- | | string | No | All events (improves match quality) | ## E.164 Format The E.164 format is the international standard for phone numbers: * Start with `+` followed by country code * No spaces, dashes, or parentheses * Example: `+15551234567` (US), `+442071234567` (UK) ## Privacy Phone numbers are normalized and SHA-256 hashed before being sent to destinations. ## Related Properties <CardGroup> <Card title="email" icon="envelope" href="/pixel/events/properties/email"> Customer email — primary identifier. </Card> <Card title="firstName / lastName" icon="user" href="/pixel/events/properties/name"> Customer name for identity resolution. </Card> </CardGroup> # promotionId Source: https://docs.upstackdata.com/pixel/events/properties/promotion-id Promotion or campaign identifier. Promotion or campaign identifier. ```javascript theme={null} window._upstack('track', 'view_content', { items: [{ id: 'SKU_001', name: 'Running Shoes', price: 89.99 }], value: 89.99, currency: 'USD', promotionId: 'SUMMER_SALE_2026' }); ``` | Type | Required | Events | | ------ | -------- | -------------------------------------- | | string | No | view\_content, add\_to\_cart, purchase | ## Related Properties <CardGroup> <Card title="promotionName" icon="tag" href="/pixel/events/properties/promotion-name"> Human-readable promotion name. </Card> <Card title="creativeName" icon="palette" href="/pixel/events/properties/creative-name"> Creative variant name. </Card> <Card title="creativeSlot" icon="table-cells" href="/pixel/events/properties/creative-slot"> Placement position on page. </Card> </CardGroup> # promotionName Source: https://docs.upstackdata.com/pixel/events/properties/promotion-name Human-readable promotion display name. Human-readable promotion display name. ```javascript theme={null} window._upstack('track', 'view_content', { items: [{ id: 'SKU_001', name: 'Running Shoes', price: 89.99 }], value: 89.99, currency: 'USD', promotionId: 'SUMMER_SALE_2026', promotionName: 'Summer Sale 2026' }); ``` | Type | Required | Events | | ------ | -------- | -------------------------------------- | | string | No | view\_content, add\_to\_cart, purchase | ## Related Properties <CardGroup> <Card title="promotionId" icon="fingerprint" href="/pixel/events/properties/promotion-id"> Promotion identifier. </Card> <Card title="creativeName" icon="palette" href="/pixel/events/properties/creative-name"> Creative variant name. </Card> </CardGroup> # Promotional Properties Source: https://docs.upstackdata.com/pixel/events/properties/promotional Properties for tracking promotions, campaigns, and affiliate activity — promotion IDs, creative names, and location tracking. Promotional properties help track on-site promotions, campaigns, and affiliate activity. ## Properties <CardGroup> <Card title="promotionId" icon="fingerprint" href="/pixel/events/properties/promotion-id"> Promotion/campaign identifier. </Card> <Card title="promotionName" icon="tag" href="/pixel/events/properties/promotion-name"> Promotion display name. </Card> <Card title="creativeName" icon="palette" href="/pixel/events/properties/creative-name"> Creative/ad variant name. </Card> <Card title="creativeSlot" icon="table-cells" href="/pixel/events/properties/creative-slot"> Placement position on page. </Card> <Card title="locationId" icon="location-dot" href="/pixel/events/properties/location-id"> Store/affiliate/location ID. </Card> </CardGroup> ## Quick Reference | Property | Type | Description | Events | | --------------- | ------ | ---------------------------------------- | -------------------------------------- | | `promotionId` | string | Promotion or campaign identifier | view\_content, add\_to\_cart, purchase | | `promotionName` | string | Promotion display name | view\_content, add\_to\_cart, purchase | | `creativeName` | string | Creative or ad variant name | view\_content, add\_to\_cart, purchase | | `creativeSlot` | string | Creative placement position | view\_content, add\_to\_cart, purchase | | `locationId` | string | Store, affiliate, or location identifier | All events | ## Example ```javascript theme={null} window._upstack('track', 'view_content', { items: [{ id: 'SKU_001', name: 'Running Shoes', price: 89.99 }], value: 89.99, currency: 'USD', promotionId: 'SUMMER_SALE_2026', promotionName: 'Summer Sale 2026', creativeName: 'hero_banner_v2', creativeSlot: 'homepage_hero', locationId: 'store_nyc_001' }); ``` ## Use Cases * **On-site promotions**: Track which banners and placements drive conversions * **Affiliate tracking**: Identify which partners referred customers * **Multi-location retail**: Attribute conversions to specific store locations # SaaS Event Properties Source: https://docs.upstackdata.com/pixel/events/properties/saas B2B/SaaS properties — account, subscription, trial, payment, seat, and churn tracking fields. For B2B/SaaS applications tracking accounts, subscriptions, trials, and recurring revenue. <Card title="SaaS Events Reference" icon="building" href="/pixel/saas-events"> See the complete SaaS Events Reference for event names, timing, and usage patterns. </Card> ## Account Properties | Property | Type | Description | Events | | ------------------ | ------ | ---------------------------------------------------------------------------- | ---------------------------------------------- | | `accountId` | string | Account or organization identifier | All SaaS events | | `accountName` | string | Account or organization display name | signup\_completed, account\_\* | | `accountCreatedAt` | string | ISO 8601 timestamp when account was created | signup\_completed | | `userId` | string | User identifier | signup\_completed, user\_joined, feature\_used | | `userEmail` | string | User's email address | signup\_completed, user\_joined | | `userRole` | string | User's role in the account: `"owner"`, `"admin"`, `"manager"`, or `"member"` | user\_joined, user\_\* | ## Subscription & Revenue Properties | Property | Type | Description | Events | | ----------------- | ------ | ------------------------------------------ | ---------------------------------------------------------------------------- | | `subscriptionId` | string | Subscription identifier | subscription\_*, trial\_*, payment\_\* | | `planId` | string | Plan identifier | trial\_*, subscription\_* | | `planName` | string | Human-readable plan name | trial\_*, subscription\_* | | `mrr` | number | Monthly recurring revenue in cents | subscription\_\*, trial\_converted | | `mrrDelta` | number | MRR change in cents (positive or negative) | subscription\_upgraded, subscription\_downgraded, seat\_added, seat\_removed | | `arr` | number | Annual recurring revenue in cents | subscription\_\*, trial\_converted | | `ltv` | number | Customer lifetime value in cents | subscription\_churned, account\_\* | | `billingInterval` | string | `"month"` or `"year"` | subscription\_*, payment\_* | ## Trial Properties | Property | Type | Description | Events | | -------------------- | ------ | ---------------------------------------- | ------------------------------------------- | | `trialDaysRemaining` | number | Days until trial expires | trial\_\* | | `trialStartDate` | string | ISO 8601 timestamp when trial started | trial\_started | | `trialEndDate` | string | ISO 8601 timestamp when trial ends/ended | trial\_\*, trial\_converted, trial\_expired | ## Payment Properties | Property | Type | Description | Events | | --------------- | ------ | -------------------------- | ----------------------------------- | | `invoiceId` | string | Invoice identifier | payment\_succeeded, payment\_failed | | `amount` | number | Payment amount in cents | payment\_succeeded, payment\_failed | | `failureReason` | string | Reason for payment failure | payment\_failed | ## Seat & Team Properties | Property | Type | Description | Events | | ----------- | ------ | ------------------------------------------------------ | -------------------------- | | `seatCount` | number | Total seats after change | seat\_added, seat\_removed | | `seatDelta` | number | Number of seats added (positive) or removed (negative) | seat\_added, seat\_removed | ## Add-on Properties | Property | Type | Description | Events | | ----------- | ------ | ------------------- | ---------------------------- | | `addonId` | string | Add-on identifier | addon\_added, addon\_removed | | `addonName` | string | Add-on display name | addon\_added, addon\_removed | ## Feature & Engagement Properties | Property | Type | Description | Events | | --------------- | ------ | --------------------------------------------------------- | -------------------------------------- | | `featureId` | string | Feature identifier | feature\_used, feature\_limit\_reached | | `featureName` | string | Feature display name | feature\_used, feature\_limit\_reached | | `usageInfo` | object | Usage details: `{ currentUsage, limit, usagePercentage }` | feature\_limit\_reached, usage\_\* | | `milestoneId` | string | Milestone identifier | milestone\_reached | | `milestoneName` | string | Milestone display name | milestone\_reached | ## Churn & Cancellation Properties | Property | Type | Description | Events | | ---------------- | ------ | ------------------------------------------- | ---------------------------------------------- | | `cancelReason` | string | Reason code for cancellation | subscription\_cancelled, subscription\_churned | | `cancelFeedback` | string | Free-text feedback from cancellation survey | subscription\_cancelled | | `cancelledAt` | string | ISO 8601 timestamp of cancellation | subscription\_cancelled, subscription\_churned | | `inactiveDays` | number | Days since last activity before churn | subscription\_churned | # searchTerm Source: https://docs.upstackdata.com/pixel/events/properties/search-term Search query entered by the user. Search query entered by the user. ```javascript theme={null} window._upstack('track', 'search', { searchTerm: 'blue running shoes', content_ids: ['SKU-001', 'SKU-002', 'SKU-003'] }); ``` | Type | Required | Events | | ------ | -------------- | ------ | | string | Yes for search | search | ## Related Properties <CardGroup> <Card title="content_ids" icon="list" href="/pixel/events/properties/content-ids"> Product IDs from search results. </Card> </CardGroup> # shipping Source: https://docs.upstackdata.com/pixel/events/properties/shipping Shipping cost for the order. Shipping cost for the order. ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 134.99, currency: 'USD', shipping: 8.00 }); ``` | Type | Required | Events | | ------ | -------- | ------------------------------------------------- | | number | No | purchase, initiate\_checkout, add\_shipping\_info | ## Related Properties <CardGroup> <Card title="shippingTier" icon="gauge-high" href="/pixel/events/properties/shipping-tier"> Shipping speed/tier selected. </Card> <Card title="tax" icon="percent" href="/pixel/events/properties/tax"> Tax amount. </Card> </CardGroup> # shippingTier Source: https://docs.upstackdata.com/pixel/events/properties/shipping-tier Shipping tier selected by the customer. Shipping tier selected by the customer. ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 134.99, currency: 'USD', shippingTier: 'express' }); ``` | Type | Required | Events | | ------ | -------- | ------------------------------------------------------- | | string | No | purchase, add\_shipping\_info, select\_shipping\_method | ## Common Values | Value | Description | | ----------- | ---------------------------- | | `standard` | Standard shipping (5-7 days) | | `express` | Express shipping (2-3 days) | | `overnight` | Next-day delivery | | `free` | Free shipping | | `pickup` | In-store pickup | <Note> These are suggested values. Any string is accepted. </Note> ## Related Properties <CardGroup> <Card title="shipping" icon="dollar-sign" href="/pixel/events/properties/shipping"> Shipping cost amount. </Card> <Card title="paymentType" icon="credit-card" href="/pixel/events/properties/payment-type"> Payment method used. </Card> </CardGroup> # subtotalPrice Source: https://docs.upstackdata.com/pixel/events/properties/subtotal-price Subtotal before tax and shipping. Subtotal before tax and shipping. ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 134.99, // Final total currency: 'USD', subtotalPrice: 149.99 // Before discounts/tax/shipping }); ``` | Type | Required | Events | | ------ | -------- | ---------------------------- | | number | No | purchase, initiate\_checkout | ## Related Properties <CardGroup> <Card title="value" icon="coins" href="/pixel/events/properties/value"> Final order total. </Card> <Card title="tax" icon="percent" href="/pixel/events/properties/tax"> Tax amount. </Card> <Card title="shipping" icon="truck" href="/pixel/events/properties/shipping"> Shipping cost. </Card> <Card title="discount" icon="tag" href="/pixel/events/properties/discount"> Discount amount applied. </Card> </CardGroup> # tax Source: https://docs.upstackdata.com/pixel/events/properties/tax Tax amount applied to the order. Tax amount applied to the order. ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-12345', value: 134.99, currency: 'USD', tax: 12.00 }); ``` | Type | Required | Events | | ------ | -------- | ---------------------------- | | number | No | purchase, initiate\_checkout | ## Related Properties <CardGroup> <Card title="subtotalPrice" icon="receipt" href="/pixel/events/properties/subtotal-price"> Subtotal before tax and shipping. </Card> <Card title="shipping" icon="truck" href="/pixel/events/properties/shipping"> Shipping cost. </Card> </CardGroup> # transactionId / orderId Source: https://docs.upstackdata.com/pixel/events/properties/transaction-id Unique identifier for the order. Use either transactionId or orderId. Unique identifier for the order. Use either `transactionId` or `orderId` — they're interchangeable. ```javascript theme={null} window._upstack('track', 'purchase', { transactionId: 'ORD-2026-001', // or orderId: 'ORD-2026-001' value: 149.99, currency: 'USD' }); ``` | Type | Required | Events | | ------ | ----------------------- | ---------------- | | string | Yes for purchase/refund | purchase, refund | <Note> For Shopify stores, this is typically the Shopify order ID (e.g., `shopify_order_5678901234`). </Note> ## Related Properties <CardGroup> <Card title="orderName" icon="hashtag" href="/pixel/events/properties/order-name"> Human-readable order number shown to customers. </Card> <Card title="value" icon="coins" href="/pixel/events/properties/value"> The monetary value of the order. </Card> </CardGroup> # value Source: https://docs.upstackdata.com/pixel/events/properties/value The monetary value of the event. Always pair with currency. The monetary value of the event. Always pair with `currency`. ```javascript theme={null} window._upstack('track', 'purchase', { value: 99.99, currency: 'USD' }); ``` | Type | Required | Events | | ------ | --------------------------------- | ------------------------------------------------------------------------------------------- | | number | Yes for purchase, lead, subscribe | purchase, add\_to\_cart, view\_content, initiate\_checkout, lead, subscribe, trial\_started | <Warning> For Purchase events, `value` should match the order total you want reported to ad platforms. Mismatched values between Shopify and your destinations are the most common attribution debugging issue. </Warning> ## Related Properties <CardGroup> <Card title="currency" icon="dollar-sign" href="/pixel/events/properties/currency"> ISO 4217 currency code — required with value. </Card> <Card title="subtotalPrice" icon="receipt" href="/pixel/events/properties/subtotal-price"> Subtotal before tax and shipping. </Card> </CardGroup> # purchase Event Source: https://docs.upstackdata.com/pixel/events/purchase Track when an order is completed Fires when an order is completed. This is the most important e-commerce event — it's used for conversion tracking, ROAS calculation, and optimization across all ad platforms. <Note> **Shopify:** Automatically tracked on the order confirmation page (thank you page) and via server-side webhooks. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'purchase', { orderId: 'ORD_12345', value: 149.99, currency: 'USD', tax: 12.50, shipping: 5.99, items: [ { id: 'SKU_001', name: 'Blue Running Shoes', price: 89.99, quantity: 1, brand: 'Nike', category: 'Shoes/Running' }, { id: 'SKU_002', name: 'Running Socks', price: 14.99, quantity: 2, brand: 'Nike', category: 'Accessories/Socks' } ], email: 'customer@example.com' }, 'ORD_12345'); ``` <Note> The third parameter (`'ORD_12345'`) is a deduplication ID. It prevents duplicate purchase events from being sent to destinations if the event fires multiple times. </Note> Minimal example: ```javascript theme={null} window._upstack('track', 'purchase', { orderId: 'ORD_12345', value: 149.99, currency: 'USD', items: [{ id: 'SKU_001', name: 'Blue Running Shoes', price: 89.99, quantity: 1 }] }, 'ORD_12345'); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | -------------------------------------------------------------------------- | | orderId | string | Yes | Unique order identifier | | value | number | Yes | Total order value | | currency | string | Yes | ISO 4217 currency code | | items | array | Yes | Products purchased (see [Item Object](/pixel/standard-events#item-object)) | | tax | number | No | Tax amount | | shipping | number | No | Shipping cost | | email | string | No | Customer email (improves identity matching) | <Warning> **Important:** The `value` property should match what you want reported to ad platforms. Discrepancies between Shopify order totals and reported CAPI revenue are the most common attribution debugging issue. </Warning> ## When to Fire * Order confirmation page load * After successful payment confirmation * Shopify `orders/create` webhook (server-side) ## Related Events * [initiate\_checkout](/pixel/events/initiate-checkout) — Starting the checkout * [add\_payment\_info](/pixel/events/add-payment-info) — Before completing purchase * [refund](/pixel/events/refund) — When order is refunded # quiz_completed Event Source: https://docs.upstackdata.com/pixel/events/quiz-completed Track when a visitor completes a quiz or assessment Fires when a visitor completes a quiz, product recommendation quiz, or assessment. This is a recommended custom event for tracking quiz funnels and product discovery flows. <Note> **Custom Event** — This event is not automatically tracked. Fire it manually using the JavaScript SDK when a quiz is completed. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'quiz_completed', { quiz_id: 'skin-type-finder', quiz_name: 'Find Your Perfect Skincare Routine', result_id: 'oily-acne-prone', result_name: 'Oily & Acne-Prone Skin', questions_answered: 8, time_to_complete: 145, value: 25.00, currency: 'USD' }); ``` Quiz with product recommendations: ```javascript theme={null} window._upstack('track', 'quiz_completed', { quiz_id: 'gift-finder', quiz_name: 'Holiday Gift Finder', result_id: 'tech-enthusiast', recommended_products: ['SKU-1234', 'SKU-5678', 'SKU-9012'], questions_answered: 5 }); ``` ## Properties | Property | Type | Required | Description | | --------------------- | --------- | -------- | --------------------------------------------- | | quiz\_id | string | Yes | Unique identifier for the quiz | | quiz\_name | string | No | Human-readable quiz title | | result\_id | string | No | Identifier for the quiz result or outcome | | result\_name | string | No | Human-readable result description | | questions\_answered | number | No | Total questions completed | | time\_to\_complete | number | No | Seconds from quiz start to completion | | recommended\_products | string\[] | No | Array of product SKUs recommended by the quiz | | value | number | No | Estimated value of the quiz completion | | currency | string | No | ISO 4217 currency code | ## When to Fire * Product recommendation quiz completion * Skin type or style finder completion * Gift guide quiz completion * Assessment or diagnostic quiz completion * Personality quiz completion ## Destination Support | Destination | Support | | --------------------- | --------------------------------------------------------------------------------- | | **Meta CAPI** | Supported as `Custom` event type. Use for building audiences of quiz completers. | | **TikTok Events API** | Supported. Use for audience building. | | **Klaviyo** | Fully supported. Triggers flows based on quiz results for personalized follow-up. | | **GA4** | Supported. Maps to custom event with parameters. | | **Webhook** | Fully supported. Raw payload forwarded. | <Tip> **Personalization tip:** Pass the `result_id` to Klaviyo to trigger personalized email flows based on quiz outcomes. Segment customers by their quiz results for targeted product recommendations. </Tip> ## Related Events * [quiz\_question\_answered](/pixel/events/quiz-question-answered) — Track individual question responses * [lead](/pixel/events/lead) — For capturing contact info during or after quiz * [view\_content](/pixel/events/view-content) — When quiz results include product views # Quiz Events Source: https://docs.upstackdata.com/pixel/events/quiz-events Track quiz funnels and product recommendation flows with quiz_completed and quiz_question_answered events. Quiz events help you track product recommendation quizzes, style finders, assessments, and other interactive quiz experiences. Use these events to understand quiz completion rates, segment customers by quiz results, and trigger personalized follow-up flows. <Note> **Custom Events** — Quiz events are not automatically tracked. Fire them manually using the JavaScript SDK at the appropriate points in your quiz flow. </Note> ## Available Events <CardGroup> <Card title="quiz_completed" icon="flag-checkered" href="/pixel/events/quiz-completed"> Fires when a visitor completes a quiz. Captures the result, recommended products, and completion time. </Card> <Card title="quiz_question_answered" icon="circle-question" href="/pixel/events/quiz-question-answered"> Fires when a visitor answers an individual question. Use for funnel analysis and drop-off tracking. </Card> </CardGroup> ## Use Cases ### Product Recommendation Quizzes Track quizzes that help customers find the right product: ```javascript theme={null} // Track each question for funnel analysis window._upstack('track', 'quiz_question_answered', { quiz_id: 'skin-type-finder', question_id: 'q1', question_text: 'What is your skin type?', answer_id: 'oily', answer_text: 'Oily', question_number: 1, total_questions: 5 }); // Track quiz completion with results window._upstack('track', 'quiz_completed', { quiz_id: 'skin-type-finder', quiz_name: 'Find Your Perfect Skincare Routine', result_id: 'oily-acne-prone', result_name: 'Oily & Acne-Prone Skin', recommended_products: ['SKU-1234', 'SKU-5678'], questions_answered: 5, time_to_complete: 120 }); ``` ### Funnel Analysis Track `quiz_question_answered` for each question to identify where users drop off: | Question | Started | Completed | Drop-off | | ------------- | ------- | --------- | --------- | | Q1: Skin Type | 1,000 | 920 | 8% | | Q2: Concerns | 920 | 850 | 7.6% | | Q3: Budget | 850 | 780 | 8.2% | | Q4: Routine | 780 | 750 | 3.8% | | Q5: Products | 750 | 720 | 4% | | **Completed** | — | 720 | 28% total | ### Klaviyo Personalization Use quiz results to trigger personalized email flows: 1. Fire `quiz_completed` with `result_id` and `result_name` 2. In Klaviyo, create a flow triggered by the `quiz_completed` event 3. Use the `result_id` property to branch into different email sequences 4. Include `recommended_products` in product recommendation blocks ## Destination Support | Destination | quiz\_completed | quiz\_question\_answered | | --------------------- | ------------------------------ | ------------------------ | | **Meta CAPI** | ✅ Custom event | ✅ Custom event | | **TikTok Events API** | ✅ Supported | ✅ Supported | | **Klaviyo** | ✅ Full support with properties | ✅ Full support | | **GA4** | ✅ Custom event | ✅ Custom event | | **Webhook** | ✅ Raw payload | ✅ Raw payload | <Tip> **Best practice:** Always include `quiz_id` on both events so you can correlate question-level data with completion data in your analytics. </Tip> ## Related * [Custom Events](/pixel/events/custom-events) — General guide for firing custom events * [lead](/pixel/events/lead) — Capture contact info during or after quiz * [view\_content](/pixel/events/view-content) — Track when quiz results show product recommendations # quiz_question_answered Event Source: https://docs.upstackdata.com/pixel/events/quiz-question-answered Track individual quiz question responses for funnel analysis Fires when a visitor answers a question in a quiz or assessment. This is a recommended custom event for tracking quiz progress, identifying drop-off points, and analyzing answer patterns. <Note> **Custom Event** — This event is not automatically tracked. Fire it manually using the JavaScript SDK after each question is answered. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'quiz_question_answered', { quiz_id: 'skin-type-finder', question_id: 'q3_skin_concerns', question_number: 3, question_text: 'What are your primary skin concerns?', answer_id: 'acne', answer_text: 'Acne & Breakouts', total_questions: 8 }); ``` Multiple-choice question with multiple answers: ```javascript theme={null} window._upstack('track', 'quiz_question_answered', { quiz_id: 'gift-finder', question_id: 'q2_interests', question_number: 2, question_text: 'What are their interests?', answer_ids: ['tech', 'outdoors', 'cooking'], answer_texts: ['Technology', 'Outdoors & Adventure', 'Cooking & Food'], total_questions: 5 }); ``` ## Properties | Property | Type | Required | Description | | ------------------ | --------- | -------- | ----------------------------------------- | | quiz\_id | string | Yes | Unique identifier for the quiz | | question\_id | string | Yes | Unique identifier for the question | | question\_number | number | No | Position of the question (1-indexed) | | question\_text | string | No | The question text displayed to the user | | answer\_id | string | No | Identifier for single-choice answer | | answer\_ids | string\[] | No | Identifiers for multiple-choice answers | | answer\_text | string | No | Display text for single-choice answer | | answer\_texts | string\[] | No | Display texts for multiple-choice answers | | total\_questions | number | No | Total number of questions in the quiz | | time\_on\_question | number | No | Seconds spent on this question | ## When to Fire * After each quiz question is submitted * When a user selects an answer (if auto-advancing) * When moving to the next question in a multi-step quiz ## Destination Support | Destination | Support | | --------------------- | ------------------------------------------------------------------------------------ | | **Meta CAPI** | Supported as `Custom` event type. Build audiences based on specific answer patterns. | | **TikTok Events API** | Supported. Use for audience building. | | **Klaviyo** | Fully supported. Track answer patterns for segmentation. | | **GA4** | Supported. Use for funnel analysis and drop-off tracking. | | **Webhook** | Fully supported. Raw payload forwarded. | <Tip> **Funnel analysis tip:** Track `question_number` and `total_questions` to identify where users drop off. High drop-off on a specific question may indicate confusing wording or too many options. </Tip> ## Related Events * [quiz\_completed](/pixel/events/quiz-completed) — Fire when the quiz is finished * [lead](/pixel/events/lead) — If capturing contact info mid-quiz # refund Event Source: https://docs.upstackdata.com/pixel/events/refund Track when an order is refunded Fires when an order is refunded. This helps maintain accurate revenue reporting and adjusts conversion data for ad platforms that support refund events. <Note> **Shopify:** Automatically tracked via the `refunds/create` webhook (server-side). </Note> ## JavaScript Full refund: ```javascript theme={null} window._upstack('track', 'refund', { orderId: 'ORD_12345', value: 149.99, currency: 'USD' }); ``` Partial refund: ```javascript theme={null} window._upstack('track', 'refund', { orderId: 'ORD_12345', value: 89.99, currency: 'USD', items: [ { id: 'SKU_001', name: 'Blue Running Shoes', price: 89.99, quantity: 1 } ] }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------------------- | | orderId | string | Yes | Original order identifier | | value | number | Yes | Refund amount | | currency | string | No | ISO 4217 currency code | | items | array | No | Products refunded (for partial refunds) | ## When to Fire * Refund processed via Shopify admin * `refunds/create` webhook (server-side) * Customer service refund action ## Related Events * [purchase](/pixel/events/purchase) — The original order event # schedule Event Source: https://docs.upstackdata.com/pixel/events/schedule Track when a user schedules an appointment Fires when a user schedules an appointment. Use this for service-based businesses where customers book appointments, fittings, or consultations. <Note> **Shopify:** Manual implementation required. Integrate with your scheduling system. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'schedule', { appointmentType: 'fitting', value: 75.00, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ---------------------- | | appointmentType | string | No | Type of appointment | | value | number | No | Service value | | currency | string | No | ISO 4217 currency code | ## When to Fire * Appointment booking confirmation * Service scheduling completion ## Related Events * [book\_call](/pixel/events/book-call) — For sales calls and consultations * [lead](/pixel/events/lead) — For general lead capture # search Event Source: https://docs.upstackdata.com/pixel/events/search Track when a visitor performs a search Fires when a visitor performs a search. This helps understand what customers are looking for and can inform product decisions and SEO strategy. <Note> **Shopify:** Automatically tracked when using Shopify's native search functionality. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'search', { searchTerm: 'blue running shoes', resultsCount: 24 }); ``` With search results: ```javascript theme={null} window._upstack('track', 'search', { searchTerm: 'blue running shoes', resultsCount: 24, items: [ { id: 'SKU_001', name: 'Blue Running Shoes', price: 89.99 }, { id: 'SKU_002', name: 'Navy Training Shoes', price: 79.99 } ] }); ``` ## Properties | Property | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------ | | searchTerm | string | Yes | The search query entered | | resultsCount | number | No | Number of results returned | | items | array | No | Top products in search results | ## When to Fire * Search results page load * Predictive search dropdown display * "No results" page (with `resultsCount: 0`) ## Related Events * [view\_content](/pixel/events/view-content) — When clicking on a search result * [view\_item\_list](/pixel/events/view-item-list) — For displaying search results as a list # select_shipping_method Event Source: https://docs.upstackdata.com/pixel/events/select-shipping-method Track when a customer selects a shipping method during checkout Fires when a customer selects a shipping method during checkout. This helps understand shipping preferences and their impact on conversion. <Note> **Shopify:** Manual implementation required. Not automatically tracked. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'select_shipping_method', { shippingTier: 'express', shipping: 12.99, currency: 'USD', value: 97.98 }); ``` With items: ```javascript theme={null} window._upstack('track', 'select_shipping_method', { shippingTier: 'overnight', shipping: 24.99, currency: 'USD', value: 109.98, items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2 } ] }); ``` ## Properties | Property | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------------------------------------- | | shippingTier | string | Yes | Shipping method selected (e.g., `'standard'`, `'express'`, `'overnight'`) | | shipping | number | No | Shipping cost | | value | number | No | Cart value at shipping selection | | currency | string | No | ISO 4217 currency code | | items | array | No | Products in checkout | ## When to Fire * Shipping method radio button selection * Shipping tier dropdown change * Before proceeding to payment ## Related Events * [add\_shipping\_info](/pixel/events/add-shipping-info) — When entering shipping address * [add\_payment\_info](/pixel/events/add-payment-info) — After entering payment details # sign_up Event Source: https://docs.upstackdata.com/pixel/events/sign-up Track when a user creates a new account Fires when a user creates a new account. Use this for simple account creation flows. <Note> **Shopify:** Manual implementation required. Not automatically tracked. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'sign_up', { method: 'email' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------------------------------- | | method | string | No | Signup method (`'email'`, `'google'`, `'facebook'`) | <Note> **sign\_up vs complete\_registration:** Use `sign_up` for initial account creation. Use `complete_registration` for multi-step registration flows or when capturing additional profile data. </Note> ## When to Fire * Account creation form submission * OAuth signup completion ## Related Events * [complete\_registration](/pixel/events/complete-registration) — For multi-step registration * [login](/pixel/events/login) — When existing users log in # submit_application Event Source: https://docs.upstackdata.com/pixel/events/submit-application Track when a user submits an application Fires when a user submits an application. Use this for wholesale applications, affiliate program signups, partnership requests, and similar high-value lead capture. <Note> **Shopify:** Manual implementation required. Integrate with your application forms. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'submit_application', { applicationType: 'wholesale_partner', value: 5000.00, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | --------------------------- | | applicationType | string | No | Application type | | value | number | No | Estimated application value | | currency | string | No | ISO 4217 currency code | ## When to Fire * Wholesale application submission * Affiliate program application * Partnership request ## Related Events * [lead](/pixel/events/lead) — For general lead capture * [complete\_registration](/pixel/events/complete-registration) — For account signups # subscribe Event Source: https://docs.upstackdata.com/pixel/events/subscribe Track when a visitor subscribes to email or SMS marketing Fires when a visitor subscribes to email or SMS marketing. This helps track marketing list growth and attribute new subscribers to campaigns. <Note> **Shopify:** Tracked via popup/form hooks when using compatible email/SMS apps. Manual implementation may be required for custom forms. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'subscribe', { channel: 'email', source: 'footer_form', value: 5.00, currency: 'USD' }); ``` SMS subscription: ```javascript theme={null} window._upstack('track', 'subscribe', { channel: 'sms', source: 'popup', phone: '+15551234567' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------------------------------------------- | | channel | string | No | Subscription channel (`'email'`, `'sms'`, `'push'`) | | source | string | No | Subscription source (e.g., `'popup'`, `'footer'`, `'checkout'`) | | value | number | No | Estimated subscriber value | | currency | string | No | ISO 4217 currency code | ## When to Fire * Newsletter signup * SMS opt-in * Push notification subscription ## Related Events * [lead](/pixel/events/lead) — For general lead capture * [complete\_registration](/pixel/events/complete-registration) — For account creation # Event Taxonomy Source: https://docs.upstackdata.com/pixel/events/taxonomy Reference for the Upstack Data event model — 25 standard events, how they flow from capture through identity resolution and enrichment to destination forwarding. Every interaction a customer has with your website generates an event. Upstack Data captures these events server-side, enriches them with identity and product data, and forwards them to your configured destinations. <Tip> Upstack tracks 25 standard events. **Shopify stores** see events tracked automatically via the theme app extension. **Custom implementations** (headless, GTM, non-Shopify platforms) can fire the same events using the [JavaScript SDK](/pixel/javascript-sdk). </Tip> ## How Events Are Captured The **Upstack Pixel** is a lightweight JavaScript snippet that runs on your website. When a visitor performs an action — viewing a page, adding a product to cart, completing a purchase — the pixel fires an event to the Upstack edge API. <Note> **Shopify stores:** The pixel is injected automatically via the theme app extension. **Custom implementations:** Add the pixel snippet to your site's `<head>` — see [Pixel Setup](/pixel/setup). </Note> From there, events flow through a four-stage pipeline: 1. **Capture** — Upstack Pixel detects the interaction and sends a structured event payload to the Cloudflare edge API. 2. **Resolve** — Upstack ID attaches identity data (email, phone, cookie, device) to the event, linking anonymous sessions to known customers. 3. **Enrich** — Product catalog data, UTM parameters, and click IDs are merged into the event. 4. **Activate** — The enriched event is forwarded to each configured destination (Meta CAPI, TikTok, Klaviyo, GA4, etc.) in the format each platform expects. ## Standard Event Taxonomy Standard events have well-defined names, properties, and semantics that all destinations understand. Using standard events ensures compatibility across your entire marketing stack. ### Page & Browse Events | Event Name | When It Fires | Key Properties | | -------------------- | -------------------------------------------------------- | ------------------------------------- | | **page\_view** | Every page load | `pageUrl`, `pageTitle`, `referrer` | | **view\_content** | Product page viewed | `items`, `value`, `currency` | | **view\_category** | Collection or category page viewed | `items`, `value`, `currency` | | **view\_item\_list** | Product list displayed (search results, recommendations) | `items`, `listId`, `listName` | | **view\_cart** | Cart page viewed | `items`, `value`, `currency` | | **search** | Site search performed | `searchTerm`, `resultsCount`, `items` | ### Cart Events | Event Name | When It Fires | Key Properties | | -------------------------------- | ---------------------- | ---------------------------- | | **add\_to\_cart** | Item added to cart | `items`, `value`, `currency` | | **product\_removed\_from\_cart** | Item removed from cart | `items`, `value`, `currency` | | **add\_to\_wishlist** | Item added to wishlist | `items`, `value`, `currency` | ### Checkout Events | Event Name | When It Fires | Key Properties | | ---------------------------- | ------------------------ | -------------------------------------------- | | **initiate\_checkout** | Checkout flow started | `items`, `value`, `currency` | | **add\_shipping\_info** | Shipping details entered | `items`, `value`, `currency`, `shippingTier` | | **select\_shipping\_method** | Shipping method selected | `items`, `value`, `currency`, `shippingTier` | | **add\_payment\_info** | Payment method entered | `items`, `value`, `currency`, `paymentType` | ### Order Events | Event Name | When It Fires | Key Properties | | ------------ | -------------------------------- | ---------------------------------------------------------- | | **purchase** | Order completed | `orderId`, `items`, `value`, `currency`, `tax`, `shipping` | | **refund** | Order refunded (full or partial) | `orderId`, `items`, `value`, `currency` | ### Conversion Events | Event Name | When It Fires | Key Properties | | ----------------------- | ------------------------- | ---------------------------------- | | **lead** | Lead form submitted | `value`, `currency`, `leadType` | | **subscribe** | Email or SMS subscription | `value`, `currency` | | **trial\_started** | Free trial initiated | `value`, `currency`, `trialLength` | | **contact** | Contact form submitted | `value`, `currency` | | **book\_call** | Call or demo booked | `value`, `currency` | | **schedule** | Appointment scheduled | `value`, `currency` | | **submit\_application** | Application submitted | `value`, `currency` | ### Account Events | Event Name | When It Fires | Key Properties | | -------------------------- | ----------------------------------- | ------------------- | | **complete\_registration** | Account created (post-verification) | `value`, `currency` | | **sign\_up** | Sign-up form submitted | `value`, `currency` | | **login** | User logged in | — | ### Quiz Events | Event Name | When It Fires | Key Properties | | ---------------------------- | --------------------------------- | -------------------------------------------- | | **quiz\_completed** | Quiz or assessment finished | `quiz_id`, `result_id`, `questions_answered` | | **quiz\_question\_answered** | Individual quiz question answered | `quiz_id`, `question_id`, `answer_id` | <Note> Quiz events are **custom events** — fire them manually using the JavaScript SDK. See [quiz\_completed](/pixel/events/quiz-completed) and [quiz\_question\_answered](/pixel/events/quiz-question-answered) for implementation details. </Note> <Note> All standard events include automatic context fields — `pageUrl`, `userAgent`, `ipAddress`, `eventTime`, and identity signals — regardless of the event type. See [Properties](/pixel/properties) for the full reference. </Note> ## How Destinations Receive Events Each destination maps standard events to its own naming convention. For example, an Upstack `purchase` event becomes: * A Meta CAPI `Purchase` event with hashed `em`, `ph`, and `fbclid` match keys * A TikTok Events API `CompletePayment` event with `ttclid` attached * A Klaviyo `Placed Order` event with full product details * A GA4 `purchase` event with `transaction_id` and line items You configure which events each destination receives in the Upstack dashboard. Upstack handles the schema transformation automatically. ## What's Next <CardGroup> <Card title="Standard Events Reference" icon="list-check" href="/pixel/standard-events"> Full specification for every standard event — required properties, optional fields, and example payloads. </Card> <Card title="SaaS & B2B Events" icon="building" href="/pixel/saas-events"> Events for subscription businesses — trials, billing, expansion, and engagement. </Card> <Card title="Custom Events" icon="code" href="/pixel/events/custom-events"> Define your own events to capture interactions beyond the standard taxonomy. </Card> <Card title="Properties & Context" icon="table" href="/pixel/properties"> Complete reference for all user data, custom data, and context fields attached to events. </Card> <Card title="Identity & Stitching" icon="link" href="/pixel/identity-stitching"> How Upstack ID enriches events with resolved identity data. </Card> </CardGroup> # trial_started Event Source: https://docs.upstackdata.com/pixel/events/trial-started Track when a visitor begins a free trial Fires when a visitor begins a free trial. This is a key conversion event for SaaS and subscription businesses to track trial signups and optimize acquisition campaigns. <Note> **Shopify:** Manual implementation required. Integrate with your subscription/trial system. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'trial_started', { planName: 'Premium Plan', trialDays: 14, value: 49.99, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | --------- | ------ | -------- | -------------------------- | | planName | string | No | Trial plan or product name | | trialDays | number | No | Trial duration in days | | value | number | No | Plan value after trial | | currency | string | No | ISO 4217 currency code | ## When to Fire * Trial signup confirmation * Trial activation ## Related Events * [sign\_up](/pixel/events/sign-up) — For account creation * [purchase](/pixel/events/purchase) — When trial converts to paid # all_purchase Event Source: https://docs.upstackdata.com/pixel/events/upstack-generated/all-purchase Track all purchases with unified customer segmentation — automatically generated by Upstack <Info> **Automatically Generated** — This event is created by Upstack backend services for Shopify customers. You do not need to fire this event manually. </Info> ## Overview The `all_purchase` event is generated for every purchase, regardless of customer type. It provides a unified purchase event that includes customer segmentation metadata, making it ideal for destinations that need a single purchase event with segmentation data attached. ## How It Works When a purchase occurs, Upstack generates an `all_purchase` event alongside the standard `purchase` event: 1. **Order received** — Shopify sends a purchase webhook to Upstack 2. **Customer analysis** — Upstack determines customer type (new, returning, lapsed, etc.) 3. **Event generation** — An `all_purchase` event is created with segmentation metadata 4. **Forwarding** — The event is sent to configured destinations This event is useful when you want all purchases sent to a destination but still need to segment by customer type in your reporting. ## Properties This event includes all properties from the original `purchase` event: | Property | Type | Description | | -------- | ------ | ---------------------------------------- | | orderId | string | Shopify order ID | | value | number | Order total value | | currency | string | ISO 4217 currency code (e.g., `USD`) | | items | array | Products purchased | | email | string | Customer email (hashed for destinations) | | phone | string | Customer phone (hashed for destinations) | ## Destination Mapping This event is forwarded to destinations as: | Destination | Event Name | Notes | | --------------------- | ----------------- | ----------------------------------------- | | **Meta CAPI** | `Purchase` | Standard purchase with all customer types | | **Google Ads** | `purchase` | Unified purchase event | | **TikTok Events API** | `CompletePayment` | All purchases | | **Klaviyo** | `Placed Order` | All orders | | **GA4** | `purchase` | Standard e-commerce purchase | ## Use Cases * **Unified reporting** — Single event stream that includes all purchase types * **Destination simplification** — Send one purchase event type instead of managing multiple * **Consistent attribution** — Ensure all purchases contribute to campaign optimization equally * **Baseline metrics** — Track total purchases before segmenting by customer type ## Relationship to Other Events The `all_purchase` event represents the union of: * `nc_purchase` — New customer purchases * `rc_purchase` — Returning customer purchases Every purchase generates both an `all_purchase` event AND one of the customer-type-specific events (`nc_purchase` or `rc_purchase`). ## Related Events * [purchase](/pixel/standard-events#purchase) — The base purchase event * [nc\_purchase](/pixel/events/upstack-generated/nc-purchase) — New customer purchases only * [rc\_purchase](/pixel/events/upstack-generated/rc-purchase) — Returning customer purchases only # AOV Purchase Events Source: https://docs.upstackdata.com/pixel/events/upstack-generated/aov-events Track purchases segmented by average order value — automatically generated by Upstack <Info> **Automatically Generated** — These events are created by Upstack backend services for Shopify customers. You do not need to fire these events manually. </Info> ## Overview Upstack automatically generates AOV (Average Order Value) segmented purchase events based on your store's order value distribution. These events help you optimize campaigns for high-value customers and understand the revenue impact of different customer segments. ## Event Types | Event Name | Description | | ------------------- | ---------------------------------------------- | | `high_aov_purchase` | Purchase with above-average order value | | `low_aov_purchase` | Purchase with below-average order value | | `p70_aov_purchase` | Purchase above the 70th percentile order value | | `p80_aov_purchase` | Purchase above the 80th percentile order value | | `p90_aov_purchase` | Purchase above the 90th percentile order value | ## How It Works When a purchase occurs, Upstack calculates AOV thresholds based on your store's historical order data: 1. **Order received** — Shopify sends a purchase webhook to Upstack 2. **Threshold calculation** — Upstack computes percentile thresholds from your order history 3. **Classification** — The order value is compared against these thresholds 4. **Event generation** — The appropriate AOV event(s) are generated 5. **Forwarding** — Events are sent to your configured destinations ### Threshold Definitions | Event | Threshold Logic | | ------------------- | ------------------------------------------- | | `high_aov_purchase` | Order value > store's average order value | | `low_aov_purchase` | Order value ≤ store's average order value | | `p70_aov_purchase` | Order value > 70th percentile of all orders | | `p80_aov_purchase` | Order value > 80th percentile of all orders | | `p90_aov_purchase` | Order value > 90th percentile of all orders | <Note> Thresholds are calculated dynamically based on your store's recent order history. As your average order value changes, the classification adjusts automatically. </Note> ## Properties These events include all properties from the original `purchase` event: | Property | Type | Description | | -------- | ------ | ---------------------------------------- | | orderId | string | Shopify order ID | | value | number | Order total value | | currency | string | ISO 4217 currency code (e.g., `USD`) | | items | array | Products purchased | | email | string | Customer email (hashed for destinations) | | phone | string | Customer phone (hashed for destinations) | ## Destination Mapping AOV events are forwarded to destinations as: | Destination | Event Name | Notes | | --------------------- | ----------------- | -------------------------------- | | **Meta CAPI** | `Purchase` | With AOV segment in custom data | | **Google Ads** | `purchase` | Filterable by event name | | **TikTok Events API** | `CompletePayment` | AOV segment included | | **Klaviyo** | `Placed Order` | Tagged with AOV tier | | **GA4** | `purchase` | Custom dimension for AOV segment | ## Use Cases ### Optimize for High-Value Customers Use `high_aov_purchase` or `p90_aov_purchase` events to train ad algorithms to find customers who spend more: * Configure Meta CAPI to optimize for `high_aov_purchase` instead of all purchases * Build lookalike audiences from high-AOV customers * Set higher bids for campaigns driving premium purchases ### Identify Discount-Driven Traffic Use `low_aov_purchase` events to understand which channels drive bargain shoppers: * Compare high vs. low AOV by traffic source * Identify campaigns that attract discount-seekers * Adjust targeting to improve order values ### Revenue-Weighted Attribution Use percentile events for more accurate revenue attribution: * `p90_aov_purchase` — Focus on your most valuable 10% of orders * `p80_aov_purchase` — Track premium customer acquisition * `p70_aov_purchase` — Identify above-average performers ## Event Overlap A single purchase may generate multiple AOV events. For example, a purchase in the 95th percentile generates: * `high_aov_purchase` (above average) * `p70_aov_purchase` (above 70th percentile) * `p80_aov_purchase` (above 80th percentile) * `p90_aov_purchase` (above 90th percentile) Choose the threshold that best matches your optimization goals. ## Related Events * [purchase](/pixel/standard-events#purchase) — The base purchase event * [nc\_purchase](/pixel/events/upstack-generated/nc-purchase) — New customer purchases * [rc\_purchase](/pixel/events/upstack-generated/rc-purchase) — Returning customer purchases * [all\_purchase](/pixel/events/upstack-generated/all-purchase) — All purchases # Upstack-Generated Events Source: https://docs.upstackdata.com/pixel/events/upstack-generated/index Events automatically generated by Upstack backend for Shopify customers — purchase segmentation, AOV tiers, and subscription tracking <Info> **Automatically Generated** — All events in this section are created by Upstack backend services for Shopify customers. You do not need to fire these events manually — they appear in your destinations automatically based on purchase data analysis. </Info> ## Overview Upstack automatically generates enriched purchase events that segment your customers beyond the standard `purchase` event. These events enable more sophisticated ad optimization, better attribution, and deeper customer insights. When a purchase occurs in your Shopify store, Upstack's backend analyzes the order and customer history to generate additional events alongside the standard `purchase` event. ## Available Events ### Customer Type Events | Event | Description | Link | | ----------------- | -------------------------------------------- | ---------------------------------------------------------------- | | `nc_purchase` | New customer purchases (first-time buyers) | [Documentation](/pixel/events/upstack-generated/nc-purchase) | | `rc_purchase` | Returning customer purchases (repeat buyers) | [Documentation](/pixel/events/upstack-generated/rc-purchase) | | `all_purchase` | All purchases (combines NC + RC) | [Documentation](/pixel/events/upstack-generated/all-purchase) | | `lapsed_purchase` | Purchases from lapsed customers who returned | [Documentation](/pixel/events/upstack-generated/lapsed-purchase) | | `upsell_purchase` | Upsell conversions | [Documentation](/pixel/events/upstack-generated/upsell-purchase) | ### AOV-Segmented Events | Event | Description | Link | | ------------------- | ----------------------------------- | ----------------------------------------------------------- | | `high_aov_purchase` | Purchases above average order value | [Documentation](/pixel/events/upstack-generated/aov-events) | | `low_aov_purchase` | Purchases below average order value | [Documentation](/pixel/events/upstack-generated/aov-events) | | `p70_aov_purchase` | Purchases above 70th percentile | [Documentation](/pixel/events/upstack-generated/aov-events) | | `p80_aov_purchase` | Purchases above 80th percentile | [Documentation](/pixel/events/upstack-generated/aov-events) | | `p90_aov_purchase` | Purchases above 90th percentile | [Documentation](/pixel/events/upstack-generated/aov-events) | ### Subscription Events | Event | Description | Link | | --------------------------------- | --------------------------------- | ----------------------------------------------------------------------------- | | `subscription_initial_purchase` | First-time subscription purchases | [Documentation](/pixel/events/upstack-generated/subscription-purchase-events) | | `subscription_recurring_purchase` | Recurring subscription renewals | [Documentation](/pixel/events/upstack-generated/subscription-purchase-events) | ## How They Work ```mermaid theme={null} flowchart LR A[Shopify Webhook] --> B[Upstack Backend] B --> C{Customer Analysis} C --> D[NC/RC Classification] C --> E[AOV Segmentation] C --> F[Subscription Detection] C --> G[Lapsed Detection] D --> H[Destination Events] E --> H F --> H G --> H ``` 1. **Shopify sends a purchase webhook** to Upstack when an order is placed 2. **Upstack analyzes** the customer's order history, order value, and subscription status 3. **Multiple events are generated** based on the analysis (e.g., both `nc_purchase` and `high_aov_purchase` for a high-value first-time buyer) 4. **Events are forwarded** to your configured destinations with proper attribution ## Why Use These Events? ### Better Ad Optimization Instead of optimizing for all purchases equally, train ad algorithms to find: * **New customers** — Reduce wasted spend on existing customers * **High-AOV customers** — Find customers who spend more * **Subscription-likely customers** — Acquire subscribers with higher LTV ### More Accurate Attribution Understand which campaigns drive: * True customer acquisition (not just repeat purchases) * Premium customers (high AOV) * Subscription sign-ups vs. one-time purchases * Win-back conversions from lapsed customers ### Deeper Insights Compare performance across customer segments: * New vs. returning customer CAC * High vs. low AOV by channel * Subscription acquisition costs * Win-back campaign effectiveness ## Destination Support All Upstack-generated events are forwarded to your configured destinations: | Destination | Support | Notes | | ----------------- | ------- | ----------------------------------------- | | Meta CAPI | ✅ Full | Event name + custom data for segmentation | | Google Ads | ✅ Full | Filterable conversion events | | TikTok Events API | ✅ Full | Event name included | | Klaviyo | ✅ Full | Tagged events for segmentation | | GA4 | ✅ Full | Custom dimensions available | ## Getting Started These events are generated automatically for Shopify stores — no additional configuration needed. To use them: 1. **Check your destinations** — Ensure you have destinations configured in Upstack 2. **Configure event mapping** — Select which generated events to send to each destination 3. **Set up conversion tracking** — Configure your ad platforms to track these specific events 4. **Build reports** — Use the Upstack dashboard to compare metrics across event types <CardGroup> <Card title="New Customer Purchases" icon="user-plus" href="/pixel/events/upstack-generated/nc-purchase"> Optimize for customer acquisition </Card> <Card title="AOV Events" icon="chart-line" href="/pixel/events/upstack-generated/aov-events"> Segment by order value </Card> <Card title="Subscription Events" icon="repeat" href="/pixel/events/upstack-generated/subscription-purchase-events"> Track subscription metrics </Card> <Card title="Lapsed Purchases" icon="user-clock" href="/pixel/events/upstack-generated/lapsed-purchase"> Measure win-back campaigns </Card> </CardGroup> # lapsed_purchase Event Source: https://docs.upstackdata.com/pixel/events/upstack-generated/lapsed-purchase Track purchases from lapsed customers who returned — automatically generated by Upstack <Info> **Automatically Generated** — This event is created by Upstack backend services for Shopify customers. You do not need to fire this event manually. </Info> ## Overview The `lapsed_purchase` event is generated when a customer who hasn't purchased in an extended period returns to make a new purchase. This event helps you measure the effectiveness of win-back campaigns and understand customer reactivation patterns. ## How It Works Upstack analyzes customer purchase history to identify lapsed customer reactivations: 1. **Order received** — Shopify sends a purchase webhook to Upstack 2. **Recency analysis** — Upstack checks the time since the customer's last purchase 3. **Lapsed classification** — If the customer hasn't purchased in the lapsed threshold period, a `lapsed_purchase` event is generated 4. **Forwarding** — The event is sent to your configured destinations ### Lapsed Customer Definition A customer is classified as "lapsed" when their last purchase occurred more than **180 days ago** (approximately 6 months). This threshold aligns with common e-commerce customer lifecycle definitions. <Note> The 180-day lapsed threshold is based on industry standards for e-commerce. It distinguishes between returning customers (recent purchasers) and lapsed customers (dormant accounts that have been reactivated). </Note> ## Properties This event includes all properties from the original `purchase` event: | Property | Type | Description | | -------- | ------ | ---------------------------------------- | | orderId | string | Shopify order ID | | value | number | Order total value | | currency | string | ISO 4217 currency code (e.g., `USD`) | | items | array | Products purchased | | email | string | Customer email (hashed for destinations) | | phone | string | Customer phone (hashed for destinations) | ## Destination Mapping This event is forwarded to destinations as: | Destination | Event Name | Notes | | --------------------- | ----------------- | ------------------------------------------- | | **Meta CAPI** | `Purchase` | With `customer_type: lapsed` in custom data | | **Google Ads** | `purchase` | Filterable by event name | | **TikTok Events API** | `CompletePayment` | Lapsed flag included | | **Klaviyo** | `Placed Order` | Tagged as lapsed customer win-back | | **GA4** | `purchase` | Custom dimension for customer lifecycle | ## Use Cases * **Measure win-back performance** — Track how effectively your reactivation campaigns bring back dormant customers * **Calculate win-back CAC** — Understand the cost to reactivate a lapsed customer vs. acquiring a new one * **Optimize win-back timing** — Identify the optimal time to reach out to customers before they become permanently churned * **Segment audiences** — Build audiences of lapsed customers for targeted reactivation campaigns ## Metrics Available In the Upstack dashboard, you can view: | Metric | Description | | ------------------------ | ------------------------------------------------- | | Lapsed Purchases | Total number of lapsed customer purchase events | | Cost per Lapsed Purchase | Average ad spend per lapsed customer reactivation | | Lapsed Purchase Value | Total revenue from reactivated customers | ## Customer Lifecycle Context The `lapsed_purchase` event fits into the broader customer lifecycle: | Lifecycle Stage | Days Since Last Purchase | Event Generated | | --------------- | ------------------------ | ----------------- | | Active | 0–90 days | `rc_purchase` | | At Risk | 90–180 days | `rc_purchase` | | Lapsed | 180–365 days | `lapsed_purchase` | | Churned | 365+ days | `lapsed_purchase` | Both "Lapsed" and "Churned" customers generate `lapsed_purchase` events when they return, as the key insight is the reactivation of a dormant account. ## Related Events * [purchase](/pixel/standard-events#purchase) — The base purchase event * [nc\_purchase](/pixel/events/upstack-generated/nc-purchase) — New customer purchases * [rc\_purchase](/pixel/events/upstack-generated/rc-purchase) — Returning customer purchases * [all\_purchase](/pixel/events/upstack-generated/all-purchase) — All purchases # nc_purchase Event Source: https://docs.upstackdata.com/pixel/events/upstack-generated/nc-purchase Track purchases from first-time customers — automatically generated by Upstack <Info> **Automatically Generated** — This event is created by Upstack backend services for Shopify customers. You do not need to fire this event manually. </Info> ## Overview The `nc_purchase` (New Customer Purchase) event is generated when Upstack detects a purchase from a first-time customer. This event fires alongside the standard `purchase` event, enabling you to segment and optimize campaigns specifically for customer acquisition. ## How It Works When a purchase occurs, Upstack's backend analyzes the customer's order history: 1. **Order received** — Shopify sends a purchase webhook to Upstack 2. **Customer lookup** — Upstack checks if this customer ID has any previous orders 3. **Classification** — If this is the customer's first order, an `nc_purchase` event is generated 4. **Forwarding** — The event is sent to your configured destinations with proper attribution The classification happens server-side using Shopify's customer order history, ensuring accurate new customer detection even when cookies are blocked or the customer uses a different device. ## Properties This event includes all properties from the original `purchase` event: | Property | Type | Description | | -------- | ------ | ---------------------------------------- | | orderId | string | Shopify order ID | | value | number | Order total value | | currency | string | ISO 4217 currency code (e.g., `USD`) | | items | array | Products purchased | | email | string | Customer email (hashed for destinations) | | phone | string | Customer phone (hashed for destinations) | No additional properties are added — the event is the purchase event with a different event name for segmentation. ## Destination Mapping This event is forwarded to destinations as: | Destination | Event Name | Notes | | --------------------- | --------------------------- | -------------------------------------------- | | **Meta CAPI** | `Purchase` with custom data | Includes `customer_type: new` in custom data | | **Google Ads** | `purchase` | Can be filtered by event name in Google Ads | | **TikTok Events API** | `CompletePayment` | Event name included for segmentation | | **Klaviyo** | `Placed Order` | Tagged as new customer | | **GA4** | `purchase` | Custom dimension for customer type | ## Use Cases * **Optimize for acquisition** — Set up Meta campaigns optimizing specifically for new customer purchases rather than all purchases * **Measure true CAC** — Calculate cost per new customer acquisition more accurately * **Exclude retargeting** — Create audiences that exclude returning customers * **A/B test acquisition strategies** — Compare campaign performance on new customers only ## Why This Matters Many brands find that optimizing for all purchases leads to over-indexing on returning customers who would have purchased anyway. By sending `nc_purchase` events to ad platforms, you can: * Train algorithms to find net-new customers * Reduce wasted spend on existing customers * Get clearer signals on acquisition campaign performance ## Related Events * [purchase](/pixel/standard-events#purchase) — The base purchase event for all orders * [rc\_purchase](/pixel/events/upstack-generated/rc-purchase) — Returning customer purchases * [all\_purchase](/pixel/events/upstack-generated/all-purchase) — All purchases (combines NC + RC) # rc_purchase Event Source: https://docs.upstackdata.com/pixel/events/upstack-generated/rc-purchase Track purchases from returning customers — automatically generated by Upstack <Info> **Automatically Generated** — This event is created by Upstack backend services for Shopify customers. You do not need to fire this event manually. </Info> ## Overview The `rc_purchase` (Returning Customer Purchase) event is generated when Upstack detects a purchase from a customer who has ordered before. This event fires alongside the standard `purchase` event, enabling you to measure retention and optimize campaigns for repeat purchases. ## How It Works When a purchase occurs, Upstack's backend analyzes the customer's order history: 1. **Order received** — Shopify sends a purchase webhook to Upstack 2. **Customer lookup** — Upstack checks if this customer ID has any previous orders 3. **Classification** — If the customer has at least one previous order, an `rc_purchase` event is generated 4. **Forwarding** — The event is sent to your configured destinations with proper attribution The classification happens server-side using Shopify's customer order history, providing accurate returning customer detection regardless of browser cookies or device changes. ## Properties This event includes all properties from the original `purchase` event: | Property | Type | Description | | -------- | ------ | ---------------------------------------- | | orderId | string | Shopify order ID | | value | number | Order total value | | currency | string | ISO 4217 currency code (e.g., `USD`) | | items | array | Products purchased | | email | string | Customer email (hashed for destinations) | | phone | string | Customer phone (hashed for destinations) | No additional properties are added — the event is the purchase event with a different event name for segmentation. ## Destination Mapping This event is forwarded to destinations as: | Destination | Event Name | Notes | | --------------------- | --------------------------- | -------------------------------------------------- | | **Meta CAPI** | `Purchase` with custom data | Includes `customer_type: returning` in custom data | | **Google Ads** | `purchase` | Can be filtered by event name in Google Ads | | **TikTok Events API** | `CompletePayment` | Event name included for segmentation | | **Klaviyo** | `Placed Order` | Tagged as returning customer | | **GA4** | `purchase` | Custom dimension for customer type | ## Use Cases * **Measure retention** — Track how well retention and loyalty campaigns drive repeat purchases * **Optimize for LTV** — Train ad algorithms to find customers likely to purchase multiple times * **Retargeting performance** — Measure the true ROI of retargeting campaigns * **Segment reporting** — Compare new vs. returning customer metrics side by side ## Why This Matters Understanding your returning customer purchase rate helps you: * Balance acquisition vs. retention spend * Identify which channels drive the most loyal customers * Calculate customer lifetime value more accurately * Optimize campaigns for long-term revenue, not just first-time purchases ## Related Events * [purchase](/pixel/standard-events#purchase) — The base purchase event for all orders * [nc\_purchase](/pixel/events/upstack-generated/nc-purchase) — New customer purchases * [all\_purchase](/pixel/events/upstack-generated/all-purchase) — All purchases (combines NC + RC) * [lapsed\_purchase](/pixel/events/upstack-generated/lapsed-purchase) — Purchases from lapsed customers who returned # Subscription Purchase Events Source: https://docs.upstackdata.com/pixel/events/upstack-generated/subscription-purchase-events Track subscription purchases — automatically generated by Upstack <Info> **Automatically Generated** — These events are created by Upstack backend services for Shopify customers. You do not need to fire these events manually. </Info> ## Overview Upstack automatically generates subscription purchase events for stores using subscription apps like Recharge, Bold Subscriptions, Skio, or native Shopify Subscriptions. These events help you measure subscription acquisition, retention, and recurring revenue. ## Event Types | Event Name | Description | | --------------------------------- | ------------------------------------------------- | | `subscription_initial_purchase` | First-time subscription purchase (new subscriber) | | `subscription_recurring_purchase` | Recurring subscription renewal | ## How It Works When a subscription order is processed, Upstack analyzes the order metadata: 1. **Order received** — Shopify sends a purchase webhook to Upstack 2. **Subscription detection** — Upstack checks for subscription app tags and order properties 3. **Classification** — The order is classified as initial or recurring based on the subscription data 4. **Event generation** — The appropriate subscription event is generated 5. **Forwarding** — Events are sent to your configured destinations ### Detection Methods Upstack identifies subscription orders through: * Order tags from subscription apps (e.g., `subscription_first_order`, `recurring_order`) * Order properties and line item properties containing subscription metadata * Subscription app-specific identifiers in the order data <Note> Subscription detection works with most major Shopify subscription apps including Recharge, Bold Subscriptions, Skio, Loop Subscriptions, and native Shopify Subscriptions. </Note> ## subscription\_initial\_purchase Generated when a customer signs up for a new subscription. This is the first order in a subscription sequence. ### Use Cases * **Measure subscriber acquisition** — Track how many new subscribers you're acquiring * **Calculate subscriber CAC** — Understand the true cost to acquire a subscriber * **Optimize acquisition campaigns** — Train ad algorithms to find subscription-likely customers * **Attribution for LTV** — Attribute the full potential LTV to the acquiring campaign ## subscription\_recurring\_purchase Generated for each recurring subscription renewal. This includes all orders after the initial subscription purchase. ### Use Cases * **Track subscription retention** — Monitor recurring revenue from existing subscribers * **Measure churn impact** — Understand when recurring purchases decline * **Attribution for retention campaigns** — Track which campaigns drive continued engagement * **Revenue forecasting** — Use recurring purchase data to predict future revenue ## Properties Both events include all properties from the original `purchase` event: | Property | Type | Description | | -------- | ------ | ---------------------------------------- | | orderId | string | Shopify order ID | | value | number | Order total value | | currency | string | ISO 4217 currency code (e.g., `USD`) | | items | array | Products purchased | | email | string | Customer email (hashed for destinations) | | phone | string | Customer phone (hashed for destinations) | ## Destination Mapping Subscription events are forwarded to destinations as: | Destination | Event Name | Notes | | --------------------- | ----------------- | --------------------------------------- | | **Meta CAPI** | `Purchase` | With `subscription_type` in custom data | | **Google Ads** | `purchase` | Filterable by event name | | **TikTok Events API** | `CompletePayment` | Subscription flag included | | **Klaviyo** | `Placed Order` | Tagged with subscription type | | **GA4** | `purchase` | Custom dimension for subscription | ## Metrics Available In the Upstack dashboard, you can view: | Metric | Description | | -------------------------------- | ------------------------------ | | Subscription Initial Purchases | New subscription sign-ups | | Cost per Subscription Initial | CAC for new subscribers | | Subscription Initial Value | Revenue from new subscriptions | | Subscription Recurring Purchases | Renewal orders | | Cost per Subscription Recurring | Cost attributed to renewals | | Subscription Recurring Value | Recurring subscription revenue | ## Subscription vs. SaaS Events <Note> **Important distinction:** These events (`subscription_initial_purchase`, `subscription_recurring_purchase`) are for e-commerce subscription boxes and recurring product purchases. For SaaS subscription lifecycle events (plan changes, trials, etc.), see [SaaS Events](/pixel/saas-events). </Note> | Event Type | Use For | | --------------------------------- | ---------------------------------------------- | | `subscription_initial_purchase` | E-commerce: First subscription box order | | `subscription_recurring_purchase` | E-commerce: Recurring subscription box renewal | | `subscription_started` | SaaS: New software subscription | | `subscription_created` | SaaS: Subscription record created | ## Related Events * [purchase](/pixel/standard-events#purchase) — The base purchase event * [nc\_purchase](/pixel/events/upstack-generated/nc-purchase) — New customer purchases * [rc\_purchase](/pixel/events/upstack-generated/rc-purchase) — Returning customer purchases * [all\_purchase](/pixel/events/upstack-generated/all-purchase) — All purchases * [SaaS Events](/pixel/saas-events) — SaaS subscription lifecycle events # upsell_purchase Event Source: https://docs.upstackdata.com/pixel/events/upstack-generated/upsell-purchase Track upsell conversions — automatically generated by Upstack <Info> **Automatically Generated** — This event is created by Upstack backend services for Shopify customers. You do not need to fire this event manually. </Info> ## Overview The `upsell_purchase` event is generated when Upstack detects a purchase that resulted from an upsell opportunity. This event helps you measure the effectiveness of upsell campaigns, post-purchase offers, and cross-sell strategies. ## How It Works Upstack analyzes purchase patterns to identify upsell conversions: 1. **Order received** — Shopify sends a purchase webhook to Upstack 2. **Upsell detection** — Upstack checks for upsell indicators (multiple items, upgraded variants, post-purchase additions) 3. **Event generation** — If upsell criteria are met, an `upsell_purchase` event is generated 4. **Forwarding** — The event is sent to your configured destinations ### Upsell Classification A purchase is classified as an upsell when: * The order contains items added through post-purchase offers * The customer upgraded to a higher-tier product variant * The order includes cross-sell items from upsell campaigns * The purchase occurred during a returning customer's session with additional items beyond their typical basket ## Properties This event includes all properties from the original `purchase` event: | Property | Type | Description | | -------- | ------ | ---------------------------------------- | | orderId | string | Shopify order ID | | value | number | Order total value | | currency | string | ISO 4217 currency code (e.g., `USD`) | | items | array | Products purchased | | email | string | Customer email (hashed for destinations) | | phone | string | Customer phone (hashed for destinations) | ## Destination Mapping This event is forwarded to destinations as: | Destination | Event Name | Notes | | --------------------- | ----------------- | ---------------------------------- | | **Meta CAPI** | `Purchase` | With `upsell: true` in custom data | | **Google Ads** | `purchase` | Filterable by event name | | **TikTok Events API** | `CompletePayment` | Upsell flag included | | **Klaviyo** | `Placed Order` | Tagged as upsell | | **GA4** | `purchase` | Custom dimension for upsell | ## Use Cases * **Measure upsell effectiveness** — Track how often upsell offers convert and their revenue impact * **Optimize upsell timing** — Identify which campaigns or touchpoints drive the most upsell conversions * **Calculate upsell ROI** — Compare ad spend to upsell revenue for campaign optimization * **A/B test offers** — Measure which upsell offers perform best by tracking conversion rates ## Metrics Available In the Upstack dashboard, you can view: | Metric | Description | | ------------------------ | -------------------------------------- | | Upsell Purchases | Total number of upsell purchase events | | Cost per Upsell Purchase | Average ad spend per upsell conversion | | Upsell Purchase Value | Total revenue from upsell purchases | ## Related Events * [purchase](/pixel/standard-events#purchase) — The base purchase event * [rc\_purchase](/pixel/events/upstack-generated/rc-purchase) — Returning customer purchases * [all\_purchase](/pixel/events/upstack-generated/all-purchase) — All purchases * [AOV Events](/pixel/events/upstack-generated/aov-events) — Purchase segmentation by order value # view_cart Event Source: https://docs.upstackdata.com/pixel/events/view-cart Track when a visitor views their shopping cart Fires when a visitor views their shopping cart. This helps track cart abandonment and build remarketing audiences for shoppers who haven't completed checkout. <Note> **Shopify:** Automatically tracked when the cart page or cart drawer is viewed. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'view_cart', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2 }, { id: 'SKU_67890', name: 'Running Socks', price: 14.99, quantity: 1 } ], value: 84.97, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | ------------------------------------------------------------------------ | | items | array | Yes | Products in cart (see [Item Object](/pixel/standard-events#item-object)) | | value | number | No | Total cart value | | currency | string | No | ISO 4217 currency code | ## When to Fire * Cart page load * Cart drawer/sidebar open * Mini-cart expansion ## Related Events * [add\_to\_cart](/pixel/events/add-to-cart) — When adding items to cart * [product\_removed\_from\_cart](/pixel/events/product-removed-from-cart) — When removing items * [initiate\_checkout](/pixel/events/initiate-checkout) — When starting checkout # view_category Event Source: https://docs.upstackdata.com/pixel/events/view-category Track when a visitor views a collection or category page Fires when a visitor views a collection or category page. Use this to track browsing behavior and build category-based audiences. <Note> **Shopify:** Automatically tracked when viewing collection pages. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'view_category', { items: [ { id: 'SKU_001', name: 'Classic Cotton Tee', price: 34.99 }, { id: 'SKU_002', name: 'Vintage Logo Hoodie', price: 59.99 }, { id: 'SKU_003', name: 'Slim Fit Jeans', price: 79.99 } ], itemListId: 'summer_collection', itemListName: 'Summer 2026 Collection' }); ``` Minimal example: ```javascript theme={null} window._upstack('track', 'view_category', { itemListId: 'mens_shirts', itemListName: 'Men\'s Shirts' }); ``` ## Properties | Property | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------------------------------------------------------------- | | itemListId | string | No | Collection/category identifier | | itemListName | string | No | Collection/category display name | | items | array | No | Products shown in the category (see [Item Object](/pixel/standard-events#item-object)) | ## When to Fire * Collection page load * Category filter applied * Browse by category navigation ## Related Events * [view\_content](/pixel/events/view-content) — When viewing an individual product * [view\_item\_list](/pixel/events/view-item-list) — For general product lists (recommendations, etc.) * [search](/pixel/events/search) — When viewing search results # view_content Event Source: https://docs.upstackdata.com/pixel/events/view-content Track when a visitor views a product or content page Fires when a visitor views a product or content page. This event is critical for remarketing audiences and conversion attribution. <Note> **Shopify:** Automatically tracked when viewing product detail pages. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'view_content', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, brand: 'Example Brand', category: 'Apparel/T-Shirts' } ], value: 34.99, currency: 'USD' }); ``` Minimal example: ```javascript theme={null} window._upstack('track', 'view_content', { items: [{ id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99 }], value: 34.99, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | ----------------------------------------------------------------------- | | items | array | Yes | Products viewed (see [Item Object](/pixel/standard-events#item-object)) | | value | number | Yes | Product price | | currency | string | Yes | ISO 4217 currency code (e.g., `'USD'`) | ## When to Fire * Product detail page load * Quick view modal open * Collection page load (with collection products) ## Related Events * [add\_to\_cart](/pixel/events/add-to-cart) — When adding the viewed product to cart * [add\_to\_wishlist](/pixel/events/add-to-wishlist) — When saving the product for later * [view\_category](/pixel/events/view-category) — When viewing a collection page # view_item_list Event Source: https://docs.upstackdata.com/pixel/events/view-item-list Track when a visitor views a list of products Fires when a visitor views a list of products. This is similar to `view_category` but more general — use it for recommendation carousels, recently viewed sections, and other product lists. <Note> **Shopify:** Manual implementation required. Not automatically tracked. </Note> ## JavaScript ```javascript theme={null} window._upstack('track', 'view_item_list', { items: [ { id: 'SKU_001', name: 'Classic Cotton Tee', price: 34.99, index: 0 }, { id: 'SKU_002', name: 'Vintage Logo Hoodie', price: 59.99, index: 1 } ], itemListId: 'recommended_products', itemListName: 'Recommended For You' }); ``` ## Properties | Property | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------------------------ | | itemListId | string | No | List identifier | | itemListName | string | No | List display name | | items | array | No | Products in the list (include `index` for position tracking) | ## When to Fire * Product recommendation carousel load * "Related Products" section view * "Recently Viewed" section view * Search results page load ## Related Events * [view\_category](/pixel/events/view-category) — For collection/category pages * [view\_content](/pixel/events/view-content) — When clicking through to a product * [search](/pixel/events/search) — For search results specifically # Upstack Data Glossary: Key Terms Explained Source: https://docs.upstackdata.com/pixel/glossary Glossary of Upstack Data terminology — attribution, CAPI, EMQ, identity resolution, destinations, server-side tracking, and other key concepts explained. | Term | Definition | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Attribution** | The process of assigning credit for a conversion to one or more marketing touchpoints. | | **CAPI** | Conversions API — a server-to-server integration for sending events to ad platforms (Meta, TikTok, etc.) without relying on browser cookies. | | **Click ID** | A unique identifier appended to URLs by ad platforms (e.g., `fbclid` for Meta, `ttclid` for TikTok, `gclid` for Google) used to match conversions to ad clicks. | | **Conversion** | A completed action that represents business value, most commonly a purchase. | | **Custom event** | A merchant-defined event tracked via the Upstack JavaScript SDK, beyond the 12 standard events. | | **Destination** | A third-party platform that receives enriched event data from Upstack (e.g., Meta CAPI, Klaviyo, GA4). | | **EMQ** | Event Match Quality — Meta's score (0–10) indicating how well your server events can be matched to Facebook users. Higher EMQ = better ad optimization. | | **Enrichment** | The process of augmenting raw events with additional data: product catalog details, UTM parameters, identity signals, and session context. | | **Event** | A structured record of a customer interaction — a pageview, add-to-cart, purchase, or any custom action. | | **Identity resolution** | Matching anonymous visitor sessions to known customer profiles using deterministic (email, phone) and probabilistic (fingerprint, device) signals. | | **Identity stitching** | Linking multiple sessions and devices belonging to the same person into a unified customer profile. | | **Match rate** | The percentage of server-side events that an ad platform can match to users on its network. Higher match rates improve ad optimization. | | **PII** | Personally Identifiable Information — data like email and phone number. Upstack hashes PII (SHA-256) before sending to ad platforms. | | **Pixel** | A lightweight JavaScript snippet injected into your storefront that captures browser-side events and sends them to the Upstack edge API. | | **ROAS** | Return on Ad Spend — revenue generated divided by ad spend. Upstack helps improve ROAS by providing higher-quality conversion data to ad platforms. | | **Server-side tracking** | Capturing events via server-to-server communication rather than browser-based JavaScript, making tracking resilient to ad blockers and cookie restrictions. | | **Source** | A platform or integration that sends data into Upstack (e.g., Shopify storefront, Facebook Ads, Google Ads). | | **Standard event** | One of the 12 predefined event types that Upstack recognizes across all destinations (page\_view, purchase, add\_to\_cart, etc.). | | **UTM parameters** | URL query parameters (`utm_source`, `utm_medium`, `utm_campaign`, etc.) used to identify traffic sources and campaigns. | | **Webhook** | An HTTP callback that delivers event data to an external URL in real time. | # Understanding Identity Resolution Source: https://docs.upstackdata.com/pixel/identity-resolution Upstack ID stitches anonymous sessions into unified customer profiles via deterministic and probabilistic matching — improving CAPI match quality. Identity resolution is the process of recognizing that the person browsing on a phone, clicking an ad on a laptop, and completing a purchase on a tablet is the same customer. <Info> **This page covers conceptual understanding** — how identity resolution works, why it matters, and key terminology. For technical details about the identity fields on events and session stitching mechanics, see [Identity & Stitching](/pixel/identity-stitching). </Info> <Note> **Works on all implementations** — Identity resolution works with Shopify, headless storefronts, and custom websites. Anywhere the Upstack pixel is installed, Upstack ID can resolve identities. </Note> <Tip> Merchants using Upstack ID see 30–60% more identified sessions, which directly improves retargeting audience size and conversion API match quality. </Tip> ## Why It Matters Most website visitors browse anonymously. They arrive from an ad, view products, leave, and return days later on a different device. Without identity resolution, each visit looks like a separate person — your attribution data fragments, retargeting audiences shrink, and conversion APIs send events with weak identity signals. The problem intensifies in a privacy-first world. Third-party cookies are disappearing, mobile identifiers are gated behind consent prompts, and cross-domain tracking is increasingly blocked. Merchants need a first-party identity layer that works within these constraints while still connecting the dots across the customer journey. Strong identity resolution also compounds the value of every other part of your data stack. Enrichment becomes more accurate when attached to a unified profile. Conversion API match quality (EMQ) rises when events carry hashed email, phone, and address. Attribution models produce meaningful results only when they can follow a single customer across touchpoints. ## How It Works Upstack ID operates at the **Resolve** stage of the data pipeline, immediately after raw events are captured by Upstack Pixel. The resolution engine uses a layered matching strategy: * **Deterministic matching** — When a visitor logs in, enters an email at checkout, or clicks a Klaviyo email link, Upstack ID creates a hard link between the anonymous session cookie and the known customer identifier. These matches are exact and high-confidence. * **Session stitching** — Events within the same browsing session are grouped using the first-party cookie set by Upstack Pixel. As soon as any event in the session is identified (e.g., checkout), all prior anonymous events in that session are retroactively attributed to the same customer. * **Cross-device linking** — When the same email or phone appears across sessions on different devices, Upstack ID merges those profiles into a single identity graph node. Future events on any linked device are automatically resolved. * **Probabilistic signals** — Browser fingerprint attributes (viewport, language, timezone, installed fonts) serve as weak tiebreakers when deterministic identifiers are absent. These signals are never used alone — they only reinforce existing deterministic links. All matching happens server-side within the AWS backend, ensuring PII is never exposed to client-side scripts or third-party tags. ## Key Terms | Term | Definition | | -------------------------- | ------------------------------------------------------------------------------------------------------------------- | | **Identity graph** | A data structure that maps all known identifiers (email, phone, cookie, device) to a single customer profile. | | **Deterministic matching** | Linking sessions using exact identifiers like email or phone number. | | **Probabilistic matching** | Using weaker signals (browser attributes, timing patterns) to suggest — not confirm — an identity link. | | **Session stitching** | Retroactively attributing anonymous events to a known customer after identification occurs within the same session. | | **Cross-device linking** | Merging profiles when the same identifier appears on different devices or browsers. | ## Related Documentation <CardGroup> <Card title="Identity & Stitching" icon="link" href="/pixel/identity-stitching"> Technical details: identity fields on events, session stitching mechanics. </Card> <Card title="JavaScript SDK" icon="code" href="/pixel/javascript-sdk#identifyuserid-data"> How to call identify() to associate user identity with sessions. </Card> <Card title="Server-Side Tracking" icon="server" href="/concepts/server-side-tracking"> How Upstack Pixel captures the raw events that feed identity resolution. </Card> <Card title="Connect a Destination" icon="plug" href="/get-started/connect-a-destination"> Forward identity-enriched events to ad platforms for higher match quality. </Card> </CardGroup> # How Session Stitching Works Source: https://docs.upstackdata.com/pixel/identity-stitching How Upstack ID attaches resolved identity to events, stitches anonymous sessions retroactively, and improves destination match quality (EMQ 7-9). Every event Upstack captures starts with whatever identity signals the visitor provides — often just an IP address and browser cookie. Upstack ID enriches these events with resolved identity data, connecting anonymous sessions to known customers and dramatically improving the quality of data sent to your destinations. <Info> **This page covers technical implementation** — the identity fields on events, how session stitching works, and the impact on destination match quality. For a conceptual overview of identity resolution and how the identity graph works, see [Identity Resolution](/pixel/identity-resolution). </Info> <Tip> Events that pass through identity resolution carry 3–5x more match keys on average. This directly translates to higher EMQ scores on Meta, better audience match rates on TikTok, and more accurate attribution. </Tip> ## Identity Fields on Events After identity resolution, events carry these identity-related fields: | Field | Location | Description | | ------------------- | ----------- | ---------------------------------------------------------------------------------- | | `session_id` | Event root | Groups all events within a single browsing session. Set by the first-party cookie. | | `identity_id` | Event root | The resolved Upstack identity ID. Present once the visitor has been identified. | | `em` | `user_data` | SHA-256 hashed email address. | | `ph` | `user_data` | SHA-256 hashed phone number. | | `external_id` | `user_data` | Shopify customer ID or other external identifier. | | `fbc` | `user_data` | Meta click ID cookie linking the session to an ad click. | | `fbp` | `user_data` | Meta browser ID cookie for cross-session continuity. | | `ttclid` | `user_data` | TikTok click ID for ad attribution. | | `gclid` | `user_data` | Google click ID for ad attribution. | | `client_ip_address` | `user_data` | Visitor IP address. | | `client_user_agent` | `user_data` | Browser user agent string. | ## How Identity Attaches to Events Identity resolution happens at the **Resolve** stage of the pipeline, between event capture and destination forwarding. ### 1. First-Party Cookie Matching When a visitor lands on your store, the Upstack Pixel sets a first-party cookie. Every event in that browsing session shares the same `session_id`. If the visitor has been seen before (returning visitor), the cookie links to their existing identity profile. ### 2. Deterministic Identification When a visitor provides a hard identifier — logging in, entering an email at checkout, clicking a Klaviyo email link — Upstack ID creates a deterministic match: * The `session_id` is linked to the customer's `identity_id` * `em` (hashed email) and `ph` (hashed phone) are attached to the event * `external_id` is set from the Shopify customer ID ### 3. Session Stitching This is where the real value emerges. When identification happens mid-session (e.g., at checkout), Upstack ID retroactively enriches all **prior anonymous events in that session** with the resolved identity data. A typical session flow: | Event | Before Stitching | After Stitching | | -------------------------- | ----------------------------- | --------------------------------------------- | | PageView (homepage) | IP + user agent only | IP + user agent + `em` + `ph` + `identity_id` | | ViewContent (product page) | IP + user agent only | IP + user agent + `em` + `ph` + `identity_id` | | AddToCart | IP + user agent only | IP + user agent + `em` + `ph` + `identity_id` | | InitiateCheckout | IP + user agent + `em` + `ph` | IP + user agent + `em` + `ph` + `identity_id` | | Purchase | IP + user agent + `em` + `ph` | IP + user agent + `em` + `ph` + `identity_id` | Without stitching, the PageView, ViewContent, and AddToCart events would be forwarded to destinations with weak identity signals. With stitching, every event in the session carries the full set of match keys. <Note> Session stitching is retroactive within the session. Events are held briefly in the pipeline to allow late-arriving identity data to propagate. The hold window is short enough to maintain near-real-time forwarding. </Note> ### 4. Cross-Device Linking When the same email or phone appears across sessions on different devices, Upstack ID merges those sessions under a single `identity_id`. A shopper who browses on mobile and purchases on desktop is recognized as one customer. Cross-device linking enables: * Accurate attribution across devices * Larger retargeting audiences (one profile instead of two) * Complete customer journey visibility in analytics ## Impact on Destination Match Quality Identity resolution directly drives the match keys available for each destination: | Destination | Key Match Fields | Typical EMQ Without Stitching | Typical EMQ With Stitching | | --------------------- | ---------------------------------------- | ----------------------------- | -------------------------- | | **Meta CAPI** | `em`, `ph`, `fbc`, `fbp`, IP, user agent | 3–5 | 7–9 | | **TikTok Events API** | `em`, `ph`, `ttclid`, IP, user agent | 2–4 | 6–8 | | **Klaviyo** | `em`, `ph` | Partial profiles | Complete profiles | | **GA4** | `client_id`, `user_id` | Anonymous only | Identified users | The difference is especially pronounced for upper-funnel events (PageView, ViewContent) that typically fire before the visitor has identified themselves. Session stitching ensures these events reach destinations with full identity data. <Warning> Identity resolution depends on the visitor eventually identifying themselves within the session. Fully anonymous sessions (no login, no checkout, no email link click) cannot be resolved. The identification rate varies by store — typically 30–60% of sessions are resolved. </Warning> ## How This Connects to the Broader Pipeline Identity resolution sits between event capture and destination forwarding: 1. **Capture** — Upstack Pixel fires raw events with whatever signals are available. 2. **Resolve** — Upstack ID attaches identity, stitches sessions, and links devices. *(You are here.)* 3. **Enrich** — Product catalog data and UTM parameters are merged. 4. **Activate** — Identity-enriched events are forwarded to destinations with maximum match keys. For a deeper dive into how identity resolution works at the infrastructure level, see the [Identity Resolution](/pixel/identity-resolution) concept page. ## Related Documentation <CardGroup> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> Conceptual overview: identity graph, deterministic matching, cross-device linking. </Card> <Card title="JavaScript SDK" icon="code" href="/pixel/javascript-sdk#identifyuserid-data"> How to call identify() to associate user identity with sessions. </Card> <Card title="Properties & Context" icon="table" href="/pixel/properties"> Full reference for all identity fields, custom data, and context on events. </Card> <Card title="Standard Events" icon="list-check" href="/pixel/standard-events"> Events that carry identity data after resolution. </Card> </CardGroup> # Upstack Data Pixel: Event Tracking Overview Source: https://docs.upstackdata.com/pixel/index Track customer events, capture identity, and forward data to ad platforms with the Upstack Data JavaScript pixel. Quick setup and full SDK reference. ## Overview The Upstack Pixel is a JavaScript library that enables you to track user behavior, capture events, and identify users on your website. <Note> **Works everywhere** — The Upstack Pixel runs on Shopify stores, headless storefronts, custom websites, and any platform where you can add JavaScript. </Note> <CardGroup> <Card title="Quick Start" icon="rocket" href="/pixel/setup"> Install the pixel in 5 minutes </Card> <Card title="JavaScript SDK" icon="code" href="/pixel/javascript-sdk"> Full SDK reference </Card> <Card title="Standard Events" icon="list" href="/pixel/standard-events"> E-commerce event reference </Card> <Card title="Event Properties" icon="database" href="/pixel/properties"> All available properties </Card> </CardGroup> *** ## Feature Availability by Platform Not all features work the same across platforms. Here's what's automatic vs manual: | Feature | Shopify | Headless / Custom / GTM | | ---------------------------------- | ----------- | ------------------------------------- | | `page_view` tracking | ✅ Automatic | Manual — call `_upstack('page')` | | `view_content` on product pages | ✅ Automatic | Manual — fire on product page load | | `add_to_cart` events | ✅ Automatic | Manual — fire on cart add | | `initiate_checkout` | ✅ Automatic | Manual — fire on checkout start | | `purchase` events | ✅ Automatic | Manual — fire on order confirmation | | Form capture (Klaviyo, Postscript) | ✅ Automatic | ✅ Automatic (when both installed) | | Custom events | ✅ Manual | ✅ Manual | | Identity resolution | ✅ Automatic | ✅ Automatic (after `identify()` call) | | `nc_purchase` / `rc_purchase` | ✅ Automatic | ❌ Shopify only | <Info> **Shopify merchants:** The theme app extension handles most tracking automatically. You only need the JavaScript SDK for custom events or advanced use cases. **Custom implementations:** Use the [JavaScript SDK Reference](/pixel/javascript-sdk) and [Standard Events](/pixel/standard-events) to implement tracking manually. </Info> # Upstack Data JavaScript SDK Reference Source: https://docs.upstackdata.com/pixel/javascript-sdk Complete API reference for the Upstack Data JavaScript SDK. Covers all 6 queue commands, 2 direct client methods, TypeScript support, and usage patterns. The Upstack JavaScript SDK provides client-side event tracking, user identification, and session management. It captures browsing behavior, resolves user identity across devices, and forwards events to your configured destinations. <Warning> **Important:** The correct global is `window._upstack()` (with underscore), not `window.upstack()`. Older documentation may reference the incorrect name. </Warning> ## Installation The Upstack pixel is distributed via CDN, not npm. Add this snippet to your site's `<head>`: ```html theme={null} <script> window._upstack = window._upstack || function() { (window._upsqueue = window._upsqueue || []).push(arguments); }; _upstack('init', 'YOUR_PIXEL_ID'); </script> <script async src="https://prod2-cdn.upstackified.com/scripts/px/ups.min.js"></script> ``` **Why this works:** 1. The inline script defines `_upstack()` as a function that pushes calls to a queue 2. Calls made before the SDK loads are queued — no events are lost 3. Once the SDK loads, it processes the queue and replaces `_upstack()` with the real implementation 4. Safe to call immediately without checking load status ## API Overview | Method | Via Queue | Via Direct Client | Description | | -------------- | ---------------- | ----------------- | --------------------------------- | | `init` | ✅ (pixelId only) | ✅ | Initialize the pixel | | `page` | ✅ | ✅ | Track page views | | `track` | ✅ | ✅ | Track custom events | | `identify` | ✅ | ✅ | Associate user identity | | `metric` | ✅ | ✅ | Send metrics (currently disabled) | | `reset` | ✅ | ✅ | Clear identity state | | `isKnown` | ❌ | ✅ | Check if user is identified | | `getUpstackId` | ❌ | ✅ | Get Upstack ID object | *** ## Queue Commands These methods can be called via `_upstack('command', ...)` before or after the SDK loads. ### init(pixelId) Initialize the Upstack pixel with your pixel ID. ```typescript theme={null} function init( pixelId: string, identityTraits?: EventIdentityTraits, scriptSource?: 'js' | 'shopify_js' | 'shopify_ext' ): Promise<{ isInitialized: boolean; isDisabled: boolean }> ``` **Parameters:** | Parameter | Type | Required | Description | | ---------------- | --------------------- | -------- | ---------------------------------------------------------------- | | `pixelId` | `string` | Yes | Your Upstack pixel ID from the dashboard (starts with `px_`) | | `identityTraits` | `EventIdentityTraits` | No | Pre-populate identity on init | | `scriptSource` | `string` | No | Script origin: `'js'` (default), `'shopify_js'`, `'shopify_ext'` | <Warning> **Queue Limitation:** When using `_upstack('init', pixelId, identityTraits, scriptSource)`, only `pixelId` is passed to the init function. The `identityTraits` and `scriptSource` parameters are dropped by the queue processor. For full init with identity traits, use the direct client after the script loads. </Warning> **Examples:** ```javascript theme={null} // Basic initialization via queue (recommended) _upstack('init', 'px_abc123def456'); // Full init with identity traits (requires direct client) // Wait for script to load first if (window._upsClient) { await window._upsClient.init('px_abc123def456', { emails: ['user@example.com'] }, 'js'); } ``` *** ### page(eventData?) Track a page view. Automatically captures page URL, title, referrer, and path. ```typescript theme={null} function page(eventData?: Record<string, unknown>): void ``` **Parameters:** | Parameter | Type | Required | Description | | ----------- | -------- | -------- | ----------------------------------------------- | | `eventData` | `object` | No | Custom properties to include with the page view | **Auto-captured properties:** * `page_url` — Current page URL * `page_title` — Document title * `page_referrer` — Referring URL * `page_path` — URL path **Examples:** ```javascript theme={null} // Basic page view _upstack('page'); // With custom properties _upstack('page', { page_category: 'product', product_id: 'SKU123', collection: 'summer-2026' }); ``` *** ### track(eventName, eventData?, ...) Track a custom event. Supports 7 positional parameters plus a shorthand for `useBeacon`. ```typescript theme={null} function track( eventName: string, eventData?: Record<string, unknown>, eventId?: string, contextOverride?: Record<string, unknown>, collectedAt?: string, // ISO 8601 timestamp collectedAtEpoch?: number, // Unix epoch milliseconds options?: TrackOptions ): void interface TrackOptions { useBeacon?: boolean; // Use navigator.sendBeacon() for page unload } ``` **Parameters:** | Parameter | Type | Required | Description | | ------------------ | -------------- | -------- | --------------------------------------------------------------- | | `eventName` | `string` | Yes | Event name in snake\_case (e.g., `'add_to_cart'`, `'purchase'`) | | `eventData` | `object` | No | Event properties | | `eventId` | `string` | No | Unique ID for deduplication across destinations | | `contextOverride` | `object` | No | Override page/session context for this event | | `collectedAt` | `string` | No | ISO 8601 timestamp for backdated events | | `collectedAtEpoch` | `number` | No | Unix epoch milliseconds for backdated events | | `options` | `TrackOptions` | No | `{ useBeacon: boolean }` for page unload tracking | **Shorthand for useBeacon:** When the 4th argument is an object with `useBeacon`, it's treated as options: ```javascript theme={null} // Shorthand (recommended for useBeacon) _upstack('track', 'lead', { email: 'user@example.com' }, { useBeacon: true }); // Full positional form (7 parameters) _upstack('track', 'lead', { email: 'user@example.com' }, null, null, null, null, { useBeacon: true }); ``` **Examples:** ```javascript theme={null} // Basic tracking _upstack('track', 'add_to_cart', { items: [{ id: 'SKU123', name: 'Widget', price: 29.99, quantity: 1 }], value: 29.99, currency: 'USD' }); // With deduplication ID (prevents duplicate events at destinations) _upstack('track', 'purchase', { items: [{ id: 'SKU123', name: 'Widget', price: 29.99, quantity: 1 }], value: 29.99, order_id: 'ORD-456', currency: 'USD' }, 'ORD-456'); // Backdated event (server-side timestamp) _upstack('track', 'server_event', { value: 50 }, null, null, '2026-06-01T12:00:00Z'); // Page unload with beacon (using shorthand) window.addEventListener('visibilitychange', () => { if (document.visibilityState === 'hidden') { _upstack('track', 'page_exit', { time_on_page_seconds: Math.round((Date.now() - pageLoadTime) / 1000) }, { useBeacon: true }); } }); ``` *** ### identify(userId?, data?) Associate user identity with the current session. Used for cross-device tracking and destination matching. ```typescript theme={null} function identify( userId?: string | null, data?: EventIdentityTraits ): void interface EventIdentityTraits { emails?: string[]; // Array of email addresses phones?: string[]; // Array of phone numbers (E.164 format preferred) firstName?: string; lastName?: string; address?: { city?: string; state?: string; zip?: string; country?: string; }; } ``` **Parameters:** | Parameter | Type | Required | Description | | --------- | --------------------- | -------- | --------------------------------------------------------------------------------- | | `userId` | `string \| null` | No | Your internal user ID. Pass `null` for anonymous identification with traits only. | | `data` | `EventIdentityTraits` | No | Identity traits with `emails[]` and `phones[]` as arrays | <Note> **Important:** `emails` and `phones` are arrays, not single values. This supports users with multiple contact methods. </Note> **Examples:** ```javascript theme={null} // With userId only _upstack('identify', 'user-456'); // With full profile _upstack('identify', 'user-456', { emails: ['jane@example.com', 'jane.doe@work.com'], phones: ['+15551234567'], firstName: 'Jane', lastName: 'Doe', address: { city: 'Austin', state: 'TX', zip: '78701', country: 'US' } }); // Traits only (Shopify path — userId is null) _upstack('identify', null, { emails: ['customer@example.com'] }); // After form submission document.querySelector('form').addEventListener('submit', (e) => { const email = e.target.querySelector('[name="email"]').value; _upstack('identify', null, { emails: [email] }); }); ``` *** ### metric(metricName, metricValue, metricData?, metricId?) Send a custom metric value. ```typescript theme={null} function metric( metricName: string, metricValue: number, metricData?: Record<string, unknown>, metricId?: string ): null ``` <Warning> **Currently Disabled:** The `metric()` method is routed through the queue but returns `null` — metric forwarding is disabled in the public SDK. This method exists for future use. </Warning> **Parameters:** | Parameter | Type | Required | Description | | ------------- | -------- | -------- | --------------------------- | | `metricName` | `string` | Yes | Metric name | | `metricValue` | `number` | Yes | Numeric value | | `metricData` | `object` | No | Additional context | | `metricId` | `string` | No | Unique ID for deduplication | **Example:** ```javascript theme={null} // Currently returns null — metric forwarding disabled _upstack('metric', 'page_load_time', 1250, { page: '/checkout' }); ``` *** ### reset() Clear identity, session data, event listeners, and hooks. Call when a user logs out. ```typescript theme={null} function reset(): void ``` **Example:** ```javascript theme={null} function handleLogout() { _upstack('reset'); window.location.href = '/login'; } ``` *** ## Direct Client Methods These methods are **only available via `window._upsClient`** after initialization completes. They cannot be called through the `_upstack()` queue. ### isKnown() Check if the current user has been identified. ```typescript theme={null} function isKnown(): Promise<boolean> ``` **Returns:** Promise resolving to `true` if the user has been identified, `false` otherwise. <Warning> **Direct Client Only:** This method is NOT available via the `_upstack()` queue. You must call it directly on `window._upsClient`. </Warning> **Example:** ```javascript theme={null} // After init completes const isKnown = await window._upsClient.isKnown(); if (!isKnown) { showEmailCapturePopup(); } ``` *** ### getUpstackId() Retrieve the Upstack identity object for the current user. ```typescript theme={null} interface UpstackId { _upstackId?: string; // Persistent user ID _upstackSid?: string; // Session ID _upstackIp?: string; // IP address (if available) } function getUpstackId(): Promise<UpstackId> ``` **Returns:** Promise resolving to an `UpstackId` object (not a string). <Warning> **Direct Client Only:** This method is NOT available via the `_upstack()` queue. You must call it directly on `window._upsClient`. **Return Type:** Returns an object with identity fields, not a single string ID. </Warning> **Example:** ```javascript theme={null} // After init completes const upstackId = await window._upsClient.getUpstackId(); console.log('Upstack ID:', upstackId._upstackId); console.log('Session ID:', upstackId._upstackSid); // Use for server-side API calls fetch('/api/track', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ upstack_id: upstackId._upstackId, event: 'server_purchase', value: 99.99 }) }); ``` *** ## Waiting for SDK Ready When using direct client methods, ensure the SDK has loaded: ```javascript theme={null} function onUpstackReady(callback) { if (window._upsClient && window._upsClient._initialized) { callback(); } else { const interval = setInterval(() => { if (window._upsClient && window._upsClient._initialized) { clearInterval(interval); callback(); } }, 100); } } // Usage onUpstackReady(async () => { const isKnown = await window._upsClient.isKnown(); if (isKnown) { const upstackId = await window._upsClient.getUpstackId(); console.log('User ID:', upstackId._upstackId); } }); ``` *** ## Common Patterns ### SPA Navigation Tracking Track page views on route changes in single-page applications: ```javascript theme={null} // React Router import { useEffect } from 'react'; import { useLocation } from 'react-router-dom'; function usePageTracking() { const location = useLocation(); useEffect(() => { _upstack('page', { page_path: location.pathname, page_search: location.search }); }, [location]); } // Next.js App Router 'use client'; import { usePathname, useSearchParams } from 'next/navigation'; import { useEffect } from 'react'; export function Analytics() { const pathname = usePathname(); const searchParams = useSearchParams(); useEffect(() => { _upstack('page', { page_path: pathname, page_search: searchParams.toString() }); }, [pathname, searchParams]); return null; } ``` ### E-commerce Funnel Track the complete customer journey: ```javascript theme={null} // Product view _upstack('track', 'view_content', { items: [{ id: 'SKU123', name: 'Widget', price: 29.99 }] }); // Add to cart _upstack('track', 'add_to_cart', { items: [{ id: 'SKU123', name: 'Widget', price: 29.99, quantity: 1 }], value: 29.99, currency: 'USD' }); // Begin checkout _upstack('track', 'initiate_checkout', { items: [{ id: 'SKU123', name: 'Widget', price: 29.99, quantity: 1 }], value: 29.99, currency: 'USD' }); // Purchase (with deduplication ID) _upstack('track', 'purchase', { items: [{ id: 'SKU123', name: 'Widget', price: 29.99, quantity: 1 }], value: 29.99, order_id: 'ORD-456', currency: 'USD' }, 'ORD-456'); ``` ### Page Exit Tracking with Beacon Reliably track time on page even when the user closes the tab: ```javascript theme={null} let pageLoadTime = Date.now(); window.addEventListener('visibilitychange', () => { if (document.visibilityState === 'hidden') { const timeOnPage = Math.round((Date.now() - pageLoadTime) / 1000); _upstack('track', 'page_exit', { time_on_page_seconds: timeOnPage, page_path: window.location.pathname }, { useBeacon: true }); } }); ``` ### Form Submission Tracking Capture leads from newsletter signups: ```javascript theme={null} document.querySelector('#newsletter-form').addEventListener('submit', (e) => { e.preventDefault(); const email = e.target.querySelector('[name="email"]').value; // Identify the user _upstack('identify', null, { emails: [email] }); // Track the lead event with beacon (in case form navigates away) _upstack('track', 'lead', { source: 'newsletter_signup', email: email }, { useBeacon: true }); // Submit the form e.target.submit(); }); ``` *** ## TypeScript Support Add type declarations for TypeScript projects: ```typescript theme={null} declare global { interface Window { _upstack: (...args: unknown[]) => void; _upsqueue: unknown[]; _upsClient: { init: (pixelId: string, identityTraits?: EventIdentityTraits, scriptSource?: string) => Promise<{ isInitialized: boolean; isDisabled: boolean }>; page: (eventData?: Record<string, unknown>) => void; track: (eventName: string, eventData?: Record<string, unknown>, eventId?: string, contextOverride?: Record<string, unknown>, collectedAt?: string, collectedAtEpoch?: number, options?: TrackOptions) => void; identify: (userId?: string | null, data?: EventIdentityTraits) => void; metric: (metricName: string, metricValue: number, metricData?: Record<string, unknown>, metricId?: string) => null; reset: () => void; isKnown: () => Promise<boolean>; getUpstackId: () => Promise<UpstackId>; _initialized: boolean; }; } } interface EventIdentityTraits { emails?: string[]; phones?: string[]; firstName?: string; lastName?: string; address?: { city?: string; state?: string; zip?: string; country?: string; }; } interface TrackOptions { useBeacon?: boolean; } interface UpstackId { _upstackId?: string; _upstackSid?: string; _upstackIp?: string; } export {}; ``` *** ## Methods NOT Available The following methods are **not implemented** in the public SDK: * `consent` — Not implemented * `group` — Not implemented (stub exists) * `screen` — Not implemented (stub exists) * `alias` — Not implemented (stub exists) Internal methods (do not call directly): * `notify` — Internal hook messaging * `postInit` — Internal post-initialization ## Related Documentation <CardGroup> <Card title="Pixel Setup" icon="download" href="/pixel/setup"> Installation guide for non-Shopify websites and SPAs. </Card> <Card title="Standard Events" icon="list-check" href="/pixel/standard-events"> Complete reference for all standard events with JavaScript snippets. </Card> <Card title="Properties & Context" icon="table" href="/pixel/events/event-properties"> Reference for item arrays, customer data, and auto-captured fields. </Card> <Card title="Custom Events" icon="sparkles" href="/pixel/custom-events"> Create events beyond the standard taxonomy for your needs. </Card> <Card title="Identity Resolution" icon="fingerprint" href="/pixel/identity-resolution"> How identify() connects sessions to customer profiles. </Card> <Card title="Shopify Automatic Tracking" icon="shopify" href="/sources/shopify-automatic-tracking"> Events tracked automatically on Shopify stores. </Card> </CardGroup> # SaaS & B2B Events Reference Source: https://docs.upstackdata.com/pixel/saas-events Track SaaS events with Upstack Data — subscription lifecycle, trials, payments, seat expansion, and user engagement with copyable JavaScript snippets. <Info> These events are designed for **B2B SaaS** and **subscription-based businesses**. If you're running an e-commerce store, see [Standard Events](/pixel/standard-events) instead. </Info> ## When to Use SaaS Events Use these events when your business model includes: * **Subscription billing** (monthly/annual plans) * **Free trials** with conversion tracking * **Seat-based pricing** with expansion revenue * **Multi-user accounts** with role-based access * **Product-led growth** with feature usage tracking *** ## Account Lifecycle Track account creation and deletion to measure growth and churn. ### account\_created Fires when a new account (organization/workspace) is created. #### JavaScript ```javascript theme={null} window._upstack('track', 'account_created', { accountId: 'acct_abc123', accountName: 'Acme Corporation', planId: 'plan_starter_monthly', planName: 'Starter', userId: 'usr_xyz789', userEmail: 'jane@acme.com' }); ``` #### Properties | Property | Type | Required | Description | | ----------- | ------ | -------- | ------------------------- | | accountId | string | Yes | Unique account identifier | | accountName | string | No | Account/organization name | | planId | string | No | Initial plan identifier | | planName | string | No | Initial plan name | | userId | string | No | Creating user's ID | | userEmail | string | No | Creating user's email | #### When to Fire * After account registration completes * After organization setup wizard finishes * After SSO provisioning creates a new workspace *** ### account\_deleted Fires when an account is permanently deleted. #### JavaScript ```javascript theme={null} window._upstack('track', 'account_deleted', { accountId: 'acct_abc123', accountName: 'Acme Corporation', cancelReason: 'no_longer_needed', cancelFeedback: 'Switching to a different solution', mrr: 9900 }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | -------------------------- | | accountId | string | Yes | Deleted account identifier | | accountName | string | No | Account name | | cancelReason | string | No | Reason code for deletion | | cancelFeedback | string | No | User-provided feedback | | mrr | number | No | Lost MRR in cents | #### When to Fire * After account deletion confirmation * After workspace removal completes * After data retention period expires *** ## Acquisition Track the lead-to-signup funnel to measure conversion rates. ### signup\_started Fires when a user begins the signup flow. #### JavaScript ```javascript theme={null} window._upstack('track', 'signup_started', { planId: 'plan_pro_monthly', source: 'pricing_page' }); ``` #### Properties | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------------- | | planId | string | No | Pre-selected plan (if applicable) | | source | string | No | Where signup was initiated | #### When to Fire * When signup form is opened * When registration page loads * When "Start Free Trial" button is clicked *** ### signup\_completed Fires when a user completes signup and creates an account. #### JavaScript ```javascript theme={null} window._upstack('track', 'signup_completed', { userId: 'usr_xyz789', accountId: 'acct_abc123', userEmail: 'jane@acme.com', planId: 'plan_pro_monthly', planName: 'Pro Plan' }); ``` #### Properties | Property | Type | Required | Description | | --------- | ------ | -------- | ---------------------- | | userId | string | Yes | New user identifier | | accountId | string | Yes | New account identifier | | userEmail | string | No | User email address | | planId | string | No | Selected plan | | planName | string | No | Plan display name | #### When to Fire * After signup form submission succeeds * After email verification completes * After OAuth signup flow finishes *** ### demo\_requested Fires when a user requests a product demo. #### JavaScript ```javascript theme={null} window._upstack('track', 'demo_requested', { userEmail: 'buyer@enterprise.com', companyName: 'Enterprise Corp', companySize: '500-1000', useCase: 'marketing_analytics' }); ``` #### Properties | Property | Type | Required | Description | | ----------- | ------ | -------- | ------------------ | | userEmail | string | No | Requester email | | companyName | string | No | Company name | | companySize | string | No | Company size range | | useCase | string | No | Primary use case | #### When to Fire * After demo request form submission * After sales call booking confirmation * After Calendly/HubSpot meeting scheduled *** ## Trial Events Track the trial lifecycle from start to conversion or expiry. ### trial\_started Fires when a user begins a free trial. #### JavaScript ```javascript theme={null} window._upstack('track', 'trial_started', { accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', trialEndDate: '2026-03-04T14:30:00.000Z', trialDaysRemaining: 14 }); ``` #### Properties | Property | Type | Required | Description | | ------------------ | ------ | -------- | ------------------------------ | | accountId | string | Yes | Account identifier | | planId | string | Yes | Trial plan identifier | | planName | string | No | Human-readable plan name | | trialEndDate | string | No | ISO 8601 trial expiration date | | trialDaysRemaining | number | No | Days until trial expires | #### When to Fire * After trial signup confirmation * After trial activation in billing system * After Stripe `customer.subscription.created` with trial *** ### trial\_activated Fires when a trial user reaches a meaningful activation milestone. #### JavaScript ```javascript theme={null} window._upstack('track', 'trial_activated', { accountId: 'acct_abc123', planId: 'plan_pro_monthly', trialDaysRemaining: 12, activationMilestone: 'first_integration_connected' }); ``` #### Properties | Property | Type | Required | Description | | ------------------- | ------ | -------- | --------------------------- | | accountId | string | Yes | Account identifier | | planId | string | No | Trial plan identifier | | trialDaysRemaining | number | No | Days remaining in trial | | activationMilestone | string | No | Which milestone was reached | #### When to Fire * After first key feature is used * After onboarding checklist is completed * After first data import succeeds *** ### trial\_extended Fires when a trial period is extended. #### JavaScript ```javascript theme={null} window._upstack('track', 'trial_extended', { accountId: 'acct_abc123', trialEndDate: '2026-03-11T14:30:00.000Z', trialDaysRemaining: 7, extensionReason: 'support_request' }); ``` #### Properties | Property | Type | Required | Description | | ------------------ | ------ | -------- | ---------------------- | | accountId | string | Yes | Account identifier | | trialEndDate | string | No | New trial end date | | trialDaysRemaining | number | No | New days remaining | | extensionReason | string | No | Why trial was extended | #### When to Fire * After support manually extends trial * After promotional extension is applied * After win-back campaign grants extension *** ### trial\_ending\_soon Fires when a trial is about to expire (typically 3 days before). #### JavaScript ```javascript theme={null} window._upstack('track', 'trial_ending_soon', { accountId: 'acct_abc123', trialDaysRemaining: 3, planId: 'plan_pro_monthly', trialEndDate: '2026-03-04T14:30:00.000Z' }); ``` #### Properties | Property | Type | Required | Description | | ------------------ | ------ | -------- | --------------------- | | accountId | string | Yes | Account identifier | | trialDaysRemaining | number | Yes | Days until expiry | | planId | string | No | Trial plan identifier | | trialEndDate | string | No | Trial expiration date | #### When to Fire * 3 days before trial expires (common) * When Stripe sends `customer.subscription.trial_will_end` * When automated warning email triggers *** ### trial\_expired Fires when a trial ends without conversion. #### JavaScript ```javascript theme={null} window._upstack('track', 'trial_expired', { accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', trialDays: 14 }); ``` #### Properties | Property | Type | Required | Description | | --------- | ------ | -------- | ------------------ | | accountId | string | Yes | Account identifier | | planId | string | No | Expired trial plan | | planName | string | No | Plan display name | | trialDays | number | No | Total trial length | #### When to Fire * When trial end date is reached without payment * When account is downgraded to free tier * When access is revoked after grace period *** ### trial\_converted Fires when a trial converts to a paid subscription. This is a key conversion event. #### JavaScript ```javascript theme={null} window._upstack('track', 'trial_converted', { accountId: 'acct_abc123', subscriptionId: 'sub_def456', planId: 'plan_pro_monthly', planName: 'Pro Plan', mrr: 9900, billingInterval: 'month' }); ``` #### Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ---------------------------------- | | accountId | string | Yes | Account identifier | | subscriptionId | string | Yes | New subscription ID | | planId | string | Yes | Converted plan identifier | | planName | string | No | Plan display name | | mrr | number | No | Monthly recurring revenue in cents | | billingInterval | string | No | `month` or `year` | #### When to Fire * After first successful payment * When Stripe subscription status changes from `trialing` to `active` * After payment method is charged successfully <Tip> Track `mrr` to measure trial-to-paid conversion value and calculate average revenue per converted trial. </Tip> *** ## Subscription Lifecycle Track the complete subscription journey from creation through churn or reactivation. ### subscription\_created Fires when a subscription record is created in your billing system. #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_created', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', billingInterval: 'month' }); ``` #### Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | --------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | Yes | Plan identifier | | planName | string | No | Plan display name | | billingInterval | string | No | `day`, `week`, `month`, or `year` | #### When to Fire * When subscription object is created in Stripe * May precede first payment (for trials) * After checkout session completes *** ### subscription\_started Fires when a new subscription begins (first billing period starts). #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_started', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', mrr: 9900, billingInterval: 'month' }); ``` #### Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ---------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | Yes | Plan identifier | | planName | string | No | Plan display name | | mrr | number | No | Monthly recurring revenue in cents | | billingInterval | string | No | Billing frequency | #### When to Fire * After first successful charge * When subscription status becomes `active` * After trial converts to paid *** ### subscription\_upgraded Fires when a customer upgrades to a higher-tier plan. #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_upgraded', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_business_monthly', planName: 'Business', previousPlanId: 'plan_pro_monthly', mrr: 19900, mrrDelta: 10000 }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | New plan identifier | | planName | string | No | New plan name | | previousPlanId | string | No | Previous plan identifier | | mrr | number | No | New MRR after upgrade in cents | | mrrDelta | number | No | MRR increase in cents (positive) | #### When to Fire * When plan changes from lower to higher tier * When Stripe subscription item is updated with higher-priced plan * After upgrade checkout completes <Tip> Track `mrrDelta` alongside `subscription_downgraded` to calculate net revenue retention. </Tip> *** ### subscription\_downgraded Fires when a customer downgrades to a lower-tier plan. #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_downgraded', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_starter_monthly', planName: 'Starter', previousPlanId: 'plan_pro_monthly', mrr: 4900, mrrDelta: -5000 }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | New plan identifier | | planName | string | No | New plan name | | previousPlanId | string | No | Previous plan identifier | | mrr | number | No | New MRR after downgrade in cents | | mrrDelta | number | No | MRR decrease in cents (negative) | #### When to Fire * When plan changes from higher to lower tier * When features are removed from subscription * When scheduled downgrade takes effect at period end *** ### subscription\_renewed <Note> This is a **custom event name**. For standard renewal tracking, consider using `payment_succeeded` or `invoice_paid` events instead. </Note> Fires when a subscription successfully renews for another billing period. #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_renewed', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', mrr: 9900, renewalCount: 6 }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ----------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Current plan identifier | | mrr | number | No | Renewed MRR in cents | | renewalCount | number | No | Number of times renewed | #### When to Fire * When recurring payment succeeds * When billing period advances * When Stripe `invoice.paid` fires for subscription *** ### subscription\_paused Fires when a subscription is paused. #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_paused', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', mrr: 9900, pauseReason: 'seasonal_business' }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | --------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Plan identifier | | mrr | number | No | Paused MRR in cents | | pauseReason | string | No | Why subscription was paused | #### When to Fire * When customer requests pause * When seasonal pause is activated * When Stripe subscription pause feature triggers *** ### subscription\_resumed Fires when a paused subscription is resumed. #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_resumed', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', mrr: 9900, pausedDays: 30 }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Plan identifier | | mrr | number | No | Resumed MRR in cents | | pausedDays | number | No | How long subscription was paused | #### When to Fire * When customer manually resumes * When pause period ends automatically * When billing restarts *** ### subscription\_cancelled Fires when a cancellation is requested (may still be active until period end). #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_cancelled', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', cancelReason: 'too_expensive', cancelFeedback: 'Budget constraints this quarter', mrr: 9900, cancelAtPeriodEnd: true }); ``` #### Properties | Property | Type | Required | Description | | ----------------- | ------- | -------- | ----------------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Cancelled plan | | cancelReason | string | No | Cancellation reason code | | cancelFeedback | string | No | User-provided feedback | | mrr | number | No | MRR being cancelled in cents | | cancelAtPeriodEnd | boolean | No | If true, cancels at end of billing period | #### When to Fire * When customer clicks cancel button * When cancellation request is submitted * When Stripe subscription is set to cancel at period end *** ### subscription\_churned Fires when a subscription ends completely (no longer billing). This is the final churn event. #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_churned', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', cancelReason: 'switched_competitor', mrr: 9900, ltv: 118800, subscriptionMonths: 12 }); ``` #### Properties | Property | Type | Required | Description | | ------------------ | ------ | -------- | -------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Churned plan | | cancelReason | string | No | Churn reason | | mrr | number | No | Lost MRR in cents | | ltv | number | No | Customer lifetime value in cents | | subscriptionMonths | number | No | How long they were subscribed | #### When to Fire * When final billing period ends * When subscription is deactivated * When Stripe `customer.subscription.deleted` fires <Warning> Use this event to calculate churn rate and analyze churn reasons. Track `ltv` to understand which customer segments have the highest lifetime value. </Warning> *** ### subscription\_initial\_purchase Fires when a customer's first subscription payment is processed (distinct from trial conversion). #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_initial_purchase', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', value: 9900, currency: 'USD', billingInterval: 'month' }); ``` #### Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ----------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Plan identifier | | planName | string | No | Plan display name | | value | number | No | Payment amount in cents | | currency | string | No | ISO 4217 currency code | | billingInterval | string | No | `month` or `year` | #### When to Fire * First subscription charge succeeds * After trial converts (first paid billing period) * When new customer's initial payment processes *** ### subscription\_recurring\_purchase Fires when a recurring subscription payment is processed (not the initial purchase). #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_recurring_purchase', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', value: 9900, currency: 'USD', billingInterval: 'month', renewalNumber: 6 }); ``` #### Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | -------------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Plan identifier | | planName | string | No | Plan display name | | value | number | No | Payment amount in cents | | currency | string | No | ISO 4217 currency code | | billingInterval | string | No | `month` or `year` | | renewalNumber | number | No | Which renewal this is (2nd, 3rd, etc.) | #### When to Fire * Each recurring billing cycle * When Stripe `invoice.paid` fires for an existing subscription * Monthly/annual renewal charge succeeds <Tip> Use `subscription_initial_purchase` for acquisition metrics and `subscription_recurring_purchase` for retention/LTV analysis. Together they give a complete picture of subscription revenue. </Tip> *** ### subscription\_reactivated Fires when a previously churned customer resubscribes. #### JavaScript ```javascript theme={null} window._upstack('track', 'subscription_reactivated', { subscriptionId: 'sub_ghi789', accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', mrr: 9900, daysSinceChurn: 45 }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ----------------------------------- | | subscriptionId | string | Yes | New subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | New plan identifier | | planName | string | No | Plan display name | | mrr | number | No | Recovered MRR in cents | | daysSinceChurn | number | No | Days between churn and reactivation | #### When to Fire * When former customer signs up again * When win-back campaign converts * When churned account starts new subscription *** ## Order Fulfillment Events Track order fulfillment and shipping for e-commerce subscription boxes, physical product deliveries, and Klaviyo flow triggers. ### order\_fulfilled Fires when an order has been completely fulfilled (all items prepared for shipment). #### JavaScript ```javascript theme={null} window._upstack('track', 'order_fulfilled', { orderId: 'ORD_12345', orderName: '#1042', value: 149.99, currency: 'USD', fulfillmentStatus: 'fulfilled', items: [ { id: 'SKU_001', name: 'Monthly Snack Box', price: 39.99, quantity: 1 } ], email: 'customer@example.com' }); ``` #### Properties | Property | Type | Required | Description | | ----------------- | ------ | -------- | ----------------------------------------------------- | | orderId | string | Yes | Order identifier | | orderName | string | No | Human-readable order name | | value | number | No | Order value | | currency | string | No | ISO 4217 currency code | | fulfillmentStatus | string | No | Fulfillment status (e.g., `'fulfilled'`, `'partial'`) | | items | array | No | Products fulfilled | | email | string | No | Customer email | #### When to Fire * When warehouse marks order as packed/ready * When Shopify fulfillment is created * When all items in an order are fulfilled *** ### order\_shipped Fires when an order has been shipped and tracking information is available. #### JavaScript ```javascript theme={null} window._upstack('track', 'order_shipped', { orderId: 'ORD_12345', orderName: '#1042', value: 149.99, currency: 'USD', trackingNumber: '1Z999AA10123456784', trackingCompany: 'UPS', trackingUrl: 'https://www.ups.com/track?tracknum=1Z999AA10123456784', estimatedDelivery: '2026-02-25T00:00:00.000Z', items: [ { id: 'SKU_001', name: 'Monthly Snack Box', price: 39.99, quantity: 1 } ], email: 'customer@example.com' }); ``` #### Properties | Property | Type | Required | Description | | ----------------- | ------ | -------- | ----------------------------------------------------- | | orderId | string | Yes | Order identifier | | orderName | string | No | Human-readable order name | | value | number | No | Order value | | currency | string | No | ISO 4217 currency code | | trackingNumber | string | No | Carrier tracking number | | trackingCompany | string | No | Shipping carrier (e.g., `'UPS'`, `'FedEx'`, `'USPS'`) | | trackingUrl | string | No | Direct link to tracking page | | estimatedDelivery | string | No | ISO 8601 estimated delivery date | | items | array | No | Products shipped | | email | string | No | Customer email | #### When to Fire * When shipping label is created with tracking * When carrier picks up package * When Shopify `fulfillment_events/create` webhook fires <Tip> **Klaviyo integration:** `order_shipped` is commonly used to trigger post-purchase flows like "Your order is on the way" emails with tracking information. </Tip> *** ## User Events Track team growth and user engagement within accounts. ### user\_invited Fires when a user is invited to join an account. #### JavaScript ```javascript theme={null} window._upstack('track', 'user_invited', { accountId: 'acct_abc123', inviteeEmail: 'newmember@acme.com', inviteeRole: 'member', invitedByUserId: 'usr_xyz789' }); ``` #### Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | --------------------- | | accountId | string | Yes | Account identifier | | inviteeEmail | string | No | Invitee email address | | inviteeRole | string | No | Assigned role | | invitedByUserId | string | No | Inviter's user ID | #### When to Fire * When team invite is sent * When collaboration request is initiated * After invite email is dispatched *** ### user\_joined Fires when an invited user accepts and joins the account. #### JavaScript ```javascript theme={null} window._upstack('track', 'user_joined', { userId: 'usr_newmember', accountId: 'acct_abc123', userEmail: 'newmember@acme.com', userRole: 'member' }); ``` #### Properties | Property | Type | Required | Description | | --------- | ------ | -------- | -------------------- | | userId | string | Yes | New user identifier | | accountId | string | Yes | Account identifier | | userEmail | string | No | User email address | | userRole | string | No | User's assigned role | #### When to Fire * When invite is accepted * When account access is granted * After user completes join flow *** ### user\_role\_changed <Note> This is a **custom event name**. Track it using the [Custom Events](/pixel/custom-events) pattern if you need role change analytics. </Note> Fires when a user's role is changed within an account. #### JavaScript ```javascript theme={null} window._upstack('track', 'user_role_changed', { userId: 'usr_xyz789', accountId: 'acct_abc123', previousRole: 'member', newRole: 'admin', changedByUserId: 'usr_admin123' }); ``` #### Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ------------------------- | | userId | string | Yes | User whose role changed | | accountId | string | Yes | Account identifier | | previousRole | string | No | Previous role | | newRole | string | No | New role | | changedByUserId | string | No | Admin who made the change | #### When to Fire * When user is promoted to admin * When permissions are modified * After role update is saved *** ## Billing Events Track payment activity for revenue analytics and dunning workflows. ### payment\_succeeded Fires when a payment is processed successfully. #### JavaScript ```javascript theme={null} window._upstack('track', 'payment_succeeded', { accountId: 'acct_abc123', invoiceId: 'inv_ghi012', subscriptionId: 'sub_def456', amount: 9900, currency: 'USD' }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ----------------------- | | accountId | string | Yes | Account identifier | | amount | number | Yes | Payment amount in cents | | invoiceId | string | No | Invoice identifier | | subscriptionId | string | No | Subscription identifier | | currency | string | No | ISO 4217 currency code | #### When to Fire * When charge succeeds * When invoice is paid * When Stripe `invoice.paid` webhook fires *** ### payment\_failed Fires when a payment attempt fails. #### JavaScript ```javascript theme={null} window._upstack('track', 'payment_failed', { accountId: 'acct_abc123', invoiceId: 'inv_ghi012', subscriptionId: 'sub_def456', amount: 9900, failureReason: 'card_declined', failureCode: 'insufficient_funds', currency: 'USD' }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ------------------------------ | | accountId | string | Yes | Account identifier | | amount | number | Yes | Failed payment amount in cents | | invoiceId | string | No | Invoice identifier | | subscriptionId | string | No | Subscription identifier | | failureReason | string | No | Failure reason code | | failureCode | string | No | Detailed failure code | | currency | string | No | ISO 4217 currency code | #### When to Fire * When card is declined * When insufficient funds error occurs * When Stripe `invoice.payment_failed` webhook fires <Warning> Track payment failures to identify at-risk customers and trigger dunning workflows. </Warning> *** ### invoice\_paid Fires when an invoice is marked as paid. #### JavaScript ```javascript theme={null} window._upstack('track', 'invoice_paid', { accountId: 'acct_abc123', invoiceId: 'inv_ghi012', subscriptionId: 'sub_def456', amount: 9900, currency: 'USD' }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ----------------------- | | accountId | string | Yes | Account identifier | | invoiceId | string | Yes | Invoice identifier | | amount | number | Yes | Paid amount in cents | | subscriptionId | string | No | Subscription identifier | | currency | string | No | ISO 4217 currency code | #### When to Fire * When payment is received * When manual reconciliation marks invoice paid * When Stripe `invoice.paid` webhook fires *** ## Expansion Events Track seat-based and add-on revenue expansion. ### seat\_added Fires when additional seats are purchased. #### JavaScript ```javascript theme={null} window._upstack('track', 'seat_added', { accountId: 'acct_abc123', subscriptionId: 'sub_def456', seatCount: 15, seatDelta: 5, mrrDelta: 2500 }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------- | | accountId | string | Yes | Account identifier | | seatCount | number | Yes | Total seats after addition | | subscriptionId | string | No | Subscription identifier | | seatDelta | number | No | Number of seats added | | mrrDelta | number | No | MRR increase from seats in cents | #### When to Fire * When seats are purchased * When user is added beyond plan limit * When Stripe subscription quantity increases *** ### seat\_removed Fires when seats are removed from the plan. #### JavaScript ```javascript theme={null} window._upstack('track', 'seat_removed', { accountId: 'acct_abc123', subscriptionId: 'sub_def456', seatCount: 10, seatDelta: -5, mrrDelta: -2500 }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ---------------------------------- | | accountId | string | Yes | Account identifier | | seatCount | number | Yes | Total seats after removal | | subscriptionId | string | No | Subscription identifier | | seatDelta | number | No | Number of seats removed (negative) | | mrrDelta | number | No | MRR decrease in cents (negative) | #### When to Fire * When seats are removed * When user is deactivated * When Stripe subscription quantity decreases *** ## Engagement Events Track user activity and product milestones. ### feature\_used Fires when a specific feature is used. Track key features to understand product adoption. #### JavaScript ```javascript theme={null} window._upstack('track', 'feature_used', { accountId: 'acct_abc123', userId: 'usr_xyz789', featureId: 'feat_export', featureName: 'CSV Export', featureCategory: 'reporting' }); ``` #### Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ------------------------- | | accountId | string | Yes | Account identifier | | featureId | string | Yes | Feature identifier | | userId | string | No | User who used the feature | | featureName | string | No | Feature display name | | featureCategory | string | No | Feature category | #### When to Fire * When key features are used * When premium features are accessed * When usage-based actions are performed *** ### milestone\_reached Fires when a key milestone is achieved. #### JavaScript ```javascript theme={null} window._upstack('track', 'milestone_reached', { accountId: 'acct_abc123', milestoneId: 'milestone_100_orders', milestoneName: '100 Orders Processed', milestoneValue: 100 }); ``` #### Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ---------------------- | | accountId | string | Yes | Account identifier | | milestoneId | string | Yes | Milestone identifier | | milestoneName | string | No | Milestone display name | | milestoneValue | number | No | Numeric value achieved | #### When to Fire * When usage threshold is crossed * When achievement is unlocked * When significant product milestone occurs *** ## Stripe Webhook Integration If you use Stripe for billing, handle webhooks to track events automatically. <Warning> Webhook handlers run server-side where `window._upstack()` is not available. Server-side event tracking requires the Upstack Server API. Contact support for early access, or use the patterns below to queue events for client-side tracking. </Warning> ### Server-Side Helper Pattern Create a helper to queue events for server-side tracking: ```javascript theme={null} // utils/tracking.js async function trackServerEvent(eventName, properties) { // Option 1: Direct API call (requires Server API access) await fetch('https://api.getupstack.com/v1/events', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${process.env.UPSTACK_API_KEY}` }, body: JSON.stringify({ event: eventName, properties, timestamp: new Date().toISOString() }) }); // Option 2: Store in database for later sync // await db.pendingEvents.create({ eventName, properties }); } ``` ### Example Webhook Handler ```javascript theme={null} // Express.js webhook handler (server-side) app.post('/webhooks/stripe', async (req, res) => { const event = stripe.webhooks.constructEvent( req.body, req.headers['stripe-signature'], process.env.STRIPE_WEBHOOK_SECRET ); switch (event.type) { case 'customer.subscription.created': const sub = event.data.object; await trackServerEvent('subscription_created', { subscriptionId: sub.id, accountId: sub.metadata.account_id, planId: sub.items.data[0].price.id, billingInterval: sub.items.data[0].price.recurring.interval }); break; case 'customer.subscription.updated': const updated = event.data.object; const previous = event.data.previous_attributes; if (previous.items) { const newPrice = updated.items.data[0].price.unit_amount; const oldPrice = previous.items.data[0].price.unit_amount; if (newPrice > oldPrice) { await trackServerEvent('subscription_upgraded', { subscriptionId: updated.id, accountId: updated.metadata.account_id, planId: updated.items.data[0].price.id, mrrDelta: newPrice - oldPrice }); } else { await trackServerEvent('subscription_downgraded', { subscriptionId: updated.id, accountId: updated.metadata.account_id, planId: updated.items.data[0].price.id, mrrDelta: newPrice - oldPrice }); } } break; case 'customer.subscription.deleted': const deleted = event.data.object; await trackServerEvent('subscription_churned', { subscriptionId: deleted.id, accountId: deleted.metadata.account_id, planId: deleted.items.data[0].price.id, mrr: deleted.items.data[0].price.unit_amount }); break; case 'invoice.paid': const invoice = event.data.object; await trackServerEvent('payment_succeeded', { accountId: invoice.metadata.account_id, invoiceId: invoice.id, subscriptionId: invoice.subscription, amount: invoice.amount_paid, currency: invoice.currency.toUpperCase() }); break; case 'invoice.payment_failed': const failed = event.data.object; await trackServerEvent('payment_failed', { accountId: failed.metadata.account_id, invoiceId: failed.id, subscriptionId: failed.subscription, amount: failed.amount_due, failureReason: failed.last_payment_error?.code }); break; case 'customer.subscription.trial_will_end': const trial = event.data.object; await trackServerEvent('trial_ending_soon', { accountId: trial.metadata.account_id, trialDaysRemaining: 3, planId: trial.items.data[0].price.id, trialEndDate: new Date(trial.trial_end * 1000).toISOString() }); break; } res.json({ received: true }); }); ``` ### Stripe Webhook Mapping | Stripe Webhook | Upstack Event | | -------------------------------------- | --------------------------------------------------- | | `customer.subscription.created` | `subscription_created` | | `customer.subscription.updated` | `subscription_upgraded` / `subscription_downgraded` | | `customer.subscription.deleted` | `subscription_churned` | | `customer.subscription.paused` | `subscription_paused` | | `customer.subscription.resumed` | `subscription_resumed` | | `invoice.paid` | `invoice_paid`, `payment_succeeded` | | `invoice.payment_failed` | `payment_failed` | | `customer.subscription.trial_will_end` | `trial_ending_soon` | | `charge.refunded` | `payment_refunded` | *** ## What's Next <CardGroup> <Card title="Standard Events" icon="list-check" href="/pixel/standard-events"> E-commerce event reference for Shopify stores. </Card> <Card title="Custom Events" icon="code" href="/pixel/custom-events"> Define your own events beyond the standard taxonomy. </Card> <Card title="Properties & Context" icon="table" href="/pixel/events/event-properties"> Complete reference for all event fields. </Card> <Card title="Event Taxonomy" icon="sitemap" href="/pixel/events/taxonomy"> How events flow through the Upstack pipeline. </Card> </CardGroup> # account_created Event Source: https://docs.upstackdata.com/pixel/saas-events/account-created Track when a new account (organization/workspace) is created in your SaaS application. Fires when a new account (organization/workspace) is created. Use this event to measure account growth and track the top of your B2B funnel. ## JavaScript ```javascript theme={null} window._upstack('track', 'account_created', { accountId: 'acct_abc123', accountName: 'Acme Corporation', planId: 'plan_starter_monthly', planName: 'Starter', userId: 'usr_xyz789', userEmail: 'jane@acme.com' }); ``` ## Properties | Property | Type | Required | Description | | ----------- | ------ | -------- | ------------------------- | | accountId | string | Yes | Unique account identifier | | accountName | string | No | Account/organization name | | planId | string | No | Initial plan identifier | | planName | string | No | Initial plan name | | userId | string | No | Creating user's ID | | userEmail | string | No | Creating user's email | ## When to Fire * After account registration completes * After organization setup wizard finishes * After SSO provisioning creates a new workspace # account_deleted Event Source: https://docs.upstackdata.com/pixel/saas-events/account-deleted Track when an account is permanently deleted from your SaaS application. Fires when an account is permanently deleted. Track this event to measure churn and understand why customers leave. ## JavaScript ```javascript theme={null} window._upstack('track', 'account_deleted', { accountId: 'acct_abc123', accountName: 'Acme Corporation', cancelReason: 'no_longer_needed', cancelFeedback: 'Switching to a different solution', mrr: 9900 }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | -------------------------- | | accountId | string | Yes | Deleted account identifier | | accountName | string | No | Account name | | cancelReason | string | No | Reason code for deletion | | cancelFeedback | string | No | User-provided feedback | | mrr | number | No | Lost MRR in cents | ## When to Fire * After account deletion confirmation * After workspace removal completes * After data retention period expires # addon_cancelled Event Source: https://docs.upstackdata.com/pixel/saas-events/addon-cancelled Track when a customer cancels an add-on feature or service. Fires when a customer cancels an add-on feature or service. Use this event to understand add-on churn and feature value. ## JavaScript ```javascript theme={null} window._upstack('track', 'addon_cancelled', { accountId: 'acct_abc123', subscriptionId: 'sub_def456', addonId: 'addon_advanced_analytics', addonName: 'Advanced Analytics', price: 4900, currency: 'USD', cancelReason: 'not_using' }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ---------------------------- | | accountId | string | Yes | Account identifier | | addonId | string | Yes | Add-on identifier | | subscriptionId | string | No | Subscription identifier | | addonName | string | No | Human-readable add-on name | | price | number | No | Lost add-on revenue in cents | | currency | string | No | ISO 4217 currency code | | cancelReason | string | No | Reason for cancellation | ## When to Fire * When add-on is removed from subscription * When add-on cancellation is requested * When Stripe subscription item is removed # addon_purchased Event Source: https://docs.upstackdata.com/pixel/saas-events/addon-purchased Track when a customer purchases an add-on feature or service. Fires when a customer purchases an add-on feature or service. Use this event to measure add-on adoption and expansion revenue. ## JavaScript ```javascript theme={null} window._upstack('track', 'addon_purchased', { accountId: 'acct_abc123', subscriptionId: 'sub_def456', addonId: 'addon_advanced_analytics', addonName: 'Advanced Analytics', price: 4900, currency: 'USD', billingInterval: 'month' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | -------------------------- | | accountId | string | Yes | Account identifier | | addonId | string | Yes | Add-on identifier | | subscriptionId | string | No | Subscription identifier | | addonName | string | No | Human-readable add-on name | | price | number | No | Add-on price in cents | | currency | string | No | ISO 4217 currency code | | billingInterval | string | No | `month` or `year` | ## When to Fire * When add-on is purchased from settings * When add-on checkout completes * When Stripe subscription item is added # content_downloaded Event Source: https://docs.upstackdata.com/pixel/saas-events/content-downloaded Track when a user downloads gated content like whitepapers, ebooks, or case studies. Fires when a user downloads gated content. Use this event to measure content marketing effectiveness and identify marketing-qualified leads. ## JavaScript ```javascript theme={null} window._upstack('track', 'content_downloaded', { contentId: 'wp_2024_analytics_guide', contentType: 'whitepaper', contentTitle: '2024 Marketing Analytics Guide', userEmail: 'prospect@company.com', companyName: 'Prospect Corp', source: 'blog_cta' }); ``` ## Properties | Property | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------------------------------------------------- | | contentId | string | Yes | Unique content identifier | | contentType | string | No | Type of content (`whitepaper`, `ebook`, `case_study`, `template`, `guide`) | | contentTitle | string | No | Human-readable content title | | userEmail | string | No | Downloader's email address | | companyName | string | No | User's company name | | source | string | No | Where the download was initiated | ## When to Fire * After gated content form submission * After PDF/document download starts * After content access is granted via email gate # demo_requested Event Source: https://docs.upstackdata.com/pixel/saas-events/demo-requested Track when a user requests a product demo in your SaaS application. Fires when a user requests a product demo. Use this event to measure sales-qualified leads and demo conversion rates. ## JavaScript ```javascript theme={null} window._upstack('track', 'demo_requested', { userEmail: 'buyer@enterprise.com', companyName: 'Enterprise Corp', companySize: '500-1000', useCase: 'marketing_analytics' }); ``` ## Properties | Property | Type | Required | Description | | ----------- | ------ | -------- | ------------------ | | userEmail | string | No | Requester email | | companyName | string | No | Company name | | companySize | string | No | Company size range | | useCase | string | No | Primary use case | ## When to Fire * After demo request form submission * After sales call booking confirmation * After Calendly/HubSpot meeting scheduled # feature_used Event Source: https://docs.upstackdata.com/pixel/saas-events/feature-used Track when a specific feature is used to understand product adoption. Fires when a specific feature is used. Track key features to understand product adoption and identify power users. ## JavaScript ```javascript theme={null} window._upstack('track', 'feature_used', { accountId: 'acct_abc123', userId: 'usr_xyz789', featureId: 'feat_export', featureName: 'CSV Export', featureCategory: 'reporting' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ------------------------- | | accountId | string | Yes | Account identifier | | featureId | string | Yes | Feature identifier | | userId | string | No | User who used the feature | | featureName | string | No | Feature display name | | featureCategory | string | No | Feature category | ## When to Fire * When key features are used * When premium features are accessed * When usage-based actions are performed # invoice_created Event Source: https://docs.upstackdata.com/pixel/saas-events/invoice-created Track when a new invoice is created in the billing system. Fires when a new invoice is created in the billing system. Use this event to track billing cycles and invoice generation. ## JavaScript ```javascript theme={null} window._upstack('track', 'invoice_created', { accountId: 'acct_abc123', invoiceId: 'inv_ghi012', subscriptionId: 'sub_def456', amount: 9900, currency: 'USD', dueDate: '2026-03-01T00:00:00.000Z' }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ----------------------- | | accountId | string | Yes | Account identifier | | invoiceId | string | Yes | Invoice identifier | | amount | number | Yes | Invoice amount in cents | | subscriptionId | string | No | Subscription identifier | | currency | string | No | ISO 4217 currency code | | dueDate | string | No | ISO 8601 due date | ## When to Fire * When invoice is generated * When billing cycle creates new invoice * When Stripe `invoice.created` webhook fires ## Stripe Webhook Maps to `invoice.created`. # invoice_paid Event Source: https://docs.upstackdata.com/pixel/saas-events/invoice-paid Track when an invoice is marked as paid. Fires when an invoice is marked as paid. Use this event for revenue recognition and payment tracking. ## JavaScript ```javascript theme={null} window._upstack('track', 'invoice_paid', { accountId: 'acct_abc123', invoiceId: 'inv_ghi012', subscriptionId: 'sub_def456', amount: 9900, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ----------------------- | | accountId | string | Yes | Account identifier | | invoiceId | string | Yes | Invoice identifier | | amount | number | Yes | Paid amount in cents | | subscriptionId | string | No | Subscription identifier | | currency | string | No | ISO 4217 currency code | ## When to Fire * When payment is received * When manual reconciliation marks invoice paid * When Stripe `invoice.paid` webhook fires ## Stripe Webhook Maps to `invoice.paid`. # invoice_past_due Event Source: https://docs.upstackdata.com/pixel/saas-events/invoice-past-due Track when an invoice becomes past due. Fires when an invoice becomes past due. Use this event to trigger collection workflows and identify accounts at risk of involuntary churn. ## JavaScript ```javascript theme={null} window._upstack('track', 'invoice_past_due', { accountId: 'acct_abc123', invoiceId: 'inv_ghi012', subscriptionId: 'sub_def456', amount: 9900, currency: 'USD', daysOverdue: 7, attemptCount: 3 }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ------------------------------- | | accountId | string | Yes | Account identifier | | invoiceId | string | Yes | Invoice identifier | | amount | number | Yes | Past due amount in cents | | subscriptionId | string | No | Subscription identifier | | currency | string | No | ISO 4217 currency code | | daysOverdue | number | No | Days past the due date | | attemptCount | number | No | Number of payment attempts made | ## When to Fire * When invoice due date passes without payment * When Stripe marks invoice as past due * When payment retry fails ## Stripe Webhook Maps to `invoice.marked_uncollectible` or custom logic based on `invoice.payment_failed` status. <Warning> Past due invoices are an early indicator of involuntary churn. Use this event to trigger proactive outreach. </Warning> # milestone_reached Event Source: https://docs.upstackdata.com/pixel/saas-events/milestone-reached Track when a key milestone is achieved. Fires when a key milestone is achieved. Use this event to celebrate customer success and trigger engagement flows. ## JavaScript ```javascript theme={null} window._upstack('track', 'milestone_reached', { accountId: 'acct_abc123', milestoneId: 'milestone_100_orders', milestoneName: '100 Orders Processed', milestoneValue: 100 }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ---------------------- | | accountId | string | Yes | Account identifier | | milestoneId | string | Yes | Milestone identifier | | milestoneName | string | No | Milestone display name | | milestoneValue | number | No | Numeric value achieved | ## When to Fire * When usage threshold is crossed * When achievement is unlocked * When significant product milestone occurs # order_fulfilled Event Source: https://docs.upstackdata.com/pixel/saas-events/order-fulfilled Track when an order has been completely fulfilled (all items prepared for shipment). Fires when an order has been completely fulfilled (all items prepared for shipment). Use this event for subscription box businesses and physical product deliveries. ## JavaScript ```javascript theme={null} window._upstack('track', 'order_fulfilled', { orderId: 'ORD_12345', orderName: '#1042', value: 149.99, currency: 'USD', fulfillmentStatus: 'fulfilled', items: [ { id: 'SKU_001', name: 'Monthly Snack Box', price: 39.99, quantity: 1 } ], email: 'customer@example.com' }); ``` ## Properties | Property | Type | Required | Description | | ----------------- | ------ | -------- | ----------------------------------------------------- | | orderId | string | Yes | Order identifier | | orderName | string | No | Human-readable order name | | value | number | No | Order value | | currency | string | No | ISO 4217 currency code | | fulfillmentStatus | string | No | Fulfillment status (e.g., `'fulfilled'`, `'partial'`) | | items | array | No | Products fulfilled | | email | string | No | Customer email | ## When to Fire * When warehouse marks order as packed/ready * When Shopify fulfillment is created * When all items in an order are fulfilled # order_shipped Event Source: https://docs.upstackdata.com/pixel/saas-events/order-shipped Track when an order has been shipped and tracking information is available. Fires when an order has been shipped and tracking information is available. Use this event to trigger shipment notification flows. ## JavaScript ```javascript theme={null} window._upstack('track', 'order_shipped', { orderId: 'ORD_12345', orderName: '#1042', value: 149.99, currency: 'USD', trackingNumber: '1Z999AA10123456784', trackingCompany: 'UPS', trackingUrl: 'https://www.ups.com/track?tracknum=1Z999AA10123456784', estimatedDelivery: '2026-02-25T00:00:00.000Z', items: [ { id: 'SKU_001', name: 'Monthly Snack Box', price: 39.99, quantity: 1 } ], email: 'customer@example.com' }); ``` ## Properties | Property | Type | Required | Description | | ----------------- | ------ | -------- | ----------------------------------------------------- | | orderId | string | Yes | Order identifier | | orderName | string | No | Human-readable order name | | value | number | No | Order value | | currency | string | No | ISO 4217 currency code | | trackingNumber | string | No | Carrier tracking number | | trackingCompany | string | No | Shipping carrier (e.g., `'UPS'`, `'FedEx'`, `'USPS'`) | | trackingUrl | string | No | Direct link to tracking page | | estimatedDelivery | string | No | ISO 8601 estimated delivery date | | items | array | No | Products shipped | | email | string | No | Customer email | ## When to Fire * When shipping label is created with tracking * When carrier picks up package * When Shopify `fulfillment_events/create` webhook fires <Tip> **Klaviyo integration:** `order_shipped` is commonly used to trigger post-purchase flows like "Your order is on the way" emails with tracking information. </Tip> # payment_failed Event Source: https://docs.upstackdata.com/pixel/saas-events/payment-failed Track when a payment attempt fails. Fires when a payment attempt fails. Use this event to trigger dunning workflows and identify at-risk subscriptions. ## JavaScript ```javascript theme={null} window._upstack('track', 'payment_failed', { accountId: 'acct_abc123', invoiceId: 'inv_ghi012', subscriptionId: 'sub_def456', amount: 9900, failureReason: 'card_declined', failureCode: 'insufficient_funds', currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ------------------------------ | | accountId | string | Yes | Account identifier | | amount | number | Yes | Failed payment amount in cents | | invoiceId | string | No | Invoice identifier | | subscriptionId | string | No | Subscription identifier | | failureReason | string | No | Failure reason code | | failureCode | string | No | Detailed failure code | | currency | string | No | ISO 4217 currency code | ## When to Fire * When card is declined * When insufficient funds error occurs * When Stripe `invoice.payment_failed` webhook fires ## Stripe Webhook Maps to `invoice.payment_failed`. <Warning> Track payment failures to identify at-risk customers and trigger dunning workflows. </Warning> # payment_refunded Event Source: https://docs.upstackdata.com/pixel/saas-events/payment-refunded Track when a payment is refunded to the customer. Fires when a payment is refunded to the customer. Use this event to track refund rates and understand customer satisfaction issues. ## JavaScript ```javascript theme={null} window._upstack('track', 'payment_refunded', { accountId: 'acct_abc123', invoiceId: 'inv_ghi012', chargeId: 'ch_abc123', subscriptionId: 'sub_def456', amount: 9900, refundReason: 'customer_request', currency: 'USD', isPartialRefund: false }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------- | -------- | -------------------------------- | | accountId | string | Yes | Account identifier | | amount | number | Yes | Refunded amount in cents | | chargeId | string | No | Original charge identifier | | invoiceId | string | No | Invoice identifier | | subscriptionId | string | No | Subscription identifier | | refundReason | string | No | Reason for refund | | currency | string | No | ISO 4217 currency code | | isPartialRefund | boolean | No | Whether this is a partial refund | ## When to Fire * When refund is processed * When Stripe `charge.refunded` webhook fires * When support issues refund ## Stripe Webhook Maps to `charge.refunded`. # payment_succeeded Event Source: https://docs.upstackdata.com/pixel/saas-events/payment-succeeded Track when a payment is processed successfully. Fires when a payment is processed successfully. Use this event for revenue tracking and payment analytics. ## JavaScript ```javascript theme={null} window._upstack('track', 'payment_succeeded', { accountId: 'acct_abc123', invoiceId: 'inv_ghi012', subscriptionId: 'sub_def456', amount: 9900, currency: 'USD' }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ----------------------- | | accountId | string | Yes | Account identifier | | amount | number | Yes | Payment amount in cents | | invoiceId | string | No | Invoice identifier | | subscriptionId | string | No | Subscription identifier | | currency | string | No | ISO 4217 currency code | ## When to Fire * When charge succeeds * When invoice is paid * When Stripe `invoice.paid` webhook fires ## Stripe Webhook Maps to `invoice.paid` or `charge.succeeded`. # seat_added Event Source: https://docs.upstackdata.com/pixel/saas-events/seat-added Track when additional seats are purchased. Fires when additional seats are purchased. Use this event to measure expansion revenue from seat-based pricing. ## JavaScript ```javascript theme={null} window._upstack('track', 'seat_added', { accountId: 'acct_abc123', subscriptionId: 'sub_def456', seatCount: 15, seatDelta: 5, mrrDelta: 2500 }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------- | | accountId | string | Yes | Account identifier | | seatCount | number | Yes | Total seats after addition | | subscriptionId | string | No | Subscription identifier | | seatDelta | number | No | Number of seats added | | mrrDelta | number | No | MRR increase from seats in cents | ## When to Fire * When seats are purchased * When user is added beyond plan limit * When Stripe subscription quantity increases ## Stripe Webhook Maps to `customer.subscription.updated` when subscription quantity increases. # seat_removed Event Source: https://docs.upstackdata.com/pixel/saas-events/seat-removed Track when seats are removed from the plan. Fires when seats are removed from the plan. Use this event to track seat contraction and understand downsizing patterns. ## JavaScript ```javascript theme={null} window._upstack('track', 'seat_removed', { accountId: 'acct_abc123', subscriptionId: 'sub_def456', seatCount: 10, seatDelta: -5, mrrDelta: -2500 }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ---------------------------------- | | accountId | string | Yes | Account identifier | | seatCount | number | Yes | Total seats after removal | | subscriptionId | string | No | Subscription identifier | | seatDelta | number | No | Number of seats removed (negative) | | mrrDelta | number | No | MRR decrease in cents (negative) | ## When to Fire * When seats are removed * When user is deactivated * When Stripe subscription quantity decreases ## Stripe Webhook Maps to `customer.subscription.updated` when subscription quantity decreases. # signed_out Event Source: https://docs.upstackdata.com/pixel/saas-events/signed-out Track when a user signs out of the application. Fires when a user signs out of the application. Use this event to understand session patterns and user behavior. ## JavaScript ```javascript theme={null} window._upstack('track', 'signed_out', { userId: 'usr_xyz789', accountId: 'acct_abc123', sessionDuration: 3600, signOutReason: 'user_initiated' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------------------------------------- | | userId | string | Yes | User identifier | | accountId | string | No | Account identifier | | sessionDuration | number | No | Session length in seconds | | signOutReason | string | No | Reason for sign out (`user_initiated`, `session_expired`, `forced`) | ## When to Fire * When user clicks sign out/logout button * When session expires * When user is forced out due to security event # signup_completed Event Source: https://docs.upstackdata.com/pixel/saas-events/signup-completed Track when a user completes signup and creates an account in your SaaS application. Fires when a user completes signup and creates an account. This is a key conversion event for measuring acquisition success. ## JavaScript ```javascript theme={null} window._upstack('track', 'signup_completed', { userId: 'usr_xyz789', accountId: 'acct_abc123', userEmail: 'jane@acme.com', planId: 'plan_pro_monthly', planName: 'Pro Plan' }); ``` ## Properties | Property | Type | Required | Description | | --------- | ------ | -------- | ---------------------- | | userId | string | Yes | New user identifier | | accountId | string | Yes | New account identifier | | userEmail | string | No | User email address | | planId | string | No | Selected plan | | planName | string | No | Plan display name | ## When to Fire * After signup form submission succeeds * After email verification completes * After OAuth signup flow finishes # signup_started Event Source: https://docs.upstackdata.com/pixel/saas-events/signup-started Track when a user begins the signup flow in your SaaS application. Fires when a user begins the signup flow. Use this event to measure signup funnel drop-off and optimize conversion. ## JavaScript ```javascript theme={null} window._upstack('track', 'signup_started', { planId: 'plan_pro_monthly', source: 'pricing_page' }); ``` ## Properties | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------------- | | planId | string | No | Pre-selected plan (if applicable) | | source | string | No | Where signup was initiated | ## When to Fire * When signup form is opened * When registration page loads * When "Start Free Trial" button is clicked # subscription_cancelled Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-cancelled Track when a cancellation is requested (may still be active until period end). Fires when a cancellation is requested (may still be active until period end). Use this event to trigger win-back campaigns and measure cancellation reasons. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_cancelled', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', cancelReason: 'too_expensive', cancelFeedback: 'Budget constraints this quarter', mrr: 9900, cancelAtPeriodEnd: true }); ``` ## Properties | Property | Type | Required | Description | | ----------------- | ------- | -------- | ----------------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Cancelled plan | | cancelReason | string | No | Cancellation reason code | | cancelFeedback | string | No | User-provided feedback | | mrr | number | No | MRR being cancelled in cents | | cancelAtPeriodEnd | boolean | No | If true, cancels at end of billing period | ## When to Fire * When customer clicks cancel button * When cancellation request is submitted * When Stripe subscription is set to cancel at period end # subscription_churned Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-churned Track when a subscription ends completely (no longer billing). Fires when a subscription ends completely (no longer billing). This is the final churn event for calculating churn rate. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_churned', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', cancelReason: 'switched_competitor', mrr: 9900, ltv: 118800, subscriptionMonths: 12 }); ``` ## Properties | Property | Type | Required | Description | | ------------------ | ------ | -------- | -------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Churned plan | | cancelReason | string | No | Churn reason | | mrr | number | No | Lost MRR in cents | | ltv | number | No | Customer lifetime value in cents | | subscriptionMonths | number | No | How long they were subscribed | ## When to Fire * When final billing period ends * When subscription is deactivated * When Stripe `customer.subscription.deleted` fires ## Stripe Webhook Maps to `customer.subscription.deleted`. <Warning> Use this event to calculate churn rate and analyze churn reasons. Track `ltv` to understand which customer segments have the highest lifetime value. </Warning> # subscription_created Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-created Track when a subscription record is created in your billing system. Fires when a subscription record is created in your billing system. This may precede first payment for trials. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_created', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', billingInterval: 'month' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | --------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | Yes | Plan identifier | | planName | string | No | Plan display name | | billingInterval | string | No | `day`, `week`, `month`, or `year` | ## When to Fire * When subscription object is created in Stripe * May precede first payment (for trials) * After checkout session completes ## Stripe Webhook Maps to `customer.subscription.created`. # subscription_downgraded Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-downgraded Track when a customer downgrades to a lower-tier plan. Fires when a customer downgrades to a lower-tier plan. Use this event to identify at-risk accounts and measure contraction. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_downgraded', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_starter_monthly', planName: 'Starter', previousPlanId: 'plan_pro_monthly', mrr: 4900, mrrDelta: -5000 }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | New plan identifier | | planName | string | No | New plan name | | previousPlanId | string | No | Previous plan identifier | | mrr | number | No | New MRR after downgrade in cents | | mrrDelta | number | No | MRR decrease in cents (negative) | ## When to Fire * When plan changes from higher to lower tier * When features are removed from subscription * When scheduled downgrade takes effect at period end ## Stripe Webhook Maps to `customer.subscription.updated` when the new price is lower than the previous price. # subscription_initial_purchase Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-initial-purchase Track when a customer's first subscription payment is processed. Fires when a customer's first subscription payment is processed (distinct from trial conversion). Use this event for acquisition revenue metrics. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_initial_purchase', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', value: 9900, currency: 'USD', billingInterval: 'month' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ----------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Plan identifier | | planName | string | No | Plan display name | | value | number | No | Payment amount in cents | | currency | string | No | ISO 4217 currency code | | billingInterval | string | No | `month` or `year` | ## When to Fire * First subscription charge succeeds * After trial converts (first paid billing period) * When new customer's initial payment processes <Tip> Use `subscription_initial_purchase` for acquisition metrics and `subscription_recurring_purchase` for retention/LTV analysis. Together they give a complete picture of subscription revenue. </Tip> # subscription_paused Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-paused Track when a subscription is paused. Fires when a subscription is paused. Use this event to measure pause rates and understand seasonal patterns. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_paused', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', mrr: 9900, pauseReason: 'seasonal_business' }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | --------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Plan identifier | | mrr | number | No | Paused MRR in cents | | pauseReason | string | No | Why subscription was paused | ## When to Fire * When customer requests pause * When seasonal pause is activated * When Stripe subscription pause feature triggers ## Stripe Webhook Maps to `customer.subscription.paused`. # subscription_reactivated Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-reactivated Track when a previously churned customer resubscribes. Fires when a previously churned customer resubscribes. Use this event to measure win-back campaign effectiveness and recovered MRR. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_reactivated', { subscriptionId: 'sub_ghi789', accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', mrr: 9900, daysSinceChurn: 45 }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | ----------------------------------- | | subscriptionId | string | Yes | New subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | New plan identifier | | planName | string | No | Plan display name | | mrr | number | No | Recovered MRR in cents | | daysSinceChurn | number | No | Days between churn and reactivation | ## When to Fire * When former customer signs up again * When win-back campaign converts * When churned account starts new subscription # subscription_recurring_purchase Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-recurring-purchase Track when a recurring subscription payment is processed (not the initial purchase). Fires when a recurring subscription payment is processed (not the initial purchase). Use this event for retention and LTV analysis. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_recurring_purchase', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', value: 9900, currency: 'USD', billingInterval: 'month', renewalNumber: 6 }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | -------------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Plan identifier | | planName | string | No | Plan display name | | value | number | No | Payment amount in cents | | currency | string | No | ISO 4217 currency code | | billingInterval | string | No | `month` or `year` | | renewalNumber | number | No | Which renewal this is (2nd, 3rd, etc.) | ## When to Fire * Each recurring billing cycle * When Stripe `invoice.paid` fires for an existing subscription * Monthly/annual renewal charge succeeds ## Stripe Webhook Maps to `invoice.paid` for existing subscriptions (not the first invoice). # subscription_resumed Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-resumed Track when a paused subscription is resumed. Fires when a paused subscription is resumed. Use this event to measure pause-to-resume rates and recovered MRR. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_resumed', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', mrr: 9900, pausedDays: 30 }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | Plan identifier | | mrr | number | No | Resumed MRR in cents | | pausedDays | number | No | How long subscription was paused | ## When to Fire * When customer manually resumes * When pause period ends automatically * When billing restarts ## Stripe Webhook Maps to `customer.subscription.resumed`. # subscription_started Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-started Track when a new subscription begins (first billing period starts). Fires when a new subscription begins (first billing period starts). This marks the start of paid service. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_started', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', mrr: 9900, billingInterval: 'month' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ---------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | Yes | Plan identifier | | planName | string | No | Plan display name | | mrr | number | No | Monthly recurring revenue in cents | | billingInterval | string | No | Billing frequency | ## When to Fire * After first successful charge * When subscription status becomes `active` * After trial converts to paid # subscription_upgraded Event Source: https://docs.upstackdata.com/pixel/saas-events/subscription-upgraded Track when a customer upgrades to a higher-tier plan. Fires when a customer upgrades to a higher-tier plan. Use this event to measure expansion revenue and upsell success. ## JavaScript ```javascript theme={null} window._upstack('track', 'subscription_upgraded', { subscriptionId: 'sub_def456', accountId: 'acct_abc123', planId: 'plan_business_monthly', planName: 'Business', previousPlanId: 'plan_pro_monthly', mrr: 19900, mrrDelta: 10000 }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------- | | subscriptionId | string | Yes | Subscription identifier | | accountId | string | Yes | Account identifier | | planId | string | No | New plan identifier | | planName | string | No | New plan name | | previousPlanId | string | No | Previous plan identifier | | mrr | number | No | New MRR after upgrade in cents | | mrrDelta | number | No | MRR increase in cents (positive) | ## When to Fire * When plan changes from lower to higher tier * When Stripe subscription item is updated with higher-priced plan * After upgrade checkout completes ## Stripe Webhook Maps to `customer.subscription.updated` when the new price is higher than the previous price. <Tip> Track `mrrDelta` alongside `subscription_downgraded` to calculate net revenue retention. </Tip> # trial_activated Event Source: https://docs.upstackdata.com/pixel/saas-events/trial-activated Track when a trial user reaches a meaningful activation milestone. Fires when a trial user reaches a meaningful activation milestone. Use this event to measure trial engagement and predict conversion likelihood. ## JavaScript ```javascript theme={null} window._upstack('track', 'trial_activated', { accountId: 'acct_abc123', planId: 'plan_pro_monthly', trialDaysRemaining: 12, activationMilestone: 'first_integration_connected' }); ``` ## Properties | Property | Type | Required | Description | | ------------------- | ------ | -------- | --------------------------- | | accountId | string | Yes | Account identifier | | planId | string | No | Trial plan identifier | | trialDaysRemaining | number | No | Days remaining in trial | | activationMilestone | string | No | Which milestone was reached | ## When to Fire * After first key feature is used * After onboarding checklist is completed * After first data import succeeds # trial_converted Event Source: https://docs.upstackdata.com/pixel/saas-events/trial-converted Track when a trial converts to a paid subscription. Fires when a trial converts to a paid subscription. This is a key conversion event for measuring trial success. ## JavaScript ```javascript theme={null} window._upstack('track', 'trial_converted', { accountId: 'acct_abc123', subscriptionId: 'sub_def456', planId: 'plan_pro_monthly', planName: 'Pro Plan', mrr: 9900, billingInterval: 'month' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ---------------------------------- | | accountId | string | Yes | Account identifier | | subscriptionId | string | Yes | New subscription ID | | planId | string | Yes | Converted plan identifier | | planName | string | No | Plan display name | | mrr | number | No | Monthly recurring revenue in cents | | billingInterval | string | No | `month` or `year` | ## When to Fire * After first successful payment * When Stripe subscription status changes from `trialing` to `active` * After payment method is charged successfully <Tip> Track `mrr` to measure trial-to-paid conversion value and calculate average revenue per converted trial. </Tip> # trial_ending_soon Event Source: https://docs.upstackdata.com/pixel/saas-events/trial-ending-soon Track when a trial is about to expire (typically 3 days before). Fires when a trial is about to expire (typically 3 days before). Use this event to trigger conversion campaigns and win-back flows. ## JavaScript ```javascript theme={null} window._upstack('track', 'trial_ending_soon', { accountId: 'acct_abc123', trialDaysRemaining: 3, planId: 'plan_pro_monthly', trialEndDate: '2026-03-04T14:30:00.000Z' }); ``` ## Properties | Property | Type | Required | Description | | ------------------ | ------ | -------- | --------------------- | | accountId | string | Yes | Account identifier | | trialDaysRemaining | number | Yes | Days until expiry | | planId | string | No | Trial plan identifier | | trialEndDate | string | No | Trial expiration date | ## When to Fire * 3 days before trial expires (common) * When Stripe sends `customer.subscription.trial_will_end` * When automated warning email triggers ## Stripe Webhook Maps to `customer.subscription.trial_will_end`. # trial_expired Event Source: https://docs.upstackdata.com/pixel/saas-events/trial-expired Track when a trial ends without conversion. Fires when a trial ends without conversion. Use this event to measure trial-to-paid conversion rates and identify drop-off reasons. ## JavaScript ```javascript theme={null} window._upstack('track', 'trial_expired', { accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', trialDays: 14 }); ``` ## Properties | Property | Type | Required | Description | | --------- | ------ | -------- | ------------------ | | accountId | string | Yes | Account identifier | | planId | string | No | Expired trial plan | | planName | string | No | Plan display name | | trialDays | number | No | Total trial length | ## When to Fire * When trial end date is reached without payment * When account is downgraded to free tier * When access is revoked after grace period # trial_extended Event Source: https://docs.upstackdata.com/pixel/saas-events/trial-extended Track when a trial period is extended. Fires when a trial period is extended. Use this event to track trial extensions and measure their impact on conversion. ## JavaScript ```javascript theme={null} window._upstack('track', 'trial_extended', { accountId: 'acct_abc123', trialEndDate: '2026-03-11T14:30:00.000Z', trialDaysRemaining: 7, extensionReason: 'support_request' }); ``` ## Properties | Property | Type | Required | Description | | ------------------ | ------ | -------- | ---------------------- | | accountId | string | Yes | Account identifier | | trialEndDate | string | No | New trial end date | | trialDaysRemaining | number | No | New days remaining | | extensionReason | string | No | Why trial was extended | ## When to Fire * After support manually extends trial * After promotional extension is applied * After win-back campaign grants extension # trial_started Event Source: https://docs.upstackdata.com/pixel/saas-events/trial-started Track when a user begins a free trial in your SaaS application. Fires when a user begins a free trial. This is the start of your trial-to-paid conversion funnel. ## JavaScript ```javascript theme={null} window._upstack('track', 'trial_started', { accountId: 'acct_abc123', planId: 'plan_pro_monthly', planName: 'Pro Plan', trialEndDate: '2026-03-04T14:30:00.000Z', trialDaysRemaining: 14 }); ``` ## Properties | Property | Type | Required | Description | | ------------------ | ------ | -------- | ------------------------------ | | accountId | string | Yes | Account identifier | | planId | string | Yes | Trial plan identifier | | planName | string | No | Human-readable plan name | | trialEndDate | string | No | ISO 8601 trial expiration date | | trialDaysRemaining | number | No | Days until trial expires | ## When to Fire * After trial signup confirmation * After trial activation in billing system * After Stripe `customer.subscription.created` with trial ## Stripe Webhook Maps to `customer.subscription.created` when the subscription has a trial period. # user_activated Event Source: https://docs.upstackdata.com/pixel/saas-events/user-activated Track when a user reaches an activation milestone within the product. Fires when a user reaches an activation milestone within the product. Use this event to measure user onboarding success and product adoption. ## JavaScript ```javascript theme={null} window._upstack('track', 'user_activated', { userId: 'usr_xyz789', accountId: 'acct_abc123', userEmail: 'user@acme.com', activationMilestone: 'completed_onboarding', daysToActivation: 2 }); ``` ## Properties | Property | Type | Required | Description | | ------------------- | ------ | -------- | ------------------------------ | | userId | string | Yes | User identifier | | accountId | string | Yes | Account identifier | | userEmail | string | No | User email address | | activationMilestone | string | No | Which milestone was reached | | daysToActivation | number | No | Days from signup to activation | ## When to Fire * When user completes onboarding checklist * When user performs first key action * When user reaches engagement threshold # user_inactive Event Source: https://docs.upstackdata.com/pixel/saas-events/user-inactive Track when a user becomes inactive after a period of no engagement. Fires when a user becomes inactive after a period of no engagement. Use this event to trigger re-engagement campaigns and identify at-risk accounts. ## JavaScript ```javascript theme={null} window._upstack('track', 'user_inactive', { userId: 'usr_xyz789', accountId: 'acct_abc123', userEmail: 'user@acme.com', lastActiveDate: '2026-01-15T10:30:00.000Z', inactiveDays: 30 }); ``` ## Properties | Property | Type | Required | Description | | -------------- | ------ | -------- | --------------------------- | | userId | string | Yes | User identifier | | accountId | string | Yes | Account identifier | | userEmail | string | No | User email address | | lastActiveDate | string | No | ISO 8601 last activity date | | inactiveDays | number | No | Days since last activity | ## When to Fire * When user hasn't logged in for defined period (e.g., 30 days) * When automated inactivity check triggers * When engagement score drops below threshold # user_invited Event Source: https://docs.upstackdata.com/pixel/saas-events/user-invited Track when a user is invited to join an account. Fires when a user is invited to join an account. Use this event to measure team growth and invitation conversion rates. ## JavaScript ```javascript theme={null} window._upstack('track', 'user_invited', { accountId: 'acct_abc123', inviteeEmail: 'newmember@acme.com', inviteeRole: 'member', invitedByUserId: 'usr_xyz789' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | --------------------- | | accountId | string | Yes | Account identifier | | inviteeEmail | string | No | Invitee email address | | inviteeRole | string | No | Assigned role | | invitedByUserId | string | No | Inviter's user ID | ## When to Fire * When team invite is sent * When collaboration request is initiated * After invite email is dispatched # user_joined Event Source: https://docs.upstackdata.com/pixel/saas-events/user-joined Track when an invited user accepts and joins the account. Fires when an invited user accepts and joins the account. Use this event to measure invite-to-join conversion rates. ## JavaScript ```javascript theme={null} window._upstack('track', 'user_joined', { userId: 'usr_newmember', accountId: 'acct_abc123', userEmail: 'newmember@acme.com', userRole: 'member' }); ``` ## Properties | Property | Type | Required | Description | | --------- | ------ | -------- | -------------------- | | userId | string | Yes | New user identifier | | accountId | string | Yes | Account identifier | | userEmail | string | No | User email address | | userRole | string | No | User's assigned role | ## When to Fire * When invite is accepted * When account access is granted * After user completes join flow # user_removed Event Source: https://docs.upstackdata.com/pixel/saas-events/user-removed Track when a user is removed from an account. Fires when a user is removed from an account. Use this event to track team changes and understand user churn at the account level. ## JavaScript ```javascript theme={null} window._upstack('track', 'user_removed', { userId: 'usr_xyz789', accountId: 'acct_abc123', userEmail: 'removed@acme.com', removedByUserId: 'usr_admin123', removalReason: 'left_company' }); ``` ## Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | -------------------------------------------------------------------------- | | userId | string | Yes | Removed user identifier | | accountId | string | Yes | Account identifier | | userEmail | string | No | Removed user's email address | | removedByUserId | string | No | Admin who removed the user | | removalReason | string | No | Reason for removal (`left_company`, `role_change`, `security`, `inactive`) | ## When to Fire * When admin removes user from team * When user access is revoked * When user is deactivated from account # webinar_registered Event Source: https://docs.upstackdata.com/pixel/saas-events/webinar-registered Track when a user registers for a webinar or virtual event. Fires when a user registers for a webinar or virtual event. Use this event to measure event marketing performance and track registrant-to-attendee conversion. ## JavaScript ```javascript theme={null} window._upstack('track', 'webinar_registered', { webinarId: 'web_product_demo_2024', webinarTitle: 'Product Demo: Advanced Analytics Features', webinarDate: '2026-03-15T14:00:00.000Z', userEmail: 'attendee@company.com', companyName: 'Attendee Corp', source: 'email_campaign' }); ``` ## Properties | Property | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------ | | webinarId | string | Yes | Unique webinar identifier | | webinarTitle | string | No | Human-readable webinar title | | webinarDate | string | No | ISO 8601 scheduled date | | userEmail | string | No | Registrant's email address | | companyName | string | No | User's company name | | source | string | No | Where the registration was initiated | ## When to Fire * After webinar registration form submission * After calendar invite is sent * After registration confirmation email is delivered # How to Install the Upstack Data Tracking Pixel Source: https://docs.upstackdata.com/pixel/setup Install the Upstack Data pixel on any website in 5 minutes. Covers installation, verification, common tracking patterns, and identity capture. Get the Upstack pixel running on your site in under 5 minutes. This guide covers non-Shopify installations — if you're on Shopify, use the [Shopify app installation guide](/guides/shopify/how-to-download-and-install-upstack-data-app-in-shopify) instead. ## Installation Add this code snippet to every page you want to track, just before the closing `</head>` tag: ```html theme={null} <script> window._upstack = window._upstack || function() { (window._upsqueue = window._upsqueue || []).push(arguments); }; _upstack('init', 'YOUR_PIXEL_ID'); </script> <script async src="https://prod2-cdn.upstackified.com/scripts/px/ups.min.js"></script> ``` <Warning> Replace `YOUR_PIXEL_ID` with your actual pixel ID from the [Upstack dashboard](https://app.upstackdata.com). Your pixel ID starts with `px_`. </Warning> ### Where to Find Your Pixel ID 1. Log in to [app.upstackdata.com](https://app.upstackdata.com) 2. Navigate to **Settings** → **Pixel** 3. Copy your pixel ID (format: `px_abc123def456`) *** ## Where to Place the Code ### Standard Websites Place the snippet in your site's `<head>` section on every page: ```html theme={null} <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>My Store ``` ### Single Page Applications (SPAs) For React, Vue, Next.js, or other SPAs: 1. **Add the snippet once** in your main `index.html` or root layout 2. **Track route changes** manually (page views don't fire automatically on navigation) ```javascript theme={null} // React Router example import { useEffect } from 'react'; import { useLocation } from 'react-router-dom'; function usePageTracking() { const location = useLocation(); useEffect(() => { window._upstack('page'); }, [location.pathname]); } ``` ```javascript theme={null} // Next.js App Router example 'use client'; import { usePathname } from 'next/navigation'; import { useEffect } from 'react'; export function Analytics() { const pathname = usePathname(); useEffect(() => { window._upstack('page'); }, [pathname]); return null; } ``` ### Google Tag Manager If you prefer GTM, create a **Custom HTML** tag: 1. Create a new tag with type **Custom HTML** 2. Paste the installation snippet 3. Set trigger to **All Pages** (or your preferred trigger) 4. Publish the container *** ## Verifying Installation ### Browser Console Check Open your browser's developer console (F12) and run: ```javascript theme={null} // Check if pixel is loaded typeof window._upstack === 'function' // Should return: true // Check initialization status window._upsClient?._initialized // Should return: true (after init completes) // Check if queue exists Array.isArray(window._upsqueue) // Should return: true ``` ### Test a Page View Manually fire a page view and check the Network tab: ```javascript theme={null} window._upstack('page'); ``` Look for a request to `upstackified.com` or `upstackdata.com` in the Network tab. ### Pixel Helper Extension Install the [Upstack Pixel Helper](/guides/shopify/how-to-install-upstack-data-pixel-helper) Chrome extension for real-time event monitoring without using the console. *** ## Quick Start: Common Tracking Patterns ### Track a Page View ```javascript theme={null} // Basic page view (auto-captures URL, title, referrer) window._upstack('page'); // With custom properties window._upstack('page', { page_category: 'product', collection: 'summer-2026' }); ``` ### Track a Product View ```javascript theme={null} window._upstack('track', 'view_content', { content_ids: ['PRODUCT_123'], content_name: 'Blue Running Shoes', content_type: 'product', value: 89.99, currency: 'USD' }); ``` ### Track Add to Cart ```javascript theme={null} window._upstack('track', 'add_to_cart', { content_ids: ['PRODUCT_123'], content_name: 'Blue Running Shoes', content_type: 'product', value: 89.99, currency: 'USD', num_items: 1 }); ``` ### Track a Purchase ```javascript theme={null} window._upstack('track', 'purchase', { content_ids: ['PRODUCT_123', 'PRODUCT_456'], value: 149.99, currency: 'USD', order_id: 'ORDER_789', num_items: 2 }); ``` Always include `order_id` for purchase events — it's used for deduplication across browser and server events. *** ## Identifying Users User identification improves match quality with ad platforms and enables cross-device tracking. ### Basic Identification ```javascript theme={null} // Identify with email only (most common) window._upstack('identify', null, { emails: ['customer@example.com'] }); // Identify with phone window._upstack('identify', null, { phones: ['+15551234567'] }); // Full identification window._upstack('identify', 'user_123', { emails: ['customer@example.com'], phones: ['+15551234567'], firstName: 'Jane', lastName: 'Doe' }); ``` **Important:** `emails` and `phones` are **arrays**, not single strings. This supports users with multiple contact methods. ### When to Identify Call `identify()` when you capture user information: * Newsletter signup form submission * Account registration * Checkout (when email is entered) * Login ```javascript theme={null} // Example: Newsletter form document.querySelector('#newsletter-form').addEventListener('submit', (e) => { const email = e.target.querySelector('[name="email"]').value; window._upstack('identify', null, { emails: [email] }); }); ``` *** ## Complete E-commerce Example Here's a full example tracking the customer journey: ```javascript theme={null} // 1. Page view (on every page load) window._upstack('page'); // 2. Product view (on product page) window._upstack('track', 'view_content', { content_ids: ['SKU-001'], content_name: 'Premium Widget', content_type: 'product', value: 49.99, currency: 'USD' }); // 3. Add to cart (on button click) document.querySelector('.add-to-cart').addEventListener('click', () => { window._upstack('track', 'add_to_cart', { content_ids: ['SKU-001'], content_name: 'Premium Widget', content_type: 'product', value: 49.99, currency: 'USD', num_items: 1 }); }); // 4. Begin checkout (on checkout page) window._upstack('track', 'initiate_checkout', { content_ids: ['SKU-001'], value: 49.99, currency: 'USD', num_items: 1 }); // 5. Identify user (when email captured at checkout) window._upstack('identify', null, { emails: ['customer@example.com'] }); // 6. Purchase (on thank-you page) window._upstack('track', 'purchase', { content_ids: ['SKU-001'], value: 49.99, currency: 'USD', order_id: 'ORD-12345', num_items: 1 }); ``` *** ## Troubleshooting ### Pixel Not Firing Open Network tab in DevTools and look for `ups.min.js`. If it's not loading: * Verify the script URL is correct * Check for ad blockers or privacy extensions * Ensure the snippet is in the ``, not blocked by CSP Run in console: ```javascript theme={null} console.log('_upstack exists:', typeof window._upstack === 'function'); console.log('_upsClient exists:', typeof window._upsClient === 'object'); console.log('Initialized:', window._upsClient?._initialized); ``` All should return `true` after the page loads. Ensure your pixel ID: * Starts with `px_` * Matches exactly what's in your dashboard * Has no extra spaces or characters Look for errors in the Console tab. Common issues: * Calling `_upstack` before defining the queue function * Syntax errors in your tracking code * Conflicts with other scripts ### Events Not Appearing in Dashboard Events can take 1-5 minutes to appear in the dashboard. Check the **Live Events** view for real-time data. Look for outgoing requests after firing an event. You should see a POST request to the tracking endpoint. Use standard event names like `page_view`, `view_content`, `add_to_cart`, `purchase`. Custom event names work but may not map to standard destination events. The pixel automatically filters bot traffic. If you're testing with automated tools, events may be ignored. ### Common Mistakes | Issue | Solution | | ----------------------------------------- | -------------------------------------------------------------- | | Using `upstack()` instead of `_upstack()` | The correct global is `window._upstack()` with underscore | | Passing `email` instead of `emails: []` | Identity fields use arrays: `{ emails: ['user@example.com'] }` | | Missing `currency` on purchase events | Always include `currency: 'USD'` (or your currency code) | | Missing `order_id` on purchases | Include for deduplication across browser/server events | | Not tracking SPA navigation | Call `_upstack('page')` on route changes | *** ## Related Documentation Full API documentation for all methods and options. Reference for all standard event types and their properties. Complete reference for item arrays, customer data, and auto-captured fields. How user identification enables cross-device tracking. Create events beyond the standard taxonomy for your needs. Send events to Meta, Google, TikTok, Klaviyo, and more. # Upstack Data Standard Events Reference Source: https://docs.upstackdata.com/pixel/standard-events Copy-paste JavaScript snippets for every Upstack Data standard event — page_view, add_to_cart, purchase, lead, and 15+ more with full property specs. Standard events are predefined event types that Upstack recognizes across all destinations. Use these events to track customer behavior and attribute conversions. **This guide applies to all Upstack implementations** — Shopify, headless, GTM, or custom websites. The JavaScript snippets below work everywhere the Upstack pixel is installed. **Shopify stores:** Most events are tracked automatically by the Upstack Pixel. See [Automatic Shopify Tracking](/sources/shopify-automatic-tracking) to understand what's already tracked. Use these snippets for custom implementations, headless checkouts, or events not covered by automatic tracking. *** ## page\_view Fires when a visitor loads a page. ### JavaScript ```javascript theme={null} window._upstack('page'); ``` With custom properties: ```javascript theme={null} window._upstack('page', { pageCategory: 'product', collectionHandle: 'summer-2026' }); ``` ### Properties | Property | Type | Required | Description | | ---------------- | ------ | -------- | ------------------------------------------------------- | | pageCategory | string | No | Page type (e.g., `'product'`, `'collection'`, `'blog'`) | | collectionHandle | string | No | Collection identifier for collection pages | ### Auto-Captured The SDK automatically captures `page_url`, `page_title`, `page_referrer`, and `page_path`. ### When to Fire * On initial page load * On SPA route changes * After dynamic content loads (infinite scroll) *** ## view\_content Fires when a visitor views a product or content page. **Shopify:** Automatically tracked when viewing product detail pages. ### JavaScript ```javascript theme={null} window._upstack('track', 'view_content', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, brand: 'Example Brand', category: 'Apparel/T-Shirts' } ], value: 34.99, currency: 'USD' }); ``` Minimal example: ```javascript theme={null} window._upstack('track', 'view_content', { items: [{ id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99 }], value: 34.99, currency: 'USD' }); ``` ### Properties | Property | Type | Required | Description | | -------- | ------ | -------- | ------------------------------------------------- | | items | array | Yes | Products viewed (see [Item Object](#item-object)) | | value | number | Yes | Product price | | currency | string | Yes | ISO 4217 currency code (e.g., `'USD'`) | ### When to Fire * Product detail page load * Quick view modal open * Collection page load (with collection products) *** ## view\_category Fires when a visitor views a collection or category page. **Shopify:** Automatically tracked when viewing collection pages. ### JavaScript ```javascript theme={null} window._upstack('track', 'view_category', { items: [ { id: 'SKU_001', name: 'Classic Cotton Tee', price: 34.99 }, { id: 'SKU_002', name: 'Vintage Logo Hoodie', price: 59.99 }, { id: 'SKU_003', name: 'Slim Fit Jeans', price: 79.99 } ], itemListId: 'summer_collection', itemListName: 'Summer 2026 Collection' }); ``` Minimal example: ```javascript theme={null} window._upstack('track', 'view_category', { itemListId: 'mens_shirts', itemListName: 'Men\'s Shirts' }); ``` ### Properties | Property | Type | Required | Description | | ------------ | ------ | -------- | ---------------------------------------------------------------- | | itemListId | string | No | Collection/category identifier | | itemListName | string | No | Collection/category display name | | items | array | No | Products shown in the category (see [Item Object](#item-object)) | ### When to Fire * Collection page load * Category filter applied * Browse by category navigation *** ## view\_item\_list Fires when a visitor views a list of products (similar to `view_category` but more general). ### JavaScript ```javascript theme={null} window._upstack('track', 'view_item_list', { items: [ { id: 'SKU_001', name: 'Classic Cotton Tee', price: 34.99, index: 0 }, { id: 'SKU_002', name: 'Vintage Logo Hoodie', price: 59.99, index: 1 } ], itemListId: 'recommended_products', itemListName: 'Recommended For You' }); ``` ### Properties | Property | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------------------------ | | itemListId | string | No | List identifier | | itemListName | string | No | List display name | | items | array | No | Products in the list (include `index` for position tracking) | ### When to Fire * Product recommendation carousel load * "Related Products" section view * "Recently Viewed" section view * Search results page load *** ## add\_to\_cart Fires when a visitor adds an item to their cart. ### JavaScript ```javascript theme={null} window._upstack('track', 'add_to_cart', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2, variant: 'Blue / Medium', brand: 'Example Brand', category: 'Apparel/T-Shirts' } ], value: 69.98, currency: 'USD' }); ``` Minimal example: ```javascript theme={null} window._upstack('track', 'add_to_cart', { items: [{ id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 1 }], value: 34.99, currency: 'USD' }); ``` ### Properties | Property | Type | Required | Description | | -------- | ------ | -------- | ------------------------------------------------ | | items | array | Yes | Products added (see [Item Object](#item-object)) | | value | number | Yes | Total value of items added | | currency | string | Yes | ISO 4217 currency code | ### When to Fire * Add-to-cart button click * Quantity increase in cart * "Buy Now" button click (before checkout) *** ## product\_removed\_from\_cart Fires when a visitor removes an item from their cart. ### JavaScript ```javascript theme={null} window._upstack('track', 'product_removed_from_cart', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 1 } ], value: 34.99, currency: 'USD' }); ``` ### Properties | Property | Type | Required | Description | | -------- | ------ | -------- | -------------------------------------------------- | | items | array | Yes | Products removed (see [Item Object](#item-object)) | | value | number | No | Value of removed items | | currency | string | No | ISO 4217 currency code | ### When to Fire * Remove button click * Quantity decrease to zero * Clear cart action *** ## view\_cart Fires when a visitor views their shopping cart. ### JavaScript ```javascript theme={null} window._upstack('track', 'view_cart', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2 }, { id: 'SKU_67890', name: 'Running Socks', price: 14.99, quantity: 1 } ], value: 84.97, currency: 'USD' }); ``` ### Properties | Property | Type | Required | Description | | -------- | ------ | -------- | -------------------------------------------------- | | items | array | Yes | Products in cart (see [Item Object](#item-object)) | | value | number | No | Total cart value | | currency | string | No | ISO 4217 currency code | ### When to Fire * Cart page load * Cart drawer/sidebar open * Mini-cart expansion *** ## initiate\_checkout Fires when a visitor starts the checkout process. ### JavaScript ```javascript theme={null} window._upstack('track', 'initiate_checkout', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2 }, { id: 'SKU_67890', name: 'Running Socks', price: 14.99, quantity: 1 } ], value: 84.97, currency: 'USD' }); ``` ### Properties | Property | Type | Required | Description | | -------- | ------ | -------- | ---------------------- | | items | array | Yes | Products in checkout | | value | number | Yes | Cart subtotal | | currency | string | Yes | ISO 4217 currency code | ### When to Fire * Checkout button click * Checkout page load * Express checkout initiation (Shop Pay, Apple Pay) *** ## add\_shipping\_info Fires when a customer enters shipping details during checkout. ### JavaScript ```javascript theme={null} window._upstack('track', 'add_shipping_info', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2 } ], value: 84.97, currency: 'USD', shippingTier: 'standard' }); ``` ### Properties | Property | Type | Required | Description | | ------------ | ------ | -------- | ---------------------------------------------------------------- | | items | array | No | Products in checkout | | value | number | No | Cart value at shipping step | | currency | string | No | ISO 4217 currency code | | shippingTier | string | No | Shipping method (e.g., `'standard'`, `'express'`, `'overnight'`) | ### When to Fire * Shipping form completion * Shipping method selection * Proceeding past shipping step *** ## select\_shipping\_method Fires when a customer selects a shipping method during checkout. ### JavaScript ```javascript theme={null} window._upstack('track', 'select_shipping_method', { shippingTier: 'express', shippingPrice: 12.99, currency: 'USD', value: 97.98 }); ``` With items: ```javascript theme={null} window._upstack('track', 'select_shipping_method', { shippingTier: 'overnight', shippingPrice: 24.99, currency: 'USD', value: 109.98, items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2 } ] }); ``` ### Properties | Property | Type | Required | Description | | ------------- | ------ | -------- | ------------------------------------------------------------------------- | | shippingTier | string | Yes | Shipping method selected (e.g., `'standard'`, `'express'`, `'overnight'`) | | shippingPrice | number | No | Shipping cost | | value | number | No | Cart value at shipping selection | | currency | string | No | ISO 4217 currency code | | items | array | No | Products in checkout | ### When to Fire * Shipping method radio button selection * Shipping tier dropdown change * Before proceeding to payment *** ## add\_payment\_info Fires when a customer enters payment details during checkout. ### JavaScript ```javascript theme={null} window._upstack('track', 'add_payment_info', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, quantity: 2 } ], value: 84.97, currency: 'USD', paymentType: 'credit_card' }); ``` ### Properties | Property | Type | Required | Description | | ----------- | ------ | -------- | ---------------------------------------------------------------- | | items | array | No | Products in checkout | | value | number | No | Cart value at payment step | | currency | string | No | ISO 4217 currency code | | paymentType | string | No | Payment method (e.g., `'credit_card'`, `'paypal'`, `'shop_pay'`) | ### When to Fire * Payment form completion * Payment method selection * Before final order submission *** ## purchase Fires when an order is completed. ### JavaScript ```javascript theme={null} window._upstack('track', 'purchase', { orderId: 'ORD_12345', value: 149.99, currency: 'USD', tax: 12.50, shipping: 5.99, items: [ { id: 'SKU_001', name: 'Blue Running Shoes', price: 89.99, quantity: 1, brand: 'Nike', category: 'Shoes/Running' }, { id: 'SKU_002', name: 'Running Socks', price: 14.99, quantity: 2, brand: 'Nike', category: 'Accessories/Socks' } ], email: 'customer@example.com' }, 'ORD_12345'); ``` The third parameter (`'ORD_12345'`) is a deduplication ID. It prevents duplicate purchase events from being sent to destinations if the event fires multiple times. Minimal example: ```javascript theme={null} window._upstack('track', 'purchase', { orderId: 'ORD_12345', value: 149.99, currency: 'USD', items: [{ id: 'SKU_001', name: 'Blue Running Shoes', price: 89.99, quantity: 1 }] }, 'ORD_12345'); ``` ### Properties | Property | Type | Required | Description | | -------- | ------ | -------- | ---------------------------------------------------- | | orderId | string | Yes | Unique order identifier | | value | number | Yes | Total order value | | currency | string | Yes | ISO 4217 currency code | | items | array | Yes | Products purchased (see [Item Object](#item-object)) | | tax | number | No | Tax amount | | shipping | number | No | Shipping cost | | email | string | No | Customer email (improves identity matching) | **Important:** The `value` property should match what you want reported to ad platforms. Discrepancies between Shopify order totals and reported CAPI revenue are the most common attribution debugging issue. ### When to Fire * Order confirmation page load * After successful payment confirmation * Shopify `orders/create` webhook (server-side) *** ## search Fires when a visitor performs a search. ### JavaScript ```javascript theme={null} window._upstack('track', 'search', { searchTerm: 'blue running shoes', resultsCount: 24 }); ``` With search results: ```javascript theme={null} window._upstack('track', 'search', { searchTerm: 'blue running shoes', resultsCount: 24, items: [ { id: 'SKU_001', name: 'Blue Running Shoes', price: 89.99 }, { id: 'SKU_002', name: 'Navy Training Shoes', price: 79.99 } ] }); ``` ### Properties | Property | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------ | | searchTerm | string | Yes | The search query entered | | resultsCount | number | No | Number of results returned | | items | array | No | Top products in search results | ### When to Fire * Search results page load * Predictive search dropdown display * "No results" page (with `resultsCount: 0`) *** ## lead Fires when a visitor submits a lead form. ### JavaScript ```javascript theme={null} window._upstack('track', 'lead', { source: 'contact_form', email: 'prospect@example.com', value: 150.00, currency: 'USD' }); ``` Newsletter signup: ```javascript theme={null} window._upstack('track', 'lead', { source: 'newsletter_popup', email: 'subscriber@example.com' }); ``` ### Properties | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------- | | source | string | No | Form or campaign identifier | | email | string | No | Lead's email address | | value | number | No | Estimated lead value | | currency | string | No | ISO 4217 currency code | ### When to Fire * Contact form submission * Newsletter signup * Quote request submission * Product inquiry *** ## complete\_registration Fires when a customer creates an account. ### JavaScript ```javascript theme={null} window._upstack('track', 'complete_registration', { method: 'email', source: 'checkout_page' }); ``` ### Properties | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------------------------------------------- | | method | string | No | Registration method (e.g., `'email'`, `'google'`, `'facebook'`) | | source | string | No | Where registration occurred | ### When to Fire * Account registration form submission * OAuth signup completion (Google, Facebook) * Post-purchase account creation *** ## subscribe Fires when a visitor subscribes to email or SMS marketing. ### JavaScript ```javascript theme={null} window._upstack('track', 'subscribe', { channel: 'email', source: 'footer_form', value: 5.00, currency: 'USD' }); ``` SMS subscription: ```javascript theme={null} window._upstack('track', 'subscribe', { channel: 'sms', source: 'popup', phone: '+15551234567' }); ``` ### Properties | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------------------------------------------- | | channel | string | No | Subscription channel (`'email'`, `'sms'`, `'push'`) | | source | string | No | Subscription source (e.g., `'popup'`, `'footer'`, `'checkout'`) | | value | number | No | Estimated subscriber value | | currency | string | No | ISO 4217 currency code | ### When to Fire * Newsletter signup * SMS opt-in * Push notification subscription *** ## add\_to\_wishlist Fires when a visitor adds a product to their wishlist. ### JavaScript ```javascript theme={null} window._upstack('track', 'add_to_wishlist', { items: [ { id: 'SKU_12345', name: 'Classic Cotton Tee', price: 34.99, brand: 'Example Brand' } ], value: 34.99, currency: 'USD' }); ``` ### Properties | Property | Type | Required | Description | | -------- | ------ | -------- | -------------------------- | | items | array | Yes | Products added to wishlist | | value | number | No | Product price | | currency | string | No | ISO 4217 currency code | ### When to Fire * Wishlist/favorite button click * Save for later action * Heart icon click on product *** ## refund Fires when an order is refunded. ### JavaScript Full refund: ```javascript theme={null} window._upstack('track', 'refund', { orderId: 'ORD_12345', value: 149.99, currency: 'USD' }); ``` Partial refund: ```javascript theme={null} window._upstack('track', 'refund', { orderId: 'ORD_12345', value: 89.99, currency: 'USD', items: [ { id: 'SKU_001', name: 'Blue Running Shoes', price: 89.99, quantity: 1 } ] }); ``` ### Properties | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------------------- | | orderId | string | Yes | Original order identifier | | value | number | Yes | Refund amount | | currency | string | No | ISO 4217 currency code | | items | array | No | Products refunded (for partial refunds) | ### When to Fire * Refund processed via Shopify admin * `refunds/create` webhook (server-side) * Customer service refund action *** ## login Fires when a user logs into their account. ### JavaScript ```javascript theme={null} window._upstack('track', 'login', { method: 'email' }); ``` ### Properties | Property | Type | Required | Description | | -------- | ------ | -------- | ---------------------------------------------------------------- | | method | string | No | Login method (`'email'`, `'google'`, `'facebook'`, `'shop_pay'`) | ### When to Fire * Successful login form submission * OAuth login completion * Automatic re-authentication *** ## sign\_up Fires when a user creates a new account. ### JavaScript ```javascript theme={null} window._upstack('track', 'sign_up', { method: 'email' }); ``` ### Properties | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------------------------------- | | method | string | No | Signup method (`'email'`, `'google'`, `'facebook'`) | **sign\_up vs complete\_registration:** Use `sign_up` for initial account creation. Use `complete_registration` for multi-step registration flows or when capturing additional profile data. ### When to Fire * Account creation form submission * OAuth signup completion *** ## contact Fires when a user submits a contact form. ### JavaScript ```javascript theme={null} window._upstack('track', 'contact', { formName: 'product_inquiry', email: 'customer@example.com' }); ``` ### Properties | Property | Type | Required | Description | | -------- | ------ | -------- | -------------------- | | formName | string | No | Form or inquiry type | | email | string | No | Contact's email | ### When to Fire * Contact us form submission * Support request submission * Product inquiry *** ## book\_call Fires when a user books a call or consultation. ### JavaScript ```javascript theme={null} window._upstack('track', 'book_call', { callType: 'sales_consultation', value: 200.00, currency: 'USD' }); ``` ### Properties | Property | Type | Required | Description | | -------- | ------ | -------- | -------------------------------------------------------- | | callType | string | No | Type of call (e.g., `'sales_consultation'`, `'support'`) | | value | number | No | Estimated value of the booking | | currency | string | No | ISO 4217 currency code | ### When to Fire * Calendly booking confirmation * Meeting scheduler submission * Demo request completion *** ## schedule Fires when a user schedules an appointment. ### JavaScript ```javascript theme={null} window._upstack('track', 'schedule', { appointmentType: 'fitting', value: 75.00, currency: 'USD' }); ``` ### Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | ---------------------- | | appointmentType | string | No | Type of appointment | | value | number | No | Service value | | currency | string | No | ISO 4217 currency code | ### When to Fire * Appointment booking confirmation * Service scheduling completion *** ## submit\_application Fires when a user submits an application. ### JavaScript ```javascript theme={null} window._upstack('track', 'submit_application', { applicationType: 'wholesale_partner', value: 5000.00, currency: 'USD' }); ``` ### Properties | Property | Type | Required | Description | | --------------- | ------ | -------- | --------------------------- | | applicationType | string | No | Application type | | value | number | No | Estimated application value | | currency | string | No | ISO 4217 currency code | ### When to Fire * Wholesale application submission * Affiliate program application * Partnership request *** ## trial\_started Fires when a visitor begins a free trial. ### JavaScript ```javascript theme={null} window._upstack('track', 'trial_started', { planName: 'Premium Plan', trialDays: 14, value: 49.99, currency: 'USD' }); ``` ### Properties | Property | Type | Required | Description | | --------- | ------ | -------- | -------------------------- | | planName | string | No | Trial plan or product name | | trialDays | number | No | Trial duration in days | | value | number | No | Plan value after trial | | currency | string | No | ISO 4217 currency code | ### When to Fire * Trial signup confirmation * Trial activation *** ## Item Object The `items` array in e-commerce events uses this structure: ```javascript theme={null} { id: 'SKU_12345', // Required: Product or variant ID name: 'Classic Cotton Tee', // Required: Product name price: 34.99, // Required: Unit price quantity: 1, // Required for cart/purchase events brand: 'Example Brand', // Optional: Brand name category: 'Apparel/Tees', // Optional: Product category (use / for hierarchy) variant: 'Blue / Medium', // Optional: Variant info position: 1 // Optional: Position in list (for impressions) } ``` | Property | Type | Required | Description | | -------- | ------ | -------- | -------------------------------------------------------------- | | id | string | Yes | Product or variant SKU/ID | | name | string | Yes | Product display name | | price | number | Yes | Unit price (not total) | | quantity | number | Varies | Required for add\_to\_cart, purchase; optional for view events | | brand | string | No | Brand or manufacturer | | category | string | No | Category path (e.g., `'Shoes/Running'`) | | variant | string | No | Size, color, or other variant | | position | number | No | Position in list for impression tracking | *** ## Event Tracking Matrix This matrix shows which events are tracked automatically by the Upstack Pixel on Shopify stores versus which require manual implementation. | Event | Shopify Auto | Headless/Manual | | --------------------------- | :------------------: | :-------------: | | `page_view` | ✅ | Required | | `view_content` | ✅ | Required | | `view_category` | ✅ | Required | | `view_item_list` | — | Required | | `add_to_cart` | ✅ | Required | | `product_removed_from_cart` | ✅ | Required | | `view_cart` | ✅ | Required | | `initiate_checkout` | ✅ | Required | | `add_shipping_info` | ✅ | Required | | `select_shipping_method` | — | Required | | `add_payment_info` | ✅ | Required | | `purchase` | ✅ | Required | | `search` | ✅ | Required | | `lead` | Via form hooks | Required | | `subscribe` | Via popup/form hooks | Required | | `complete_registration` | — | Required | | `login` | — | Required | | `sign_up` | — | Required | | `refund` | Via webhook | — | **Legend:** * ✅ = Automatically tracked by Upstack Pixel * Via form hooks = Tracked when using compatible form/popup apps * Via webhook = Tracked server-side through Shopify webhooks * Required = You must implement manually * — = Not applicable or rarely needed *** ## Events Not Covered Here | Event Type | Documentation | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `identify` | See [JavaScript SDK Reference](/pixel/javascript-sdk#identifyuserid-data) | | `nc_purchase` / `rc_purchase` | Upstack-generated new vs. returning customer purchase events. See [Custom Events](/pixel/custom-events#upstack-native-custom-purchase-events) | | Shopify automatic events | See [Shopify Automatic Tracking](/sources/shopify-automatic-tracking) | | SaaS events | See [SaaS Events Reference](/pixel/saas-events) | | Custom events | See [Custom Events](/pixel/custom-events) | ## Related Documentation Events that fire automatically on Shopify stores — check what's already tracked. Full SDK API reference including `identify()` and direct client methods. Complete reference for item arrays, customer data, and auto-captured fields. Create events beyond the standard taxonomy, including Upstack-generated events like `nc_purchase`. # Blended CPM: Cost Per 1,000 Impressions Across Channels Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-audience/blended-cpm Track your cost per 1,000 ad impressions across Meta, Google, and TikTok. Learn the formula, see examples, and optimize your reach efficiency. How much you pay for every 1,000 times your ads are shown across all channels. ## Formula **Blended CPM** = ( **Blended Spend** ÷ **Blended Impressions** ) × 1,000 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total amount spent on advertising across all platforms | | [**Blended Impressions**](/reference/metrics/advertising/blended/blended-audience/blended-impressions) | Total number of times ads were displayed across all platforms | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your campaigns spent **\$15,000** and generated **3,000,000 impressions** this month: | Channel | Spend | Impressions | CPM | | ----------- | ------------ | ------------- | ---------- | | Meta Ads | \$8,000 | 1,600,000 | \$5.00 | | Google Ads | \$5,000 | 1,000,000 | \$5.00 | | TikTok Ads | \$2,000 | 400,000 | \$5.00 | | **Blended** | **\$15,000** | **3,000,000** | **\$5.00** | *** ## How It Works Blended CPM aggregates your total ad spend and impressions across all connected advertising platforms, then calculates the cost per 1,000 impressions. This gives you a single efficiency metric for your entire paid media program regardless of channel mix. *** ## When to Use | Scenario | Action | | -------------------------- | ---------------------------------------------------------- | | Comparing reach efficiency | Benchmark your blended CPM against industry averages | | Budget planning | Estimate required budget based on target impression volume | | Channel mix optimization | Compare blended CPM to individual platform CPMs | | Seasonal analysis | Track how CPM fluctuates during peak advertising periods | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | The numerator in CPM calculation | | [Blended Impressions](/reference/metrics/advertising/blended/blended-audience/blended-impressions) | The denominator in CPM calculation | | [Blended CPC](/reference/metrics/advertising/blended/blended-clicks/blended-cpc) | Cost efficiency measured by clicks instead of impressions | [See all Blended Audience metrics →](/reference/metrics/advertising/blended/blended-audience) # Blended CPP: Cost Per Person Reached Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-audience/blended-cpp Track your blended cost per person reached across Meta, Google, and TikTok ads. Measure audience efficiency across all advertising channels. Blended CPP measures how much you pay to show your ads to each unique person across all advertising channels. ## Formula **Blended CPP** = **Blended Spend** ÷ **Blended Reach** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------ | -------------------------------------------------------- | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total amount spent on advertising across all channels | | [**Blended Reach**](/reference/metrics/advertising/blended/blended-audience/blended-reach) | Total unique people who saw your ads across all channels | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your brand spent **\$12,000** on advertising last month and reached **400,000 unique people** across all channels. | Channel | Spend | Reach | CPP | | ----------- | ------------ | ----------- | ----------- | | Meta Ads | \$6,000 | 250,000 | \$0.024 | | Google Ads | \$4,000 | 100,000 | \$0.040 | | TikTok Ads | \$2,000 | 50,000 | \$0.040 | | **Blended** | **\$12,000** | **400,000** | **\$0.030** | *** ## How It Works Blended CPP aggregates spend and reach data from all connected advertising platforms. It divides total spend by total unique people reached to show your average cost to reach one person. This metric helps evaluate cross-channel audience efficiency. *** ## When to Use | Scenario | Action | | --------------------------------------------- | ------------------------------------------------ | | Comparing audience efficiency across channels | Lower CPP indicates more cost-effective reach | | Budget allocation decisions | Shift spend toward channels with lower CPP | | Evaluating brand awareness campaigns | Track CPP trends to measure awareness efficiency | | Identifying audience saturation | Rising CPP may indicate diminishing returns | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator in CPP calculation | | [Blended Reach](/reference/metrics/advertising/blended/blended-audience/blended-reach) | Denominator in CPP calculation | | [Blended CPM](/reference/metrics/advertising/blended/blended-audience/blended-cpm) | Alternative audience cost metric (per 1,000 impressions) | [See all Blended Audience metrics →](/reference/metrics/advertising/blended/blended-audience) # Blended Frequency: Average Ad Views per User Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-audience/blended-frequency Measure how many times each user saw your ads across Meta, Google, and TikTok combined. Calculate frequency to optimize reach and avoid ad fatigue. The average number of times each unique user saw your ads across all channels. ## Formula **Blended Frequency** = **Blended Impressions** ÷ **Blended Reach** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------- | | [**Blended Impressions**](/reference/metrics/advertising/blended/blended-audience/blended-impressions) | Total ad views across all channels | | [**Blended Reach**](/reference/metrics/advertising/blended/blended-audience/blended-reach) | Unique users who saw your ads across all channels | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your cross-channel campaigns delivered **8.4M impressions** to **1.2M unique users**: | Metric | Value | | --------------------- | --------- | | Blended Impressions | 8,400,000 | | Blended Reach | 1,200,000 | | **Blended Frequency** | **7.0** | On average, each person saw your ads 7 times across Meta, Google, and TikTok. *** ## How It Works Blended Frequency aggregates impressions and reach from all connected ad platforms, then divides total impressions by unique reach. A frequency of 7.0 means users saw your ads 7 times on average across all channels combined. *** ## When to Use | Scenario | Action | | ---------------------------------- | ------------------------------------------------------------ | | Detecting ad fatigue | Frequency above 10–15 often signals diminishing returns | | Balancing reach vs. repetition | Lower frequency = broader reach; higher = deeper engagement | | Optimizing multi-channel campaigns | Compare blended frequency to platform-specific metrics | | Budget reallocation | Shift spend to lower-frequency channels if saturation occurs | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | ------------------------------------------ | | [Blended Impressions](/reference/metrics/advertising/blended/blended-audience/blended-impressions) | Numerator in the frequency calculation | | [Blended Reach](/reference/metrics/advertising/blended/blended-audience/blended-reach) | Denominator in the frequency calculation | | [Blended CPM](/reference/metrics/advertising/blended/blended-audience/blended-cpm) | Cost efficiency at current frequency level | [See all Blended Audience metrics →](/reference/metrics/advertising/blended/blended-audience) # Blended Impressions: Total Ad Views Across All Channels Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-audience/blended-impressions Track total ad impressions across Meta, Google, and TikTok in one view. Compare platform reach and optimize ad frequency for better efficiency. The total number of times your ads were displayed across all advertising channels. ## Formula **Blended Impressions** = **SUM** ( Impressions ) **ACROSS** all platforms ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | [**Meta Impressions**](/reference/metrics/advertising/meta/meta-audience/meta-impressions) | Number of times your Meta ads were displayed | | [**Google Impressions**](/reference/metrics/advertising/google/google-audience/google-impressions) | Number of times your Google ads were displayed | | [**TikTok Impressions**](/reference/metrics/advertising/tiktok/tiktok-audience/tiktok-impressions) | Number of times your TikTok ads were displayed | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your campaigns delivered **2.4M impressions** across all channels last week: | Platform | Impressions | Share | | ---------- | ----------- | ----- | | Meta Ads | 1,200,000 | 50% | | Google Ads | 840,000 | 35% | | TikTok Ads | 360,000 | 15% | *** ## How It Works Blended Impressions aggregates impression counts from each connected advertising platform into a single metric. Each platform reports impressions differently—Meta counts each ad view, Google counts each ad load, and TikTok counts viewable impressions. This metric sums them all for a unified view of total ad delivery. *** ## When to Use | Scenario | Action | | --------------------- | ------------------------------------------------------------- | | Measuring total reach | Track how many times your ads appear across all platforms | | Calculating CPM | Divide Blended Spend by Blended Impressions × 1,000 | | Frequency analysis | Compare impressions to reach to understand repeat views | | Budget pacing | Monitor delivery against spend to ensure efficient ad serving | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | [Blended Reach](/reference/metrics/advertising/blended/blended-audience/blended-reach) | Unique users who saw your ads (impressions ÷ frequency) | | [Blended CPM](/reference/metrics/advertising/blended/blended-audience/blended-cpm) | Cost per 1,000 impressions | | [Blended Frequency](/reference/metrics/advertising/blended/blended-audience/blended-frequency) | Average impressions per unique user | [See all Blended Audience metrics →](/reference/metrics/advertising/blended/blended-audience) # Blended Reach: Cross-Platform Audience Size Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-audience/blended-reach Track unique users who saw your ads across Meta, Google, and TikTok. Understand total audience size and eliminate platform overlap in reach reporting. The total number of unique users who saw your ads at least once across all connected advertising platforms. ## Formula **Blended Reach** = **COUNT DISTINCT** ( Users ) **WHERE** impression ≥ 1 **ACROSS** all platforms ### Formula Components | Metric | Definition | | ------------------ | --------------------------------------------------------------------------------- | | **Users** | Individual people served at least one ad impression across any connected platform | | **impression ≥ 1** | Filter ensuring only users with at least one ad view are counted | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Count Distinct | *** ## Example Your campaigns reached **2.4M unique users** across all platforms this month: | Platform | Reach | Share | | ---------- | ----- | ----- | | Meta Ads | 1.8M | 75% | | Google Ads | 420K | 18% | | TikTok Ads | 180K | 7% | Note: Platform totals may exceed blended reach due to cross-platform audience overlap. *** ## How It Works Blended Reach aggregates unique user counts from all connected ad platforms. Each platform reports its own reach independently—users who see ads on multiple platforms are counted once per platform but may appear in multiple platform totals. The blended figure provides a unified view of total audience exposure. *** ## When to Use | Scenario | Action | | ------------------------- | ------------------------------------------------ | | Measuring brand awareness | Track how many unique people saw your ads | | Evaluating media mix | Compare reach contribution by platform | | Calculating frequency | Divide Blended Impressions by Blended Reach | | Optimizing CPP | Monitor cost per person reached across platforms | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | -------------------------------------------- | | [Blended Impressions](/reference/metrics/advertising/blended/blended-audience/blended-impressions) | Total ad views (Reach counts unique users) | | [Blended Frequency](/reference/metrics/advertising/blended/blended-audience/blended-frequency) | Impressions ÷ Reach (average views per user) | | [Blended CPP](/reference/metrics/advertising/blended/blended-audience/blended-cpp) | Spend ÷ Reach (cost per person reached) | [See all Blended Audience metrics →](/reference/metrics/advertising/blended/blended-audience) # Blended Audience Metrics Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-audience/index Cross-platform audience metrics for reach, impressions, and frequency across Meta, Google, and TikTok. Track total ad exposure and cost efficiency in one view. Blended Audience metrics aggregate reach, impressions, frequency, and audience costs from all connected advertising platforms. Understand your total ad exposure without checking each platform separately. **Data Sources:** [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok)\ **Metrics:** 5 ## Metrics in This Group | Metric | Description | When to Use | | -------------------------------------------------------------------------------------------------- | -------------------------------------------------- | --------------------------------------- | | [Blended Impressions](/reference/metrics/advertising/blended/blended-audience/blended-impressions) | Total ad views across all platforms | Measure total ad exposure and scale | | [Blended Reach](/reference/metrics/advertising/blended/blended-audience/blended-reach) | Unique users who saw your ads across all platforms | Measure total audience size | | [Blended Frequency](/reference/metrics/advertising/blended/blended-audience/blended-frequency) | Average times each person saw your ads | Detect ad fatigue and optimize delivery | | [Blended CPM](/reference/metrics/advertising/blended/blended-audience/blended-cpm) | Cost per 1,000 impressions across all platforms | Evaluate delivery cost efficiency | | [Blended CPP](/reference/metrics/advertising/blended/blended-audience/blended-cpp) | Cost per person reached across all platforms | Measure cost efficiency per unique user | ## How These Metrics Relate * **Blended Impressions** counts every ad view across platforms * **Blended Reach** counts unique individuals across platforms * **Blended Frequency** = Impressions ÷ Reach — average views per person * **Blended CPM** = Spend ÷ Impressions × 1,000 — measures delivery cost * **Blended CPP** = Spend ÷ Reach — cost per person reached ## Platform Overlap Users may see ads on multiple platforms. Platform totals may exceed blended totals because: * A user who sees ads on both Meta and TikTok counts once in Blended Reach * Platform-specific reach counts them separately in each platform's metrics Blended metrics provide the most accurate total audience picture. # Blended Clicks: Total Ad Clicks Across All Platforms Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-clicks/blended-clicks Track total clicks on your ads across Meta, Google, and TikTok. Measure cross-platform engagement and benchmark click performance. Blended Clicks measures the total number of clicks on your ads across all connected advertising platforms, including all click types. ## Formula **Blended Clicks** = **SUM** ( Clicks ) **ACROSS** all platforms ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------- | -------------------------------- | | [**Meta Clicks**](/reference/metrics/advertising/meta/meta-clicks/meta-clicks) | Clicks from Meta Ads campaigns | | [**Google Clicks**](/reference/metrics/advertising/google/google-clicks/google-clicks) | Clicks from Google Ads campaigns | | [**TikTok Clicks**](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-clicks) | Clicks from TikTok Ads campaigns | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your brand received **45,200 clicks** across all platforms in February: | Platform | Clicks | % of Total | | ----------- | ---------- | ---------- | | Meta Ads | 28,500 | 63% | | Google Ads | 11,300 | 25% | | TikTok Ads | 5,400 | 12% | | **Blended** | **45,200** | **100%** | *** ## How It Works Blended Clicks aggregates click data from all connected ad platforms into a single metric. Each platform reports clicks differently—Meta includes various in-app interactions, Google counts Search and Display clicks, and TikTok tracks in-feed engagements—but the blended total gives you a unified view of ad engagement. *** ## When to Use | Scenario | Action | | -------------------------- | ------------------------------------------------------------ | | Measuring total engagement | Track blended clicks to see overall ad performance | | Calculating CPC | Divide total spend by blended clicks for true cost per click | | Comparing time periods | Benchmark click volume week-over-week or month-over-month | | Evaluating campaign scale | Assess whether your budget is generating sufficient clicks | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | [Blended CTR](/reference/metrics/advertising/blended/blended-clicks/blended-ctr) | Click-through rate using this as the numerator | | [Blended CPC](/reference/metrics/advertising/blended/blended-clicks/blended-cpc) | Cost efficiency using this as the denominator | | [Blended Impressions](/reference/metrics/advertising/blended/blended-audience/blended-impressions) | Total ad views — clicks ÷ impressions = CTR | [See all Blended Clicks metrics →](/reference/metrics/advertising/blended/blended-clicks) # Blended Cost Per Landing Page View: Ad Efficiency Metric Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-clicks/blended-cost-per-landing-page-view Track your cost per landing page view across all ad platforms. Measure what you pay for each successful page load from Meta, Google, and TikTok ads. Blended Cost Per Landing Page View measures how much you pay for each successful landing page load from an ad click, aggregated across all connected ad platforms. ## Formula **Blended Cost Per Landing Page View** = **Blended Spend** ÷ **Blended Landing Page Views** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total ad spend aggregated across all platforms | | [**Blended Landing Page Views**](/reference/metrics/advertising/blended/blended-clicks/blended-landing-page-views) | Landing page views from clicks across all platforms | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your campaigns generated **12,500 landing page views** across all platforms with **\$2,500 in total spend**. | Platform | Spend | Landing Page Views | Cost Per LPV | | ----------- | ----------- | ------------------ | ------------ | | Meta | \$1,200 | 6,000 | \$0.20 | | Google | \$800 | 4,000 | \$0.20 | | TikTok | \$500 | 2,500 | \$0.20 | | **Blended** | **\$2,500** | **12,500** | **\$0.20** | *** ## How It Works This metric divides your total ad spend by the number of landing page views across Meta, Google, and TikTok. A landing page view counts only when someone clicks your ad and the page actually loads—filtering out accidental clicks and bounces before load. *** ## When to Use | Scenario | Action | | ---------------------------- | ----------------------------------------------------------- | | Comparing true click quality | Use instead of CPC to see what you pay for engaged visitors | | High CPC but low conversions | Check if landing pages are loading for clickers | | Mobile vs desktop analysis | Compare cost per LPV across devices | | Cross-platform efficiency | Identify which platform delivers cheapest qualified traffic | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator—total ad cost | | [Blended Landing Page Views](/reference/metrics/advertising/blended/blended-clicks/blended-landing-page-views) | Denominator—successful page loads | | [Blended CPC](/reference/metrics/advertising/blended/blended-clicks/blended-cpc) | Compare to see click vs load efficiency | [See all Blended Clicks metrics →](/reference/metrics/advertising/blended/blended-clicks) # Blended Cost Per Outbound Click: Cross-Platform Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-clicks/blended-cost-per-outbound-click Track your cost per outbound click across all ad platforms. Measure efficiency of clicks that lead users off Meta, Google, and TikTok to your site. Blended Cost Per Outbound Click measures how much you pay for each click that leads users off the ad platform to your website, aggregated across all connected ad accounts. ## Formula **Blended Cost Per Outbound Click** = **Blended Spend** ÷ **Blended Outbound Clicks** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total advertising spend across all connected ad platforms | | [**Blended Outbound Clicks**](/reference/metrics/advertising/blended/blended-clicks/blended-outbound-clicks) | Clicks that lead users off the ad platform to your website | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your campaigns spent **\$5,000** across all platforms and generated **2,500 outbound clicks**. | Metric | Value | | --------------------------- | ---------- | | Total Spend | \$5,000 | | Outbound Clicks | 2,500 | | **Cost Per Outbound Click** | **\$2.00** | *** ## How It Works This metric divides your total advertising spend by the number of clicks that actually send users to your website. Unlike standard CPC which includes all clicks, this focuses only on outbound clicks—giving you a true picture of what you pay for traffic. *** ## When to Use | Scenario | Action | | ---------------------------------- | --------------------------------------------------------------- | | Comparing traffic acquisition cost | Use to evaluate cost efficiency across platforms | | Budget allocation decisions | Shift spend toward platforms with lower cost per outbound click | | Campaign optimization | Identify campaigns with high costs relative to outbound traffic | | Benchmarking efficiency | Track changes over time to measure optimization impact | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator in the formula | | [Blended Outbound Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-outbound-clicks) | Denominator in the formula | | [Blended CPC](/reference/metrics/advertising/blended/blended-clicks/blended-cpc) | Similar metric using all clicks instead of outbound only | [See all Blended Clicks metrics →](/reference/metrics/advertising/blended/blended-clicks) # Blended Cost Per Unique Click: Cost Per Unique Ad Clicker Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-clicks/blended-cost-per-unique-click Track the cost per unique person who clicked your ads across Meta, Google, and TikTok. Optimize spend efficiency by measuring deduplicated click costs. Blended Cost Per Unique Click measures how much you pay to acquire each distinct person who clicks your ads across all advertising platforms. ## Formula **Blended Cost Per Unique Click** = **Blended Spend** ÷ **Blended Unique Clicks** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Combined ad spend across all connected advertising platforms | | [**Blended Unique Clicks**](/reference/metrics/advertising/blended/blended-clicks/blended-unique-clicks) | Distinct people who clicked ads at least once across all platforms | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your brand spent **\$8,400** in March and acquired **8,420 unique clickers**: | Metric | Value | | --------------------------------- | ---------- | | Blended Spend | \$8,400 | | Unique Clickers | 8,420 | | **Blended Cost Per Unique Click** | **\$1.00** | *** ## How It Works Blended Cost Per Unique Click divides total spend by unique clickers across all connected platforms. Unlike standard CPC, this metric counts each person only once—showing true cost to reach new engaged users. *** ## When to Use | Scenario | Action | | -------------------------------- | ------------------------------------------------------------------ | | Measuring acquisition efficiency | Compare cost per unique clicker vs standard CPC | | Detecting click fraud | High CPC but low cost/unique click may indicate bot clicks | | Optimizing for reach | Prioritize platforms with lower cost per unique click | | Cross-platform budgeting | Identify which platforms deliver unique audiences cost-effectively | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | ----------------------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator — total cost across platforms | | [Blended Unique Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-unique-clicks) | Denominator — distinct clickers | | [Blended CPC](/reference/metrics/advertising/blended/blended-clicks/blended-cpc) | Total click cost (includes repeat clicks) | [See all Blended Clicks metrics →](/reference/metrics/advertising/blended/blended-clicks) # Blended CPC: Average Cost Per Click Across All Ad Platforms Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-clicks/blended-cpc Track your average cost per click across Meta, Google, and TikTok ads. Compare cross-platform click efficiency and optimize ad spend allocation. Blended CPC measures how much you pay on average for each click on your ads across all connected advertising platforms. ## Formula **Blended CPC** = **Blended Spend** ÷ **Blended Clicks** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------ | -------------------------------------- | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Combined ad spend across all platforms | | [**Blended Clicks**](/reference/metrics/advertising/blended/blended-clicks/blended-clicks) | Total clicks across all platforms | | Metadata | | | --------------- | ---------------------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) (aggregated) | | **Aggregation** | Ratio | *** ## Example Your brand spent **\$8,400** across all platforms in March and received **12,000 clicks**: | Platform | Spend | Clicks | CPC | | ----------- | ----------- | ---------- | ---------- | | Meta Ads | \$4,200 | 7,000 | \$0.60 | | Google Ads | \$2,800 | 3,500 | \$0.80 | | TikTok Ads | \$1,400 | 1,500 | \$0.93 | | **Blended** | **\$8,400** | **12,000** | **\$0.70** | *** ## How It Works Blended CPC aggregates spend and clicks from all connected ad platforms, then calculates the weighted average cost per click. This gives you a single efficiency metric for your entire paid media budget regardless of platform mix. *** ## When to Use | Scenario | Action | | ----------------------------- | ------------------------------------------------------------ | | Setting budget caps | Use blended CPC to establish cost thresholds across channels | | Comparing platform efficiency | Identify which platforms deliver cheaper clicks | | Forecasting click volume | Estimate clicks from a given budget allocation | | Optimizing media mix | Shift spend toward platforms with lower CPC | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------- | ------------------------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator — total cost across platforms | | [Blended Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-clicks) | Denominator — total clicks across platforms | | [Blended CTR](/reference/metrics/advertising/blended/blended-clicks/blended-ctr) | Measures click rate; CPC shows click cost | [See all Blended Clicks metrics →](/reference/metrics/advertising/blended/blended-clicks) # Blended CPC (Link): Cost Per Link Click Across Channels Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-clicks/blended-cpc-link Track your cost per link click across Meta, Google, and TikTok ads combined. Calculate efficiency and optimize your cross-channel ad spend. The cost per link click across all advertising channels combined. ## Formula **Blended CPC (Link)** = **Blended Spend** ÷ **Blended Link Clicks** ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total ad spend aggregated across all channels | | [**Blended Link Clicks**](/reference/metrics/advertising/blended/blended-clicks/blended-link-clicks) | Total link clicks aggregated across all channels | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your campaigns generated **125,000 link clicks** with **\$8,750 total spend**: | Channel | Spend | Link Clicks | CPC (Link) | | ----------- | ----------- | ----------- | ---------- | | Meta Ads | \$5,000 | 71,400 | \$0.07 | | Google Ads | \$2,500 | 35,700 | \$0.07 | | TikTok Ads | \$1,250 | 17,900 | \$0.07 | | **Blended** | **\$8,750** | **125,000** | **\$0.07** | *** ## How It Works Blended CPC (Link) divides your total ad spend across all channels by the total link clicks received. Link clicks specifically measure clicks that take users to your website, excluding engagement clicks like reactions or video views. *** ## When to Use | Scenario | Action | | ----------------------- | --------------------------------------------------- | | Comparing traffic costs | Benchmark link click efficiency across all channels | | Budget optimization | Identify if blended costs are rising or falling | | Creative testing | Measure if new creatives improve click efficiency | | Cross-channel analysis | Compare blended CPC to individual platform CPCs | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------ | ----------------------------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | The numerator in this calculation | | [Blended Link Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-link-clicks) | The denominator in this calculation | | [Blended CPC](/reference/metrics/advertising/blended/blended-clicks/blended-cpc) | Cost per total click (includes all click types) | [See all Blended Clicks metrics →](/reference/metrics/advertising/blended/blended-clicks) # Blended CTR: Click-Through Rate Across All Channels Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-clicks/blended-ctr Track your blended click-through rate across Meta, Google, and TikTok ads. Learn how CTR measures ad engagement and what benchmarks to target. Blended CTR measures the percentage of impressions that resulted in a click across all your advertising channels. ## Formula **Blended CTR** = ( **Blended Clicks** ÷ **Blended Impressions** ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------- | | [**Blended Clicks**](/reference/metrics/advertising/blended/blended-clicks/blended-clicks) | Total clicks across Meta, Google, and TikTok ads | | [**Blended Impressions**](/reference/metrics/advertising/blended/blended-audience/blended-impressions) | Total impressions across all advertising channels | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your campaigns delivered **2,450,000 impressions** and **36,750 clicks** across all channels last month: | Metric | Value | | ------------------- | --------- | | Blended Impressions | 2,450,000 | | Blended Clicks | 36,750 | | **Blended CTR** | **1.50%** | *** ## How It Works Blended CTR aggregates clicks and impressions from Meta, Google, and TikTok, then calculates the overall click-through rate. This gives you a single view of ad engagement across your entire paid media mix. *** ## When to Use | Scenario | Action | | ------------------------ | ----------------------------------------------- | | Evaluating ad engagement | Compare to industry benchmarks (1-2% typical) | | Testing new creative | Monitor CTR changes after launching variations | | Budget allocation | Identify which channels drive higher engagement | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | ------------------------------ | | [Blended Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-clicks) | Numerator in CTR calculation | | [Blended Impressions](/reference/metrics/advertising/blended/blended-audience/blended-impressions) | Denominator in CTR calculation | | [Blended CPC](/reference/metrics/advertising/blended/blended-clicks/blended-cpc) | Cost efficiency of each click | [See all Blended Clicks metrics →](/reference/metrics/advertising/blended/blended-clicks) # Blended Inline Link Clicks: Clicks on Embedded Ad Links Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-clicks/blended-inline-link-clicks Track inline link clicks across Meta, Google, and TikTok ads. Measure engagement with embedded links in ad creative text, not CTA buttons. Clicks on links embedded in the ad text or creative (not CTA buttons), aggregated across all ad platforms. ## Formula **Blended Inline Link Clicks** = **SUM** ( Inline Link Clicks ) **ACROSS** all platforms ### Formula Components | Metric | Definition | | ------------------------- | -------------------------------------------------------- | | Meta Inline Link Clicks | Clicks on embedded links within Meta ad copy or creative | | Google Inline Link Clicks | Clicks on embedded links within Google ad text | | TikTok Inline Link Clicks | Clicks on embedded links within TikTok ad creative | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your campaigns generated **2,840 inline link clicks** this week: | Platform | Inline Clicks | Share | | ---------- | ------------- | ----- | | Meta Ads | 1,560 | 55% | | Google Ads | 890 | 31% | | TikTok Ads | 390 | 14% | *** ## How It Works Inline link clicks are counted when users click on links embedded within the ad's text content—such as hyperlinked words, hashtags, or mentions—rather than the primary call-to-action button. This metric aggregates inline clicks across all connected ad platforms. *** ## When to Use | Scenario | Action | | ---------------------------- | ----------------------------------------------------- | | Measuring content engagement | Identify ads where copy drives clicks vs. CTAs | | Comparing click types | Contrast inline clicks with outbound and CTA clicks | | Optimizing ad creative | Test different link placements in ad copy | | Cross-platform analysis | Compare inline engagement across Meta, Google, TikTok | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [Blended Link Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-link-clicks) | All link clicks (includes inline, outbound, CTA) | | [Blended Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-clicks) | Total clicks of all types on ads | | [Blended Outbound Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-outbound-clicks) | Clicks that lead users off-platform | [See all Blended Clicks metrics →](/reference/metrics/advertising/blended/blended-clicks) # Blended Landing Page Views: Successful Post-Click Site Visits Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-clicks/blended-landing-page-views Track landing page views across Meta, Google, and TikTok ads. Measure how many users successfully loaded your site after clicking an ad. Blended Landing Page Views measures the number of times users successfully loaded your landing page after clicking an ad across all connected advertising platforms. ## Formula **Blended Landing Page Views** = **SUM** ( Landing Page Views ) **ACROSS** all platforms ### Formula Components | Metric | Definition | | ----------------------------- | ------------------------------------------- | | **Meta Landing Page Views** | Successful page loads from Meta ad clicks | | **Google Landing Page Views** | Successful page loads from Google ad clicks | | **TikTok Landing Page Views** | Successful page loads from TikTok ad clicks | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your brand's ads generated **12,450 landing page views** last week across all platforms: | Platform | Landing Page Views | Share | | ---------- | ------------------ | ----- | | Meta Ads | 6,780 | 54% | | Google Ads | 4,120 | 33% | | TikTok Ads | 1,550 | 13% | *** ## How It Works Landing Page Views count when a user clicks your ad and the destination page successfully loads in their browser. This is more qualified than raw clicks—it confirms the user actually reached your site rather than bouncing before the page loaded due to slow connections or abandoned navigation. *** ## When to Use | Scenario | Action | | ---------------------------------- | ----------------------------------------------- | | Measuring qualified traffic | Track users who actually reached your site | | Diagnosing click-to-visit drop-off | Compare link clicks vs landing page views | | Evaluating page load performance | Low LP views vs high clicks suggests slow pages | | Calculating cost per site visit | Divide spend by landing page views | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | [Blended Link Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-link-clicks) | Clicks that lead to landing page views | | [Blended Outbound Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-outbound-clicks) | Clicks that leave the ad platform | | [Blended Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-clicks) | Total clicks including non-link interactions | [See all Blended Clicks metrics →](/reference/metrics/advertising/blended/blended-clicks) # Blended Link Clicks: Total Ad Link Engagement Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-clicks/blended-link-clicks Track total link clicks across Meta, Google, and TikTok ads. Measure how many users clicked links in your ads to reach destinations on or off the platform. Blended Link Clicks measures the total number of clicks on links in your ads across all connected advertising channels. ## Formula **Blended Link Clicks** = **SUM** ( Link Clicks ) **ACROSS** all platforms ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------- | ---------------------------------------- | | [**Meta Link Clicks**](/reference/metrics/advertising/meta/meta-clicks/meta-link-clicks) | Clicks on ad links from Meta campaigns | | **Google Link Clicks** | Clicks on ad links from Google campaigns | | **TikTok Link Clicks** | Clicks on ad links from TikTok campaigns | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your brand ran campaigns across three platforms last week, generating **8,432 total link clicks**: | Platform | Link Clicks | Share | | ---------- | ----------- | ----- | | Meta Ads | 4,150 | 49% | | Google Ads | 2,890 | 34% | | TikTok Ads | 1,392 | 17% | *** ## How It Works Blended Link Clicks aggregates link click data from each connected advertising platform. A link click occurs when a user clicks a link in your ad that directs them to a destination—whether that's your website, app store, or another page within the ad platform. *** ## When to Use | Scenario | Action | | -------------------------------------------- | --------------------------------------------- | | Measuring cross-platform ad engagement | Compare link click volume across channels | | Evaluating creative performance | Identify which ads drive the most link clicks | | Calculating blended click-through efficiency | Divide by impressions for blended link CTR | | Budget allocation decisions | Shift spend toward higher link click channels | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | [Blended Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-clicks) | Total clicks including non-link interactions | | [Blended Outbound Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-outbound-clicks) | Clicks that leave the ad platform | | [Blended Landing Page Views](/reference/metrics/advertising/blended/blended-clicks/blended-landing-page-views) | Users who actually reached your landing page | [See all Blended Clicks metrics →](/reference/metrics/advertising/blended/blended-clicks) # Blended Link CTR: Link Click-Through Rate Across All Channels Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-clicks/blended-link-ctr Track your blended link click-through rate across Meta, Google, and TikTok ads. Measure what percentage of impressions resulted in a link click. Blended Link CTR measures the percentage of impressions that resulted in a link click across all your advertising channels. ## Formula **Blended Link CTR** = ( **Blended Link Clicks** ÷ **Blended Impressions** ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- | | [**Blended Link Clicks**](/reference/metrics/advertising/blended/blended-clicks/blended-link-clicks) | Total link clicks across Meta, Google, and TikTok ads | | [**Blended Impressions**](/reference/metrics/advertising/blended/blended-audience/blended-impressions) | Total impressions across all advertising channels | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your campaigns delivered **3,200,000 impressions** and **28,800 link clicks** across all channels last month: | Metric | Value | | -------------------- | --------- | | Blended Impressions | 3,200,000 | | Blended Link Clicks | 28,800 | | **Blended Link CTR** | **0.90%** | *** ## How It Works Blended Link CTR aggregates link clicks and impressions from Meta, Google, and TikTok, then calculates the overall link click-through rate. Unlike standard CTR which includes all clicks, Link CTR focuses specifically on clicks that direct users to a destination URL. *** ## When to Use | Scenario | Action | | --------------------------------------- | ----------------------------------------------- | | Measuring ad-to-site traffic efficiency | Compare link CTR to standard CTR | | Optimizing landing page campaigns | Target 0.5-1.5% link CTR benchmarks | | Evaluating creative performance | Identify which ads drive more link clicks | | Budget allocation | Prioritize channels with higher link engagement | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | ----------------------------------------- | | [Blended Link Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-link-clicks) | Numerator in Link CTR calculation | | [Blended Impressions](/reference/metrics/advertising/blended/blended-audience/blended-impressions) | Denominator in Link CTR calculation | | [Blended CTR](/reference/metrics/advertising/blended/blended-clicks/blended-ctr) | Includes all clicks, not just link clicks | [See all Blended Clicks metrics →](/reference/metrics/advertising/blended/blended-clicks) # Blended Outbound Clicks: Off-Platform Click Tracking Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-clicks/blended-outbound-clicks Track outbound clicks that drive traffic from ad platforms to your website or app. Aggregate data from Meta, Google, and TikTok Ads. Blended Outbound Clicks measures how many ad clicks took users away from ad platforms to your website, app, or other external destinations. ## Formula **Blended Outbound Clicks** = **SUM** ( Outbound Clicks ) **ACROSS** all platforms ### Formula Components | Metric | Definition | | -------------------------- | ------------------------------------------------ | | **Meta Outbound Clicks** | Clicks that sent people from Meta to your site | | **Google Outbound Clicks** | Clicks that sent people from Google to your site | | **TikTok Outbound Clicks** | Clicks that sent people from TikTok to your site | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example A DTC skincare brand ran campaigns across Meta and Google Ads during a spring promotion. Their **outbound click performance**: | Platform | Outbound Clicks | Spend | Cost per Outbound Click | | ----------------- | --------------- | ------- | ----------------------- | | Meta Ads | 8,420 | \$2,105 | \$0.25 | | Google Ads | 3,180 | \$954 | \$0.30 | | **Blended Total** | **11,600** | \$3,059 | \$0.26 | *** ## How It Works Outbound clicks count only clicks that lead users away from the ad platform to an external destination—typically your website or app. This excludes clicks that stay within the platform (like clicks to view more of a carousel or expand a post). Upstack aggregates this metric from each connected ad account to give you a unified view of traffic-driving performance. *** ## When to Use | Scenario | Action | | ----------------------------- | ------------------------------------------------------------------ | | Measuring traffic acquisition | Compare outbound clicks to landing page views to identify drop-off | | Evaluating ad creative | Higher outbound clicks indicate stronger calls-to-action | | Cross-platform comparison | Identify which platforms drive the most site traffic | | Budget allocation | Shift spend toward platforms with lower cost per outbound click | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | [Blended Link Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-link-clicks) | All link clicks including in-platform; outbound is a subset | | [Blended Landing Page Views](/reference/metrics/advertising/blended/blended-clicks/blended-landing-page-views) | Users who fully loaded your page after an outbound click | | [Blended Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-clicks) | Total clicks of all types; outbound focuses on external traffic | [See all Blended Clicks metrics →](/reference/metrics/advertising/blended/blended-clicks) # Blended Outbound CTR: External Click-Through Rate Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-clicks/blended-outbound-ctr Track your blended outbound click-through rate across Meta, Google, and TikTok ads. Measure the percentage of impressions that drove traffic to your site. Blended Outbound CTR measures the percentage of impressions that resulted in an outbound click—clicks that drove users to your website or app from ad platforms. ## Formula **Blended Outbound CTR** = ( **Blended Outbound Clicks** ÷ **Blended Impressions** ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | | [**Blended Outbound Clicks**](/reference/metrics/advertising/blended/blended-clicks/blended-outbound-clicks) | Clicks that drove users from ad platforms to your site | | [**Blended Impressions**](/reference/metrics/advertising/blended/blended-audience/blended-impressions) | Total impressions across all advertising channels | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your campaigns delivered **1,800,000 impressions** and **18,000 outbound clicks** across all channels: | Metric | Value | | ------------------------ | --------- | | Blended Impressions | 1,800,000 | | Blended Outbound Clicks | 18,000 | | **Blended Outbound CTR** | **1.00%** | *** ## How It Works Blended Outbound CTR aggregates outbound clicks and impressions from Meta, Google, and TikTok, then calculates the rate at which ad views converted into external site visits. Unlike standard CTR, this focuses only on clicks that left the ad platform. *** ## When to Use | Scenario | Action | | ---------------------------- | ----------------------------------------------------------- | | Measuring traffic efficiency | Compare to standard CTR to see external vs total engagement | | Evaluating landing page CTAs | Low outbound CTR may indicate weak calls-to-action | | Budget optimization | Allocate spend to platforms with higher outbound CTR | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | --------------------------------------- | | [Blended Outbound Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-outbound-clicks) | Numerator in outbound CTR calculation | | [Blended Impressions](/reference/metrics/advertising/blended/blended-audience/blended-impressions) | Denominator in outbound CTR calculation | | [Blended CTR](/reference/metrics/advertising/blended/blended-clicks/blended-ctr) | Total CTR including in-platform clicks | [See all Blended Clicks metrics →](/reference/metrics/advertising/blended/blended-clicks) # Blended Unique Clicks: Deduplicated Ad Clicks Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-clicks/blended-unique-clicks Track unique people who clicked your ads across Meta, Google, and TikTok. Count each person once regardless of total clicks. Blended Unique Clicks counts the number of distinct people who clicked your ads at least once, aggregated across all advertising platforms. ## Formula **Blended Unique Clicks** = **COUNT DISTINCT** ( Users ) **WHERE** clicked = true **ACROSS** all platforms ### Formula Components | Metric | Definition | | ------------------ | ------------------------------------------------------------ | | **Unique Users** | Distinct people who interacted with ads across all platforms | | **clicked = true** | Filters to users who clicked at least one ad | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Count Distinct | *** ## Example Your campaigns reached **8,420 unique clickers** in March across all platforms. | Platform | Impressions | Total Clicks | Unique Clicks | | ----------- | ----------- | ------------ | ------------- | | Meta | 125,000 | 3,200 | 2,850 | | Google | 89,000 | 2,100 | 1,920 | | TikTok | 156,000 | 4,500 | 3,650 | | **Blended** | **370,000** | **9,800** | **8,420** | *** ## How It Works Each platform reports unique clicks by deduplicating users who clicked multiple times. Blended Unique Clicks aggregates these counts across Meta, Google, and TikTok to show total unique engagement. *** ## When to Use | Scenario | Action | | ----------------------------- | -------------------------------------------------------------- | | Measuring true engagement | Compare unique clicks vs total clicks to gauge repeat interest | | Evaluating creative quality | High unique-to-total ratio indicates broad appeal | | Assessing audience saturation | Declining unique clicks may signal audience fatigue | | Budget allocation | Shift spend to platforms with more unique clickers | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | [Blended Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-clicks) | Total clicks including repeats from same user | | [Blended Unique CTR](/reference/metrics/advertising/blended/blended-clicks/blended-unique-ctr) | Percentage of impressions resulting in unique clicks | | [Blended Cost per Unique Click](/reference/metrics/advertising/blended/blended-clicks/blended-cost-per-unique-click) | Average cost to acquire each unique clicker | [See all Blended Clicks metrics →](/reference/metrics/advertising/blended/blended-clicks) # Blended Unique CTR: Percentage of Reach That Clicked Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-clicks/blended-unique-ctr Track your unique click-through rate across Meta, Google, and TikTok ads. Measure what percentage of reached users clicked at least once. Blended Unique CTR measures the percentage of unique users reached who clicked your ads at least once across all advertising channels. ## Formula **Blended Unique CTR** = ( **Blended Unique Clicks** ÷ **Blended Reach** ) × 100 ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | [**Blended Unique Clicks**](/reference/metrics/advertising/blended/blended-clicks/blended-unique-clicks) | Distinct people who clicked at least once across all platforms | | [**Blended Reach**](/reference/metrics/advertising/blended/blended-audience/blended-reach) | Unique users who saw your ads across all platforms | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your campaigns reached **850,000 unique users** with **12,750 unique clickers** last month. | Metric | Value | | ---------------------- | --------- | | Blended Unique Clicks | 12,750 | | Blended Reach | 850,000 | | **Blended Unique CTR** | **1.50%** | *** ## How It Works Blended Unique CTR divides unique clickers by unique users reached across Meta, Google, and TikTok. Unlike standard CTR (which uses impressions), this shows what percentage of your actual audience engaged with your ads at least once. *** ## When to Use | Scenario | Action | | ----------------------------- | ------------------------------------------------- | | Measuring audience engagement | Compare to standard CTR for true reach conversion | | Evaluating creative resonance | Higher unique CTR indicates broader appeal | | Assessing targeting quality | Low unique CTR may signal poor audience fit | | Cross-platform benchmarking | Compare engagement rates across unified audience | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | ---------------------------------- | | [Blended Unique Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-unique-clicks) | Numerator — unique clickers | | [Blended Reach](/reference/metrics/advertising/blended/blended-audience/blended-reach) | Denominator — unique users reached | | [Blended CTR](/reference/metrics/advertising/blended/blended-clicks/blended-ctr) | Impression-based CTR alternative | [See all Blended Clicks metrics →](/reference/metrics/advertising/blended/blended-clicks) # Blended Clicks: Aggregated Click Performance Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-clicks/index Track click performance metrics across all ad platforms. Includes Blended Clicks, Blended CPC, Blended CTR, and landing page view metrics. Click metrics measure user engagement with ads across all connected platforms—total clicks, click-through rates, and costs per click. **Data Source:** Meta Ads, Google Ads, TikTok Ads (aggregated)\ **Metrics:** 18 ## Metrics in This Group | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- | ------------------------------- | | [Blended Total Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-clicks) | Number of clicks on ads across all channels | Measure total click volume | | [Blended CPC](/reference/metrics/advertising/blended/blended-clicks/blended-cpc) | Cost per click across all channels | Evaluate click cost efficiency | | [Blended CTR](/reference/metrics/advertising/blended/blended-clicks/blended-ctr) | Click-through rate across all channels | Compare creative performance | | [Blended Unique Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-unique-clicks) | Unique people who clicked across all channels | Count distinct clickers | | [Blended Unique Click CTR](/reference/metrics/advertising/blended/blended-clicks/blended-unique-click-ctr) | Unique click-through rate | Filter out repeat clicks | | [Blended Cost per Unique Click](/reference/metrics/advertising/blended/blended-clicks/blended-cost-per-unique-click) | Cost per unique click | Cost to engage new clickers | | [Blended Inline Link Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-inline-link-clicks) | Inline link clicks across all channels | Measure in-ad link engagement | | [Blended Inline CTR](/reference/metrics/advertising/blended/blended-clicks/blended-inline-ctr) | Inline link click-through rate | Evaluate in-ad link performance | | [Blended Cost per Inline Link Click](/reference/metrics/advertising/blended/blended-clicks/blended-cost-per-inline-link-click) | Cost per inline link click | Cost for in-ad links | | [Blended Outbound Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-outbound-clicks) | Clicks leading off-platform | Measure external traffic | | [Blended Outbound Click CTR](/reference/metrics/advertising/blended/blended-clicks/blended-outbound-click-ctr) | Outbound click-through rate | Evaluate outbound performance | | [Blended Cost per Outbound Click](/reference/metrics/advertising/blended/blended-clicks/blended-cost-per-outbound-click) | Cost per outbound click | Cost for external traffic | | [Blended Link Clicks](/reference/metrics/advertising/blended/blended-clicks/blended-link-clicks) | Link clicks across all channels | Measure link engagement | | [Blended Link Click CTR](/reference/metrics/advertising/blended/blended-clicks/blended-link-click-ctr) | Link click-through rate | Evaluate link performance | | [Blended Cost per Link Click](/reference/metrics/advertising/blended/blended-clicks/blended-cost-per-link-click) | Cost per link click | Cost per link engagement | | [Blended Landing Page Views](/reference/metrics/advertising/blended/blended-clicks/blended-landing-page-views) | Landing page views from ads | Measure site visits | | [Blended Cost per LP View](/reference/metrics/advertising/blended/blended-clicks/blended-cost-per-landing-page-view) | Cost per landing page view | Cost per site visit | | [Blended LP View Rate](/reference/metrics/advertising/blended/blended-clicks/blended-landing-page-view-rate) | Landing page view rate | Click-to-visit conversion | ## How These Metrics Relate Click metrics progress from raw clicks to qualified site visits: * **Total Clicks** includes all interactions * **Unique Clicks** filters to distinct people * **Link Clicks** focuses on destination-driving clicks * **Landing Page Views** confirms the page actually loaded CTR metrics = Clicks ÷ Impressions × 100 Cost metrics = Spend ÷ Clicks ## Choosing the Right Metric * **Traffic campaigns**: Focus on Link Clicks and Landing Page Views * **Engagement analysis**: Use Total Clicks and CTR * **Cost efficiency**: Compare CPC across campaigns * **Quality assessment**: Landing Page View Rate shows click-to-visit conversion # Blended Add to Carts: Cross-Platform Shopping Intent Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-add-to-carts Track add-to-cart events attributed to your ads across Meta, Google, and TikTok. Measure shopping intent driven by cross-platform advertising. Blended Add to Carts measures the total number of add-to-cart events attributed to your ads across all connected advertising platforms. ## Formula **Blended Add to Carts** = **SUM** ( Add to Cart Events ) **ACROSS** All Channels ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | [**Meta Add to Carts**](/reference/metrics/advertising/meta/meta-conversions/meta-add-to-carts) | Add-to-cart events attributed to Meta Ads campaigns | | [**Google Add to Carts**](/reference/metrics/advertising/google/google-conversions/google-add-to-carts) | Add-to-cart events attributed to Google Ads campaigns | | [**TikTok Add to Carts**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-carts) | Add-to-cart events attributed to TikTok Ads campaigns | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example A DTC brand running campaigns across three platforms sees **2,847 add to carts** for the week: | Platform | Add to Carts | % of Total | | ----------------- | ------------ | ---------- | | Meta Ads | 1,523 | 53.5% | | Google Ads | 892 | 31.3% | | TikTok Ads | 432 | 15.2% | | **Blended Total** | **2,847** | **100%** | *** ## How It Works Blended Add to Carts aggregates add-to-cart conversion events reported by each advertising platform. When a user clicks an ad and adds a product to their cart within the attribution window, that platform counts the event. This metric sums those events across all connected platforms for a unified view. *** ## When to Use | Scenario | Action | | ---------------------------------------- | --------------------------------------------- | | Measuring cross-platform shopping intent | Compare blended add to carts to total traffic | | Evaluating funnel health | Track ratio of add to carts to checkouts | | Optimizing for consideration | Use to measure mid-funnel ad effectiveness | | Budgeting across platforms | Identify which platforms drive cart activity | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | [Blended View Contents](/reference/metrics/advertising/blended/blended-conversions/blended-view-contents) | Earlier funnel stage — product page views | | [Blended Initiate Checkouts](/reference/metrics/advertising/blended/blended-conversions/blended-initiate-checkouts) | Next funnel stage — checkout starts | | [Blended Purchases](/reference/metrics/advertising/blended/blended-conversions/blended-purchases) | Final funnel stage — completed orders | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Add to Carts Value: Cross-Platform Cart Value Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-add-to-carts-value Track the total monetary value of items added to cart attributed to your ads across Meta, Google, and TikTok. Measure cross-platform cart performance. Blended Add to Carts Value measures the total monetary value of items added to cart attributed to your advertising across all connected ad platforms. ## Formula **Blended Add to Carts Value** = **SUM** ( Cart Value ) **ACROSS** All Channels ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | **Meta Add to Carts Value** | Monetary value of items added to cart from Meta ads | | **Google Add to Carts Value** | Monetary value of items added to cart from Google ads | | [**TikTok Add to Carts Value**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-carts-value) | Monetary value of items added to cart from TikTok ads | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your ads drove **\$24,500 in cart value** this week across all platforms: | Platform | Add to Carts Value | % of Total | | ----------------- | ------------------ | ---------- | | Meta Ads | \$14,200 | 58% | | Google Ads | \$7,100 | 29% | | TikTok Ads | \$3,200 | 13% | | **Blended Total** | **\$24,500** | 100% | *** ## How It Works Blended Add to Carts Value aggregates the monetary value of all add-to-cart events attributed to your advertising across Meta, Google, and TikTok. Each platform reports the value based on their own attribution windows and models. This metric helps you understand the total cart value your ads are generating before checkout. *** ## When to Use | Scenario | Action | | ---------------------------------------- | ------------------------------------------------- | | Measuring total ad-attributed cart value | Compare blended value against total ad spend | | Identifying high-value product interest | Analyze which campaigns drive highest cart values | | Forecasting potential revenue | Use cart value to predict checkout conversion | | Comparing platform performance | Break down by platform to see value contribution | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | [Blended Add to Carts](/reference/metrics/advertising/blended/blended-conversions/blended-add-to-carts) | Count of add-to-cart events; this metric shows their value | | [Blended Purchases Value](/reference/metrics/advertising/blended/blended-conversions/blended-purchases-value) | Revenue from completed purchases | | [Blended Initiate Checkouts Value](/reference/metrics/advertising/blended/blended-conversions/blended-initiate-checkouts-value) | Value of checkout starts | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Add to Wishlists: Cross-Platform Wishlist Intent Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-add-to-wishlists Track wishlist additions attributed to your ads across Meta, Google, and TikTok. Measure consideration intent and optimize cross-platform campaigns. Blended Add to Wishlists measures the total number of wishlist additions attributed to your ads across all connected advertising platforms. ## Formula **Blended Add to Wishlists** = **SUM** ( Wishlist Events ) **ACROSS** All Channels ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | **Meta Add to Wishlists** | Wishlist additions attributed to Meta Ads campaigns | | **Google Add to Wishlists** | Wishlist additions attributed to Google Ads campaigns | | [**TikTok Add to Wishlists**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-wishlists) | Wishlist additions attributed to TikTok Ads campaigns | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example A fashion brand running campaigns across three platforms sees **1,847 wishlist additions** for the week: | Platform | Wishlists | % of Total | | ----------------- | --------- | ---------- | | Meta Ads | 1,024 | 55.4% | | Google Ads | 512 | 27.7% | | TikTok Ads | 311 | 16.9% | | **Blended Total** | **1,847** | **100%** | *** ## How It Works Blended Add to Wishlists aggregates wishlist addition events reported by each advertising platform. When a user clicks or views an ad and then adds a product to their wishlist within the attribution window, that platform counts the event. This metric sums those events across all connected platforms for a unified view of consideration intent. *** ## When to Use | Scenario | Action | | ------------------------------- | --------------------------------------------------- | | Measuring consideration intent | Track users who save products for later purchase | | Comparing platform performance | See which channels drive the most wishlist activity | | Optimizing mid-funnel campaigns | Identify ads that generate high-intent engagement | | Forecasting future purchases | Wishlist users often convert within 30 days | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------- | ------------------------------------ | | [Blended View Contents](/reference/metrics/advertising/blended/blended-conversions/blended-view-contents) | Previous funnel step before wishlist | | [Blended Add to Carts](/reference/metrics/advertising/blended/blended-conversions/blended-add-to-carts) | Next funnel step after wishlist | | [Blended Purchases](/reference/metrics/advertising/blended/blended-conversions/blended-purchases) | Final conversion from wishlist users | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended All Conversions: Total Conversions Across Platforms Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-all-conversions Track total conversions across Meta, Google, and TikTok Ads. Measure aggregate conversion volume including purchases, leads, and registrations. Blended All Conversions measures the total count of all conversions attributed to your advertising across Meta, Google, and TikTok combined. ## Formula **Blended All Conversions** = **SUM** ( Conversions ) **ACROSS** Meta + Google + TikTok ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | [**Meta Conversions**](/reference/metrics/advertising/meta/meta-conversions) | Conversions attributed to Meta Ads campaigns | | [**Google All Conversions**](/reference/metrics/advertising/google/google-conversions/google-all-conversions) | Conversions attributed to Google Ads campaigns | | [**TikTok Conversions**](/reference/metrics/advertising/tiktok/tiktok-conversions) | Conversions attributed to TikTok Ads campaigns | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your advertising drove **2,847 total conversions** across all platforms in March. | Platform | Conversions | % of Total | | ----------------- | ----------- | ---------- | | Meta | 1,423 | 50.0% | | Google | 987 | 34.7% | | TikTok | 437 | 15.3% | | **Blended Total** | **2,847** | **100%** | *** ## How It Works Blended All Conversions aggregates the total conversion count from each advertising platform into a single metric. Each platform reports conversions based on their own attribution models—purchases, leads, registrations, sign-ups, and other configured goals. The blended total gives you a unified view of ad-driven actions without manual aggregation. *** ## When to Use | Scenario | Action | | --------------------------------- | ------------------------------------------------------------------ | | Measuring total ad-driven actions | Track blended conversions to see aggregate volume | | Comparing platform contribution | Break down by platform to see conversion distribution | | Calculating overall CPA | Divide total spend by blended conversions for true cost per action | | Executive reporting | Present unified conversion count across all paid channels | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | [Blended All Conversions Value](/reference/metrics/advertising/blended/blended-conversions/blended-all-conversions-value) | Total monetary value of these conversions | | [Blended CPA](/reference/metrics/advertising/blended/blended-efficiency/blended-cpa) | Blended Spend ÷ Blended All Conversions | | [Blended Purchases](/reference/metrics/advertising/blended/blended-conversions/blended-purchases) | Subset counting only purchase conversions | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended All Conversions Value: Total Revenue Across Platforms Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-all-conversions-value Track total conversion value across Meta, Google, and TikTok Ads. Measure aggregate revenue attributed to advertising across all platforms. Blended All Conversions Value measures the total monetary value of all conversions attributed to your advertising across Meta, Google, and TikTok combined. ## Formula **Blended All Conversions Value** = **SUM** ( Conversion Value ) **ACROSS** Meta + Google + TikTok ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | [**Meta All Conversions Value**](/reference/metrics/advertising/meta/meta-conversions/meta-all-conversions-value) | Total value of conversions attributed to Meta Ads | | [**Google Conversions Value**](/reference/metrics/advertising/google/google-conversions/google-conversions-value) | Total value of conversions attributed to Google Ads | | [**TikTok Conversions Value**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-conversions-value) | Total value of conversions attributed to TikTok Ads | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your store's advertising generated **\$87,500** in total conversion value last month across all platforms. | Platform | Conversions Value | % of Total | | ----------------- | ----------------- | ---------- | | Meta | \$52,000 | 59.4% | | Google | \$28,500 | 32.6% | | TikTok | \$7,000 | 8.0% | | **Blended Total** | **\$87,500** | **100%** | *** ## How It Works Blended All Conversions Value aggregates the conversion values reported by each advertising platform into a single metric. Each platform reports the monetary value of conversions based on their own attribution models and tracking. The blended total gives you a unified view of revenue attributed to paid advertising without manual aggregation. *** ## When to Use | Scenario | Action | | ----------------------------------- | ---------------------------------------------------------- | | Measuring total advertising revenue | Track blended value to understand aggregate performance | | Comparing platform contribution | Break down by platform to see revenue distribution | | Setting advertising budgets | Use blended value to determine total ad-attributed revenue | | Executive reporting | Present unified conversion value across all paid channels | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total cost across platforms — compare to conversion value for efficiency | | [Blended ROAS](/reference/metrics/advertising/blended/blended-efficiency/blended-roas) | Blended All Conversions Value ÷ Blended Spend | | [Blended All Conversions](/reference/metrics/advertising/blended/blended-conversions/blended-all-conversions) | Total number of conversions (not value) | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended App Installs: Cross-Platform Mobile Downloads Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-app-installs Track total mobile app installs attributed to your ads across Meta, Google, and TikTok. Measure app acquisition performance. Blended App Installs measures the total number of mobile app downloads attributed to your advertising across all connected platforms. ## Formula **Blended App Installs** = **SUM** ( App Install Events ) **ACROSS** All Channels ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | [**Meta App Installs**](/reference/metrics/advertising/meta/meta-conversions/meta-app-installs) | App installs attributed to Meta Ads campaigns | | [**Google App Installs**](/reference/metrics/advertising/google/google-conversions/google-app-installs) | App installs attributed to Google Ads campaigns | | [**TikTok App Installs**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-app-installs) | App installs attributed to TikTok Ads campaigns | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your app campaign drove **2,847 installs** in March across platforms: | Platform | App Installs | Share | | ----------------- | ------------ | ----- | | Meta Ads | 1,423 | 50% | | Google Ads | 998 | 35% | | TikTok Ads | 426 | 15% | | **Blended Total** | **2,847** | 100% | With a total ad spend of **\$14,235**, your blended cost per install is **\$5.00**. *** ## How It Works App installs are counted when a user downloads your mobile app after clicking or viewing an ad. Each platform reports installs based on their attribution window—typically 7 days for click-through and 1 day for view-through. Blended App Installs aggregates these counts to show total acquisition volume across your entire paid media mix. *** ## When to Use | Scenario | Action | | ----------------------------------- | ---------------------------------------------------------- | | Measuring app acquisition campaigns | Track total installs across all platforms | | Comparing platform efficiency | Pair with cost per app install to find lowest cost channel | | Forecasting growth | Use install trends to project user acquisition | | Budget allocation | Shift spend toward platforms driving more installs | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | [Blended Cost per App Install](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-app-install) | Cost efficiency for each app download | | [Blended Completed Registrations](/reference/metrics/advertising/blended/blended-conversions/blended-completed-registrations) | In-app signups after install | | [Blended Leads](/reference/metrics/advertising/blended/blended-conversions/blended-leads) | Lead generation conversions | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Application Submissions: Applications Across All Platforms Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-application-submissions Track application form submissions across Meta, Google, and TikTok Ads. Measure job applications, loan applications, and other application events attributed to ads. Blended Application Submissions measures the total count of application form completions attributed to your advertising across Meta, Google, and TikTok combined. ## Formula **Blended Application Submissions** = **SUM** ( Application Events ) **ACROSS** All Channels ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | [**Meta Application Submissions**](/reference/metrics/advertising/meta/meta-conversions/meta-application-submissions) | Application events attributed to Meta Ads campaigns | | [**Google Application Submissions**](/reference/metrics/advertising/google/google-conversions/google-application-submissions) | Application events attributed to Google Ads campaigns | | [**TikTok Application Submissions**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-application-submissions) | Application events attributed to TikTok Ads campaigns | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your campaigns drove **1,247 total application submissions** across all platforms in February. | Platform | Applications | % of Total | | ----------------- | ------------ | ---------- | | Meta | 623 | 50.0% | | Google | 437 | 35.0% | | TikTok | 187 | 15.0% | | **Blended Total** | **1,247** | **100%** | *** ## How It Works Blended Application Submissions aggregates application form completion events from each advertising platform into a single metric. Application events include job applications, loan applications, insurance quote requests, college applications, and other form submissions configured as application goals. Each platform attributes applications based on their own attribution windows and models. *** ## When to Use | Scenario | Action | | -------------------------------- | ------------------------------------------------------- | | Measuring lead generation volume | Track blended applications for total applicant pipeline | | Comparing platform effectiveness | Break down by platform to optimize budget allocation | | Calculating cost per application | Divide total spend by blended applications for true CPA | | Recruitment or lending campaigns | Monitor application flow across all paid channels | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | [Blended All Conversions](/reference/metrics/advertising/blended/blended-conversions/blended-all-conversions) | Broader metric including all conversion types | | [Blended CPA](/reference/metrics/advertising/blended/blended-efficiency/blended-cpa) | Blended Spend ÷ Blended All Conversions | | [Blended Leads](/reference/metrics/advertising/blended/blended-conversions/blended-leads) | Related lead generation metric across platforms | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Appointments Scheduled: Aggregated Booking Conversions Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-appointments-scheduled Track appointments scheduled across Meta, Google, and TikTok ads. View aggregated booking conversions attributed to your advertising campaigns. Blended Appointments Scheduled measures the total number of appointment or booking events attributed to your ads across all connected advertising platforms. ## Formula **Blended Appointments Scheduled** = **SUM** ( Appointment Events ) **ACROSS** All Channels ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | [**Meta Appointments Scheduled**](/reference/metrics/advertising/meta/meta-conversions/meta-appointments-scheduled) | Appointments from Meta Ads campaigns | | [**Google Appointments Scheduled**](/reference/metrics/advertising/google/google-conversions/google-appointments-scheduled) | Appointments from Google Ads campaigns | | [**TikTok Appointments Scheduled**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-appointments-scheduled) | Appointments from TikTok Ads campaigns | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your campaigns drove **847 appointments** scheduled this month: | Platform | Appointments | % of Total | | ----------- | ------------ | ---------- | | Meta Ads | 423 | 50% | | Google Ads | 296 | 35% | | TikTok Ads | 128 | 15% | | **Blended** | **847** | **100%** | *** ## How It Works Blended Appointments Scheduled counts every appointment booking event attributed to your advertising across Meta, Google, and TikTok. Each platform's conversion tracking captures scheduling events, which are then aggregated into this single metric for a unified view of booking performance. *** ## When to Use | Scenario | Action | | -------------------------------- | -------------------------------------------------- | | Measuring lead gen performance | Track booking volume across all ad platforms | | Comparing channel efficiency | Identify which platform drives the most bookings | | Calculating cost per appointment | Divide total spend by appointments scheduled | | Optimizing campaign targeting | Allocate budget toward highest-converting channels | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | [Blended Leads](/reference/metrics/advertising/blended/blended-conversions/blended-leads) | Broader lead metric that includes appointments | | [Blended Completed Registrations](/reference/metrics/advertising/blended/blended-conversions/blended-completed-registrations) | Related conversion event for signups | | [Blended CPA](/reference/metrics/advertising/blended/blended-efficiency/blended-cpa) | Cost per acquisition for these conversions | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Completed Registrations: Cross-Channel Registration Tracking Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-completed-registrations Track completed registrations from advertising across Meta, Google, and TikTok. Monitor cross-channel account signup performance. Blended Completed Registrations measures the total number of registration completions attributed to your ads across all connected advertising platforms. ## Formula **Blended Completed Registrations** = **SUM** ( Registration Events ) **ACROSS** All Channels ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [**Meta Completed Registrations**](/reference/metrics/advertising/meta/meta-conversions/meta-completed-registrations) | Registrations attributed to Meta Ads campaigns | | [**Google Completed Registrations**](/reference/metrics/advertising/google/google-conversions/google-completed-registrations) | Registrations attributed to Google Ads campaigns | | [**TikTok Completed Registrations**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-completed-registrations) | Registrations attributed to TikTok Ads campaigns | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your campaigns generated **1,247 completed registrations** across all channels last month: | Channel | Registrations | Share | | ----------- | ------------- | -------- | | Meta Ads | 623 | 50% | | Google Ads | 412 | 33% | | TikTok Ads | 212 | 17% | | **Blended** | **1,247** | **100%** | *** ## How It Works Blended Completed Registrations aggregates registration completion events reported by each connected advertising platform. When a user completes an account registration that's attributed to an ad, each platform reports it as a completed registration. This metric sums those registrations across Meta, Google, and TikTok to give you a unified view of account signup performance. *** ## When to Use | Scenario | Action | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Measuring total signups | Track overall registration volume across all paid channels | | Comparing channel efficiency | Pair with [Blended Cost per Completed Registration](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-completed-registration) to see cost per registration | | Budget allocation | Identify which platforms drive the most account signups | | Lead-to-registration tracking | Compare [Blended Leads](/reference/metrics/advertising/blended/blended-conversions/blended-leads) to registrations for funnel insights | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [Blended Cost per Completed Registration](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-completed-registration) | Cost efficiency of acquiring registrations | | [Blended Leads](/reference/metrics/advertising/blended/blended-conversions/blended-leads) | Earlier funnel stage — leads before registration | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total ad spend driving these registrations | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Cost per Add to Cart: Cross-Platform ATC Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-add-to-cart Track your blended cost per add to cart across Meta, Google, and TikTok ads. Measure cross-platform efficiency for cart actions. Blended Cost per Add to Cart measures how much you spend across all ad platforms to generate one add-to-cart event. ## Formula **Blended Cost per Add to Cart** = [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) ÷ [**Blended Add to Carts**](/reference/metrics/advertising/blended/blended-conversions/blended-add-to-carts) ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total advertising spend across all connected ad platforms | | [**Blended Add to Carts**](/reference/metrics/advertising/blended/blended-conversions/blended-add-to-carts) | Total add-to-cart events attributed across all ad platforms | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your store spent **\$15,000** across all ad platforms last month and generated **3,000** add-to-cart events. | Metric | Value | | -------------------------------- | ---------- | | Blended Spend | \$15,000 | | Blended Add to Carts | 3,000 | | **Blended Cost per Add to Cart** | **\$5.00** | *** ## How It Works Blended Cost per Add to Cart divides your total advertising spend across Meta, Google, and TikTok by the total add-to-cart events attributed to those platforms. This gives you a unified view of how efficiently your combined ad spend drives cart actions, regardless of which platform generated them. *** ## When to Use | Scenario | Action | | --------------------------- | ---------------------------------------------------------------------------------------- | | Budget allocation | Compare blended cost per ATC against platform-specific costs to identify efficiency gaps | | Funnel optimization | Track how cost per cart action changes relative to cost per purchase | | Campaign scaling | Monitor if increased spend maintains efficient cost per cart action | | Cross-platform benchmarking | Evaluate overall ad efficiency without platform-specific bias | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator — total ad spend across platforms | | [Blended Add to Carts](/reference/metrics/advertising/blended/blended-conversions/blended-add-to-carts) | Denominator — total cart events across platforms | | [Blended Cost per Purchase](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-purchase) | Downstream efficiency — cost to convert cart to purchase | | [Blended ROAS](/reference/metrics/advertising/blended/blended-efficiency/blended-roas) | Revenue efficiency — return on combined ad spend | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Cost per App Install: Cross-Platform Acquisition Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-app-install Track your blended cost per app install (CPI) across Meta, Google, and TikTok. Measure mobile acquisition efficiency and optimize your app install campaigns. Blended Cost per App Install measures the average cost to acquire one mobile app install across all your advertising platforms combined. ## Formula **Blended Cost per App Install** = [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) ÷ [**Blended App Installs**](/reference/metrics/advertising/blended/blended-conversions/blended-app-installs) ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total advertising spend across Meta, Google, and TikTok combined | | [**Blended App Installs**](/reference/metrics/advertising/blended/blended-conversions/blended-app-installs) | Total app installs attributed across all advertising platforms | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your app campaigns spent **\$15,000** across all platforms and generated **3,000 installs** in March. | Platform | Spend | App Installs | CPI | | ----------- | ------------ | ------------ | ---------- | | Meta Ads | \$8,000 | 1,800 | \$4.44 | | Google Ads | \$5,000 | 900 | \$5.56 | | TikTok Ads | \$2,000 | 300 | \$6.67 | | **Blended** | **\$15,000** | **3,000** | **\$5.00** | *** ## How It Works Blended CPI aggregates your total advertising spend and total app installs across Meta, Google, and TikTok, then calculates the average cost per install. This gives you a single efficiency metric that accounts for your entire mobile acquisition budget regardless of which platform drove the install. *** ## When to Use | Scenario | Action | | -------------------------------- | ------------------------------------------------------------------------------- | | Setting acquisition budgets | Use blended CPI to establish target cost thresholds for mobile campaigns | | Comparing to industry benchmarks | Compare your overall CPI against category averages without platform bias | | Executive reporting | Report a single efficiency metric that represents total mobile acquisition cost | | Evaluating media mix | Identify if shifting budget between platforms would lower overall CPI | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator — total cost driving app installs | | [Blended App Installs](/reference/metrics/advertising/blended/blended-conversions/blended-app-installs) | Denominator — total installs acquired | | [Blended CPA](/reference/metrics/advertising/blended/blended-efficiency/blended-cpa) | Similar efficiency metric for all conversions | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Cost per Completed Registration: Aggregate Registration Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-completed-registration Track your cost per completed registration across Meta, Google, and TikTok ads combined. Calculate aggregate CPR to optimize signup acquisition efficiency. The average cost to acquire one completed account registration across all connected advertising platforms. ## Formula **Blended Cost per Completed Registration** = [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) ÷ [**Blended Completed Registrations**](/reference/metrics/advertising/blended/blended-conversions/blended-completed-registrations) ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total ad spend across Meta, Google, and TikTok | | [**Blended Completed Registrations**](/reference/metrics/advertising/blended/blended-conversions/blended-completed-registrations) | Total registration completions attributed to your ads | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your registration campaigns spent **\$8,000** and captured 400 completed registrations this month: | Platform | Spend | Registrations | Cost per Reg | | ----------- | ----------- | ------------- | ------------ | | Meta Ads | \$4,000 | 200 | \$20.00 | | Google Ads | \$2,500 | 125 | \$20.00 | | TikTok Ads | \$1,500 | 75 | \$20.00 | | **Blended** | **\$8,000** | **400** | **\$20.00** | *** ## How It Works Blended Cost per Completed Registration aggregates total ad spend and registration completions across all connected platforms, then calculates the combined cost per registration. This gives you a single efficiency metric for your entire registration program regardless of which platforms you use. *** ## When to Use | Scenario | Action | | ---------------------------- | -------------------------------------------------------------------- | | Setting registration targets | Determine sustainable cost per registration based on customer LTV | | Budget planning | Forecast registration volume based on available spend | | Comparing periods | Track cost per registration trends month-over-month | | Optimizing funnel | Reduce cost per registration by improving targeting or landing pages | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator in the formula | | [Blended Completed Registrations](/reference/metrics/advertising/blended/blended-conversions/blended-completed-registrations) | Denominator in the formula | | [Blended CPA](/reference/metrics/advertising/blended/blended-efficiency/blended-cpa) | Cost per acquisition (all conversions, not just registrations) | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Cost per Initiate Checkout: Acquisition Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-initiate-checkout Track your blended cost per checkout initiation across all ad platforms. Compare acquisition efficiency and optimize ad spend for checkout conversions. Blended Cost per Initiate Checkout measures how much you spend across all ad platforms to generate one checkout initiation. ## Formula **Blended Cost per Initiate Checkout** = [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) ÷ [**Blended Initiate Checkouts**](/reference/metrics/advertising/blended/blended-conversions/blended-initiate-checkouts) ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total ad spend aggregated across all connected platforms | | [**Blended Initiate Checkouts**](/reference/metrics/advertising/blended/blended-conversions/blended-initiate-checkouts) | Total checkout initiations attributed to ads across all platforms | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your campaigns spent **\$2,400** across all platforms and generated **800** checkout initiations. | Metric | Value | Calculation | | -------------------------------------- | ---------- | -------------------- | | Blended Spend | \$2,400 | Sum across platforms | | Blended Initiate Checkouts | 800 | Attributed checkouts | | **Blended Cost per Initiate Checkout** | **\$3.00** | \$2,400 ÷ 800 | *** ## How It Works This metric divides your total ad spend across Meta, Google, and TikTok by the number of checkout initiations attributed to those ads. It provides a unified view of acquisition costs regardless of which platform drove the conversion. *** ## When to Use | Scenario | Action | | ---------------------------------------- | ------------------------------------------------------- | | Comparing overall acquisition efficiency | Benchmark against Blended CPA to assess funnel drop-off | | Setting budget allocation targets | Use as a cost ceiling for checkout-focused campaigns | | Evaluating funnel optimization impact | Track changes after checkout UX improvements | | Measuring cross-platform performance | Compare to platform-specific costs to identify outliers | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator in calculation | | [Blended Initiate Checkouts](/reference/metrics/advertising/blended/blended-conversions/blended-initiate-checkouts) | Denominator in calculation | | [Blended CPA](/reference/metrics/advertising/blended/blended-efficiency/blended-cpa) | Compare checkout cost vs purchase cost | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Cost per Lead: Cross-Platform Lead Acquisition Cost Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-lead Track your blended cost per lead across Meta, Google, and TikTok ads. Measure lead acquisition efficiency with unified CPL metrics. Blended Cost per Lead measures how much you spend on average to acquire a single lead across all advertising platforms combined. ## Formula **Blended Cost per Lead** = [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) ÷ [**Blended Leads**](/reference/metrics/advertising/blended/blended-conversions/blended-leads) ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total advertising spend across all connected ad platforms | | [**Blended Leads**](/reference/metrics/advertising/blended/blended-conversions/blended-leads) | Total lead conversions attributed across all ad platforms | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your business spent **\$5,000** across all ad platforms last month and generated **250 leads**. | Metric | Value | | ------------------------- | ----------- | | Blended Spend | \$5,000 | | Blended Leads | 250 | | **Blended Cost per Lead** | **\$20.00** | At **\$20 per lead**, you can evaluate whether your cross-platform lead generation strategy is cost-effective compared to industry benchmarks or your target acquisition costs. *** ## How It Works Blended Cost per Lead aggregates total advertising spend from Meta, Google, and TikTok, then divides by the total number of leads attributed to those platforms. This provides a unified view of lead acquisition efficiency without platform-specific silos. *** ## When to Use | Scenario | Action | | --------------------------------------------- | --------------------------------------------------------------- | | Evaluating overall lead generation efficiency | Compare blended CPL against your target cost per lead | | Budget planning for lead campaigns | Use blended CPL to forecast spend needed for lead volume goals | | Benchmarking against industry standards | Compare your blended CPL to industry averages | | Identifying efficiency trends | Track blended CPL over time to spot improvements or degradation | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator — total ad spend across platforms | | [Blended Leads](/reference/metrics/advertising/blended/blended-conversions/blended-leads) | Denominator — total leads across platforms | | [Blended Cost per Acquisition](/reference/metrics/advertising/blended/blended-conversions/blended-cpa) | Similar efficiency metric for purchases instead of leads | | [Blended ROAS](/reference/metrics/advertising/blended/blended-efficiency/blended-roas) | Revenue efficiency metric for overall ad performance | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Cost per Search: Cross-Platform Search Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-search Track your blended cost per search event across Meta, Google, and TikTok ads. Measure cross-platform efficiency for on-site search actions. Blended Cost per Search measures how much you spend across all ad platforms to generate one on-site search event. ## Formula **Blended Cost per Search** = [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) ÷ [**Blended Searches**](/reference/metrics/advertising/blended/blended-conversions/blended-searches) ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total advertising spend across all connected ad platforms | | [**Blended Searches**](/reference/metrics/advertising/blended/blended-conversions/blended-searches) | Total on-site search events attributed across all ad platforms | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your store spent **\$5,000** across all ad platforms last week and generated **2,500** on-site search events. | Metric | Value | | --------------------------- | ---------- | | Blended Spend | \$5,000 | | Blended Searches | 2,500 | | **Blended Cost per Search** | **\$2.00** | *** ## How It Works Blended Cost per Search divides your total advertising spend across Meta, Google, and TikTok by the total on-site search events attributed to those platforms. This gives you a unified view of how efficiently your combined ad spend drives product discovery behavior, regardless of which platform generated the search. *** ## When to Use | Scenario | Action | | ----------------------- | ------------------------------------------------------------------------------------------- | | Budget allocation | Compare blended cost per search against platform-specific costs to identify efficiency gaps | | Funnel optimization | Track how cost per search changes relative to cost per add-to-cart or purchase | | Campaign scaling | Monitor if increased spend maintains efficient cost per search event | | Landing page evaluation | High cost per search may indicate visitors are struggling to find products | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator — total ad spend across platforms | | [Blended Searches](/reference/metrics/advertising/blended/blended-conversions/blended-searches) | Denominator — total search events across platforms | | [Blended Cost per View Content](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-view-content) | Downstream efficiency — cost to drive product page views | | [Blended CPA](/reference/metrics/advertising/blended/blended-efficiency/blended-cpa) | Conversion efficiency — cost per attributed conversion | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Cost per Subscription: Ad Efficiency Metric Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-subscription Track cost per subscription sign-up across Meta, Google, and TikTok ads. Measure blended acquisition efficiency for subscription-based products. Blended Cost per Subscription measures how much you spend across all ad platforms to acquire one subscription sign-up. ## Formula **Blended Cost per Subscription** = [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) ÷ [**Blended Subscriptions**](/reference/metrics/advertising/blended/blended-conversions/blended-subscriptions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total advertising spend aggregated across all connected ad platforms | | [**Blended Subscriptions**](/reference/metrics/advertising/blended/blended-conversions/blended-subscriptions) | Subscription sign-ups attributed to ads across Meta, Google, and TikTok | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example A subscription brand spent **\$4,500** across all ad platforms and acquired **150 subscriptions**: | Metric | Value | | ------------------------- | ----------- | | Total Spend | \$4,500 | | Subscriptions | 150 | | **Cost per Subscription** | **\$30.00** | *** ## How It Works This metric divides your total advertising spend across Meta, Google, and TikTok by the number of subscription sign-ups attributed to those ads. Lower values indicate more efficient subscriber acquisition. Data syncs daily from each platform's reporting API. *** ## When to Use | Scenario | Action | | ------------------------------ | ------------------------------------------------------ | | Setting acquisition targets | Establish benchmark cost per new subscription | | Comparing platforms | Identify which platforms acquire subscribers cheapest | | Budget allocation | Shift spend toward lower-cost subscription channels | | Evaluating campaign efficiency | Compare cost per subscription across creative variants | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------- | ------------------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator — total advertising cost | | [Blended Subscriptions](/reference/metrics/advertising/blended/blended-conversions/blended-subscriptions) | Denominator — subscription sign-ups | | [Blended CPA](/reference/metrics/advertising/blended/blended-efficiency/blended-cpa) | All-conversion cost efficiency metric | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Cost per Trial Start: Acquisition Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-trial-start Measure your cost per free trial start across all ad platforms. Track trial acquisition efficiency to optimize spend and lower customer acquisition costs. Blended Cost per Trial Start measures how much you spend on advertising to generate one free trial signup across all your ad platforms. ## Formula **Blended Cost per Trial Start** = [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) ÷ [**Blended Trial Starts**](/reference/metrics/advertising/blended/blended-conversions/blended-trial-starts) ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total advertising spend across all platforms | | [**Blended Trial Starts**](/reference/metrics/advertising/blended/blended-conversions/blended-trial-starts) | Free trial signups attributed to your ads | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your SaaS company spent **\$5,000** on ads last month and generated **250 trial signups** across all platforms. | Metric | Value | | -------------------------------- | ----------- | | Blended Spend | \$5,000 | | Trial Starts | 250 | | **Blended Cost per Trial Start** | **\$20.00** | *** ## How It Works This metric divides your total advertising spend by the number of free trial signups attributed to your campaigns. It aggregates data from Meta, Google, and TikTok to give you one unified cost-per-trial figure. *** ## When to Use | Scenario | Action | | -------------------------------------- | ----------------------------------------------- | | Comparing trial acquisition efficiency | Use to benchmark cost across campaigns | | Budget allocation decisions | Shift spend to platforms with lower trial costs | | Measuring campaign optimizations | Track if changes reduce acquisition cost | | Forecasting trial volume | Estimate trials from planned ad spend | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator — total ad spend | | [Blended Trial Starts](/reference/metrics/advertising/blended/blended-conversions/blended-trial-starts) | Denominator — trial signups | | [Blended CPA](/reference/metrics/advertising/blended/blended-efficiency/blended-cpa) | Similar efficiency metric for all conversions | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Cost per View Content: Cross-Platform Content View Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-view-content Track your blended cost per view content across Meta, Google, and TikTok ads. Measure cross-platform efficiency for content view events. Blended Cost per View Content measures how much you spend across all ad platforms to generate one content view event. ## Formula **Blended Cost per View Content** = [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) ÷ [**Blended View Contents**](/reference/metrics/advertising/blended/blended-conversions/blended-view-contents) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total advertising spend across all connected ad platforms | | [**Blended View Contents**](/reference/metrics/advertising/blended/blended-conversions/blended-view-contents) | Total content view events attributed across all ad platforms | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your store spent **\$5,000** across all ad platforms last month and generated **10,000** content view events. | Metric | Value | | --------------------------------- | ---------- | | Blended Spend | \$5,000 | | Blended View Contents | 10,000 | | **Blended Cost per View Content** | **\$0.50** | *** ## How It Works Blended Cost per View Content divides your total advertising spend across Meta, Google, and TikTok by the total content view events attributed to those platforms. This gives you a unified view of how efficiently your combined ad spend drives product page visits, regardless of which platform generated them. *** ## When to Use | Scenario | Action | | --------------------------- | ------------------------------------------------------------------------------------------------- | | Budget allocation | Compare blended cost per view content against platform-specific costs to identify efficiency gaps | | Funnel optimization | Track how cost per content view changes relative to cost per add-to-cart or purchase | | Campaign scaling | Monitor if increased spend maintains efficient cost per content view | | Cross-platform benchmarking | Evaluate overall top-of-funnel efficiency without platform-specific bias | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator — total ad spend across platforms | | [Blended View Contents](/reference/metrics/advertising/blended/blended-conversions/blended-view-contents) | Denominator — total content view events across platforms | | [Blended Cost per Add to Cart](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-add-to-cart) | Downstream efficiency — cost to convert view to cart action | | [Blended ROAS](/reference/metrics/advertising/blended/blended-efficiency/blended-roas) | Revenue efficiency — return on combined ad spend | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Initiate Checkouts: Cross-Platform Checkout Intent Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-initiate-checkouts Track checkout initiations attributed to your ads across Meta, Google, and TikTok. Measure purchase intent driven by cross-platform advertising. Blended Initiate Checkouts measures the total number of checkout starts attributed to your ads across all connected advertising platforms. ## Formula **Blended Initiate Checkouts** = **SUM** ( Checkout Initiations ) **ACROSS** All Channels ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | [**Meta Initiate Checkouts**](/reference/metrics/advertising/meta/meta-conversions/meta-initiate-checkouts) | Checkout initiations attributed to Meta ads | | [**Google Initiate Checkouts**](/reference/metrics/advertising/google/google-conversions/google-initiate-checkouts) | Checkout initiations attributed to Google ads | | [**TikTok Initiate Checkouts**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-initiate-checkouts) | Checkout initiations attributed to TikTok ads | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example A DTC brand running campaigns across three platforms sees **1,892 checkout starts** for the week: | Platform | Initiate Checkouts | % of Total | | ----------------- | ------------------ | ---------- | | Meta Ads | 1,047 | 55.3% | | Google Ads | 568 | 30.0% | | TikTok Ads | 277 | 14.7% | | **Blended Total** | **1,892** | **100%** | *** ## How It Works Blended Initiate Checkouts aggregates checkout initiation events reported by each advertising platform. When a user clicks an ad and starts the checkout process within the attribution window, that platform counts the event. This metric sums those events across all connected platforms for a unified view of purchase intent. *** ## When to Use | Scenario | Action | | ---------------------------------------- | ------------------------------------------------ | | Measuring cross-platform purchase intent | Compare checkout starts to completed purchases | | Identifying checkout abandonment | Track ratio of initiates to purchases | | Optimizing for high-intent users | Use to measure bottom-funnel ad effectiveness | | Budgeting across platforms | Identify which platforms drive checkout activity | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | [Blended Add to Carts](/reference/metrics/advertising/blended/blended-conversions/blended-add-to-carts) | Earlier funnel stage — cart additions | | [Blended Purchases](/reference/metrics/advertising/blended/blended-conversions/blended-purchases) | Next funnel stage — completed orders | | [Blended Cost per Initiate Checkout](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-initiate-checkout) | Efficiency metric — spend per checkout start | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Initiate Checkouts Value: Cross-Platform Checkout Intent Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-initiate-checkouts-value Track the total monetary value at checkout initiation attributed to your ads across Meta, Google, and TikTok. Measure cross-platform checkout intent. Blended Initiate Checkouts Value measures the total monetary value of checkout initiations attributed to your advertising across all connected ad platforms. ## Formula **Blended Initiate Checkouts Value** = **SUM** ( Checkout Value ) **ACROSS** All Channels ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | **Meta Initiate Checkouts Value** | Monetary value of checkout initiations from Meta ads | | **Google Initiate Checkouts Value** | Monetary value of checkout initiations from Google ads | | [**TikTok Initiate Checkouts Value**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-initiate-checkouts-value) | Monetary value of checkout initiations from TikTok ads | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your ads drove **\$47,250 in checkout initiation value** this month across all platforms: | Platform | Initiate Checkouts Value | % of Total | | ----------------- | ------------------------ | ---------- | | Meta Ads | \$28,350 | 60% | | Google Ads | \$14,175 | 30% | | TikTok Ads | \$4,725 | 10% | | **Blended Total** | **\$47,250** | 100% | *** ## How It Works Blended Initiate Checkouts Value aggregates the cart value at checkout initiation for all conversions attributed to your advertising across Meta, Google, and TikTok. Each platform reports the value based on their own attribution windows and models. This metric represents the total potential revenue from users who started checkout after interacting with your ads. *** ## When to Use | Scenario | Action | | -------------------------- | --------------------------------------------------------------------- | | Evaluating checkout intent | Compare initiate checkout value to purchase value to measure drop-off | | Cross-platform performance | Identify which platforms drive highest-value checkout sessions | | Budget allocation | Shift spend toward platforms generating more checkout value | | Funnel optimization | Track checkout intent trends to spot conversion opportunities | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | [Blended Initiate Checkouts](/reference/metrics/advertising/blended/blended-conversions/blended-initiate-checkouts) | Count of checkout initiations; this metric shows their value | | [Blended Purchases Value](/reference/metrics/advertising/blended/blended-conversions/blended-purchases-value) | Completed purchase value (downstream conversion) | | [Blended Add to Carts Value](/reference/metrics/advertising/blended/blended-conversions/blended-add-to-carts-value) | Value at cart addition (upstream funnel step) | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Leads: Cross-Channel Lead Tracking Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-leads Track total leads generated from your advertising across Meta, Google, and TikTok. Monitor cross-channel lead generation performance. Blended Leads measures the total number of lead submission events attributed to your ads across all connected advertising platforms. ## Formula **Blended Leads** = **SUM** ( Lead Events ) **ACROSS** All Channels ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------- | ------------------------------------------------ | | [**Meta Leads**](/reference/metrics/advertising/meta/meta-conversions/meta-leads) | Lead submission events from Meta Ads campaigns | | [**Google Leads**](/reference/metrics/advertising/google/google-conversions/google-leads) | Lead submission events from Google Ads campaigns | | [**TikTok Leads**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-leads) | Lead submission events from TikTok Ads campaigns | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your campaigns generated **847 leads** across all channels last month: | Platform | Leads | % of Total | | ----------- | ------- | ---------- | | Meta Ads | 412 | 49% | | Google Ads | 298 | 35% | | TikTok Ads | 137 | 16% | | **Blended** | **847** | **100%** | *** ## How It Works Blended Leads aggregates lead conversion events reported by each connected advertising platform. When a user completes a lead action—form submission, newsletter sign-up, quote request, or contact inquiry—that's attributed to an ad, each platform reports it as a lead. This metric sums those leads across Meta, Google, and TikTok to give you a unified view of lead generation performance. *** ## When to Use | Scenario | Action | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Measuring total lead volume | Track overall lead generation across all paid channels | | Comparing channel efficiency | Pair with [Blended Cost per Lead](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-lead) to see cost per lead | | Budget allocation | Identify which platforms drive the most leads for your spend | | Funnel analysis | Compare leads to registrations for conversion rate insights | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | [Blended Cost per Lead](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-lead) | Cost efficiency metric using leads as the denominator | | [Blended Completed Registrations](/reference/metrics/advertising/blended/blended-conversions/blended-completed-registrations) | Tracks registrations that follow lead capture | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total ad spend driving these leads | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended New Customer Purchases: First-Time Buyer Conversions Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-new-customer-purchases Track purchases from first-time customers attributed to your ads across all channels. Measure new customer acquisition from Meta, Google, and TikTok advertising. Blended New Customer Purchases counts first-time buyers whose purchases are attributed to advertising across all connected ad platforms. ## Formula **Blended NC Purchases** = **COUNT** ( Purchases ) **WHERE** customer = new **AND** attributed = true ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | [**Blended Purchases**](/reference/metrics/advertising/blended/blended-conversions/blended-purchases) | Total purchase conversions attributed to ads across all platforms | | [**customer = new**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | First-time buyers with no prior order history | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Count | *** ## Example Your ads drove **847 new customer purchases** across all channels in March: | Channel | NC Purchases | % of Total | | ----------------- | ------------ | ---------- | | Meta Ads | 412 | 48.6% | | Google Ads | 298 | 35.2% | | TikTok Ads | 137 | 16.2% | | **Blended Total** | **847** | **100%** | *** ## How It Works Blended New Customer Purchases counts first-time buyers whose purchases are attributed to any advertising channel. Upstack identifies new customers by checking order history—if no prior purchase exists, the customer is flagged as new. This metric aggregates new customer conversions across Meta, Google, and TikTok into a single cross-platform view. *** ## When to Use | Scenario | Action | | ----------------------------------- | ----------------------------------------------------------------------- | | Measuring acquisition effectiveness | Compare NC purchases across channels to find best prospecting platforms | | Calculating new customer CPA | Use as denominator: Spend ÷ NC Purchases | | Evaluating campaign types | Separate prospecting vs retargeting performance | | Forecasting growth | Project new customer acquisition rates from advertising | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | | [Blended Purchases](/reference/metrics/advertising/blended/blended-conversions/blended-purchases) | Total purchases (new + returning customers) | | [Blended NC CPA](/reference/metrics/advertising/blended/blended-efficiency/blended-new-customer-cpa) | Cost to acquire each new customer | | [Blended NC ROAS](/reference/metrics/advertising/blended/blended-efficiency/blended-new-customer-roas) | Revenue efficiency from new customer purchases | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended New Customer Purchases Value: Revenue from First-Time Buyers Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-new-customer-purchases-value Track total revenue from first-time customers attributed to your ads across Meta, Google, and TikTok. Optimize acquisition spend with NC purchase value. Total monetary value from purchases made by first-time customers, attributed to your advertising across all platforms. ## Formula **Blended NC Purchases Value** = **SUM** ( Purchase Value ) **WHERE** customer = new ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | [**Purchase Value**](/reference/metrics/advertising/blended/blended-conversions/blended-purchases-value) | Revenue from all purchase conversions attributed to ads | | [**customer = new**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | First-time buyers with no prior order history | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your campaigns generated **\$32,400** from new customers this month: | Channel | NC Value | Share | | ---------- | ------------ | ----- | | Meta Ads | \$18,900 | 58% | | Google Ads | \$9,720 | 30% | | TikTok Ads | \$3,780 | 12% | | **Total** | **\$32,400** | 100% | *** ## How It Works Blended New Customer Purchases Value sums revenue from orders placed by customers making their first purchase. Upstack identifies new customers by checking order history, then aggregates attributed revenue across Meta, Google, and TikTok. *** ## When to Use | Scenario | Action | | --------------------------- | -------------------------------------------------------------- | | Measuring acquisition value | Track revenue specifically from new customer acquisition | | Calculating NC ROAS | Divide by Ad Spend to find new customer acquisition efficiency | | Channel comparison | Identify which platforms drive highest-value new customers | | Budget allocation | Shift acquisition spend toward channels with highest NC value | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | [Blended New Customer Purchases](/reference/metrics/advertising/blended/blended-conversions/blended-new-customer-purchases) | Count of NC purchases; this metric sums their values | | [Blended New Customer ROAS](/reference/metrics/advertising/blended/blended-efficiency/blended-new-customer-roas) | NC Purchases Value ÷ Ad Spend | | [Blended Purchases Value](/reference/metrics/advertising/blended/blended-conversions/blended-purchases-value) | Total purchase value including new and returning customers | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Purchases: Cross-Channel Conversion Tracking Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-purchases Track purchase conversions attributed to your advertising across all channels. Measure total cross-platform conversion volume. Blended Purchases measures the total number of purchase conversions attributed to your advertising across all connected ad platforms. ## Formula **Blended Purchases** = **SUM** ( Attributed Purchases ) **ACROSS** All Channels ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------- | --------------------------------------------- | | [**Meta Purchases**](/reference/metrics/advertising/meta/meta-conversions/meta-purchases) | Purchase conversions attributed to Meta ads | | [**Google Purchases**](/reference/metrics/advertising/google/google-conversions/google-purchases) | Purchase conversions attributed to Google ads | | [**TikTok Purchases**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases) | Purchase conversions attributed to TikTok ads | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example **Your ad campaigns drove 847 purchases across all platforms in March:** | Platform | Purchases | % of Total | | ----------------- | --------- | ---------- | | Meta Ads | 512 | 60% | | Google Ads | 268 | 32% | | TikTok Ads | 67 | 8% | | **Blended Total** | **847** | 100% | *** ## How It Works Blended Purchases aggregates purchase conversions attributed to your advertising across Meta, Google, and TikTok. Each platform reports conversions based on its own attribution model and window, then these values are summed to provide a unified cross-channel view of ad-driven conversions. *** ## When to Use | Scenario | Action | | ------------------------------------- | -------------------------------------------------- | | Measuring total ad-driven conversions | Track overall advertising effectiveness | | Comparing cross-platform performance | Identify which platforms drive more purchases | | Calculating blended CPA or ROAS | Use as the conversion count for efficiency metrics | | Budget allocation decisions | Allocate spend toward higher-converting platforms | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | [Blended Purchases Value](/reference/metrics/advertising/blended/blended-conversions/blended-purchases-value) | Revenue from these purchases | | [Blended CPA](/reference/metrics/advertising/blended/blended-efficiency/blended-cpa) | Cost per purchase (Spend ÷ Purchases) | | [Blended ROAS](/reference/metrics/advertising/blended/blended-efficiency/blended-roas) | Return on ad spend using these conversions | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Purchases Value: Total Revenue from Ad-Attributed Purchases Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-purchases-value Track the total revenue from purchase conversions attributed to your ads across Meta, Google, and TikTok. Measure your advertising revenue impact. Blended Purchases Value measures the total monetary value of purchases attributed to your advertising across all connected ad platforms. ## Formula **Blended Purchases Value** = **SUM** ( Purchase Value ) **ACROSS** All Channels ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | [**Meta Purchases Value**](/reference/metrics/advertising/meta/meta-conversions/meta-purchases-value) | Revenue from purchases attributed to Meta ads | | [**Google Purchases Value**](/reference/metrics/advertising/google/google-conversions/google-purchases-value) | Revenue from purchases attributed to Google ads | | [**TikTok Purchases Value**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases-value) | Revenue from purchases attributed to TikTok ads | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your campaigns generated **\$47,250** in attributed purchase value last month: | Platform | Purchases Value | % of Total | | ----------------- | --------------- | ---------- | | Meta Ads | \$28,500 | 60% | | Google Ads | \$14,175 | 30% | | TikTok Ads | \$4,575 | 10% | | **Blended Total** | **\$47,250** | 100% | *** ## How It Works Blended Purchases Value aggregates the total revenue from purchase conversions attributed to your ads across Meta, Google, and TikTok. Each platform reports its attributed conversion value, and Upstack combines them into a single cross-platform view. *** ## When to Use | Scenario | Action | | ------------------------------------- | ------------------------------------------------------ | | Measuring total ad-attributed revenue | Compare against total spend to calculate blended ROAS | | Budget allocation decisions | Identify which platforms drive the most purchase value | | Revenue forecasting | Project expected revenue based on planned ad spend | | Performance reporting | Show stakeholders total revenue impact of advertising | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | [Blended Purchases](/reference/metrics/advertising/blended/blended-conversions/blended-purchases) | Count of purchases; this metric shows their value | | [Blended ROAS](/reference/metrics/advertising/blended/blended-efficiency/blended-roas) | Uses this metric as the numerator | | [Blended CPA](/reference/metrics/advertising/blended/blended-efficiency/blended-cpa) | Cost efficiency; this metric shows revenue efficiency | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Searches: Cross-Platform Site Search Tracking Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-searches Track search events attributed to your ads across Meta, Google, and TikTok. Measure cross-platform site search activity driven by advertising. Blended Searches measures the total number of on-site search events attributed to your ads across all connected advertising platforms. ## Formula **Blended Searches** = **SUM** ( Search Events ) **ACROSS** All Channels ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [**Meta Search Events**](/reference/metrics/advertising/meta/meta-conversions/meta-search-events) | On-site search events attributed to Meta Ads campaigns | | [**Google Searches**](/reference/metrics/advertising/google/google-conversions/google-searches) | On-site search events attributed to Google Ads campaigns | | [**TikTok Searches**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-searches) | On-site search events attributed to TikTok Ads campaigns | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example A fashion retailer running campaigns across three platforms sees **1,892 searches** for the week: | Platform | Searches | % of Total | | ----------------- | --------- | ---------- | | Meta Ads | 1,043 | 55.1% | | Google Ads | 621 | 32.8% | | TikTok Ads | 228 | 12.1% | | **Blended Total** | **1,892** | **100%** | *** ## How It Works Blended Searches aggregates on-site search events reported by each advertising platform. When a user clicks an ad and performs a search on your website within the attribution window, that platform counts the event. This metric sums those events across all connected platforms for a unified view. *** ## When to Use | Scenario | Action | | --------------------------------- | ---------------------------------------------- | | Measuring ad-driven search intent | Track how ads drive product discovery | | Evaluating top-funnel engagement | Use searches as an early intent signal | | Optimizing landing pages | High searches may indicate unclear navigation | | Comparing platform performance | Identify which platforms drive search behavior | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | [Blended Cost per Search](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-search) | Efficiency metric showing cost to generate each search | | [Blended View Contents](/reference/metrics/advertising/blended/blended-conversions/blended-view-contents) | Next funnel stage — product page views | | [Blended Add to Carts](/reference/metrics/advertising/blended/blended-conversions/blended-add-to-carts) | Further down funnel — cart additions | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Subscriptions: Track Subscription Sign-Ups Across Platforms Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-subscriptions Track subscription sign-ups attributed to your ads across Meta, Google, and TikTok. Measure how advertising drives recurring revenue. Blended Subscriptions measures the total number of subscription sign-ups attributed to your advertising across all connected platforms. ## Formula **Blended Subscriptions** = **SUM** ( Subscription Events ) **ACROSS** All Channels ### Formula Components | Metric | Definition | | ------------------------------ | -------------------------------------------------------- | | **Meta Subscription Events** | Subscription sign-ups attributed to Meta Ads campaigns | | **Google Subscription Events** | Subscription sign-ups attributed to Google Ads campaigns | | **TikTok Subscription Events** | Subscription sign-ups attributed to TikTok Ads campaigns | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your subscription business generated **847 new subscriptions** last month across all ad platforms. | Platform | Subscriptions | Ad Spend | Cost per Subscription | | ---------- | ------------- | ------------ | --------------------- | | Meta Ads | 412 | \$6,180 | \$15.00 | | Google Ads | 298 | \$5,066 | \$17.00 | | TikTok Ads | 137 | \$2,466 | \$18.00 | | **Total** | **847** | **\$13,712** | **\$16.19** | *** ## How It Works When a user clicks or views your ad and later signs up for a subscription, that conversion is attributed to the originating ad. Blended Subscriptions aggregates these attributed sign-ups across Meta, Google, and TikTok to show your total subscription acquisition from paid advertising. *** ## When to Use | Scenario | Action | | ---------------------------------- | ------------------------------------------------------- | | Measuring subscription acquisition | Track total subscriptions driven by all ad platforms | | Comparing platform performance | See which channels drive the most subscriptions | | Forecasting recurring revenue | Multiply subscriptions by average subscription value | | Optimizing for LTV | Focus spend on platforms with highest-value subscribers | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | [Blended Trial Starts](/reference/metrics/advertising/blended/blended-conversions/blended-trial-starts) | Users who started trials before subscribing | | [Blended Purchases](/reference/metrics/advertising/blended/blended-conversions/blended-purchases) | One-time purchases vs recurring subscriptions | | [Blended Cost per Subscription](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-subscription) | Cost to acquire each subscription | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Trial Starts: Cross-Channel Trial Tracking Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-trial-starts Track free trial starts attributed to your ads across Meta, Google, and TikTok. Monitor cross-channel trial acquisition performance. Blended Trial Starts measures the total number of free trial activations attributed to your ads across all connected advertising platforms. ## Formula **Blended Trial Starts** = **SUM** ( Trial Start Events ) **ACROSS** All Channels ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | [**Meta Trial Starts**](/reference/metrics/advertising/meta/meta-conversions/meta-trial-starts) | Free trials attributed to Meta Ads campaigns | | [**Google Trial Starts**](/reference/metrics/advertising/google/google-conversions/google-trial-starts) | Free trials attributed to Google Ads campaigns | | [**TikTok Trial Starts**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-trial-starts) | Free trials attributed to TikTok Ads campaigns | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your campaigns generated **847 free trial starts** across all channels last month: | Channel | Trial Starts | Share | | ----------- | ------------ | -------- | | Meta Ads | 412 | 49% | | Google Ads | 289 | 34% | | TikTok Ads | 146 | 17% | | **Blended** | **847** | **100%** | *** ## How It Works Blended Trial Starts aggregates trial activation events reported by each connected advertising platform. When a user starts a free trial that's attributed to an ad within the platform's attribution window, each platform records a trial start event. This metric sums those events across Meta, Google, and TikTok to give you a unified view of trial acquisition performance. *** ## When to Use | Scenario | Action | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Measuring trial volume | Track overall free trial acquisition across all paid channels | | Comparing channel efficiency | Pair with [Blended Cost Per Trial Start](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-trial-start) to see cost per trial | | Budget allocation | Identify which platforms drive the most trial signups per dollar spent | | Trial-to-subscription tracking | Compare to [Blended Subscriptions](/reference/metrics/advertising/blended/blended-conversions/blended-subscriptions) for conversion insights | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [Blended Cost Per Trial Start](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-trial-start) | Cost efficiency of acquiring trials | | [Blended Subscriptions](/reference/metrics/advertising/blended/blended-conversions/blended-subscriptions) | Later funnel stage — trials that convert to paid | | [Blended Completed Registrations](/reference/metrics/advertising/blended/blended-conversions/blended-completed-registrations) | Related acquisition metric — account signups | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended View Contents: Cross-Platform Product Page Views Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-view-contents Track product page views attributed to your ads across Meta, Google, and TikTok. Measure discovery driven by cross-platform advertising. Blended View Contents measures the total number of product page views attributed to your ads across all connected advertising platforms. ## Formula **Blended View Contents** = **SUM** ( View Content Events ) **ACROSS** All Channels ### Formula Components | Metric | Definition | | ----------------------- | ---------------------------------------------------------------------------- | | **View Content Events** | Individual instances where a user viewed a product page after ad interaction | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example A fashion retailer running campaigns across three platforms sees **8,432 product page views** for the week: | Platform | View Contents | % of Total | | ----------------- | ------------- | ---------- | | Meta Ads | 4,891 | 58.0% | | Google Ads | 2,654 | 31.5% | | TikTok Ads | 887 | 10.5% | | **Blended Total** | **8,432** | **100%** | *** ## How It Works Blended View Contents aggregates product page view events reported by each advertising platform. When a user clicks an ad and views a product page within the attribution window, that platform counts the event. This metric sums those events across all connected platforms for a unified view of ad-driven product discovery. *** ## When to Use | Scenario | Action | | ------------------------------------ | ----------------------------------------------- | | Measuring product discovery | Compare view contents to site traffic | | Evaluating top-of-funnel performance | Track ratio of view contents to add to carts | | Optimizing for awareness | Use to measure which ads drive product browsing | | Budgeting across platforms | Identify which platforms drive product views | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | [Blended Add to Carts](/reference/metrics/advertising/blended/blended-conversions/blended-add-to-carts) | Next funnel stage — shopping intent | | [Blended Purchases](/reference/metrics/advertising/blended/blended-conversions/blended-purchases) | Final funnel stage — completed orders | | [Blended Landing Page Views](/reference/metrics/advertising/blended/blended-clicks/blended-landing-page-views) | Similar metric — any landing page visits | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended View Contents Value: Cross-Platform Product View Value Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-view-contents-value Track the total monetary value of products viewed from your ads across Meta, Google, and TikTok. Measure upper-funnel value engagement. Blended View Contents Value measures the total monetary value of products viewed that are attributed to your advertising across all connected ad platforms. ## Formula **Blended View Contents Value** = **SUM** ( View Content Value ) **ACROSS** All Channels ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | **Meta View Contents Value** | Monetary value of products viewed from Meta ads | | **Google View Contents Value** | Monetary value of products viewed from Google ads | | [**TikTok View Contents Value**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-view-contents-value) | Monetary value of products viewed from TikTok ads | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your ads drove **\$47,500 in viewed product value** across all platforms last week: | Platform | View Contents | Avg Product Value | View Contents Value | | ----------------- | ------------- | ----------------- | ------------------- | | Meta Ads | 2,150 | \$18.50 | \$39,775 | | Google Ads | 320 | \$22.00 | \$7,040 | | TikTok Ads | 28 | \$24.50 | \$686 | | **Blended Total** | **2,498** | **\$19.02** | **\$47,501** | *** ## How It Works When users click your ads and view product pages, each ad platform tracks the product value based on your catalog data. Blended View Contents Value aggregates these values across Meta, Google, and TikTok to show your total upper-funnel value engagement from advertising. *** ## When to Use | Scenario | Action | | --------------------------------------- | ---------------------------------------------------- | | Measuring upper-funnel value engagement | Compare view contents value to add-to-cart value | | Evaluating product discovery from ads | Track which platforms drive high-value product views | | Forecasting downstream revenue | Use as leading indicator for purchases | | Optimizing for consideration | Allocate budget to platforms driving valuable views | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | [Blended View Contents](/reference/metrics/advertising/blended/blended-conversions/blended-view-contents) | Count of views — this metric adds the value | | [Blended Add to Carts Value](/reference/metrics/advertising/blended/blended-conversions/blended-add-to-carts-value) | Next funnel stage — cart value | | [Blended Purchases Value](/reference/metrics/advertising/blended/blended-conversions/blended-purchases-value) | Final conversion value | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended View-Through Conversions: Ad View Attribution Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/blended-view-through-conversions Track conversions from users who saw but didn't click your ads across Meta, Google, and TikTok. Measure view-through attribution impact. Blended View-Through Conversions counts users who saw your ad, did not click, but converted later—aggregated across all connected ad platforms. ## Formula **Blended View-Through Conversions** = **COUNT** ( Conversions ) **WHERE** attribution = view-through ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | [**Blended All Conversions**](/reference/metrics/advertising/blended/blended-conversions/blended-all-conversions) | Total conversions attributed to advertising across all platforms | | **attribution = view-through** | Filters to conversions where the user viewed but did not click the ad before converting | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your campaigns generated **847 view-through conversions** last month across all platforms. | Platform | Impressions | VT Conversions | VT Rate | | -------- | ----------- | -------------- | ------- | | Meta | 125,000 | 412 | 0.33% | | Google | 98,000 | 287 | 0.29% | | TikTok | 67,000 | 148 | 0.22% | *** ## How It Works Each ad platform tracks when users view your ads without clicking. If those users later convert within the platform's attribution window, the conversion is credited as view-through. Upstack aggregates these counts across Meta, Google, and TikTok for a unified view. *** ## When to Use | Scenario | Action | | ---------------------------------- | ------------------------------------------------ | | Measuring brand awareness impact | Compare VT vs click-through conversion ratios | | Evaluating display/video campaigns | VT conversions indicate passive ad influence | | Attribution window analysis | Assess how ad viewing affects conversion timing | | Platform comparison | Identify which channels drive passive engagement | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [Blended All Conversions](/reference/metrics/advertising/blended/blended-conversions/blended-all-conversions) | Total conversions including click and view-through | | [Blended Purchases](/reference/metrics/advertising/blended/blended-conversions/blended-purchases) | Purchase-specific conversions across platforms | | [Blended Impressions](/reference/metrics/advertising/blended/blended-audience/blended-impressions) | Total ad views that drive VT conversions | [See all Blended Conversions metrics →](/reference/metrics/advertising/blended/blended-conversions) # Blended Conversions: Aggregated Conversion Events Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-conversions/index Track conversion events across all ad platforms. Includes purchases, add to carts, leads, registrations, and app installs with costs and values. Conversion metrics track user actions attributed to advertising across all connected platforms—from initial interest (view content) through purchase completion. **Data Source:** Meta Ads, Google Ads, TikTok Ads (aggregated)\ **Metrics:** 41 ## Metrics in This Group ### Purchase Conversions | Metric | Description | When to Use | | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | -------------------------- | | [Blended Purchases](/reference/metrics/advertising/blended/blended-conversions/blended-purchases) | Purchase events across all channels | Count total purchases | | [Blended Purchases Value](/reference/metrics/advertising/blended/blended-conversions/blended-purchases-value) | Revenue from purchases | Measure purchase revenue | | [Blended NC Purchases](/reference/metrics/advertising/blended/blended-conversions/blended-new-customer-purchases) | New customer purchases | Track customer acquisition | | [Blended NC Purchases Value](/reference/metrics/advertising/blended/blended-conversions/blended-new-customer-purchases-value) | New customer revenue | Value of new customers | ### Funnel Conversions | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ------------------------- | | [Blended View Contents](/reference/metrics/advertising/blended/blended-conversions/blended-view-contents) | Product page views | Top-of-funnel interest | | [Blended View Contents Value](/reference/metrics/advertising/blended/blended-conversions/blended-view-contents-value) | Value of viewed products | Product interest value | | [Blended Cost per View Content](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-view-content) | Cost per product view | Cost for product interest | | [Blended Add to Carts](/reference/metrics/advertising/blended/blended-conversions/blended-add-to-carts) | Add to cart events | Mid-funnel intent | | [Blended Add to Carts Value](/reference/metrics/advertising/blended/blended-conversions/blended-add-to-carts-value) | Value of carted items | Cart value | | [Blended Cost per Add to Cart](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-add-to-cart) | Cost per cart addition | Cost for cart intent | | [Blended Initiate Checkouts](/reference/metrics/advertising/blended/blended-conversions/blended-initiate-checkouts) | Checkout starts | Purchase intent | | [Blended Initiate Checkouts Value](/reference/metrics/advertising/blended/blended-conversions/blended-initiate-checkouts-value) | Value at checkout | Checkout value | | [Blended Cost per Checkout](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-initiate-checkout) | Cost per checkout start | Cost for checkout intent | ### Search and Wishlist | Metric | Description | When to Use | | --------------------------------------------------------------------------------------------------------------------------- | --------------------- | ---------------------- | | [Blended Searches](/reference/metrics/advertising/blended/blended-conversions/blended-searches) | On-site search events | Search engagement | | [Blended Searches Value](/reference/metrics/advertising/blended/blended-conversions/blended-searches-value) | Value from searches | Search value | | [Blended Cost per Search](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-search) | Cost per search | Search cost | | [Blended Add to Wishlists](/reference/metrics/advertising/blended/blended-conversions/blended-add-to-wishlists) | Wishlist additions | Future purchase intent | | [Blended Add to Wishlists Value](/reference/metrics/advertising/blended/blended-conversions/blended-add-to-wishlists-value) | Wishlist value | Saved items value | | [Blended Cost per Wishlist](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-add-to-wishlist) | Cost per wishlist add | Wishlist cost | ### Lead and Registration | Metric | Description | When to Use | | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ------------------- | | [Blended Leads](/reference/metrics/advertising/blended/blended-conversions/blended-leads) | Lead submissions | Lead generation | | [Blended Leads Value](/reference/metrics/advertising/blended/blended-conversions/blended-leads-value) | Lead value | Lead worth | | [Blended Cost per Lead](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-lead) | Cost per lead | CPL metric | | [Blended Appointments](/reference/metrics/advertising/blended/blended-conversions/blended-appointments) | Appointment bookings | Booking conversions | | [Blended Appointments Value](/reference/metrics/advertising/blended/blended-conversions/blended-appointments-value) | Appointment value | Booking value | | [Blended Cost per Appointment](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-appointment) | Cost per booking | Appointment cost | | [Blended Registrations](/reference/metrics/advertising/blended/blended-conversions/blended-complete-registrations) | Completed registrations | Account signups | | [Blended Registrations Value](/reference/metrics/advertising/blended/blended-conversions/blended-completed-registrations-value) | Registration value | Signup value | | [Blended Cost per Registration](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-complete-registration) | Cost per registration | Signup cost | ### Subscription and Trial | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------------------------------------- | --------------------- | ---------------------- | | [Blended Subscriptions](/reference/metrics/advertising/blended/blended-conversions/blended-subscriptions) | Subscription signups | Recurring revenue | | [Blended Subscriptions Value](/reference/metrics/advertising/blended/blended-conversions/blended-subscriptions-value) | Subscription value | Recurring value | | [Blended Cost per Subscription](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-subscription) | Cost per subscription | Subscription CAC | | [Blended Trial Starts](/reference/metrics/advertising/blended/blended-conversions/blended-trial-starts) | Trial activations | Trial signups | | [Blended Trial Starts Value](/reference/metrics/advertising/blended/blended-conversions/blended-trial-starts-value) | Trial value | Trial worth | | [Blended Cost per Trial](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-trial-start) | Cost per trial | Trial acquisition cost | ### App and Application | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------- | ----------------------- | | [Blended Applications](/reference/metrics/advertising/blended/blended-conversions/blended-submit-applications) | Application submissions | Application conversions | | [Blended Applications Value](/reference/metrics/advertising/blended/blended-conversions/blended-submit-applications-value) | Application value | Application worth | | [Blended Cost per Application](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-submit-application) | Cost per application | Application cost | | [Blended App Installs](/reference/metrics/advertising/blended/blended-conversions/blended-app-installs) | Mobile app installs | App acquisition | | [Blended App Installs Value](/reference/metrics/advertising/blended/blended-conversions/blended-app-installs-value) | Install value | App install value | | [Blended Cost per Install](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-app-install) | Cost per install | CPI metric | ### All Conversions | Metric | Description | When to Use | | --------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ---------------------- | | [Blended Conversions](/reference/metrics/advertising/blended/blended-conversions/blended-conversions) | Total conversions | All conversion events | | [Blended Conversions Value](/reference/metrics/advertising/blended/blended-conversions/blended-conversions-value) | Total conversion value | All conversion value | | [Blended Cost per Conversion](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-conversion) | Cost per conversion | Conversion efficiency | | [Blended All Conversions](/reference/metrics/advertising/blended/blended-conversions/blended-all-conversions) | Including cross-device | Expanded attribution | | [Blended All Conversions Value](/reference/metrics/advertising/blended/blended-conversions/blended-all-conversions-value) | All conversions value | Full conversion value | | [Blended Cost per All Conv.](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-all-conversions) | Cost per all conversion | Full attribution cost | | [Blended View-Through Conv.](/reference/metrics/advertising/blended/blended-conversions/blended-view-through-conversions) | View-through conversions | Impression attribution | | [Blended Cost per VTC](/reference/metrics/advertising/blended/blended-conversions/blended-cost-per-view-through-conversion) | Cost per view-through | View-through cost | ## How These Metrics Relate Conversion metrics follow the customer journey: View Content → Add to Cart → Initiate Checkout → Purchase Each stage has count, value, and cost metrics. ## Choosing the Right Metric * **E-commerce**: Focus on Purchase metrics and funnel progression * **Lead generation**: Track Leads, Appointments, and Registrations * **SaaS/Apps**: Monitor Subscriptions, Trials, and App Installs * **Full attribution**: Use All Conversions for cross-device tracking # Blended All Conversions ROAS: Cross-Platform Return on Ad Spend Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-efficiency/blended-all-conversions-roas Measure aggregated ROAS across Meta, Google, and TikTok including all conversion types. Formula, examples, and optimization strategies. Return on ad spend calculated from all conversion types—including cross-device and view-through conversions—aggregated across all ad platforms. ## Formula **Blended All Conversions ROAS** = **Blended All Conversions Value** ÷ **Blended Spend** ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [**Blended All Conversions Value**](/reference/metrics/advertising/blended/blended-conversions/blended-all-conversions-value) | Total revenue from all conversion types across platforms | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total ad spend aggregated across all platforms | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Multiplier | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your campaigns show **3.8x** blended all conversions ROAS this month: | Metric | Value | | -------------------------------- | --------- | | Blended All Conversions Value | \$152,000 | | Blended Spend | \$40,000 | | **Blended All Conversions ROAS** | **3.8x** | This includes view-through and cross-device conversions that standard ROAS may miss. *** ## How It Works Blended All Conversions ROAS divides total conversion value—including cross-device and view-through conversions—by total ad spend across Meta, Google, and TikTok. This provides a comprehensive view of advertising efficiency that captures the full customer journey across devices and touchpoints. *** ## When to Use | Scenario | Action | | -------------------------------------- | ---------------------------------------------- | | Measuring total advertising efficiency | Compare all conversions ROAS vs standard ROAS | | Evaluating view-through impact | Quantify revenue from non-click conversions | | Cross-device attribution | Capture conversions that span multiple devices | | Executive reporting | Report holistic marketing ROI to stakeholders | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [Blended ROAS](/reference/metrics/advertising/blended/blended-efficiency/blended-roas) | Click-attributed conversions only (narrower scope) | | [Blended Conversions ROAS](/reference/metrics/advertising/blended/blended-efficiency/blended-conversions-roas) | Similar metric with different conversion window | | [Blended All Conversions Value](/reference/metrics/advertising/blended/blended-conversions/blended-all-conversions-value) | Numerator in this calculation | [See all Blended Efficiency metrics →](/reference/metrics/advertising/blended/blended-efficiency) # Blended Conversions ROAS: Cross-Platform Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-efficiency/blended-conversions-roas Track return on ad spend for all conversion events across Meta, Google, and TikTok Ads combined for comprehensive efficiency analysis. Blended Conversions ROAS measures the revenue generated from all conversion types across all ad platforms for every dollar spent on advertising. ## Formula **Blended Conversions ROAS** = **Blended All Conversions Value** ÷ **Blended Spend** ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [**Blended All Conversions Value**](/reference/metrics/advertising/blended/blended-conversions/blended-all-conversions-value) | Total revenue from all conversion types across platforms | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total amount spent on advertising across all platforms | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Multiplier | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your campaigns spent **\$10,000** across all platforms and generated **\$45,000** in conversion value from all event types. | Metric | Value | | ----------------------------- | -------- | | Blended All Conversions Value | \$45,000 | | Blended Spend | \$10,000 | | **Blended Conversions ROAS** | **4.5x** | *** ## How It Works This metric aggregates all conversion events (purchases, signups, leads, etc.) across Meta, Google, and TikTok Ads, then divides by total spend. It provides a holistic view of advertising efficiency by including all conversion types, not just purchases. *** ## When to Use | Scenario | Action | | ------------------------------------------------- | ------------------------------------------------- | | Comparing total ad efficiency across platforms | Use to evaluate overall marketing ROI | | Tracking campaigns with multiple conversion goals | Monitor combined conversion value performance | | Budgeting across ad platforms | Allocate spend based on all-conversion efficiency | | Reporting to stakeholders | Show comprehensive advertising returns | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | [Blended ROAS](/reference/metrics/advertising/blended/blended-efficiency/blended-roas) | Purchase-only ROAS vs all conversions | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Denominator in this calculation | | [Blended All Conversions Value](/reference/metrics/advertising/blended/blended-conversions/blended-all-conversions-value) | Numerator in this calculation | [See all Blended Efficiency metrics →](/reference/metrics/advertising/blended/blended-efficiency) # Blended CPA: Cost Per Acquisition Across All Channels Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-efficiency/blended-cpa Track your blended CPA to understand acquisition costs across Meta, Google, and TikTok combined. Optimize your overall marketing efficiency. Blended CPA measures the average cost to acquire each purchase conversion across all your advertising channels combined. ## Formula **Blended CPA** = **Blended Spend** ÷ **Blended Purchases** ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total advertising spend across all connected platforms | | [**Blended Purchases**](/reference/metrics/advertising/blended/blended-conversions/blended-purchases) | Total attributed purchase conversions across all channels | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your store spent **\$12,500** across all advertising channels in March and generated **250 attributed purchases**. | Channel | Spend | Purchases | Channel CPA | | ----------- | ------------ | --------- | ----------- | | Meta | \$6,000 | 150 | \$40.00 | | Google | \$4,000 | 70 | \$57.14 | | TikTok | \$2,500 | 30 | \$83.33 | | **Blended** | **\$12,500** | **250** | **\$50.00** | *** ## How It Works Blended CPA aggregates total spend and total attributed purchases from all connected ad platforms, then calculates the average cost per conversion. This gives you a single efficiency metric across your entire paid media mix rather than evaluating each channel separately. *** ## When to Use | Scenario | Action | | ----------------------------------- | ----------------------------------------------------------- | | Setting overall acquisition targets | Compare blended CPA to customer lifetime value | | Budget allocation decisions | Identify if total spend is generating efficient conversions | | Monthly performance reviews | Track acquisition cost trends across all channels | | Scaling paid media | Monitor if efficiency holds as you increase total spend | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator — total ad spend across platforms | | [Blended Purchases](/reference/metrics/advertising/blended/blended-conversions/blended-purchases) | Denominator — total attributed purchases | | [Blended ROAS](/reference/metrics/advertising/blended/blended-efficiency/blended-roas) | Inverse efficiency metric measuring revenue return | [See all Blended Efficiency metrics →](/reference/metrics/advertising/blended/blended-efficiency) # Blended New Customer CPA: Cost to Acquire New Customers Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-efficiency/blended-new-customer-cpa Track your cost per new customer acquisition across all ad platforms. Calculate how much you spend on average to acquire each first-time buyer. Blended New Customer CPA measures how much you spend on average to acquire each new customer through your ads across all channels. ## Formula **Blended New Customer CPA** = **Blended Spend** ÷ **Blended New Customer Purchases** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Combined ad spend across all connected platforms | | [**Blended New Customer Purchases**](/reference/metrics/advertising/blended/blended-conversions/blended-new-customer-purchases) | First-time customer orders attributed to ads | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your store spent **\$12,000** across all ad platforms last month and acquired **150 new customers**: | Platform | Spend | New Customers | Platform NC CPA | | ----------- | ------------ | ------------- | --------------- | | Meta | \$6,000 | 80 | \$75.00 | | Google | \$4,000 | 50 | \$80.00 | | TikTok | \$2,000 | 20 | \$100.00 | | **Blended** | **\$12,000** | **150** | **\$80.00** | *** ## How It Works Blended NC CPA divides your total ad spend across all platforms by the number of new customers acquired. This metric specifically tracks first-time buyers, excluding repeat customers from the calculation. *** ## When to Use | Scenario | Action | | ------------------------------------------ | ------------------------------------------------- | | Evaluating customer acquisition efficiency | Compare NC CPA to customer lifetime value | | Budget allocation decisions | Shift spend toward platforms with lower NC CPA | | Scaling acquisition campaigns | Monitor NC CPA as spend increases | | Comparing to overall CPA | Higher NC CPA than CPA indicates strong retention | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator in NC CPA calculation | | [Blended New Customer Purchases](/reference/metrics/advertising/blended/blended-conversions/blended-new-customer-purchases) | Denominator in NC CPA calculation | | [Blended CPA](/reference/metrics/advertising/blended/blended-efficiency/blended-cpa) | Overall CPA including repeat customers | [See all Blended Efficiency metrics →](/reference/metrics/advertising/blended/blended-efficiency) # Blended New Customer ROAS: First-Time Buyer Ad Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-efficiency/blended-new-customer-roas Measure return on ad spend for new customer purchases across all channels. See how many dollars of first-time buyer revenue you earn per dollar spent. How many dollars of new customer revenue you generate for every dollar spent on ads across all channels. ## Formula **Blended New Customer ROAS** = **Blended New Customer Purchases Value** ÷ **Blended Spend** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | [**Blended New Customer Purchases Value**](/reference/metrics/advertising/blended/blended-conversions/blended-new-customer-purchases-value) | Total revenue from first-time buyers across all ad platforms | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Combined ad spend across Meta, Google, and TikTok | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Multiplier | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your store spent **\$15,000** on ads this month and generated **\$37,500** from first-time customers: | Channel | NC Revenue | Spend | NC ROAS | | ----------- | ------------ | ------------ | --------- | | Meta | \$22,500 | \$8,000 | 2.81× | | Google | \$10,500 | \$5,000 | 2.10× | | TikTok | \$4,500 | \$2,000 | 2.25× | | **Blended** | **\$37,500** | **\$15,000** | **2.50×** | *** ## How It Works Blended New Customer ROAS aggregates revenue from first-time buyers across all connected ad platforms and divides by total spend. A customer is "new" if they have no prior purchases in your store's history. This metric isolates acquisition efficiency from repeat purchase revenue. *** ## When to Use | Scenario | Action | | --------------------------------- | ------------------------------------------------------------------------- | | Evaluating acquisition efficiency | Compare NC ROAS to overall ROAS to see true acquisition cost | | Scaling new customer campaigns | Identify which channels acquire customers most profitably | | LTV-based budget planning | Combine with customer lifetime value for long-term ROI | | Diagnosing growth stalls | Low NC ROAS with high overall ROAS signals over-reliance on repeat buyers | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | [Blended ROAS](/reference/metrics/advertising/blended/blended-efficiency/blended-roas) | Total return including repeat customers | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | The denominator in this calculation | | [Blended New Customer Purchases Value](/reference/metrics/advertising/blended/blended-conversions/blended-new-customer-purchases-value) | The numerator in this calculation | [See all Blended Efficiency metrics →](/reference/metrics/advertising/blended/blended-efficiency) # Blended ROAS: Return on Ad Spend Across All Channels Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-efficiency/blended-roas Track Blended ROAS to measure how many dollars of revenue you generate for every dollar spent on ads across Meta, Google, and TikTok combined. Blended ROAS measures how many dollars of purchase revenue you generate for every dollar spent on ads across all channels. ## Formula **Blended ROAS** = **Blended Purchases Value** ÷ **Blended Spend** ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | [**Blended Purchases Value**](/reference/metrics/advertising/blended/blended-conversions/blended-purchases-value) | Total attributed revenue from purchases across all ad platforms | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total ad spend across Meta, Google, and TikTok | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Multiplier | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your store spent **\$15,000** on advertising last month and generated **\$52,500** in attributed revenue: | Platform | Spend | Revenue | Platform ROAS | | ----------- | ------------ | ------------ | ------------- | | Meta Ads | \$8,000 | \$28,000 | 3.5x | | Google Ads | \$5,000 | \$17,500 | 3.5x | | TikTok Ads | \$2,000 | \$7,000 | 3.5x | | **Blended** | **\$15,000** | **\$52,500** | **3.5x** | *** ## How It Works Blended ROAS aggregates spend and attributed purchase revenue across all connected ad platforms. A ROAS of 3x means you generate \$3 in revenue for every \$1 spent on ads. This provides a unified view of advertising efficiency without manually combining platform data. *** ## When to Use | Scenario | Action | | -------------------------------- | --------------------------------------------------------- | | Evaluating overall ad efficiency | Compare Blended ROAS to your target (e.g., 3x minimum) | | Reporting to stakeholders | Use as the single efficiency metric across all paid media | | Budget allocation decisions | Compare to platform-specific ROAS to identify winners | | Profitability analysis | Combine with margin data to assess true ad profitability | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Denominator — total cost of ads | | [Blended Purchases Value](/reference/metrics/advertising/blended/blended-conversions/blended-purchases-value) | Numerator — total attributed revenue | | [Blended CPA](/reference/metrics/advertising/blended/blended-efficiency/blended-cpa) | Inverse efficiency — cost to acquire a customer | [See all Blended Efficiency metrics →](/reference/metrics/advertising/blended/blended-efficiency) # Blended Efficiency: Aggregated ROAS and CPA Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-efficiency/index Track advertising efficiency metrics across all platforms. Includes Blended ROAS, Blended CPA, and new customer acquisition metrics. Efficiency metrics measure how effectively your advertising investment converts to revenue or customer acquisition across all connected platforms. **Data Source:** Meta Ads, Google Ads, TikTok Ads (aggregated)\ **Metrics:** 7 ## Metrics in This Group | Metric | Description | When to Use | | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------------ | | [Blended CPA](/reference/metrics/advertising/blended/blended-efficiency/blended-cpa) | Cost per acquisition across all channels | Measure acquisition cost | | [Blended ROAS](/reference/metrics/advertising/blended/blended-efficiency/blended-roas) | Return on ad spend across all channels | Measure revenue return | | [Blended NC CPA](/reference/metrics/advertising/blended/blended-efficiency/blended-new-customer-cpa) | Cost per new customer acquisition | New customer cost | | [Blended NC ROAS](/reference/metrics/advertising/blended/blended-efficiency/blended-new-customer-roas) | Return on ad spend for new customers | New customer efficiency | | [Blended Conversions ROAS](/reference/metrics/advertising/blended/blended-efficiency/blended-conversions-roas) | ROAS for all conversion events | Conversion efficiency | | [Blended All Conv. ROAS](/reference/metrics/advertising/blended/blended-efficiency/blended-all-conversions-roas) | ROAS including cross-device | Full attribution ROAS | ## How These Metrics Relate Efficiency metrics are ratios that connect spend to outcomes: * **CPA** = Total Spend ÷ Purchases (cost to acquire a customer) * **ROAS** = Purchase Value ÷ Total Spend (revenue per dollar spent) * **NC CPA** = Spend ÷ New Customer Purchases (cost for new customers) * **NC ROAS** = NC Purchase Value ÷ Spend (new customer revenue return) ROAS and CPA are inversely related—high ROAS typically means low CPA. ## Choosing the Right Metric * **E-commerce profitability**: Focus on ROAS (target typically 3x–5x) * **Customer acquisition**: Track CPA and NC CPA * **New customer growth**: Monitor NC ROAS to ensure acquisition is profitable * **Full funnel view**: Use All Conversions ROAS for complete attribution ## Benchmarks | Metric | Good | Excellent | | ------ | ---------- | ---------- | | ROAS | 3x | 5x+ | | CPA | \< 1/3 AOV | \< 1/5 AOV | | NC CPA | \< LTV/3 | \< LTV/5 | # Blended Comments: Cross-Platform Ad Conversation Volume Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-engagement/blended-comments Track total comments on your ads across Meta, Google, and TikTok to measure audience engagement and conversation volume. Blended Comments measures the total number of comments on your ads across all connected advertising platforms. ## Formula **Blended Comments** = **SUM** ( Comments ) across all ad platforms ### Formula Components | Metric | Definition | | --------------- | ---------------------------------------------- | | Meta Comments | Comments on your ads from Meta Ads campaigns | | Google Comments | Comments on your ads from Google Ads campaigns | | TikTok Comments | Comments on your ads from TikTok Ads campaigns | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your brand ran a multi-channel product launch campaign in April, generating **4,156 total comments** across all platforms. | Platform | Comments | Insight | | ---------- | -------- | ------------------------------------------- | | Meta Ads | 2,341 | Strong engagement on Facebook and Instagram | | TikTok Ads | 1,512 | High conversation on video content | | Google Ads | 303 | Lower comment volume on YouTube | *** ## How It Works Blended Comments aggregates comment counts from all connected advertising platforms. Each platform reports comments based on their own counting methodology—the blended total provides a unified view of conversation volume across your entire paid media presence. *** ## When to Use | Scenario | Action | | --------------------------------------- | --------------------------------------------------------------- | | Cross-platform campaign comparison | Compare total engagement volume across multi-channel campaigns | | Identifying high-conversation creatives | Find which ads spark the most discussion regardless of platform | | Measuring brand awareness impact | Track overall audience interaction with your advertising | | Detecting viral moments | Monitor spikes in cross-platform conversation | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | [Blended Engagements](/reference/metrics/advertising/blended/blended-engagement/blended-engagements) | Parent metric including comments, shares, and reactions | | [Blended Shares](/reference/metrics/advertising/blended/blended-engagement/blended-shares) | Measures share/repost volume across channels | | [Blended Reactions](/reference/metrics/advertising/blended/blended-engagement/blended-reactions) | Measures likes and reactions across channels | [See all Blended Engagement metrics →](/reference/metrics/advertising/blended/blended-engagement) # Blended Cost Per Comment: Ad Engagement Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-engagement/blended-cost-per-comment Measure the cost per comment on your ads across Meta, Google, and TikTok. Optimize engagement spending with this aggregated efficiency metric. The cost per comment on your ads, aggregated across all advertising platforms. ## Formula **Blended Cost Per Comment** = **Blended Spend** ÷ **Blended Comments** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------- | ------------------------------- | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total ad spend across platforms | | [**Blended Comments**](/reference/metrics/advertising/blended/blended-engagement/blended-comments) | Total comments across platforms | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your campaigns spent **\$2,540** and generated **127 comments**—yielding **\$20.00 cost per comment**. Meta drove comments at \$17.65 while TikTok cost \$26.67 per comment. *** ## How It Works Divides total ad spend by total comments across all platforms. Lower values mean more cost-efficient comment generation. *** ## When to Use | Scenario | Action | | --------------------- | ---------------------------------------------------- | | Engagement efficiency | Compare cost to acquire comments across campaigns | | Budget optimization | Identify platforms with lower engagement costs | | Creative testing | Measure which ads drive cost-efficient conversations | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator (total spend) | | [Blended Comments](/reference/metrics/advertising/blended/blended-engagement/blended-comments) | Denominator (total comments) | | [Blended Cost Per Engagement](/reference/metrics/advertising/blended/blended-engagement/blended-cost-per-engagement) | Broader engagement efficiency | [See all Blended Engagement metrics →](/reference/metrics/advertising/blended/blended-engagement) # Blended Cost Per Engagement: Aggregate CPE Across Platforms Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-engagement/blended-cost-per-engagement Track cost per social engagement across Meta, Google, and TikTok combined. Learn the formula, see examples, and benchmark engagement efficiency. The cost per social engagement on your ads, aggregated across all advertising platforms. ## Formula **Blended Cost Per Engagement** = **Blended Spend** ÷ **Blended Engagements** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total ad spend across all platforms | | [**Blended Engagements**](/reference/metrics/advertising/blended/blended-engagement/blended-engagements) | Total social engagements across platforms | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your campaigns spent **\$12,000** and generated **8,000 engagements** this month: | Platform | Spend | Engagements | CPE | | ----------- | ------------ | ----------- | ---------- | | Meta Ads | \$6,500 | 5,200 | \$1.25 | | Google Ads | \$3,000 | 1,500 | \$2.00 | | TikTok Ads | \$2,500 | 1,300 | \$1.92 | | **Blended** | **\$12,000** | **8,000** | **\$1.50** | *** ## How It Works Blended CPE divides total ad spend by the sum of all social engagements across Meta, Google, and TikTok. Lower CPE indicates more efficient engagement per dollar. *** ## When to Use | Scenario | Action | | ------------------------------- | --------------------------------------------------- | | Benchmark engagement efficiency | Compare CPE across platforms and campaigns | | Optimize social campaigns | Shift budget toward platforms with lower CPE | | Evaluate creative performance | Test which creatives drive engagement at lower cost | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | ------------------------------ | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator in CPE calculation | | [Blended Engagements](/reference/metrics/advertising/blended/blended-engagement/blended-engagements) | Denominator in CPE calculation | | [Blended CPM](/reference/metrics/advertising/blended/blended-audience/blended-cpm) | Cost per 1,000 impressions | [See all Blended Engagement metrics →](/reference/metrics/advertising/blended/blended-engagement) # Blended Cost Per Like: Engagement Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-engagement/blended-cost-per-like Track cost per like across all ad platforms. Compare engagement efficiency and optimize your social ad spend for better results. Blended Cost Per Like measures how much you pay for each like across all your advertising platforms combined. ## Formula **Blended Cost Per Like** = **Blended Spend** ÷ **Blended Likes** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------- | ---------------------------------------------- | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total ad spend aggregated across all platforms | | [**Blended Likes**](/reference/metrics/advertising/blended/blended-engagement/blended-likes) | Total likes on ads across all platforms | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your campaigns generated **12,500 likes** with **\$2,500 total spend** across Meta, TikTok, and Google—yielding a blended cost per like of **\$0.20**. *** ## How It Works Blended Cost Per Like aggregates total spend and total likes from Meta, Google, and TikTok, then calculates the combined cost per like. This gives you a single efficiency metric across all platforms rather than evaluating each separately. *** ## When to Use | Scenario | Action | | ---------------------------------------------- | ------------------------------------------- | | Comparing cross-platform engagement efficiency | Use blended CPL as your unified benchmark | | Budget allocation decisions | Shift spend toward platforms with lower CPL | | Campaign performance review | Track blended CPL trends over time | | Setting engagement cost targets | Establish CPL thresholds for new campaigns | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator in this calculation | | [Blended Likes](/reference/metrics/advertising/blended/blended-engagement/blended-likes) | Denominator in this calculation | | [Blended Cost Per Engagement](/reference/metrics/advertising/blended/blended-engagement/blended-cost-per-engagement) | Broader engagement efficiency metric | [See all Blended Engagement metrics →](/reference/metrics/advertising/blended/blended-engagement) # Blended Cost Per Share: Measure Ad Sharing Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-engagement/blended-cost-per-share Track how much you spend for each share of your ads across all platforms. Optimize viral potential and social engagement cost-efficiency. Blended Cost Per Share measures the average cost to generate one share of your ads across all connected advertising platforms. ## Formula **Blended Cost Per Share** = **Blended Spend** ÷ **Blended Shares** ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total advertising spend aggregated across all platforms | | [**Blended Shares**](/reference/metrics/advertising/blended/blended-engagement/blended-shares) | Total shares of your ads aggregated across all platforms | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your campaigns generated **2,500 shares** across all platforms with a total spend of **\$5,000**. | Platform | Spend | Shares | Cost Per Share | | ----------- | ----------- | --------- | -------------- | | Meta | \$2,500 | 1,800 | \$1.39 | | TikTok | \$2,500 | 700 | \$3.57 | | **Blended** | **\$5,000** | **2,500** | **\$2.00** | *** ## How It Works Blended Cost Per Share divides your total ad spend by the total number of shares across all connected platforms. This gives you a unified view of how efficiently your budget generates viral engagement, regardless of which platform drives the shares. *** ## When to Use | Scenario | Action | | --------------------------- | -------------------------------------------------------------------- | | Comparing viral efficiency | Benchmark cost per share against industry standards | | Optimizing for shareability | Identify which creative assets generate shares most cost-effectively | | Budget allocation | Shift spend toward platforms with lower cost per share | | Campaign planning | Set target cost per share for awareness campaigns | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator in this calculation | | [Blended Shares](/reference/metrics/advertising/blended/blended-engagement/blended-shares) | Denominator in this calculation | | [Blended Cost Per Engagement](/reference/metrics/advertising/blended/blended-engagement/blended-cost-per-engagement) | Broader engagement efficiency metric | [See all Blended Engagement metrics →](/reference/metrics/advertising/blended/blended-engagement) # Blended Engagement Rate: Cross-Platform Ad Resonance Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-engagement/blended-engagement-rate Track the percentage of impressions that resulted in engagements across Meta, Google, and TikTok ads. Compare creative performance across platforms. The percentage of impressions that resulted in an engagement, aggregated across all ad platforms. ## Formula **Blended Engagement Rate** = ( **Blended Engagements** ÷ **Blended Impressions** ) × 100 ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | [**Blended Engagements**](/reference/metrics/advertising/blended/blended-engagement/blended-engagements) | Total interactions (likes, comments, shares, clicks) across platforms | | [**Blended Impressions**](/reference/metrics/advertising/blended/blended-audience/blended-impressions) | Total times ads were shown across platforms | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your cross-platform campaign generated **2,850** engagements from **95,000** impressions: | Platform | Impressions | Engagements | Rate | | --------------- | ----------- | ----------- | -------- | | Meta | 50,000 | 1,500 | 3.0% | | TikTok + Google | 45,000 | 1,350 | 3.0% | | **Blended** | **95,000** | **2,850** | **3.0%** | *** ## How It Works Blended Engagement Rate aggregates engagement data from Meta, Google, and TikTok. Each platform defines engagement differently (reactions, clicks, likes), but the blended rate normalizes by total impressions for cross-platform comparison. *** ## When to Use | Scenario | Action | | ------------------------------ | --------------------------------------------------------- | | Comparing platform performance | Identify which platform drives highest engagement | | Budget allocation decisions | Shift spend toward platforms with higher engagement rates | | Creative performance analysis | Use as a leading indicator of ad resonance | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | ---------------------------------- | | [Blended Engagements](/reference/metrics/advertising/blended/blended-engagement/blended-engagements) | The numerator (total interactions) | | [Blended Impressions](/reference/metrics/advertising/blended/blended-audience/blended-impressions) | The denominator (times shown) | | [Blended CTR](/reference/metrics/advertising/blended/blended-clicks/blended-ctr) | Click-specific engagement measure | [See all Blended Engagement metrics →](/reference/metrics/advertising/blended/blended-engagement) # Blended Engagements: Total Social Ad Interactions Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-engagement/blended-engagements Track total social engagements on your ads across all channels. Includes likes, comments, shares, and reactions from Meta, Google, and TikTok. Blended Engagements measures total social interactions on your ads across all advertising channels. ## Formula **Blended Engagements** = **Blended Likes** + **Blended Comments** + **Blended Shares** + **Blended Reactions** ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [**Blended Likes**](/reference/metrics/advertising/blended/blended-engagement/blended-likes) | Total likes on your ads across all channels | | [**Blended Comments**](/reference/metrics/advertising/blended/blended-engagement/blended-comments) | Total comments on your ads across all channels | | [**Blended Shares**](/reference/metrics/advertising/blended/blended-engagement/blended-shares) | Total shares of your ads across all channels | | [**Blended Reactions**](/reference/metrics/advertising/blended/blended-engagement/blended-reactions) | Total reactions (likes, loves, etc.) across all channels | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your ads generated **12,450 total engagements** last month across all platforms. | Platform | Engagements | % of Total | | ---------- | ----------- | ---------- | | Meta Ads | 7,820 | 62.8% | | TikTok Ads | 3,180 | 25.5% | | Google Ads | 1,450 | 11.7% | *** ## How It Works Blended Engagements aggregates all social interactions from your advertising accounts—including likes, comments, shares, and reactions. The metric pulls data from Meta, Google, and TikTok to provide a unified view of ad engagement. *** ## When to Use | Scenario | Action | | --------------------------------------------- | ---------------------------------------------- | | Comparing overall engagement across platforms | Use blended view to see total reach | | Measuring content resonance | High engagements indicate compelling creative | | Optimizing ad creative | Compare engagement rates between ad variations | | Reporting to stakeholders | Show total social proof across all channels | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------ | ----------------------------------------- | | [Blended Shares](/reference/metrics/advertising/blended/blended-engagement/blended-shares) | Subset: content sharing actions | | [Blended Reactions](/reference/metrics/advertising/blended/blended-engagement/blended-reactions) | Subset: likes, loves, and other reactions | | [Blended Comments](/reference/metrics/advertising/blended/blended-engagement/blended-comments) | Subset: comment interactions | [See all Blended Engagement metrics →](/reference/metrics/advertising/blended/blended-engagement) # Blended Likes: Cross-Platform Ad Engagement Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-engagement/blended-likes Track total likes on your ads across Meta, Google, and TikTok. Measure audience approval and engagement at a glance. Blended Likes measures the total number of likes on your ads across all connected advertising platforms. ## Formula **Blended Likes** = **SUM** ( Likes ) across all ad platforms ### Formula Components | Metric | Definition | | ------------ | ------------------------------------------- | | Meta Likes | Likes on your ads from Meta Ads campaigns | | Google Likes | Likes on your ads from Google Ads campaigns | | TikTok Likes | Likes on your ads from TikTok Ads campaigns | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your ads received **8,432 likes** across all platforms last month. | Platform | Likes | Share | | ---------- | ----- | ----- | | Meta Ads | 5,210 | 62% | | TikTok Ads | 2,890 | 34% | | Google Ads | 332 | 4% | *** ## How It Works Blended Likes aggregates like counts from Meta, Google, and TikTok into a single metric. Each platform reports likes differently—Meta includes post reactions, TikTok counts video likes, and Google tracks engagement signals. This metric combines them for a unified view. *** ## When to Use | Scenario | Action | | ------------------------------ | --------------------------------------------------- | | Comparing creative performance | Higher likes indicate stronger audience resonance | | Measuring brand sentiment | Track likes over time to gauge audience approval | | Evaluating ad formats | Compare likes across video, image, and carousel ads | | Cross-platform benchmarking | Identify which platforms drive the most engagement | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | [Blended Reactions](/reference/metrics/advertising/blended/blended-engagement/blended-reactions) | Broader engagement including all reaction types | | [Blended Engagements](/reference/metrics/advertising/blended/blended-engagement/blended-engagements) | Total interactions including likes, comments, shares | | [Blended Comments](/reference/metrics/advertising/blended/blended-engagement/blended-comments) | Measures conversation volume vs passive approval | [See all Blended Engagement metrics →](/reference/metrics/advertising/blended/blended-engagement) # Blended Reactions: Total Ad Reaction Interactions Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-engagement/blended-reactions Track total reactions on your ads across all channels. Includes likes, loves, and other emotional responses from Meta, Google, and TikTok Ads. Blended Reactions measures the total number of reactions (likes, love, etc.) on your ads across all advertising channels. ## Formula **Blended Reactions** = **SUM** ( Reactions ) across all ad platforms ### Formula Components | Metric | Definition | | ---------------- | --------------------------------------------------------- | | Meta Reactions | Reactions on Meta ads (like, love, haha, wow, sad, angry) | | Google Reactions | Reactions on Google ads where available | | TikTok Reactions | Reactions on TikTok ads (likes, hearts) | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your ads received **8,940 total reactions** last month across all platforms. | Platform | Reactions | % of Total | | ---------- | --------- | ---------- | | Meta Ads | 5,620 | 62.9% | | TikTok Ads | 2,810 | 31.4% | | Google Ads | 510 | 5.7% | *** ## How It Works Blended Reactions aggregates all emotional response interactions from your advertising accounts. This includes likes, loves, and other reaction types across Meta, Google, and TikTok platforms to provide a unified view of how audiences emotionally respond to your ads. *** ## When to Use | Scenario | Action | | ------------------------------ | ---------------------------------------------------- | | Measuring emotional resonance | High reactions indicate content that evokes response | | Comparing platform performance | See which platform drives more emotional engagement | | Optimizing creative direction | Use reaction data to guide ad creative strategy | | Tracking social proof | Reactions contribute to perceived ad credibility | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | [Blended Engagements](/reference/metrics/advertising/blended/blended-engagement/blended-engagements) | Parent: reactions are a component of total engagements | | [Blended Likes](/reference/metrics/advertising/blended/blended-engagement/blended-likes) | Subset: like reactions specifically | | [Blended Shares](/reference/metrics/advertising/blended/blended-engagement/blended-shares) | Sibling: sharing actions on ads | [See all Blended Engagement metrics →](/reference/metrics/advertising/blended/blended-engagement) # Blended Saves: Ad Bookmarks Across Platforms Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-engagement/blended-saves Track total saves and bookmarks of your ads across Meta, Google, and TikTok. Measure content resonance with aggregated save metrics. Blended Saves counts the total number of times users saved or bookmarked your ads across all connected advertising platforms. ## Formula **Blended Saves** = **SUM** ( Saves ) across all ad platforms ### Formula Components | Metric | Definition | | ------------ | ------------------------------- | | Meta Saves | Saves from Meta Ads campaigns | | Google Saves | Saves from Google Ads campaigns | | TikTok Saves | Saves from TikTok Ads campaigns | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your ads received **2,847 saves** last month across platforms. | Platform | Saves | Share | | -------- | ----- | ----- | | Meta | 1,523 | 53% | | TikTok | 892 | 31% | | Google | 432 | 16% | *** ## How It Works Blended Saves aggregates save and bookmark actions from all connected advertising platforms into a single metric. When users save your ad for later viewing, each platform reports this engagement, and Upstack combines them for a unified view. *** ## When to Use | Scenario | Action | | ----------------------- | ---------------------------------------- | | Content resonance | High saves indicate ads worth revisiting | | Purchase intent signals | Saves often precede conversions | | Creative optimization | Compare save rates across ad variants | | Audience insights | Identify which audiences save most | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | -------------------------------- | | [Blended Engagements](/reference/metrics/advertising/blended/blended-engagement/blended-engagements) | Total engagement including saves | | [Blended Likes](/reference/metrics/advertising/blended/blended-engagement/blended-likes) | Another engagement signal | | [Blended Shares](/reference/metrics/advertising/blended/blended-engagement/blended-shares) | Viral engagement metric | [See all Blended Engagement metrics →](/reference/metrics/advertising/blended/blended-engagement) # Blended Shares: Total Ad Shares Across Channels Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-engagement/blended-shares Track total shares of your ads across all advertising channels. Measure viral reach and content sharing from Meta, Google, and TikTok campaigns. Blended Shares measures the total number of times users shared your ads across all advertising channels. ## Formula **Blended Shares** = **SUM** ( Shares ) across all ad platforms ### Formula Components | Metric | Definition | | ------------- | -------------------------------------- | | Meta Shares | Shares of your ads on Meta platforms | | Google Shares | Shares of your ads on Google platforms | | TikTok Shares | Shares of your ads on TikTok | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your ads were shared **2,340 times** last month across all platforms. | Platform | Shares | % of Total | | ---------- | ------ | ---------- | | Meta Ads | 1,520 | 65.0% | | TikTok Ads | 680 | 29.1% | | Google Ads | 140 | 5.9% | *** ## How It Works Blended Shares aggregates share actions from all your advertising accounts. When users share your ad content with their network, it extends your organic reach. The metric pulls share data from Meta, Google, and TikTok to provide a unified view. *** ## When to Use | Scenario | Action | | ---------------------------- | -------------------------------------------- | | Measuring viral potential | High shares indicate content worth spreading | | Optimizing for organic reach | Compare share rates between ad creatives | | Evaluating content resonance | Shares show audience finds content valuable | | Cross-platform performance | Compare sharing behavior across channels | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | ----------------------------------------- | | [Blended Engagements](/reference/metrics/advertising/blended/blended-engagement/blended-engagements) | Parent: total engagement including shares | | [Blended Reactions](/reference/metrics/advertising/blended/blended-engagement/blended-reactions) | Sibling: likes and reaction interactions | | [Blended Comments](/reference/metrics/advertising/blended/blended-engagement/blended-comments) | Sibling: comment interactions | [See all Blended Engagement metrics →](/reference/metrics/advertising/blended/blended-engagement) # Blended Engagement: Aggregated Social Engagement Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-engagement/index Track social engagement metrics across all ad platforms. Includes likes, comments, shares, saves, and engagement rates. Engagement metrics measure social interactions with your ads across all connected platforms—likes, comments, shares, saves, and reactions. **Data Source:** Meta Ads, Google Ads, TikTok Ads (aggregated)\ **Metrics:** 12 ## Metrics in This Group | Metric | Description | When to Use | | -------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------ | | [Blended Engagements](/reference/metrics/advertising/blended/blended-engagement/blended-engagements) | Total engagement actions | Measure overall interaction | | [Blended Cost per Engagement](/reference/metrics/advertising/blended/blended-engagement/blended-cost-per-engagement) | Cost per engagement action | Evaluate engagement efficiency | | [Blended Engagement Rate](/reference/metrics/advertising/blended/blended-engagement/blended-engagement-rate) | Engagements as % of impressions | Compare content performance | | [Blended Shares](/reference/metrics/advertising/blended/blended-engagement/blended-shares) | Number of shares | Track viral potential | | [Blended Cost per Share](/reference/metrics/advertising/blended/blended-engagement/blended-cost-per-share) | Cost per share | Viral reach cost | | [Blended Reactions](/reference/metrics/advertising/blended/blended-engagement/blended-reactions) | Emoji reactions received | Emotional response | | [Blended Cost per Reaction](/reference/metrics/advertising/blended/blended-engagement/blended-cost-per-reaction) | Cost per reaction | Reaction efficiency | | [Blended Likes](/reference/metrics/advertising/blended/blended-engagement/blended-likes) | Number of likes | Basic approval signal | | [Blended Cost per Like](/reference/metrics/advertising/blended/blended-engagement/blended-cost-per-like) | Cost per like | Like efficiency | | [Blended Comments](/reference/metrics/advertising/blended/blended-engagement/blended-comments) | Number of comments | Conversation driver | | [Blended Cost per Comment](/reference/metrics/advertising/blended/blended-engagement/blended-cost-per-comment) | Cost per comment | Comment efficiency | | [Blended Saves](/reference/metrics/advertising/blended/blended-engagement/blended-saves) | Number of saves | Content bookmarking | | [Blended Cost per Save](/reference/metrics/advertising/blended/blended-engagement/blended-cost-per-save) | Cost per save | Save efficiency | ## How These Metrics Relate Engagement metrics capture different levels of user investment: * **Likes** = lowest friction, quick approval * **Reactions** = emotional response (loves, wows, etc.) * **Comments** = active conversation participation * **Shares** = highest value, extends reach organically * **Saves** = future reference intent Total Engagements = Likes + Reactions + Comments + Shares + Saves + Clicks Engagement Rate = Engagements ÷ Impressions × 100 ## Choosing the Right Metric * **Brand awareness**: Track Engagements and Engagement Rate * **Viral campaigns**: Focus on Shares * **Content quality**: Compare Engagement Rate across creatives * **Community building**: Monitor Comments and Reactions * **Future intent**: Track Saves for purchase consideration # Blended Spend: Total Ad Spend Across All Channels Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-spend/blended-spend Track your total advertising spend across Meta, Google, and TikTok in one unified metric. See how to analyze and optimize your marketing budget. The total amount of money spent on advertising across all connected ad platforms. ## Formula **Blended Spend** = **SUM** ( Ad Spend ) **ACROSS** Meta Ads, Google Ads, TikTok Ads | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your marketing campaigns spent **\$24,750** across all channels this month: | Platform | Spend | Share | | ---------- | -------- | ----- | | Meta Ads | \$12,400 | 50% | | Google Ads | \$8,600 | 35% | | TikTok Ads | \$3,750 | 15% | *** ## How It Works Blended Spend aggregates advertising costs from all connected ad platforms into a single metric. Data syncs daily from each platform's reporting API. Currency conversions use the exchange rate at time of spend. *** ## When to Use | Scenario | Action | | ------------------------ | ------------------------------------------------ | | Total budget tracking | Monitor overall marketing investment | | Calculating blended ROAS | Divide total revenue by Blended Spend | | Budget pacing | Compare actual spend against monthly targets | | CFO reporting | Provide single source of truth for ad investment | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | ----------------------------- | | [Blended Impressions](/reference/metrics/advertising/blended/blended-audience/blended-impressions) | Reach generated by this spend | | [Blended ROAS](/reference/metrics/advertising/blended/blended-efficiency/blended-roas) | Revenue ÷ Blended Spend | | [Blended CPA](/reference/metrics/advertising/blended/blended-efficiency/blended-cpa) | Blended Spend ÷ Conversions | [See all Blended Spend metrics →](/reference/metrics/advertising/blended/blended-spend) # Blended Spend: Total Advertising Investment Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-spend/index Track total advertising spend across all connected platforms. Includes Blended Spend with formulas and optimization tips. Spend metrics track total advertising investment across all connected ad platforms. Use these to understand total budget allocation and calculate blended efficiency metrics. **Data Source:** Meta Ads, Google Ads, TikTok Ads (aggregated)\ **Metrics:** 1 ## Metrics in This Group | Metric | Description | When to Use | | -------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------ | | [Blended Ad Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total amount spent on advertising across all channels | Measure total advertising investment | ## How These Metrics Relate Blended Spend is the foundation for all blended efficiency calculations. It aggregates spend from Meta, Google, TikTok, and any other connected advertising platforms. ## Choosing the Right Metric * **Total budget tracking**: Use Blended Spend to see total advertising investment * **Platform comparison**: Compare with [Meta Ad Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) or [Google Ad Spend](/reference/metrics/advertising/google/google-spend/google-spend) for platform breakdowns # Blended Cost Per ThruPlay: Cross-Platform Video Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-video/blended-cost-per-thruplay Track your cost per completed or 15-second video view across Meta, Google, and TikTok. Optimize video ad efficiency with this unified metric. The cost per completed or 15-second video view across all connected advertising platforms. ## Formula **Blended Cost Per ThruPlay** = **Blended Spend** ÷ **Blended ThruPlay Views** ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total amount spent on advertising across all platforms | | [**Blended ThruPlay Views**](/reference/metrics/advertising/blended/blended-video/blended-thruplay-views) | Video views watched to completion or for at least 15 seconds | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your video campaigns spent **\$8,500** and generated **425,000 ThruPlay views** this month: | Channel | Spend | ThruPlay Views | Cost Per ThruPlay | | ----------- | ----------- | -------------- | ----------------- | | Meta Ads | \$5,000 | 250,000 | \$0.020 | | Google Ads | \$2,000 | 100,000 | \$0.020 | | TikTok Ads | \$1,500 | 75,000 | \$0.020 | | **Blended** | **\$8,500** | **425,000** | **\$0.020** | *** ## How It Works Blended Cost Per ThruPlay divides your total ad spend by the number of ThruPlay views across all connected platforms. A ThruPlay counts when users watch to completion or for at least 15 seconds—measuring meaningful video engagement rather than passive impressions. *** ## When to Use | Scenario | Action | | ------------------------------------ | -------------------------------------------------------- | | Comparing video creative performance | Identify which videos drive engagement at lower cost | | Optimizing for brand awareness | Track cost efficiency of meaningful video views | | Budget allocation decisions | Shift spend toward channels with lower cost per ThruPlay | | Benchmarking against CPV | Compare ThruPlay efficiency to general video view costs | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | The numerator in Cost Per ThruPlay calculation | | [Blended ThruPlay Views](/reference/metrics/advertising/blended/blended-video/blended-thruplay-views) | The denominator in Cost Per ThruPlay calculation | | [Blended CPV](/reference/metrics/advertising/blended/blended-video/blended-cpv) | Cost per any video view (less strict than ThruPlay) | [See all Blended Video metrics →](/reference/metrics/advertising/blended/blended-video) # Blended CPV: Cost Per Video View Across Channels Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-video/blended-cpv Track your cost per video view across Meta, Google, and TikTok. Learn the formula, see examples, and optimize your video ad efficiency. How much you pay on average for each video view across all channels. ## Formula **Blended CPV** = **Blended Spend** ÷ **Blended Video Views** ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------------------- | -------------------------------------- | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total ad spend across all platforms | | [**Blended Video Views**](/reference/metrics/advertising/blended/blended-video/blended-video-views) | Total video views across all platforms | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your campaigns spent **\$12,000** and generated **400,000 video views** this month: | Channel | Spend | Video Views | CPV | | ----------- | ------------ | ----------- | ----------- | | Meta Ads | \$6,000 | 200,000 | \$0.030 | | TikTok Ads | \$2,000 | 50,000 | \$0.040 | | **Blended** | **\$12,000** | **400,000** | **\$0.030** | *** ## How It Works Blended CPV aggregates your total ad spend and video views across all connected platforms, then calculates the average cost per view. *** ## When to Use | Scenario | Action | | --------------------------- | ------------------------------------------------------------- | | Evaluating video efficiency | Compare CPV across campaigns to find cost-effective creatives | | Budget allocation | Shift budget toward channels with lower CPV | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------- | ------------------------------ | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator in CPV calculation | | [Blended Video Views](/reference/metrics/advertising/blended/blended-video/blended-video-views) | Denominator in CPV calculation | | [Blended CPM](/reference/metrics/advertising/blended/blended-audience/blended-cpm) | Cost efficiency by impressions | [See all Blended Video metrics →](/reference/metrics/advertising/blended/blended-video) # Blended ThruPlay Views: Cross-Platform Video Engagement Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-video/blended-thruplay-views Track ThruPlay views across Meta, Google, and TikTok. Measures videos watched to completion or for at least 15 seconds. Blended ThruPlay Views measures the total number of times your video ads were watched to completion or for at least 15 seconds across all connected ad platforms. ## Formula **Blended ThruPlay Views** = **COUNT** ( Video Views ) **WHERE** watch\_time ≥ 15s **OR** completed = true ### Formula Components | Metric | Definition | | ----------------- | -------------------------------------------------------------- | | Video Views | Individual video ad impressions that met the ThruPlay criteria | | watch\_time ≥ 15s | Videos watched for at least 15 seconds | | completed = true | Videos watched to the end | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your video campaign ran across Meta, Google, and TikTok last week with **12,450 ThruPlay views**. | Platform | ThruPlay Views | Avg. Watch Time | | ----------------- | -------------- | --------------- | | Meta Ads | 7,200 | 18s | | Google Ads | 3,100 | 22s | | TikTok Ads | 2,150 | 16s | | **Blended Total** | **12,450** | 18.5s | *** ## How It Works A ThruPlay view is counted when a user watches your video ad to completion or for at least 15 seconds—whichever comes first. This metric aggregates ThruPlay-equivalent views across all connected ad platforms, providing a unified view of video engagement regardless of where your ads run. *** ## When to Use | Scenario | Action | | -------------------------------------------- | ------------------------------------------------------------ | | Comparing video performance across platforms | Use blended view to see total engaged video views | | Optimizing video creative | Identify which platforms drive the most ThruPlay completions | | Measuring brand awareness campaigns | Track meaningful video engagement at scale | | Allocating video ad budget | Shift spend toward platforms with higher ThruPlay rates | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------- | -------------------------------------- | | [Blended Video Views](/reference/metrics/advertising/blended/blended-video/blended-video-views) | Total video views (any duration) | | [Blended Video Views (100%)](/reference/metrics/advertising/blended/blended-video/blended-video-views-100) | Videos watched to full completion | | [Blended Video Views (15s)](/reference/metrics/advertising/blended/blended-video/blended-video-views-15s) | Videos watched for at least 15 seconds | [See all Blended Video metrics →](/reference/metrics/advertising/blended/blended-video) # Blended Video Plays: Cross-Platform Video Engagement Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-video/blended-video-plays Track total video plays across Meta, Google, and TikTok ads. Monitor cross-platform video engagement and autoplay performance in one metric. Blended Video Plays measures the total number of times your videos started playing across all advertising platforms, including autoplay. ## Formula **Blended Video Plays** = **SUM** ( Video Plays ) across Meta, Google, TikTok ### Formula Components | Metric | Definition | | ------------------ | ------------------------------------- | | Meta Video Plays | Video plays from Meta Ads campaigns | | Google Video Plays | Video plays from Google Ads campaigns | | TikTok Video Plays | Video plays from TikTok Ads campaigns | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your video campaigns generated **48,250 video plays** last week across all platforms. | Platform | Video Plays | Share | | ---------- | ----------- | ----- | | Meta Ads | 22,100 | 46% | | TikTok Ads | 18,650 | 39% | | Google Ads | 7,500 | 15% | | **Total** | **48,250** | 100% | *** ## How It Works Video plays count each time a video starts playing, including autoplay. This metric aggregates plays from Meta, Google, and TikTok into a single cross-platform total. Each platform may define "play" slightly differently—Meta counts at 0 seconds, while others may require brief engagement. *** ## When to Use | Scenario | Action | | ------------------------ | ------------------------------------------ | | Measuring video reach | Compare plays to impressions for play rate | | Cross-platform reporting | View total video engagement in one metric | | Campaign optimization | Identify which platforms drive most plays | | Creative testing | Compare play counts across video variants | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | [Blended Video Views](/reference/metrics/advertising/blended/blended-video/blended-video-views) | Views with completion requirements | | [Blended ThruPlay Views](/reference/metrics/advertising/blended/blended-video/blended-thruplay-views) | Videos watched to 15s or completion | | [Blended Impressions](/reference/metrics/advertising/blended/blended-audience/blended-impressions) | Total ad impressions for play rate calculation | [See all Blended Video metrics →](/reference/metrics/advertising/blended/blended-video) # Blended Video Views: Total Video Ad Views Across Platforms Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-video/blended-video-views Track total video views across Meta, Google, and TikTok Ads. Measure video ad engagement with platform-specific view thresholds aggregated. The total number of times your video ads were watched across all advertising platforms. ## Formula **Blended Video Views** = **SUM** ( Video Views ) across all ad platforms ### Formula Components | Metric | Definition | | ------------------ | ------------------------------------- | | Meta Video Views | Video views from Meta Ads campaigns | | Google Video Views | Video views from Google Ads campaigns | | TikTok Video Views | Video views from TikTok Ads campaigns | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your video campaigns generated **142,500 views** across platforms this week: | Platform | Views | Share | | ---------- | ------ | ----- | | Meta Ads | 78,000 | 55% | | TikTok Ads | 45,200 | 32% | | Google Ads | 19,300 | 13% | *** ## How It Works Blended Video Views sums all video view events from Meta, Google, and TikTok. Each platform has different view thresholds (Meta counts 3+ seconds, TikTok counts 2+ seconds, Google varies by format). This metric gives you a unified view of total video engagement. *** ## When to Use | Scenario | Action | | --------------------- | --------------------------------------------------- | | Measuring video reach | Track total video consumption across platforms | | Comparing ad formats | Evaluate video vs. static ad performance | | Calculating CPV | Divide Spend by Video Views for cost efficiency | | Evaluating creative | Identify which video creatives drive the most views | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | [Blended CPV](/reference/metrics/advertising/blended/blended-video/blended-cpv) | Spend ÷ Video Views | | [Blended ThruPlay Views](/reference/metrics/advertising/blended/blended-video/blended-thruplay-views) | Views where video was watched to completion | | [Blended Video Views (25%)](/reference/metrics/advertising/blended/blended-video/blended-video-views-25) | Views reaching 25% completion | [See all Blended Video metrics →](/reference/metrics/advertising/blended/blended-video) # Blended Video Views at 100%: Complete Video Plays Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-video/blended-video-views-100 Track video views where 100% of the video was watched across Meta, Google, and TikTok Ads. Measure true video completion rates. Video views where 100% (completion) of the video was watched, aggregated across all connected ad platforms. ## Formula **Blended Video Views (100%)** = **SUM** ( Video Views at 100% ) across Meta, Google, TikTok ### Formula Components | Metric | Definition | | -------------------------- | ----------------------------------- | | Meta Video Views at 100% | Completed video views on Meta Ads | | Google Video Views at 100% | Completed video views on Google Ads | | TikTok Video Views at 100% | Completed video views on TikTok Ads | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example A furniture brand ran video ads across Meta, Google, and TikTok promoting a 30-second product showcase. | Platform | Video Views at 100% | % of Total | | ----------------- | ------------------- | ---------- | | Meta Ads | 12,400 | 48% | | Google Ads | 8,200 | 32% | | TikTok Ads | 5,100 | 20% | | **Blended Total** | **25,700** | 100% | *** ## How It Works This metric aggregates complete video views (100% watched) from all connected advertising platforms into a single blended total. Each platform defines "100% viewed" as watching the entire video duration from start to finish. *** ## When to Use | Scenario | Action | | ------------------------------- | ------------------------------------------------------------- | | Measuring true engagement | Compare 100% views to partial views to assess content quality | | Evaluating creative performance | Higher completion rates indicate compelling content | | Cross-platform comparison | Identify which platform delivers most engaged viewers | | Retargeting audiences | Build audiences from users who watched entire videos | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | -------------------------------------- | | [Blended Video Views (75%)](/reference/metrics/advertising/blended/blended-video/blended-video-views-75) | Viewers who watched at least 75% | | [Blended Video Views](/reference/metrics/advertising/blended/blended-video/blended-video-views) | All video plays regardless of duration | | [Blended ThruPlay Views](/reference/metrics/advertising/blended/blended-video/blended-thruplay-views) | 15s or complete view metric | [See all Blended Video metrics →](/reference/metrics/advertising/blended/blended-video) # Blended Video Views 15s: Cross-Platform Video Engagement Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-video/blended-video-views-15s Track video views with 15+ seconds watched across Meta, Google, and TikTok ads. Measure engaged viewing behavior and optimize video creative. Video views where at least 15 seconds of the video was watched, aggregated across all connected ad platforms. ## Formula **Blended Video Views (15s)** = **SUM** ( Video Views ≥ 15s ) across all platforms ### Formula Components | Metric | Definition | | ---------------------- | -------------------------------------- | | Meta 15s Video Views | Video views reaching 15s on Meta Ads | | Google 15s Video Views | Video views reaching 15s on Google Ads | | TikTok 15s Video Views | Video views reaching 15s on TikTok Ads | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your video campaigns generated **24,500** 15-second views this week: | Platform | 15s Views | Share | | ---------- | --------- | ----- | | Meta Ads | 14,200 | 58% | | Google Ads | 6,850 | 28% | | TikTok Ads | 3,450 | 14% | *** ## How It Works This metric counts video views where the viewer watched at least 15 seconds. It aggregates equivalent metrics from each ad platform into a single cross-channel view. This threshold indicates meaningful engagement beyond initial impressions. *** ## When to Use | Scenario | Action | | --------------------------- | -------------------------------------------- | | Measuring video engagement | Compare engaged viewing across platforms | | Evaluating creative quality | Higher 15s views indicate compelling content | | Optimizing video length | Determine if viewers stay past the 15s mark | | Comparing to ThruPlay | Understand viewing behavior progression | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | [Blended Video Views](/reference/metrics/advertising/blended/blended-video/blended-video-views) | Total views (this metric filters for 15s+) | | [Blended Video Views (30s)](/reference/metrics/advertising/blended/blended-video/blended-video-views-30s) | Views with 30+ seconds watched | | [Blended ThruPlay Views](/reference/metrics/advertising/blended/blended-video/blended-thruplay-views) | Completed/15s threshold metric | [See all Blended Video metrics →](/reference/metrics/advertising/blended/blended-video) # Blended Video Views at 25%: Partial Watch Metric Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-video/blended-video-views-25 Track video views where at least 25% of your ad was watched across Meta, Google, and TikTok. Measure early engagement and viewer interest. Blended Video Views at 25% counts video views where at least 25% of your video ad was watched, aggregated across all connected ad platforms. ## Formula **Blended Video Views (25%)** = **COUNT** ( Video Views ) **WHERE** watch\_progress ≥ 25% ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | [**Blended Video Views**](/reference/metrics/advertising/blended/blended-video/blended-video-views) | Total number of times your video ad started playing | | watch\_progress ≥ 25% | Filter for views reaching at least 25% completion | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your video campaign received **12,450 views at 25%** last week across all platforms. | Platform | Total Views | 25% Views | Drop-off Rate | | -------- | ----------- | --------- | ------------- | | Meta | 8,200 | 6,150 | 25% | | Google | 3,100 | 2,480 | 20% | | TikTok | 4,500 | 3,820 | 15% | *** ## How It Works When a viewer watches at least 25% of your video ad, each platform records a 25% view event. Upstack aggregates these counts across Meta, Google, and TikTok to show your total early engagement. *** ## When to Use | Scenario | Action | | ------------------------------- | ---------------------------------------------- | | High impressions, low 25% views | Improve video hook in first 2-3 seconds | | Comparing creative performance | Use 25% views to identify engaging intros | | Funnel analysis | Compare 25% → 50% → 75% progression | | Budget allocation | Shift spend to platforms with higher 25% rates | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | [Blended Video Views](/reference/metrics/advertising/blended/blended-video/blended-video-views) | Total views before filtering by watch progress | | [Blended Video Views (50%)](/reference/metrics/advertising/blended/blended-video/blended-video-views-50) | Next milestone in viewer engagement | | [Blended Video Views (75%)](/reference/metrics/advertising/blended/blended-video/blended-video-views-75) | Near-complete video watches | [See all Blended Video metrics →](/reference/metrics/advertising/blended/blended-video) # Blended Video Views at 30 Seconds: Cross-Platform Engagement Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-video/blended-video-views-30s Track video views with 30+ seconds watched across Meta, Google, and TikTok Ads. Measure engaged viewers and optimize your video ad performance. Video views where at least 30 seconds of the video was watched, aggregated across all connected ad platforms. ## Formula **Blended Video Views (30s)** = **COUNT** ( Video Views ) **WHERE** watch\_time ≥ 30 seconds ### Formula Components | Metric | Definition | | ---------------------- | -------------------------------------- | | Meta 30s Video Views | Video views reaching 30s on Meta Ads | | Google 30s Video Views | Video views reaching 30s on Google Ads | | TikTok 30s Video Views | Video views reaching 30s on TikTok Ads | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your video campaigns generated **24,800** 30-second views this week: | Platform | 30s Views | Share | | ---------- | --------- | ----- | | Meta Ads | 14,200 | 57% | | Google Ads | 6,450 | 26% | | TikTok Ads | 4,150 | 17% | *** ## How It Works This metric counts video views where the viewer watched at least 30 seconds. For videos shorter than 30 seconds, this threshold may not apply. The metric aggregates equivalent engagement signals from each platform to provide a unified view of engaged viewership. *** ## When to Use | Scenario | Action | | -------------------- | --------------------------------------------------------- | | Measuring engagement | Identify which platforms drive the most engaged viewers | | Optimizing creatives | Compare 30s views across video variants to find winners | | Budget allocation | Shift spend toward platforms with higher engagement rates | | Audience quality | Use as a signal of genuine interest vs. passive scrolling | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | [Blended Video Views (15s)](/reference/metrics/advertising/blended/blended-video/blended-video-views-15s) | Shorter engagement threshold (15 seconds) | | [Blended ThruPlay Views](/reference/metrics/advertising/blended/blended-video/blended-thruplay-views) | Completed or 15s+ views | | [Blended Video Views (50%)](/reference/metrics/advertising/blended/blended-video/blended-video-views-50) | Views reaching 50% of video duration | [See all Blended Video metrics →](/reference/metrics/advertising/blended/blended-video) # Blended Video Views at 50%: Measure Video Engagement Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-video/blended-video-views-50 Track video views where at least 50% of the video was watched. Aggregate mid-point video engagement across Meta, Google, and TikTok Ads. Blended Video Views at 50% counts the total number of times your video ads were watched to at least the halfway point across all connected ad platforms. ## Formula **Blended Video Views (50%)** = **SUM** ( Video Views at 50% ) across Meta, Google, TikTok ### Formula Components | Metric | Definition | | ------------------------- | -------------------------------------- | | Meta Video Views at 50% | Video views reaching 50% on Meta Ads | | Google Video Views at 50% | Video views reaching 50% on Google Ads | | TikTok Video Views at 50% | Video views reaching 50% on TikTok Ads | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your video campaign generated **12,450 views at 50%** last week across all platforms. | Platform | Video Views at 50% | Share | | ---------- | ------------------ | ----- | | Meta Ads | 7,200 | 57.8% | | Google Ads | 3,100 | 24.9% | | TikTok Ads | 2,150 | 17.3% | | **Total** | **12,450** | 100% | *** ## How It Works This metric aggregates video views that reached the 50% completion mark from Meta Ads, Google Ads, and TikTok Ads into a single blended number. It provides a unified view of mid-point engagement across your video campaigns without needing to check each platform separately. *** ## When to Use | Scenario | Action | | ------------------------------------------- | ------------------------------------------------------------- | | Comparing video engagement across platforms | Use blended 50% views as a unified benchmark | | Measuring content quality | Higher 50% views indicate compelling video content | | Identifying drop-off points | Compare 25%, 50%, 75%, 100% views to find where viewers leave | | Optimizing video length | Low 50% completion suggests videos may be too long | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------- | ---------------------------- | | [Blended Video Views (25%)](/reference/metrics/advertising/blended/blended-video/blended-video-views-25) | Earlier engagement threshold | | [Blended Video Views (75%)](/reference/metrics/advertising/blended/blended-video/blended-video-views-75) | Later engagement threshold | | [Blended Video Views (100%)](/reference/metrics/advertising/blended/blended-video/blended-video-views-100) | Full video completions | [See all Blended Video metrics →](/reference/metrics/advertising/blended/blended-video) # Blended Video Views at 75%: Cross-Platform Engagement Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-video/blended-video-views-75 Track video views where at least 75% was watched across Meta, Google, and TikTok Ads. Measure deep engagement with your video creative. Blended Video Views at 75% counts video ad views where at least 75% of the video was watched—aggregated across all your connected ad platforms. ## Formula **Blended Video Views (75%)** = **SUM** ( 75% Video Views ) across Meta, Google, TikTok ### Formula Components | Metric | Definition | | ---------------------- | -------------------------------------- | | Meta 75% Video Views | Video views reaching 75% on Meta Ads | | Google 75% Video Views | Video views reaching 75% on Google Ads | | TikTok 75% Video Views | Video views reaching 75% on TikTok Ads | | Metadata | | | --------------- | --------------------------------------------------------------------------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your video campaign generated **42,500 75% video views** across all platforms last month. | Platform | 75% Video Views | Total Views | Deep Engagement Rate | | ----------- | --------------- | ----------- | -------------------- | | Meta Ads | 24,000 | 85,000 | 28.2% | | Google Ads | 11,500 | 38,000 | 30.3% | | TikTok Ads | 7,000 | 32,000 | 21.9% | | **Blended** | **42,500** | **155,000** | **27.4%** | *** ## How It Works This metric aggregates 75% video views from Meta, Google, and TikTok into a single number. A view counts when someone watches at least three-quarters of your video ad. This indicates strong engagement—viewers are invested enough to watch most of your content rather than skipping early. *** ## When to Use | Scenario | Action | | -------------------------------------- | -------------------------------------------------------- | | Measuring deep content engagement | Track 75% views to identify videos that hold attention | | Comparing creative performance | Higher 75% rates indicate more compelling content | | Optimizing for consideration campaigns | Use as a benchmark for mid-funnel video effectiveness | | Allocating budget across platforms | Shift spend toward platforms with higher deep engagement | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | [Blended Video Views (50%)](/reference/metrics/advertising/blended/blended-video/blended-video-views-50) | Lower engagement threshold—viewers watched half | | [Blended Video Views (100%)](/reference/metrics/advertising/blended/blended-video/blended-video-views-100) | Highest engagement—video watched to completion | | [Blended ThruPlay Views](/reference/metrics/advertising/blended/blended-video/blended-thruplay-views) | 15-second or completion views | [See all Blended Video metrics →](/reference/metrics/advertising/blended/blended-video) # Blended Video: Aggregated Video Performance Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/blended-video/index Track video ad performance across all platforms. Includes Blended Video Views, completion rates, ThruPlay, and cost metrics. Video metrics measure how users engage with video ads across all connected platforms—views, completion rates, and view costs. **Data Source:** Meta Ads, Google Ads, TikTok Ads (aggregated)\ **Metrics:** 19 ## Metrics in This Group | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- | ----------------------------- | | [Blended Video Views](/reference/metrics/advertising/blended/blended-video/blended-video-views) | Number of video views across all channels | Measure total video reach | | [Blended CPV](/reference/metrics/advertising/blended/blended-video/blended-cpv) | Cost per video view | Evaluate view cost efficiency | | [Blended 15s Video Views](/reference/metrics/advertising/blended/blended-video/blended-15-second-video-views) | Views reaching 15 seconds | Measure short-form engagement | | [Blended Cost per 15s View](/reference/metrics/advertising/blended/blended-video/blended-cost-per-15-second-video-view) | Cost per 15-second view | Cost for short attention | | [Blended 30s Video Views](/reference/metrics/advertising/blended/blended-video/blended-30-second-video-views) | Views reaching 30 seconds | Measure mid-length engagement | | [Blended Cost per 30s View](/reference/metrics/advertising/blended/blended-video/blended-cost-per-30-second-video-view) | Cost per 30-second view | Cost for longer attention | | [Blended 25% Video Views](/reference/metrics/advertising/blended/blended-video/blended-25-percent-video-views) | Views reaching 25% completion | Early retention metric | | [Blended 50% Video Views](/reference/metrics/advertising/blended/blended-video/blended-50-percent-video-views) | Views reaching 50% completion | Midpoint retention | | [Blended 75% Video Views](/reference/metrics/advertising/blended/blended-video/blended-75-percent-video-views) | Views reaching 75% completion | Strong retention signal | | [Blended 95% Video Views](/reference/metrics/advertising/blended/blended-video/blended-95-percent-video-views) | Views reaching 95% completion | Near-complete views | | [Blended 100% Video Views](/reference/metrics/advertising/blended/blended-video/blended-100-percent-video-views) | Views watching to completion | Full completion count | | [Blended 25% Completion Rate](/reference/metrics/advertising/blended/blended-video/blended-25-percent-video-completion-rate) | Percentage reaching 25% | Early drop-off rate | | [Blended 50% Completion Rate](/reference/metrics/advertising/blended/blended-video/blended-50-percent-video-completion-rate) | Percentage reaching 50% | Midpoint retention rate | | [Blended 75% Completion Rate](/reference/metrics/advertising/blended/blended-video/blended-75-percent-video-completion-rate) | Percentage reaching 75% | Strong engagement rate | | [Blended 100% Completion Rate](/reference/metrics/advertising/blended/blended-video/blended-100-percent-video-completion-rate) | Percentage completing video | Full completion rate | | [Blended ThruPlay Views](/reference/metrics/advertising/blended/blended-video/blended-video-thruplay-views) | ThruPlay views (15s or complete) | Quality view count | | [Blended Cost per ThruPlay](/reference/metrics/advertising/blended/blended-video/blended-cost-per-video-thruplay) | Cost per ThruPlay | Cost for quality views | | [Blended Video Plays](/reference/metrics/advertising/blended/blended-video/blended-video-plays) | Video play initiations | Total play starts | | [Blended Cost per Play](/reference/metrics/advertising/blended/blended-video/blended-cost-per-video-play) | Cost per video play | Cost per play initiation | ## How These Metrics Relate Video metrics measure progressive engagement: * **Video Plays** = initial play starts (includes autoplay) * **Video Views** = meaningful view threshold met * **25% → 100% Views** = progressive completion milestones * **ThruPlay** = watched 15+ seconds or to completion Completion rates = X% Views ÷ Video Views × 100 ## Choosing the Right Metric * **Brand awareness**: Track Video Views and ThruPlay for reach * **Content quality**: Compare completion rates to identify engaging content * **Cost efficiency**: Use CPV and Cost per ThruPlay for video campaign optimization * **Funnel analysis**: Track drop-off at each quartile to identify where viewers lose interest # Blended Advertising Metrics Source: https://docs.upstackdata.com/reference/metrics/advertising/blended/index Cross-platform advertising metrics aggregated across Meta, Google, and TikTok. Track total spend, reach, and efficiency without switching between ad platforms. Blended metrics aggregate advertising data from all connected ad platforms—Meta, Google, and TikTok—into unified performance views. Instead of checking each platform separately, see total spend, combined reach, and overall efficiency in one place. **Data Sources:** [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok)\ **Categories:** 5 ## Metric Categories **1 metric** — Total advertising spend across all platforms. **5 metrics** — Cross-platform reach, impressions, frequency, and audience costs. **15 metrics** — Click metrics, CTR, and cost-per-click across all platforms. **6 metrics** — Cross-platform ROAS, CPA, and return metrics. **Multiple metrics** — Aggregated conversion events and values. ## Why Use Blended Metrics * **Unified view**: See total marketing performance without platform-switching * **Budget analysis**: Track combined spend and efficiency across all channels * **Cross-platform reach**: Understand total audience exposure * **Simplified reporting**: Export single metrics instead of platform-by-platform data ## How Blended Metrics Work Blended metrics aggregate data from each connected ad platform: 1. **Meta Ads** — Campaign, ad set, and ad-level data via Marketing API 2. **Google Ads** — Campaign performance via Google Ads API 3. **TikTok Ads** — Campaign data via TikTok Marketing API Data is pulled daily and aggregated at the metric level. Platform-specific breakdowns remain available in their respective metric categories. # Google CPM: Cost Per Thousand Impressions Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-audience/google-cpm Track your Google Ads cost per thousand impressions. Measure how efficiently your ad budget reaches audiences and optimize for better CPM. Google CPM measures how much you pay for every 1,000 times your Google ad is shown—lower CPM means your budget reaches more people. ## Formula **Google CPM** = ( [**Google Spend**](/reference/metrics/advertising/google/google-spend/google-spend) ÷ [**Google Impressions**](/reference/metrics/advertising/google/google-audience/google-impressions) ) × 1,000 ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------- | ------------------------------------------ | | [**Google Spend**](/reference/metrics/advertising/google/google-spend/google-spend) | Total amount spent on Google advertising | | [**Google Impressions**](/reference/metrics/advertising/google/google-audience/google-impressions) | Total times your Google ads were displayed | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Ratio | *** ## Example A home décor brand spent **\$2,400** on Google Display ads in March and received **1,200,000 impressions**: | Metric | Value | Calculation | | ------------------ | ---------- | --------------------------- | | Google Spend | \$2,400 | — | | Google Impressions | 1,200,000 | — | | **Google CPM** | **\$2.00** | \$2,400 ÷ 1,200,000 × 1,000 | *** ## How It Works Google CPM divides your total ad spend by the number of impressions, then multiplies by 1,000 to express the cost per thousand views. This metric helps you understand the efficiency of your awareness campaigns where reach matters more than clicks. *** ## When to Use | Scenario | Action | | --------------------------------------- | ------------------------------------ | | Comparing brand awareness campaigns | Lower CPM = more efficient reach | | Evaluating Display vs. YouTube spend | Compare CPM across campaign types | | Assessing audience targeting efficiency | High CPM may signal narrow targeting | | Budget planning for impressions | Forecast spend based on target reach | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------- | -------------------------- | | [Google Spend](/reference/metrics/advertising/google/google-spend/google-spend) | Numerator—total ad cost | | [Google Impressions](/reference/metrics/advertising/google/google-audience/google-impressions) | Denominator—total ad views | [See all Google Audience metrics →](/reference/metrics/advertising/google/google-audience) # Google Frequency: Average Ad Views Per Person Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-audience/google-frequency Track Google Frequency to measure how often each person sees your ads. Monitor ad fatigue, optimize campaign reach, and improve Google Ads performance. Google Frequency measures the average number of times each person saw your Google ads. ## Formula **Google Frequency** = [**Google Impressions**](/reference/metrics/advertising/google/google-audience/google-impressions) ÷ **Reach** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | [**Google Impressions**](/reference/metrics/advertising/google/google-audience/google-impressions) | Total number of times your Google ads were displayed | | **Reach** | Number of unique people who saw your ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Ratio | *** ## Example A skincare brand running Google Display campaigns sees **125,000 impressions** reaching **25,000 unique users** during a product launch. | Metric | Value | Calculation | | -------------------- | ------- | ----------------- | | Google Impressions | 125,000 | Total ad displays | | Reach | 25,000 | Unique viewers | | **Google Frequency** | **5.0** | 125,000 ÷ 25,000 | Each person saw the ad an average of 5 times during the campaign. *** ## How It Works Google calculates frequency by dividing total impressions by the number of unique users reached. This metric only counts unique people—if someone sees your ad on multiple devices, they're counted once. High frequency can lead to ad fatigue, reducing campaign effectiveness over time. *** ## When to Use | Scenario | Action | | ----------------------------- | ----------------------------------------------------------------------------- | | Frequency above 7-10 | Refresh creative or expand targeting to reduce ad fatigue | | Low frequency with high reach | Increase frequency caps to boost message retention | | Brand awareness campaigns | Target 3-5 frequency for optimal recall | | Retargeting campaigns | Monitor closely—higher frequency acceptable but watch for diminishing returns | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------- | -------------------------------------- | | [Google Impressions](/reference/metrics/advertising/google/google-audience/google-impressions) | Numerator in the frequency calculation | [See all Google Audience metrics →](/reference/metrics/advertising/google/google-audience) # Google Impressions: Ad Visibility Metric Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-audience/google-impressions Track how many times your Google ads were shown to users. Measure reach and visibility across Search, Display, and YouTube campaigns. Google Impressions measures the total number of times your Google ads appeared in front of users. ## Formula **Google Impressions** = **COUNT** ( Ad Impressions ) | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Sum | *** ## Example Your Google campaigns reached **1.2 million impressions** in January across different ad types: | Campaign Type | Impressions | Share | | --------------- | ----------- | ----- | | Search Ads | 450,000 | 37.5% | | Display Network | 520,000 | 43.3% | | YouTube Ads | 230,000 | 19.2% | *** ## How It Works Google counts one impression each time your ad is shown on a search results page, website, or video. Display ads count when the ad loads in the viewable area. Search ads count when your ad appears for a user's query. *** ## When to Use | Scenario | Action | | ------------------------- | --------------------------------------------------------- | | Measuring brand awareness | Track total reach of your campaigns | | Evaluating campaign scale | Compare impression volume across campaigns | | Diagnosing low clicks | High impressions with low clicks signals targeting issues | | Calculating CPM | Divide Spend by Impressions × 1,000 | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------ | -------------------------------------------- | | [Google CPM](/reference/metrics/advertising/google/google-audience/google-cpm) | Cost per 1,000 impressions | | [Google CTR](/reference/metrics/advertising/google/google-clicks/google-ctr) | Clicks ÷ Impressions (click-through rate) | | [Google Frequency](/reference/metrics/advertising/google/google-audience/google-frequency) | Impressions ÷ Reach (average views per user) | | [Google Clicks](/reference/metrics/advertising/google/google-clicks/google-clicks) | User engagement from these impressions | [See all Google Audience metrics →](/reference/metrics/advertising/google/google-audience) # Google Audience: Reach and Impression Metrics for Google Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-audience/index Track Google Ads audience metrics in Upstack. Includes Google Impressions, Google CPM, and Google Frequency with formulas and optimization tips. Audience metrics measure the reach and exposure of your Google ads—how many times your ads were shown and how efficiently you're reaching your target audience. Use these to evaluate campaign scale and impression efficiency. **Data Source:** [Google Ads](/sources/google-ads)\ **Metrics:** 3 ## Metrics in This Group | Metric | Description | When to Use | | ---------------------------------------------------------------------------------------------- | ------------------------------ | ------------------------- | | [Google Impressions](/reference/metrics/advertising/google/google-audience/google-impressions) | Number of times ads were shown | Measure campaign reach | | [Google CPM](/reference/metrics/advertising/google/google-audience/google-cpm) | Cost per thousand impressions | Evaluate reach efficiency | | [Google Frequency](/reference/metrics/advertising/google/google-audience/google-frequency) | Average views per person | Monitor ad fatigue risk | ## How These Metrics Relate These metrics form a hierarchy of audience measurement: * **Google Impressions** counts total ad views across all users * **Google CPM** = Google Spend ÷ Google Impressions × 1,000 (cost to reach 1,000 people) * **Google Frequency** = Google Impressions ÷ Reach (how often each person sees your ad) ## Choosing the Right Metric * **Brand awareness campaigns**: Use Impressions and CPM to maximize reach within budget * **Ad fatigue monitoring**: Track Frequency to avoid overexposing your audience (typically keep below 3-5x) * **Efficiency benchmarking**: Compare CPM across campaigns to find cost-effective audience targeting # Google Clicks: Total Ad Click Volume Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-clicks/google-clicks Track total clicks on your Google ads to measure audience engagement and traffic generation from your campaigns. Google Clicks measures the total number of times users clicked on your Google ads. ## Formula **Google Clicks** = **COUNT** ( Ad Clicks ) | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Sum | *** ## Example Your fitness apparel brand ran Google Shopping ads in March, generating **18,432 clicks** across your campaigns. | Campaign | Clicks | Spend | | ----------------------- | ------ | ------- | | Brand Search | 8,241 | \$2,472 | | Shopping - Best Sellers | 6,105 | \$4,884 | | Performance Max | 4,086 | \$3,269 | *** ## How It Works Google Clicks counts every instance a user clicks on your ad. This includes clicks to your website, app installs, phone calls, and map directions—depending on your campaign type and ad format. Google deduplicates invalid clicks automatically. *** ## When to Use | Scenario | Action | | -------------------------------------- | ----------------------------------------------- | | Low traffic despite high impressions | Improve ad copy and creative relevance | | Clicks increasing but conversions flat | Review landing page experience | | Budget constrained campaigns | Prioritize campaigns with highest click volume | | Comparing campaign performance | Use clicks alongside CTR for engagement context | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------- | -------------------------------------------------------------- | | [Google CTR](/reference/metrics/advertising/google/google-clicks/google-ctr) | Click-through rate shows clicks as a percentage of impressions | | [Google CPC](/reference/metrics/advertising/google/google-clicks/google-cpc) | Cost per click divides spend by total clicks | [See all Google Clicks metrics →](/reference/metrics/advertising/google/google-clicks) # Google CPC: Cost Per Click on Your Google Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-clicks/google-cpc Track your Google CPC to measure average cost per ad click. Lower CPC means more traffic for your budget—optimize bids and quality scores. Google CPC measures the average amount you pay each time someone clicks your Google ad. ## Formula **Google CPC** = [**Google Spend**](/reference/metrics/advertising/google/google-spend/google-spend) ÷ [**Google Clicks**](/reference/metrics/advertising/google/google-clicks/google-clicks) ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------- | ---------------------------------------- | | [**Google Spend**](/reference/metrics/advertising/google/google-spend/google-spend) | Total amount spent on Google advertising | | [**Google Clicks**](/reference/metrics/advertising/google/google-clicks/google-clicks) | Total clicks on your Google ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Ratio | *** ## Example Your skincare brand spent **\$2,450** on Google Ads last week and received **3,500 clicks**: | Metric | Value | | -------------- | ---------- | | Google Spend | \$2,450 | | Google Clicks | 3,500 | | **Google CPC** | **\$0.70** | *** ## How It Works Google CPC divides your total Google ad spend by the number of clicks received. This metric reflects your average cost efficiency—lower CPC means you're acquiring more traffic for each dollar spent. *** ## When to Use | Scenario | Action | | ----------------------------- | ---------------------------------------------- | | Comparing campaign efficiency | Identify which campaigns drive cheaper traffic | | Budget optimization | Shift spend to lower-CPC keywords | | Quality Score analysis | High CPC may signal low relevance scores | | Competitive benchmarking | Compare CPC against industry averages | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------- | -------------------------- | | [Google Spend](/reference/metrics/advertising/google/google-spend/google-spend) | Numerator in CPC formula | | [Google Clicks](/reference/metrics/advertising/google/google-clicks/google-clicks) | Denominator in CPC formula | [See all Google Clicks metrics →](/reference/metrics/advertising/google/google-clicks) # Google CTR: Click-Through Rate for Google Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-clicks/google-ctr Measure your Google Ads click-through rate. See what percentage of impressions convert to clicks and optimize ad relevance. Google CTR measures the percentage of people who saw your Google ad and clicked on it. ## Formula **Google CTR** = ( [**Google Clicks**](/reference/metrics/advertising/google/google-clicks/google-clicks) ÷ [**Google Impressions**](/reference/metrics/advertising/google/google-audience/google-impressions) ) × 100 ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | [**Google Clicks**](/reference/metrics/advertising/google/google-clicks/google-clicks) | Total number of clicks on your Google ads | | [**Google Impressions**](/reference/metrics/advertising/google/google-audience/google-impressions) | Total number of times your Google ads were displayed | | Metadata | | | --------------- | --------------------------------- | | **Type** | Percentage | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Ratio | *** ## Example A home goods store ran Google Search ads during a spring sale promotion: | Campaign | Impressions | Clicks | CTR | | ------------------- | ----------- | ------ | ----- | | Spring Bedding Sale | 45,000 | 1,800 | 4.00% | | Outdoor Furniture | 32,000 | 960 | 3.00% | | Kitchen Appliances | 28,000 | 560 | 2.00% | *** ## How It Works CTR is calculated by dividing clicks by impressions and multiplying by 100. Higher CTR signals your ad copy and targeting resonate with your audience. Google uses CTR as a key factor in Quality Score, which affects ad rank and cost-per-click. *** ## When to Use | Scenario | Action | | ---------------------------- | ----------------------------------------- | | Low CTR on search campaigns | Test new ad headlines and descriptions | | CTR varies by device | Adjust bids or create device-specific ads | | High impressions, low clicks | Refine keyword targeting or audience | | Comparing ad variations | Use CTR to identify winning creative | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------- | ------------------------------ | | [Google Clicks](/reference/metrics/advertising/google/google-clicks/google-clicks) | Numerator in CTR calculation | | [Google Impressions](/reference/metrics/advertising/google/google-audience/google-impressions) | Denominator in CTR calculation | [See all Google Clicks metrics →](/reference/metrics/advertising/google/google-clicks) # Google Clicks: Click Engagement Metrics for Google Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-clicks/index Track Google Ads click metrics in Upstack. Includes Google Clicks, Google CPC, and Google CTR with formulas, examples, and optimization tips. Click metrics measure user engagement with your Google ads—from total clicks to click-through rates. Use these to evaluate ad relevance, creative performance, and traffic generation efficiency. **Data Source:** [Google Ads](/sources/google-ads)\ **Metrics:** 3 ## Metrics in This Group | Metric | Description | When to Use | | ---------------------------------------------------------------------------------- | ------------------- | ---------------------------- | | [Google Clicks](/reference/metrics/advertising/google/google-clicks/google-clicks) | Total clicks on ads | Measure traffic generation | | [Google CPC](/reference/metrics/advertising/google/google-clicks/google-cpc) | Cost per click | Evaluate click efficiency | | [Google CTR](/reference/metrics/advertising/google/google-clicks/google-ctr) | Click-through rate | Compare creative performance | ## How These Metrics Relate Click metrics connect impressions to traffic: * **Google Clicks** counts total user clicks on your ads * **Google CPC** = Google Spend ÷ Google Clicks (cost efficiency per click) * **Google CTR** = Google Clicks ÷ Google Impressions × 100 (engagement rate) ## Choosing the Right Metric * **Traffic campaigns**: Use Clicks to measure absolute volume of site visitors from ads * **Cost efficiency**: Compare CPC across campaigns to find cost-effective traffic sources * **Creative testing**: Use CTR to compare ad copy, images, and headlines—higher CTR signals stronger relevance * **Quality Score impact**: Google uses CTR as a signal for ad relevance, affecting your ad position and costs # Google All Conversions: Total Conversion Actions Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-conversions/google-all-conversions Track the total number of conversion actions from your Google Ads campaigns, including purchases, sign-ups, and other goals. Google All Conversions measures all conversion actions tracked by Google from your ads, including purchases, sign-ups, and other configured goals. ## Formula **Google All Conversions** = **COUNT** ( All Conversion Actions ) | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Sum | *** ## Example Your online store ran a Google Ads campaign in March that generated **2,847 total conversions** across all configured goals. | Conversion Type | Count | Percentage | | ------------------- | --------- | ---------- | | Purchases | 1,523 | 53.5% | | Newsletter Sign-ups | 892 | 31.3% | | Add to Cart | 432 | 15.2% | | **Total** | **2,847** | 100% | *** ## How It Works Google All Conversions counts every conversion action Google attributed to your ads based on your configured conversion goals. This includes all conversion types you've set up in Google Ads—purchases, form submissions, phone calls, app installs, and any custom goals. The metric reflects Google's own attribution model. *** ## When to Use | Scenario | Action | | ------------------------------- | ------------------------------------------------------------------- | | Measuring total campaign impact | Compare all conversions across campaigns to identify top performers | | Evaluating conversion volume | Track whether ad spend drives meaningful user actions | | Comparing attribution models | Cross-reference with Upstack-attributed conversions | | Optimizing for multiple goals | Monitor all conversion types, not just purchases | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | [Google Purchases](/reference/metrics/advertising/google/google-conversions/google-purchases) | Subset focusing only on purchase conversions | | [Google All Conversions Value](/reference/metrics/advertising/google/google-conversions/google-all-conversions-value) | Monetary value of all conversions | [See all Google Conversions metrics →](/reference/metrics/advertising/google/google-conversions) # Google All Conversions Value: Total Revenue from All Google Conversion Types Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-conversions/google-all-conversions-value Track the total monetary value of all conversion actions from your Google Ads campaigns, including purchases, sign-ups, and other goals. Google All Conversions Value measures the total monetary value of all conversion actions tracked by Google Ads, including purchases, lead submissions, sign-ups, and other configured goals. ## Formula **Google All Conversions Value** = **SUM** ( Conversion Value ) | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Sum | *** ## Example Your fitness apparel brand ran Google Search and Shopping campaigns in March, generating **\$47,850 in All Conversions Value**: | Conversion Type | Count | Value | | ------------------- | --------- | ------------ | | Purchases | 312 | \$38,940 | | Newsletter Sign-ups | 1,847 | \$5,541 | | Account Creations | 673 | \$3,369 | | **Total** | **2,832** | **\$47,850** | *** ## How It Works Google tracks value for every configured conversion action—not just purchases. Each conversion type can have an assigned value (fixed or dynamic), and this metric sums all values across all goal types within your selected date range. *** ## When to Use | Scenario | Action | | ------------------------------- | ------------------------------------------------------------------------- | | Measuring total campaign impact | Compare All Conversions Value across campaigns to see full business value | | Evaluating micro-conversion ROI | Assess whether sign-ups and leads contribute meaningful value | | Campaign budget allocation | Shift spend toward campaigns generating highest total value | | Full-funnel reporting | Report on all value driven by Google Ads, not just purchases | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- | | [Google All Conversions](/reference/metrics/advertising/google/google-conversions/google-all-conversions) | Count of all conversions (volume behind this value) | | [Google All Conversions ROAS](/reference/metrics/advertising/google/google-efficiency/google-all-conversions-roas) | Return on ad spend using this value metric | [See all Google Conversions metrics →](/reference/metrics/advertising/google/google-conversions) # Google Average All Conversion Value: Value Per Conversion Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-conversions/google-average-all-conversion-value Track Google Ads average conversion value to understand the typical worth of each conversion action across all goal types. Google Average All Conversion Value measures the typical monetary worth of each conversion action from your Google Ads campaigns. ## Formula **Google Average All Conversion Value** = [**Google All Conversions Value**](/reference/metrics/advertising/google/google-conversions/google-all-conversions-value) ÷ [**Google All Conversions**](/reference/metrics/advertising/google/google-conversions/google-all-conversions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [**Google All Conversions Value**](/reference/metrics/advertising/google/google-conversions/google-all-conversions-value) | Total monetary value from all conversion actions | | [**Google All Conversions**](/reference/metrics/advertising/google/google-conversions/google-all-conversions) | Total count of all conversion actions | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Ratio | *** ## Example A DTC brand's Google Shopping campaign generated **\$47,500 in total conversion value** from **950 conversions** last month. | Metric | Value | Calculation | | ------------------------- | ----------- | ---------------------------- | | All Conversions Value | \$47,500 | Sum of all conversion values | | All Conversions | 950 | Total conversion count | | **Avg. Conversion Value** | **\$50.00** | \$47,500 ÷ 950 | *** ## How It Works Google calculates this by dividing the total value assigned to all conversion actions by the number of conversions. This includes all goal types—purchases, leads, signups, and any other configured conversion actions. Values are assigned based on your conversion tracking setup. *** ## When to Use | Scenario | Action | | --------------------------------- | -------------------------------------------------------------------------------- | | Evaluating campaign profitability | Compare avg. conversion values across campaigns to prioritize high-value traffic | | Setting bidding strategies | Use as a baseline when configuring value-based bidding | | Identifying audience segments | Find audiences that generate higher-value conversions | | Comparing ad formats | Assess whether Shopping vs. Search drives more valuable conversions | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------------------- | ------------------------------- | | [Google All Conversions](/reference/metrics/advertising/google/google-conversions/google-all-conversions) | Denominator in this calculation | | [Google All Conversions Value](/reference/metrics/advertising/google/google-conversions/google-all-conversions-value) | Numerator in this calculation | [See all Google Conversions metrics →](/reference/metrics/advertising/google/google-conversions) # Google Average Purchase Value: Revenue Per Conversion Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-conversions/google-average-purchase-value Track the average revenue per Google Ads purchase. Optimize campaigns for higher-value conversions and improve overall ROAS. Google Average Purchase Value measures the average order value for purchases attributed to your Google ads. ## Formula **Google Average Purchase Value** = [**Google Purchases Value**](/reference/metrics/advertising/google/google-conversions/google-purchases-value) ÷ [**Google Purchases**](/reference/metrics/advertising/google/google-conversions/google-purchases) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | [**Google Purchases Value**](/reference/metrics/advertising/google/google-conversions/google-purchases-value) | Total revenue from purchases attributed to Google ads | | [**Google Purchases**](/reference/metrics/advertising/google/google-conversions/google-purchases) | Number of purchases attributed to Google ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Ratio | *** ## Example Your Google Search campaigns generated **\$28,450 in attributed revenue** from **215 purchases** last month. | Campaign | Purchases Value | Purchases | Avg Purchase Value | | ---------------- | --------------- | --------- | ------------------ | | Brand Search | \$15,200 | 95 | \$160.00 | | Non-Brand Search | \$8,750 | 85 | \$102.94 | | Shopping | \$4,500 | 35 | \$128.57 | | **Total** | **\$28,450** | **215** | **\$132.33** | *** ## How It Works This metric divides total Google-attributed revenue by the number of Google-attributed purchases. Higher values indicate your ads are driving customers who spend more per order, improving the efficiency of your ad spend. *** ## When to Use | Scenario | Action | | ------------------------------- | ------------------------------------------------------------- | | Comparing campaign quality | Identify which campaigns drive higher-value customers | | Budget allocation | Shift spend toward campaigns with higher average order values | | Audience targeting optimization | Test audiences to find segments that spend more | | Seasonal analysis | Track how purchase values change during promotions | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | [Google Purchases Value](/reference/metrics/advertising/google/google-conversions/google-purchases-value) | Numerator: total revenue attributed to Google | | [Google Purchases](/reference/metrics/advertising/google/google-conversions/google-purchases) | Denominator: purchase count | [See all Google Conversions metrics →](/reference/metrics/advertising/google/google-conversions) # Google Purchases: Ad-Attributed Purchase Count Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-conversions/google-purchases Track the number of purchases attributed to your Google ads. Monitor purchase conversion volume and campaign effectiveness. Google Purchases is the total number of purchase conversions that Google attributes to your ads. ## Formula **Google Purchases** = **COUNT** ( Purchase Conversions ) | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Count | *** ## Example A fitness equipment store ran **\$12,500** in Google Ads last month: | Campaign | Purchases | Spend | CPA | | --------------- | --------- | ------------ | -------- | | Brand Search | 187 | \$2,800 | \$15 | | Shopping | 124 | \$5,200 | \$42 | | Performance Max | 89 | \$4,500 | \$51 | | **Total** | **400** | **\$12,500** | **\$31** | *** ## How It Works Google tracks purchase conversion events triggered by users who interacted with your ads. This count is pulled directly from the Google Ads API and reflects Google's attribution model for determining which purchases resulted from your advertising. *** ## When to Use | Scenario | Action | | --------------------------- | ------------------------------------------------------- | | Measuring conversion volume | Compare purchase counts across campaigns | | Calculating CPA | Divide spend by purchases to find cost per acquisition | | Scaling campaigns | Identify campaigns generating the most purchases | | Attribution comparison | Compare Google-attributed purchases to first-party data | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | [Google Purchases Value](/reference/metrics/advertising/google/google-conversions/google-purchases-value) | Revenue generated from these purchases | | [Google ROAS](/reference/metrics/advertising/google/google-efficiency/google-roas) | Return on ad spend using purchases value | | [Google CPA](/reference/metrics/advertising/google/google-efficiency/google-cpa) | Cost per purchase acquisition | [See all Google Conversions metrics →](/reference/metrics/advertising/google/google-conversions) # Google Purchases Value: Google-Attributed Revenue Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-conversions/google-purchases-value Track total revenue from purchases attributed to your Google ads. Monitor Google-reported purchase conversions and revenue performance. Google Purchases Value is the total revenue from purchases that Google attributes to your ads based on purchase conversion events. ## Formula **Google Purchases Value** = **SUM** ( Purchase Revenue ) | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Sum | *** ## Example A home goods store spent **\$8,400** on Google Ads last month: | Campaign | Purchases | Purchases Value | Avg. Order | | --------------- | --------- | --------------- | ---------- | | Brand Search | 142 | \$18,460 | \$130 | | Shopping | 89 | \$9,790 | \$110 | | Performance Max | 67 | \$8,710 | \$130 | | **Total** | **298** | **\$36,960** | **\$124** | *** ## How It Works Google tracks purchase conversion events triggered by your ads and sums the revenue values. This data is pulled directly from the Google Ads API and reflects Google's attribution of revenue to your advertising campaigns. *** ## When to Use | Scenario | Action | | --------------------------- | -------------------------------------------------------- | | Measuring ad-driven revenue | Compare purchases value across campaigns | | Calculating ROAS | Divide purchases value by spend | | Budget allocation | Shift spend toward campaigns with higher purchases value | | Conversion optimization | Track revenue trends after bid strategy changes | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [Google Purchases](/reference/metrics/advertising/google/google-conversions/google-purchases) | Count of purchase conversions driving this revenue | | [Google ROAS](/reference/metrics/advertising/google/google-efficiency/google-roas) | Efficiency ratio using this as numerator | [See all Google Conversions metrics →](/reference/metrics/advertising/google/google-conversions) # Google Video Views: Track Video Ad Engagement Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-conversions/google-video-views Track video views from your Google video ad campaigns. Measure audience engagement with your video content across YouTube and Google Display Network. Google Video Views measures the total number of times users watched your Google video ads (typically 30+ seconds or the full video if shorter). ## Formula **Google Video Views** = **COUNT** ( Video Views ) | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Sum | *** ## Example A home fitness brand runs YouTube TrueView ads for their new workout equipment. **Over 2 weeks, their campaign generated 47,800 video views:** | Campaign | Impressions | Video Views | View Rate | | --------------------- | ----------- | ----------- | --------- | | Spring Fitness Launch | 215,000 | 32,400 | 15.1% | | Product Demo Series | 98,000 | 15,400 | 15.7% | | **Total** | **313,000** | **47,800** | **15.3%** | *** ## How It Works Google counts a video view when a user watches 30 seconds of your video ad (or the full ad if shorter than 30 seconds) or interacts with it, whichever comes first. This metric is pulled directly from your Google Ads account and reflects engagement with video campaigns across YouTube and the Google Display Network. *** ## When to Use | Scenario | Action | | ------------------------------- | ------------------------------------------------------ | | Measuring brand awareness | Track video views as a top-funnel engagement indicator | | Evaluating creative performance | Compare view counts across different video creatives | | Optimizing video campaigns | Identify which audiences complete more video views | | Budget allocation | Shift spend toward campaigns with higher view volume | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------- | ------------------------------ | | [Google CPV](/reference/metrics/advertising/google/google-efficiency/google-cpv) | Cost efficiency per video view | [See all Google Conversions metrics →](/reference/metrics/advertising/google/google-conversions) # Google View-Through Conversions: Measure Impression Impact Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-conversions/google-view-through-conversions Track conversions from users who saw but didn't click your Google ad. Measure the impact of display and video impressions on conversions. View-through conversions count users who saw your Google ad, didn't click, but later converted—measuring the indirect impact of ad impressions. ## Formula **Google View-Through Conversions** = **COUNT** ( View-Through Conversions ) | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Sum | *** ## Example Your Display campaign generated **847 view-through conversions** last month: | Campaign | Impressions | Clicks | View-Thru Conv. | | ------------------------- | ----------- | ------ | --------------- | | Display - Retargeting | 450,000 | 2,100 | 412 | | YouTube - Brand Awareness | 320,000 | 890 | 298 | | Discovery - Prospecting | 180,000 | 650 | 137 | *** ## How It Works Google tracks when a user sees your ad impression, then converts within the view-through conversion window (typically 1-30 days) without ever clicking. This attribution helps quantify the value of awareness campaigns where users don't click but are influenced to convert later. *** ## When to Use | Scenario | Action | | ---------------------------- | ---------------------------------------------------- | | Evaluating Display campaigns | View-through conversions reveal impact beyond clicks | | YouTube brand awareness | Measure video ad influence on downstream conversions | | Retargeting effectiveness | Track users who saw ads and converted organically | | Full-funnel attribution | Combine with click conversions for complete picture | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- | | [Google Purchases](/reference/metrics/advertising/google/google-conversions/google-purchases) | Click-based conversions to compare against | | [Google Cost per View-Through Conversion](/reference/metrics/advertising/google/google-efficiency/google-cost-per-view-through-conversion) | Efficiency of impression-driven conversions | [See all Google Conversions metrics →](/reference/metrics/advertising/google/google-conversions) # Google Conversions: Purchase and Conversion Metrics for Google Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-conversions/index Track Google Ads conversion metrics in Upstack. Includes Google Purchases, All Conversions, Video Views, and View-Through Conversions with formulas and examples. Conversion metrics measure the outcomes of your Google advertising—purchases, conversion events, and video engagement. These metrics are reported directly by Google based on their attribution model. **Data Source:** [Google Ads](/sources/google-ads)\ **Metrics:** 8 ## Metrics in This Group | Metric | Description | When to Use | | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ----------------------------------- | | [Google Purchases](/reference/metrics/advertising/google/google-conversions/google-purchases) | Purchases attributed by Google | Count purchase conversions | | [Google Purchases Value](/reference/metrics/advertising/google/google-conversions/google-purchases-value) | Revenue from Google-attributed purchases | Measure revenue impact | | [Google Average Purchase Value](/reference/metrics/advertising/google/google-conversions/google-average-purchase-value) | Average order value per purchase | Evaluate conversion quality | | [Google All Conversions](/reference/metrics/advertising/google/google-conversions/google-all-conversions) | All tracked conversion actions | Count all goal completions | | [Google All Conversions Value](/reference/metrics/advertising/google/google-conversions/google-all-conversions-value) | Total value of all conversions | Measure total conversion value | | [Google Average All Conversion Value](/reference/metrics/advertising/google/google-conversions/google-average-all-conversion-value) | Average value per conversion | Evaluate overall conversion quality | | [Google Video Views](/reference/metrics/advertising/google/google-conversions/google-video-views) | Video ad views (30+ seconds) | Measure video engagement | | [Google View-Through Conversions](/reference/metrics/advertising/google/google-conversions/google-view-through-conversions) | Conversions after ad view (no click) | Measure impression-driven impact | ## How These Metrics Relate Google reports two levels of conversions: **Purchase-specific:** * **Google Purchases** = Count of purchase conversion events * **Google Purchases Value** = Total revenue from those purchases * **Google Average Purchase Value** = Purchases Value ÷ Purchases **All conversion types:** * **Google All Conversions** = Purchases + sign-ups + other tracked goals * **Google All Conversions Value** = Total value across all conversion types * **Google Average All Conversion Value** = All Conversions Value ÷ All Conversions **Engagement metrics:** * **Google Video Views** = Users who watched 30+ seconds (or full video if shorter) * **Google View-Through Conversions** = Users who saw ad but didn't click, then later converted ## Choosing the Right Metric * **E-commerce ROAS**: Use Purchases and Purchases Value for direct revenue attribution * **Lead generation**: Use All Conversions to track form submissions and sign-ups * **Brand campaigns**: Use Video Views to measure engagement, View-Through Conversions for awareness impact * **Full-funnel analysis**: Compare click-through vs view-through conversions to understand the customer journey # Google All Conversions ROAS: Full-Funnel Return on Ad Spend Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-efficiency/google-all-conversions-roas Measure the return on ad spend for all Google Ads conversions. Includes purchases, leads, sign-ups, and all tracked conversion actions—not just direct sales. Google All Conversions ROAS measures the revenue return on ad spend including all conversion types tracked by Google, not just purchases. ## Formula **Google All Conversions ROAS** = [**Google All Conversions Value**](/reference/metrics/advertising/google/google-conversions/google-all-conversions-value) ÷ [**Google Spend**](/reference/metrics/advertising/google/google-spend/google-spend) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | [**Google All Conversions Value**](/reference/metrics/advertising/google/google-conversions/google-all-conversions-value) | Total value from all conversion types tracked in Google Ads | | [**Google Spend**](/reference/metrics/advertising/google/google-spend/google-spend) | Total amount billed by Google for advertising | | Metadata | | | --------------- | --------------------------------- | | **Type** | Ratio | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Ratio | *** ## Example Your brand spent **\$8,000** on Google Ads last month and generated **\$28,000** in all conversions value: | Metric | Value | Calculation | | ------------------------ | --------- | ----------------------------------- | | All Conversions Value | \$28,000 | Includes purchases, leads, sign-ups | | Google Spend | \$8,000 | Total ad spend | | **All Conversions ROAS** | **3.50x** | \$28,000 ÷ \$8,000 | For every \$1 spent, you generated \$3.50 in total conversion value across all tracked conversion types. *** ## How It Works Google All Conversions ROAS divides the total value of all tracked conversions by your ad spend. Unlike standard ROAS which focuses on purchases, this metric includes the value of all conversion actions—leads, sign-ups, phone calls, and other goals you've assigned values to in Google Ads. *** ## When to Use | Scenario | Action | | -------------------------------- | ---------------------------------------------------- | | Evaluating full-funnel campaigns | Measure total value generated, not just direct sales | | Comparing lead gen vs e-commerce | Use for campaigns with mixed conversion goals | | Benchmarking Performance Max | Assess all conversion types in Smart campaigns | | Justifying upper-funnel spend | Show value beyond immediate purchases | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | [Google ROAS](/reference/metrics/advertising/google/google-efficiency/google-roas) | Purchase-only ROAS; use for direct sales comparison | | [Google All Conversions Value](/reference/metrics/advertising/google/google-conversions/google-all-conversions-value) | Numerator of this formula | [See all Google Efficiency metrics →](/reference/metrics/advertising/google/google-efficiency) # Google Cost per All Conversions: Efficiency Across All Goal Types Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-efficiency/google-cost-per-all-conversions Track your Google Ads cost per all conversions to measure efficiency across every conversion action. Optimize spend allocation by goal type. Google Cost per All Conversions measures how much you spend on average to drive each conversion action across all goal types in Google Ads. ## Formula **Google Cost per All Conversions** = [**Google Spend**](/reference/metrics/advertising/google/google-spend/google-spend) ÷ [**Google All Conversions**](/reference/metrics/advertising/google/google-conversions/google-all-conversions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | [**Google Spend**](/reference/metrics/advertising/google/google-spend/google-spend) | Total amount spent on Google Ads campaigns | | [**Google All Conversions**](/reference/metrics/advertising/google/google-conversions/google-all-conversions) | Total count of all conversion actions tracked by Google Ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Ratio | *** ## Example Your brand awareness campaign spent **\$3,200** in March and generated **640 all conversions** (including purchases, sign-ups, and video views). | Campaign | Spend | All Conversions | Cost/All Conv. | | --------------- | ------- | --------------- | -------------- | | Brand Awareness | \$3,200 | 640 | \$5.00 | | Retargeting | \$1,800 | 450 | \$4.00 | | Shopping | \$4,500 | 300 | \$15.00 | *** ## How It Works Google calculates this metric by dividing your total ad spend by the number of all conversions recorded. Unlike standard cost-per-conversion, this includes every conversion action—purchases, leads, phone calls, app installs, and micro-conversions like video engagement or page views. *** ## When to Use | Scenario | Action | | -------------------------------- | ----------------------------------------------------------------------- | | Comparing full-funnel efficiency | Use to evaluate campaigns tracking multiple conversion types | | Assessing awareness campaigns | Benchmark cost efficiency when optimizing for video views or engagement | | Evaluating lead gen performance | Track cost across form fills, calls, and chat initiations | | Setting bidding targets | Inform target CPA strategies that include all goal types | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------- | --------------------------- | | [Google Spend](/reference/metrics/advertising/google/google-spend/google-spend) | Numerator in this formula | | [Google All Conversions](/reference/metrics/advertising/google/google-conversions/google-all-conversions) | Denominator in this formula | [See all Google Efficiency metrics →](/reference/metrics/advertising/google/google-efficiency) # Google Cost per Purchase: Acquisition Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-efficiency/google-cost-per-purchase Track your Google Ads cost per purchase to measure acquisition efficiency. Calculate how much you spend to drive each conversion through Google campaigns. Google Cost per Purchase measures how much you spend on average to drive each purchase through your Google Ads campaigns. ## Formula **Google Cost per Purchase** = [**Google Spend**](/reference/metrics/advertising/google/google-spend/google-spend) ÷ [**Google Purchases**](/reference/metrics/advertising/google/google-conversions/google-purchases) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------- | --------------------------------------------- | | [**Google Spend**](/reference/metrics/advertising/google/google-spend/google-spend) | Total amount billed by Google for advertising | | [**Google Purchases**](/reference/metrics/advertising/google/google-conversions/google-purchases) | Number of purchases attributed to Google ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Ratio | *** ## Example A home decor store spent **\$4,200** on Google Ads in March and drove **84 purchases**. | Metric | Value | Calculation | | --------------------- | ----------- | ---------------------- | | Google Spend | \$4,200 | Total ad spend | | Google Purchases | 84 | Attributed conversions | | **Cost per Purchase** | **\$50.00** | \$4,200 ÷ 84 | *** ## How It Works Google Cost per Purchase divides your total Google Ads spend by the number of purchases attributed to those campaigns. Lower values indicate more efficient acquisition—you're spending less to acquire each customer through Google. *** ## When to Use | Scenario | Action | | ------------------------- | --------------------------------------------------------- | | High cost per purchase | Pause underperforming campaigns or ad groups | | Compare campaign types | Evaluate Search vs Shopping vs Performance Max efficiency | | Budget allocation | Shift spend to campaigns with lower acquisition costs | | Cross-platform comparison | Compare against Meta or TikTok cost per purchase | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------- | ------------------------------- | | [Google Spend](/reference/metrics/advertising/google/google-spend/google-spend) | Numerator in calculation | | [Google Purchases](/reference/metrics/advertising/google/google-conversions/google-purchases) | Denominator in calculation | | [Google ROAS](/reference/metrics/advertising/google/google-efficiency/google-roas) | Revenue-based efficiency metric | [See all Google Efficiency metrics →](/reference/metrics/advertising/google/google-efficiency) # Google Cost per View-Through Conversion: VTC Efficiency Metric Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-efficiency/google-cost-per-view-through-conversion Track your Google Ads cost per view-through conversion to measure impression-based campaign efficiency and optimize display and video advertising. Google Cost per View-Through Conversion measures how much you spend on average to drive each conversion from impression-only exposure in Google Ads. ## Formula **Google Cost per View-Through Conversion** = [**Google Spend**](/reference/metrics/advertising/google/google-spend/google-spend) ÷ [**Google View-Through Conversions**](/reference/metrics/advertising/google/google-conversions/google-view-through-conversions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [**Google Spend**](/reference/metrics/advertising/google/google-spend/google-spend) | Total amount spent on Google advertising | | [**Google View-Through Conversions**](/reference/metrics/advertising/google/google-conversions/google-view-through-conversions) | Conversions attributed to ad impressions without a click | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Ratio | *** ## Example Your home decor store spent **\$3,200** on Google Display campaigns in March, generating **128 view-through conversions**. | Metric | Value | Calculation | | ------------------------ | ----------- | --------------------------------- | | Google Spend | \$3,200 | Total ad spend | | View-Through Conversions | 128 | Impression-attributed conversions | | **Cost per VTC** | **\$25.00** | \$3,200 ÷ 128 | *** ## How It Works This metric divides your total Google ad spend by the number of view-through conversions. A view-through conversion occurs when someone sees your ad impression but converts later without clicking—common in display and video campaigns where brand awareness drives delayed action. *** ## When to Use | Scenario | Action | | ------------------------------- | -------------------------------------------------------------- | | Evaluating display campaign ROI | Compare Cost/VTC across ad groups to find efficient placements | | Assessing video campaign impact | Measure impression-based conversion efficiency | | Budget allocation decisions | Shift spend toward campaigns with lower Cost/VTC | | Justifying awareness spend | Demonstrate value of non-click conversions | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | [Google View-Through Conversions](/reference/metrics/advertising/google/google-conversions/google-view-through-conversions) | The denominator—total impression-attributed conversions | | [Google Spend](/reference/metrics/advertising/google/google-spend/google-spend) | The numerator—total ad spend driving these conversions | [See all Google Efficiency metrics →](/reference/metrics/advertising/google/google-efficiency) # Google CPA: Average Cost to Acquire a Purchase Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-efficiency/google-cpa Track your Google CPA to measure how much you spend on average to drive each purchase. Compare cost per acquisition across campaigns to optimize ad efficiency. Google CPA measures how much you spend on average to drive each purchase through Google Ads—lower is better. ## Formula **Google CPA** = [**Google Spend**](/reference/metrics/advertising/google/google-spend/google-spend) ÷ [**Google Purchases**](/reference/metrics/advertising/google/google-conversions/google-purchases) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------- | -------------------------------------------- | | [**Google Spend**](/reference/metrics/advertising/google/google-spend/google-spend) | Total amount spent on Google advertising | | [**Google Purchases**](/reference/metrics/advertising/google/google-conversions/google-purchases) | Number of purchases attributed to Google Ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Ratio | *** ## Example A home goods store spent **\$4,200** on Google Ads in March and drove **84 purchases**: | Metric | Value | Calculation | | ---------------- | ----------- | ------------ | | Google Spend | \$4,200 | — | | Google Purchases | 84 | — | | **Google CPA** | **\$50.00** | \$4,200 ÷ 84 | *** ## How It Works Google CPA divides your total Google ad spend by the number of purchases attributed to those ads. This gives you the average cost to acquire each conversion, helping you understand campaign efficiency at a glance. *** ## When to Use | Scenario | Action | | ----------------------------- | -------------------------------------------------- | | Comparing campaign efficiency | Lower CPA campaigns deliver purchases more cheaply | | Setting bidding targets | Use historical CPA to inform target CPA bidding | | Budget allocation | Shift spend toward campaigns with better CPA | | Evaluating profitability | Compare CPA against average order margin | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------- | | [Google Cost per Purchase](/reference/metrics/advertising/google/google-efficiency/google-cost-per-purchase) | Same calculation—CPA is a common abbreviation | | [Google ROAS](/reference/metrics/advertising/google/google-efficiency/google-roas) | Efficiency from the revenue perspective | | [Google Spend](/reference/metrics/advertising/google/google-spend/google-spend) | Numerator in the CPA formula | | [Google Purchases](/reference/metrics/advertising/google/google-conversions/google-purchases) | Denominator in the CPA formula | [See all Google Efficiency metrics →](/reference/metrics/advertising/google/google-efficiency) # Google CPV: Video Ad Cost Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-efficiency/google-cpv Track your Google CPV (cost per video view) to measure video ad efficiency. Calculate how much you pay each time someone watches your Google video ad. Google CPV measures how much you pay on average each time someone watches your Google video ad. ## Formula **Google CPV** = [**Google Spend**](/reference/metrics/advertising/google/google-spend/google-spend) ÷ [**Google Video Views**](/reference/metrics/advertising/google/google-conversions/google-video-views) ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | [**Google Spend**](/reference/metrics/advertising/google/google-spend/google-spend) | Total amount spent on Google advertising | | [**Google Video Views**](/reference/metrics/advertising/google/google-conversions/google-video-views) | Number of times users watched your Google video ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Ratio | *** ## Example A skincare brand runs YouTube ads promoting their new serum. Here's their weekly performance: | Campaign | Spend | Video Views | CPV | | --------------- | ------- | ----------- | ------ | | Product Demo | \$850 | 42,500 | \$0.02 | | Brand Story | \$1,200 | 30,000 | \$0.04 | | Tutorial Series | \$650 | 65,000 | \$0.01 | The Tutorial Series campaign delivers the lowest CPV at **\$0.01 per view**, making it the most efficient for building video engagement. *** ## How It Works Google CPV divides your total ad spend by the number of video views. A view is typically counted when someone watches at least 30 seconds of your video (or the entire video if shorter). Lower CPV means you're paying less for each viewer to engage with your video content. *** ## When to Use | Scenario | Action | | --------------------------------------- | ----------------------------------------------------------- | | Comparing video campaign efficiency | Lower CPV indicates better cost efficiency per viewer | | Setting video campaign budgets | Use historical CPV to forecast costs for target view counts | | Optimizing creative performance | Test different video formats and track CPV changes | | Benchmarking against industry standards | Compare your CPV to vertical averages | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------- | -------------------------------------------- | | [Google Video Views](/reference/metrics/advertising/google/google-conversions/google-video-views) | The denominator—total views driving your CPV | | [Google Spend](/reference/metrics/advertising/google/google-spend/google-spend) | The numerator—total cost divided by views | [See all Google Efficiency metrics →](/reference/metrics/advertising/google/google-efficiency) # Google ROAS: Measure Your Google Ads Return on Investment Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-efficiency/google-roas Track Google ROAS to measure revenue earned per dollar spent on Google Ads. Calculate return on ad spend and optimize your advertising efficiency. Google ROAS measures how much revenue you earn for every dollar spent on Google Ads. ## Formula **Google ROAS** = [**Google Purchases Value**](/reference/metrics/advertising/google/google-conversions/google-purchases-value) ÷ [**Google Spend**](/reference/metrics/advertising/google/google-spend/google-spend) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | [**Google Purchases Value**](/reference/metrics/advertising/google/google-conversions/google-purchases-value) | Revenue from purchases attributed to Google Ads | | [**Google Spend**](/reference/metrics/advertising/google/google-spend/google-spend) | Total amount spent on Google Ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Multiplier (displayed as Nx) | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Ratio | *** ## Example **Your Google Ads campaign generated \$12,500 in revenue from \$2,500 in ad spend:** | Metric | Value | | ---------------------- | -------- | | Google Purchases Value | \$12,500 | | Google Spend | \$2,500 | | **Google ROAS** | **5.0x** | A 5.0x ROAS means you earned \$5 in revenue for every \$1 spent on Google Ads. *** ## How It Works Google ROAS divides revenue from purchases attributed to your Google Ads by your total ad spend. A ROAS of 3x means \$3 in revenue per \$1 spent. Higher ROAS indicates more efficient advertising performance. *** ## When to Use | Scenario | Action | | --------------------------------- | --------------------------------------------------- | | Evaluating campaign profitability | Compare ROAS against your target (e.g., 3x minimum) | | Optimizing budget allocation | Shift spend toward campaigns with higher ROAS | | Testing ad creatives | Measure which variations drive better returns | | Setting bid strategies | Use target ROAS bidding in Google Ads | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | [Google Spend](/reference/metrics/advertising/google/google-spend/google-spend) | The denominator in the ROAS calculation | | [Google Purchases Value](/reference/metrics/advertising/google/google-conversions/google-purchases-value) | The numerator in the ROAS calculation | | [Google CPA](/reference/metrics/advertising/google/google-efficiency/google-cpa) | Cost efficiency metric—lower CPA often correlates with higher ROAS | [See all Google Efficiency metrics →](/reference/metrics/advertising/google/google-efficiency) # Google Efficiency: ROAS and Cost Efficiency Metrics for Google Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-efficiency/index Track Google Ads efficiency metrics in Upstack. Includes Google ROAS, Google CPA, and cost per conversion metrics with formulas and optimization tips. Efficiency metrics measure the return on your Google ad spend—how much revenue you generate per dollar spent and how efficiently you're acquiring conversions. Use these to optimize campaign performance and budget allocation. **Data Source:** [Google Ads](/sources/google-ads)\ **Metrics:** 7 ## Metrics in This Group | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | ----------------------------- | | [Google ROAS](/reference/metrics/advertising/google/google-efficiency/google-roas) | Return on ad spend | Measure revenue efficiency | | [Google CPA](/reference/metrics/advertising/google/google-efficiency/google-cpa) | Cost per purchase acquisition | Evaluate acquisition cost | | [Google Cost per Purchase](/reference/metrics/advertising/google/google-efficiency/google-cost-per-purchase) | Cost to acquire one purchase | Same as CPA, explicit naming | | [Google All Conversions ROAS](/reference/metrics/advertising/google/google-efficiency/google-all-conversions-roas) | ROAS across all conversion types | Measure full conversion value | | [Google Cost per All Conversions](/reference/metrics/advertising/google/google-efficiency/google-cost-per-all-conversions) | Cost per any conversion | Evaluate cost per goal | | [Google CPV](/reference/metrics/advertising/google/google-efficiency/google-cpv) | Cost per video view | Measure video ad efficiency | | [Google Cost per View-Through Conversion](/reference/metrics/advertising/google/google-efficiency/google-cost-per-view-through-conversion) | Cost per view-through conversion | Measure impression ROI | ## How These Metrics Relate Efficiency metrics are ratios of spend to outcomes: **Purchase-focused:** * **Google ROAS** = Purchases Value ÷ Spend (revenue return) * **Google CPA** = Spend ÷ Purchases (cost to acquire) * **Google Cost per Purchase** = Same formula as CPA **All conversions:** * **Google All Conversions ROAS** = All Conversions Value ÷ Spend * **Google Cost per All Conversions** = Spend ÷ All Conversions **Specialized:** * **Google CPV** = Spend ÷ Video Views * **Google Cost per View-Through Conversion** = Spend ÷ View-Through Conversions ## Choosing the Right Metric * **E-commerce profitability**: Use ROAS (target 3x+ for healthy margins) * **Acquisition budgeting**: Use CPA to set maximum bids based on customer LTV * **Lead generation**: Use Cost per All Conversions for non-purchase goals * **Video campaigns**: Use CPV to compare video ad efficiency * **Brand impact**: Use Cost per View-Through Conversion to value impression-only touchpoints # Google Spend: Total Ad Investment Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-spend/google-spend Track your total Google Ads spending to monitor budget utilization and control advertising costs across campaigns. Google Spend measures the total amount billed by Google for your ads in the selected period. ## Formula **Google Spend** = **SUM** ( Amount Spent ) | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Google Ads](/sources/google-ads) | | **Aggregation** | Sum | *** ## Example A home goods retailer spent **\$12,450** on Google Ads in March across their campaigns: | Campaign | Spend | Share of Budget | | ----------------------- | ------- | --------------- | | Shopping - Best Sellers | \$5,200 | 42% | | Search - Brand Terms | \$3,100 | 25% | | Performance Max | \$2,850 | 23% | | Display Remarketing | \$1,300 | 10% | *** ## How It Works Google Spend is pulled directly from the Google Ads API and represents actual charges to your account. This includes all costs across Search, Shopping, Display, Video, and Performance Max campaigns. The metric updates as Google processes billing events. *** ## When to Use | Scenario | Action | | ------------------- | ---------------------------------------------------------- | | Budget monitoring | Compare spend vs. allocated budget to prevent overspending | | Campaign allocation | Identify which campaigns consume the most budget | | Cost trend analysis | Track spending patterns over time to spot anomalies | | ROAS calculation | Use as denominator when calculating return on ad spend | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------- | -------------------------- | | [Google ROAS](/reference/metrics/advertising/google/google-efficiency/google-roas) | Revenue divided by spend | | [Google CPA](/reference/metrics/advertising/google/google-efficiency/google-cpa) | Spend divided by purchases | | [Google CPC](/reference/metrics/advertising/google/google-clicks/google-cpc) | Spend divided by clicks | [See all Google Spend metrics →](/reference/metrics/advertising/google/google-spend) # Google Spend: Ad Spend Metrics for Google Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/google/google-spend/index Track Google Ads spending metrics in Upstack. Monitor your Google advertising budget allocation and total ad spend with real-time data from the Google Ads API. Spend metrics track your Google Ads investment—how much you're spending on campaigns and where your advertising budget is allocated. Use these to monitor costs and compare spending across campaigns. **Data Source:** [Google Ads](/sources/google-ads)\ **Metrics:** 1 ## Metrics in This Group | Metric | Description | When to Use | | ------------------------------------------------------------------------------- | -------------------------------- | ---------------------------- | | [Google Spend](/reference/metrics/advertising/google/google-spend/google-spend) | Total amount spent on Google ads | Track advertising investment | ## How These Metrics Relate Google Spend is the foundation for all efficiency calculations: * **Google CPC** = Google Spend ÷ Google Clicks * **Google CPA** = Google Spend ÷ Google Purchases * **Google ROAS** = Google Purchases Value ÷ Google Spend * **Google CPM** = Google Spend ÷ Google Impressions × 1,000 ## Choosing the Right Metric * **Budget tracking**: Use Google Spend to monitor daily, weekly, or monthly ad investment * **Efficiency analysis**: Combine with conversion metrics to calculate ROAS and CPA * **Cross-channel comparison**: Compare Google Spend against Meta Spend or TikTok Spend for budget allocation decisions # Google Ads Metrics: Performance Tracking for Search, Display & YouTube Source: https://docs.upstackdata.com/reference/metrics/advertising/google/index Track Google Ads performance metrics in Upstack. Includes spend, clicks, impressions, conversions, ROAS, CPA, and video metrics from the Google Ads API. Google Ads metrics track performance across Search, Display, Shopping, and YouTube campaigns. These metrics are pulled directly from the Google Ads API and represent Google's reported attribution. **Data Source:** [Google Ads](/sources/google-ads)\ **Metrics:** 22\ **Subcategories:** 5 ## Metric Groups ### [Google Spend](/reference/metrics/advertising/google/google-spend) Track your Google advertising investment and budget allocation. | Metric | Description | | ------------------------------------------------------------------------------- | -------------------------------- | | [Google Spend](/reference/metrics/advertising/google/google-spend/google-spend) | Total amount spent on Google ads | ### [Google Audience](/reference/metrics/advertising/google/google-audience) Measure reach and impression efficiency across your campaigns. | Metric | Description | | ---------------------------------------------------------------------------------------------- | ------------------------------ | | [Google Impressions](/reference/metrics/advertising/google/google-audience/google-impressions) | Number of times ads were shown | | [Google CPM](/reference/metrics/advertising/google/google-audience/google-cpm) | Cost per thousand impressions | | [Google Frequency](/reference/metrics/advertising/google/google-audience/google-frequency) | Average views per person | ### [Google Clicks](/reference/metrics/advertising/google/google-clicks) Evaluate click engagement and traffic generation from your ads. | Metric | Description | | ---------------------------------------------------------------------------------- | ------------------- | | [Google Clicks](/reference/metrics/advertising/google/google-clicks/google-clicks) | Total clicks on ads | | [Google CPC](/reference/metrics/advertising/google/google-clicks/google-cpc) | Cost per click | | [Google CTR](/reference/metrics/advertising/google/google-clicks/google-ctr) | Click-through rate | ### [Google Conversions](/reference/metrics/advertising/google/google-conversions) Track purchases, conversions, and video engagement attributed by Google. | Metric | Description | | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | [Google Purchases](/reference/metrics/advertising/google/google-conversions/google-purchases) | Purchases attributed by Google | | [Google Purchases Value](/reference/metrics/advertising/google/google-conversions/google-purchases-value) | Revenue from attributed purchases | | [Google Average Purchase Value](/reference/metrics/advertising/google/google-conversions/google-average-purchase-value) | Average order value | | [Google All Conversions](/reference/metrics/advertising/google/google-conversions/google-all-conversions) | All tracked conversion actions | | [Google All Conversions Value](/reference/metrics/advertising/google/google-conversions/google-all-conversions-value) | Total value of all conversions | | [Google Average All Conversion Value](/reference/metrics/advertising/google/google-conversions/google-average-all-conversion-value) | Average value per conversion | | [Google Video Views](/reference/metrics/advertising/google/google-conversions/google-video-views) | Video ad views (30+ seconds) | | [Google View-Through Conversions](/reference/metrics/advertising/google/google-conversions/google-view-through-conversions) | Conversions after ad view (no click) | ### [Google Efficiency](/reference/metrics/advertising/google/google-efficiency) Measure return on ad spend and acquisition efficiency. | Metric | Description | | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | | [Google ROAS](/reference/metrics/advertising/google/google-efficiency/google-roas) | Return on ad spend | | [Google CPA](/reference/metrics/advertising/google/google-efficiency/google-cpa) | Cost per purchase acquisition | | [Google Cost per Purchase](/reference/metrics/advertising/google/google-efficiency/google-cost-per-purchase) | Cost to acquire one purchase | | [Google All Conversions ROAS](/reference/metrics/advertising/google/google-efficiency/google-all-conversions-roas) | ROAS across all conversion types | | [Google Cost per All Conversions](/reference/metrics/advertising/google/google-efficiency/google-cost-per-all-conversions) | Cost per any conversion | | [Google CPV](/reference/metrics/advertising/google/google-efficiency/google-cpv) | Cost per video view | | [Google Cost per View-Through Conversion](/reference/metrics/advertising/google/google-efficiency/google-cost-per-view-through-conversion) | Cost per view-through conversion | ## Attribution Model Google Ads uses its own attribution model to assign conversions to campaigns. Key differences from Upstack attribution: * **Data-driven attribution**: Google uses machine learning to assign conversion credit across touchpoints * **Click vs view-through**: Google tracks both click-based and impression-based conversions * **Conversion windows**: Default 30-day click, 1-day view attribution windows For cross-channel comparison, use [Blended Metrics](/reference/metrics/advertising/blended) which normalize attribution across platforms. # Advertising Metrics: Track Ad Performance Across Platforms Source: https://docs.upstackdata.com/reference/metrics/advertising/index Track advertising performance across Meta, Google, TikTok, and blended views. View 305+ metrics including ROAS, CPA, CTR, spend, and conversions with formulas and benchmarks. Advertising metrics measure your paid marketing performance across channels. These platform-reported metrics come directly from ad platform APIs and help you evaluate spend efficiency, audience reach, engagement, and campaign ROI. Use these alongside [Funnel metrics](/reference/metrics/funnel) for a complete picture of attributed vs. platform-reported performance. **Data Source:** Ad Platform APIs (Meta, Google, TikTok)\ **Metrics in Category:** 305+ ## Platforms | Platform | Metrics | Description | | --------------------------------------------------- | ------- | --------------------------------------------- | | [Meta Ads](/reference/metrics/advertising/meta) | 97 | Facebook & Instagram advertising performance | | [Google Ads](/reference/metrics/advertising/google) | 22 | Search, Display, Shopping & YouTube campaigns | | [TikTok Ads](/reference/metrics/advertising/tiktok) | 61 | TikTok video advertising performance | | [Blended](/reference/metrics/advertising/blended) | 110 | Cross-platform aggregated metrics | ## When to Use | Goal | Platform | Key Metrics | | ---------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Optimize Meta campaigns** | Meta Ads | [Meta ROAS](/reference/metrics/advertising/meta/meta-efficiency/meta-roas), [Meta CPA](/reference/metrics/advertising/meta/meta-efficiency/meta-cpa), [Meta CTR](/reference/metrics/advertising/meta/meta-clicks/meta-ctr) | | **Track search performance** | Google Ads | Google ROAS, Google CPC, Google Conversions | | **Measure video engagement** | TikTok Ads | TikTok Video Views, TikTok CTR, TikTok CPA | | **Compare across platforms** | Blended | Blended ROAS, Blended CPA, Total Ad Spend | *** ## Meta Ads Comprehensive metrics from Meta (Facebook & Instagram) covering spend, audience, clicks, efficiency, conversions, engagement, and video performance. → [View All Meta Metrics](/reference/metrics/advertising/meta) | Subcategory | Metrics | Description | | ------------------------------------------------------------------------ | ------- | ------------------------------------------ | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend) | 1 | Budget consumption tracking | | [Meta Audience](/reference/metrics/advertising/meta/meta-audience) | 4 | Reach, impressions, frequency, CPM | | [Meta Clicks](/reference/metrics/advertising/meta/meta-clicks) | 18 | CTR, CPC, link clicks, landing page views | | [Meta Efficiency](/reference/metrics/advertising/meta/meta-efficiency) | 7 | ROAS, CPA, cost-per-purchase ratios | | [Meta Conversions](/reference/metrics/advertising/meta/meta-conversions) | 32 | Purchases, leads, registrations, checkouts | | [Meta Engagement](/reference/metrics/advertising/meta/meta-engagement) | 18 | Likes, comments, shares, reactions, saves | | [Meta Video](/reference/metrics/advertising/meta/meta-video) | 15 | Views, completion rates, ThruPlay metrics | ### Key Meta Metrics | Metric | Subcategory | Description | | -------------------------------------------------------------------------------------- | ----------- | -------------------------------------- | | [Meta ROAS](/reference/metrics/advertising/meta/meta-efficiency/meta-roas) | Efficiency | Return on ad spend from Meta campaigns | | [Meta CPA](/reference/metrics/advertising/meta/meta-efficiency/meta-cpa) | Efficiency | Cost per acquisition | | [Meta Ad Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Spend | Total budget consumed | | [Meta CTR](/reference/metrics/advertising/meta/meta-clicks/meta-ctr) | Clicks | Click-through rate | | [Meta Purchases](/reference/metrics/advertising/meta/meta-conversions/meta-purchases) | Conversions | Platform-reported purchase count | | [Meta Impressions](/reference/metrics/advertising/meta/meta-audience/meta-impressions) | Audience | Number of ad impressions | | [Meta Reach](/reference/metrics/advertising/meta/meta-audience/meta-reach) | Audience | Unique people reached | *** ## Google Ads Metrics from Google Ads covering Search, Display, Shopping, and YouTube campaign performance. → [View All Google Metrics](/reference/metrics/advertising/google) *(coming soon)* | Subcategory | Metrics | Description | | ------------------ | ------- | -------------------------------------- | | Google Spend | 1 | Budget consumption tracking | | Google Clicks | 6 | Clicks, CTR, CPC across campaign types | | Google Efficiency | 4 | ROAS, CPA, cost-per-conversion | | Google Conversions | 11 | Purchase, lead, and action conversions | *** ## TikTok Ads Metrics from TikTok Ads Manager for video advertising performance and conversion tracking. → [View All TikTok Metrics](/reference/metrics/advertising/tiktok) *(coming soon)* | Subcategory | Metrics | Description | | ------------------ | ------- | ----------------------------------- | | TikTok Spend | 1 | Budget consumption tracking | | TikTok Clicks | 8 | Clicks, CTR, CPC | | TikTok Efficiency | 4 | ROAS, CPA ratios | | TikTok Conversions | 18 | Purchase and action conversions | | TikTok Video | 30 | Video views, watch time, completion | *** ## Blended Metrics Cross-platform aggregated metrics for unified advertising performance analysis. Blended metrics combine data from Meta, Google, and TikTok into single views for holistic campaign evaluation. → [View All Blended Metrics](/reference/metrics/advertising/blended) *(coming soon)* | Subcategory | Metrics | Description | | ------------------- | ------- | ------------------------------ | | Blended Spend | 4 | Total and per-platform spend | | Blended Efficiency | 12 | Cross-platform ROAS, CPA, MER | | Blended Conversions | 8 | Aggregated conversion counts | | Blended Audience | 6 | Combined reach and impressions | ### Key Blended Metrics | Metric | Description | | -------------------------------- | ------------------------------------------------ | | Blended ROAS | Combined return on ad spend across all platforms | | Blended CPA | Average cost per acquisition across platforms | | Total Ad Spend | Sum of all platform advertising spend | | MER (Marketing Efficiency Ratio) | Revenue divided by total marketing spend | *** ## Platform vs. Attributed Metrics Understanding the difference between advertising metrics and funnel metrics: | Aspect | Advertising Metrics | Funnel Metrics | | --------------- | --------------------------- | ---------------------------------------------------------------- | | **Source** | Ad platform APIs | Upstack attribution | | **Attribution** | Platform-specific models | Cross-channel attribution | | **Example** | Meta Purchases | [Conversions](/reference/metrics/funnel/conversions/conversions) | | **Use Case** | Optimize platform campaigns | Understand true channel value | **Best Practice:** Compare platform-reported conversions (advertising metrics) with attributed conversions (funnel metrics) to understand how each platform's attribution model differs from cross-channel reality. # Meta Advertising Metrics: Track Facebook & Instagram Ad Performance Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/index Track Meta (Facebook/Instagram) ad performance in Upstack. View 100 metrics including ROAS, CPA, CTR, video views with formulas and optimization tips. Meta advertising metrics measure your Facebook and Instagram ad performance across the full marketing funnel. These metrics come directly from Meta's Marketing API and help you evaluate campaign efficiency, audience engagement, and conversion attribution. **Data Source:** Meta Marketing API\ **Total Metrics:** 100 ## Subcategories | Category | Metrics | Description | | ------------------------------------------------------------------------ | ------- | ---------------------------------------------------------------- | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend) | 1 | Budget consumption and ad spend tracking | | [Meta Audience](/reference/metrics/advertising/meta/meta-audience) | 4 | Reach, impressions, frequency, and audience cost metrics | | [Meta Clicks](/reference/metrics/advertising/meta/meta-clicks) | 18 | Click types, click-through rates, and cost-per-click metrics | | [Meta Efficiency](/reference/metrics/advertising/meta/meta-efficiency) | 7 | ROAS, CPA, and return-on-investment efficiency ratios | | [Meta Conversions](/reference/metrics/advertising/meta/meta-conversions) | 35 | Purchase, lead, registration, and conversion event tracking | | [Meta Engagement](/reference/metrics/advertising/meta/meta-engagement) | 19 | Social interactions including likes, comments, shares, and saves | | [Meta Video](/reference/metrics/advertising/meta/meta-video) | 16 | Video views, ThruPlay, watch time, and completion rates | *** ## Subcategory Details ### Meta Spend Track total advertising budget consumption across your Meta campaigns. Essential for budget monitoring and pacing. → [View Meta Spend Metrics](/reference/metrics/advertising/meta/meta-spend) ### Meta Audience Measure how many people see your ads and how often. Includes reach, impressions, frequency, and CPM for understanding audience penetration. → [View Meta Audience Metrics](/reference/metrics/advertising/meta/meta-audience) ### Meta Clicks Analyze user click behavior with 18 metrics covering different click types (link, inline, outbound), click-through rates, and cost-per-click metrics. → [View Meta Clicks Metrics](/reference/metrics/advertising/meta/meta-clicks) ### Meta Efficiency Evaluate advertising ROI with efficiency ratios including ROAS, CPA, and cost-per-purchase metrics. Critical for optimizing campaign profitability. → [View Meta Efficiency Metrics](/reference/metrics/advertising/meta/meta-efficiency) ### Meta Conversions Track Meta-attributed conversion events including purchases, add-to-carts, leads, registrations, and app installs. The largest subcategory with 35 metrics covering the full conversion funnel. → [View Meta Conversions Metrics](/reference/metrics/advertising/meta/meta-conversions) ### Meta Engagement Measure social interactions including likes, comments, shares, saves, and reactions. Useful for brand awareness campaigns and content resonance analysis. → [View Meta Engagement Metrics](/reference/metrics/advertising/meta/meta-engagement) ### Meta Video Track video ad performance with views, ThruPlay, watch time, and completion rate metrics. Essential for video-first campaign optimization. → [View Meta Video Metrics](/reference/metrics/advertising/meta/meta-video) *** ## When to Use Each Subcategory | Goal | Start With | | ---------------------------- | ------------------------------------------------------------------------ | | Monitor budget pacing | [Meta Spend](/reference/metrics/advertising/meta/meta-spend) | | Understand audience reach | [Meta Audience](/reference/metrics/advertising/meta/meta-audience) | | Optimize for website traffic | [Meta Clicks](/reference/metrics/advertising/meta/meta-clicks) | | Maximize return on ad spend | [Meta Efficiency](/reference/metrics/advertising/meta/meta-efficiency) | | Track purchases and leads | [Meta Conversions](/reference/metrics/advertising/meta/meta-conversions) | | Build brand awareness | [Meta Engagement](/reference/metrics/advertising/meta/meta-engagement) | | Evaluate video campaigns | [Meta Video](/reference/metrics/advertising/meta/meta-video) | *** ## How Meta Attribution Works Meta attributes conversions based on its attribution window settings. By default, Meta uses a 7-day click and 1-day view window—meaning a conversion is attributed to an ad if someone clicked it within 7 days or viewed it within 1 day before converting. ## All Meta Metrics by Category ### Spend Metrics | Metric | Description | | ----------------------------------------------------------------------- | ------------------------ | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total ad budget consumed | ### Audience Metrics | Metric | Description | | -------------------------------------------------------------------------------------- | -------------------------------------- | | [Meta Impressions](/reference/metrics/advertising/meta/meta-audience/meta-impressions) | Number of times ads were shown | | [Meta Reach](/reference/metrics/advertising/meta/meta-audience/meta-reach) | Unique people who saw your ads | | [Meta Frequency](/reference/metrics/advertising/meta/meta-audience/meta-frequency) | Average times each person saw your ads | | [Meta CPM](/reference/metrics/advertising/meta/meta-audience/meta-cpm) | Cost per 1,000 impressions | ### Click Metrics | Metric | Description | | ------------------------------------------------------------------------------------------------------------------ | ----------------------------- | | [Meta Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-clicks) | All clicks on your ads | | [Meta Link Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-link-clicks) | Clicks on ad links | | [Meta Inline Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-inline-clicks) | Clicks on inline links | | [Meta Outbound Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-outbound-clicks) | Clicks leaving Meta | | [Meta Unique Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-unique-clicks) | Unique people who clicked | | [Meta Landing Page Views](/reference/metrics/advertising/meta/meta-clicks/meta-landing-page-views) | Times landing page loaded | | [Meta CTR](/reference/metrics/advertising/meta/meta-clicks/meta-ctr) | Click-through rate | | [Meta Link CTR](/reference/metrics/advertising/meta/meta-clicks/meta-link-ctr) | Link clicks ÷ Impressions | | [Meta Inline Clicks CTR](/reference/metrics/advertising/meta/meta-clicks/meta-inline-clicks-ctr) | Inline clicks ÷ Impressions | | [Meta Outbound CTR](/reference/metrics/advertising/meta/meta-clicks/meta-outbound-ctr) | Outbound clicks ÷ Impressions | | [Meta Unique CTR](/reference/metrics/advertising/meta/meta-clicks/meta-unique-ctr) | Unique clicks ÷ Reach | | [Meta Landing Page View Rate](/reference/metrics/advertising/meta/meta-clicks/meta-landing-page-view-rate) | LP views ÷ Link clicks | | [Meta CPC](/reference/metrics/advertising/meta/meta-clicks/meta-cpc) | Cost per click | | [Meta Cost per Link Click](/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-link-click) | Spend ÷ Link clicks | | [Meta Cost per Inline Click](/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-inline-click) | Spend ÷ Inline clicks | | [Meta Cost per Outbound Click](/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-outbound-click) | Spend ÷ Outbound clicks | | [Meta Cost per Unique Click](/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-unique-click) | Spend ÷ Unique clicks | | [Meta Cost per Landing Page View](/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-landing-page-view) | Spend ÷ Landing page views | ### Efficiency Metrics | Metric | Description | | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | | [Meta ROAS](/reference/metrics/advertising/meta/meta-efficiency/meta-roas) | Return on ad spend | | [Meta CPA](/reference/metrics/advertising/meta/meta-efficiency/meta-cpa) | Cost per purchase | | [Meta CPP](/reference/metrics/advertising/meta/meta-efficiency/meta-cpp) | Cost per 1,000 people reached | | [Meta Cost per Purchase](/reference/metrics/advertising/meta/meta-efficiency/meta-cost-per-purchase) | Spend ÷ Purchases | | [Meta New Customer ROAS](/reference/metrics/advertising/meta/meta-efficiency/meta-new-customer-roas) | ROAS from new customers | | [Meta New Customer CPA](/reference/metrics/advertising/meta/meta-efficiency/meta-new-customer-cpa) | Cost to acquire new customers | | [Meta New Customer Cost per Purchase](/reference/metrics/advertising/meta/meta-efficiency/meta-new-customer-cost-per-purchase) | Spend ÷ New customer purchases | ### Conversion Metrics | Metric | Description | | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | | [Meta Purchases](/reference/metrics/advertising/meta/meta-conversions/meta-purchases) | Attributed purchase count | | [Meta Purchases Value](/reference/metrics/advertising/meta/meta-conversions/meta-purchases-value) | Revenue from purchases | | [Meta New Customer Purchases](/reference/metrics/advertising/meta/meta-conversions/meta-new-customer-purchases) | First-time buyer purchases | | [Meta Add to Carts](/reference/metrics/advertising/meta/meta-conversions/meta-add-to-carts) | Add to cart actions | | [Meta View Contents](/reference/metrics/advertising/meta/meta-conversions/meta-view-contents) | Product page views | | [Meta Initiate Checkouts](/reference/metrics/advertising/meta/meta-conversions/meta-initiate-checkouts) | Checkout starts | | [Meta Add Payment Info](/reference/metrics/advertising/meta/meta-conversions/meta-add-payment-info) | Payment info additions | | [Meta Leads](/reference/metrics/advertising/meta/meta-conversions/meta-leads) | Lead form submissions | | [Meta Completed Registrations](/reference/metrics/advertising/meta/meta-conversions/meta-completed-registrations) | Account sign-ups | | [Meta App Installs](/reference/metrics/advertising/meta/meta-conversions/meta-app-installs) | Mobile app installs | | [Meta Subscriptions](/reference/metrics/advertising/meta/meta-conversions/meta-subscriptions) | Subscription sign-ups | | [Meta Subscribes](/reference/metrics/advertising/meta/meta-conversions/meta-subscribes) | Subscribe actions | | [Meta Start Trials](/reference/metrics/advertising/meta/meta-conversions/meta-start-trials) | Trial initiations | | [Meta Contact Events](/reference/metrics/advertising/meta/meta-conversions/meta-contact-events) | Contact form submissions | | [Meta Customize Product Events](/reference/metrics/advertising/meta/meta-conversions/meta-customize-product-events) | Product customizations | | [Meta Donate Events](/reference/metrics/advertising/meta/meta-conversions/meta-donate-events) | Donation actions | | [Meta Find Location Events](/reference/metrics/advertising/meta/meta-conversions/meta-find-location-events) | Location searches | | [Meta Schedule Events](/reference/metrics/advertising/meta/meta-conversions/meta-schedule-events) | Schedule bookings | | [Meta Search Events](/reference/metrics/advertising/meta/meta-conversions/meta-search-events) | On-site searches | | [Meta Submit Application Events](/reference/metrics/advertising/meta/meta-conversions/meta-submit-application-events) | Application submissions | | [Meta Messaging Conversations Started](/reference/metrics/advertising/meta/meta-conversions/meta-messaging-conversations-started) | Messaging initiations | | [Meta Cost per Add to Cart](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-add-to-cart) | Spend ÷ Add to carts | | [Meta Cost per Lead](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-lead) | Spend ÷ Leads | | [Meta Cost per Registration](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-registration) | Spend ÷ Registrations | | [Meta Cost per Add Payment Info](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-add-payment-info) | Spend ÷ Payment info | | [Meta Cost per Contact](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-contact) | Spend ÷ Contacts | | [Meta Cost per Customize Product](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-customize-product) | Spend ÷ Customizations | | [Meta Cost per Donate](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-donate) | Spend ÷ Donations | | [Meta Cost per Find Location](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-find-location) | Spend ÷ Location searches | | [Meta Cost per Schedule](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-schedule) | Spend ÷ Schedules | | [Meta Cost per Search](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-search) | Spend ÷ Searches | | [Meta Cost per Start Trial](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-start-trial) | Spend ÷ Trials | | [Meta Cost per Submit Application](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-submit-application) | Spend ÷ Applications | | [Meta Cost per Subscribe](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-subscribe) | Spend ÷ Subscribes | ### Engagement Metrics | Metric | Description | | -------------------------------------------------------------------------------------------------------- | ----------------------- | | [Meta Engagements](/reference/metrics/advertising/meta/meta-engagement/meta-engagements) | All social interactions | | [Meta Engagement Rate](/reference/metrics/advertising/meta/meta-engagement/meta-engagement-rate) | Engagements ÷ Reach | | [Meta Likes](/reference/metrics/advertising/meta/meta-engagement/meta-likes) | Like reactions | | [Meta Comments](/reference/metrics/advertising/meta/meta-engagement/meta-comments) | Comment count | | [Meta Shares](/reference/metrics/advertising/meta/meta-engagement/meta-shares) | Share count | | [Meta Saves](/reference/metrics/advertising/meta/meta-engagement/meta-saves) | Save/bookmark count | | [Meta Reactions](/reference/metrics/advertising/meta/meta-engagement/meta-reactions) | All emoji reactions | | [Meta Page Likes](/reference/metrics/advertising/meta/meta-engagement/meta-page-likes) | Page like actions | | [Meta Post Comments](/reference/metrics/advertising/meta/meta-engagement/meta-post-comments) | Post comment count | | [Meta Post Saves](/reference/metrics/advertising/meta/meta-engagement/meta-post-saves) | Post saves count | | [Meta Post Shares](/reference/metrics/advertising/meta/meta-engagement/meta-post-shares) | Post share count | | [Meta Photo Views](/reference/metrics/advertising/meta/meta-engagement/meta-photo-views) | Expanded photo views | | [Meta Cost per Engagement](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-engagement) | Spend ÷ Engagements | | [Meta Cost per Comment](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-comment) | Spend ÷ Comments | | [Meta Cost per Share](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-share) | Spend ÷ Shares | | [Meta Cost per Save](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-save) | Spend ÷ Saves | | [Meta Cost per Page Like](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-page-like) | Spend ÷ Page likes | | [Meta Cost per Photo View](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-photo-view) | Spend ÷ Photo views | ### Video Metrics | Metric | Description | | ----------------------------------------------------------------------------------------------------- | ---------------------------- | | [Meta Video Views](/reference/metrics/advertising/meta/meta-video/meta-video-views) | 3+ second video views | | [Meta Video Plays](/reference/metrics/advertising/meta/meta-video/meta-video-plays) | Video play starts | | [Meta Video Completions](/reference/metrics/advertising/meta/meta-video/meta-video-completions) | 100% completion | | [Meta ThruPlay](/reference/metrics/advertising/meta/meta-video/meta-thruplay) | ThruPlay views | | [Meta ThruPlay Views](/reference/metrics/advertising/meta/meta-video/meta-thruplay-views) | ThruPlay view count | | [Meta Video Views 15 Sec](/reference/metrics/advertising/meta/meta-video/meta-video-views-15-sec) | 15+ second views | | [Meta Video Views 25%](/reference/metrics/advertising/meta/meta-video/meta-video-views-25-percent) | 25%+ completion | | [Meta Video Views 50%](/reference/metrics/advertising/meta/meta-video/meta-video-views-50-percent) | 50%+ completion | | [Meta Video Views 75%](/reference/metrics/advertising/meta/meta-video/meta-video-views-75-percent) | 75%+ completion | | [Meta Video Views 100%](/reference/metrics/advertising/meta/meta-video/meta-video-views-100-percent) | 100% completion | | [Meta Average Watch Time](/reference/metrics/advertising/meta/meta-video/meta-average-watch-time) | Average video watch duration | | [Meta Cost per Video View](/reference/metrics/advertising/meta/meta-video/meta-cost-per-video-view) | Spend ÷ Video views | | [Meta Cost per Video Play](/reference/metrics/advertising/meta/meta-video/meta-cost-per-video-play) | Spend ÷ Video plays | | [Meta Cost per ThruPlay](/reference/metrics/advertising/meta/meta-video/meta-cost-per-thruplay) | Spend ÷ ThruPlay | | [Meta Cost per 15 Sec View](/reference/metrics/advertising/meta/meta-video/meta-cost-per-15-sec-view) | Spend ÷ 15s views | # Meta Audience Metrics Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-audience/index Track Meta audience reach and impressions in Upstack. Monitor reach, impressions, frequency, and CPM for your Facebook and Instagram campaigns. Audience metrics measure how many people see your Meta ads and how often. Track reach, impressions, frequency, and cost efficiency of audience delivery. **Data Source:** Meta Marketing API\ **Metrics:** 4 ## Metrics in This Group | Metric | Description | When to Use | | -------------------------------------------------------------------------------------- | -------------------------------------- | --------------------------------------- | | [Meta Impressions](/reference/metrics/advertising/meta/meta-audience/meta-impressions) | Number of times ads were shown | Measure total ad exposure and scale | | [Meta Reach](/reference/metrics/advertising/meta/meta-audience/meta-reach) | Unique people who saw your ads | Measure audience size and penetration | | [Meta Frequency](/reference/metrics/advertising/meta/meta-audience/meta-frequency) | Average times each person saw your ads | Detect ad fatigue and optimize delivery | | [Meta CPM](/reference/metrics/advertising/meta/meta-audience/meta-cpm) | Cost per 1,000 impressions | Evaluate delivery cost efficiency | ## How These Metrics Relate * **Impressions** counts every time your ad appears on screen * **Reach** counts unique individuals, regardless of how many times they saw it * **Frequency** = Impressions ÷ Reach — shows average views per person * **CPM** = Spend ÷ Impressions × 1,000 — measures delivery cost efficiency High frequency can signal ad fatigue, while low CPM indicates efficient reach. ## Choosing the Right Metric * **Awareness campaigns**: Use Impressions and Reach to measure visibility * **Ad fatigue detection**: Monitor Frequency—above 3-4 may indicate fatigue * **Cost efficiency**: Compare CPM across campaigns to find efficient delivery * **Audience expansion**: Track Reach growth to measure new audience acquisition # Meta CPM: Cost Per Thousand Impressions Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-audience/meta-cpm Track Meta CPM to understand your cost per thousand impressions. Optimize ad reach efficiency and compare audience costs across campaigns. Meta CPM measures how much you pay for every 1,000 times your ad is shown on Meta platforms. ## Formula **Meta CPM** = ( **Meta Spend** ÷ **Meta Impressions** ) × 1,000 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------ | ------------------------------ | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta ads | | [**Meta Impressions**](/reference/metrics/advertising/meta/meta-audience/meta-impressions) | Total times ads were shown | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your Meta campaigns delivered **500,000 impressions** last week with a total spend of **\$3,500**. | Metric | Value | Calculation | | ---------------- | ---------- | --------------------------- | | Meta Spend | \$3,500 | Total ad spend | | Meta Impressions | 500,000 | Total impressions delivered | | **Meta CPM** | **\$7.00** | (\$3,500 ÷ 500,000) × 1,000 | *** ## How It Works CPM calculates the cost efficiency of reaching your audience at scale. The formula divides your total ad spend by the number of impressions, then multiplies by 1,000 to express the cost per thousand views. Lower CPM means you're reaching more people for less money. *** ## When to Use | Scenario | Action | | ---------------------------- | -------------------------------------------------------------- | | Comparing audience costs | Use CPM to identify which audiences are cheapest to reach | | Planning awareness campaigns | Estimate budget needed to reach a target number of impressions | | Seasonal cost monitoring | Track CPM spikes during competitive periods like Q4 | | Creative testing | Compare CPM across ad creatives to find efficient combinations | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------- | -------------------------------------- | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Numerator in CPM calculation | | [Meta Impressions](/reference/metrics/advertising/meta/meta-audience/meta-impressions) | Denominator in CPM calculation | | [Meta CTR](/reference/metrics/advertising/meta/meta-clicks/meta-ctr) | Engagement rate from those impressions | [See all Meta Audience metrics →](/reference/metrics/advertising/meta/meta-audience) # Meta Frequency: Average Ad Views per Person Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-audience/meta-frequency Track how many times each person saw your Meta ads. Monitor frequency to optimize ad exposure and avoid audience fatigue on Facebook and Instagram. Meta Frequency measures the average number of times each unique person saw your Meta ads. ## Formula **Meta Frequency** = **Meta Impressions** ÷ **Meta Reach** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------ | ------------------------------------------------------ | | [**Meta Impressions**](/reference/metrics/advertising/meta/meta-audience/meta-impressions) | Total number of times your ads appeared on screen | | [**Meta Reach**](/reference/metrics/advertising/meta/meta-audience/meta-reach) | Number of unique people who saw your ads at least once | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Average | *** ## Example Your Meta campaign delivered **450,000 impressions** to **90,000 unique people**: | Metric | Value | | ------------------ | ------- | | Meta Impressions | 450,000 | | Meta Reach | 90,000 | | **Meta Frequency** | **5.0** | On average, each person saw your ads 5 times across Facebook, Instagram, and Audience Network. *** ## How It Works Meta calculates frequency by dividing total impressions by unique reach. A frequency of 5.0 means users saw your ad 5 times on average. High frequency can signal ad fatigue—when users see your ad too often, engagement and conversion rates typically decline. *** ## When to Use | Scenario | Action | | -------------------------------- | --------------------------------------------------------------------------- | | Detecting ad fatigue | Frequency above 5–7 often signals diminishing returns for prospecting | | Optimizing retargeting | Higher frequency (7–15) acceptable for warm audiences with purchase intent | | Balancing reach vs. repetition | Lower frequency broadens exposure; higher deepens engagement | | Diagnosing declining performance | Rising frequency with falling CTR indicates creative or audience saturation | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | [Meta Impressions](/reference/metrics/advertising/meta/meta-audience/meta-impressions) | Numerator—total ad views driving the frequency calculation | | [Meta Reach](/reference/metrics/advertising/meta/meta-audience/meta-reach) | Denominator—unique audience size that determines frequency | | [Meta CPM](/reference/metrics/advertising/meta/meta-audience/meta-cpm) | Cost efficiency at current frequency level—higher frequency often increases CPM | [See all Meta Audience metrics →](/reference/metrics/advertising/meta/meta-audience) # Meta Impressions: Total Ad Displays on Meta Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-audience/meta-impressions Track how many times your Meta ads were displayed. Understand ad visibility and reach across Facebook, Instagram, and Audience Network. Meta Impressions counts the total number of times your ads appeared on screen across Facebook, Instagram, and Audience Network. ## Formula **Meta Impressions** = **COUNT** ( Ad displays ) ### Formula Components | Metric | Definition | | --------------- | --------------------------------------------------------------------------- | | **Ad displays** | Each instance your ad renders on a user's screen, regardless of interaction | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your Meta campaign delivered **125,000 impressions** last week across all placements. | Campaign | Impressions | Reach | Frequency | | --------------- | ----------- | ---------- | --------- | | Summer Sale | 75,000 | 25,000 | 3.0 | | Brand Awareness | 50,000 | 40,000 | 1.25 | | **Total** | **125,000** | **52,000** | **2.4** | *** ## How It Works Meta counts an impression each time your ad renders on screen. One person can generate multiple impressions by seeing your ad more than once. Impressions include all placements—Feed, Stories, Reels, and Audience Network. *** ## When to Use | Scenario | Action | | ------------------------------ | -------------------------------------------------------------- | | Measuring brand visibility | Track impressions to understand how often your brand appears | | Diagnosing delivery issues | Low impressions indicate targeting, budget, or bid constraints | | Calculating efficiency metrics | Use as denominator for CPM and CTR calculations | | Comparing reach vs. frequency | Divide impressions by reach to get average frequency | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------- | --------------------------------------------------------------- | | [Meta Reach](/reference/metrics/advertising/meta/meta-audience/meta-reach) | Unique users who saw your ads (impressions ÷ reach = frequency) | | [Meta Frequency](/reference/metrics/advertising/meta/meta-audience/meta-frequency) | Average times each person saw your ad | | [Meta CPM](/reference/metrics/advertising/meta/meta-audience/meta-cpm) | Cost per 1,000 impressions—spend efficiency metric | [See all Meta Audience metrics →](/reference/metrics/advertising/meta/meta-audience) # Meta Reach: Unique People Who Saw Your Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-audience/meta-reach Track unique people reached by your Meta ads. Understand audience size vs impressions to optimize frequency and reduce ad fatigue. Meta Reach measures the number of unique people who saw your Meta ads at least once. ## Formula **Meta Reach** = **COUNT DISTINCT** ( People who saw ad ) ### Formula Components | Metric | Definition | | --------------------- | ----------------------------------------------------------------------------- | | **People who saw ad** | Individual users who viewed your ad at least once during the reporting period | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count Distinct | *** ## Example Your Meta campaign reached **45,000 unique people** in the last 7 days. | Campaign | Reach | Impressions | Frequency | | --------------- | ------ | ----------- | --------- | | Summer Sale | 45,000 | 135,000 | 3.0 | | Brand Awareness | 28,000 | 56,000 | 2.0 | | Retargeting | 8,500 | 42,500 | 5.0 | The Summer Sale campaign reached 45,000 unique people who saw the ad an average of 3 times each (135,000 impressions ÷ 45,000 reach). *** ## How It Works Reach counts each person only once, regardless of how many times they saw your ad. Meta tracks this using anonymized user identifiers across their platforms (Facebook, Instagram, Messenger, Audience Network). This differs from impressions, which count every ad view including repeat views to the same person. *** ## When to Use | Scenario | Action | | ------------------------------------ | ---------------------------------------------------------------- | | High impressions but low conversions | Check if reach is low—you may be oversaturating a small audience | | Planning brand awareness campaigns | Use reach to estimate total audience exposure | | Comparing campaign efficiency | Evaluate cost per person reached (CPP) across campaigns | | Managing ad fatigue | Monitor reach vs frequency to avoid showing ads too often | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------- | ----------------------------------------------- | | [Meta Impressions](/reference/metrics/advertising/meta/meta-audience/meta-impressions) | Total ad views; reach × frequency = impressions | | [Meta CPP](/reference/metrics/advertising/meta/meta-efficiency/meta-cpp) | Cost to reach each unique person | [See all Meta Audience metrics →](/reference/metrics/advertising/meta/meta-audience) # Meta Click Metrics Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-clicks/index Track Meta click performance in Upstack. Monitor CTR, CPC, link clicks, landing page views, and outbound click metrics for your campaigns. Click metrics measure how people interact with your Meta ads. Track total clicks, link clicks, landing page views, and the cost efficiency of driving traffic. **Data Source:** Meta Marketing API\ **Metrics:** 18 ## Metrics in This Group | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------------------------------ | ----------------------------- | ------------------------------------- | | [Meta Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-clicks) | All clicks on your ads | Measure total engagement interactions | | [Meta CPC](/reference/metrics/advertising/meta/meta-clicks/meta-cpc) | Cost per click | Evaluate click cost efficiency | | [Meta CTR](/reference/metrics/advertising/meta/meta-clicks/meta-ctr) | Click-through rate | Compare creative performance | | [Meta Link Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-link-clicks) | Clicks on ad links | Measure traffic generation | | [Meta Link Click-Through Rate](/reference/metrics/advertising/meta/meta-clicks/meta-link-ctr) | Link clicks ÷ Impressions | Evaluate link engagement rate | | [Meta Cost per Link Click](/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-link-click) | Spend ÷ Link clicks | Optimize traffic acquisition cost | | [Meta Outbound Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-outbound-clicks) | Clicks leaving Meta | Track exits to your website | | [Meta Outbound Click-Through Rate](/reference/metrics/advertising/meta/meta-clicks/meta-outbound-ctr) | Outbound clicks ÷ Impressions | Measure off-platform navigation rate | | [Meta Cost per Outbound Click](/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-outbound-click) | Spend ÷ Outbound clicks | Evaluate website visit cost | | [Meta Unique Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-unique-clicks) | Unique people who clicked | Count distinct clickers | | [Meta Unique Click-Through Rate](/reference/metrics/advertising/meta/meta-clicks/meta-unique-ctr) | Unique clicks ÷ Reach | Measure per-person engagement | | [Meta Cost per Unique Click](/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-unique-click) | Spend ÷ Unique clicks | Evaluate cost per new clicker | | [Meta Inline Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-inline-clicks) | Clicks on inline links | Track in-content link engagement | | [Meta Inline Link Click-Through Rate](/reference/metrics/advertising/meta/meta-clicks/meta-inline-ctr) | Inline clicks ÷ Impressions | Measure inline content performance | | [Meta Cost per Inline Click](/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-inline-click) | Spend ÷ Inline clicks | Optimize inline link costs | | [Meta Landing Page Views](/reference/metrics/advertising/meta/meta-clicks/meta-landing-page-views) | Times landing page loaded | Verify actual page loads | | [Meta Cost per Landing Page View](/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-landing-page-view) | Spend ÷ Landing page views | Measure true traffic cost | | [Meta Landing Page View Rate](/reference/metrics/advertising/meta/meta-clicks/meta-landing-page-view-rate) | LP views ÷ Link clicks | Identify bounce-before-load issues | ## How These Metrics Relate * **Clicks** includes all interactions (link clicks, reactions, profile visits) * **Link Clicks** are specifically clicks on your ad's destination link * **Outbound Clicks** leave Meta to your website or app * **Landing Page Views** show how many people actually loaded your page after clicking * The gap between Link Clicks and Landing Page Views indicates bounce-before-load ## Choosing the Right Metric * **Awareness campaigns**: Use Total Clicks and CTR to measure engagement breadth * **Traffic campaigns**: Use Link Clicks and Landing Page Views for site visits * **Efficiency analysis**: Compare CPC across campaigns to find cost-effective performers * **Audience quality**: Use Unique Clicks to avoid counting repeat clickers * **Landing page issues**: Compare Link Clicks vs Landing Page Views to detect load problems # Meta Clicks: Total Engagement on Your Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-clicks/meta-clicks Track Meta Clicks to measure total engagement on your Facebook and Instagram ads. Includes link clicks, reactions, comments, shares, and profile visits. Meta Clicks measures the total number of clicks anywhere on your Meta ads, including link clicks, reactions, comments, shares, and profile visits. ## Formula **Meta Clicks** = **COUNT** ( Clicks ) ### Formula Components | Metric | Definition | | ---------- | ------------------------------------------------------------------------------------------------------ | | **Clicks** | Any click on your ad — link clicks, reactions, comments, shares, profile visits, or other interactions | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your Meta campaign received **12,450 clicks** last week across all ad sets. | Campaign | Clicks | Link Clicks | Other Clicks | | ----------- | ---------- | ----------- | ------------ | | Prospecting | 8,200 | 5,100 | 3,100 | | Retargeting | 4,250 | 3,800 | 450 | | **Total** | **12,450** | **8,900** | **3,550** | *** ## How It Works Meta counts every click on your ad, regardless of where users click. This includes clicks that lead to your website (link clicks) and engagement actions like reactions, comments, shares, and profile visits. The metric is pulled directly from Meta's reporting API. *** ## When to Use | Scenario | Action | | ------------------------------- | --------------------------------------------------------------------- | | Measuring overall ad engagement | Compare clicks across campaigns to identify high-engagement creatives | | Analyzing click composition | Break down total clicks vs link clicks to understand engagement types | | Calculating efficiency metrics | Use as denominator for CPC and CTR calculations | | Optimizing for engagement | Target campaigns with high click volume for brand awareness goals | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------ | --------------------------------------------------------------- | | [Meta Link Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-link-clicks) | Subset of total clicks — only clicks that lead to a destination | | [Meta CPC](/reference/metrics/advertising/meta/meta-clicks/meta-cpc) | Cost efficiency — spend divided by total clicks | | [Meta CTR](/reference/metrics/advertising/meta/meta-clicks/meta-ctr) | Click-through rate — clicks as percentage of impressions | [See all Meta Clicks metrics →](/reference/metrics/advertising/meta/meta-clicks) # Meta Cost per Inline Click: Average Spend Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-inline-click Track cost per inline click on Meta ads. Measure efficiency of link-focused ad formats and optimize your CPC for inline link clicks. Meta Cost per Inline Click measures the average amount you spend for each inline link click on your Meta ads. ## Formula **Meta Cost per Inline Click** = **Meta Spend** ÷ **Meta Inline Clicks** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising campaigns | | [**Meta Inline Clicks**](/reference/metrics/advertising/meta/meta-clicks/meta-inline-clicks) | Number of clicks on inline links within your Meta ad content | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your Meta campaigns spent **\$2,500** and generated **1,250 inline clicks** last week. | Metric | Value | Calculation | | ------------------------------ | ---------- | ---------------------- | | Meta Spend | \$2,500 | Total ad spend | | Meta Inline Clicks | 1,250 | Clicks on inline links | | **Meta Cost per Inline Click** | **\$2.00** | \$2,500 ÷ 1,250 | *** ## How It Works Inline clicks are clicks on links that appear within the ad content itself—not profile clicks, page likes, or other engagement actions. This metric calculates your average cost for each of these link-specific clicks by dividing total spend by inline click volume. *** ## When to Use | Scenario | Action | | ---------------------------------- | ------------------------------------------------------------------------------- | | Evaluating link-focused ad formats | Compare cost per inline click across ad types to identify efficient formats | | Optimizing traffic campaigns | Lower cost per inline click indicates better efficiency for driving link clicks | | Comparing to standard CPC | Use alongside Meta CPC to understand click type distribution | | Budget allocation decisions | Allocate more budget to campaigns with lower inline click costs | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | [Meta Inline Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-inline-clicks) | Denominator — total inline clicks driving this cost metric | | [Meta CPC](/reference/metrics/advertising/meta/meta-clicks/meta-cpc) | Alternative — cost per all click types, not just inline links | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Numerator — total spend used in this calculation | [See all Meta Clicks metrics →](/reference/metrics/advertising/meta/meta-clicks) # Meta Cost per Landing Page View: Average Ad Cost per Page Load Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-landing-page-view Track Meta cost per landing page view to measure true traffic acquisition costs. A more reliable efficiency metric than cost per click alone. Meta Cost per Landing Page View measures the average spend per landing page load from your Meta ads. ## Formula **Meta Cost per Landing Page View** = **Meta Spend** ÷ **Meta Landing Page Views** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta ads | | [**Meta Landing Page Views**](/reference/metrics/advertising/meta/meta-clicks/meta-landing-page-views) | Number of times users loaded your landing page after clicking a Meta ad | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your Meta campaigns spent **\$5,000** and drove **2,500 landing page views** this month. | Metric | Value | Calculation | | -------------------- | ---------- | ------------------ | | Meta Spend | \$5,000 | Total ad spend | | Landing Page Views | 2,500 | Pages fully loaded | | **Cost per LP View** | **\$2.00** | \$5,000 ÷ 2,500 | *** ## How It Works Meta Cost per Landing Page View divides your total ad spend by the number of times users actually loaded your landing page. Unlike cost per click, this metric filters out accidental clicks, bounces before page load, and slow-loading pages that users abandon—giving you a clearer picture of true traffic acquisition costs. *** ## When to Use | Scenario | Action | | ---------------------------------------- | ---------------------------------------------------------------- | | Compare traffic quality across campaigns | Lower cost per LP view indicates more engaged traffic | | Identify landing page load issues | High CPC but higher cost per LP view signals page speed problems | | Optimize for real site visitors | Use as a quality-adjusted alternative to cost per click | | Budget forecasting | Estimate true cost to acquire actual site traffic | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | [Meta Landing Page Views](/reference/metrics/advertising/meta/meta-clicks/meta-landing-page-views) | The denominator in this calculation | | [Meta Cost per Link Click](/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-link-click) | Alternative click-based cost metric (includes all clicks) | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | The numerator in this calculation | [See all Meta Clicks metrics →](/reference/metrics/advertising/meta/meta-clicks) # Meta Cost per Link Click: Website Traffic Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-link-click Track Meta Cost per Link Click to measure your average spend per website visit from ads. The standard CPC metric for traffic campaigns on Facebook and Instagram. Meta Cost per Link Click measures the average cost each time someone clicks a link in your ad that takes them to your website or app. ## Formula **Meta Cost per Link Click** = **Meta Spend** ÷ **Meta Link Clicks** ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta ads | | [**Meta Link Clicks**](/reference/metrics/advertising/meta/meta-clicks/meta-link-clicks) | Clicks that direct users to your website, app, or other destination | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your fitness brand spent **\$3,600** on Meta traffic campaigns in April and generated **6,000 link clicks** to your website. | Campaign | Spend | Link Clicks | Cost/Link Click | | ------------- | ------- | ----------- | --------------- | | New Arrivals | \$1,800 | 3,600 | \$0.50 | | Seasonal Sale | \$1,200 | 2,000 | \$0.60 | | Blog Content | \$600 | 400 | \$1.50 | *** ## How It Works Meta counts link clicks as clicks that take users to your specified destination—your website, app store listing, or Instant Experience. Unlike total clicks (which include reactions, comments, and profile visits), link clicks measure intent to visit your property. This makes Cost per Link Click the standard efficiency metric for website traffic campaigns. *** ## When to Use | Scenario | Action | | -------------------------------------------- | --------------------------------------------------------------------------- | | Running traffic campaigns | Use this as your primary cost efficiency metric over CPC | | Cost per Link Click rising | Refresh creative or refine targeting to improve ad relevance | | Comparing to CPC | Large gap between CPC and Cost per Link Click suggests many non-link clicks | | Cost per Link Click low but conversions poor | Traffic is cheap but may not be qualified—review landing page or audience | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | | [Meta Link Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-link-clicks) | Denominator—the click count used in this formula | | [Meta CPC](/reference/metrics/advertising/meta/meta-clicks/meta-cpc) | Includes all clicks; compare to see engagement vs. traffic intent | | [Meta Cost per Outbound Click](/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-outbound-click) | Similar metric focused on clicks leaving Facebook/Instagram | [See all Meta Clicks metrics →](/reference/metrics/advertising/meta/meta-clicks) # Meta Cost per Outbound Click: Ad Traffic Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-outbound-click Measure how much you pay each time someone clicks from Meta to your website. Track traffic acquisition costs for campaign optimization. Measures how much you pay each time someone leaves Meta for your site—a key efficiency metric for traffic campaigns. ## Formula **Meta Cost per Outbound Click** = **Meta Spend** ÷ **Meta Outbound Clicks** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount billed by Meta for advertising during the period | | [**Meta Outbound Clicks**](/reference/metrics/advertising/meta/meta-clicks/meta-outbound-clicks) | Clicks on your ad that directed users to destinations outside Meta | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your traffic campaign spent **\$1,200** and generated **800 outbound clicks** this week. | Metric | Value | Context | | ----------------------- | ------- | ---------------------------- | | Meta Spend | \$1,200 | Weekly budget consumed | | Outbound Clicks | 800 | Clicks leaving Meta | | Cost per Outbound Click | \$1.50 | Acquisition cost per visitor | *** ## How It Works Meta tracks clicks that send users away from Facebook or Instagram to external destinations like your website or app. This metric divides your total spend by those outbound clicks, giving you the true cost of driving traffic off-platform. *** ## When to Use | Scenario | Action | | -------------------------------------- | --------------------------------------------------- | | Evaluating traffic campaign efficiency | Compare against industry benchmarks (\$0.50–\$2.00) | | High cost per outbound click | Test new creatives or refine audience targeting | | Comparing ad sets | Identify which audiences deliver cheapest traffic | | Budget allocation | Shift spend toward lower-cost campaigns | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | [Meta Outbound Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-outbound-clicks) | The click volume this cost metric is derived from | | [Meta Cost per Link Click](/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-link-click) | Broader click cost including CTA button clicks | [See all Meta Clicks metrics →](/reference/metrics/advertising/meta/meta-clicks) # Meta Cost per Unique Click: Average Cost for Unique Ad Engagers Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-unique-click Track your Meta cost per unique click to understand what you pay per unique person who clicks your ads. Optimize for efficient audience reach. Meta Cost per Unique Click measures the average cost to acquire a click from a unique person on your Meta ads, accounting for users who click multiple times. ## Formula **Meta Cost per Unique Click** = **Meta Spend** ÷ **Meta Unique Clicks** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------- | ------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising campaigns | | [**Meta Unique Clicks**](/reference/metrics/advertising/meta/meta-clicks/meta-unique-clicks) | Number of unique people who clicked your Meta ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your Meta campaign spent **\$5,000** and received clicks from **2,000 unique users**. | Metric | Value | Calculation | | ------------------------------ | ---------- | ------------------------- | | Meta Spend | \$5,000 | Total ad spend | | Meta Unique Clicks | 2,000 | Unique people who clicked | | **Meta Cost per Unique Click** | **\$2.50** | \$5,000 ÷ 2,000 | *** ## How It Works Meta Cost per Unique Click divides your total ad spend by the number of unique individuals who clicked your ads. Unlike standard CPC which counts every click, this metric de-duplicates users who clicked multiple times, giving you the true cost to engage each unique person. *** ## When to Use | Scenario | Action | | ------------------------------------ | ------------------------------------------------------------- | | Evaluating audience reach efficiency | Compare against standard CPC to see repeat click impact | | Optimizing retargeting campaigns | Monitor if the same users click repeatedly without converting | | Budget allocation decisions | Identify campaigns with efficient unique user acquisition | | Audience fatigue analysis | Rising cost per unique click may indicate creative exhaustion | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------- | ---------------------------------------------- | | [Meta Unique Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-unique-clicks) | The denominator in this calculation | | [Meta CPC](/reference/metrics/advertising/meta/meta-clicks/meta-cpc) | Standard cost per click without de-duplication | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | The numerator in this calculation | [See all Meta Clicks metrics →](/reference/metrics/advertising/meta/meta-clicks) # Meta CPC: Cost Per Click on Meta Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-clicks/meta-cpc Track Meta CPC to measure how efficiently your Meta ads drive traffic. Lower cost per click means more efficient ad spend. Meta CPC measures the average cost each time someone clicks your Meta ad—lower CPC means you're driving traffic more efficiently. ## Formula **Meta CPC** = **Meta Spend** ÷ **Meta Clicks** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------ | ------------------------------ | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta ads | | [**Meta Clicks**](/reference/metrics/advertising/meta/meta-clicks/meta-clicks) | Total clicks on your ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your Meta campaigns spent **\$2,500** and generated **5,000 clicks** last week. | Metric | Value | | ------------ | ---------- | | Meta Spend | \$2,500 | | Meta Clicks | 5,000 | | **Meta CPC** | **\$0.50** | *** ## How It Works Meta CPC divides your total ad spend by the number of clicks received. This gives you the average cost to drive one visitor to your site. CPC fluctuates based on audience targeting, creative performance, and competition in the auction. *** ## When to Use | Scenario | Action | | ----------------------- | ----------------------------------------------------------------------- | | Comparing ad efficiency | Use CPC to identify which campaigns drive traffic most cost-effectively | | Budget optimization | Shift spend toward lower-CPC campaigns to maximize traffic volume | | Creative testing | Compare CPC across ad variations to find top performers | | Audience analysis | Monitor CPC by audience segment to find efficient targets | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | [Meta Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-clicks) | Denominator—total clicks used in CPC calculation | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Numerator—total spend divided by clicks | | [Meta CTR](/reference/metrics/advertising/meta/meta-clicks/meta-ctr) | Engagement rate—affects CPC through auction dynamics | | [Meta Cost Per Link Click](/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-link-click) | Alternative metric measuring cost of outbound clicks only | [See all Meta Clicks metrics →](/reference/metrics/advertising/meta/meta-clicks) # Meta CTR: Measure Ad Click-Through Performance Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-clicks/meta-ctr Track your Meta Ads click-through rate to measure how often people click after seeing your ad. Optimize creative and targeting for higher engagement. Meta CTR measures the percentage of impressions that resulted in clicks on your Meta ads. ## Formula **Meta CTR** = ( **Meta Clicks** ÷ **Meta Impressions** ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------ | ----------------------------------------- | | [**Meta Clicks**](/reference/metrics/advertising/meta/meta-clicks/meta-clicks) | Total number of clicks on your Meta ads | | [**Meta Impressions**](/reference/metrics/advertising/meta/meta-audience/meta-impressions) | Total number of times your ads were shown | | Metadata | | | --------------- | --------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your summer campaign ad set delivered **125,000 impressions** and received **2,875 clicks** in June. | Ad Set | Impressions | Clicks | CTR | | -------------- | ----------- | --------- | --------- | | Summer Promo A | 75,000 | 1,950 | 2.60% | | Summer Promo B | 50,000 | 925 | 1.85% | | **Total** | **125,000** | **2,875** | **2.30%** | *** ## How It Works CTR is calculated by dividing total clicks by total impressions, then multiplying by 100 to express as a percentage. A higher CTR indicates your ad creative and targeting resonate with your audience, while a low CTR suggests your messaging or visuals may need refinement. *** ## When to Use | Scenario | Action | | ----------------------------- | ----------------------------------------------------------- | | Low CTR with high impressions | Test new creative variations or refine audience targeting | | CTR declining over time | Refresh ad creative to combat ad fatigue | | Comparing ad sets | Identify top performers and allocate budget accordingly | | Evaluating creative tests | Use CTR to determine which visuals or copy drive engagement | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------- | ------------------------------------------------ | | [Meta Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-clicks) | The numerator in the CTR calculation | | [Meta Impressions](/reference/metrics/advertising/meta/meta-audience/meta-impressions) | The denominator in the CTR calculation | | [Meta Link CTR](/reference/metrics/advertising/meta/meta-clicks/meta-link-ctr) | CTR specifically for link clicks to your website | [See all Meta Clicks metrics →](/reference/metrics/advertising/meta/meta-clicks) # Meta Inline Clicks: Track Link Clicks Within Your Meta Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-clicks/meta-inline-clicks Track clicks on links embedded within your Meta ads, including post body links and carousel card links. Measure in-ad engagement. Meta Inline Clicks measures the number of clicks on links embedded inside the ad unit itself, such as links in the post body or carousel cards. ## Formula **Meta Inline Clicks** = **COUNT** ( Inline link clicks ) ### Formula Components | Metric | Definition | | ------------------ | --------------------------------------------------------------------- | | Inline link clicks | Clicks on links within the ad content itself, not the main CTA button | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your Meta campaign generated **2,847 inline clicks** last week from carousel card links. | Ad Format | Inline Clicks | Click Location | | ------------ | ------------- | ---------------- | | Carousel Ad | 1,623 | Card links | | Single Image | 892 | Post body link | | Video Ad | 332 | Description link | *** ## How It Works Meta tracks inline clicks separately from main CTA clicks. These are clicks on links embedded within the ad creative—like links in the post text, carousel card destinations, or video description links. This metric helps you understand engagement with supplementary links in your ad content. *** ## When to Use | Scenario | Action | | ----------------------------- | ------------------------------------------------------------------------------- | | Carousel performance analysis | Compare inline clicks across carousel cards to identify top-performing products | | Ad copy optimization | Test different link placements in post body to maximize engagement | | Multi-link ad strategy | Measure effectiveness of secondary links beyond your main CTA | | Content engagement tracking | Understand how users interact with in-ad content links | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | ------------------------------------- | | [Meta Inline Clicks CTR](/reference/metrics/advertising/meta/meta-clicks/meta-inline-clicks-ctr) | Click-through rate for inline links | | [Meta Cost per Inline Click](/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-inline-click) | Cost efficiency of inline clicks | | [Meta Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-clicks) | Total clicks including CTA and inline | [See all Meta Clicks metrics →](/reference/metrics/advertising/meta/meta-clicks) # Meta Inline CTR: Measure In-Ad Link Engagement Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-clicks/meta-inline-clicks-ctr Track your Meta Ads inline click-through rate to measure how often viewers click embedded links in your ad content. Optimize carousel and copy performance. Meta Inline CTR measures the percentage of impressions that resulted in clicks on links embedded within your Meta ad unit. ## Formula **Meta Inline CTR** = ( **Meta Inline Clicks** ÷ **Meta Impressions** ) × 100 ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | [**Meta Inline Clicks**](/reference/metrics/advertising/meta/meta-clicks/meta-inline-clicks) | Clicks on links embedded within ad content (carousel cards, text links) | | [**Meta Impressions**](/reference/metrics/advertising/meta/meta-audience/meta-impressions) | Total number of times your ads were displayed | | Metadata | | | --------------- | --------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your carousel campaign delivered **185,000 impressions** and generated **2,960 inline clicks** last month: | Metric | Value | | ------------------- | --------- | | Meta Impressions | 185,000 | | Meta Inline Clicks | 2,960 | | **Meta Inline CTR** | **1.60%** | *** ## How It Works Inline CTR calculates how often viewers click embedded links within your ad creative—such as carousel card links or text links in post copy—rather than the primary CTA button. A higher Inline CTR indicates your ad content is compelling enough to drive engagement beyond the main call-to-action. *** ## When to Use | Scenario | Action | | -------------------------------- | --------------------------------------------------------- | | Low inline engagement | Test more compelling carousel card copy or link placement | | High overall CTR, low Inline CTR | Strengthen embedded links and in-ad content | | Comparing ad formats | Evaluate which creative types drive embedded clicks | | Optimizing multi-link ads | Identify which inline link positions perform best | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------- | ----------------------------------------- | | [Meta Inline Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-inline-clicks) | Numerator in the Inline CTR calculation | | [Meta CTR](/reference/metrics/advertising/meta/meta-clicks/meta-ctr) | Overall click-through rate for comparison | | [Meta Impressions](/reference/metrics/advertising/meta/meta-audience/meta-impressions) | Denominator in the Inline CTR calculation | [See all Meta Clicks metrics →](/reference/metrics/advertising/meta/meta-clicks) # Meta Landing Page View Rate: Measure Click-to-Load Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-clicks/meta-landing-page-view-rate Track Meta landing page view rate to see what percentage of ad clicks actually load your page. Low rates indicate page speed or bounce issues. Meta Landing Page View Rate measures the percentage of link clicks that resulted in your landing page fully loading. ## Formula **Meta Landing Page View Rate** = ( **Meta Landing Page Views** ÷ **Meta Link Clicks** ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | | [**Meta Landing Page Views**](/reference/metrics/advertising/meta/meta-clicks/meta-landing-page-views) | Number of times your landing page fully loaded after an ad click | | [**Meta Link Clicks**](/reference/metrics/advertising/meta/meta-clicks/meta-link-clicks) | Clicks on your ad's CTA button or primary link directing to your destination | | Metadata | | | --------------- | --------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Average | *** ## Example Your campaign received **2,450 link clicks** and **1,890 landing page views** in January, resulting in a **77.1% landing page view rate**. | Metric | Value | Insight | | ------------------ | ----- | -------------------------------------------- | | Link Clicks | 2,450 | Total ad clicks | | Landing Page Views | 1,890 | Pages that fully loaded | | LP View Rate | 77.1% | Share of clicks that converted to page loads | *** ## How It Works Meta calculates this rate by dividing landing page views by link clicks. A landing page view fires when your page fully loads after someone clicks your ad. Low rates suggest users are leaving before the page renders—often due to slow load times, excessive redirects, or mobile performance issues. *** ## When to Use | Scenario | Action | | ------------------------------- | ------------------------------------------------------------- | | LP view rate below 70% | Audit page speed and reduce redirects | | Mobile rates lower than desktop | Optimize mobile page performance and reduce asset sizes | | Comparing landing pages | Identify which pages retain traffic best after ad clicks | | Diagnosing high CPA | Check if users are reaching the page before blaming targeting | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------- | | [Meta Landing Page Views](/reference/metrics/advertising/meta/meta-clicks/meta-landing-page-views) | Numerator—total landing page loads | | [Meta Link Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-link-clicks) | Denominator—total clicks on ad links | | [Meta Cost per Landing Page View](/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-landing-page-view) | Cost efficiency for actual page loads | [See all Meta Clicks metrics →](/reference/metrics/advertising/meta/meta-clicks) # Meta Landing Page Views: Track Ad Click Conversions Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-clicks/meta-landing-page-views Track Meta landing page views to measure how many people fully loaded your page after clicking ads. Identify drop-off between clicks and page loads. Meta Landing Page Views counts how many times your landing page fully loaded after someone clicked your ad. ## Formula **Meta Landing Page Views** = **COUNT** ( Landing page loads ) ### Formula Components | Metric | Definition | | ------------------ | ---------------------------------------------------------------------------------------- | | Landing page loads | Number of times the destination page fired the landing page view event after an ad click | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your campaign received **2,450 link clicks** but only **1,890 landing page views** in January. | Metric | Value | Insight | | ------------------ | --------- | --------------------------------- | | Link Clicks | 2,450 | Total ad clicks | | Landing Page Views | 1,890 | Pages that fully loaded | | Drop-off | 560 (23%) | Users who left before page loaded | *** ## How It Works Meta fires a landing page view event when your page fully loads after someone clicks your ad. This metric counts those events, giving you visibility into how many users actually reached your content versus bouncing before the page rendered. *** ## When to Use | Scenario | Action | | ---------------------------------------------- | ----------------------------------------------------------------- | | Landing page views much lower than link clicks | Improve page load speed or reduce redirects | | High drop-off rate on mobile | Optimize mobile page performance | | Comparing landing pages | Identify which pages retain traffic best | | Diagnosing conversion funnel leaks | Check if users are reaching the page before optimizing conversion | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | | [Meta Link Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-link-clicks) | Total clicks before landing page load filter | | [Meta Landing Page Views Cost](/reference/metrics/advertising/meta/meta-clicks/meta-landing-page-views-cost) | Cost per landing page view | | [Meta Landing Page View Rate](/reference/metrics/advertising/meta/meta-clicks/meta-landing-page-view-rate) | Percentage of clicks that result in page views | [See all Meta Clicks metrics →](/reference/metrics/advertising/meta/meta-clicks) # Meta Link Clicks: Track Ad Link Engagement Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-clicks/meta-link-clicks Track link clicks on your Meta ads. Measure how many people click your CTA button or primary link directing to your website or app. Meta Link Clicks measures the number of clicks specifically on your ad's call-to-action button or primary link that direct people to your website or app. ## Formula **Meta Link Clicks** = **COUNT** ( Link clicks ) ### Formula Components | Metric | Definition | | ----------- | ---------------------------------------------------------------------------- | | Link clicks | Clicks on your ad's CTA button or primary link directing to your destination | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your Meta campaign received **3,847 link clicks** last week across all ad sets. | Ad Set | Link Clicks | CTR | | ---------------------- | ----------- | ---- | | Prospecting - Broad | 2,156 | 1.8% | | Retargeting - Cart | 1,247 | 3.2% | | Lookalike - Purchasers | 444 | 1.4% | *** ## How It Works Meta counts a link click when someone clicks your ad's primary destination link—the CTA button, headline link, or any link configured to send traffic to your website or app. This excludes clicks on your profile, comments, shares, or photo expansions. Link clicks are the standard metric for measuring outbound traffic from your ads. *** ## When to Use | Scenario | Action | | ------------------------------- | ------------------------------------------------------------------- | | Measuring traffic generation | Track link clicks to see how many people your ads send to your site | | Optimizing for website visits | Use link clicks as your campaign objective metric | | Calculating cost efficiency | Divide spend by link clicks to get cost per link click | | Comparing to landing page views | Check the ratio to identify page load or redirect issues | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | [Meta Link Clicks CTR](/reference/metrics/advertising/meta/meta-clicks/meta-link-clicks-ctr) | Percentage of impressions resulting in link clicks | | [Meta Cost per Link Click](/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-link-click) | Average cost to generate one link click | | [Meta Landing Page Views](/reference/metrics/advertising/meta/meta-clicks/meta-landing-page-views) | How many link clicks actually loaded your landing page | [See all Meta Clicks metrics →](/reference/metrics/advertising/meta/meta-clicks) # Meta Link CTR: Measure Ad Creative Performance Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-clicks/meta-link-ctr Track how often people click your primary link after seeing your Meta ad. Calculate Link Click-Through Rate to evaluate creative and targeting quality. Link Click-Through Rate measures the percentage of impressions that resulted in clicks on your ad's primary link. ## Formula **Meta Link CTR** = ( **Meta Link Clicks** ÷ **Meta Impressions** ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | | [**Meta Link Clicks**](/reference/metrics/advertising/meta/meta-clicks/meta-link-clicks) | Clicks on your ad's call-to-action button or primary destination link | | [**Meta Impressions**](/reference/metrics/advertising/meta/meta-audience/meta-impressions) | Total number of times your ads were shown | | Metadata | | | --------------- | --------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your summer collection campaign generated **4,200 link clicks** from **210,000 impressions**. | Campaign | Link Clicks | Impressions | Link CTR | | ----------------- | ----------- | ----------- | --------- | | Summer Collection | 4,200 | 210,000 | 2.00% | | Spring Clearance | 2,850 | 285,000 | 1.00% | | **Total** | **7,050** | **495,000** | **1.42%** | *** ## How It Works Link CTR counts only clicks on your primary call-to-action button or destination link—not social interactions like likes or comments. This makes it more focused than overall CTR for measuring intent to visit your site or app. *** ## When to Use | Scenario | Action | | ----------------------- | ---------------------------------------------------- | | Link CTR drops below 1% | Test new creative or refine audience targeting | | Link CTR exceeds 2% | Scale budget or expand to similar audiences | | Comparing ad variations | Use Link CTR to identify highest-performing creative | | Traffic campaigns | Monitor Link CTR as primary efficiency indicator | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [Meta Link Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-link-clicks) | The numerator—total clicks on your primary link | | [Meta CTR](/reference/metrics/advertising/meta/meta-clicks/meta-ctr) | Broader metric counting all clicks, not just link clicks | | [Meta Outbound CTR](/reference/metrics/advertising/meta/meta-clicks/meta-outbound-ctr) | Clicks that leave Meta entirely for your destination | [See all Meta Clicks metrics →](/reference/metrics/advertising/meta/meta-clicks) # Meta Outbound Clicks: Clicks Leaving Meta Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-clicks/meta-outbound-clicks Track Meta outbound clicks—the number of ad clicks that took people to your website or app. Measure off-platform traffic from Meta ads. Meta Outbound Clicks measures the number of clicks on your ads that sent people to destinations outside of Meta—typically your website or app. ## Formula **Meta Outbound Clicks** = **COUNT** ( Clicks leaving Meta ) ### Formula Components | Metric | Definition | | ----------------------- | ----------------------------------------------------------------------------------------------------------- | | **Clicks leaving Meta** | Clicks on your ad that directed users to an external destination such as your website, app, or landing page | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your Meta campaign generated **4,872 outbound clicks** this week, sending users directly to your product pages. | Campaign | Impressions | Outbound Clicks | Outbound CTR | | ------------ | ----------- | --------------- | ------------ | | Summer Sale | 125,000 | 2,340 | 1.87% | | New Arrivals | 98,000 | 1,532 | 1.56% | | Retargeting | 45,000 | 1,000 | 2.22% | *** ## How It Works Meta counts an outbound click each time someone clicks on your ad and is directed to a destination outside of Meta's properties. This includes clicks to your website, app store listing, or any external URL. Outbound clicks exclude interactions that stay within Meta (like expanding an ad, viewing a profile, or clicking to comment). *** ## When to Use | Scenario | Action | | --------------------------------------- | ------------------------------------------------------------------- | | Measuring website traffic from ads | Track outbound clicks to see how many users Meta sent to your site | | Comparing link vs. engagement campaigns | Use outbound clicks to focus on traffic-driving objectives | | Optimizing landing page performance | Compare outbound clicks to landing page views to identify drop-off | | Evaluating cost efficiency | Calculate cost per outbound click to measure acquisition efficiency | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | | [Meta Outbound Clicks CTR](/reference/metrics/advertising/meta/meta-clicks/meta-outbound-clicks-ctr) | Percentage of impressions resulting in outbound clicks | | [Meta Cost Per Outbound Click](/reference/metrics/advertising/meta/meta-clicks/meta-cost-per-outbound-click) | Average cost for each outbound click | | [Meta Landing Page Views](/reference/metrics/advertising/meta/meta-views/meta-landing-page-views) | Users who clicked and loaded your landing page | [See all Meta Clicks metrics →](/reference/metrics/advertising/meta/meta-clicks) # Meta Outbound Click-Through Rate: Website Traffic Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-clicks/meta-outbound-ctr Track the percentage of impressions that drove traffic off Meta to your website. The most relevant CTR for website-focused campaigns. Meta Outbound CTR measures the percentage of impressions that resulted in outbound clicks—the share of ad views that drove someone off Meta to your destination. ## Formula **Meta Outbound CTR** = ( **Meta Outbound Clicks** ÷ **Meta Impressions** ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | | [**Meta Outbound Clicks**](/reference/metrics/advertising/meta/meta-clicks/meta-outbound-clicks) | Clicks on your ad that directed users to an external destination outside Meta | | [**Meta Impressions**](/reference/metrics/advertising/meta/meta-audience/meta-impressions) | Total number of times your ad was displayed on screen | | Metadata | | | --------------- | --------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your traffic campaign delivered **185,000 impressions** and generated **3,145 outbound clicks** in March: | Ad Set | Impressions | Outbound Clicks | Outbound CTR | | ----------------------------- | ----------- | --------------- | ------------ | | Prospecting - Lookalike | 95,000 | 1,900 | 2.00% | | Retargeting - Cart Abandoners | 50,000 | 850 | 1.70% | | Interest - Home Decor | 40,000 | 395 | 0.99% | | **Total** | **185,000** | **3,145** | **1.70%** | *** ## How It Works Outbound CTR counts only clicks that take users away from Meta properties (Facebook, Instagram, Messenger) to your external destination. This excludes in-platform interactions like reactions, comments, and profile visits. For campaigns optimized for website traffic, outbound CTR provides a clearer signal of ad effectiveness than overall CTR. *** ## When to Use | Scenario | Action | | --------------------------------------- | ---------------------------------------------------------- | | Running traffic or conversion campaigns | Use outbound CTR as your primary click-through metric | | Outbound CTR below 1% | Test new creative or refine audience targeting | | Comparing to overall CTR | Large gaps may indicate engagement but not intent to visit | | Evaluating website-focused ads | Prioritize ad sets with higher outbound CTR | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------- | ---------------------------------------- | | [Meta Outbound Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-outbound-clicks) | Numerator—total clicks leaving Meta | | [Meta CTR](/reference/metrics/advertising/meta/meta-clicks/meta-ctr) | Broader metric including all click types | | [Meta Link CTR](/reference/metrics/advertising/meta/meta-clicks/meta-link-ctr) | CTR for primary link clicks specifically | [See all Meta Clicks metrics →](/reference/metrics/advertising/meta/meta-clicks) # Meta Unique Clicks: Distinct Ad Clickers Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-clicks/meta-unique-clicks Track how many distinct people clicked your Meta ads. Measure true audience reach and engagement by counting unique clickers, not repeat clicks. Meta Unique Clicks measures the number of distinct individuals who clicked on your Meta ads, counting each person only once regardless of how many times they clicked. ## Formula **Meta Unique Clicks** = **COUNT DISTINCT** ( People who clicked ) ### Formula Components | Metric | Definition | | ---------------------- | -------------------------------------------------------------------------------------- | | **People who clicked** | Individual users who clicked on your Meta ad at least once during the reporting period | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your Meta campaign reached **45,000 people** last week, and **3,240 unique individuals** clicked on your ads. | Metric | Value | Insight | | -------------------------------------------------------------------------- | ----- | --------------------------------- | | [Meta Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-clicks) | 4,850 | Total click events recorded | | Meta Unique Clicks | 3,240 | Distinct people who clicked | | Repeat Click Rate | 1.5× | Average clicks per unique clicker | This tells you that 3,240 real people engaged with your ads, with some clicking multiple times. *** ## How It Works Meta tracks user identity across sessions to deduplicate click events. When the same person clicks your ad three times, Meta Clicks counts 3 while Meta Unique Clicks counts 1. This deduplication uses Meta's cross-device identity graph to recognize the same person across different devices and browsers. *** ## When to Use | Scenario | Action | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Measuring true audience engagement | Use unique clicks instead of total clicks to understand how many real people interacted | | Identifying repeat clicker patterns | Compare unique clicks to total clicks to find ads driving curiosity vs. immediate action | | Calculating accurate CTR | Use [Meta Unique Clicks CTR](/reference/metrics/advertising/meta/meta-clicks/meta-unique-clicks-ctr) for click-through rate based on unique clickers | | Frequency capping decisions | High ratio of total clicks to unique clicks may indicate over-exposure | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | | [Meta Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-clicks) | Total click count including repeat clicks from the same person | | [Meta Unique Clicks CTR](/reference/metrics/advertising/meta/meta-clicks/meta-unique-clicks-ctr) | Click-through rate calculated using unique clickers | | [Meta Impressions](/reference/metrics/advertising/meta/meta-audience/meta-impressions) | Total ad views that drive click behavior | [See all Meta Clicks metrics →](/reference/metrics/advertising/meta/meta-clicks) # Meta Unique CTR: Click Rate Without Repeat Clickers Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-clicks/meta-unique-ctr Track the percentage of people who clicked your Meta ads at least once. Measure true engagement by removing inflation from repeat clickers. Meta Unique CTR measures the percentage of people who clicked on your ad at least once, removing the inflation from repeat clickers. ## Formula **Meta Unique CTR** = ( **Meta Unique Clicks** ÷ **Meta Reach** ) × 100 ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | [**Meta Unique Clicks**](/reference/metrics/advertising/meta/meta-clicks/meta-unique-clicks) | Number of distinct people who clicked on your ad at least once | | [**Meta Reach**](/reference/metrics/advertising/meta/meta-audience/meta-reach) | Number of unique people who saw your ad at least once | | Metadata | | | --------------- | --------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your prospecting campaign reached **85,000 unique people** last week, and **2,550 distinct individuals** clicked on your ads. | Metric | Value | Insight | | ---------------------------------------------------------------------------------------- | ------ | ----------------------------- | | [Meta Reach](/reference/metrics/advertising/meta/meta-audience/meta-reach) | 85,000 | Unique people who saw the ad | | [Meta Unique Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-unique-clicks) | 2,550 | Distinct people who clicked | | Meta Unique CTR | 3.00% | Share of audience who clicked | This tells you that 3% of the people who saw your ad took action—a cleaner engagement signal than standard CTR. *** ## How It Works Unique CTR divides unique clickers by unique viewers, giving you a person-based click rate. Unlike standard [Meta CTR](/reference/metrics/advertising/meta/meta-clicks/meta-ctr) which uses impressions (and can be inflated by high frequency), Unique CTR shows what share of your actual audience engaged. This makes it especially useful for comparing ads served at different frequencies. *** ## When to Use | Scenario | Action | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | Comparing ads with different frequencies | Use Unique CTR to normalize for impression count differences | | Measuring true audience engagement | Unique CTR shows what percentage of reached people clicked | | Identifying ad fatigue | If [Meta CTR](/reference/metrics/advertising/meta/meta-clicks/meta-ctr) is high but Unique CTR is low, the same people are clicking repeatedly | | Evaluating prospecting creative | Unique CTR reveals how well your ad resonates with new audiences | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | [Meta Unique Clicks](/reference/metrics/advertising/meta/meta-clicks/meta-unique-clicks) | The numerator—distinct people who clicked | | [Meta CTR](/reference/metrics/advertising/meta/meta-clicks/meta-ctr) | Standard click-through rate based on impressions, not people | | [Meta Reach](/reference/metrics/advertising/meta/meta-audience/meta-reach) | The denominator—unique people who saw your ad | [See all Meta Clicks metrics →](/reference/metrics/advertising/meta/meta-clicks) # Meta Conversion Metrics Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/index Track Meta attributed conversions in Upstack. Monitor purchases, add-to-carts, leads, app installs, and 34 conversion events from your campaigns. Conversion metrics track actions people take after engaging with your Meta ads. These include purchases, add-to-carts, leads, registrations, and other pixel or Conversions API events. **Data Source:** Meta Marketing API + Meta Pixel/CAPI\ **Metrics:** 34 ## Metrics in This Group ### E-commerce Conversions | Metric | Description | When to Use | | --------------------------------------------------------------------------------------------------------------- | -------------------------- | ---------------------------------- | | [Meta Purchases](/reference/metrics/advertising/meta/meta-conversions/meta-purchases) | Attributed purchase count | Measure sales volume | | [Meta Purchases Value](/reference/metrics/advertising/meta/meta-conversions/meta-purchases-value) | Revenue from purchases | Track revenue attribution | | [Meta New Customer Purchases](/reference/metrics/advertising/meta/meta-conversions/meta-new-customer-purchases) | First-time buyer purchases | Measure customer acquisition | | [Meta Add to Carts](/reference/metrics/advertising/meta/meta-conversions/meta-add-to-carts) | Add to cart actions | Track purchase intent | | [Meta View Contents](/reference/metrics/advertising/meta/meta-conversions/meta-view-contents) | Product page views | Measure product interest | | [Meta Initiate Checkouts](/reference/metrics/advertising/meta/meta-conversions/meta-initiate-checkouts) | Checkout starts | Track conversion funnel progress | | [Meta Add Payment Info](/reference/metrics/advertising/meta/meta-conversions/meta-add-payment-info) | Payment info additions | Measure checkout completion intent | ### Lead Generation | Metric | Description | When to Use | | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ----------------------------- | | [Meta Leads](/reference/metrics/advertising/meta/meta-conversions/meta-leads) | Lead form submissions | Track lead gen campaigns | | [Meta Completed Registrations](/reference/metrics/advertising/meta/meta-conversions/meta-completed-registrations) | Account sign-ups | Measure sign-up campaigns | | [Meta Contact Events](/reference/metrics/advertising/meta/meta-conversions/meta-contact-events) | Contact form submissions | Track inquiry volume | | [Meta Submit Application Events](/reference/metrics/advertising/meta/meta-conversions/meta-submit-application-events) | Application submissions | Measure application campaigns | | [Meta Messaging Conversations Started](/reference/metrics/advertising/meta/meta-conversions/meta-messaging-conversations-started) | Messaging initiations | Track click-to-message ads | ### App & Subscription | Metric | Description | When to Use | | --------------------------------------------------------------------------------------------- | --------------------- | ----------------------------------- | | [Meta App Installs](/reference/metrics/advertising/meta/meta-conversions/meta-app-installs) | Mobile app installs | Measure app install campaigns | | [Meta Subscriptions](/reference/metrics/advertising/meta/meta-conversions/meta-subscriptions) | Subscription sign-ups | Track recurring revenue acquisition | | [Meta Subscribes](/reference/metrics/advertising/meta/meta-conversions/meta-subscribes) | Subscribe actions | Measure newsletter/list growth | | [Meta Start Trials](/reference/metrics/advertising/meta/meta-conversions/meta-start-trials) | Trial initiations | Track trial sign-up campaigns | ### Other Conversions | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------------------------------- | ---------------------- | ----------------------------- | | [Meta Customize Product Events](/reference/metrics/advertising/meta/meta-conversions/meta-customize-product-events) | Product customizations | Track configurator engagement | | [Meta Donate Events](/reference/metrics/advertising/meta/meta-conversions/meta-donate-events) | Donation actions | Measure fundraising campaigns | | [Meta Find Location Events](/reference/metrics/advertising/meta/meta-conversions/meta-find-location-events) | Location searches | Track store locator usage | | [Meta Schedule Events](/reference/metrics/advertising/meta/meta-conversions/meta-schedule-events) | Schedule bookings | Measure appointment campaigns | | [Meta Search Events](/reference/metrics/advertising/meta/meta-conversions/meta-search-events) | On-site searches | Track search engagement | ### Cost per Conversion | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------ | | [Meta Cost per Add to Cart](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-add-to-cart) | Spend ÷ Add to carts | Evaluate cart acquisition cost | | [Meta Cost per Lead](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-lead) | Spend ÷ Leads | Optimize lead gen efficiency | | [Meta Cost per Registration](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-registration) | Spend ÷ Registrations | Track sign-up acquisition cost | | [Meta Cost per Add Payment Info](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-add-payment-info) | Spend ÷ Payment info | Measure checkout intent cost | | [Meta Cost per Contact](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-contact) | Spend ÷ Contacts | Evaluate inquiry acquisition cost | | [Meta Cost per Customize Product](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-customize-product) | Spend ÷ Customizations | Track configurator engagement cost | | [Meta Cost per Donate](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-donate) | Spend ÷ Donations | Evaluate fundraising efficiency | | [Meta Cost per Find Location](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-find-location) | Spend ÷ Location searches | Measure store visit intent cost | | [Meta Cost per Schedule](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-schedule) | Spend ÷ Schedules | Track appointment acquisition cost | | [Meta Cost per Search](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-search) | Spend ÷ Searches | Evaluate search engagement cost | | [Meta Cost per Start Trial](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-start-trial) | Spend ÷ Trials | Measure trial acquisition efficiency | | [Meta Cost per Submit Application](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-submit-application) | Spend ÷ Applications | Evaluate application cost | | [Meta Cost per Subscribe](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-subscribe) | Spend ÷ Subscribes | Track subscriber acquisition cost | ## How Attribution Works Meta attributes conversions using its attribution window. Default is 7-day click and 1-day view—meaning conversions are attributed if someone clicked within 7 days or viewed within 1 day. ## Choosing the Right Metric * **E-commerce**: Use Purchases and Purchases Value for revenue impact * **Lead generation**: Use Leads and Completed Registrations for pipeline building * **Funnel analysis**: Track View Contents → Add to Cart → Initiate Checkout → Purchase * **Cost efficiency**: Use Cost per \[Event] metrics to evaluate campaign efficiency * **New customer focus**: Use New Customer Purchases to isolate acquisition # Meta Add Payment Info: Payment Details Entered from Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-add-payment-info Track how many add payment info events Meta attributes to your ads. Measure this critical checkout step to optimize for higher purchase completion rates. Meta Add Payment Info counts how many people added payment information after engaging with your ad—a critical step before purchase completion. ## Formula **Meta Add Payment Info** = **COUNT** ( add\_payment\_info events ) Each add-payment-info action attributed to your Meta ads is counted once. | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your Meta campaigns drove **1,892 payment info submissions** in March across different campaign objectives. | Campaign | Add Payment Info | Spend | Cost/Payment Info | | ----------- | ---------------- | ------- | ----------------- | | Retargeting | 1,047 | \$1,620 | \$1.55 | | Lookalike | 584 | \$2,340 | \$4.01 | | Prospecting | 261 | \$1,890 | \$7.24 | *** ## How It Works Meta counts an add-payment-info event when a visitor enters payment details (credit card, PayPal, etc.) during checkout after interacting with your ad within the attribution window. The event is captured via the Meta Pixel or Conversions API when the shopper submits their payment method. *** ## When to Use | Scenario | Action | | -------------------------------- | --------------------------------------------------------------------------------- | | Measuring checkout intent | Compare payment info submissions to initiated checkouts to assess buyer readiness | | Identifying payment friction | Low add-payment-info vs high checkouts signals payment UX issues | | Diagnosing funnel drop-off | Compare payment info to purchases to find final-step abandonment | | Optimizing for high-intent users | Shift budget to campaigns driving more payment submissions | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | [Meta Cost per Add Payment Info](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-add-payment-info) | Efficiency of driving payment submissions | | [Meta Initiate Checkouts](/reference/metrics/advertising/meta/meta-conversions/meta-initiate-checkouts) | Previous step in the purchase funnel | | [Meta Purchases](/reference/metrics/advertising/meta/meta-conversions/meta-purchases) | Final conversion after payment info | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Add to Carts: Mid-Funnel Purchase Intent Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-add-to-carts Track Meta Add to Carts to measure purchase intent from your ads. Monitor how many visitors add products to cart after engaging with Meta campaigns. Meta Add to Carts counts how many add-to-cart events Meta attributes to your ads, indicating mid-funnel purchase intent. ## Formula **Meta Add to Carts** = **COUNT** ( add\_to\_cart events ) Each add-to-cart event attributed to your Meta ads is counted once, regardless of cart value. | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your Meta campaigns drove **2,847 add-to-carts** in March across three ad sets. | Ad Set | Add to Carts | Spend | Cost per ATC | | ----------- | ------------ | ------- | ------------ | | Retargeting | 1,412 | \$1,412 | \$1.00 | | Lookalike | 898 | \$1,796 | \$2.00 | | Prospecting | 537 | \$2,148 | \$4.00 | *** ## How It Works Meta counts an add-to-cart event when a visitor adds a product to their shopping cart after interacting with your ad within the attribution window. The event is captured via the Meta Pixel on your site or sent through the Conversions API from your server. *** ## When to Use | Scenario | Action | | --------------------------------- | ------------------------------------------------------------------------------ | | Measuring purchase intent | Track add-to-cart volume to gauge how many visitors show buying interest | | Evaluating mid-funnel performance | Compare add-to-cart counts across campaigns to identify engagement drivers | | Diagnosing funnel drop-off | Analyze the gap between add-to-carts and purchases to find conversion blockers | | Optimizing prospecting campaigns | Monitor add-to-carts for cold audiences where immediate purchases are rare | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | [Meta Cost per Add to Cart](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-add-to-cart) | Efficiency metric for add-to-cart acquisition | | [Meta Purchases](/reference/metrics/advertising/meta/meta-conversions/meta-purchases) | Final conversion event in the purchase funnel | | [Meta Initiate Checkouts](/reference/metrics/advertising/meta/meta-conversions/meta-initiate-checkouts) | Next step in the funnel after add-to-cart | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta App Installs: Mobile App Installations from Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-app-installs Track mobile app installations from Meta ads. Measure app install campaign performance and optimize user acquisition costs. Counts how many people installed your mobile app after engaging with your Meta ad—the primary metric for app install campaigns. ## Formula **Meta App Installs** = **COUNT** ( app\_install events ) ### Formula Components | Metric | Definition | | ----------------------- | -------------------------------------------------------------------------------------- | | **app\_install events** | Each mobile app installation attributed to your Meta ads within the attribution window | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your Meta app install campaigns drove **2,847 installs** in Q2 across iOS and Android. | Campaign | Installs | Spend | Cost per Install | | ------------- | -------- | ------- | ---------------- | | iOS Lookalike | 1,423 | \$4,269 | \$3.00 | | Android Broad | 892 | \$3,568 | \$4.00 | | Retargeting | 532 | \$1,330 | \$2.50 | *** ## How It Works Meta counts an app install when a user downloads and opens your app after interacting with your ad within the attribution window. Install events are captured via the Meta SDK integrated in your mobile app, which sends the installation signal back to Meta's servers for attribution. *** ## When to Use | Scenario | Action | | ------------------------------ | ------------------------------------------------------------------ | | Evaluating app campaigns | Compare install counts across campaigns to identify top performers | | Optimizing cost per install | Shift budget toward ad sets driving installs more efficiently | | Assessing platform performance | Compare iOS vs Android install volumes and costs | | Planning acquisition budgets | Forecast install volumes based on historical campaign data | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total ad investment used to calculate cost per install | | [Meta Completed Registrations](/reference/metrics/advertising/meta/meta-conversions/meta-completed-registrations) | Users who registered after installing your app | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Completed Registrations: Account Sign-ups from Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-completed-registrations Track Meta Completed Registrations to measure how many people signed up for accounts after engaging with your Meta ads. Optimize sign-up campaigns. Meta Completed Registrations counts how many people finished a registration or sign-up flow after engaging with your Meta ads. ## Formula **Meta Completed Registrations** = **COUNT** ( CompleteRegistration events ) | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your SaaS app ran a Meta campaign promoting free trial sign-ups. In the first week, **842 registrations** were completed. | Campaign | Spend | Registrations | Cost per Registration | | ---------------------- | ------- | ------------- | --------------------- | | Free Trial - Broad | \$2,400 | 512 | \$4.69 | | Free Trial - Lookalike | \$1,800 | 330 | \$5.45 | *** ## How It Works Meta tracks the CompleteRegistration event fired when a user finishes your sign-up flow. Attribution follows your account's attribution window settings (typically 7-day click, 1-day view). Registrations from both Facebook and Instagram placements are combined. *** ## When to Use | Scenario | Action | | --------------------------------------- | ----------------------------------------------------------- | | Evaluating sign-up campaign performance | Compare registration volume across ad sets | | Optimizing for lower-funnel conversions | Use as the conversion event for campaign optimization | | Building lead generation funnels | Track progression from lead to registered user | | Calculating customer acquisition costs | Pair with cost per registration to find efficient campaigns | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | [Meta Cost per Registration](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-registration) | Spend efficiency per registration | | [Meta Leads](/reference/metrics/advertising/meta/meta-conversions/meta-leads) | Earlier funnel stage before registration | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total ad spend used to calculate cost per registration | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Contact Events: Contact Form Submissions from Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-contact-events Track how many contact events your Meta ads generate including email, chat, and call inquiries to measure lead generation for service businesses. Meta Contact Events counts how many people initiated contact (email, chat, or call) after engaging with your Meta ads. ## Formula **Meta Contact Events** = **COUNT** ( Contact Events ) | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your home services business generated **312 contact requests** in March across three service categories. | Service Category | Contacts | Spend | Cost per Contact | | ----------------- | -------- | ------- | ---------------- | | HVAC Repair | 142 | \$2,840 | \$20.00 | | Plumbing Services | 98 | \$1,960 | \$20.00 | | Electrical Work | 72 | \$1,440 | \$20.00 | *** ## How It Works Meta counts a contact event when someone initiates contact through email, chat, phone, or a contact form after interacting with your ad within the attribution window. Contact events are captured via the Meta Pixel or Conversions API when you fire the Contact standard event. *** ## When to Use | Scenario | Action | | -------------------------------- | ---------------------------------------------------------- | | Measuring service business leads | Track contact volume as your primary lead metric | | Comparing lead channels | Evaluate contact events against leads and form submissions | | Optimizing campaign targeting | Shift budget toward audiences generating more contacts | | Calculating acquisition costs | Use with cost per contact to measure efficiency | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------- | -------------------------------------------- | | [Meta Cost per Contact](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-contact) | Cost to acquire each contact event | | [Meta Leads](/reference/metrics/advertising/meta/meta-conversions/meta-leads) | Alternative lead metric for form submissions | | [Meta Schedule Events](/reference/metrics/advertising/meta/meta-conversions/meta-schedule-events) | Appointment booking metric | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Cost per Add Payment Info: Payment Entry Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-add-payment-info Track Meta Cost per Add Payment Info to measure payment entry efficiency. Calculate spend per payment submission to optimize checkout funnel costs. Meta Cost per Add Payment Info measures the average spend per add-payment-info event from your Meta ads, indicating checkout intent acquisition efficiency. ## Formula **Meta Cost per Add Payment Info** = **Meta Spend** ÷ **Meta Add Payment Info** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising | | [**Meta Add Payment Info**](/reference/metrics/advertising/meta/meta-conversions/meta-add-payment-info) | Count of add-payment-info events attributed to Meta ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your retargeting campaign spent **\$2,400** on Meta ads last week and generated **120** add-payment-info events. | Metric | Value | Calculation | | ------------------------- | ------- | -------------------------------------- | | Meta Spend | \$2,400 | Total spent on Meta | | Add Payment Info | 120 | Payment submissions attributed to Meta | | Cost per Add Payment Info | \$20.00 | \$2,400 ÷ 120 | *** ## How It Works Cost per Add Payment Info divides your total Meta ad spend by the number of add-payment-info events tracked via the Meta Pixel or Conversions API. An add-payment-info event fires when someone enters payment details during checkout after engaging with your ad. Lower cost indicates more efficient acquisition of high-intent users close to completing a purchase. *** ## When to Use | Scenario | Action | | ------------------------------ | -------------------------------------------------------------- | | Evaluating checkout efficiency | Compare cost across campaigns to find best performers | | Optimizing bottom-funnel spend | Lower costs indicate better targeting or creative | | Diagnosing drop-off issues | High cost may signal friction before payment step | | Budget allocation | Shift spend toward campaigns with lower cost per payment event | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [Meta Add Payment Info](/reference/metrics/advertising/meta/meta-conversions/meta-add-payment-info) | The denominator in this calculation | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | The numerator in this calculation | | [Meta CPA](/reference/metrics/advertising/meta/meta-efficiency/meta-cpa) | Similar efficiency metric for purchase conversions | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Cost per Add to Cart: Purchase Intent Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-add-to-cart Track Meta Cost per Add to Cart to measure purchase intent efficiency. Calculate how much you spend to generate each add-to-cart action from Meta ads. Meta Cost per Add to Cart measures the average spend per add-to-cart event from your Meta ads, indicating purchase intent acquisition efficiency. ## Formula **Meta Cost per Add to Cart** = **Meta Spend** ÷ **Meta Add to Carts** ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising | | [**Meta Add to Carts**](/reference/metrics/advertising/meta/meta-conversions/meta-add-to-carts) | Count of add-to-cart events attributed to Meta ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your retargeting campaign spent **\$3,500** on Meta ads last month and generated **1,750 add-to-carts**. | Metric | Value | Calculation | | -------------------- | ------- | --------------------------------- | | Meta Spend | \$3,500 | Total spent on Meta | | Add to Carts | 1,750 | Cart additions attributed to Meta | | Cost per Add to Cart | \$2.00 | \$3,500 ÷ 1,750 | *** ## How It Works Cost per Add to Cart divides your total Meta ad spend by the number of add-to-cart events tracked via the Meta Pixel or Conversions API. An add-to-cart event fires when someone adds a product to their shopping cart after engaging with your ad. Lower cost per add-to-cart indicates more efficient purchase intent generation. *** ## When to Use | Scenario | Action | | -------------------------------- | ----------------------------------------------------------------- | | Evaluating mid-funnel efficiency | Compare cost per ATC across campaigns to find top performers | | Budget allocation | Shift spend toward campaigns with lower cost per add-to-cart | | Benchmarking intent costs | Track cost per ATC trends to identify efficiency changes | | Optimizing prospecting | Use cost per ATC when direct purchases are too few to optimize on | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [Meta Add to Carts](/reference/metrics/advertising/meta/meta-conversions/meta-add-to-carts) | The denominator in this calculation | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | The numerator in this calculation | | [Meta CPA](/reference/metrics/advertising/meta/meta-efficiency/meta-cpa) | Similar efficiency metric for purchase conversions | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Cost per Contact: Contact Acquisition Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-contact Calculate your Meta Ads cost per contact event. Track lead acquisition efficiency for service businesses and optimize your marketing spend effectively. Meta Cost per Contact measures the average spend to generate each contact request from your Meta ads. ## Formula **Meta Cost per Contact** = **Meta Spend** ÷ **Meta Contact Events** ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising | | [**Meta Contact Events**](/reference/metrics/advertising/meta/meta-conversions/meta-contact-events) | Number of contact submissions attributed to Meta ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your home services business spent **\$2,400** on Meta ads and generated **80** contact requests. | Campaign | Spend | Contacts | Cost per Contact | | --------------- | ------- | -------- | ---------------- | | Kitchen Remodel | \$1,200 | 30 | \$40.00 | | Bathroom Reno | \$800 | 35 | \$22.86 | | General Inquiry | \$400 | 15 | \$26.67 | *** ## How It Works Cost per Contact divides your total Meta ad spend by the number of contact events tracked via the Meta Pixel or Conversions API. Contact events typically fire when someone submits a contact form, requests a quote, or initiates a service inquiry. *** ## When to Use | Scenario | Action | | ------------------------------ | ------------------------------------------------- | | Evaluating lead gen efficiency | Compare cost per contact across campaigns | | Budget optimization | Shift spend to campaigns with lower contact costs | | Benchmarking acquisition costs | Track cost per contact trends over time | | Comparing to cost per lead | Analyze contact-to-lead conversion rates | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------- | ---------------------------------------- | | [Meta Contact Events](/reference/metrics/advertising/meta/meta-conversions/meta-contact-events) | The denominator in this calculation | | [Meta Cost per Lead](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-lead) | Similar metric for lead form submissions | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | The numerator in this calculation | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Cost per Customize Product: Customization Event Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-customize-product Track Meta Cost per Customize Product to measure your average spend per product customization. Optimize personalization-driven campaigns on Facebook and Instagram. Meta Cost per Customize Product measures the average spend per product customization event from your Meta ads. ## Formula **Meta Cost per Customize Product** = **Meta Spend** ÷ **Meta Customize Product Events** ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising | | [**Meta Customize Product Events**](/reference/metrics/advertising/meta/meta-conversions/meta-customize-product-events) | Count of customize product events attributed to Meta ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your jewelry brand spent **\$2,400** on Meta ads this month and drove **1,600 product customizations** (engraving, sizing, color selections). | Metric | Value | Calculation | | -------------------------- | ------- | --------------------------------- | | Meta Spend | \$2,400 | Total spent on Meta | | Customize Product Events | 1,600 | Customizations attributed to Meta | | Cost per Customize Product | \$1.50 | \$2,400 ÷ 1,600 | *** ## How It Works Cost per Customize Product divides your total Meta ad spend by the number of customize product events tracked via the Meta Pixel or Conversions API. A customization event fires when someone selects product options like size, color, engraving, or monogramming after engaging with your ad. High customization rates indicate users actively considering purchases, making this a strong mid-funnel signal. *** ## When to Use | Scenario | Action | | ------------------------------------ | ----------------------------------------------------------------- | | Evaluating personalization campaigns | Compare cost per customization across ad sets | | Optimizing product configurators | Identify which customization options drive cheapest engagement | | Forecasting purchase intent | Low cost per customization often predicts strong conversion rates | | Budget allocation | Shift spend toward ads driving affordable customizations | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [Meta Customize Product Events](/reference/metrics/advertising/meta/meta-conversions/meta-customize-product-events) | The denominator in this calculation | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | The numerator in this calculation | | [Meta Cost per Add to Cart](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-add-to-cart) | Similar efficiency metric for the next funnel step | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Cost per Donate: Donation Acquisition Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-donate Track Meta Cost per Donate to measure donation campaign efficiency. Calculate the average ad cost per donation and optimize your nonprofit fundraising ROI. Meta Cost per Donate measures the average advertising cost to generate each donation from your Meta ads. ## Formula **Meta Cost per Donate** = **Meta Spend** ÷ **Meta Donate Events** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total advertising spend on Meta platforms (Facebook, Instagram) | | [**Meta Donate Events**](/reference/metrics/advertising/meta/meta-conversions/meta-donate-events) | Count of donate events attributed to Meta ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your nonprofit's year-end campaign spent **\$1,500** on Meta ads and generated **42 donations**. | Metric | Value | Calculation | | -------------------- | ------- | ---------------------------- | | Meta Spend | \$1,500 | Total spent on Meta | | Meta Donate Events | 42 | Donations attributed to Meta | | Meta Cost per Donate | \$35.71 | \$1,500 ÷ 42 | *** ## How It Works Meta Cost per Donate divides your total Meta ad spend by the number of donate events tracked via the Meta Pixel or Conversions API. A donate event fires when someone completes a donation on your site. Compare this cost against your average donation amount to evaluate fundraising ROI. *** ## When to Use | Scenario | Action | | -------------------------------- | ------------------------------------------------------------- | | Evaluating fundraising campaigns | Compare cost per donate across ad sets to find top performers | | Budget allocation | Shift spend toward campaigns with lower acquisition costs | | ROI analysis | Ensure cost per donate stays below average donation amount | | Seasonal benchmarking | Track trends during giving seasons vs. off-peak periods | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [Meta Donate Events](/reference/metrics/advertising/meta/meta-conversions/meta-donate-events) | The denominator in cost per donate calculation | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | The numerator in cost per donate calculation | | [Meta CPA](/reference/metrics/advertising/meta/meta-efficiency/meta-cpa) | Similar efficiency metric for purchase conversions | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Cost per Find Location: Store Locator Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-find-location Track your cost per find location event from Meta ads. Measure how efficiently your campaigns drive store locator searches and physical location interest. Meta Cost per Find Location measures how much you pay for each find location event triggered by your Meta advertising campaigns. ## Formula **Meta Cost per Find Location** = **Meta Spend** ÷ **Meta Find Location Events** ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total advertising spend on Meta platforms | | [**Meta Find Location Events**](/reference/metrics/advertising/meta/meta-conversions/meta-find-location-events) | Count of find location events attributed to Meta ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your Meta campaigns generated **850 find location events** with **\$4,250 in total spend**. | Campaign | Spend | Find Location Events | Cost per Find Location | | -------------------- | ----------- | -------------------- | ---------------------- | | Store Awareness | \$2,000 | 500 | \$4.00 | | Local Promotions | \$1,500 | 250 | \$6.00 | | Holiday Store Finder | \$750 | 100 | \$7.50 | | **Total** | **\$4,250** | **850** | **\$5.00** | *** ## How It Works This metric divides your total Meta ad spend by the number of find location events recorded. A find location event fires when someone uses your store locator, searches for nearby stores, or interacts with location-finding features after seeing your ad. *** ## When to Use | Scenario | Action | | ------------------------------------ | --------------------------------------------------------- | | Measuring store locator efficiency | Track cost to drive physical location interest | | Comparing local awareness campaigns | Identify which creative drives cheapest location searches | | Multi-location retail planning | Allocate budget to campaigns driving store discovery | | O2O (online-to-offline) optimization | Balance digital spend with physical store traffic goals | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Numerator—total Meta ad cost | | [Meta Find Location Events](/reference/metrics/advertising/meta/meta-conversions/meta-find-location-events) | Denominator—location search events | | [Meta CPC](/reference/metrics/advertising/meta/meta-clicks/meta-cpc) | Compare click efficiency to location efficiency | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Cost per Lead: Lead Generation Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-lead Track your Meta Cost per Lead (CPL) to measure lead generation efficiency. Learn how CPL is calculated and when to optimize your lead campaigns. Meta Cost per Lead measures the average amount you spend to acquire each lead from your Meta ads. ## Formula **Meta Cost per Lead** = **Meta Spend** ÷ **Meta Leads** ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------- | ----------------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount billed by Meta for your advertising | | [**Meta Leads**](/reference/metrics/advertising/meta/meta-conversions/meta-leads) | Count of lead form submissions or lead events from your ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your B2B SaaS campaign spent **\$2,400** on Meta ads last month and generated **80 leads**. | Metric | Value | Calculation | | ------------------ | ------- | ----------------------------------- | | Meta Spend | \$2,400 | Total spent on Meta | | Meta Leads | 80 | Form submissions attributed to Meta | | Meta Cost per Lead | \$30.00 | \$2,400 ÷ 80 | *** ## How It Works Cost per Lead divides your total Meta ad spend by the number of lead events tracked via the Meta Pixel or Conversions API. A lead event fires when someone submits a form, signs up for a newsletter, or completes another lead capture action on your site. Lower CPL indicates more efficient lead generation. *** ## When to Use | Scenario | Action | | ----------------------------- | ------------------------------------------------- | | Evaluating lead gen campaigns | Compare CPL across ad sets to find top performers | | Budget allocation | Shift spend toward campaigns with lower CPL | | Benchmarking efficiency | Track CPL trends week-over-week to spot issues | | Comparing channels | Use CPL alongside other platforms' lead costs | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------- | -------------------------------------------------- | | [Meta Leads](/reference/metrics/advertising/meta/meta-conversions/meta-leads) | The denominator in CPL calculation | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | The numerator in CPL calculation | | [Meta CPA](/reference/metrics/advertising/meta/meta-efficiency/meta-cpa) | Similar efficiency metric for purchase conversions | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Cost per Registration: Registration Acquisition Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-registration Track Meta Cost per Registration to measure sign-up campaign efficiency. Calculate average spend per registration and optimize your Meta ads. Meta Cost per Registration measures the average spend to acquire each registration from your Meta ads. ## Formula **Meta Cost per Registration** = **Meta Spend** ÷ **Meta Completed Registrations** ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta ads | | [**Meta Completed Registrations**](/reference/metrics/advertising/meta/meta-conversions/meta-completed-registrations) | Number of completed sign-ups attributed to Meta | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your SaaS app spent **\$3,200** on Meta ads last month promoting free trial sign-ups and drove **640 registrations**. | Metric | Value | | ------------------------------ | ---------- | | Meta Spend | \$3,200 | | Meta Completed Registrations | 640 | | **Meta Cost per Registration** | **\$5.00** | *** ## How It Works Meta Cost per Registration divides your total ad spend by the number of CompleteRegistration events tracked via the Meta Pixel or Conversions API. A registration event fires when someone finishes your sign-up flow, creates an account, or completes a free trial registration. Lower cost per registration indicates more efficient acquisition. *** ## When to Use | Scenario | Action | | ---------------------------- | ------------------------------------------------------------------------- | | Evaluating sign-up campaigns | Compare cost per registration across ad sets to find efficient performers | | Budget allocation | Shift spend toward campaigns with lower registration costs | | Benchmarking against leads | Compare to Cost per Lead to see funnel conversion efficiency | | Setting acquisition targets | Use as a baseline for customer acquisition cost planning | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [Meta Completed Registrations](/reference/metrics/advertising/meta/meta-conversions/meta-completed-registrations) | Denominator—total registrations used in calculation | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Numerator—total spend divided by registrations | | [Meta Cost per Lead](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-lead) | Similar efficiency metric for earlier-funnel lead events | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Cost per Schedule: Appointment Booking Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-schedule Calculate your Meta Ads cost per schedule event. Track appointment booking efficiency for service businesses and optimize your marketing spend effectively. Meta Cost per Schedule measures the average spend to generate each appointment booking from your Meta ads. ## Formula **Meta Cost per Schedule** = **Meta Spend** ÷ **Meta Schedule Events** ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising | | [**Meta Schedule Events**](/reference/metrics/advertising/meta/meta-conversions/meta-schedule-events) | Number of appointment bookings attributed to Meta ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your wellness spa spent **\$3,600** on Meta ads and generated **120** appointment bookings. | Campaign | Spend | Bookings | Cost per Schedule | | ---------------- | ------- | -------- | ----------------- | | Massage Promo | \$1,800 | 60 | \$30.00 | | Facial Package | \$1,200 | 45 | \$26.67 | | New Client Offer | \$600 | 15 | \$40.00 | *** ## How It Works Cost per Schedule divides your total Meta ad spend by the number of schedule events tracked via the Meta Pixel or Conversions API. Schedule events fire when someone books an appointment, reserves a time slot, or completes a scheduling action on your site. *** ## When to Use | Scenario | Action | | --------------------------------- | ------------------------------------------------- | | Evaluating booking efficiency | Compare cost per schedule across campaigns | | Budget optimization | Shift spend to campaigns with lower booking costs | | Benchmarking service business ads | Track cost per schedule trends over time | | Comparing acquisition channels | Analyze schedule costs vs. contact costs | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------- | ------------------------------------------- | | [Meta Schedule Events](/reference/metrics/advertising/meta/meta-conversions/meta-schedule-events) | The denominator in this calculation | | [Meta Cost per Contact](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-contact) | Similar metric for contact form submissions | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | The numerator in this calculation | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Cost per Search: Search Event Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-search Calculate the cost to generate each on-site search from Meta ads. Optimize your product discovery campaigns for efficient engagement. Meta Cost per Search measures the average advertising spend required to generate one on-site search event through your Meta campaigns. ## Formula **Meta Cost per Search** = **Meta Spend** ÷ **Meta Search Events** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising campaigns | | [**Meta Search Events**](/reference/metrics/advertising/meta/meta-conversions/meta-search-events) | Number of on-site searches attributed to Meta ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your product discovery campaigns spent **\$8,500** and generated **12,847 searches**, resulting in a cost per search of **\$0.66**. | Campaign | Spend | Searches | Cost per Search | | ------------ | ------- | -------- | --------------- | | New Arrivals | \$3,200 | 5,312 | \$0.60 | | Sale Items | \$2,800 | 4,285 | \$0.65 | | Gift Guide | \$2,500 | 3,250 | \$0.77 | *** ## How It Works Cost per Search divides your total Meta advertising spend by the number of on-site search events generated. Lower values indicate campaigns are efficiently driving product discovery behavior at a minimal cost. *** ## When to Use | Scenario | Action | | ------------------------------ | --------------------------------------------------- | | Evaluating discovery campaigns | Assess efficiency of driving product exploration | | Budget optimization | Allocate spend to campaigns with lower search costs | | Audience analysis | Identify segments that engage more actively | | Funnel efficiency | Compare cost per search against cost per purchase | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [Meta Search Events](/reference/metrics/advertising/meta/meta-conversions/meta-search-events) | Denominator showing total searches generated | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Numerator showing total advertising investment | | [Meta CPC](/reference/metrics/advertising/meta/meta-clicks/meta-cpc) | Cost per click for broader engagement comparison | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Cost per Start Trial: Trial Acquisition Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-start-trial Calculate the average cost to acquire a trial start from Meta ads. Measure trial CPA efficiency and optimize subscription acquisition campaigns. The average spend required to generate one free trial start from your Meta ads—a key efficiency metric for subscription-based businesses. ## Formula **Meta Cost per Start Trial** = **Meta Spend** ÷ **Meta Start Trials** ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising campaigns | | [**Meta Start Trials**](/reference/metrics/advertising/meta/meta-conversions/meta-start-trials) | Count of free trial initiations attributed to your Meta ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your SaaS campaign spent **\$3,200** on Meta ads and generated **160 trial starts** this month: | Campaign | Spend | Trials | Cost per Trial | | ----------- | ------- | ------ | -------------- | | Prospecting | \$2,000 | 80 | \$25.00 | | Retargeting | \$800 | 60 | \$13.33 | | Lookalike | \$400 | 20 | \$20.00 | **Cost per Start Trial:** \$3,200 ÷ 160 = **\$20.00** *** ## How It Works Meta attributes trial starts using Pixel or Conversions API data. The cost is calculated by dividing total spend by trial count within your selected date range and attribution window. Multiply this by your trial-to-paid conversion rate to estimate true customer acquisition cost. *** ## When to Use | Scenario | Action | | ---------------------------- | --------------------------------------------------- | | Evaluating trial efficiency | Compare cost per trial across campaigns and ad sets | | Forecasting acquisition cost | Multiply by trial-to-paid rate to estimate full CPA | | Budget allocation | Shift spend toward lower cost-per-trial campaigns | | Testing creative performance | Identify which ads drive the most affordable trials | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [Meta Start Trials](/reference/metrics/advertising/meta/meta-conversions/meta-start-trials) | The denominator—trial volume generated by your ads | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | The numerator—total ad investment | | [Meta Subscriptions](/reference/metrics/advertising/meta/meta-conversions/meta-subscriptions) | Completed subscriptions after trial conversion | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Cost per Submit Application: Application Acquisition Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-submit-application Calculate the cost to acquire each application submission from Meta ads. Optimize your recruitment and lead generation campaigns for efficiency. Meta Cost per Submit Application measures the average advertising spend required to generate one application submission through your Meta campaigns. ## Formula **Meta Cost per Submit Application** = **Meta Spend** ÷ **Meta Submit Application Events** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising campaigns | | [**Meta Submit Application Events**](/reference/metrics/advertising/meta/meta-conversions/meta-submit-application-events) | Number of application submissions attributed to Meta ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your recruitment campaigns spent **\$18,500** and generated **847 applications**, resulting in a cost per submit application of **\$21.84**. | Campaign | Spend | Applications | Cost per Application | | ------------------ | ------- | ------------ | -------------------- | | Software Engineers | \$5,750 | 312 | \$18.43 | | Marketing Roles | \$6,312 | 285 | \$22.15 | | Sales Positions | \$6,438 | 250 | \$25.75 | *** ## How It Works Cost per Submit Application divides your total Meta advertising spend by the number of application submissions received. Lower values indicate more efficient campaigns where you're acquiring applicants at a lower cost. *** ## When to Use | Scenario | Action | | --------------------------- | -------------------------------------------------------------- | | Budget allocation decisions | Shift spend toward campaigns with lower cost per application | | Campaign optimization | Test creative and audience changes to reduce acquisition costs | | Benchmarking performance | Compare efficiency across job categories or time periods | | ROI analysis | Evaluate if application costs justify the value of hires | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | [Meta Submit Application Events](/reference/metrics/advertising/meta/meta-conversions/meta-submit-application-events) | Denominator showing total applications received | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Numerator showing total advertising investment | | [Meta CPA](/reference/metrics/advertising/meta/meta-conversions/meta-cpa) | General cost per action for comparison | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Cost per Subscribe: Subscription Acquisition Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-subscribe Track your Meta Cost per Subscribe to measure how efficiently your ads acquire new subscribers. Optimize acquisition costs for subscription-based businesses. Meta Cost per Subscribe measures the average spend to acquire each new subscriber from your Meta ads. ## Formula **Meta Cost per Subscribe** = **Meta Spend** ÷ **Meta Subscribes** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------- | ------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta ads | | [**Meta Subscribes**](/reference/metrics/advertising/meta/meta-conversions/meta-subscribes) | Number of subscription sign-ups attributed to ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your subscription box company spent **\$5,400** on Meta ads this month and acquired **180 new subscribers**. | Metric | Value | | --------------------------- | ----------- | | Meta Spend | \$5,400 | | Meta Subscribes | 180 | | **Meta Cost per Subscribe** | **\$30.00** | *** ## How It Works Meta Cost per Subscribe divides your total Meta ad spend by the number of subscription events tracked via the Meta Pixel or Conversions API. A subscribe event fires when someone signs up for a subscription after engaging with your ad. This metric is critical for subscription-based businesses to ensure acquisition costs remain below subscriber lifetime value. *** ## When to Use | Scenario | Action | | --------------------------------- | ------------------------------------------------------ | | Evaluating subscriber acquisition | Compare cost per subscribe across campaigns | | Unit economics analysis | Ensure cost stays below subscriber lifetime value | | Budget allocation | Shift spend toward ads with lower subscriber costs | | Creative testing | Identify which messaging drives cheapest subscriptions | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------- | --------------------------------------------------- | | [Meta Subscribes](/reference/metrics/advertising/meta/meta-conversions/meta-subscribes) | Denominator—subscription events used in calculation | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Numerator—total spend divided by subscribes | | [Meta Cost per Lead](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-lead) | Top-of-funnel cost metric for lead generation | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Customize Product: Product Customizations from Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-customize-product-events Track how many customize product events Meta attributes to your ads. Measure purchase consideration when shoppers select size, color, or engraving. Meta Customize Product Events counts how many people customized a product (size, color, engraving) after engaging with your ad—indicating strong purchase consideration. ## Formula **Meta Customize Product Events** = **COUNT** ( customize\_product events ) Each product customization action attributed to your Meta ads is counted once, regardless of product value. | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your Meta campaigns drove **1,892 product customizations** in March across personalization-focused products. | Campaign | Customizations | Spend | Cost/Event | | -------------------- | -------------- | ------- | ---------- | | Jewelry Engraving | 847 | \$1,420 | \$1.68 | | Apparel Sizing | 692 | \$980 | \$1.42 | | Gift Personalization | 353 | \$540 | \$1.53 | *** ## How It Works Meta counts a customize product event when a visitor personalizes a product after interacting with your ad within the attribution window. This includes selecting size, color, adding engraving, monogramming, or any other customization option. The event is captured via the Meta Pixel or Conversions API when the shopper completes the customization step. *** ## When to Use | Scenario | Action | | ------------------------------------ | ------------------------------------------------------------------- | | Measuring personalization engagement | Track how often ads drive customization interactions | | Identifying high-intent traffic | Customizers show strong buying signals—prioritize similar audiences | | Optimizing product pages | Compare customization rates across products to improve UX | | Forecasting conversions | Use as a leading indicator of purchases for personalized items | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | [Meta Cost per Customize Product](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-customize-product) | Efficiency of driving product customizations | | [Meta Add to Carts](/reference/metrics/advertising/meta/meta-conversions/meta-add-to-carts) | Next typical step after customizing a product | | [Meta Purchases](/reference/metrics/advertising/meta/meta-conversions/meta-purchases) | Final conversion event in the purchase funnel | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Donate Events: Donations from Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-donate-events Track donation conversions attributed to your Meta ad campaigns. Measure how effectively your ads drive charitable contributions and fundraising goals. Meta Donate Events counts the total number of donations attributed to your Meta (Facebook/Instagram) advertising campaigns. ## Formula **Meta Donate Events** = **COUNT** ( Donate Events ) ### Formula Components | Metric | Definition | | ----------------- | ------------------------------------------------------------------------------- | | **Donate Events** | Individual donation conversions recorded by the Meta Pixel after ad interaction | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your nonprofit ran a fundraising campaign during the holiday season with a \$5,000 ad spend. | Campaign | Ad Spend | Donate Events | Cost per Donation | | ------------------- | ----------- | ------------- | ----------------- | | Holiday Giving 2024 | \$3,000 | 127 | \$23.62 | | Year-End Appeal | \$2,000 | 89 | \$22.47 | | **Total** | **\$5,000** | **216** | **\$23.15** | *** ## How It Works Meta tracks donate events when users complete a donation action after interacting with your ads. The Donate standard event fires when a user submits a donation form or completes a contribution on your website. Attribution follows your configured Meta attribution window settings. *** ## When to Use | Scenario | Action | | -------------------------------------- | ----------------------------------------------------------------- | | Measuring fundraising campaign success | Compare donate events across campaigns to identify top performers | | Calculating cost per donation | Divide spend by donate events to assess acquisition efficiency | | Optimizing for conversions | Use donate events as an optimization event in Meta Ads Manager | | Reporting donor acquisition | Track total donations attributed to paid advertising efforts | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------- | --------------------------------------------------- | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Ad spend used to calculate cost per donation | | [Meta Conversions](/reference/metrics/advertising/meta/meta-conversions/meta-conversions) | Total attributed conversions including donations | | [Meta ROAS](/reference/metrics/advertising/meta/meta-efficiency/meta-roas) | Overall return on ad spend for all conversion types | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Find Location: Store Locator Uses from Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-find-location-events Track Meta Find Location events to measure store locator uses from Facebook and Instagram ads. Understand offline purchase intent from your social campaigns. Meta Find Location Events counts how many people used your store locator or searched for physical locations after engaging with your Meta ads. ## Formula **Meta Find Location Events** = **COUNT** ( Find Location Events ) ### Formula Components | Metric | Definition | | ------------------------ | --------------------------------------------------------------------------------------------------- | | **Find Location Events** | Each store locator use or location search attributed to your Meta ads within the attribution window | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your Meta campaigns drove **1,284 find location events** in March across three store regions. | Campaign | Find Locations | Spend | Cost/Event | | ------------ | -------------- | ------- | ---------- | | NYC Metro | 582 | \$1,450 | \$2.49 | | LA Region | 423 | \$1,280 | \$3.03 | | Chicago Area | 279 | \$920 | \$3.30 | *** ## How It Works Meta counts a find location event when a visitor uses a store locator or searches for store addresses after interacting with your ad. The event is captured via the Meta Pixel or Conversions API when the shopper triggers your store finder functionality within the attribution window. *** ## When to Use | Scenario | Action | | ----------------------------- | ---------------------------------------------------------------- | | Measuring offline intent | Track how many ad viewers actively seek physical store locations | | Evaluating regional campaigns | Compare find location rates across geographic markets | | Bridging online-to-offline | Correlate find location events with in-store foot traffic | | Optimizing local awareness | Shift budget to campaigns driving store discovery | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | [Meta Cost per Find Location](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-find-location) | Efficiency of driving store searches | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total ad spend used to calculate cost per find location | | [Meta Purchases](/reference/metrics/advertising/meta/meta-conversions/meta-purchases) | Conversions that may follow store visits | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Initiate Checkouts: Bottom-Funnel Conversion Signal Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-initiate-checkouts Track Meta Initiate Checkouts to measure bottom-funnel purchase intent. Monitor how many visitors start checkout after engaging with Meta ads. Meta Initiate Checkouts counts how many shoppers started the checkout process after engaging with your Meta ads. ## Formula **Meta Initiate Checkouts** = **COUNT** ( initiate\_checkout events ) ### Formula Components | Metric | Definition | | ----------------------------- | ------------------------------------------------------------------------------------ | | **initiate\_checkout events** | Checkout initiation events attributed to your Meta ads within the attribution window | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your Meta campaigns drove **1,842 checkout initiations** in April across three ad sets. | Ad Set | Checkouts | Spend | Cost per Checkout | | ----------- | --------- | ------- | ----------------- | | Retargeting | 923 | \$4,615 | \$5.00 | | Lookalike | 612 | \$4,284 | \$7.00 | | Prospecting | 307 | \$3,684 | \$12.00 | *** ## How It Works Meta counts an initiate checkout event when a visitor begins the checkout process after interacting with your ad within the attribution window. This event is captured when shoppers reach the checkout page, whether via the Meta Pixel or Conversions API. *** ## When to Use | Scenario | Action | | ---------------------------- | ----------------------------------------------------------------- | | Measuring purchase intent | Track checkout initiations to gauge high-intent traffic from ads | | Identifying cart abandonment | Compare checkout initiations to purchases to find drop-off points | | Evaluating funnel efficiency | Monitor the ratio of add-to-carts progressing to checkout | | Optimizing for conversions | Use checkout data to inform bid strategy and audience targeting | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | [Meta Cost per Initiate Checkout](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-initiate-checkout) | Cost efficiency for driving checkouts | | [Meta Purchases](/reference/metrics/advertising/meta/meta-conversions/meta-purchases) | Final conversions from these checkout initiations | | [Meta Add to Carts](/reference/metrics/advertising/meta/meta-conversions/meta-add-to-carts) | Mid-funnel step before checkout | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Leads: Lead Form Submissions from Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-leads Track how many leads your Meta ads generate through form submissions or lead events to measure lead generation campaign effectiveness. Meta Leads counts how many people submitted a lead form or completed a lead event from your Meta ads. ## Formula **Meta Leads** = **COUNT** ( Lead Events ) ### Formula Components | Metric | Definition | | --------------- | ------------------------------------------------------------ | | **Lead Events** | Form submissions or lead actions attributed to your Meta ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your Meta lead generation campaigns captured **1,847 leads** in Q1 across three audience segments. | Audience | Leads | Spend | CPL | | ------------------ | ----- | ------- | ------- | | Email Subscribers | 892 | \$4,460 | \$5.00 | | Lookalike Audience | 614 | \$4,912 | \$8.00 | | Interest Targeting | 341 | \$5,115 | \$15.00 | *** ## How It Works Meta counts a lead when someone submits a lead form (native or on your website) or triggers a lead event after interacting with your ad within the attribution window. Lead events are captured via Meta's Lead Ads, the Meta Pixel, or through the Conversions API. *** ## When to Use | Scenario | Action | | --------------------------------------- | --------------------------------------------------------------- | | Measuring lead gen campaign performance | Compare lead counts across campaigns to identify top performers | | Optimizing audience targeting | Shift budget toward audiences generating more qualified leads | | Tracking sales funnel top | Monitor lead volume as the entry point for your sales pipeline | | Calculating lead acquisition cost | Divide spend by leads to evaluate cost efficiency | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------- | ------------------------------------------ | | [Meta Cost per Lead](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-lead) | Cost to acquire each lead | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | The numerator for calculating CPL | | [Meta Purchases](/reference/metrics/advertising/meta/meta-conversions/meta-purchases) | Downstream conversions from lead campaigns | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Messaging Conversations: Chat Initiations from Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-messaging-conversations-started Track Messenger, Instagram DM, and WhatsApp conversations started from your Meta ads. Measure click-to-message campaign performance across platforms. Meta Messaging Conversations Started counts new chat conversations initiated from your Meta ads across Messenger, Instagram Direct, and WhatsApp. ## Formula **Meta Messaging Conversations Started** = **COUNT** ( Messaging Conversation Starts ) ### Formula Components | Metric | Definition | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | **Messaging Conversation Starts** | New conversations initiated when users send a message via Messenger, Instagram DM, or WhatsApp after engaging with your ad | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your e-commerce brand ran click-to-message campaigns across Facebook and Instagram. In March, your ads generated **1,247 new conversations** from product inquiries. | Platform | Conversations | Spend | Cost per Conversation | | ------------ | ------------- | ----------- | --------------------- | | Messenger | 623 | \$1,869 | \$3.00 | | Instagram DM | 456 | \$1,368 | \$3.00 | | WhatsApp | 168 | \$504 | \$3.00 | | **Total** | **1,247** | **\$3,741** | **\$3.00** | *** ## How It Works Meta counts a conversation when someone opens Messenger, Instagram Direct, or WhatsApp and sends their first message after engaging with your ad. The conversation must occur within your attribution window. Only the initial message starting a new thread is counted — follow-up messages in the same conversation are not included. *** ## When to Use | Scenario | Action | | ------------------------------------- | ------------------------------------------------------------------ | | Evaluating click-to-message campaigns | Use as the primary success metric for messaging objectives | | Comparing lead generation channels | Compare against leads and contact events for channel mix decisions | | Staffing customer support | Track conversation volume to allocate support resources | | Measuring acquisition efficiency | Pair with cost per conversation to optimize spend | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total ad spend used to calculate cost per conversation | | [Meta Contact Events](/reference/metrics/advertising/meta/meta-conversions/meta-contact-events) | Alternative metric for broader contact tracking | | [Meta Leads](/reference/metrics/advertising/meta/meta-conversions/meta-leads) | Form-based lead generation alternative to messaging | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta NC Purchases: New Customer Attributed Conversions Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-new-customer-purchases Track first-time buyer purchases attributed to your Meta ads. Measure acquisition performance with new customer conversion counts from Facebook and Instagram campaigns. Meta NC Purchases counts the number of purchases from first-time buyers that Meta attributes to your ads. ## Formula **Meta NC Purchases** = **COUNT** ( purchase events ) **WHERE** customer\_type = new ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | | [**purchase events**](/reference/metrics/advertising/meta/meta-conversions/meta-purchases) | Total purchase events attributed to your Meta ads | | [**customer\_type = new**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to purchases from first-time buyers with no prior purchase history | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your prospecting campaign drove **847 new customer purchases** in Q1. | Campaign | NC Purchases | Total Purchases | NC Rate | | ------------------ | ------------ | --------------- | ------- | | Lookalike - Top 1% | 412 | 523 | 79% | | Interest - Fitness | 289 | 456 | 63% | | Broad - Advantage+ | 146 | 892 | 16% | *** ## How It Works Meta identifies new customers using customer list data you provide through the Conversions API or pixel. When a purchase event fires, Meta checks if the buyer's email or phone matches your existing customer list. Purchases from unmatched users count as new customer conversions. This requires configuring your new customer signal in Meta. *** ## When to Use | Scenario | Action | | ------------------------------------- | ---------------------------------------------------------------------- | | Prospecting campaigns underperforming | Compare NC purchases across audiences to find best acquisition sources | | High ROAS but low growth | Check if most purchases come from existing customers | | Budget allocation decisions | Shift spend toward campaigns with higher NC purchase rates | | Evaluating Advantage+ Shopping | Monitor NC vs returning customer mix in automated campaigns | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | [Meta Purchases](/reference/metrics/advertising/meta/meta-conversions/meta-purchases) | Total purchases including new and returning customers | | [Meta NC Purchases Value](/reference/metrics/advertising/meta/meta-conversions/meta-new-customer-purchases-value) | Revenue from first-time buyers | | [Meta NC CPA](/reference/metrics/advertising/meta/meta-efficiency/meta-new-customer-cpa) | Cost to acquire each new customer | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Purchases: Attributed Conversion Count Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-purchases Track how many completed purchases Meta attributes to your ads via pixel or Conversions API to measure campaign effectiveness. Meta Purchases counts how many completed purchases Meta attributes to your ads, based on pixel or Conversions API data. ## Formula **Meta Purchases** = **COUNT** ( purchase events ) Each purchase event attributed to your Meta ads is counted once, regardless of order value. ### Formula Components | Metric | Definition | | ------------------- | -------------------------------------------------------------------- | | **purchase events** | Purchase conversion events reported by Meta Pixel or Conversions API | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your Meta campaigns drove **847 purchases** in March across three ad sets. | Ad Set | Purchases | Spend | CPA | | ----------- | --------- | ------- | ------- | | Retargeting | 412 | \$2,060 | \$5.00 | | Lookalike | 298 | \$2,682 | \$9.00 | | Prospecting | 137 | \$2,740 | \$20.00 | *** ## How It Works Meta counts a purchase when a visitor completes checkout after interacting with your ad within the attribution window. The purchase event is captured via the Meta Pixel on your site or sent through the Conversions API from your server. *** ## When to Use | Scenario | Action | | ------------------------------- | ------------------------------------------------------------------- | | Evaluating campaign performance | Compare purchase counts across campaigns to identify top performers | | Optimizing ad spend allocation | Shift budget toward ad sets generating more purchases | | Assessing funnel health | Track purchase volume alongside add-to-cart and checkout metrics | | Benchmarking seasonal trends | Compare monthly purchase counts to identify growth patterns | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------- | ---------------------------------- | | [Meta Purchases Value](/reference/metrics/advertising/meta/meta-conversions/meta-purchases-value) | Total revenue from these purchases | | [Meta CPA](/reference/metrics/advertising/meta/meta-efficiency/meta-cpa) | Cost per purchase conversion | | [Meta ROAS](/reference/metrics/advertising/meta/meta-efficiency/meta-roas) | Return on ad spend from purchases | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Purchases Value: Attributed Revenue Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-purchases-value Track total revenue Meta attributes to your ads. Calculate ROAS, evaluate campaign profitability, and optimize ad spend allocation. Meta Purchases Value is the total revenue from purchases that Meta attributes to your ads. ## Formula **Meta Purchases Value** = **SUM** ( purchase values ) Each purchase order total attributed to your Meta ads is summed across the selected period. ### Formula Components | Metric | Definition | | ------------------- | --------------------------------------------------------------------------- | | **purchase values** | Order totals from purchase events reported by Meta Pixel or Conversions API | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your Meta campaigns generated **\$42,800** in attributed revenue in March across three campaign types. | Campaign | Revenue | Purchases | Avg Order | | ----------- | -------- | --------- | --------- | | Retargeting | \$18,540 | 412 | \$45.00 | | Lookalike | \$16,072 | 298 | \$53.93 | | Prospecting | \$8,188 | 137 | \$59.77 | *** ## How It Works Meta captures the order total each time a purchase event fires after someone interacts with your ad. Revenue is attributed based on Meta's attribution window (default 7-day click, 1-day view). This value forms the numerator when calculating ROAS. *** ## When to Use | Scenario | Action | | ------------------------ | ----------------------------------------------------- | | Measuring campaign ROI | Divide by spend to calculate ROAS | | Budget allocation | Shift spend toward campaigns driving the most revenue | | Evaluating profitability | Compare revenue against ad spend and product margins | | Seasonal planning | Track revenue trends to forecast peak period budgets | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------- | -------------------------------------------------- | | [Meta Purchases](/reference/metrics/advertising/meta/meta-conversions/meta-purchases) | Count of purchases (this metric sums their values) | | [Meta ROAS](/reference/metrics/advertising/meta/meta-efficiency/meta-roas) | Purchases Value ÷ Ad Spend | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | The denominator for ROAS calculations | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Schedule Events: Appointment Bookings from Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-schedule-events Track how many schedule events your Meta ads generate. Measure appointment bookings and service scheduling for service-based businesses. Meta Schedule Events counts how many people booked appointments or scheduled services after engaging with your Meta ads. ## Formula **Meta Schedule Events** = **COUNT** ( Schedule Events ) | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your med spa generated **186 appointment bookings** in February across three service lines. | Service | Bookings | Spend | Cost per Booking | | ------------------- | -------- | ------- | ---------------- | | Botox Consultations | 82 | \$1,640 | \$20.00 | | Facial Treatments | 64 | \$1,280 | \$20.00 | | Laser Services | 40 | \$1,080 | \$27.00 | *** ## How It Works Meta counts a schedule event when someone books an appointment or schedules a service after interacting with your ad within the attribution window. Schedule events are captured via the Meta Pixel or Conversions API when you fire the Schedule standard event on your booking confirmation page. *** ## When to Use | Scenario | Action | | ------------------------------- | --------------------------------------------------- | | Measuring service bookings | Track schedules as your primary conversion metric | | Evaluating campaign performance | Compare booking volume across ad sets and creatives | | Optimizing for appointments | Use schedule events as your conversion objective | | Calculating booking costs | Pair with cost per schedule to measure efficiency | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------- | ------------------------------------- | | [Meta Cost per Schedule](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-schedule) | Cost to acquire each booking | | [Meta Contact Events](/reference/metrics/advertising/meta/meta-conversions/meta-contact-events) | Alternative lead metric for inquiries | | [Meta Leads](/reference/metrics/advertising/meta/meta-conversions/meta-leads) | Form submission lead metric | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Search Events: On-Site Searches from Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-search-events Track on-site search events driven by Meta ads. Measure how your Facebook and Instagram campaigns generate product discovery and search engagement. Meta Search Events counts the total number of on-site search actions attributed to your Meta advertising campaigns. ## Formula **Meta Search Events** = **COUNT** ( search events ) ### Formula Components | Metric | Definition | | ------------- | --------------------------------------------------------------- | | search events | On-site search actions tracked by Meta Pixel or Conversions API | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your product discovery campaign generated **12,847 search events** last month as users explored your catalog after engaging with Meta ads. | Campaign | Search Events | Searches per Session | | ------------ | ------------- | -------------------- | | New Arrivals | 5,312 | 2.4 | | Sale Items | 4,285 | 1.8 | | Gift Guide | 3,250 | 2.1 | *** ## How It Works Meta tracks search events when users perform searches on your website after clicking or viewing your ads. These events are captured through Meta Pixel or Conversions API and indicate high purchase intent as users actively look for specific products. *** ## When to Use | Scenario | Action | | ------------------------------------------ | ---------------------------------------------------- | | Measuring discovery campaign effectiveness | Track how well ads drive product exploration | | Identifying high-intent audiences | Analyze which ad sets generate the most searches | | Optimizing for bottom-funnel behavior | Use search events as a signal for purchase intent | | Improving site experience | Understand what users search for after ad engagement | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | [Meta Cost per Search](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-search) | Efficiency metric showing cost to generate each search | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total ad spend used to calculate search costs | | [Meta Add to Cart Events](/reference/metrics/advertising/meta/meta-conversions/meta-add-to-cart-events) | Next funnel step after product discovery | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Start Trials: Free Trial Sign-ups from Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-start-trials Track free trial sign-ups from Meta ads. Measure subscription intent and optimize campaigns for trial acquisition performance. Counts how many people started a free trial after engaging with your Meta ad—an early indicator of subscription conversion potential. ## Formula **Meta Start Trials** = **COUNT** ( trial\_start events ) ### Formula Components | Metric | Definition | | ----------------------- | ------------------------------------------------------------------------------------ | | **trial\_start events** | Each free trial initiation attributed to your Meta ads within the attribution window | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your SaaS company ran a prospecting campaign in March, generating **847 trial starts** across ad sets. | Ad Set | Trials Started | Cost per Trial | | --------------------------- | -------------- | -------------- | | Lookalike - High Value | 312 | \$8.42 | | Interest - Small Business | 285 | \$11.67 | | Retargeting - Site Visitors | 250 | \$5.23 | *** ## How It Works Meta fires a `StartTrial` event when a user initiates a free trial on your site or app. This event is captured via the Meta Pixel or Conversions API and attributed to the ad that influenced the conversion within your attribution window. *** ## When to Use | Scenario | Action | | ------------------------- | ------------------------------------------------------------------ | | Subscription model launch | Track trial volume as your primary top-of-funnel metric | | Campaign optimization | Compare trial rates across audiences to find high-intent segments | | Budget allocation | Shift spend toward ad sets with lower cost per trial | | Funnel analysis | Pair with subscriptions to calculate trial-to-paid conversion rate | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | [Meta Cost per Start Trial](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-start-trial) | Average spend required to generate one trial start | | [Meta Subscriptions](/reference/metrics/advertising/meta/meta-conversions/meta-subscriptions) | Completed subscriptions—tracks trial-to-paid conversion | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total ad spend used to calculate cost per trial | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Submit Application: Application Submissions from Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-submit-application-events Track application submissions driven by Meta ads. Measure how effectively your Facebook and Instagram campaigns generate job, membership, or form submissions. Meta Submit Application Events counts the total number of application submissions attributed to your Meta advertising campaigns. ## Formula **Meta Submit Application Events** = **COUNT** ( submit\_application events ) ### Formula Components | Metric | Definition | | -------------------------- | --------------------------------------------------------------------- | | submit\_application events | Application form completions tracked by Meta Pixel or Conversions API | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your job recruitment campaign generated **847 application submissions** last month across Facebook and Instagram placements. | Campaign | Submit Applications | Cost per Application | | ------------------ | ------------------- | -------------------- | | Software Engineers | 312 | \$18.42 | | Marketing Roles | 285 | \$22.15 | | Sales Positions | 250 | \$25.80 | *** ## How It Works Meta tracks submit\_application events when users complete application forms on your website after clicking or viewing your ads. These events are captured through Meta Pixel or Conversions API and attributed based on your configured attribution window. *** ## When to Use | Scenario | Action | | -------------------------------------------- | ------------------------------------------------------------ | | Measuring recruitment campaign effectiveness | Compare application volume across job categories and ad sets | | Optimizing for qualified applicants | Analyze which audiences drive the most submissions | | Calculating application acquisition costs | Combine with spend data to find cost per submission | | Comparing application channels | Benchmark Meta against other recruitment sources | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | [Meta Cost per Submit Application](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-submit-application) | Efficiency metric showing cost to acquire each application | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total ad spend used to calculate application costs | | [Meta Conversions](/reference/metrics/advertising/meta/meta-conversions/meta-conversions) | Total conversions including applications | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Subscribes: Subscription Sign-ups from Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-subscribes Track subscription sign-ups attributed to your Meta ads. Measure how effectively your campaigns drive recurring revenue for SaaS and subscription businesses. Meta Subscribes counts how many subscription sign-ups your Meta ads generated during the selected period. ## Formula **Meta Subscribes** = **COUNT** ( Subscribe Events ) Each subscription event triggered by Meta ad engagement is counted once. | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your SaaS product acquired **127 new subscribers** from Meta campaigns this quarter. | Campaign | Subscribes | Cost per Subscribe | | ------------------ | ---------- | ------------------ | | Retargeting | 52 | \$18.50 | | Lookalike Audience | 45 | \$24.20 | | Interest Targeting | 30 | \$31.80 | *** ## How It Works Meta tracks subscription events when users complete a subscribe action after engaging with your ad. This requires the Meta Pixel or Conversions API to fire a Subscribe event. Attribution follows your configured window (typically 7-day click, 1-day view). *** ## When to Use | Scenario | Action | | --------------------------------- | ------------------------------------------------------------ | | Evaluating subscription campaigns | Compare subscribe volume across ad sets | | Calculating acquisition cost | Divide Meta Spend by Meta Subscribes for cost per subscriber | | Optimizing for recurring revenue | Identify which audiences convert to subscribers | | Forecasting LTV | Combine with subscription value for revenue projections | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | [Meta Cost per Subscribe](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-subscribe) | Meta Spend ÷ Meta Subscribes | | [Meta Purchases](/reference/metrics/advertising/meta/meta-conversions/meta-purchases) | One-time purchases vs recurring subscriptions | | [Meta Start Trials](/reference/metrics/advertising/meta/meta-conversions/meta-start-trials) | Trial conversions that may become subscribers | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Subscriptions: Subscription Sign-ups from Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-subscriptions Track how many subscription sign-ups your Meta ads generate to measure recurring revenue acquisition from paid social campaigns. Meta Subscriptions counts how many people signed up for a subscription after engaging with your Meta ad. ## Formula **Meta Subscriptions** = **COUNT** ( Subscription Events ) Each subscription sign-up attributed to your Meta ads is counted once. | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your subscription box brand drove **428 new subscribers** in March across three campaign objectives. | Campaign | Subscriptions | Spend | Cost/Sub | | ----------- | ------------- | ------- | -------- | | Prospecting | 186 | \$5,580 | \$30.00 | | Retargeting | 157 | \$3,140 | \$20.00 | | Lookalike | 85 | \$2,975 | \$35.00 | *** ## How It Works Meta counts a subscription when someone completes a subscription sign-up event after interacting with your ad within the attribution window. Subscription events are captured via the Meta Pixel or through the Conversions API when you fire the Subscribe standard event. *** ## When to Use | Scenario | Action | | -------------------------------------- | ------------------------------------------------------------------- | | Measuring subscription campaign ROI | Compare subscription volume against spend to evaluate profitability | | Optimizing for recurring revenue | Prioritize campaigns driving the most subscription sign-ups | | Tracking subscriber acquisition funnel | Monitor subscription conversions as a key business outcome | | Comparing acquisition channels | Benchmark Meta subscription performance against other paid channels | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | [Meta Cost per Subscribe](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-subscribe) | Cost to acquire each subscriber | | [Meta Start Trials](/reference/metrics/advertising/meta/meta-conversions/meta-start-trials) | Trial initiations that may convert to subscriptions | | [Meta Purchases](/reference/metrics/advertising/meta/meta-conversions/meta-purchases) | One-time purchase conversions for comparison | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta View Contents: Product Page Views from Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-conversions/meta-view-contents Track how many product page views Meta attributes to your ads. Measure top-of-funnel engagement to optimize campaigns for product discovery. Meta View Contents counts how many times visitors viewed a product detail page after clicking your ad—a top-of-funnel engagement signal. ## Formula **Meta View Contents** = **COUNT** ( view\_content events ) Each product or content page view attributed to your Meta ads is counted once per view event. | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your Meta campaigns drove **12,340 product page views** in March across three audience segments. | Audience | View Contents | Spend | Cost/View | | ----------- | ------------- | ------- | --------- | | Retargeting | 5,420 | \$890 | \$0.16 | | Lookalike | 4,180 | \$1,450 | \$0.35 | | Prospecting | 2,740 | \$1,980 | \$0.72 | *** ## How It Works Meta counts a view content event when a visitor lands on a product detail page after interacting with your ad within the attribution window. The event is captured via the Meta Pixel or Conversions API when the shopper views a specific product page on your site. *** ## When to Use | Scenario | Action | | --------------------------------------- | ----------------------------------------------------------------- | | Measuring top-of-funnel traffic quality | Compare view content volumes across campaigns to assess interest | | Identifying high-intent audiences | High view contents signal that ads are driving product discovery | | Diagnosing funnel entry points | Compare view contents vs add-to-carts to find engagement drop-off | | Optimizing for awareness campaigns | Shift budget to campaigns with strong view content rates | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | [Meta Cost per View Content](/reference/metrics/advertising/meta/meta-conversions/meta-cost-per-view-content) | Efficiency of driving product page views | | [Meta Add to Carts](/reference/metrics/advertising/meta/meta-conversions/meta-add-to-carts) | Next step in the purchase funnel | | [Meta Purchases](/reference/metrics/advertising/meta/meta-conversions/meta-purchases) | Final conversion from product views | [See all Meta Conversions metrics →](/reference/metrics/advertising/meta/meta-conversions) # Meta Efficiency Metrics Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-efficiency/index Track Meta ad efficiency in Upstack. Monitor ROAS, CPA, CPP, and cost-per-action metrics to optimize your Facebook and Instagram campaign ROI. Efficiency metrics evaluate the return you get from your Meta advertising spend. Track ROAS, CPA, and other cost-per-outcome metrics to optimize campaign profitability. **Data Source:** Meta Marketing API\ **Metrics:** 7 ## Metrics in This Group | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | ------------------------------------------- | | [Meta ROAS](/reference/metrics/advertising/meta/meta-efficiency/meta-roas) | Return on ad spend | Measure overall campaign profitability | | [Meta CPA](/reference/metrics/advertising/meta/meta-efficiency/meta-cpa) | Cost per purchase | Evaluate acquisition cost efficiency | | [Meta Cost per Purchase](/reference/metrics/advertising/meta/meta-efficiency/meta-cost-per-purchase) | Spend ÷ Purchases | Calculate precise purchase acquisition cost | | [Meta CPP](/reference/metrics/advertising/meta/meta-efficiency/meta-cpp) | Cost per 1,000 people reached | Measure audience acquisition efficiency | | [Meta New Customer ROAS](/reference/metrics/advertising/meta/meta-efficiency/meta-new-customer-roas) | ROAS from new customers | Measure acquisition campaign profitability | | [Meta New Customer CPA](/reference/metrics/advertising/meta/meta-efficiency/meta-new-customer-cpa) | Cost to acquire new customers | Track first-time buyer acquisition cost | | [Meta New Customer Cost per Purchase](/reference/metrics/advertising/meta/meta-efficiency/meta-new-customer-cost-per-purchase) | Spend ÷ New customer purchases | Evaluate new customer efficiency | ## How These Metrics Relate * **ROAS** = Revenue ÷ Spend — measures overall profitability * **CPA** = Spend ÷ Purchases — measures acquisition cost * **New Customer metrics** filter to first-time buyers only A ROAS above 1x means revenue exceeds spend. Target CPA depends on your margins and customer lifetime value. ## Choosing the Right Metric * **Profitability focus**: Use ROAS to ensure revenue exceeds spend * **Acquisition campaigns**: Use CPA/CPP to measure cost per outcome * **New customer acquisition**: Use New Customer metrics to isolate first-time buyer efficiency * **Budget allocation**: Compare ROAS across campaigns to optimize spend distribution * **LTV analysis**: Compare CPA against customer lifetime value for sustainable growth # Meta Cost per Purchase: Track Ad Acquisition Cost Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-efficiency/meta-cost-per-purchase Track your Meta Cost per Purchase to measure advertising efficiency. See how much you spend on average for each purchase attributed to your Meta campaigns. Meta Cost per Purchase measures how much you spend on average for each purchase attributed to your Meta ads. ## Formula **Meta Cost per Purchase** = **Meta Spend** ÷ **Meta Purchases** ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------- | ------------------------------------------ | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising | | [**Meta Purchases**](/reference/metrics/advertising/meta/meta-conversions/meta-purchases) | Number of purchases attributed to Meta ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your skincare brand spent **\$2,450** on Meta ads in March and drove **98 purchases**. | Metric | Value | Insight | | --------------------- | ----------- | -------------------------- | | Ad Spend | \$2,450 | Total Meta budget consumed | | Purchases | 98 | Orders attributed to Meta | | **Cost per Purchase** | **\$25.00** | Average acquisition cost | *** ## How It Works Meta tracks purchases using pixel events and Conversions API data. When a user who saw or clicked your ad completes a purchase within the attribution window, Meta credits that sale to the campaign. This metric divides your total spend by those attributed purchases. *** ## When to Use | Scenario | Action | | ---------------------------- | ------------------------------------------------- | | Compare campaign efficiency | Lower cost per purchase = more efficient spend | | Set target acquisition costs | Benchmark against your average order value | | Identify underperforming ads | Pause ads with cost per purchase above target | | Scale profitable campaigns | Increase budget on ads with low acquisition costs | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------- | ----------------------------------------- | | [Meta Purchases](/reference/metrics/advertising/meta/meta-conversions/meta-purchases) | The denominator in this calculation | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | The numerator in this calculation | | [Meta CPA](/reference/metrics/advertising/meta/meta-efficiency/meta-cpa) | Alternative name for cost per acquisition | # Meta CPA: Cost Per Acquisition from Meta Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-efficiency/meta-cpa Track your Meta CPA to measure how much you spend per purchase. Lower CPA means more efficient ad spend and better campaign profitability. Meta CPA measures the average cost to generate one purchase conversion from your Meta advertising campaigns. ## Formula **Meta CPA** = **Meta Spend** ÷ **Meta Purchases** ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------- | ------------------------------------------ | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising | | [**Meta Purchases**](/reference/metrics/advertising/meta/meta-conversions/meta-purchases) | Number of purchases attributed to Meta ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your skincare brand spent **\$4,500 on Meta ads** last month and generated **150 purchases**. | Campaign | Spend | Purchases | CPA | | ----------- | ----------- | --------- | ----------- | | Retargeting | \$1,200 | 80 | \$15.00 | | Prospecting | \$2,100 | 50 | \$42.00 | | Lookalike | \$1,200 | 20 | \$60.00 | | **Total** | **\$4,500** | **150** | **\$30.00** | *** ## How It Works Meta calculates CPA by dividing total ad spend by purchase conversions recorded through the Meta Pixel or Conversions API. The attribution window you configure in Meta Ads Manager determines which purchases count toward each campaign. Lower CPA indicates more efficient acquisition—you're spending less to convert each customer. *** ## When to Use | Scenario | Action | | ---------------------- | --------------------------------------------- | | CPA exceeds target | Narrow audience targeting or improve creative | | CPA varies by campaign | Reallocate budget to lowest-CPA campaigns | | CPA rising over time | Test new audiences or refresh ad creative | | Comparing channels | Benchmark against Google and TikTok CPA | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | ------------------------------------------- | | [Meta Purchases](/reference/metrics/advertising/meta/meta-conversions/meta-purchases) | Conversion count used in denominator | | [Meta ROAS](/reference/metrics/advertising/meta/meta-efficiency/meta-roas) | Revenue efficiency vs cost efficiency | | [Meta New Customer CPA](/reference/metrics/advertising/meta/meta-efficiency/meta-new-customer-cpa) | Acquisition cost for first-time buyers only | # Meta CPP: Cost to Reach 1,000 Unique People Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-efficiency/meta-cpp Track Meta CPP to measure how much you pay to reach 1,000 unique people. Evaluate audience targeting efficiency and compare reach costs across campaigns. Meta CPP (Cost Per 1,000 People) measures how much you pay to reach 1,000 unique individuals with your Meta ads. ## Formula **Meta CPP** = ( **Meta Spend** ÷ **Meta Reach** ) × 1,000 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------ | ---------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising | | [**Meta Reach**](/reference/metrics/advertising/meta/meta-audience/meta-reach) | Number of unique people who saw your ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your brand awareness campaign spent **\$2,400** and reached **120,000 unique people** in February. | Campaign | Spend | Reach | CPP | | --------------- | ------- | ------- | ------- | | Brand Awareness | \$2,400 | 120,000 | \$20.00 | | Prospecting | \$1,800 | 45,000 | \$40.00 | | Lookalike | \$900 | 30,000 | \$30.00 | *** ## How It Works Meta calculates CPP by dividing your total ad spend by the number of unique people reached, then multiplying by 1,000. Unlike CPM (cost per thousand impressions), CPP counts each person only once regardless of how many times they saw your ad. A lower CPP indicates more efficient audience targeting and reach. *** ## When to Use | Scenario | Action | | ----------------------------- | --------------------------------------------------------------------- | | Comparing audience efficiency | Use CPP to identify which audiences cost less to reach | | Brand awareness campaigns | Prioritize CPP over CPM when unique reach matters more than frequency | | Audience saturation | Rising CPP signals shrinking available audience—expand targeting | | Budget allocation | Shift spend toward campaigns with lower CPP for broader reach | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------- | ------------------------------------------------ | | [Meta Reach](/reference/metrics/advertising/meta/meta-audience/meta-reach) | Unique people reached—the denominator in CPP | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total ad spend—the numerator in CPP | | [Meta CPM](/reference/metrics/advertising/meta/meta-audience/meta-cpm) | Cost per 1,000 impressions (counts repeat views) | # Meta New Customer Cost per Purchase: Acquisition Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-efficiency/meta-new-customer-cost-per-purchase Track Meta new customer cost per purchase to measure acquisition efficiency. Calculate average ad spend per first-time buyer conversion from Meta campaigns. Meta New Customer Cost per Purchase measures how much you spend on Meta ads for each first-time buyer conversion. ## Formula **Meta NC Cost per Purchase** = **Meta Spend** ÷ **Meta New Customer Purchases** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising | | [**Meta New Customer Purchases**](/reference/metrics/advertising/meta/meta-conversions/meta-new-customer-purchases) | Number of purchases by first-time buyers attributed to Meta ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your store ran a prospecting campaign in March with **\$12,400 in Meta ad spend** that generated **124 new customer purchases**. | Metric | Value | Calculation | | ---------------------- | ------------ | ----------------- | | Ad Spend | \$12,400 | Total Meta spend | | New Customer Purchases | 124 | First-time buyers | | **NC Cost/Purchase** | **\$100.00** | \$12,400 ÷ 124 | *** ## How It Works This metric isolates your acquisition efficiency by focusing exclusively on first-time buyers. Meta identifies new customers using the customer information signals you send via the Conversions API. Unlike overall CPA, this filters out repeat purchasers to show true acquisition costs. *** ## When to Use | Scenario | Action | | ------------------------------------- | ----------------------------------------------------------- | | Evaluating prospecting campaigns | Compare NC cost across ad sets targeting cold audiences | | Setting acquisition budgets | Use as baseline to forecast spend needed for growth targets | | Comparing to customer LTV | Ensure acquisition cost stays below customer lifetime value | | Optimizing creative for new customers | Test which ads drive lowest NC acquisition costs | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [Meta New Customer Purchases](/reference/metrics/advertising/meta/meta-conversions/meta-new-customer-purchases) | The denominator in this calculation | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | The numerator in this calculation | | [Meta New Customer CPA](/reference/metrics/advertising/meta/meta-efficiency/meta-new-customer-cpa) | Equivalent metric using standard CPA terminology | # Meta New Customer CPA: Measure First-Time Buyer Acquisition Cost Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-efficiency/meta-new-customer-cpa Track Meta New Customer CPA to measure your cost per first-time buyer. Optimize acquisition spend and evaluate prospecting campaign efficiency. Meta New Customer CPA measures the average cost to acquire one first-time buyer through Meta advertising. ## Formula **Meta NC CPA** = **Meta Spend** ÷ **Meta New Customer Purchases** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising | | [**Meta New Customer Purchases**](/reference/metrics/advertising/meta/meta-conversions/meta-new-customer-purchases) | Number of purchases by first-time buyers attributed to Meta ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your DTC brand spent **\$8,000 on Meta ads** in March and acquired **100 new customers**. | Campaign | Spend | New Customers | NC CPA | | ---------------- | ----------- | ------------- | ----------- | | Prospecting Cold | \$4,500 | 45 | \$100.00 | | Lookalike 1% | \$2,500 | 40 | \$62.50 | | Interest-Based | \$1,000 | 15 | \$66.67 | | **Total** | **\$8,000** | **100** | **\$80.00** | *** ## How It Works Meta calculates New Customer CPA by dividing ad spend by purchases from first-time buyers. This requires configuring the new customer signal through Meta's Conversions API or Pixel. The metric isolates acquisition efficiency from repeat purchases, giving you a true cost of customer growth separate from retention-driven revenue. *** ## When to Use | Scenario | Action | | --------------------------- | ---------------------------------------------------------- | | NC CPA exceeds customer LTV | Reduce prospecting spend or tighten targeting | | NC CPA varies by audience | Shift budget toward lowest-cost acquisition segments | | Comparing to blended CPA | Identify how much more new customers cost vs all purchases | | Setting acquisition budgets | Use NC CPA to forecast spend needed for growth targets | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | [Meta New Customer Purchases](/reference/metrics/advertising/meta/meta-conversions/meta-new-customer-purchases) | Conversion count used in denominator | | [Meta CPA](/reference/metrics/advertising/meta/meta-efficiency/meta-cpa) | Blended acquisition cost (all customers) | | [Meta New Customer ROAS](/reference/metrics/advertising/meta/meta-efficiency/meta-new-customer-roas) | Revenue efficiency for first-time buyers | # Meta New Customer ROAS: Measure Acquisition Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-efficiency/meta-new-customer-roas Meta New Customer ROAS measures revenue from first-time buyers per dollar spent on ads. Evaluate how effectively campaigns convert spend into new customers. Meta New Customer ROAS measures the return on ad spend specifically from first-time buyers acquired through your Meta campaigns. ## Formula **Meta NC ROAS** = **Meta New Customer Purchases Value** ÷ **Meta Spend** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | [**Meta New Customer Purchases Value**](/reference/metrics/advertising/meta/meta-conversions/meta-new-customer-purchases-value) | Revenue from purchases by first-time buyers attributed to Meta ads | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising | | Metadata | | | --------------- | --------------------------------- | | **Type** | Ratio (multiplier) | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your Black Friday campaign spent **\$5,000** on Meta ads and generated **\$12,500** in revenue from first-time buyers. | Metric | Value | Calculation | | -------------------- | -------- | ------------------------------ | | New Customer Revenue | \$12,500 | Revenue from first-time buyers | | Ad Spend | \$5,000 | Total Meta spend | | **NC ROAS** | **2.5x** | \$12,500 ÷ \$5,000 | *** ## How It Works This metric isolates revenue from customers making their first purchase, excluding repeat buyers. Meta identifies new customers using your customer list uploads or the new customer signal configured in your pixel. A NC ROAS of 2.5x means you earn \$2.50 from new buyers for every \$1 spent on ads. *** ## When to Use | Scenario | Action | | ---------------------------------- | ----------------------------------------------------------------- | | Evaluating prospecting campaigns | Compare NC ROAS to overall ROAS to gauge acquisition efficiency | | Budget allocation decisions | Shift spend toward campaigns with higher NC ROAS | | Customer acquisition cost analysis | Use alongside NC CPA for a complete acquisition picture | | Retention vs. acquisition balance | Low NC ROAS with high overall ROAS suggests retargeting dominance | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | [Meta ROAS](/reference/metrics/advertising/meta/meta-efficiency/meta-roas) | Overall return including repeat buyers | | [Meta New Customer Purchases Value](/reference/metrics/advertising/meta/meta-conversions/meta-new-customer-purchases-value) | The revenue component of NC ROAS | | [Meta New Customer CPA](/reference/metrics/advertising/meta/meta-efficiency/meta-new-customer-cpa) | Cost-based view of acquisition efficiency | # Meta ROAS: Measure Your Meta Ad Return on Investment Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-efficiency/meta-roas Track Meta ROAS to measure revenue generated per dollar spent on Meta ads. Calculate return on ad spend and optimize campaign profitability. Meta ROAS measures the revenue Meta attributes to your ads for every dollar spent. ## Formula **Meta ROAS** = **Meta Purchases Value** ÷ **Meta Spend** ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | [**Meta Purchases Value**](/reference/metrics/advertising/meta/meta-conversions/meta-purchases-value) | Total revenue from purchases attributed to Meta ads | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising | | Metadata | | | --------------- | --------------------------------- | | **Type** | Ratio (multiplier) | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your store spent **\$5,000** on Meta ads in January and drove \$18,500 in attributed revenue. | Campaign | Spend | Revenue | ROAS | | ----------- | ------- | ------- | ---- | | Prospecting | \$3,000 | \$9,000 | 3.0x | | Retargeting | \$1,500 | \$7,500 | 5.0x | | Lookalike | \$500 | \$2,000 | 4.0x | *** ## How It Works Meta calculates ROAS by dividing the total purchase value it attributes to your ads by your ad spend. A ROAS of 3x means Meta credits \$3 in revenue for every \$1 spent. This metric uses Meta's attribution model, which may differ from your actual store revenue due to attribution windows and cross-platform purchases. *** ## When to Use | Scenario | Action | | ------------------------- | --------------------------------------------------------- | | Campaign isn't profitable | Pause campaigns with ROAS below your break-even threshold | | Scaling decisions | Increase budget on campaigns exceeding target ROAS | | Creative testing | Compare ROAS across ad variations to identify winners | | Channel comparison | Benchmark Meta ROAS against other paid channels | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | The denominator in ROAS calculation | | [Meta Purchases Value](/reference/metrics/advertising/meta/meta-conversions/meta-purchases-value) | The numerator in ROAS calculation | | [Meta CPA](/reference/metrics/advertising/meta/meta-efficiency/meta-cpa) | Cost efficiency per purchase (inverse perspective) | | [Meta New Customer ROAS](/reference/metrics/advertising/meta/meta-efficiency/meta-new-customer-roas) | ROAS from first-time buyers only | # Meta Engagement Metrics Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-engagement/index Track Meta social engagement in Upstack. Monitor likes, comments, shares, reactions, and saves to measure ad resonance on Facebook and Instagram. Engagement metrics measure how people interact socially with your Meta ads. Track likes, comments, shares, reactions, and saves to understand content resonance. **Data Source:** Meta Marketing API\ **Metrics:** 18 ## Metrics in This Group ### Engagement Totals | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------------ | ----------------------- | --------------------------------------- | | [Meta Engagements](/reference/metrics/advertising/meta/meta-engagement/meta-engagements) | All social interactions | Measure total engagement volume | | [Meta Engagement Rate](/reference/metrics/advertising/meta/meta-engagement/meta-engagement-rate) | Engagements ÷ Reach | Compare engagement relative to audience | ### Social Actions | Metric | Description | When to Use | | -------------------------------------------------------------------------------------------- | -------------------- | ---------------------------------- | | [Meta Likes](/reference/metrics/advertising/meta/meta-engagement/meta-likes) | Like reactions | Measure positive sentiment | | [Meta Comments](/reference/metrics/advertising/meta/meta-engagement/meta-comments) | Comment count | Track discussion and conversation | | [Meta Shares](/reference/metrics/advertising/meta/meta-engagement/meta-shares) | Share count | Measure viral potential | | [Meta Saves](/reference/metrics/advertising/meta/meta-engagement/meta-saves) | Save/bookmark count | Track content value and intent | | [Meta Reactions](/reference/metrics/advertising/meta/meta-engagement/meta-reactions) | All emoji reactions | Measure emotional response breadth | | [Meta Page Likes](/reference/metrics/advertising/meta/meta-engagement/meta-page-likes) | Page like actions | Track follower acquisition | | [Meta Post Comments](/reference/metrics/advertising/meta/meta-engagement/meta-post-comments) | Post comment count | Measure post-level conversation | | [Meta Post Saves](/reference/metrics/advertising/meta/meta-engagement/meta-post-saves) | Post saves count | Track content bookmark rate | | [Meta Post Shares](/reference/metrics/advertising/meta/meta-engagement/meta-post-shares) | Post share count | Measure organic amplification | | [Meta Photo Views](/reference/metrics/advertising/meta/meta-engagement/meta-photo-views) | Expanded photo views | Track image engagement depth | ### Cost per Engagement | Metric | Description | When to Use | | -------------------------------------------------------------------------------------------------------- | ------------------- | -------------------------------------- | | [Meta Cost per Engagement](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-engagement) | Spend ÷ Engagements | Evaluate overall engagement efficiency | | [Meta Cost per Comment](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-comment) | Spend ÷ Comments | Track discussion acquisition cost | | [Meta Cost per Share](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-share) | Spend ÷ Shares | Measure viral amplification cost | | [Meta Cost per Save](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-save) | Spend ÷ Saves | Evaluate content value cost | | [Meta Cost per Page Like](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-page-like) | Spend ÷ Page likes | Track follower acquisition cost | | [Meta Cost per Photo View](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-photo-view) | Spend ÷ Photo views | Measure image engagement cost | ## How These Metrics Relate * **Engagements** = Total of all social actions (likes, comments, shares, saves, reactions) * **Reactions** include all emoji responses (love, wow, haha, etc.) * **Likes** are specifically thumbs-up reactions * **Shares** extend organic reach at no additional cost * **Engagement Rate** = Engagements ÷ Reach × 100 High engagement signals resonant creative and can improve delivery efficiency. ## Choosing the Right Metric * **Brand awareness**: Use Engagements and Engagement Rate for overall resonance * **Community building**: Track Comments, Shares, and Page Likes * **Content strategy**: Use Saves to identify high-value content * **Viral potential**: Monitor Shares to find content worth amplifying * **Cost optimization**: Compare Cost per Engagement across campaigns # Meta Comments: Track Ad Conversation Volume Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-engagement/meta-comments Track Meta ad comments to measure audience engagement. Comments signal strong opinions or questions about your product and indicate high-intent interactions. Meta Comments measures the total number of comments left on your Meta (Facebook and Instagram) ads. ## Formula **Meta Comments** = **COUNT** ( Comments ) ### Formula Components | Metric | Definition | | ------------ | ---------------------------------------------------------------------- | | **Comments** | Each comment posted on your ad, including replies to existing comments | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your skincare brand ran a product launch campaign in March, and your ads generated **2,847 comments** across all ad sets. | Ad Creative | Comments | Insight | | ---------------------- | -------- | ---------------------------------------- | | Before/After Video | 1,423 | Questions about ingredients and results | | Influencer Testimonial | 892 | Mix of positive reactions and skepticism | | Product Demo | 532 | Requests for pricing and availability | *** ## How It Works Meta counts every comment posted directly on your ad, including threaded replies. Comments accumulate throughout the ad's lifetime and are attributed based on when the comment was posted, not when the ad was first shown. *** ## When to Use | Scenario | Action | | ----------------------------------- | -------------------------------------------------------------------------------------- | | Evaluating ad creative resonance | Compare comment volume across creatives to identify which sparks the most conversation | | Identifying customer objections | Review comment content to surface common questions or concerns about your product | | Measuring brand awareness campaigns | Use alongside other engagement metrics to gauge overall audience interaction | | Detecting polarizing content | High comments with low shares may indicate controversial messaging | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | [Meta Cost per Comment](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-comment) | Measures how much you spend for each comment received | | [Meta Engagements](/reference/metrics/advertising/meta/meta-engagement/meta-engagements) | Parent metric that includes comments plus likes, shares, and saves | [See all Meta Engagement metrics →](/reference/metrics/advertising/meta/meta-engagement) # Meta Cost per Comment: Ad Spend per Post Comment Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-comment Track Meta cost per comment to measure spend efficiency on high-intent engagement actions. Lower costs indicate resonant ad content that sparks conversation. Measures the average cost to generate each comment on your Meta (Facebook and Instagram) ad posts. ## Formula **Meta Cost per Comment** = **Meta Spend** ÷ **Meta Comments** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------- | -------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising | | [**Meta Comments**](/reference/metrics/advertising/meta/meta-engagement/meta-comments) | Total comments left on your Meta ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your skincare brand spent **\$1,200** on Meta ads this month and generated **480 comments** across campaigns. | Ad Creative | Spend | Comments | Cost/Comment | | -------------------- | ----- | -------- | ------------ | | Before/After Results | \$600 | 312 | \$1.92 | | Ingredient Education | \$400 | 128 | \$3.13 | | Product Comparison | \$200 | 40 | \$5.00 | *** ## How It Works Upstack pulls comment counts from the Meta Ads API and divides your ad spend by total comments for the selected period. Comments represent higher-intent engagement than reactions—users take time to write a response—but typically occur at lower volume. A lower cost per comment indicates your content resonates enough to spark conversation. *** ## When to Use | Scenario | Action | | ------------------------------------------- | ------------------------------------------------------------------------------ | | Identifying conversation-driving content | Compare cost per comment across creatives to find topics that spark discussion | | Evaluating brand awareness efficiency | Lower cost indicates stronger audience engagement per dollar spent | | Optimizing engagement campaigns | Prioritize ad sets with lower cost per comment for community building | | Benchmarking against other engagement types | Compare to cost per reaction to understand engagement depth versus volume | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | [Meta Comments](/reference/metrics/advertising/meta/meta-engagement/meta-comments) | The comment volume this metric divides spend by | | [Meta Cost per Engagement](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-engagement) | Broader engagement efficiency including all interaction types | | [Meta Engagement Rate](/reference/metrics/advertising/meta/meta-engagement/meta-engagement-rate) | Shows engagement as percentage of reach, not cost efficiency | [See all Meta Engagement metrics →](/reference/metrics/advertising/meta/meta-engagement) # Meta Cost per Engagement: Measure Brand Interaction Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-engagement Track Meta cost per engagement to measure brand awareness efficiency. Calculate average spend per social interaction on Meta ads. Meta Cost per Engagement measures how much you spend for each social interaction (like, comment, share, save) on your Meta ads. ## Formula **Meta Cost per Engagement** = **Meta Spend** ÷ **Meta Engagements** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising campaigns | | [**Meta Engagements**](/reference/metrics/advertising/meta/meta-engagement/meta-engagements) | Total social interactions (likes, comments, shares, saves) on your Meta ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your brand awareness campaign spent **\$2,400** and generated **8,000 engagements** over the month. | Metric | Value | Calculation | | ----------------------- | ---------- | --------------------------------- | | Meta Spend | \$2,400 | Total ad spend | | Meta Engagements | 8,000 | Likes + comments + shares + saves | | **Cost per Engagement** | **\$0.30** | \$2,400 ÷ 8,000 | *** ## How It Works Meta Cost per Engagement divides your total ad spend by the number of social interactions your ads received. This metric helps you understand how efficiently your budget drives meaningful social engagement rather than just impressions or clicks. *** ## When to Use | Scenario | Action | | ------------------------------------ | --------------------------------------------------------------------- | | Evaluating brand awareness campaigns | Compare cost per engagement across ad sets to identify what resonates | | Community-building initiatives | Track engagement costs to optimize social content strategy | | Benchmarking creative performance | Lower cost per engagement indicates more engaging creative | | Budget allocation decisions | Shift spend toward campaigns with efficient engagement costs | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | | [Meta Engagements](/reference/metrics/advertising/meta/meta-engagement/meta-engagements) | The denominator — total interactions driving this cost metric | | [Meta Engagement Rate](/reference/metrics/advertising/meta/meta-engagement/meta-engagement-rate) | Percentage view showing engagement efficiency without cost context | | [Meta CPM](/reference/metrics/advertising/meta/meta-audience/meta-cpm) | Cost per thousand impressions — compare reach efficiency vs engagement efficiency | [See all Meta Engagement metrics →](/reference/metrics/advertising/meta/meta-engagement) # Meta Cost per Page Like: Follower Acquisition Metric Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-page-like Track Meta cost per page like to measure how efficiently your ads acquire new Page followers. Evaluate spend against the lifetime organic reach value of each follower. Measures the average amount you spend to acquire each new follower for your Facebook Page through Meta ads. ## Formula **Meta Cost per Page Like** = **Meta Spend** ÷ **Meta Page Likes** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising campaigns | | [**Meta Page Likes**](/reference/metrics/advertising/meta/meta-engagement/meta-page-likes) | Number of Facebook Page follows attributed to your Meta ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your Page growth campaign spent **\$1,200** and gained **800 new followers** this month. | Campaign | Spend | Page Likes | Cost/Like | | ----------------------- | ----- | ---------- | --------- | | Page Growth - Lookalike | \$700 | 520 | \$1.35 | | Page Growth - Interest | \$500 | 280 | \$1.79 | *** ## How It Works Upstack pulls Page like data directly from Meta Ads API. The cost per page like is calculated by dividing total ad spend by new Page followers gained during the selected period. This metric specifically tracks Facebook Page follows, not post reactions. *** ## When to Use | Scenario | Action | | ---------------------------------- | ----------------------------------------------------- | | Building organic reach | Lower cost indicates efficient audience growth | | Comparing audience targeting | Identify which targeting drives cheapest followers | | Evaluating follower lifetime value | Compare acquisition cost against organic reach value | | Benchmarking Page campaigns | Track efficiency across different creative approaches | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | [Meta Page Likes](/reference/metrics/advertising/meta/meta-engagement/meta-page-likes) | The follower count this metric divides spend by | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | The ad spend this metric divides by page likes | | [Meta Cost per Engagement](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-engagement) | Broader engagement cost including all social actions | [See all Meta Engagement metrics →](/reference/metrics/advertising/meta/meta-engagement) # Meta Cost per Photo View: Photo Ad Engagement Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-photo-view Track cost per photo view for Meta ads. Measure photo ad engagement efficiency and optimize creative spend across Facebook and Instagram. Average spend per photo view on your Meta ads—useful for measuring photo ad engagement efficiency. ## Formula **Meta Cost per Photo View** = **Meta Spend** ÷ **Meta Photo Views** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------- | --------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising campaigns | | [**Meta Photo Views**](/reference/metrics/advertising/meta/meta-engagement/meta-photo-views) | Number of times photos in your Meta ads were viewed | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your Meta campaigns spent **\$1,200** and generated **15,000 photo views** last week. | Metric | Value | | ---------------------------- | ---------- | | Meta Spend | \$1,200 | | Meta Photo Views | 15,000 | | **Meta Cost per Photo View** | **\$0.08** | At \$0.08 per photo view, you're paying eight cents for each time a user views a photo in your ad creative. *** ## How It Works Meta Cost per Photo View divides your total ad spend by the number of photo views. This metric helps you understand how efficiently your budget drives engagement with photo-based creative. Lower values indicate more cost-effective photo ad performance. *** ## When to Use | Scenario | Action | | ---------------------------------- | ------------------------------------------------------------- | | Comparing photo vs. video creative | Use to benchmark photo engagement costs against video metrics | | Optimizing carousel ads | Track cost per photo view across carousel cards | | Budget allocation | Identify which campaigns deliver photo views most efficiently | | Creative testing | Compare photo engagement costs across different ad variations | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------- | | [Meta Photo Views](/reference/metrics/advertising/meta/meta-engagement/meta-photo-views) | Denominator in this calculation | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Numerator in this calculation | | [Meta CPM](/reference/metrics/advertising/meta/meta-audience/meta-cpm) | Alternative cost efficiency metric based on impressions | | [Meta CPC](/reference/metrics/advertising/meta/meta-clicks/meta-cpc) | Cost efficiency metric based on clicks | [See all Meta Engagement metrics →](/reference/metrics/advertising/meta/meta-engagement) # Meta Cost per Save: Efficiency of Ad Engagement Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-save Track Meta Cost per Save to measure how efficiently your ad spend generates saves. Lower cost per save indicates stronger ad resonance with audiences. Meta Cost per Save measures the average amount you spend to generate one ad save on Meta platforms. ## Formula **Meta Cost per Save** = **Meta Spend** ÷ **Meta Saves** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------- | ------------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising campaigns | | [**Meta Saves**](/reference/metrics/advertising/meta/meta-engagement/meta-saves) | Number of times users saved your ad for later reference | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your brand spent **\$2,500** on Meta ads last week and generated **312 saves**. | Metric | Value | Calculation | | ---------------------- | ---------- | ------------------- | | Meta Spend | \$2,500 | Total ad budget | | Meta Saves | 312 | Users who saved ads | | **Meta Cost per Save** | **\$8.01** | \$2,500 ÷ 312 | *** ## How It Works Meta Cost per Save divides your total Meta ad spend by the number of saves your ads received. Saves indicate strong purchase intent—users bookmarking your ad to revisit later. A lower cost per save suggests your creative resonates well enough that users want to return to it. *** ## When to Use | Scenario | Action | | ---------------------------------- | ----------------------------------------------------------------------- | | Comparing ad creatives | Identify which visuals or messages drive saves most efficiently | | Evaluating consideration campaigns | Measure mid-funnel engagement where users show intent to return | | Optimizing for purchase intent | Saves often correlate with future conversions—track alongside ROAS | | Benchmarking engagement costs | Compare against other engagement metrics like cost per share or comment | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | [Meta Saves](/reference/metrics/advertising/meta/meta-engagement/meta-saves) | The volume metric this efficiency metric normalizes | | [Meta Cost per Engagement](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-engagement) | Broader engagement efficiency including all interaction types | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | The numerator in this cost efficiency calculation | [See all Meta Engagement metrics →](/reference/metrics/advertising/meta/meta-engagement) # Meta Cost per Share: Ad Spend per Share Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-share Track cost per share for Meta ads. A lower cost-per-share signals strong word-of-mouth potential and organic reach amplification. Average spend per ad share—a lower cost-per-share can signal strong word-of-mouth potential. ## Formula **Meta Cost per Share** = **Meta Spend** ÷ **Meta Shares** ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------- | ------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising campaigns | | [**Meta Shares**](/reference/metrics/advertising/meta/meta-engagement/meta-shares) | Number of times users shared your Meta ad content | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your brand awareness campaign spent **\$4,000** and generated **800 shares** last month. | Metric | Value | | ----------------------- | ---------- | | Meta Spend | \$4,000 | | Meta Shares | 800 | | **Meta Cost per Share** | **\$5.00** | At \$5.00 per share, each share costs five dollars—but that share exposes your ad to the sharer's entire network at no additional cost. *** ## How It Works Meta Cost per Share divides your total ad spend by the number of shares. Shares amplify your reach organically—each share exposes your ad to the sharer's network without additional spend. Lower cost per share indicates content that resonates enough for users to publicly endorse and redistribute. *** ## When to Use | Scenario | Action | | ------------------------------------------ | ------------------------------------------------------------------------------------------ | | Identifying viral-worthy content | Compare cost per share across creatives to find what audiences want to redistribute | | Evaluating organic amplification potential | Lower cost indicates stronger word-of-mouth efficiency per dollar spent | | Optimizing brand awareness campaigns | Prioritize ad sets with lower cost per share for earned reach | | Benchmarking shareability | Compare to cost per other engagement types to understand sharing versus passive engagement | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | [Meta Shares](/reference/metrics/advertising/meta/meta-engagement/meta-shares) | Denominator in this calculation | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Numerator in this calculation | | [Meta Cost per Engagement](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-engagement) | Broader engagement efficiency including all interaction types | | [Meta Engagement Rate](/reference/metrics/advertising/meta/meta-engagement/meta-engagement-rate) | Shows engagement as percentage of reach, not cost efficiency | [See all Meta Engagement metrics →](/reference/metrics/advertising/meta/meta-engagement) # Meta Engagement Rate: Measure Ad Creative Resonance Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-engagement/meta-engagement-rate Track the percentage of people who engaged with your Meta ads after seeing them. Learn the formula, see benchmarks, and optimize creative for higher engagement. The percentage of people who engaged with your Meta ads after seeing them. ## Formula **Meta Engagement Rate** = ( **Meta Engagements** ÷ **Meta Reach** ) × 100 ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | [**Meta Engagements**](/reference/metrics/advertising/meta/meta-engagement/meta-engagements) | Total interactions on your ads including reactions, comments, shares, and saves | | [**Meta Reach**](/reference/metrics/advertising/meta/meta-audience/meta-reach) | Number of unique people who saw your ads at least once | | Metadata | | | --------------- | --------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your brand awareness campaign reached **125,000** people and generated **4,375** engagements: | Campaign | Reach | Engagements | Rate | | ----------------- | ----------- | ----------- | -------- | | Summer Collection | 85,000 | 3,400 | 4.0% | | Flash Sale | 40,000 | 975 | 2.4% | | **Total** | **125,000** | **4,375** | **3.5%** | *** ## How It Works Engagement Rate measures how compelling your ad creative is to your audience. Meta counts engagements as any interaction—reactions, comments, shares, saves, or clicks. The rate normalizes by reach so you can compare campaigns with different audience sizes. *** ## When to Use | Scenario | Action | | ------------------------------- | ------------------------------------------------------------ | | Evaluating creative performance | Compare rates across ad variations to find top performers | | Diagnosing low conversions | High reach + low engagement suggests creative refresh needed | | Optimizing for awareness | Target 2-5% engagement rate for brand campaigns | | A/B testing ad copy | Use engagement rate as a leading indicator of resonance | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | [Meta Engagements](/reference/metrics/advertising/meta/meta-engagement/meta-engagements) | The numerator (total interactions) | | [Meta Cost per Engagement](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-engagement) | Spend efficiency for driving engagements | | [Meta Reach](/reference/metrics/advertising/meta/meta-audience/meta-reach) | The denominator (unique people) | | [Meta CTR](/reference/metrics/advertising/meta/meta-clicks/meta-ctr) | Click-based engagement measure | [See all Meta Engagement metrics →](/reference/metrics/advertising/meta/meta-engagement) # Meta Engagements: Track Total Social Ad Interactions Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-engagement/meta-engagements Measure total interactions on your Meta ads including likes, comments, shares, and saves. High engagement signals resonant creative that drives brand awareness. Meta Engagements measures the total social interactions on your Meta ads—reactions, comments, shares, and saves combined. ## Formula **Meta Engagements** = [**Meta Reactions**](/reference/metrics/advertising/meta/meta-engagement/meta-reactions) + [**Meta Comments**](/reference/metrics/advertising/meta/meta-engagement/meta-comments) + [**Meta Shares**](/reference/metrics/advertising/meta/meta-engagement/meta-shares) + [**Meta Saves**](/reference/metrics/advertising/meta/meta-engagement/meta-saves) ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | [**Meta Reactions**](/reference/metrics/advertising/meta/meta-engagement/meta-reactions) | Emoji responses on your ads including likes, loves, wows, and cares | | [**Meta Comments**](/reference/metrics/advertising/meta/meta-engagement/meta-comments) | Comments posted directly on your ads including threaded replies | | [**Meta Shares**](/reference/metrics/advertising/meta/meta-engagement/meta-shares) | Times users shared your ad to their feed, stories, or DMs | | [**Meta Saves**](/reference/metrics/advertising/meta/meta-engagement/meta-saves) | Times users bookmarked your ad for later viewing | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your skincare brand ran a video ad showcasing a new serum. Over the campaign, the ad generated **8,420 engagements**. | Interaction Type | Count | Share | | ---------------- | ----- | ----- | | Reactions | 5,240 | 62% | | Comments | 1,685 | 20% | | Shares | 842 | 10% | | Saves | 653 | 8% | *** ## How It Works Meta aggregates all social interactions on your ad into a single engagement count. This includes emoji reactions (like, love, wow, etc.), comments, shares to feeds or stories, and saves for later viewing. Each action by a unique user counts separately. *** ## When to Use | Scenario | Action | | ----------------------------- | ----------------------------------------------------------------- | | Evaluating creative resonance | Compare engagements across ad variants to identify top performers | | Brand awareness campaigns | Prioritize high-engagement ads to maximize organic reach | | Content testing | Use engagement patterns to guide future creative direction | | Audience targeting validation | High engagements signal you're reaching the right people | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | [Meta Cost per Engagement](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-engagement) | How much you pay per interaction | | [Meta Engagement Rate](/reference/metrics/advertising/meta/meta-engagement/meta-engagement-rate) | Engagements as a percentage of reach | | [Meta Reactions](/reference/metrics/advertising/meta/meta-engagement/meta-reactions) | Emoji reactions component of engagements | | [Meta Shares](/reference/metrics/advertising/meta/meta-engagement/meta-shares) | Share component driving organic amplification | [See all Meta Engagement metrics →](/reference/metrics/advertising/meta/meta-engagement) # Meta Likes: Track Positive Engagement on Your Meta Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-engagement/meta-likes Track Meta Likes to measure positive engagement on your ads. Monitor thumbs-up reactions and compare with total reactions to gauge audience sentiment. Meta Likes counts the total thumbs-up reactions on your Meta ads—a basic positive engagement signal. ## Formula **Meta Likes** = **COUNT** ( Post Likes ) ### Formula Components | Metric | Definition | | -------------- | ------------------------------------------------ | | **Post Likes** | Thumbs-up reactions recorded by Meta on your ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your spring campaign ad received **3,420 likes** across 50,000 impressions in March. | Campaign | Likes | Impressions | Like Rate | | ------------ | ----- | ----------- | --------- | | Spring Sale | 3,420 | 50,000 | 6.8% | | New Arrivals | 1,890 | 42,000 | 4.5% | *** ## How It Works Meta counts every thumbs-up reaction on your ad. Likes are the most basic positive reaction—they indicate the audience noticed your ad and responded favorably, though they don't signal as strong an emotional response as other reactions like Love or Wow. *** ## When to Use | Scenario | Action | | ------------------------------ | --------------------------------------------------- | | Comparing creative performance | Higher likes suggest more appealing visuals or copy | | Monitoring brand sentiment | Consistent likes indicate stable audience approval | | Benchmarking engagement | Compare likes-to-impressions ratio across campaigns | | Identifying fatigue | Declining likes may signal ad creative burnout | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [Meta Reactions](/reference/metrics/advertising/meta/meta-engagement/meta-reactions) | Broader count including all emoji reactions | | [Meta Engagements](/reference/metrics/advertising/meta/meta-engagement/meta-engagements) | Total interactions including comments, shares, and saves | | [Meta Cost per Engagement](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-engagement) | Measures efficiency—spend required for each engagement | [See all Meta Engagement metrics →](/reference/metrics/advertising/meta/meta-engagement) # Meta Page Likes: Grow Your Organic Facebook Audience Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-engagement/meta-page-likes Track Meta Page Likes to measure Facebook Page followers gained from ads. Build your organic audience, monitor campaign effectiveness, and grow future reach. How many people liked your Facebook Page after seeing your ad. Measures page growth from advertising. ## Formula **Meta Page Likes** = **COUNT** ( Page Likes ) ### Formula Components | Metric | Definition | | -------------- | ------------------------------------------------------- | | **Page Likes** | Each new Facebook Page like attributed to your Meta ads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your brand awareness campaign generated **2,340 page likes** in Q1, growing your Facebook following by 15%. | Campaign | Page Likes | Reach | Page Like Rate | | --------------- | ---------- | ------- | -------------- | | Brand Awareness | 2,340 | 425,000 | 0.55% | | Product Launch | 890 | 180,000 | 0.49% | | Retargeting | 156 | 45,000 | 0.35% | *** ## How It Works When someone clicks "Like" on your Facebook Page after viewing or engaging with your ad, Meta attributes that page like to the campaign. Page likes differ from ad likes—they represent a lasting connection where followers will see your future organic posts in their feed. *** ## When to Use | Scenario | Action | | --------------------------------- | --------------------------------------------------------------- | | Building brand presence | Run page like campaigns to establish your Facebook audience | | Page likes declining | Refresh creative or expand targeting to reach new prospects | | Comparing organic reach potential | Higher page likes mean larger organic audience for future posts | | Evaluating acquisition cost | Track cost per page like alongside page like volume | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | | [Meta Cost per Page Like](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-page-like) | Spend required for each new page follower | | [Meta Engagements](/reference/metrics/advertising/meta/meta-engagement/meta-engagements) | Total ad interactions including reactions, comments, and shares | | [Meta Likes](/reference/metrics/advertising/meta/meta-engagement/meta-likes) | Likes on your ads, distinct from page follows | [See all Meta Engagement metrics →](/reference/metrics/advertising/meta/meta-engagement) # Meta Photo Views: Track Visual Content Engagement Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-engagement/meta-photo-views Measure how many times photos in your Meta ads were viewed in expanded or full-screen mode. High photo views indicate strong visual content engagement. The number of times photos in your Meta ads were viewed. Includes clicks to expand or zoom on images. ## Formula **Meta Photo Views** = **COUNT** ( Photo Views ) ### Formula Components | Metric | Definition | | --------------- | ----------------------------------------------------------------- | | **Photo Views** | Each tap or click to view a photo in expanded or full-screen mode | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your furniture brand ran a carousel ad featuring 6 product photos. Over the campaign, the ad generated **12,840 photo views**. | Photo Position | Views | Share | | --------------- | ----- | ----- | | Hero image | 5,136 | 40% | | Detail shot 1 | 3,210 | 25% | | Detail shot 2 | 2,568 | 20% | | Lifestyle image | 1,284 | 10% | | Other photos | 642 | 5% | *** ## How It Works Meta counts a photo view when a user actively engages with an image by tapping or clicking to view it in expanded or full-screen mode. This differs from impressions, which count when the ad appears on screen. Photo views indicate intentional engagement with your visual content. *** ## When to Use | Scenario | Action | | --------------------------- | --------------------------------------------------------------------- | | Evaluating visual creative | Compare photo views across ad variants to identify compelling imagery | | Product photography testing | Use photo view patterns to guide image selection | | Carousel optimization | Identify which carousel positions drive the most engagement | | Visual content strategy | High photo views signal strong visual storytelling | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | [Meta Cost per Photo View](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-photo-view) | How much you pay per expanded photo view | | [Meta Engagements](/reference/metrics/advertising/meta/meta-engagement/meta-engagements) | Total social interactions including photo views | | [Meta Reactions](/reference/metrics/advertising/meta/meta-engagement/meta-reactions) | Emoji reactions to your visual content | [See all Meta Engagement metrics →](/reference/metrics/advertising/meta/meta-engagement) # Meta Post Comments: Track Ad Conversation Depth Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-engagement/meta-post-comments Track comments on your Meta ad posts. Comments indicate high engagement and surface customer questions or feedback about your products. Comments left directly on your ad post. Indicates high engagement and potential customer questions or feedback. ## Formula **Meta Post Comments** = **COUNT** ( Post Comments ) ### Formula Components | Metric | Definition | | ----------------- | ------------------------------------------------------------------------------------------- | | **Post Comments** | Each comment posted directly on your ad post, including replies to existing comment threads | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your fitness apparel brand ran a new product launch campaign, and your ads generated **1,847 post comments** over three weeks. | Ad Creative | Post Comments | Insight | | ----------------------- | ------------- | --------------------------------------- | | Workout Video Demo | 892 | Questions about sizing and fabric | | Customer Transformation | 623 | Mix of motivation and product inquiries | | Product Features | 332 | Pricing questions and color requests | *** ## How It Works Meta counts every comment posted directly on your ad post, including threaded replies within existing comment chains. Post comments accumulate over the ad's lifetime and are attributed based on when the comment was posted, not when the ad was first shown. *** ## When to Use | Scenario | Action | | --------------------------------- | ----------------------------------------------------------------------------------- | | Measuring creative resonance | Compare post comment volume across ads to identify content that sparks conversation | | Surfacing customer objections | Review comment content to identify common questions or product concerns | | Prioritizing community management | Higher comment counts require active monitoring and response | | Evaluating engagement depth | Post comments indicate deeper engagement than passive likes or reactions | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | [Meta Cost per Comment](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-comment) | Measures spend efficiency per comment received | | [Meta Engagements](/reference/metrics/advertising/meta/meta-engagement/meta-engagements) | Parent metric that includes comments plus likes, shares, and saves | | [Meta Post Shares](/reference/metrics/advertising/meta/meta-engagement/meta-post-shares) | Measures organic amplification through user shares | [See all Meta Engagement metrics →](/reference/metrics/advertising/meta/meta-engagement) # Meta Post Saves: Track Ad Saves & Purchase Intent Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-engagement/meta-post-saves Track Meta post saves to measure purchase intent. Saves reveal high-value audiences who bookmark your ads to revisit later—a strong buying signal. Meta Post Saves counts how many times users saved your ad posts to view later. ## Formula **Meta Post Saves** = **COUNT** ( Post Saves ) ### Formula Components | Metric | Definition | | -------------- | ------------------------------------------------------------------- | | **Post Saves** | Individual save actions when users tap the bookmark icon on your ad | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your skincare brand ran a carousel ad featuring a 5-step routine. The ad received **847 saves** over two weeks. | Campaign | Saves | CTR | Purchases | | ---------------- | ----- | ---- | --------- | | Routine Carousel | 847 | 2.1% | 156 | | Single Product | 312 | 1.8% | 89 | | Video Tutorial | 623 | 1.4% | 134 | The carousel with the highest saves also drove the most purchases, confirming saves as a strong intent signal. *** ## How It Works When users save your ad, Meta records the action as a post engagement. Saves indicate the user found your content valuable enough to bookmark for later—often signaling purchase consideration. Unlike reactions or comments, saves require deliberate intent to revisit. *** ## When to Use | Scenario | Action | | ---------------------------- | --------------------------------------------------------- | | High saves but low purchases | Add urgency or clearer CTA to convert saved audiences | | Testing ad creative | Prioritize concepts with higher save rates | | Building retargeting pools | Target users who saved ads for follow-up campaigns | | Measuring content value | Compare saves across product education vs promotional ads | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------- | ------------------------------------ | | [Meta Cost per Save](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-save) | Efficiency of driving saves | | [Meta Engagements](/reference/metrics/advertising/meta/meta-engagement/meta-engagements) | Total interactions including saves | | [Meta Add to Carts](/reference/metrics/advertising/meta/meta-conversions/meta-add-to-carts) | Downstream conversion from saved ads | [See all Meta Engagement metrics →](/reference/metrics/advertising/meta/meta-engagement) # Meta Post Shares: Track Ad Content Virality Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-engagement/meta-post-shares Track Meta Post Shares to measure ad virality. See how often people share your content, analyze resonance, and optimize for organic reach. The number of times people shared your Meta ad posts to their feed, stories, or with friends. Shares extend organic reach. ## Formula **Meta Post Shares** = **COUNT** ( Post Shares ) ### Formula Components | Metric | Definition | | --------------- | ------------------------------------------------------------------------------------------- | | **Post Shares** | Each instance someone shares your ad post to their timeline, stories, or via direct message | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your summer collection campaign generated **847 shares** in June across three ad sets. | Ad Set | Shares | Share Rate | | ------------ | ------ | ---------- | | UGC Video | 412 | 0.8% | | Carousel | 298 | 0.5% | | Static Image | 137 | 0.2% | *** ## How It Works Meta counts a share whenever someone distributes your ad content through any sharing mechanism—posting to their feed, sharing to stories, or sending to friends via Messenger. High shares indicate content that resonates strongly enough for people to endorse with their personal network. *** ## When to Use | Scenario | Action | | ---------------------------- | --------------------------------------------------------------------- | | Evaluating content resonance | Compare share rates across creative formats to identify viral content | | Building brand awareness | Prioritize ad sets with high shares for organic amplification | | Measuring social proof | Track shares alongside reactions and comments for engagement health | | Optimizing creative strategy | Double down on themes and formats that drive sharing behavior | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------- | ------------------------------- | | [Meta Cost per Share](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-share) | Efficiency of driving shares | | [Meta Reactions](/reference/metrics/advertising/meta/meta-engagement/meta-reactions) | Emotional engagement complement | | [Meta Post Comments](/reference/metrics/advertising/meta/meta-engagement/meta-post-comments) | Conversation-driving engagement | [See all Meta Engagement metrics →](/reference/metrics/advertising/meta/meta-engagement) # Meta Reactions: Measure Emotional Engagement on Your Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-engagement/meta-reactions Track Meta Reactions to measure emotional engagement on your ads. Monitor emoji responses like love, wow, care, and haha to evaluate creative resonance. Meta Reactions counts all emoji responses on your Meta ads—likes, loves, wows, cares, hahas, and more. ## Formula **Meta Reactions** = **COUNT** ( Reactions ) ### Formula Components | Metric | Definition | | ------------- | -------------------------------------------------------------------------------------------------- | | **Reactions** | Emoji responses recorded by Meta on your ads including like, love, care, haha, wow, sad, and angry | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your holiday campaign video generated **12,850 reactions** across 180,000 impressions in December. | Campaign | Reactions | Impressions | Reaction Rate | | ------------------ | --------- | ----------- | ------------- | | Holiday Gift Guide | 12,850 | 180,000 | 7.1% | | Winter Clearance | 4,320 | 95,000 | 4.5% | | New Year Sale | 6,740 | 120,000 | 5.6% | *** ## How It Works Meta tracks every emoji reaction on your ad—including like, love, care, haha, wow, sad, and angry. Reactions provide a quick signal of emotional resonance beyond basic engagement. A high reaction count suggests your creative strikes an emotional chord with viewers. *** ## When to Use | Scenario | Action | | ------------------------------ | ------------------------------------------------------------ | | Testing creative concepts | Compare reaction counts to identify emotionally resonant ads | | Measuring brand sentiment | Track reaction trends to gauge audience emotional response | | Optimizing awareness campaigns | Prioritize ads with high reactions for organic amplification | | Identifying viral potential | High reactions relative to reach signal share-worthy content | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | [Meta Cost per Reaction](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-reaction) | How much you pay per emoji reaction | | [Meta Likes](/reference/metrics/advertising/meta/meta-engagement/meta-likes) | Thumbs-up reactions, a subset of total reactions | | [Meta Engagements](/reference/metrics/advertising/meta/meta-engagement/meta-engagements) | Broader count including comments, shares, and saves | [See all Meta Engagement metrics →](/reference/metrics/advertising/meta/meta-engagement) # Meta Saves: Measure Bookmark Interest Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-engagement/meta-saves Track how many people saved your Meta ads for later viewing. Saves indicate strong product interest and future purchase intent. Measures how many times people bookmarked your Meta ad to revisit later. ## Formula **Meta Saves** = **COUNT** ( Saves ) ### Formula Components | Metric | Definition | | --------- | ----------------------------------------------------------- | | **Saves** | Each tap of the bookmark icon on your ad counts as one save | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your new product launch campaign generated **523 saves** on Instagram and Facebook last week. | Ad Creative | Saves | Est. Return Rate | | ------------------------- | ----- | ---------------- | | Product lifestyle video | 218 | \~12% | | Limited-time offer static | 189 | \~8% | | Product feature carousel | 116 | \~6% | The lifestyle video earned the most saves, suggesting viewers plan to return and purchase later. Consider retargeting users who saved but haven't converted. *** ## How It Works When someone saves your ad, they're bookmarking it for future reference—often because they're interested but not ready to buy. Meta tracks saves across Facebook and Instagram, including posts saved to Collections. High save counts indicate strong product interest and potential future conversions, making savers ideal candidates for retargeting campaigns. *** ## When to Use | Scenario | Action | | --------------------------------- | ----------------------------------------------------- | | Identifying high-intent audiences | Build retargeting segments from users who saved | | Evaluating creative appeal | Compare save counts to find ads with lasting interest | | Measuring consideration intent | High saves signal people researching before buying | | Optimizing for future conversions | Prioritize creatives that drive saves for remarketing | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | [Meta Cost per Save](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-save) | How much you pay per save action | | [Meta Engagements](/reference/metrics/advertising/meta/meta-engagement/meta-engagements) | Total interactions including saves, likes, comments, shares | [See all Meta Engagement metrics →](/reference/metrics/advertising/meta/meta-engagement) # Meta Shares: Track Ad Virality Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-engagement/meta-shares Track how many times people shared your Meta ads to their own feed or stories. Shares extend organic reach at no extra cost. Measures how many times people shared your Meta ad to their own feed or stories. ## Formula **Meta Shares** = **COUNT** ( Shares ) ### Formula Components | Metric | Definition | | ---------- | ------------------------------------------------------------------------------------------ | | **Shares** | Each time a user taps "Share" and distributes your ad to their network counts as one share | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your spring sale campaign generated **847 shares** across Facebook and Instagram last week. | Ad Creative | Shares | Organic Impressions | | ------------------- | ------ | ------------------- | | Carousel with UGC | 412 | \~8,200 | | Video testimonial | 289 | \~5,800 | | Static product shot | 146 | \~2,900 | The UGC carousel earned the most shares, extending reach to an estimated 8,200 additional viewers without increasing ad spend. *** ## How It Works When someone shares your ad, their followers see it organically—without you paying for that impression. Meta tracks all share actions across Facebook feed, Stories, Messenger, and Instagram DMs. Shares indicate strong resonance and can amplify campaign reach beyond your paid audience. *** ## When to Use | Scenario | Action | | ---------------------------- | -------------------------------------------------------------- | | Evaluating creative virality | Compare share counts across ad sets to identify what resonates | | Measuring brand awareness | High shares signal content worth spreading | | Optimizing for organic reach | Prioritize creatives that earn the most shares | | Reducing cost per impression | More shares means more free exposure | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | [Meta Cost per Share](/reference/metrics/advertising/meta/meta-engagement/meta-cost-per-share) | How much you pay per share action | | [Meta Engagements](/reference/metrics/advertising/meta/meta-engagement/meta-engagements) | Total interactions including shares, likes, comments | [See all Meta Engagement metrics →](/reference/metrics/advertising/meta/meta-engagement) # Meta Spend Metrics Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-spend/index Track Meta advertising spend in Upstack. Monitor your Facebook and Instagram ad budget consumption with real-time spend tracking. Spend metrics track your Meta advertising budget consumption. Monitor how much you're spending across campaigns to manage budgets and calculate efficiency ratios. **Data Source:** Meta Marketing API\ **Metrics:** 1 ## Metrics in This Group | Metric | Description | When to Use | | ----------------------------------------------------------------------- | -------------------------------- | -------------------------------------------------------------- | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total ad budget consumed by Meta | Track budget consumption, calculate ROAS and efficiency ratios | ## How Spend Works Meta Spend represents the actual amount billed by Meta for your advertising. This value is pulled directly from Meta's reporting API and reflects real ad delivery costs including any platform fees. ## Choosing the Right Metric Meta Spend is the foundation metric for all efficiency calculations. Use it to: * **Budget tracking**: Monitor daily/weekly spend against targets * **ROAS calculation**: Divide revenue by spend to measure return * **CPA analysis**: Divide spend by conversions to measure acquisition cost * **Channel comparison**: Compare spend efficiency across platforms # Meta Spend: Track Your Total Ad Budget Consumption Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-spend/meta-spend Track total Meta ad spend. See how much Meta billed you during any period to monitor budget consumption and calculate efficiency metrics. Meta Spend measures the total amount Meta billed you for advertising during the selected period. ## Formula **Meta Spend** = **SUM** ( Ad Costs ) | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your store spent **\$4,850** on Meta ads in January across three campaigns. | Campaign | Spend | Share of Budget | | --------------- | ------- | --------------- | | Prospecting | \$2,400 | 49.5% | | Retargeting | \$1,650 | 34.0% | | Brand Awareness | \$800 | 16.5% | *** ## How It Works Meta Spend is pulled directly from your Meta Ads account via the Marketing API. It reflects the actual amount billed to your payment method, updated daily. This value serves as the denominator for efficiency metrics like ROAS and CPA. *** ## When to Use | Scenario | Action | | ------------------- | ------------------------------------------- | | Budget pacing | Monitor daily spend against monthly targets | | Campaign comparison | Compare spend distribution across campaigns | | Efficiency analysis | Combine with revenue to calculate ROAS | | Cost control | Set alerts when spend exceeds thresholds | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------- | ------------------------------------ | | [Meta CPM](/reference/metrics/advertising/meta/meta-audience/meta-cpm) | Spend divided by impressions × 1,000 | | [Meta CPC](/reference/metrics/advertising/meta/meta-clicks/meta-cpc) | Spend divided by clicks | | [Meta ROAS](/reference/metrics/advertising/meta/meta-efficiency/meta-roas) | Revenue divided by spend | # Meta Video Metrics Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-video/index Track Meta video ad performance in Upstack. Monitor video views, ThruPlay, completion rates, and cost efficiency for Facebook and Instagram video campaigns. Video metrics track how people watch your Meta video ads. Monitor view counts, completion rates, and cost efficiency for video content on Facebook and Instagram. **Data Source:** Meta Marketing API\ **Metrics:** 15 ## Metrics in This Group | Metric | Description | When to Use | | ----------------------------------------------------------------------------------------------------- | ---------------------------- | ---------------------------------- | | [Meta Video Views](/reference/metrics/advertising/meta/meta-video/meta-video-views) | 3+ second video views | Measure video engagement threshold | | [Meta Video Plays](/reference/metrics/advertising/meta/meta-video/meta-video-plays) | Video play starts | Track total play initiations | | [Meta Video Completions](/reference/metrics/advertising/meta/meta-video/meta-video-completions) | 100% completion | Measure full video engagement | | [Meta ThruPlay](/reference/metrics/advertising/meta/meta-video/meta-thruplay) | ThruPlay views | Optimize for awareness campaigns | | [Meta ThruPlay Views](/reference/metrics/advertising/meta/meta-video/meta-thruplay-views) | ThruPlay view count | Track ThruPlay volume | | [Meta Video Views 15 Sec](/reference/metrics/advertising/meta/meta-video/meta-video-views-15-sec) | 15+ second views | Measure sustained attention | | [Meta Video Views 25%](/reference/metrics/advertising/meta/meta-video/meta-video-views-25-percent) | 25%+ completion | Track early drop-off | | [Meta Video Views 50%](/reference/metrics/advertising/meta/meta-video/meta-video-views-50-percent) | 50%+ completion | Measure mid-point retention | | [Meta Video Views 75%](/reference/metrics/advertising/meta/meta-video/meta-video-views-75-percent) | 75%+ completion | Track near-completion rate | | [Meta Video Views 100%](/reference/metrics/advertising/meta/meta-video/meta-video-views-100-percent) | 100% completion | Measure full video consumption | | [Meta Average Watch Time](/reference/metrics/advertising/meta/meta-video/meta-average-watch-time) | Average video watch duration | Compare content engagement | | [Meta Cost per Video View](/reference/metrics/advertising/meta/meta-video/meta-cost-per-video-view) | Spend ÷ Video views | Evaluate view acquisition cost | | [Meta Cost per Video Play](/reference/metrics/advertising/meta/meta-video/meta-cost-per-video-play) | Spend ÷ Video plays | Track play initiation cost | | [Meta Cost per ThruPlay](/reference/metrics/advertising/meta/meta-video/meta-cost-per-thruplay) | Spend ÷ ThruPlay | Optimize ThruPlay efficiency | | [Meta Cost per 15 Sec View](/reference/metrics/advertising/meta/meta-video/meta-cost-per-15-sec-view) | Spend ÷ 15s views | Measure sustained attention cost | ## How These Metrics Relate * **Video Plays** counts all play initiations, including auto-plays * **Video Views** requires 3+ seconds watched (Meta's standard threshold) * **ThruPlay** counts views that complete OR reach 15 seconds (whichever comes first) * **Completion metrics** (25%, 50%, 75%, 100%) track viewing depth ThruPlay is Meta's recommended optimization goal for video awareness campaigns. ## Choosing the Right Metric * **Awareness campaigns**: Use ThruPlay as your primary optimization metric * **Content quality**: Compare completion rates (25% → 100%) to identify drop-off points * **Attention span**: Use Average Watch Time to compare video performance * **Cost efficiency**: Track Cost per ThruPlay to optimize delivery efficiency * **Full engagement**: Use Video Completions for videos where the full message matters # Meta Average Watch Time: Measure Video Engagement Duration Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-video/meta-average-watch-time Track average watch time on your Meta video ads. Measure how long viewers engage with your content to optimize video length and improve creative performance. The average time people spent watching your video ads. ## Formula **Meta Average Watch Time** = **Total Watch Time** ÷ **Meta Video Plays** ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | **Total Watch Time** | Cumulative seconds spent watching your video ads across all plays | | [**Meta Video Plays**](/reference/metrics/advertising/meta/meta-video/meta-video-plays) | Total number of times your video ads started playing | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number (seconds) | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Average | *** ## Example Your three video campaigns show **different average watch times** based on content length and engagement: | Campaign | Avg Watch Time | Video Length | Watch Ratio | | --------------- | -------------- | ------------ | ----------- | | Product Teaser | 8.2 seconds | 10 seconds | 82% | | Brand Story | 18.5 seconds | 45 seconds | 41% | | Tutorial Series | 32.4 seconds | 90 seconds | 36% | The Product Teaser retains most viewers, while longer formats show expected drop-off. Average watch time helps you find the optimal video length for your audience. *** ## How It Works Meta tracks how long each viewer watches your video ads and calculates the average across all plays. Higher watch time indicates more engaging video content. This includes partial views—if 100 people play your 30-second video and half leave at 10 seconds while half complete it, your average watch time would be 20 seconds. *** ## When to Use | Scenario | Action | | -------------------------- | ----------------------------------------------------------------- | | Optimizing video length | Compare average watch time to total length to find ideal duration | | Testing hook effectiveness | Low watch time on long videos signals weak opening | | Comparing creative formats | Higher watch time indicates more engaging content style | | Pacing content structure | Place key messages before average drop-off point | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------- | ---------------------------------------------- | | [Meta Video Plays](/reference/metrics/advertising/meta/meta-video/meta-video-plays) | Denominator for average watch time calculation | | [Meta ThruPlay Views](/reference/metrics/advertising/meta/meta-video/meta-thruplay-views) | Videos watched to completion or 15+ seconds | | [Meta Video Completions](/reference/metrics/advertising/meta/meta-video/meta-video-completions) | 100% completion views—highest engagement tier | [See all Meta Video metrics →](/reference/metrics/advertising/meta/meta-video) # Meta Cost per 15-Second View: Deep Engagement Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-video/meta-cost-per-15-sec-view Track Meta Cost per 15-Second Video View to measure your average spend per deeply engaged viewer. Compare against 3-second cost to optimize video ad efficiency. Measures the average cost for each time someone watches your Meta video ad for at least 15 continuous seconds. ## Formula **Meta Cost per 15-Second View** = **Meta Spend** ÷ **Meta 15-Second Video Views** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount billed by Meta for advertising | | [**Meta 15-Second Video Views**](/reference/metrics/advertising/meta/meta-video/meta-video-views-15-sec) | Count of video views watched for at least 15 continuous seconds | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your skincare brand spent **\$3,600** on video campaigns last month and generated **45,000** fifteen-second views. | Campaign | Spend | 15s Views | Cost/15s View | | --------------- | ------- | --------- | ------------- | | Product Demo | \$1,800 | 24,000 | \$0.075 | | Brand Story | \$1,200 | 12,000 | \$0.100 | | Tutorial Series | \$600 | 9,000 | \$0.067 | *** ## How It Works Meta records a 15-second view when someone watches your video ad continuously for at least 15 seconds without skipping. This cost metric divides your spend by these engaged views, giving you the price of meaningful attention rather than just scroll-stopping impressions. *** ## When to Use | Scenario | Action | | ---------------------------- | ------------------------------------------------------------- | | Comparing creative depth | Lower cost per 15s view indicates better sustained engagement | | Optimizing for consideration | Prioritize this over 3s cost when brand messaging needs time | | Evaluating storytelling ads | Track if longer narratives justify higher per-view costs | | Building retargeting pools | Understand cost to acquire high-intent video viewers | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | [Meta 15-Second Video Views](/reference/metrics/advertising/meta/meta-video/meta-video-views-15-sec) | Denominator — the view count used in this cost formula | | [Meta Cost per Video View](/reference/metrics/advertising/meta/meta-video/meta-cost-per-video-view) | Cost per 3-second view for baseline comparison | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Numerator — the total ad spend used in the formula | [See all Meta Video metrics →](/reference/metrics/advertising/meta/meta-video) # Meta Cost per Thruplay: Video View Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-video/meta-cost-per-thruplay Track Meta Cost per Thruplay to measure video campaign efficiency. The standard metric for optimizing video completion campaigns on Meta. Meta Cost per Thruplay measures the average spend for each video watched to completion or for at least 15 seconds—the standard efficiency metric when optimizing for video completion campaigns. ## Formula **Meta Cost per Thruplay** = **Meta Spend** ÷ **Meta Thruplay Views** ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta ads | | [**Meta Thruplay Views**](/reference/metrics/advertising/meta/meta-video/meta-thruplay-views) | Videos watched to completion or for at least 15 seconds | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your video campaign spent **\$2,400** and generated **18,450 Thruplay views**, giving you a Cost per Thruplay of **\$0.13**. | Ad Set | Spend | Thruplay Views | Cost/Thruplay | | ------------ | ------- | -------------- | ------------- | | Product Demo | \$1,200 | 8,200 | \$0.15 | | Brand Story | \$850 | 6,750 | \$0.13 | | Quick Promo | \$350 | 3,500 | \$0.10 | The Quick Promo achieves the lowest cost because shorter videos reach the Thruplay threshold faster. *** ## How It Works Meta Cost per Thruplay divides your total ad spend by the number of Thruplay views. Meta counts a Thruplay when someone watches your video to completion or for at least 15 seconds. Lower costs indicate more efficient delivery and stronger creative resonance with your target audience. *** ## When to Use | Scenario | Action | | ----------------------------- | ---------------------------------------------------- | | Setting video campaign bids | Use as your target cost when optimizing for Thruplay | | Comparing video creatives | Lower Cost/Thruplay indicates more engaging content | | Evaluating audience targeting | Rising costs may signal audience saturation | | Budget allocation | Shift spend toward ad sets with lower Cost/Thruplay | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | [Meta Thruplay Views](/reference/metrics/advertising/meta/meta-video/meta-thruplay-views) | Denominator—total Thruplay views generated | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Numerator—total spend divided by Thruplay views | | [Meta Cost per Video View](/reference/metrics/advertising/meta/meta-video/meta-cost-per-video-view) | Alternative metric—cost per 3-second view (lower threshold) | | [Meta Video Completions](/reference/metrics/advertising/meta/meta-video/meta-video-completions) | Full completions only (stricter than Thruplay) | [See all Meta Video metrics →](/reference/metrics/advertising/meta/meta-video) # Meta Cost per Video Play: Average Spend per Video Initiation Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-video/meta-cost-per-video-play Track cost per video play for Meta ads. Measure average spend per video play initiation, including auto-plays, to optimize video ad efficiency. Meta Cost per Video Play measures the average spend per video play initiation on your Meta ads, including auto-plays. ## Formula **Meta Cost per Video Play** = **Meta Spend** ÷ **Meta Video Plays** ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount spent on Meta advertising campaigns | | [**Meta Video Plays**](/reference/metrics/advertising/meta/meta-video/meta-video-plays) | Number of times your video started playing, including auto-plays | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your video campaign spent **\$2,500** and generated **50,000 video plays**. | Metric | Value | Calculation | | ---------------------------- | ---------- | --------------------- | | Meta Spend | \$2,500 | Total campaign spend | | Meta Video Plays | 50,000 | All video initiations | | **Meta Cost per Video Play** | **\$0.05** | \$2,500 ÷ 50,000 | *** ## How It Works Meta Cost per Video Play divides your total ad spend by the number of video play initiations. This includes both user-initiated plays and auto-plays that occur when videos appear in feed. The metric helps you understand the efficiency of your video content at capturing initial attention. *** ## When to Use | Scenario | Action | | --------------------------------------- | -------------------------------------------------------------- | | Comparing video creative efficiency | Lower cost per play indicates more efficient attention capture | | Budget allocation for video campaigns | Identify which videos deliver plays most cost-effectively | | Benchmarking against industry standards | Track cost per play trends over time | | Optimizing video ad formats | Compare in-feed vs. Stories vs. Reels cost efficiency | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [Meta Video Plays](/reference/metrics/advertising/meta/meta-video/meta-video-plays) | Denominator — total video play initiations | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Numerator — total advertising spend | | [Meta Cost per Video View](/reference/metrics/advertising/meta/meta-video/meta-cost-per-video-view) | Similar metric measuring cost per qualified view | [See all Meta Video metrics →](/reference/metrics/advertising/meta/meta-video) # Meta Cost per Video View: Video Awareness Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-video/meta-cost-per-video-view Track Meta Cost per Video View to measure your average spend per 3-second video view. The standard cost metric for video awareness campaigns on Facebook and Instagram. Meta Cost per Video View measures your average spend for each 3-second video view on your Meta ads. ## Formula **Meta Cost per Video View** = **Meta Spend** ÷ **Meta Video Views** ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | [**Meta Spend**](/reference/metrics/advertising/meta/meta-spend/meta-spend) | Total amount billed by Meta for your advertising | | [**Meta Video Views**](/reference/metrics/advertising/meta/meta-video/meta-video-views) | Number of times your video was watched for at least 3 seconds | | Metadata | | | --------------- | --------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Ratio (Spend ÷ Video Views) | *** ## Example Your skincare brand spent **\$2,400** on video awareness campaigns in March and generated **800,000 video views** across placements. | Placement | Spend | Video Views | Cost/View | | --------------- | ------- | ----------- | --------- | | Instagram Reels | \$1,200 | 480,000 | \$0.0025 | | Facebook Feed | \$800 | 240,000 | \$0.0033 | | Stories | \$400 | 80,000 | \$0.0050 | *** ## How It Works Meta counts a video view when someone watches your ad for at least 3 continuous seconds. Cost per Video View divides your spend by these qualified views, filtering out accidental scrolls and immediate skips. This metric is your primary efficiency measure when optimizing for top-of-funnel video reach and brand awareness. *** ## When to Use | Scenario | Action | | ------------------------------------ | --------------------------------------------------------------------- | | Evaluating video awareness campaigns | Compare cost per view across ad sets to find efficient audiences | | Cost per view rising | Refresh creative or expand targeting to combat ad fatigue | | Comparing to Thruplay cost | Higher Thruplay cost vs. view cost indicates drop-off after 3 seconds | | Planning brand awareness budgets | Use cost per view to forecast reach at different spend levels | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | [Meta Video Views](/reference/metrics/advertising/meta/meta-video/meta-video-views) | The view count used in the Cost per Video View formula | | [Meta Cost per Thruplay](/reference/metrics/advertising/meta/meta-video/meta-cost-per-thruplay) | Cost for deeper engagement—15+ seconds or completion | | [Meta Spend](/reference/metrics/advertising/meta/meta-spend/meta-spend) | The total ad spend used in the formula | [See all Meta Video metrics →](/reference/metrics/advertising/meta/meta-video) # Meta Thruplay: Video Completion Measurement Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-video/meta-thruplay Track Meta Thruplay for video ads. Measure videos watched to completion or for at least 15 seconds—Meta's recommended metric for video campaign optimization. The number of videos watched to completion or for at least 15 seconds—Meta's recommended metric for video campaign optimization. ## Formula **Meta Thruplay** = **COUNT** ( Thruplay Views ) ### Formula Components | Metric | Definition | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------- | | **Thruplay Views** | Individual video views counted when a viewer watches your video to completion or for at least 15 seconds, whichever comes first | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your video ad campaign achieved **8,250 Thruplay views** last week across three creative variants. | Video Creative | Thruplay Views | Video Length | | -------------- | -------------- | ------------ | | Product Demo | 3,840 | 45 seconds | | Customer Story | 2,910 | 28 seconds | | Quick Promo | 1,500 | 12 seconds | The 12-second promo counts completions only since it's under 15 seconds. *** ## How It Works Meta counts a Thruplay when a viewer watches your entire video or at least 15 continuous seconds, whichever comes first. For videos shorter than 15 seconds, the user must complete the full video. This metric provides a more meaningful engagement signal than standard 3-second video views. *** ## When to Use | Scenario | Action | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Optimizing video campaigns | Use Thruplay as your primary optimization event for awareness objectives | | Comparing video creatives | Identify which videos hold viewer attention longest | | Calculating cost efficiency | Pair with [Meta Cost per Thruplay](/reference/metrics/advertising/meta/meta-video/meta-cost-per-thruplay) to evaluate engaged view cost | | Benchmarking engagement | Compare Thruplay against [Meta Video Views 100%](/reference/metrics/advertising/meta/meta-video/meta-video-views-100-percent) for full completion | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | [Meta Thruplay Views](/reference/metrics/advertising/meta/meta-video/meta-thruplay-views) | Same metric with alternate name | | [Meta Cost per Thruplay](/reference/metrics/advertising/meta/meta-video/meta-cost-per-thruplay) | Ad Spend ÷ Thruplay Views—efficiency metric for video spend | | [Meta Video Views 100%](/reference/metrics/advertising/meta/meta-video/meta-video-views-100-percent) | Views where the entire video was watched—stricter completion metric | | [Meta Video Views 15 Sec](/reference/metrics/advertising/meta/meta-video/meta-video-views-15-sec) | Views reaching 15 seconds—component of Thruplay for longer videos | [See all Meta Video metrics →](/reference/metrics/advertising/meta/meta-video) # Meta Thruplay Views: Video Completion Measurement Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-video/meta-thruplay-views Track Meta Thruplay Views for your video ads. Measure completions or 15+ second views to optimize video campaign performance. Meta Thruplay Views counts video views that were either watched to completion or for at least 15 seconds—Meta's recommended metric for video campaign optimization. ## Formula **Meta Thruplay Views** = **COUNT** ( Thruplay Views ) ### Formula Components | Metric | Definition | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------- | | **Thruplay Views** | Individual video views counted when a viewer watches your video to completion or for at least 15 seconds, whichever comes first | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your video ad campaign achieved **12,450 Thruplay Views** last month across three creative variants. | Video Creative | Thruplay Views | Completion Rate | | -------------------- | -------------- | --------------- | | Product Demo (45s) | 5,230 | 42% | | Customer Story (30s) | 4,120 | 55% | | Brand Intro (15s) | 3,100 | 78% | *** ## How It Works Meta counts a Thruplay View when a user watches your video ad to completion OR for at least 15 seconds, whichever occurs first. For videos shorter than 15 seconds, the user must watch the entire video. This metric provides a more meaningful engagement signal than standard video views. *** ## When to Use | Scenario | Action | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | Optimizing video campaigns | Use Thruplay as your primary optimization event for video-focused objectives | | Comparing video creatives | Identify which videos hold viewer attention longest | | Calculating cost efficiency | Pair with [Meta Thruplay Cost](/reference/metrics/advertising/meta/meta-video/meta-thruplay-cost) to evaluate cost per engaged view | | Benchmarking engagement | Compare Thruplay rate against [Meta 100% Watched](/reference/metrics/advertising/meta/meta-video/meta-video-p100-watched) for full completion insights | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | [Meta Thruplay Cost](/reference/metrics/advertising/meta/meta-video/meta-thruplay-cost) | Cost per Thruplay View—efficiency metric for video spend | | [Meta 100% Watched](/reference/metrics/advertising/meta/meta-video/meta-video-p100-watched) | Views where the entire video was watched—stricter completion metric | | [Meta 15 Second Views](/reference/metrics/advertising/meta/meta-video/meta-video-views-15-sec) | Views reaching 15 seconds—component of Thruplay for longer videos | [See all Meta Video metrics →](/reference/metrics/advertising/meta/meta-video) # Meta Video Completions: Full Video Watch Metric Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-video/meta-video-completions Meta Video Completions count views where your entire video ad was watched from start to finish. The strongest video engagement signal for evaluating content. The number of times your video ads were watched to 100% completion. ## Formula **Meta Video Completions** = **COUNT** ( Video Completions ) ### Formula Components | Metric | Definition | | --------------------- | ------------------------------------------------------------------------------------------------- | | **Video Completions** | Individual instances where a viewer watched your entire video ad from the first frame to the last | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your brand story campaign generated **4,250 video completions** across three video lengths: | Video | Length | Completions | Completion Rate | | -------------------- | ------ | ----------- | --------------- | | Customer Testimonial | 28 sec | 2,100 | 18.2% | | Product Tutorial | 45 sec | 1,450 | 12.8% | | Brand Documentary | 90 sec | 700 | 6.1% | Shorter videos typically see higher completion rates, but completions on longer content signal deeper engagement. *** ## How It Works Meta registers a video completion when someone watches your entire video ad from start to finish. This is the strictest engagement metric—viewers who reach 100% have seen your complete message. Completions are especially valuable for videos with calls-to-action or key information at the end. *** ## When to Use | Scenario | Action | | ------------------------------ | -------------------------------------------------------- | | Evaluating message delivery | High completions mean viewers saw your full story | | Testing video length | Compare completion rates across different durations | | Identifying engaging content | Videos with high completions resonate with your audience | | Building retargeting audiences | Target users who completed videos for warm leads | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | [Meta Thruplay Views](/reference/metrics/advertising/meta/meta-video/meta-thruplay-views) | Completions or 15+ second views—Meta's recommended video optimization metric | | [Meta Video 75% Views](/reference/metrics/advertising/meta/meta-video/meta-video-views-75-percent) | Near-completions—viewers who watched most of your video | | [Meta Video Views](/reference/metrics/advertising/meta/meta-video/meta-video-views) | 3-second views—top of the video engagement funnel | [See all Meta Video metrics →](/reference/metrics/advertising/meta/meta-video) # Meta Video Plays: Track Video Starts on Your Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-video/meta-video-plays Track how many times your Meta video ads started playing, including auto-plays. Compare plays to views to measure engagement and creative performance. The total number of times your Meta video ads started playing, including auto-plays. ## Formula **Meta Video Plays** = **COUNT** ( Video Plays ) ### Formula Components | Metric | Definition | | --------------- | --------------------------------------------------------------------------------------- | | **Video Plays** | Each instance a video ad started playing, whether auto-played in feed or user-initiated | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your video campaign generated **142,800 plays** across three ad sets this week: | Ad Set | Plays | Views | Play-to-View Rate | | ------------ | ------ | ------ | ----------------- | | Lifestyle | 68,400 | 52,100 | 76% | | Product Demo | 51,200 | 41,000 | 80% | | Testimonial | 23,200 | 16,500 | 71% | *** ## How It Works Video Plays counts every time your video starts playing, including auto-plays as users scroll through their feed. This number is typically higher than Video Views because Meta only counts a "view" after 3+ seconds of watch time. The gap between plays and views reveals how many people scrolled past immediately. *** ## When to Use | Scenario | Action | | ----------------------------- | ------------------------------------------------- | | Measuring initial exposure | Track raw video starts across campaigns | | Diagnosing drop-off | Compare plays to views to find early abandonment | | Evaluating hook effectiveness | Low play-to-view rate suggests weak opening | | Optimizing cost efficiency | Divide spend by plays to find cost per video play | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------- | ----------------------------------------- | | [Meta Cost per Video Play](/reference/metrics/advertising/meta/meta-video/meta-cost-per-video-play) | Ad Spend ÷ Video Plays | | [Meta Video Views](/reference/metrics/advertising/meta/meta-video/meta-video-views) | Plays that reached the 3-second threshold | [See all Meta Video metrics →](/reference/metrics/advertising/meta/meta-video) # Meta Video Views: Measure Video Ad Engagement Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-video/meta-video-views Track how many times your Meta video ads were watched for at least 3 seconds. Evaluate creative performance and optimize video campaigns. Meta Video Views counts how many times your video ad was watched for at least 3 seconds—Meta's default view threshold. ## Formula **Meta Video Views** = **COUNT** ( 3-Second Video Views ) ### Formula Components | Metric | Definition | | ------------------------ | -------------------------------------------------------------------- | | **3-Second Video Views** | Video plays where the user watched for at least 3 continuous seconds | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your product demo campaign generated **125,000 video views** across Instagram and Facebook last month. | Placement | Video Views | Video Plays | View Rate | | --------------- | ----------- | ----------- | --------- | | Instagram Reels | 72,000 | 95,000 | 75.8% | | Facebook Feed | 38,000 | 52,000 | 73.1% | | Stories | 15,000 | 28,000 | 53.6% | *** ## How It Works Meta registers a video view when a user watches your ad for at least 3 continuous seconds. This threshold filters out accidental scrolls and auto-play skips, giving you a cleaner signal of intentional engagement. Views are counted across Facebook, Instagram, Messenger, and the Audience Network. *** ## When to Use | Scenario | Action | | ------------------------------------ | -------------------------------------------------------- | | Comparing video creative performance | Higher view counts signal more engaging content | | Evaluating audience targeting | Low views relative to plays indicates targeting mismatch | | Measuring brand awareness lift | Track views alongside reach for exposure metrics | | Optimizing cost efficiency | Compare cost per view across ad sets | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [Meta Cost per Video View](/reference/metrics/advertising/meta/meta-video/meta-cost-per-video-view) | Spend efficiency—how much each 3-second view costs | | [Meta Video Plays](/reference/metrics/advertising/meta/meta-video/meta-video-plays) | Total plays including auto-play—always higher than views | | [Meta Thruplay Views](/reference/metrics/advertising/meta/meta-video/meta-thruplay-views) | Videos watched to completion or 15+ seconds | [See all Meta Video metrics →](/reference/metrics/advertising/meta/meta-video) # Meta Video 100% Views: Complete Video Engagement Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-video/meta-video-views-100-percent Track Meta video ads watched to 100% completion. Measure your strongest video engagement signal and optimize creative performance. Meta Video 100% Views measures the number of times your video ads were watched to complete 100% of their duration. ## Formula **Meta Video 100% Views** = **COUNT** ( 100% Completion Views ) ### Formula Components | Metric | Definition | | ------------------------- | ---------------------------------------------------------------------------------------- | | **100% Completion Views** | The raw count of video plays where viewers watched the entire video from start to finish | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example A sportswear brand runs a 30-second product video campaign across Meta platforms. | Ad Creative | Total Plays | 100% Views | Completion Rate | | ------------- | ----------- | ---------- | --------------- | | Product Demo | 15,000 | 2,250 | 15% | | Athlete Story | 12,500 | 3,750 | 30% | | Quick Cuts | 20,000 | 1,800 | 9% | The "Athlete Story" creative drives 67% more complete views than "Product Demo" despite fewer total plays—indicating stronger engagement with narrative content. *** ## How It Works Meta counts a 100% view when a user watches your entire video from the first frame to the last. Unlike ThruPlay (15 seconds or completion), this metric requires full video consumption. It represents the highest intent signal for video creative performance. *** ## When to Use | Scenario | Action | | -------------------------------- | -------------------------------------------------------------- | | Comparing creative performance | Identify which videos hold attention to completion | | Measuring brand awareness impact | Complete views indicate strong message delivery | | Optimizing video length | High completion rates on longer videos signal engaging content | | Evaluating audience targeting | Low completion rates may indicate audience-content mismatch | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [Meta Video 95% Views](/reference/metrics/advertising/meta/meta-video/meta-video-views-95-percent) | Near-complete views—useful when 100% is too strict | | [Meta ThruPlay Views](/reference/metrics/advertising/meta/meta-video/meta-video-views-thruplay) | Meta's standard video metric (15s or completion) | | [Meta Video Views](/reference/metrics/advertising/meta/meta-video/meta-video-views) | 3-second views—top-of-funnel video engagement | [See all Meta Video metrics →](/reference/metrics/advertising/meta/meta-video) # Meta 15-Second Video Views: Measure Deep Video Engagement Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-video/meta-video-views-15-sec Track Meta video ads watched for at least 15 seconds to measure deeper viewer engagement beyond the 3-second threshold. Counts how many times your Meta video ads were watched for at least 15 continuous seconds. ## Formula **Meta 15-Second Video Views** = **COUNT** ( 15-Second Video Views ) ### Formula Components | Metric | Definition | | ------------------------- | -------------------------------------------------------------------------------------------------------- | | **15-Second Video Views** | Individual video views counted when a viewer watches your video ad for at least 15 uninterrupted seconds | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your skincare brand ran a 30-second product demo video ad last week, generating **18,450** fifteen-second views. | Ad Creative | 15s Views | 3s Views | Retention | | --------------- | --------- | -------- | --------- | | Product Demo | 18,450 | 42,000 | 44% | | Testimonial | 12,300 | 38,500 | 32% | | How-To Tutorial | 24,100 | 48,200 | 50% | *** ## How It Works Meta records a 15-second view whenever a viewer watches your video ad continuously for at least 15 seconds without skipping. This threshold indicates stronger intent than the standard 3-second view metric, as viewers have invested meaningful attention in your content. *** ## When to Use | Scenario | Action | | ------------------------------ | ------------------------------------------------------------- | | Evaluating creative quality | Compare 15s views across ad variants to find engaging content | | Measuring brand storytelling | Track if viewers watch long enough to absorb your message | | Building retargeting audiences | Use 15s viewers as a higher-intent audience segment | | Optimizing video length | Analyze where viewers drop off between 3s and 15s | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | [Meta Cost per 15-Second View](/reference/metrics/advertising/meta/meta-video/meta-cost-per-15-sec-view) | Cost efficiency of driving 15-second views | | [Meta Video Views](/reference/metrics/advertising/meta/meta-video/meta-video-views) | Total 3-second views for baseline comparison | | [Meta Thruplay Views](/reference/metrics/advertising/meta/meta-video/meta-thruplay-views) | Views watched to completion or 15+ seconds | [See all Meta Video metrics →](/reference/metrics/advertising/meta/meta-video) # Meta Video 25% Views: Track Early Video Engagement Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-video/meta-video-views-25-percent Track how many viewers watched at least 25% of your Meta video ads. Identify early drop-off points and optimize video creative for better retention. The number of times your video ads were watched to at least 25% completion—part of the video completion rate funnel. ## Formula **Meta Video 25% Views** = **COUNT** ( 25% Completion Views ) ### Formula Components | Metric | Definition | | ------------------------ | -------------------------------------------------------------------------- | | **25% Completion Views** | Each instance where a viewer watches at least one quarter of your video ad | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your skincare brand ran a 60-second product demo video ad last week. Here's the completion breakdown: | Video | Impressions | 25% Views | 25% View Rate | | --------------- | ----------- | --------- | ------------- | | Product Demo | 45,000 | 12,150 | 27% | | How-To Tutorial | 38,000 | 15,200 | 40% | | Brand Story | 52,000 | 9,360 | 18% | The tutorial captures attention better in the first 15 seconds, while the brand story loses viewers early. *** ## How It Works Meta fires a 25% completion event when a viewer watches at least one quarter of your video's total duration. For a 60-second video, this means watching at least 15 seconds. This metric counts each qualifying view, including repeat views from the same person. *** ## When to Use | Scenario | Action | | ------------------------------------ | ------------------------------------------------------- | | High impressions but low 25% views | Improve your video hook in the first 3-5 seconds | | Comparing creative variations | Identify which opening sequences retain viewers best | | Building video remarketing audiences | Target users who reached 25%+ for mid-funnel ads | | Diagnosing funnel drop-off | Compare 25% to 50%/75%/100% to find where viewers leave | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | [Meta Video 50% Views](/reference/metrics/advertising/meta/meta-video/meta-video-views-50-percent) | Next milestone in the video completion funnel | | [Meta Video Views](/reference/metrics/advertising/meta/meta-video/meta-video-views) | Base 3-second view count—always higher than 25% views | | [Meta Video Completions](/reference/metrics/advertising/meta/meta-video/meta-video-completions) | Viewers who watched your entire video | [See all Meta Video metrics →](/reference/metrics/advertising/meta/meta-video) # Meta Video 50% Views: Measure Mid-Video Engagement Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-video/meta-video-views-50-percent Track how many viewers watched at least half of your Meta video ads. A key milestone for measuring message delivery and evaluating creative effectiveness. The number of times your video ads were watched to at least 50% completion—indicates moderate viewing engagement. ## Formula **Meta Video 50% Views** = **COUNT** ( 50% Completion Views ) ### Formula Components | Metric | Definition | | ------------------------ | ------------------------------------------------------------------- | | **50% Completion Views** | Each instance where a viewer watches at least half of your video ad | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your fitness brand ran a 40-second workout preview across three ad sets last week. Here's how viewers progressed through each video: | Ad Set | Impressions | 50% Views | 50% View Rate | | --------------- | ----------- | --------- | ------------- | | Morning Routine | 62,000 | 18,600 | 30% | | HIIT Preview | 48,000 | 20,160 | 42% | | Recovery Tips | 55,000 | 11,000 | 20% | The HIIT preview maintains viewer attention through the midpoint, while Recovery Tips needs a stronger narrative hook. *** ## How It Works Meta fires a 50% completion event when a viewer watches at least half of your video's total duration. For a 40-second video, this means watching at least 20 seconds. This metric counts each qualifying view, including repeat views from the same person. *** ## When to Use | Scenario | Action | | ----------------------------------- | -------------------------------------------------------- | | Strong 25% but weak 50% views | Your middle content loses viewers—tighten the narrative | | Comparing video lengths | Shorter videos often have higher 50% rates; test formats | | Building warm remarketing audiences | Target 50%+ viewers for bottom-funnel conversion ads | | Evaluating message delivery | 50% completion means your core message likely landed | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | [Meta Video 25% Views](/reference/metrics/advertising/meta/meta-video/meta-video-views-25-percent) | Earlier funnel stage showing initial hook effectiveness | | [Meta Video 75% Views](/reference/metrics/advertising/meta/meta-video/meta-video-views-75-percent) | Next milestone showing strong content retention | | [Meta Video Completions](/reference/metrics/advertising/meta/meta-video/meta-video-completions) | Viewers who watched your entire video | [See all Meta Video metrics →](/reference/metrics/advertising/meta/meta-video) # Meta Video 75% Views: Measure Deep Video Engagement Source: https://docs.upstackdata.com/reference/metrics/advertising/meta/meta-video/meta-video-views-75-percent Track how many viewers watched three-quarters of your Meta video ads. Identify highly engaged audiences and optimize video creative for retention. The number of times your video ads were watched to at least 75% completion—signals strong content retention. ## Formula **Meta Video 75% Views** = **COUNT** ( 75% Completion Views ) ### Formula Components | Metric | Definition | | ------------------------ | ----------------------------------------------------------------------------- | | **75% Completion Views** | Each instance where a viewer watches at least three-quarters of your video ad | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Sum | *** ## Example Your skincare brand ran video ads in May showing product application tutorials. **12,847 viewers watched to 75% completion**. | Campaign | 25% Views | 50% Views | 75% Views | Completions | | --------------- | --------- | --------- | --------- | ----------- | | Tutorial Series | 45,200 | 28,100 | 12,847 | 8,920 | | Product Demo | 32,100 | 18,400 | 7,650 | 4,210 | | Brand Story | 28,500 | 12,300 | 4,120 | 2,180 | *** ## How It Works Meta tracks video watch progress and fires a 75% completion event when a viewer reaches three-quarters of your video's duration. For a 60-second video, this means watching at least 45 seconds. This threshold filters out casual scrollers, capturing viewers who demonstrated genuine interest in your content. *** ## When to Use | Scenario | Action | | --------------------------------- | --------------------------------------------------------------------- | | Evaluating video creative quality | Compare 75% rates across videos to find formats that hold attention | | Building retargeting audiences | Target 75% viewers for bottom-funnel campaigns—they're highly engaged | | Optimizing video length | Low 75% rates may signal videos are too long for the platform | | Measuring brand storytelling | Use for brand awareness videos where message delivery matters | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | [Meta Video 50% Views](/reference/metrics/advertising/meta/meta-video/meta-video-views-50-percent) | Earlier milestone—compare drop-off between 50% and 75% | | [Meta Video Completions](/reference/metrics/advertising/meta/meta-video/meta-video-completions) | Final milestone—100% completion for full message delivery | | [Meta Video 25% Views](/reference/metrics/advertising/meta/meta-video/meta-video-views-25-percent) | Initial hook effectiveness—measures early attention capture | [See all Meta Video metrics →](/reference/metrics/advertising/meta/meta-video) # TikTok Ads Metrics Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/index Measure TikTok advertising performance with metrics for spend, conversions, video engagement, and ROI. TikTok Ads metrics help you understand how your TikTok advertising campaigns drive engagement, video views, and conversions. ## Metric Categories | Category | Description | Key Metrics | | ------------------------------------------------------------------------------ | ----------------------------------------------------- | --------------------------------------------- | | [TikTok Spend](/reference/metrics/advertising/tiktok/tiktok-spend) | Track your TikTok advertising investment | Ad Spend | | [TikTok Efficiency](/reference/metrics/advertising/tiktok/tiktok-efficiency) | Measure return on ad spend and cost efficiency | ROAS, CPA | | [TikTok Audience](/reference/metrics/advertising/tiktok/tiktok-audience) | Understand ad reach and impression costs | Impressions, CPM | | [TikTok Clicks](/reference/metrics/advertising/tiktok/tiktok-clicks) | Analyze click performance and landing page engagement | Clicks, CPC, CTR, Landing Page Views | | [TikTok Video](/reference/metrics/advertising/tiktok/tiktok-video) | Track video ad performance and completion rates | Video Views, Watch Time, Completion Rate | | [TikTok Conversions](/reference/metrics/advertising/tiktok/tiktok-conversions) | Measure conversion actions and their costs | Purchases, Add to Carts, Leads, Registrations | | [TikTok Engagement](/reference/metrics/advertising/tiktok/tiktok-engagement) | Track social engagement with your ads | Likes, Comments, Shares, Follows | ## TikTok-Specific Features TikTok provides unique metrics for video-first advertising: * **Video completion metrics**: Track 25%, 50%, 75%, and 100% watch rates * **6-second and 15-second view benchmarks**: Industry-standard video engagement thresholds * **Social engagement**: Native metrics for likes, comments, shares, and follows * **Profile visits**: Track how ads drive traffic to your TikTok profile ## Data Source All TikTok Ads metrics are sourced from the [TikTok Ads Manager API](/sources/tiktok), synchronized daily with your Upstack dashboard. # TikTok Audience: Reach and Impression Metrics Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-audience/index Track TikTok ad reach metrics including impressions and CPM. Understand how many people see your TikTok ads and the cost to reach them. Audience metrics measure how many times your TikTok ads are shown and the cost efficiency of reaching your audience. **Data Source:** [TikTok Ads](/sources/tiktok)\ **Metrics:** 2 ## Metrics in This Group | Metric | Description | When to Use | | ---------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------- | | [TikTok Impressions](/reference/metrics/advertising/tiktok/tiktok-audience/tiktok-impressions) | Number of times ads were displayed | Measure ad exposure | | [TikTok CPM](/reference/metrics/advertising/tiktok/tiktok-audience/tiktok-cpm) | Cost per 1,000 impressions | Evaluate reach efficiency | ## How These Metrics Relate * **TikTok Impressions** counts every time your ad appears on screen * **TikTok CPM** = (TikTok Ad Spend ÷ TikTok Impressions) × 1,000 CPM depends on: * [TikTok Ad Spend](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) — total cost * TikTok Impressions — total ad views ## Choosing the Right Metric * **Awareness campaigns**: Use Impressions to measure total exposure * **Budget efficiency**: Use CPM to compare cost of reach across campaigns * **Audience targeting**: Lower CPM with maintained CTR indicates efficient targeting # TikTok CPM: Cost Per 1,000 Impressions Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-audience/tiktok-cpm Track how much you pay for every 1,000 TikTok ad impressions. Lower CPM means cheaper reach to your target audience. TikTok CPM measures how much you pay for every 1,000 times your ad is shown — lower CPM means cheaper impressions. ## Formula **TikTok CPM** = **TikTok Spend** ÷ **TikTok Impressions** × 1,000 ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------- | -------------------------------------- | | [**TikTok Spend**](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on TikTok ads | | [**TikTok Impressions**](/reference/metrics/advertising/tiktok/tiktok-audience/tiktok-impressions) | Number of times ads appeared on screen | || Metadata | | ||---|---| || **Type** | Currency | || **Data Source** | [TikTok Ads](/sources/tiktok) | || **Aggregation** | Ratio | *** ## Example Your TikTok campaign spent **\$5,000** and delivered **1,250,000 impressions** last month. | Metric | Value | | ------------------ | ---------- | | TikTok Spend | \$5,000 | | TikTok Impressions | 1,250,000 | | **TikTok CPM** | **\$4.00** | Calculation: \$5,000 ÷ 1,250,000 × 1,000 = **\$4.00 CPM** *** ## How It Works CPM divides your total ad spend by the number of impressions, then multiplies by 1,000 to express cost per thousand views. TikTok CPM varies by audience competitiveness, ad placement, time of year, and creative quality. Broader targeting typically yields lower CPMs while niche audiences cost more. *** ## When to Use | Scenario | Action | | ------------------------------------ | ----------------------------------------------------------------------------------- | | Comparing reach efficiency | Lower CPM means you're reaching more people for the same budget | | Evaluating audience targeting | Narrow audiences often have higher CPMs — assess if the precision is worth the cost | | Seasonal budget planning | CPMs rise during peak seasons (holidays, events) — plan accordingly | | Benchmarking against other platforms | Compare TikTok CPM to Meta or Google to allocate budget efficiently | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------- | --------------------------------------------------- | | [TikTok Impressions](/reference/metrics/advertising/tiktok/tiktok-audience/tiktok-impressions) | Denominator in CPM calculation — total ad views | | [TikTok Spend](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Numerator in CPM calculation — total cost | | [TikTok CPC](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-cpc) | Cost per click — efficiency metric for engagement | | [TikTok CTR](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-ctr) | Click-through rate — measures ad engagement quality | [See all TikTok Audience metrics →](/reference/metrics/advertising/tiktok/tiktok-audience) # TikTok Impressions: Ad Views on TikTok Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-audience/tiktok-impressions Track how many times your TikTok ads appeared on screen. Monitor ad visibility and reach to optimize campaign delivery. TikTok Impressions measures how many times your ads appeared on screen — the same viewer can account for multiple impressions. ## Formula **TikTok Impressions** = **SUM** ( Ad Impressions ) **FROM** TikTok Ads || Metadata | | ||---|---| || **Type** | Number | || **Data Source** | [TikTok Ads](/sources/tiktok) | || **Aggregation** | Sum | *** ## Example Your TikTok campaign delivered **2.4 million impressions** last week across three ad groups. | Ad Group | Impressions | Spend | CPM | | ---------- | ------------- | ------------ | ---------- | | Awareness | 1,200,000 | \$4,800 | \$4.00 | | Engagement | 850,000 | \$3,825 | \$4.50 | | Conversion | 350,000 | \$1,925 | \$5.50 | | **Total** | **2,400,000** | **\$10,550** | **\$4.40** | *** ## How It Works TikTok counts an impression each time your ad appears on a user's screen. This includes feed ads, in-stream ads, and TopView placements. The same user can generate multiple impressions if they see your ad more than once. *** ## When to Use | Scenario | Action | | ------------------------------ | ---------------------------------------------------------------------- | | Measuring brand awareness | Track impression volume to gauge how many eyes see your ads | | Diagnosing delivery issues | Low impressions with sufficient budget may indicate targeting problems | | Calculating efficiency metrics | Use as denominator for CPM and CTR calculations | | Comparing ad group performance | Identify which audiences generate the most ad views | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------- | ----------------------------------------------------------- | | [TikTok CPM](/reference/metrics/advertising/tiktok/tiktok-audience/tiktok-cpm) | Cost per 1,000 impressions — measures impression efficiency | | [TikTok Spend](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total cost to generate these impressions | | [TikTok CTR](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-ctr) | Percentage of impressions that resulted in clicks | [See all TikTok Audience metrics →](/reference/metrics/advertising/tiktok/tiktok-audience) # TikTok Clicks: Click Performance and Landing Page Metrics Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-clicks/index Track TikTok click metrics including clicks, CPC, CTR, and landing page views. Measure ad engagement and traffic generation from TikTok campaigns. Click metrics measure how users engage with your TikTok ads through clicks and landing page interactions. Use these to evaluate creative performance and traffic generation. **Data Source:** [TikTok Ads](/sources/tiktok)\ **Metrics:** 6 ## Metrics in This Group | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------- | | [TikTok Total Clicks](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-clicks) | Total clicks on ads | Measure overall engagement | | [TikTok CPC](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-cpc) | Cost per click (Spend ÷ Clicks) | Evaluate click efficiency | | [TikTok CTR](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-ctr) | Click-through rate (Clicks ÷ Impressions) | Compare creative performance | | [TikTok Landing Page Views](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-landing-page-views) | Clicks that loaded your landing page | Measure actual site visits | | [TikTok Cost per LP View](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-landing-page-views-cost) | Cost per landing page view | Evaluate traffic cost | | [TikTok LP View Rate](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-landing-page-view-rate) | Percentage of clicks that loaded page | Identify landing page issues | ## How These Metrics Relate Click metrics form a funnel from impressions to site visits: 1. **TikTok Impressions** → Users see your ad 2. **TikTok Total Clicks** → Users click your ad 3. **TikTok Landing Page Views** → Users' browsers load your page Calculated metrics: * **TikTok CTR** = Clicks ÷ Impressions × 100 * **TikTok CPC** = Spend ÷ Clicks * **TikTok LP View Rate** = Landing Page Views ÷ Clicks × 100 ## Choosing the Right Metric * **Engagement analysis**: Use Clicks and CTR to measure ad appeal * **Traffic campaigns**: Use Landing Page Views for actual site visits * **Cost analysis**: Use CPC and Cost per LP View to evaluate traffic cost * **Page performance**: Low LP View Rate indicates slow pages or bounce issues # TikTok Clicks: Total Clicks on Your TikTok Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-clicks Track total clicks on your TikTok ads including destination clicks and other interactions. Measure ad engagement and traffic volume. TikTok Clicks measures the total number of clicks on your TikTok ads, including destination clicks and other interactions. ## Formula **TikTok Clicks** = **SUM** ( Clicks ) **FROM** TikTok Ads | Metadata | | | --------------- | ----------------------------- | | **Type** | Number | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your TikTok campaign received **18,500 clicks** in March across all ad groups: | Ad Group | Clicks | % of Total | | ----------- | ---------- | ---------- | | Prospecting | 11,100 | 60% | | Retargeting | 5,550 | 30% | | Lookalike | 1,850 | 10% | | **Total** | **18,500** | **100%** | *** ## How It Works TikTok Clicks counts every interaction that registers as a click on your ad. This includes taps on the call-to-action button, profile visits, and destination clicks that send users to your website or app. The metric updates in near real-time as TikTok processes ad engagement data. *** ## When to Use | Scenario | Action | | -------------------- | ---------------------------------------------------------- | | Measuring engagement | Track clicks to gauge audience interest in your creative | | Calculating CPC | Use clicks as the denominator to determine cost efficiency | | Comparing ad sets | Identify which targeting or creative drives more clicks | | Forecasting traffic | Estimate website visitors based on historical click rates | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | [TikTok CPC](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-cpc) | Cost efficiency — spend divided by clicks | | [TikTok CTR](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-ctr) | Click rate — clicks divided by impressions | | [TikTok Landing Page Views](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-landing-page-views) | Clicks that fully loaded your page | [See all TikTok Clicks metrics →](/reference/metrics/advertising/tiktok/tiktok-clicks) # TikTok CPC: Average Cost Per Click on TikTok Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-cpc Track your average cost per click on TikTok ads. Lower CPC means you are driving traffic more efficiently. Optimize ad spend allocation. TikTok CPC measures the average cost each time someone clicks your TikTok ad. Lower CPC means you are driving traffic more efficiently. ## Formula **TikTok CPC** = **TikTok Spend** ÷ **TikTok Clicks** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------- | -------------------------------- | | [**TikTok Spend**](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on TikTok ads | | [**TikTok Clicks**](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-clicks) | Total clicks on your TikTok ads | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your brand spent **\$4,500** on TikTok ads in February and received **15,000 clicks**: | Ad Group | Spend | Clicks | CPC | | ----------- | ----------- | ---------- | ---------- | | Prospecting | \$2,250 | 9,000 | \$0.25 | | Retargeting | \$1,500 | 4,500 | \$0.33 | | Lookalike | \$750 | 1,500 | \$0.50 | | **Total** | **\$4,500** | **15,000** | **\$0.30** | *** ## How It Works TikTok CPC divides your total TikTok ad spend by the number of clicks received. This weighted average reflects your true cost to drive one click across all campaigns. A lower CPC indicates more efficient traffic acquisition, though click quality and conversion rate matter more than raw click cost. *** ## When to Use | Scenario | Action | | --------------------- | ---------------------------------------------------- | | Budget planning | Estimate clicks you can generate from a given budget | | Creative testing | Compare CPC across ad variations to find winners | | Platform comparison | Benchmark TikTok CPC against Meta or Google | | Optimization triggers | Pause or adjust campaigns with rising CPC | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------- | ------------------------------------------------------- | | [TikTok Spend](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Numerator — total cost of TikTok ads | | [TikTok Clicks](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-clicks) | Denominator — total clicks received | | [TikTok CTR](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-ctr) | Click rate — higher CTR often correlates with lower CPC | [See all TikTok Clicks metrics →](/reference/metrics/advertising/tiktok/tiktok-clicks) # TikTok CTR: Click-Through Rate on TikTok Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-ctr Track how often people click your TikTok ad after seeing it. Higher CTR signals more engaging creative or targeting. Optimize ad performance. TikTok CTR measures how often people click your ad after seeing it. Higher CTR signals more engaging creative or targeting. ## Formula **TikTok CTR** = ( **TikTok Clicks** ÷ **TikTok Impressions** ) × 100 ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------- | -------------------------------------- | | [**TikTok Clicks**](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-clicks) | Total clicks on your TikTok ads | | [**TikTok Impressions**](/reference/metrics/advertising/tiktok/tiktok-audience/tiktok-impressions) | Total times your TikTok ads were shown | | Metadata | | | --------------- | ----------------------------- | | **Type** | Percentage | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your TikTok campaign received **25,000 clicks** from **1,250,000 impressions** in January: | Ad Group | Impressions | Clicks | CTR | | ----------- | ------------- | ---------- | --------- | | Prospecting | 750,000 | 12,000 | 1.60% | | Retargeting | 300,000 | 9,000 | 3.00% | | Lookalike | 200,000 | 4,000 | 2.00% | | **Total** | **1,250,000** | **25,000** | **2.00%** | *** ## How It Works TikTok CTR divides clicks by impressions and multiplies by 100 to express the result as a percentage. A 2% CTR means 2 out of every 100 people who saw your ad clicked on it. CTR reflects how compelling your creative and targeting are—higher rates typically indicate stronger audience resonance. *** ## When to Use | Scenario | Action | | --------------------- | ------------------------------------------------------- | | Creative testing | Compare CTR across video variations to identify winners | | Audience quality | Higher CTR suggests better targeting alignment | | Platform benchmarking | Compare TikTok CTR to other channels | | Performance diagnosis | Declining CTR may signal creative fatigue | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------- | -------------------------------------------- | | [TikTok Clicks](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-clicks) | Numerator — total clicks on ads | | [TikTok Impressions](/reference/metrics/advertising/tiktok/tiktok-audience/tiktok-impressions) | Denominator — total ad views | | [TikTok CPC](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-cpc) | Cost per click — higher CTR often lowers CPC | [See all TikTok Clicks metrics →](/reference/metrics/advertising/tiktok/tiktok-clicks) # TikTok Landing Page View Rate: Click-to-Page-Load Conversion Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-landing-page-view-rate Track the share of clicks that actually loaded your landing page. Low rates suggest slow load times or bounce issues. Optimize page performance. TikTok Landing Page View Rate measures the share of clicks that actually loaded your landing page. Low rates suggest slow load times or bounce issues. ## Formula **TikTok LP View Rate** = ( **TikTok Landing Page Views** ÷ **TikTok Clicks** ) × 100 ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | [**TikTok Landing Page Views**](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-landing-page-views) | Total landing page loads from TikTok ads | | [**TikTok Clicks**](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-clicks) | Total clicks on your TikTok ads | | Metadata | | | --------------- | ----------------------------- | | **Type** | Percentage | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your TikTok campaign received **20,000 clicks** and **16,000 landing page views** in January: | Ad Group | Clicks | LP Views | LP View Rate | | ----------- | ---------- | ---------- | ------------ | | Prospecting | 12,000 | 9,600 | 80% | | Retargeting | 6,000 | 4,800 | 80% | | Lookalike | 2,000 | 1,600 | 80% | | **Total** | **20,000** | **16,000** | **80%** | *** ## How It Works TikTok Landing Page View Rate divides landing page views by clicks and expresses the result as a percentage. An 80% rate means 80 out of every 100 clicks resulted in a fully loaded page. The remaining 20% bounced before the page finished loading—often due to slow page speeds, poor mobile experience, or users abandoning before load completion. *** ## When to Use | Scenario | Action | | ------------------------ | ------------------------------------------------- | | Page speed diagnosis | Rates below 70% suggest critical load time issues | | Mobile optimization | Compare rates between mobile and desktop traffic | | Landing page testing | Measure which pages retain more clickers | | Campaign troubleshooting | Identify ad sets with unusually low load rates | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | [TikTok Landing Page Views](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-landing-page-views) | Numerator — completed page loads | | [TikTok Clicks](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-clicks) | Denominator — total ad clicks | | [TikTok Cost per LP View](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-landing-page-views-cost) | Cost efficiency — affected by this rate | [See all TikTok Clicks metrics →](/reference/metrics/advertising/tiktok/tiktok-clicks) # TikTok Landing Page Views: Completed Page Loads from TikTok Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-landing-page-views Track how many times your landing page fully loaded after a TikTok ad click. Lower than clicks indicates drop-off before the page loaded. TikTok Landing Page Views measures how many times your landing page fully loaded after a click. Lower than clicks indicates drop-off before the page loaded. ## Formula **TikTok Landing Page Views** = **SUM** ( Landing Page Views ) **FROM** TikTok Ads | Metadata | | | --------------- | ----------------------------- | | **Type** | Number | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your TikTok campaign received **12,000 clicks** but only **9,600 landing page views** in March: | Ad Group | Clicks | LP Views | Drop-off | | ----------- | ---------- | --------- | -------- | | Prospecting | 7,200 | 5,760 | 20% | | Retargeting | 3,600 | 2,880 | 20% | | Lookalike | 1,200 | 960 | 20% | | **Total** | **12,000** | **9,600** | **20%** | *** ## How It Works TikTok Landing Page Views counts clicks that result in a fully loaded landing page. Unlike total clicks, this metric only fires when your page loads completely. The gap between clicks and landing page views reveals bounce and load-time issues—a significant drop-off suggests slow page speeds or mobile optimization problems. *** ## When to Use | Scenario | Action | | -------------------- | ------------------------------------------------------- | | Page speed diagnosis | Large click-to-LP-view gap indicates slow load times | | Mobile optimization | Check if mobile landing pages load properly | | Traffic quality | Use LP views instead of clicks for cleaner traffic data | | Campaign comparison | Identify which ad sets deliver actual site visitors | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | [TikTok Clicks](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-clicks) | Total clicks — LP views should be close to this | | [TikTok Cost per LP View](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-landing-page-views-cost) | Cost efficiency for actual page loads | | [TikTok LP View Rate](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-landing-page-view-rate) | Percentage of clicks that loaded the page | [See all TikTok Clicks metrics →](/reference/metrics/advertising/tiktok/tiktok-clicks) # TikTok Cost per Landing Page View: Cost for Completed Page Loads Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-landing-page-views-cost Track average spend per landing page load from TikTok ads. A more reliable traffic metric than clicks alone. Optimize ad spend efficiency. TikTok Cost per Landing Page View measures the average spend per landing page load. A more reliable traffic metric than clicks alone. ## Formula **TikTok Cost per LP View** = **TikTok Spend** ÷ **TikTok Landing Page Views** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | [**TikTok Spend**](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on TikTok ads | | [**TikTok Landing Page Views**](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-landing-page-views) | Total landing page loads from TikTok ads | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your brand spent **\$3,600** on TikTok ads in February and received **9,000 landing page views**: | Ad Group | Spend | LP Views | Cost/LP View | | ----------- | ----------- | --------- | ------------ | | Prospecting | \$1,800 | 4,500 | \$0.40 | | Retargeting | \$1,200 | 3,000 | \$0.40 | | Lookalike | \$600 | 1,500 | \$0.40 | | **Total** | **\$3,600** | **9,000** | **\$0.40** | *** ## How It Works TikTok Cost per Landing Page View divides total spend by landing page views rather than clicks. Since landing page views only count when your page fully loads, this metric gives a truer picture of what you pay for actual website traffic. It's typically higher than CPC because some clicks never result in a loaded page. *** ## When to Use | Scenario | Action | | ------------------------ | ---------------------------------------------------- | | True traffic cost | Use instead of CPC when page speed varies | | Budget forecasting | Estimate actual site visitors from planned spend | | Campaign comparison | Identify which ad sets deliver cheapest real traffic | | Performance benchmarking | Track efficiency improvements over time | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | [TikTok Spend](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Numerator — total TikTok ad cost | | [TikTok Landing Page Views](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-landing-page-views) | Denominator — completed page loads | | [TikTok CPC](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-cpc) | Cost per click — typically lower than cost per LP view | [See all TikTok Clicks metrics →](/reference/metrics/advertising/tiktok/tiktok-clicks) # TikTok Conversions: Purchase, Lead, and Event Metrics Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/index Track TikTok conversion metrics including purchases, leads, add-to-carts, checkouts, and app installs. Measure TikTok-attributed actions and their value. Conversion metrics track actions TikTok attributes to your ads—from product views through purchases, plus lead generation and app installs. **Data Source:** [TikTok Ads](/sources/tiktok)\ **Metrics:** 29 ## Metrics in This Group ### Purchase Funnel | Metric | Description | When to Use | | --------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ------------------------ | | [TikTok View Contents](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-view-contents) | Product page views | Top-of-funnel engagement | | [TikTok View Contents Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-view-contents-value) | Value of viewed products | Measure interest quality | | [TikTok Cost per View Content](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-view-contents-cost) | Cost per product view | Traffic efficiency | | [TikTok Add to Carts](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-carts) | Cart additions | Mid-funnel intent | | [TikTok Add to Carts Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-carts-value) | Value of carted items | Cart quality | | [TikTok Cost per Add to Cart](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-carts-cost) | Cost per cart add | Mid-funnel efficiency | | [TikTok Initiate Checkouts](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-initiate-checkouts) | Checkout starts | Bottom-funnel intent | | [TikTok Initiate Checkouts Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-initiate-checkouts-value) | Value of checkouts started | Checkout quality | | [TikTok Cost per Init. Checkout](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-initiate-checkouts-cost) | Cost per checkout start | Checkout efficiency | | [TikTok Purchases](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases) | Completed purchases | Conversion count | | [TikTok Purchases Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases-value) | Revenue from purchases | Attributed revenue | ### Lead Generation | Metric | Description | When to Use | | -------------------------------------------------------------------------------------------------- | --------------------- | --------------- | | [TikTok Leads](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-leads) | Lead form submissions | Lead volume | | [TikTok Leads Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-leads-value) | Value of leads | Lead quality | | [TikTok Cost per Lead](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-leads-cost) | Cost per lead (CPL) | Lead efficiency | ### User Actions | Metric | Description | When to Use | | ----------------------------------------------------------------------------------------------------------------------- | -------------------------- | -------------------- | | [TikTok Searches](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-searches) | Site searches | Search engagement | | [TikTok Searches Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-searches-value) | Value of searches | Search intent | | [TikTok Cost per Search](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-searches-cost) | Cost per search | Search efficiency | | [TikTok Subscribes](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-subscribes) | Newsletter/service signups | Subscription volume | | [TikTok Subscribes Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-subscribes-value) | Value of subscriptions | Subscription quality | | [TikTok Cost per Subscribe](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-subscribes-cost) | Cost per subscription | Subscribe efficiency | | [TikTok Schedules](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-schedules) | Appointments scheduled | Booking volume | | [TikTok Schedules Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-schedules-value) | Value of schedules | Booking quality | | [TikTok Cost per Schedule](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-schedules-cost) | Cost per schedule | Booking efficiency | | [TikTok Add to Wishlists](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-wishlists) | Wishlist additions | Future intent | | [TikTok Add to Wishlists Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-wishlists-value) | Value of wishlisted items | Wishlist quality | | [TikTok Cost per Wishlist Add](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-wishlists-cost) | Cost per wishlist add | Wishlist efficiency | ### App & Registration | Metric | Description | When to Use | | --------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ----------------------- | | [TikTok App Installs](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-app-installs) | Mobile app installs | App acquisition | | [TikTok Cost per App Install](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-app-installs-cost) | Cost per install (CPI) | App install efficiency | | [TikTok Completed Registrations](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-complete-registrations) | Account signups | Registration volume | | [TikTok Completed Reg. Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-complete-registrations-value) | Value of registrations | Registration quality | | [TikTok Cost per Registration](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-complete-registrations-cost) | Cost per registration | Registration efficiency | ## How These Metrics Relate Purchase funnel flow: ``` View Contents → Add to Cart → Initiate Checkout → Purchase ``` Each metric has three variants: * **Count** — Number of events * **Value** — Monetary value of events * **Cost** — Spend ÷ Count (efficiency) ## Choosing the Right Metric * **E-commerce**: Focus on purchase funnel metrics * **Lead generation**: Use Leads and Cost per Lead (CPL) * **App campaigns**: Use App Installs and CPI * **Funnel optimization**: Compare drop-off between funnel stages # TikTok Add to Carts: Attributed Cart Actions Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-carts Track add-to-cart events TikTok attributes to your ads. Monitor mid-funnel purchase intent signals to optimize TikTok ad campaigns. TikTok Add to Carts counts the number of add-to-cart events TikTok attributes to your ads—a mid-funnel signal of purchase intent. ## Formula **TikTok Add to Carts** = **COUNT** ( TikTok-Attributed Add to Cart Events ) ### Formula Components | Metric | Definition | | ---------------------------------------- | ------------------------------------------------------------------------------------ | | **TikTok-Attributed Add to Cart Events** | Cart additions tracked by TikTok's pixel or Events API within the attribution window | | Metadata | | | --------------- | ----------------------------- | | **Type** | Number | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example A skincare brand spent **\$2,400 on TikTok ads** last week targeting Gen Z audiences with influencer-style content. | Campaign | Add to Carts | Cost per Add to Cart | | ---------------- | ------------ | -------------------- | | UGC Testimonials | 847 | \$1.42 | | Product Demo | 312 | \$3.85 | | Flash Sale | 1,203 | \$0.99 | | **Total** | **2,362** | **\$1.02** | *** ## How It Works TikTok counts an add-to-cart event when a user adds a product to their cart on your site after interacting with your ad. Attribution uses TikTok's click-through and view-through windows (typically 7-day click, 1-day view). The count reflects TikTok's attribution model, which may differ from Upstack's first-party attribution. *** ## When to Use | Scenario | Action | | ------------------------------------------ | ---------------------------------------------- | | Evaluating campaign mid-funnel performance | Compare add-to-cart volume across campaigns | | Optimizing for purchase intent | Scale campaigns with high add-to-cart counts | | Diagnosing checkout drop-off | Compare add-to-carts vs. initiated checkouts | | Benchmarking creative performance | Identify which ads drive the most cart actions | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | [TikTok Cost per Add to Cart](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-cost-per-add-to-cart) | Cost efficiency of driving cart actions | | [TikTok Initiate Checkouts](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-initiate-checkouts) | Next step in purchase funnel | | [TikTok Purchases](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases) | Final conversion event | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Cost per Add to Cart: Measure Purchase Intent Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-carts-cost Track your TikTok cost per add to cart to measure how efficiently your ads drive purchase intent. Lower costs mean better mid-funnel performance. Average spend per add-to-cart event from your TikTok ads—a key indicator of how efficiently your campaigns drive purchase intent. ## Formula **TikTok Cost per Add to Cart** = **TikTok Ad Spend** ÷ **TikTok Add to Carts** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | [**TikTok Ad Spend**](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on your TikTok ads | | [**TikTok Add to Carts**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-carts) | Number of add to cart actions attributed to your TikTok ads | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your TikTok prospecting campaign spent **\$2,400** last week and drove **800 add to carts**. | Campaign | Spend | Add to Carts | Cost/ATC | | ---------------------- | ----------- | ------------ | ---------- | | Prospecting - Video | \$1,500 | 600 | \$2.50 | | Retargeting - Carousel | \$900 | 200 | \$4.50 | | **Total** | **\$2,400** | **800** | **\$3.00** | *** ## How It Works TikTok tracks add-to-cart events through its Pixel or Events API. Upstack calculates cost per add to cart by dividing your total TikTok ad spend by the number of attributed add-to-cart events during the selected period. *** ## When to Use | Scenario | Action | | -------------------------------- | ------------------------------------------------------------ | | Evaluating mid-funnel efficiency | Compare cost/ATC across campaigns to find best performers | | Creative testing | Lower cost/ATC signals more compelling product presentation | | Audience optimization | Identify which audiences show strongest purchase intent | | Budget allocation | Shift spend toward campaigns with lower cost per add to cart | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | [TikTok Add to Carts](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-carts) | The denominator—total add to cart events | | [TikTok CPA](/reference/metrics/advertising/tiktok/tiktok-efficiency/tiktok-cpa) | Cost per purchase—measures full conversion efficiency | | [TikTok Cost per Initiate Checkout](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-initiate-checkouts-cost) | Next funnel stage—cost per checkout started | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Add to Carts Value: Track Cart Revenue Potential Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-carts-value Measure the total dollar value of products added to cart from your TikTok ads. Track mid-funnel revenue potential and identify high-value audiences. The combined dollar value of all products added to shopping carts by visitors from your TikTok ads. ## Formula **TikTok Add to Carts Value** = **SUM** ( Product Values Added to Cart ) ### Formula Components | Metric | Definition | | -------------------------------- | -------------------------------------------------------------------------- | | **Product Values Added to Cart** | The dollar value passed with each AddToCart event attributed to TikTok ads | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example A skincare brand's TikTok campaign drove **\$47,200 in cart value** last week across three ad sets. | Ad Set | Add to Carts | Cart Value | Avg Cart | | ---------------- | ------------ | ---------- | -------- | | Serum Collection | 284 | \$22,720 | \$80 | | Bundle Deals | 156 | \$18,720 | \$120 | | New Arrivals | 145 | \$5,760 | \$40 | The Bundle Deals ad set shows the highest average cart value despite fewer add-to-carts, indicating stronger purchase intent from that audience. *** ## How It Works TikTok tracks the value parameter passed with each AddToCart event and attributes it to your ads based on your attribution window. The total is summed across all cart additions from ad-driven traffic. This reflects the potential revenue sitting in carts, not completed purchases. *** ## When to Use | Scenario | Action | | --------------------------------- | --------------------------------------------------------------------- | | Comparing ad creative performance | Higher cart values indicate ads attracting buyers with larger baskets | | Evaluating audience targeting | Audiences with high cart value are more likely to convert profitably | | Forecasting revenue potential | Cart value indicates pipeline revenue before checkout drop-off | | Optimizing for value over volume | Prioritize campaigns with higher value per cart, not just cart count | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------- | ------------------------------------ | | [TikTok Add to Carts](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-carts) | Count of add-to-cart events (volume) | | [TikTok Purchases Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases-value) | Revenue from completed purchases | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Add to Wishlists: Wishlist Intent from Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-wishlists Track wishlist additions attributed to your TikTok ads. Measure future purchase intent and optimize campaigns targeting high-intent shoppers. The number of add-to-wishlist actions attributed to your TikTok ads. ## Formula **TikTok Add to Wishlists** = **COUNT** ( TikTok-Attributed Add to Wishlist Events ) ### Formula Components | Metric | Definition | | -------------------------------------------- | ------------------------------------------------------------------------------ | | **TikTok-Attributed Add to Wishlist Events** | Wishlist additions that occurred after a user viewed or clicked your TikTok ad | | Metadata | | | --------------- | ----------------------------- | | **Type** | Number | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your TikTok campaigns generated **2,847 wishlist additions** this month: | Campaign | Wishlists | Cost per Wishlist | | ------------------ | --------- | ----------------- | | Holiday Gift Guide | 1,245 | \$0.42 | | New Arrivals | 892 | \$0.58 | | Flash Sale Teaser | 710 | \$0.31 | *** ## How It Works TikTok tracks when users add products to their wishlist after viewing or clicking your ads. These events signal strong purchase intent—users are saving items for later. Attribution follows TikTok's click-through and view-through windows. *** ## When to Use | Scenario | Action | | ------------------------- | -------------------------------------------------------- | | Measuring purchase intent | Track wishlists as a leading indicator before sales | | Optimizing for intent | Target campaigns toward wishlist-prone audiences | | Retargeting lists | Build audiences from users who wishlisted but didn't buy | | Seasonal planning | Monitor wishlist spikes before major shopping events | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | [TikTok Wishlist Cost](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-wishlists-cost) | Cost per wishlist addition | | [TikTok Wishlist Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-wishlists-value) | Revenue from wishlisted items | | [TikTok Add to Carts](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-carts) | Next step in funnel after wishlisting | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Cost per Add to Wishlist: Wishlist Efficiency Metric Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-wishlists-cost Track your TikTok cost per wishlist addition to measure how efficiently your ads capture future purchase intent. Lower costs signal stronger wishlist appeal. Average spend per wishlist add from your TikTok ads—measures how efficiently your campaigns drive future purchase intent. ## Formula **TikTok Cost per Add to Wishlist** = **TikTok Ad Spend** ÷ **TikTok Add to Wishlists** ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | [**TikTok Ad Spend**](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on your TikTok ads | | [**TikTok Add to Wishlists**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-wishlists) | Number of wishlist additions attributed to your TikTok ads | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your TikTok holiday campaign spent **\$1,800** and drove **4,500 wishlist additions**. | Campaign | Spend | Wishlists | Cost/Wishlist | | ------------------ | ----------- | --------- | ------------- | | Holiday Gift Guide | \$1,200 | 3,200 | \$0.38 | | New Arrivals | \$600 | 1,300 | \$0.46 | | **Total** | **\$1,800** | **4,500** | **\$0.40** | *** ## How It Works TikTok tracks wishlist events through its Pixel or Events API. Upstack calculates cost per wishlist by dividing your total TikTok ad spend by the number of attributed wishlist additions during the selected period. *** ## When to Use | Scenario | Action | | --------------------------- | ------------------------------------------------------------------ | | Measuring intent efficiency | Compare cost/wishlist across campaigns to find best performers | | Seasonal planning | Track wishlist efficiency before major shopping events | | Creative testing | Lower cost/wishlist signals more desirable product presentation | | Budget allocation | Shift spend toward campaigns with lower wishlist acquisition costs | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | [TikTok Add to Wishlists](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-wishlists) | The denominator—total wishlist events | | [TikTok Cost per Add to Cart](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-carts-cost) | Next funnel stage—cost per cart addition | | [TikTok CPA](/reference/metrics/advertising/tiktok/tiktok-efficiency/tiktok-cpa) | Cost per purchase—measures full conversion efficiency | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Add to Wishlists Value: Total Wishlist Revenue Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-wishlists-value Track the total monetary value of add to wishlist actions attributed to your TikTok ads. Measures future purchase intent value. TikTok Add to Wishlists Value measures the combined monetary value of all products added to wishlists by visitors from your TikTok ads. ## Formula **TikTok Add to Wishlists Value** = **SUM** ( Product Values Added to Wishlist ) ### Formula Components | Metric | Definition | | ------------------------------------ | -------------------------------------------------------------- | | **Product Values Added to Wishlist** | Catalog value of each product added to wishlist via TikTok ads | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your TikTok campaigns generated **\$12,450** in wishlist value last month from visitors saving products for later. | Campaign | Wishlists | Wishlist Value | Avg Item Value | | ----------------- | --------- | -------------- | -------------- | | Summer Collection | 847 | \$6,230 | \$7.35 | | New Arrivals | 512 | \$4,180 | \$8.16 | | Clearance Sale | 423 | \$2,040 | \$4.82 | *** ## How It Works TikTok tracks when users add products to wishlists after interacting with your ads and sums the catalog value of those items. This metric signals future purchase intent—visitors who wishlist products often return to buy when timing or budget allows. *** ## When to Use | Scenario | Action | | ------------------------------------------ | -------------------------------------------------------- | | Evaluating consideration stage performance | Compare wishlist value against actual purchase value | | Identifying high-intent products | Find items with high wishlist value but low purchases | | Planning retargeting campaigns | Target users who wishlisted high-value items | | Seasonal trend analysis | Track wishlist value spikes before peak shopping periods | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | | [TikTok Add to Wishlists](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-wishlists) | Count of wishlist actions generating this value | | [TikTok Cost per Add to Wishlist](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-wishlists-cost) | Efficiency of driving wishlist actions | | [TikTok Add to Carts Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-carts-value) | Next stage in purchase funnel | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok App Installs: Mobile App Downloads from TikTok Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-app-installs Track app installs attributed to your TikTok ads. Measure mobile app download performance and optimize app install campaigns. TikTok App Installs counts the number of app downloads TikTok attributes to your ads. ## Formula **TikTok App Installs** = **COUNT** ( TikTok-Attributed App Install Events ) ### Formula Components | Metric | Definition | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | **TikTok-Attributed App Install Events** | App download events tracked by TikTok via mobile measurement partners (MMPs) or TikTok SDK within the attribution window | | Metadata | | | --------------- | ----------------------------- | | **Type** | Number | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Count | *** ## Example **Your fitness app campaign drove 2,847 installs in March** across three ad groups targeting different audiences. | Ad Group | App Installs | Spend | Cost per Install | | -------------------- | ------------ | ------- | ---------------- | | Health Enthusiasts | 1,245 | \$2,490 | \$2.00 | | New Year Resolutions | 982 | \$2,455 | \$2.50 | | Athletes | 620 | \$1,860 | \$3.00 | *** ## How It Works TikTok tracks app installs using mobile measurement partners (MMPs) and TikTok's own SDK. When a user clicks your ad and installs your app within the attribution window, TikTok counts it as an attributed install. *** ## When to Use | Scenario | Action | | ----------------------------- | ------------------------------------------------ | | Launching a new app | Track total installs to measure campaign reach | | Comparing ad creatives | Identify which videos drive the most downloads | | Scaling install campaigns | Monitor volume against budget increases | | Evaluating audience targeting | Compare install rates across different ad groups | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------------- | --------------------------- | | [TikTok Cost per App Install](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-cost-per-app-install) | Cost efficiency per install | | [TikTok Completed Registrations](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-completed-registrations) | Post-install signup actions | | [TikTok Spend](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total ad budget consumed | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Cost per App Install: CPI for App Campaigns Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-app-installs-cost Track the cost per app install from your TikTok ads. Learn how CPI is calculated, see examples, and optimize your app install campaign efficiency. The average cost to acquire one app install from your TikTok advertising. ## Formula **TikTok Cost per App Install** = **TikTok Ad Spend** ÷ **TikTok App Installs** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | [**TikTok Ad Spend**](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on TikTok advertising | | [**TikTok App Installs**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-app-installs) | Number of app installs attributed to TikTok ads | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your app install campaign spent **\$2,400** and drove **800 installs** this week: | Ad Group | Spend | Installs | CPI | | ------------------ | ------- | -------- | ------ | | Lookalike Audience | \$1,200 | 480 | \$2.50 | | Interest Targeting | \$800 | 240 | \$3.33 | | Retargeting | \$400 | 80 | \$5.00 | *** ## How It Works CPI divides your TikTok ad spend by the number of app installs TikTok attributes to your ads. Lower CPI means you're acquiring users more efficiently. TikTok tracks installs through its SDK integration with your mobile app. *** ## When to Use | Scenario | Action | | ---------------------------------- | --------------------------------------------------- | | Evaluating app campaign efficiency | Compare CPI across ad groups and creatives | | Setting install targets | Use CPI to forecast budget needed for install goals | | Benchmarking performance | Compare your CPI to industry averages | | Optimizing creative | Test new creatives to lower acquisition cost | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | [TikTok App Installs](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-app-installs) | The denominator for CPI | | [TikTok CPA](/reference/metrics/advertising/tiktok/tiktok-efficiency/tiktok-cpa) | Cost per purchase (compare to CPI for full-funnel view) | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Complete Registrations: Account Signups from Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-complete-registrations Track completed registration events from your TikTok ads. Measure account signups and user acquisitions attributed to your TikTok campaigns. The number of completed registration events TikTok attributes to your ads. ## Formula **TikTok Complete Registrations** = **COUNT** ( TikTok-Attributed Registration Events ) ### Formula Components | Metric | Definition | | ----------------------------------------- | -------------------------------------------------------------------------- | | **TikTok-Attributed Registration Events** | CompleteRegistration events fired by the TikTok Pixel after ad interaction | | Metadata | | | --------------- | ----------------------------- | | **Type** | Number | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Count | *** ## Example Your signup campaign generated **842 registrations** this week across three ad groups: | Ad Group | Registrations | Cost per Registration | | ------------------- | ------------- | --------------------- | | Lookalike Audiences | 412 | \$2.85 | | Interest Targeting | 287 | \$3.42 | | Retargeting | 143 | \$1.94 | *** ## How It Works TikTok counts a completed registration when a user triggers the `CompleteRegistration` event on your site or app after interacting with your ad. This event is typically fired after account creation, email verification, or form submission. Attribution follows TikTok's configured click and view windows. *** ## When to Use | Scenario | Action | | --------------------------------- | -------------------------------------------------------------- | | Measuring user acquisition | Track how many new accounts your ads generate | | Optimizing signup campaigns | Compare registration rates across ad groups | | Calculating cost per registration | Divide spend by registrations to find acquisition cost | | Evaluating lead quality | Compare registrations to downstream conversions like purchases | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | [TikTok Cost per Completed Registration](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-complete-registrations-cost) | Spend ÷ Registrations | | [TikTok Completed Registrations Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-complete-registrations-value) | Total value assigned to registrations | | [TikTok Leads](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-leads) | Another top-of-funnel conversion event | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Cost per Registration: Ad Efficiency Metric Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-complete-registrations-cost Track your cost per completed registration from TikTok ads. Measure registration acquisition efficiency and optimize signup campaigns. TikTok Cost per Registration measures the average amount you spend on TikTok ads to acquire one completed registration. ## Formula **TikTok Cost per Registration** = **TikTok Ad Spend** ÷ **TikTok Complete Registrations** ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | [**TikTok Ad Spend**](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on TikTok advertising | | [**TikTok Complete Registrations**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-complete-registrations) | Total registrations attributed to TikTok ads | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example A DTC brand spent **\$2,400** on TikTok registration campaigns and generated **120 complete registrations**. | Metric | Value | | ------------------------- | ----------- | | TikTok Spend | \$2,400 | | Complete Registrations | 120 | | **Cost per Registration** | **\$20.00** | *** ## How It Works Upstack calculates this metric by dividing your total TikTok ad spend by the number of complete registrations attributed to those ads. Lower values indicate more efficient registration acquisition from your TikTok campaigns. *** ## When to Use | Scenario | Action | | ------------------------------------- | ---------------------------------------------------- | | Evaluating signup campaign efficiency | Compare cost per registration across ad sets | | Budget allocation decisions | Shift spend toward lower-cost registration sources | | Campaign optimization | Identify which creatives drive cheaper registrations | | Benchmarking performance | Track cost per registration trends over time | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | | [TikTok Complete Registrations](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-complete-registrations) | The denominator in this calculation | | [TikTok Cost per Lead](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-leads-cost) | Similar efficiency metric for leads | | [TikTok Spend](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | The numerator in this calculation | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Complete Registrations Value: Revenue from Signups Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-complete-registrations-value Track total value of completed registrations attributed to TikTok ads. Measure signup revenue, optimize registration campaigns, and calculate cost efficiency. The combined monetary value of all completed registrations attributed to your TikTok ads. ## Formula **TikTok Complete Registrations Value** = **SUM** ( Registration Values ) ### Formula Components | Metric | Definition | | ----------------------- | ---------------------------------------------------------------- | | **Registration Values** | The monetary value assigned to each completed registration event | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your TikTok registration campaigns generated **\$12,400** in value from 620 completed signups this month: | Campaign | Registrations | Value | Avg Value | | ---------------------- | ------------- | ------- | --------- | | Lead Gen - Fitness App | 340 | \$6,800 | \$20.00 | | Free Trial - SaaS | 180 | \$3,600 | \$20.00 | | Newsletter Signup | 100 | \$2,000 | \$20.00 | *** ## How It Works Registration Value sums the monetary value assigned to each completed registration event. TikTok attributes registrations to your ads based on view-through and click-through windows. Values are typically set as a fixed amount per registration or calculated from expected customer lifetime value. *** ## When to Use | Scenario | Action | | ----------------------------- | ---------------------------------------------------------------------- | | Evaluating lead gen campaigns | Compare total registration value across campaigns | | Calculating registration ROAS | Divide Registration Value by TikTok Spend | | Optimizing signup flow | Identify which creatives drive the highest-value registrations | | Budget planning | Allocate spend toward campaigns generating the most registration value | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | [TikTok Complete Registrations](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-complete-registrations) | Count of registrations (this metric sums their values) | | [TikTok Cost per Registration](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-complete-registrations-cost) | TikTok Spend ÷ Completed Registrations | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Initiate Checkouts: Attributed Checkout Starts Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-initiate-checkouts Track checkout initiations attributed to TikTok ads. Measure how many users start the checkout process after engaging with your TikTok campaigns. TikTok Initiate Checkouts counts the number of checkout initiations attributed to your TikTok ad campaigns. ## Formula **TikTok Initiate Checkouts** = **COUNT** ( TikTok-Attributed Initiate Checkout Events ) ### Formula Components | Metric | Definition | | ---------------------------------------------- | ------------------------------------------------------------------------------------------ | | **TikTok-Attributed Initiate Checkout Events** | Checkout starts from users who clicked or viewed a TikTok ad within the attribution window | | Metadata | | | --------------- | ----------------------------- | | **Type** | Number | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Count | *** ## Example Your TikTok campaigns drove **892 checkout initiations** during a product launch week. | Campaign | Initiate Checkouts | Conversion Rate to Purchase | | ----------------- | ------------------ | --------------------------- | | Summer Collection | 534 | 68% | | Flash Sale | 285 | 72% | | New Arrivals | 73 | 61% | *** ## How It Works When a user views or clicks a TikTok ad and later initiates checkout on your store, Upstack attributes that checkout start to TikTok. Attribution uses TikTok's click ID (ttclid) and view-through tracking within the configured attribution window. *** ## When to Use | Scenario | Action | | ------------------------- | ---------------------------------------------------------------------- | | Measuring checkout intent | Compare initiate checkouts to completed purchases to identify drop-off | | Evaluating ad creative | Analyze which TikTok ads drive the most checkout starts | | Funnel optimization | Calculate the initiate checkout to purchase conversion rate | | Campaign comparison | Compare checkout intent across different TikTok campaign types | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [TikTok Conversions](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-conversions) | Completed purchases vs. checkout starts | | [TikTok Add to Carts](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-carts) | Earlier funnel stage before checkout | | [TikTok Conversion Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-conversion-value) | Revenue from completed TikTok-attributed purchases | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Cost per Initiate Checkout: Checkout Acquisition Cost Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-initiate-checkouts-cost Track TikTok Cost per Initiate Checkout to measure spend efficiency for driving checkout starts. Lower values indicate better bottom-of-funnel ad performance. TikTok Cost per Initiate Checkout measures the average spend per checkout started from your TikTok ads. ## Formula **TikTok Cost per Initiate Checkout** = **TikTok Ad Spend** ÷ **TikTok Initiate Checkouts** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [**TikTok Ad Spend**](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on TikTok advertising | | [**TikTok Initiate Checkouts**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-initiate-checkouts) | Number of checkout starts attributed to TikTok ads | | Metadata | | | --------------- | ---------------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio (Spend ÷ Initiate Checkouts) | *** ## Example Your activewear brand spent **\$2,400** on TikTok ads last week and drove **320 checkout starts**. | Campaign | Spend | Checkouts | Cost/Checkout | | ----------------- | ------- | --------- | ------------- | | Summer Collection | \$1,200 | 200 | \$6.00 | | Influencer Collab | \$800 | 96 | \$8.33 | | Flash Sale | \$400 | 24 | \$16.67 | *** ## How It Works TikTok calculates this metric by dividing your total ad spend by the number of checkout initiations attributed to your ads. A lower cost per checkout indicates efficient bottom-of-funnel performance—your ads successfully move high-intent shoppers toward purchase at a reasonable cost. *** ## When to Use | Scenario | Action | | --------------------------------- | ---------------------------------------------------------------------- | | Cost rising while checkouts drop | Test new creative angles or refine audience targeting | | Lower cost than CPA | Strong mid-funnel—investigate checkout abandonment for conversion gaps | | Cost varies by campaign | Reallocate budget toward campaigns with lower checkout costs | | Cost acceptable but purchases low | Focus on checkout experience and retargeting abandoners | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | [TikTok Initiate Checkouts](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-initiate-checkouts) | The checkout count used in this formula | | [TikTok CPA](/reference/metrics/advertising/tiktok/tiktok-efficiency/tiktok-cpa) | Compare checkout cost to final purchase cost | | [TikTok Add to Carts Cost](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-carts-cost) | Earlier funnel stage cost for comparison | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Initiate Checkouts Value: Total Checkout Revenue Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-initiate-checkouts-value Track total checkout initiation value from TikTok ads. Measure the combined cart value of users entering checkout from your campaigns. Combined value of all checkout initiations by visitors from your TikTok ads. ## Formula **TikTok Initiate Checkouts Value** = **SUM** ( Checkout Values ) ### Formula Components | Metric | Definition | | ------------------- | ------------------------------------------------------------------------ | | **Checkout Values** | The cart value at checkout initiation for each TikTok-attributed visitor | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your TikTok campaigns drove **\$18,450 in checkout value** last week across 312 checkout initiations. | Campaign | Checkout Value | Checkouts | Avg Cart | | ----------------- | -------------- | --------- | -------- | | Spring Collection | \$12,300 | 198 | \$62.12 | | Flash Sale | \$4,150 | 89 | \$46.63 | | New Arrivals | \$2,000 | 25 | \$80.00 | *** ## How It Works TikTok reports the total cart value each time a user attributed to your ads initiates the checkout process. This value represents purchase intent — not completed sales — and typically exceeds final purchase value due to cart abandonment. *** ## When to Use | Scenario | Action | | --------------------- | ------------------------------------------------------------------- | | Forecasting revenue | Use checkout value as a leading indicator for expected purchases | | Comparing ad creative | Higher checkout value suggests ads attract higher-value customers | | Optimizing for value | Pair with checkout count to calculate average cart size | | Funnel analysis | Compare against purchases value to measure checkout completion rate | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | [TikTok Initiate Checkouts](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-initiate-checkouts) | Count of checkout initiations (volume) | | [TikTok Purchases Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases-value) | Completed purchase revenue (downstream) | | [TikTok Cost per Initiate Checkout](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-initiate-checkouts-cost) | Efficiency of driving checkout value | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Leads: Track Lead Generation from TikTok Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-leads Track lead events attributed to your TikTok ads. Monitor form submissions and lead actions to measure campaign effectiveness. TikTok Leads counts the number of lead events TikTok attributes to your ads, including form submissions and equivalent lead actions. ## Formula **TikTok Leads** = **COUNT** ( TikTok-Attributed Lead Events ) ### Formula Components | Metric | Definition | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | **TikTok-Attributed Lead Events** | Lead actions (form submissions, sign-ups) that TikTok attributes to your ads based on click-through and view-through attribution windows | | Metadata | | | --------------- | ----------------------------- | | **Type** | Number | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Count | *** ## Example Your skincare brand ran a TikTok lead generation campaign offering a free consultation. **In March, you generated 847 leads** from your TikTok ads. | Week | Leads | Spend | Cost per Lead | | ------ | ----- | ------- | ------------- | | Week 1 | 189 | \$1,420 | \$7.51 | | Week 2 | 234 | \$1,680 | \$7.18 | | Week 3 | 198 | \$1,520 | \$7.68 | | Week 4 | 226 | \$1,580 | \$6.99 | *** ## How It Works TikTok tracks when users complete lead actions after engaging with your ads, typically form submissions on your landing page or TikTok's native Lead Gen Forms. Attribution follows TikTok's click-through and view-through windows configured in your ad account settings. *** ## When to Use | Scenario | Action | | --------------------------------------- | ---------------------------------------------------------- | | Measuring lead gen campaign performance | Compare lead volume across ad groups and creatives | | Evaluating audience quality | Track leads alongside conversion rates to downstream sales | | Optimizing for lead volume | Identify which creatives drive the most form submissions | | Planning budget allocation | Compare lead efficiency across TikTok vs other platforms | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | --------------------------------------- | | [TikTok Cost per Lead](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-leads-cost) | Cost efficiency of lead generation | | [TikTok Leads Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-leads-value) | Total assigned value of leads generated | | [TikTok Purchases](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases) | Downstream purchase conversions | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Cost per Lead: Lead Generation Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-leads-cost Track the cost per lead from your TikTok ads. Optimize lead generation campaign efficiency with CPL benchmarking. TikTok Cost per Lead (CPL) measures the average spend required to generate one lead from your TikTok ads. ## Formula **TikTok Cost per Lead** = **TikTok Ad Spend** ÷ **TikTok Leads** ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------- | ---------------------------------------------- | | [**TikTok Ad Spend**](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on TikTok advertising | | [**TikTok Leads**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-leads) | Number of lead events attributed to TikTok ads | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example A B2B company spent **\$4,500** on TikTok lead gen ads in March and captured **150 leads**. | Month | Ad Spend | Leads | Cost per Lead | | -------- | -------- | ----- | ------------- | | January | \$3,200 | 80 | \$40.00 | | February | \$3,800 | 95 | \$40.00 | | March | \$4,500 | 150 | \$30.00 | March's CPL of **\$30.00** shows a 25% improvement from better targeting. *** ## How It Works TikTok tracks lead events when users complete form submissions or sign-ups attributed to your ads. CPL divides total spend by lead events to show average acquisition cost. *** ## When to Use | Scenario | Action | | -------------------- | --------------------------------------------------- | | Evaluating campaigns | Compare CPL across campaigns to find top performers | | Budget allocation | Shift spend toward campaigns with lower CPL | | Creative testing | A/B test ad creatives and measure CPL impact | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------- | ------------------------------------------------ | | [TikTok Leads](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-leads) | Denominator—total leads driving this calculation | | [TikTok CPA](/reference/metrics/advertising/tiktok/tiktok-efficiency/tiktok-cpa) | Similar efficiency metric for purchases | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Leads Value: Total Revenue from Lead Generation Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-leads-value Track total value of leads from TikTok ads. Monitor lead generation revenue and optimize campaigns for higher-value leads. TikTok Leads Value measures the combined assigned monetary value of all leads generated through your TikTok advertising campaigns. ## Formula **TikTok Leads Value** = **SUM** ( Lead Values ) ### Formula Components | Metric | Definition | | --------------- | ---------------------------------------------------------------- | | **Lead Values** | Monetary value assigned to each lead event from TikTok campaigns | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your fitness app ran TikTok lead generation campaigns targeting gym-goers. In March, you generated **847 leads** with a total value of **\$42,350**. | Week | Leads | Lead Value | Avg Lead Value | | ------ | ----- | ---------- | -------------- | | Week 1 | 185 | \$9,250 | \$50.00 | | Week 2 | 224 | \$11,200 | \$50.00 | | Week 3 | 198 | \$9,900 | \$50.00 | | Week 4 | 240 | \$12,000 | \$50.00 | *** ## How It Works TikTok tracks lead events (form submissions, sign-ups, or custom lead actions) and sums their assigned values. The value comes from either your TikTok Pixel configuration or the value passed with each lead event. This metric aggregates across all campaigns, ad groups, and ads in your selected time period. *** ## When to Use | Scenario | Action | | ----------------------- | -------------------------------------------------------------------------- | | Evaluating lead gen ROI | Compare total lead value against ad spend to assess campaign profitability | | Optimizing for quality | Monitor lead value trends to ensure campaigns attract high-value prospects | | Budget allocation | Shift spend toward campaigns generating higher total lead value | | Comparing channels | Benchmark TikTok lead value against Meta or Google lead generation | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | [TikTok Leads](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-leads) | Count of leads generated (quantity vs. this value) | | [TikTok Cost per Lead](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-cost-per-lead) | Efficiency metric showing acquisition cost per lead | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Purchases: Track TikTok-Attributed Conversions Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases Track purchase conversions attributed to TikTok ads. Measure how many sales your TikTok campaigns generate. TikTok Purchases counts the total number of purchase conversions attributed to your TikTok ad campaigns. ## Formula **TikTok Purchases** = **COUNT** ( TikTok-Attributed Purchase Events ) ### Formula Components | Metric | Definition | | ------------------------------------- | -------------------------------------------------------------------------------------------- | | **TikTok-Attributed Purchase Events** | Purchase conversions tracked by the TikTok pixel and attributed to TikTok ad clicks or views | | Metadata | | | --------------- | ----------------------------- | | **Type** | Number | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Count | *** ## Example Your TikTok campaigns generated **847 purchases** last month across all ad groups. | Campaign | TikTok Purchases | TikTok Spend | Cost per Purchase | | ------------ | ---------------- | ------------ | ----------------- | | Summer Sale | 412 | \$8,240 | \$20.00 | | New Arrivals | 289 | \$7,225 | \$25.00 | | Retargeting | 146 | \$2,190 | \$15.00 | | **Total** | **847** | **\$17,655** | **\$20.84** | *** ## How It Works TikTok Purchases counts each purchase event that TikTok attributes to your ad campaigns. Attribution includes both click-through conversions (user clicked an ad before purchasing) and view-through conversions (user saw an ad before purchasing). The attribution window is configurable in your TikTok Ads Manager settings. *** ## When to Use | Scenario | Action | | -------------------------------- | ------------------------------------------------------------- | | Measuring campaign effectiveness | Compare purchases across campaigns to identify top performers | | Calculating cost per acquisition | Divide TikTok Spend by TikTok Purchases for CPA | | Evaluating creative performance | Track which ad creatives drive the most purchases | | Budget allocation | Shift spend toward campaigns generating more purchases | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------- | --------------------------------------------------------- | | [TikTok Spend](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total cost of TikTok campaigns generating these purchases | | [TikTok ROAS](/reference/metrics/advertising/tiktok/tiktok-efficiency/tiktok-roas) | Return on ad spend calculated from purchase revenue | | [TikTok CPA](/reference/metrics/advertising/tiktok/tiktok-efficiency/tiktok-cpa) | Cost per purchase acquisition | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Purchases Value: Track Ad-Attributed Revenue Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases-value Track total revenue from purchases attributed to your TikTok ads. Use purchases value to measure campaign profitability, calculate ROAS, and optimize budget allocation. Total revenue from purchases that TikTok attributes to your advertising campaigns. ## Formula **TikTok Purchases Value** = **SUM** ( Purchase Revenue ) ### Formula Components | Metric | Definition | | -------------------- | --------------------------------------------------------------------------------------- | | **Purchase Revenue** | The transaction value recorded when a tracked purchase event fires after ad interaction | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your TikTok campaigns generated **\$24,650 in attributed revenue** last month across 412 purchases. | Campaign | Purchases | Purchases Value | Avg. Order Value | | ----------------- | --------- | --------------- | ---------------- | | Spring Collection | 248 | \$15,120 | \$61 | | Flash Sale | 164 | \$9,530 | \$58 | | **Total** | **412** | **\$24,650** | **\$60** | *** ## How It Works TikTok tracks purchases that occur after users interact with your ads within your attribution window. When a tracked purchase event fires, TikTok records the transaction value and attributes it to the ad that drove the conversion. *** ## When to Use | Scenario | Action | | -------------------------- | ------------------------------------------------------------------- | | Measuring campaign revenue | Compare purchases value across campaigns to identify top performers | | Calculating ROAS | Divide purchases value by spend to get return on ad spend | | Budget allocation | Shift spend toward campaigns generating highest revenue | | Profitability analysis | Subtract ad spend from purchases value to assess net return | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------- | ---------------------------------------------- | | [TikTok Purchases](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases) | Count of purchases that generated this revenue | | [TikTok ROAS](/reference/metrics/advertising/tiktok/tiktok-efficiency/tiktok-roas) | Revenue return per dollar spent | | [TikTok Spend](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Ad budget used to generate this revenue | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Schedules: Ad-Attributed Appointment Bookings Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-schedules Track schedule events attributed to your TikTok ads. Measure appointment bookings, demo requests, and consultation sign-ups driven by TikTok campaigns. TikTok Schedules counts the number of schedule events (appointment bookings, demo requests, consultation sign-ups) that TikTok attributes to your ads. ## Formula **TikTok Schedules** = **COUNT** ( TikTok-Attributed Schedule Events ) ### Formula Components | Metric | Definition | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | **TikTok-Attributed Schedule Events** | Appointment bookings, demo requests, or consultation sign-ups that occur within TikTok's attribution window after ad interaction | | Metadata | | | --------------- | ----------------------------- | | **Type** | Number | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example **Your salon ran a TikTok campaign promoting online booking.** Over the week, 156 users clicked through and scheduled appointments. | Day | Schedules | Spend | Cost per Schedule | | --------- | --------- | --------- | ----------------- | | Monday | 28 | \$140 | \$5.00 | | Tuesday | 31 | \$155 | \$5.00 | | Wednesday | 22 | \$132 | \$6.00 | | Thursday | 35 | \$140 | \$4.00 | | Friday | 40 | \$160 | \$4.00 | | **Total** | **156** | **\$727** | **\$4.66** | *** ## How It Works TikTok tracks when users complete a schedule event (appointment booking, demo request, or consultation sign-up) after interacting with your ad. Attribution follows TikTok's click-through and view-through windows, crediting your ad when the booking occurs within the attribution period. *** ## When to Use | Scenario | Action | | ----------------------- | ------------------------------------------ | | Service-based campaigns | Track bookings driven by TikTok ads | | B2B demo requests | Measure demo sign-ups from ad traffic | | Consultation funnels | Monitor consultation bookings per campaign | | Scheduling efficiency | Compare cost per schedule across ad sets | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------- | ---------------------------------- | | [TikTok Cost per Schedule](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-schedules-cost) | Cost efficiency per booking | | [TikTok Schedules Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-schedules-value) | Revenue value of bookings | | [TikTok Leads](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-leads) | Alternative lead conversion metric | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Cost per Schedule: Booking Efficiency Metric Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-schedules-cost Track TikTok Cost per Schedule to measure how efficiently your ads drive appointment bookings and scheduling events. TikTok Cost per Schedule measures the average ad spend required to generate one schedule event from your TikTok campaigns. ## Formula **TikTok Cost per Schedule** = **TikTok Ad Spend** ÷ **TikTok Schedules** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------- | ---------------------------------------- | | [**TikTok Ad Spend**](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on TikTok advertising | | [**TikTok Schedules**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-schedules) | Schedule events attributed to TikTok ads | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example A wellness brand spent **\$2,400** on TikTok ads in March, generating **120 appointment bookings**. | Metric | Value | Calculation | | --------------------- | ----------- | ------------- | | TikTok Spend | \$2,400 | — | | TikTok Schedules | 120 | — | | **Cost per Schedule** | **\$20.00** | \$2,400 ÷ 120 | *** ## How It Works TikTok reports schedule events when users complete booking actions after interacting with your ads. This metric divides your total TikTok ad spend by the number of schedule events to show the average cost of acquiring each booking. *** ## When to Use | Scenario | Action | | ----------------------------- | ------------------------------------------------- | | High cost per schedule | Test new creative or audience targeting | | Comparing campaign efficiency | Identify which campaigns drive bookings cheapest | | Budget planning | Estimate spend needed for booking volume goals | | Benchmarking against CPA | Compare schedule acquisition cost to purchase CPA | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------- | -------------------------------------- | | [TikTok Schedules](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-schedules) | The denominator — total booking events | | [TikTok CPA](/reference/metrics/advertising/tiktok/tiktok-efficiency/tiktok-cpa) | Cost per purchase for comparison | | [TikTok Spend](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | The numerator — total ad investment | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Schedules Value: Total Revenue from Schedule Events Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-schedules-value Track total value of schedule events from TikTok ads. Measure revenue from appointment bookings attributed to your TikTok campaigns. The combined monetary value of all schedule events attributed to your TikTok ads. ## Formula **TikTok Schedules Value** = **SUM** ( Schedule Values ) ### Formula Components | Metric | Definition | | ------------------- | -------------------------------------------------------------------------------------------- | | **Schedule Values** | The monetary value assigned to each schedule event (appointment booking, consultation, etc.) | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your TikTok campaigns generated **\$12,400** in schedule value from 62 appointments this month: | Campaign | Schedules | Value | Avg Value | | ------------ | --------- | ------- | --------- | | Spring Sale | 38 | \$7,600 | \$200 | | New Customer | 24 | \$4,800 | \$200 | *** ## How It Works TikTok Schedules Value sums the monetary value of each schedule event that TikTok attributes to your ads. Schedule events capture appointment bookings, consultations, and other scheduled interactions. Values are reported by TikTok based on the event data you pass to their pixel. *** ## When to Use | Scenario | Action | | ------------------------- | --------------------------------------------------------- | | Measuring booking revenue | Track total revenue from scheduled appointments | | Comparing campaign value | Identify which campaigns drive highest-value bookings | | Calculating schedule ROI | Divide by ad spend to find return on schedule events | | Optimizing for value | Shift budget toward campaigns with higher schedule values | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | [TikTok Schedules](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-schedules) | Count of events (this metric sums their values) | | [TikTok Cost per Schedule](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-cost-per-schedule) | TikTok Spend ÷ Schedules | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Searches: Attributed Search Events Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-searches Track search events TikTok attributes to your ads. Measure how effectively your campaigns drive site search activity and product discovery. TikTok Searches counts how many on-site search events TikTok attributes to your ads. ## Formula **TikTok Searches** = **COUNT** ( TikTok-Attributed Search Events ) ### Formula Components | Metric | Definition | | ----------------------------------- | ---------------------------------------------------------------------------- | | **TikTok-Attributed Search Events** | On-site search actions performed by users after interacting with a TikTok ad | | Metadata | | | --------------- | ----------------------------- | | **Type** | Number | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your TikTok campaign generated **842 searches** in March. Users clicked your ads and searched for products on your site, indicating strong purchase intent. | Campaign | Searches | Add to Carts | Conversion | | ----------------- | -------- | ------------ | ---------- | | Spring Collection | 512 | 287 | 56% | | New Arrivals | 330 | 156 | 47% | *** ## How It Works TikTok fires a search event when a user performs an on-site search after interacting with your ad. Attribution follows TikTok's default window (typically 7-day click, 1-day view). Higher search counts indicate your ads drive product discovery. *** ## When to Use | Scenario | Action | | ---------------------------------- | --------------------------------------------------------- | | Evaluating brand awareness | More searches suggest users want to explore your catalog | | Optimizing top-of-funnel campaigns | Track search-to-purchase ratio | | Comparing creative performance | Higher searches indicate more curiosity-driven engagement | | Identifying high-intent audiences | Audiences that search often convert better | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------- | ----------------------------------- | | [TikTok Cost per Search](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-searches-cost) | Efficiency of driving search events | | [TikTok Searches Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-searches-value) | Monetary value of search activity | | [TikTok Purchases](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases) | Downstream conversion from searches | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Cost per Search: Measure Search Event Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-searches-cost Track your TikTok cost per search to measure how efficiently your ads drive site search activity. Lower costs mean better product discovery performance. Average spend per search event from your TikTok ads—a key indicator of how efficiently your campaigns drive product discovery and site engagement. ## Formula **TikTok Cost per Search** = **TikTok Ad Spend** ÷ **TikTok Searches** ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | [**TikTok Ad Spend**](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on your TikTok ads | | [**TikTok Searches**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-searches) | Number of search events attributed to your TikTok ads | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your TikTok awareness campaign spent **\$1,800** last week and drove **600 search events** on your site. | Campaign | Spend | Searches | Cost/Search | | --------------- | ----------- | -------- | ----------- | | Spring Lookbook | \$1,200 | 480 | \$2.50 | | New Arrivals | \$600 | 120 | \$5.00 | | **Total** | **\$1,800** | **600** | **\$3.00** | *** ## How It Works TikTok tracks search events through its Pixel or Events API when users perform on-site searches after interacting with your ad. Upstack calculates cost per search by dividing your total TikTok ad spend by the number of attributed search events during the selected period. *** ## When to Use | Scenario | Action | | ------------------------------------- | -------------------------------------------------------------- | | Evaluating brand awareness efficiency | Compare cost/search across campaigns to find best performers | | Creative testing | Lower cost/search signals more curiosity-driven engagement | | Audience optimization | Identify which audiences explore your catalog most efficiently | | Budget allocation | Shift spend toward campaigns with lower cost per search | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | [TikTok Searches](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-searches) | The denominator—total search events | | [TikTok CPA](/reference/metrics/advertising/tiktok/tiktok-efficiency/tiktok-cpa) | Cost per purchase—measures full conversion efficiency | | [TikTok Searches Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-searches-value) | Monetary value of search activity | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Searches Value: Total Value from Search Events Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-searches-value Track the total monetary value of search events from your TikTok ads. Learn how search value measures conversion quality and campaign ROI. The combined monetary value of all search events attributed to your TikTok ads. ## Formula **TikTok Searches Value** = **SUM** ( Search Values ) ### Formula Components | Metric | Definition | | ----------------- | ---------------------------------------------------------------------- | | **Search Values** | The dollar value assigned to each search event from TikTok ad visitors | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your TikTok campaigns drove **\$8,450** in search value from 1,690 search events this month: | Campaign | Searches | Search Value | Avg Value | | ----------------- | -------- | ------------ | --------- | | Spring Collection | 820 | \$4,510 | \$5.50 | | New Arrivals | 540 | \$2,430 | \$4.50 | | Clearance Sale | 330 | \$1,510 | \$4.58 | *** ## How It Works TikTok Searches Value sums the monetary value assigned to each search event from visitors who clicked your TikTok ads. This value reflects user intent—visitors actively searching for products after engaging with your ads signal strong purchase consideration. *** ## When to Use | Scenario | Action | | ------------------------------- | ------------------------------------------------------------------------ | | Measuring search intent quality | Compare search values across campaigns to identify high-intent audiences | | Evaluating cost efficiency | Divide by TikTok Cost per Search to assess ROI | | Optimizing ad targeting | Shift budget toward audiences generating higher search values | | Funnel analysis | Track how search behavior correlates with downstream conversions | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | [TikTok Searches](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-searches) | Count of search events (this metric sums their values) | | [TikTok Cost per Search](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-searches-cost) | Ad Spend ÷ Searches—measure efficiency | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Subscribes: Attributed Subscription Events Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-subscribes Track subscribe events TikTok attributes to your ads. Measure newsletter signups, service subscriptions, and recurring revenue conversions from TikTok campaigns. TikTok Subscribes counts how many subscribe events TikTok attributes to your ads. ## Formula **TikTok Subscribes** = **COUNT** ( TikTok-Attributed Subscribe Events ) ### Formula Components | Metric | Definition | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | **TikTok-Attributed Subscribe Events** | Subscribe events (newsletter signups, trial starts, memberships) where TikTok attributed the conversion to an ad interaction | | Metadata | | | --------------- | ----------------------------- | | **Type** | Number | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your TikTok campaign generated **1,247 subscribes** in Q1. Users signed up for your newsletter or subscription service after engaging with your ads, building your recurring customer base. | Campaign | Subscribes | Cost/Subscribe | LTV Impact | | --------------- | ---------- | -------------- | ---------- | | Loyalty Program | 782 | \$2.45 | High | | Newsletter Push | 465 | \$1.89 | Medium | *** ## How It Works TikTok fires a subscribe event when a user completes a subscription action after interacting with your ad—such as signing up for a newsletter, starting a trial, or joining a membership program. Attribution follows TikTok's default window (typically 7-day click, 1-day view). *** ## When to Use | Scenario | Action | | -------------------------------- | ---------------------------------------------- | | Building email lists | Track newsletter signups from TikTok traffic | | Launching subscription services | Measure trial starts and membership signups | | Evaluating campaign ROI | Compare subscribe cost to subscriber LTV | | Optimizing for recurring revenue | Focus on campaigns with higher subscribe rates | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------ | --------------------------------------- | | [TikTok Cost per Subscribe](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-subscribes-cost) | Efficiency of driving subscribe events | | [TikTok Subscribes Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-subscribes-value) | Monetary value of subscription activity | | [TikTok Purchases](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases) | Downstream conversion from subscribers | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Cost per Subscribe: Subscription Campaign Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-subscribes-cost Track the cost per subscribe event from your TikTok ads. Measure subscription campaign efficiency and optimize your audience targeting for lower acquisition costs. TikTok Cost per Subscribe measures the average spend required to generate one subscribe event from your TikTok ads. ## Formula **TikTok Cost per Subscribe** = **TikTok Ad Spend** ÷ **TikTok Subscribes** ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | [**TikTok Ad Spend**](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on TikTok advertising | | [**TikTok Subscribes**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-subscribes) | Number of subscribe events attributed to TikTok ads | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example A subscription box company spent **\$6,000** on TikTok ads in April and generated **240 new subscribers**. | Month | Ad Spend | Subscribes | Cost per Subscribe | | -------- | -------- | ---------- | ------------------ | | February | \$4,200 | 140 | \$30.00 | | March | \$5,000 | 180 | \$27.78 | | April | \$6,000 | 240 | \$25.00 | April's cost per subscribe of **\$25.00** shows a 10% improvement from refined audience targeting. *** ## How It Works TikTok tracks subscribe events when users complete subscription sign-ups attributed to your ads. This metric divides total ad spend by subscribe events to show your average acquisition cost per subscriber. *** ## When to Use | Scenario | Action | | --------------------- | ---------------------------------------------------------------------- | | Evaluating campaigns | Compare cost per subscribe across campaigns to identify top performers | | Budget planning | Calculate required spend for subscriber acquisition goals | | Creative testing | A/B test ad creatives and measure impact on subscription cost | | Audience optimization | Refine targeting to lower cost per subscribe | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | [TikTok Subscribes](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-subscribes) | Denominator—total subscribes driving this calculation | | [TikTok CPA](/reference/metrics/advertising/tiktok/tiktok-efficiency/tiktok-cpa) | Similar efficiency metric for purchase conversions | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Subscribes Value: Track Subscription Revenue from Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-subscribes-value Track total value of subscribe events attributed to your TikTok ads. Use subscribes value to measure subscription campaign performance and optimize ad spend. Total dollar value of subscribe events that TikTok attributes to your advertising campaigns. ## Formula **TikTok Subscribes Value** = **SUM** ( Subscribe Values ) ### Formula Components | Metric | Definition | | -------------------- | ------------------------------------------------------------------------ | | **Subscribe Values** | Dollar amounts assigned to individual subscribe events tracked by TikTok | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your TikTok campaigns generated **\$8,450 in subscription value** last month from 169 subscribe events. | Campaign | Subscribes | Value | Avg. Value | | ----------------- | ---------- | ----------- | ---------- | | Newsletter Signup | 102 | \$5,100 | \$50 | | Premium Tier | 67 | \$3,350 | \$50 | | **Total** | **169** | **\$8,450** | **\$50** | *** ## How It Works TikTok tracks subscribe events that occur after users interact with your ads within your attribution window. When a tracked subscribe event fires with an assigned value, TikTok records that value and attributes it to the ad that drove the conversion. *** ## When to Use | Scenario | Action | | ------------------------------ | -------------------------------------------------------------------- | | Measuring subscription revenue | Compare subscribes value across campaigns to identify top performers | | Evaluating cost efficiency | Divide value by Cost per Subscribe to assess return on acquisition | | Budget allocation | Shift spend toward campaigns generating highest subscription value | | Subscription campaign ROI | Compare subscribes value against ad spend to gauge profitability | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- | | [TikTok Subscribes](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-subscribes) | Count of subscribe events that generated this value | | [TikTok Cost per Subscribe](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-subscribes-cost) | Average spend per subscribe event | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok View Contents: Product Page Views from Ads Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-view-contents Track product page views attributed to TikTok ads. Measure top-of-funnel engagement and optimize your ad creative for browsing behavior. TikTok View Contents measures the number of product or content page views that TikTok attributes to your ads. ## Formula **TikTok View Contents** = **COUNT** ( TikTok-Attributed View Content Events ) ### Formula Components | Metric | Definition | | ----------------------------------------- | ---------------------------------------------------------------------------------------------- | | **TikTok-Attributed View Content Events** | ViewContent events fired when users visit product pages after interacting with your TikTok ads | | Metadata | | | --------------- | ----------------------------- | | **Type** | Number | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your skincare brand spent **\$2,500** on TikTok ads in March. TikTok attributed **8,420 view content events** to those ads. | Campaign | Spend | View Contents | Cost per View | | ----------- | ------- | ------------- | ------------- | | Spring Sale | \$1,200 | 4,850 | \$0.25 | | New Product | \$800 | 2,340 | \$0.34 | | Retargeting | \$500 | 1,230 | \$0.41 | *** ## How It Works TikTok fires a ViewContent event when a user visits a product detail page on your site after interacting with your ad. This metric counts all such events within TikTok's attribution window. It's a top-of-funnel signal showing how many users are actively browsing your products. *** ## When to Use | Scenario | Action | | ---------------------------- | ---------------------------------------------------------------------------- | | Evaluating ad creative | Compare view content rates across creatives to identify what drives browsing | | Measuring top-of-funnel | Track view contents as an early indicator of purchase intent | | Optimizing traffic campaigns | Use view content volume to gauge landing page engagement | | Diagnosing drop-off | Compare view contents to add-to-carts to find where users exit | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------- | | [TikTok Cost per View Content](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-view-contents-cost) | Cost efficiency of driving product views | | [TikTok Add to Carts](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-carts) | Next step in the funnel after viewing | | [TikTok Purchases](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases) | Final conversion from the funnel | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Cost per View Content: Top-of-Funnel Traffic Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-view-contents-cost Track cost per product page view from TikTok ads. Optimize top-of-funnel traffic spend by monitoring view content cost efficiency. TikTok Cost per View Content measures the average spend per product or content page view from your TikTok ads. ## Formula **TikTok Cost per View Content** = **TikTok Ad Spend** ÷ **TikTok View Contents** ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | [**TikTok Ad Spend**](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on TikTok advertising | | [**TikTok View Contents**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-view-contents) | Product page views attributed to TikTok ads | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example A skincare brand spent **\$2,400** on TikTok ads in February, generating **8,000 product page views**. | Period | Ad Spend | View Contents | Cost per View Content | | ------ | -------- | ------------- | --------------------- | | Week 1 | \$600 | 1,800 | \$0.33 | | Week 2 | \$600 | 2,100 | \$0.29 | | Week 3 | \$600 | 2,200 | \$0.27 | | Week 4 | \$600 | 1,900 | \$0.32 | *** ## How It Works Cost per View Content divides your total TikTok ad spend by the number of product page views TikTok attributes to your campaigns. A lower value indicates more efficient top-of-funnel traffic acquisition, meaning you're paying less for each potential customer to browse your products. *** ## When to Use | Scenario | Action | | --------------------- | ----------------------------------------------------- | | New creative testing | Compare cost per view across ad variations | | Audience optimization | Identify which audiences drive cheapest product views | | Budget allocation | Shift spend toward campaigns with lower view costs | | Funnel analysis | Compare against add-to-cart cost to measure drop-off | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | [TikTok View Contents](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-view-contents) | Denominator; total product page views | | [TikTok Cost per Add to Cart](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-carts-cost) | Next funnel stage efficiency metric | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok View Contents Value: Product View Revenue Tracking Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-view-contents-value Track the total catalog value of product pages viewed by visitors from your TikTok ads. Measure top-of-funnel engagement value. TikTok View Contents Value measures the combined catalog value of all product pages viewed by visitors from your TikTok ads. ## Formula **TikTok View Contents Value** = **SUM** ( View Content Values ) ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | [**View Content Values**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-view-contents) | Catalog price of each product viewed, attributed to TikTok ads | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example A home decor brand ran TikTok ads in March and drove **8,450 product page views** with a combined catalog value of **\$127,680**. | Week | View Contents | View Contents Value | Avg Value/View | | ------ | ------------- | ------------------- | -------------- | | Week 1 | 1,890 | \$28,350 | \$15.00 | | Week 2 | 2,240 | \$33,600 | \$15.00 | | Week 3 | 2,120 | \$31,800 | \$15.00 | | Week 4 | 2,200 | \$33,930 | \$15.42 | *** ## How It Works TikTok tracks the view\_content event when a visitor lands on a product page after engaging with your ad. The value is pulled from your product catalog—typically the listed price of the viewed item. This metric sums all product values across view events. *** ## When to Use | Scenario | Action | | --------------------------------- | ------------------------------------------------------------- | | Evaluate top-of-funnel value | Compare view value against add-to-cart value to gauge intent | | Assess product interest | High view value indicates visitors are browsing premium items | | Benchmark campaign creative | Higher-value views may indicate better audience targeting | | Calculate funnel conversion rates | Divide cart value by view value to measure progression | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | [TikTok View Contents](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-view-contents) | Count of product views (pair with value for avg view value) | | [TikTok Add to Carts Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-add-to-carts-value) | Next funnel stage—value of items added to cart | [See all TikTok Conversions metrics →](/reference/metrics/advertising/tiktok/tiktok-conversions) # TikTok Efficiency: ROAS and CPA Metrics Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-efficiency/index Track TikTok advertising efficiency with ROAS and CPA metrics. Measure return on ad spend and cost per acquisition for TikTok campaigns. Efficiency metrics measure the effectiveness of your TikTok ad spend—how much revenue you generate per dollar spent and how much each conversion costs. **Data Source:** [TikTok Ads](/sources/tiktok)\ **Metrics:** 2 ## Metrics in This Group | Metric | Description | When to Use | | ---------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------ | | [TikTok ROAS](/reference/metrics/advertising/tiktok/tiktok-efficiency/tiktok-roas) | Revenue per dollar spent (Purchases Value ÷ Spend) | Measure campaign profitability | | [TikTok CPA](/reference/metrics/advertising/tiktok/tiktok-efficiency/tiktok-cpa) | Cost per purchase (Spend ÷ Purchases) | Evaluate acquisition cost | ## How These Metrics Relate ROAS and CPA are inverse efficiency measures: * **TikTok ROAS** tells you how much revenue you earn per dollar spent (higher is better) * **TikTok CPA** tells you how much you spend per conversion (lower is better) Both depend on: * [TikTok Ad Spend](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) — your investment * [TikTok Purchases](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases) — conversions attributed * [TikTok Purchases Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases-value) — revenue attributed ## Choosing the Right Metric * **Revenue-focused analysis**: Use ROAS to measure dollar-for-dollar return * **Cost control**: Use CPA to track acquisition costs against targets * **Campaign optimization**: Compare both across ad sets to find efficient performers # TikTok CPA: Cost Per Acquisition Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-efficiency/tiktok-cpa Track TikTok CPA to measure how much you spend for each TikTok-attributed purchase. Lower CPA means more efficient ad spend. TikTok CPA measures how much you spend on average for each purchase TikTok attributes to your ads—lower is better. ## Formula **TikTok CPA** = **TikTok Spend** ÷ **TikTok Purchases** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | [**TikTok Spend**](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on TikTok ads | | [**TikTok Purchases**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases) | Number of purchases TikTok attributes to your ads | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your TikTok campaigns spent **\$12,000** and TikTok reported **400 attributed purchases**. | Metric | Value | Calculation | | ---------------- | ----------- | ---------------------- | | TikTok Spend | \$12,000 | Total ad spend | | TikTok Purchases | 400 | Attributed conversions | | **TikTok CPA** | **\$30.00** | \$12,000 ÷ 400 | *** ## How It Works TikTok CPA divides your total TikTok ad spend by the number of purchases TikTok attributes to those ads. This attribution uses TikTok's click and view windows to connect ad interactions with conversions. A lower CPA indicates more efficient customer acquisition from your TikTok advertising. *** ## When to Use | Scenario | Action | | ------------------------------ | --------------------------------------------------------------- | | Campaign efficiency comparison | Compare CPA across campaigns to identify top performers | | Budget allocation decisions | Shift budget toward campaigns with lower CPA | | Scaling evaluation | Monitor CPA as you increase spend to catch efficiency drops | | Creative testing | Use CPA to measure which ad creatives drive cheaper conversions | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | [TikTok ROAS](/reference/metrics/advertising/tiktok/tiktok-efficiency/tiktok-roas) | Revenue efficiency counterpart to cost efficiency | | [TikTok Spend](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Numerator in CPA calculation | | [TikTok Purchases](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases) | Denominator in CPA calculation | | [TikTok Purchases Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases-value) | Revenue generated from TikTok purchases | [See all TikTok Efficiency metrics →](/reference/metrics/advertising/tiktok/tiktok-efficiency) # TikTok ROAS: Return on Ad Spend Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-efficiency/tiktok-roas Track TikTok ROAS to measure revenue generated per dollar spent on TikTok ads. A ROAS of 3x means $3 in revenue for every $1 spent. TikTok ROAS measures revenue TikTok reports per dollar spent on ads—a ROAS of 3x means \$3 in attributed revenue for every \$1 spent. ## Formula **TikTok ROAS** = **TikTok Purchases Value** ÷ **TikTok Spend** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | [**TikTok Purchases Value**](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases-value) | Total revenue from purchases TikTok attributes to your ads | | [**TikTok Spend**](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on TikTok ads | | Metadata | | | --------------- | ----------------------------- | | **Type** | Multiplier | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your TikTok campaigns generated **\$45,000** in attributed revenue from **\$15,000** in ad spend. | Metric | Value | Calculation | | ---------------------- | -------- | ------------------- | | TikTok Purchases Value | \$45,000 | Attributed revenue | | TikTok Spend | \$15,000 | Total ad spend | | **TikTok ROAS** | **3.0x** | \$45,000 ÷ \$15,000 | *** ## How It Works TikTok ROAS divides the total revenue from TikTok-attributed purchases by your total TikTok ad spend. TikTok uses its click and view attribution windows to connect ad interactions with conversions and their associated order values. A ROAS above 1.0x means you're generating more revenue than you're spending on ads. *** ## When to Use | Scenario | Action | | --------------------------------- | ---------------------------------------------------------- | | Campaign profitability assessment | Identify campaigns generating positive returns | | Budget reallocation | Shift spend toward high-ROAS campaigns | | Scaling decisions | Monitor ROAS while increasing spend to maintain efficiency | | Cross-platform comparison | Compare TikTok ROAS against other channels | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | [TikTok CPA](/reference/metrics/advertising/tiktok/tiktok-efficiency/tiktok-cpa) | Cost efficiency counterpart to revenue efficiency | | [TikTok Purchases Value](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases-value) | Numerator in ROAS calculation | | [TikTok Spend](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Denominator in ROAS calculation | | [TikTok Purchases](/reference/metrics/advertising/tiktok/tiktok-conversions/tiktok-purchases) | Conversion count driving purchases value | [See all TikTok Efficiency metrics →](/reference/metrics/advertising/tiktok/tiktok-efficiency) # TikTok Engagement: Social Interaction and Community Metrics Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-engagement/index Track TikTok engagement metrics including follows, likes, comments, shares, and profile visits. Measure community growth and social engagement from TikTok campaigns. Engagement metrics measure how users interact with your TikTok ads through social actions like follows, likes, comments, and shares. Use these to evaluate brand awareness campaigns and community growth. **Data Source:** [TikTok Ads](/sources/tiktok)\ **Metrics:** 11 ## Metrics in This Group | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ---------------------------------------- | | [TikTok Follows](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-follows) | New followers from ads | Measure community growth | | [TikTok Cost per Follow](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-follows-cost) | Cost per new follower | Evaluate follower acquisition efficiency | | [TikTok Profile Visits](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-profile-visits) | Profile page visits from ads | Measure brand interest | | [TikTok Cost per Profile Visit](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-profile-visits-cost) | Cost per profile visit | Evaluate profile traffic cost | | [TikTok Engagements](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-engagements) | Total social interactions | Measure overall engagement | | [TikTok Cost per Engagement](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-engagements-cost) | Cost per engagement | Evaluate engagement efficiency | | [TikTok Engagement Rate](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-engagement-rate) | Engagements ÷ Impressions | Compare creative performance | | [TikTok Likes](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-likes) | Likes on ads | Measure positive sentiment | | [TikTok Comments](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-comments) | Comments on ads | Measure conversation | | [TikTok Shares](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-shares) | Shares of ads | Measure organic reach | ## How These Metrics Relate Engagement metrics form a hierarchy of user investment: 1. **TikTok Impressions** → Users see your ad 2. **TikTok Engagements** → Users interact (like, comment, share) 3. **TikTok Profile Visits** → Users visit your profile 4. **TikTok Follows** → Users join your community Calculated metrics: * **TikTok Engagement Rate** = Engagements ÷ Impressions × 100 * **TikTok Cost per Follow** = Spend ÷ Follows * **TikTok Cost per Engagement** = Spend ÷ Engagements ## Choosing the Right Metric * **Community growth**: Use Follows and Cost per Follow for follower campaigns * **Brand awareness**: Use Engagements and Engagement Rate for resonance * **Organic amplification**: Use Shares to measure viral potential * **Sentiment analysis**: Use Likes and Comments for audience feedback # TikTok Comments: Ad Engagement Metric Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-comments Track total comments on your TikTok ads. Measure deeper audience engagement and identify content that sparks conversation. Total comments left on your ad. Comments often indicate strong opinions or questions about your product. ## Formula **TikTok Comments** = **SUM** ( Comments ) || Metadata | | ||---|---| || **Type** | Number | || **Data Source** | [TikTok Ads](/sources/tiktok) | || **Aggregation** | Sum | *** ## Example Your product launch campaign received **1,847 comments** across all ad groups in June. | Campaign | Comments | Impressions | Comment Rate | | ---------------- | -------- | ----------- | ------------ | | Product Demo | 1,234 | 425,000 | 0.29% | | UGC Testimonials | 613 | 312,000 | 0.20% | *** ## How It Works TikTok counts each comment left on your ad by viewers. Comments indicate deeper engagement than likes—users take time to type a response. High comment counts often signal content that sparks curiosity, questions, or strong opinions about your product. *** ## When to Use | Scenario | Action | | ----------------------------- | ------------------------------------------------ | | Measuring content resonance | High comments indicate strong audience interest | | Identifying FAQ opportunities | Analyze comment themes to improve messaging | | Evaluating ad creative | Content that sparks discussion drives awareness | | Community building | Ads with many comments help build brand presence | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------ | ------------------------------------------------- | | [TikTok Engagements](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-engagements) | Total of all engagement types (includes comments) | | [TikTok Likes](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-likes) | Lighter engagement signal than comments | | [TikTok Shares](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-shares) | Indicates content worth spreading | [See all TikTok Engagement metrics →](/reference/metrics/advertising/tiktok/tiktok-engagement) # TikTok Engagement Rate: Measure Content Resonance Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-engagement-rate Calculate TikTok ad engagement rate as a percentage of impressions. Learn the formula, see benchmarks, and optimize your creative performance. Engagements divided by impressions. Higher rates indicate more compelling content. ## Formula **TikTok Engagement Rate** = ( **TikTok Engagements** ÷ **TikTok Impressions** ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | [**TikTok Engagements**](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-engagements) | Total interactions including likes, comments, shares, and clicks | | [**TikTok Impressions**](/reference/metrics/advertising/tiktok/tiktok-audience/tiktok-impressions) | Number of times your ads were displayed | || Metadata | | ||---|---| || **Type** | Percentage | || **Data Source** | [TikTok Ads](/sources/tiktok) | || **Aggregation** | Ratio | *** ## Example Your TikTok campaign delivered **2.4M impressions** with **86,400 engagements**, resulting in a **3.6% engagement rate**: | Ad Group | Impressions | Engagements | Engagement Rate | | ---------------- | ----------- | ----------- | --------------- | | Gen Z Creators | 1,200,000 | 54,000 | 4.5% | | Product Demo | 800,000 | 24,000 | 3.0% | | UGC Testimonials | 400,000 | 8,400 | 2.1% | *** ## How It Works TikTok Engagement Rate calculates the percentage of ad impressions that generate user interactions. Higher rates indicate more compelling content that resonates with your audience. TikTok's algorithm favors engaging content, so higher engagement rates often correlate with lower costs. *** ## When to Use | Scenario | Action | | ------------------------------ | ------------------------------------------------------- | | Comparing creative performance | Higher engagement rates signal better content resonance | | Optimizing for awareness | Target 3-5% engagement rate for top-funnel campaigns | | Identifying viral potential | Engagement rates above 5% indicate share-worthy content | | Reducing cost per result | Improve engagement to lower CPM and CPC | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | [TikTok Engagements](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-engagements) | Numerator in this calculation | | [TikTok Impressions](/reference/metrics/advertising/tiktok/tiktok-audience/tiktok-impressions) | Denominator in this calculation | | [TikTok Cost per Engagement](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-engagements-cost) | How much you pay for each engagement | [See all TikTok Engagement metrics →](/reference/metrics/advertising/tiktok/tiktok-engagement) # TikTok Engagements: Total Ad Interactions Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-engagements Track total social interactions on your TikTok ads including likes, comments, and shares. Measure creative resonance and audience engagement. All social interactions on your ad reported by TikTok, such as likes, comments, and shares. High engagement signals resonant creative. ## Formula **TikTok Engagements** = **SUM** ( Engagements ) || Metadata | | ||---|---| || **Type** | Number | || **Data Source** | [TikTok Ads](/sources/tiktok) | || **Aggregation** | Sum | *** ## Example Your TikTok campaign generated **12,450 engagements** last week: | Ad Creative | Engagements | Breakdown | | --------------- | ----------- | ------------------------------------- | | Product Demo | 5,200 | 3,800 likes, 950 comments, 450 shares | | UGC Testimonial | 4,850 | 4,100 likes, 420 comments, 330 shares | | Brand Story | 2,400 | 1,900 likes, 280 comments, 220 shares | *** ## How It Works TikTok Engagements counts all social interactions with your ads—likes, comments, and shares. High engagement signals that your creative resonates with your audience and indicates potential for organic reach through shares. *** ## When to Use | Scenario | Action | | --------------------------------- | ------------------------------------------- | | Evaluating creative performance | Compare engagements across ad variations | | Measuring brand awareness | Track engagement growth over time | | Identifying viral potential | High shares indicate content worth boosting | | Optimizing for community building | Prioritize creatives that spark comments | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | [TikTok Cost per Engagement](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-engagements-cost) | Cost efficiency of generating engagements | | [TikTok Engagement Rate](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-engagement-rate) | Engagements as percentage of impressions | | [TikTok Likes](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-likes) | Subset: positive reactions only | | [TikTok Shares](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-shares) | Subset: viral distribution actions | [See all TikTok Engagement metrics →](/reference/metrics/advertising/tiktok/tiktok-engagement) # TikTok Cost per Engagement: Ad Efficiency Metric Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-engagements-cost Track your TikTok cost per engagement to measure ad efficiency. Calculate average spend per like, comment, share, or follow on TikTok campaigns. Average spend per social interaction. Useful for evaluating brand awareness and community-building campaigns. ## Formula **TikTok Cost per Engagement** = **TikTok Spend** ÷ **TikTok Engagements** ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | [**TikTok Spend**](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on TikTok ads | | [**TikTok Engagements**](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-engagements) | Total likes, comments, shares, and follows on ads | || Metadata | | ||---|---| || **Type** | Currency | || **Data Source** | [TikTok Ads](/sources/tiktok) | || **Aggregation** | Ratio | *** ## Example A beauty brand's TikTok campaign spent **\$2,400** and generated **12,000 engagements** over two weeks. | Metric | Value | Calculation | | ----------------------- | ---------- | ----------------------------------- | | Ad Spend | \$2,400 | — | | Engagements | 12,000 | Likes + comments + shares + follows | | **Cost per Engagement** | **\$0.20** | \$2,400 ÷ 12,000 | *** ## How It Works TikTok reports total engagements (likes, comments, shares, follows) for your ads. Upstack divides your total ad spend by total engagements to calculate the average cost per social interaction. *** ## When to Use | Scenario | Action | | ----------------------------------- | ----------------------------------------------------- | | Running brand awareness campaigns | Track if engagement costs are sustainable | | Comparing creative performance | Lower cost/engagement indicates more resonant content | | Budgeting for community growth | Estimate spend needed to hit engagement targets | | Evaluating influencer-style content | Measure audience interaction efficiency | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [TikTok Engagements](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-engagements) | Denominator in this calculation | | [TikTok Engagement Rate](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-engagement-rate) | Measures engagement as percentage of impressions | | [TikTok Spend](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Numerator in this calculation | [See all TikTok Engagement metrics →](/reference/metrics/advertising/tiktok/tiktok-engagement) # TikTok Follows: Follower Acquisition Metric Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-follows Track new followers gained from your TikTok ads. Measure community growth and brand account interest from paid campaigns. How many users followed your TikTok account after seeing your ad. ## Formula **TikTok Follows** = **SUM** ( Follows ) || Metadata | | ||---|---| || **Type** | Number | || **Data Source** | [TikTok Ads](/sources/tiktok) | || **Aggregation** | Sum | *** ## Example Your brand awareness campaign generated **2,847 new followers** across all ad groups in June. | Campaign | Follows | Impressions | Follow Rate | | -------------- | ------- | ----------- | ----------- | | Brand Story | 1,534 | 425,000 | 0.36% | | Creator Collab | 913 | 312,000 | 0.29% | | Product Demo | 400 | 180,000 | 0.22% | *** ## How It Works TikTok counts each time a viewer taps the follow button on your ad or navigates to your profile from the ad and follows. Follows indicate strong brand interest—users want to see more of your content in their feed. This builds long-term organic reach. *** ## When to Use | Scenario | Action | | ------------------------------ | ------------------------------------------------ | | Measuring community growth | Track follower acquisition from paid campaigns | | Evaluating brand interest | High follows indicate strong brand appeal | | Comparing creative performance | Content that drives follows builds lasting value | | Planning organic strategy | More followers means more organic reach | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | | [TikTok Cost per Follow](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-follows-cost) | Cost efficiency of follower acquisition | | [TikTok Engagements](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-engagements) | Total of all engagement types (includes follows) | | [TikTok Profile Visits](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-profile-visits) | Users who visited your profile (may or may not follow) | [See all TikTok Engagement metrics →](/reference/metrics/advertising/tiktok/tiktok-engagement) # TikTok Cost per Follow: Follower Acquisition Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-follows-cost Track the cost per new follower from TikTok ads. Measure follower acquisition efficiency and optimize your community-building campaigns. Average spend per new follower from TikTok ads. ## Formula **TikTok Cost per Follow** = **TikTok Spend** ÷ **TikTok Follows** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------- | ---------------------------------------------- | | [**TikTok Spend**](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on TikTok ads | | [**TikTok Follows**](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-follows) | Number of new followers gained from TikTok ads | || Metadata | | ||---|---| || **Type** | Currency | || **Data Source** | [TikTok Ads](/sources/tiktok) | || **Aggregation** | Ratio | *** ## Example A beauty brand ran follower-focused campaigns in April with **\$2,400 in TikTok spend** generating **800 new followers**. | Campaign | Spend | Follows | Cost per Follow | | ----------------- | ----------- | ------- | --------------- | | Spring Launch | \$1,200 | 500 | \$2.40 | | Influencer Collab | \$800 | 250 | \$3.20 | | Tutorial Series | \$400 | 50 | \$8.00 | | **Total** | **\$2,400** | **800** | **\$3.00** | *** ## How It Works TikTok Cost per Follow divides your total ad spend by the number of new followers attributed to your ads. This metric helps you understand the efficiency of campaigns optimized for community growth and brand awareness. *** ## When to Use | Scenario | Action | | ---------------------------- | --------------------------------------------------------- | | Comparing follower campaigns | Identify which creatives drive followers most efficiently | | Budget allocation | Shift spend toward lower cost-per-follow campaigns | | Community growth strategy | Track follower acquisition costs over time | | Influencer partnerships | Measure follower efficiency of creator collaborations | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------- | ------------------------------- | | [TikTok Follows](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-follows) | Denominator in this calculation | | [TikTok Spend](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Numerator in this calculation | | [TikTok Cost per Engagement](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-engagements-cost) | Broader engagement cost metric | [See all TikTok Engagement metrics →](/reference/metrics/advertising/tiktok/tiktok-engagement) # TikTok Likes: Ad Engagement Metric Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-likes Track total likes on your TikTok ads. Measure audience approval and basic positive engagement signals across campaigns. Total likes on your ad. Likes are a basic positive engagement signal. ## Formula **TikTok Likes** = **SUM** ( Likes ) || Metadata | | ||---|---| || **Type** | Number | || **Data Source** | [TikTok Ads](/sources/tiktok) | || **Aggregation** | Sum | *** ## Example Your summer collection campaign received **12,847 likes** across all ad groups in June. | Campaign | Likes | Impressions | Like Rate | | ------------ | ----- | ----------- | --------- | | Summer Sale | 8,234 | 425,000 | 1.94% | | New Arrivals | 4,613 | 312,000 | 1.48% | *** ## How It Works TikTok counts each time a viewer taps the like (heart) button on your ad. One user can only like an ad once, making likes a unique engagement signal. Likes are aggregated at the campaign, ad group, or ad level. *** ## When to Use | Scenario | Action | | ------------------------------ | ------------------------------------------- | | Comparing creative performance | Higher likes indicate more resonant content | | Benchmarking engagement | Compare like rates across ad sets | | Identifying viral potential | Ads with high likes may spread organically | | Evaluating brand sentiment | Likes signal positive audience reception | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------ | ------------------------------------------------ | | [TikTok Engagements](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-engagements) | Total of all engagement types (includes likes) | | [TikTok Comments](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-comments) | Deeper engagement signal than likes | | [TikTok Shares](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-shares) | Highest engagement signal; extends organic reach | [See all TikTok Engagement metrics →](/reference/metrics/advertising/tiktok/tiktok-engagement) # TikTok Profile Visits: Profile Traffic Metric Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-profile-visits Track how many users visited your TikTok profile after seeing your ad. Measure brand interest and profile engagement from paid campaigns. How many users visited your TikTok profile after seeing your ad. ## Formula **TikTok Profile Visits** = **SUM** ( Profile Visits ) || Metadata | | ||---|---| || **Type** | Number | || **Data Source** | [TikTok Ads](/sources/tiktok) | || **Aggregation** | Sum | *** ## Example Your brand campaign drove **4,532 profile visits** across all ad groups in June. | Campaign | Profile Visits | Impressions | Visit Rate | | ------------ | -------------- | ----------- | ---------- | | Brand Story | 2,156 | 425,000 | 0.51% | | Product Demo | 1,534 | 312,000 | 0.49% | | UGC Content | 842 | 180,000 | 0.47% | *** ## How It Works TikTok counts each time a viewer taps on your profile from an ad. Profile visits indicate strong brand curiosity—users want to learn more about your brand before following or purchasing. This is a mid-funnel signal between ad view and follow. *** ## When to Use | Scenario | Action | | ------------------------ | --------------------------------------------------------- | | Measuring brand interest | High profile visits indicate curiosity about your brand | | Evaluating ad creative | Content that drives profile visits builds brand awareness | | Comparing funnel stages | Compare profile visits to follows to measure conversion | | Optimizing for discovery | Prioritize content that encourages profile exploration | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | [TikTok Cost per Profile Visit](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-profile-visits-cost) | Cost efficiency of driving profile traffic | | [TikTok Follows](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-follows) | Users who followed after visiting profile | | [TikTok Engagements](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-engagements) | Total of all engagement types | [See all TikTok Engagement metrics →](/reference/metrics/advertising/tiktok/tiktok-engagement) # TikTok Cost per Profile Visit: Profile Traffic Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-profile-visits-cost Track the cost per profile visit from TikTok ads. Measure efficiency of driving users to your TikTok profile from paid campaigns. Average spend per profile visit from TikTok ads. ## Formula **TikTok Cost per Profile Visit** = **TikTok Spend** ÷ **TikTok Profile Visits** ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [**TikTok Spend**](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on TikTok ads | | [**TikTok Profile Visits**](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-profile-visits) | Number of users who visited your TikTok profile from ads | || Metadata | | ||---|---| || **Type** | Currency | || **Data Source** | [TikTok Ads](/sources/tiktok) | || **Aggregation** | Ratio | *** ## Example A fashion brand ran profile-focused campaigns in April with **\$3,000 in TikTok spend** generating **2,500 profile visits**. | Campaign | Spend | Profile Visits | Cost per Visit | | ---------------- | ----------- | -------------- | -------------- | | Brand Story | \$1,500 | 1,500 | \$1.00 | | Creator Collab | \$1,000 | 750 | \$1.33 | | Product Showcase | \$500 | 250 | \$2.00 | | **Total** | **\$3,000** | **2,500** | **\$1.20** | *** ## How It Works TikTok Cost per Profile Visit divides your total ad spend by the number of profile visits attributed to your ads. This metric helps you understand the efficiency of campaigns designed to drive brand discovery and profile exploration. *** ## When to Use | Scenario | Action | | ------------------------------ | -------------------------------------------------------------- | | Comparing brand campaigns | Identify which creatives drive profile visits most efficiently | | Budget allocation | Shift spend toward lower cost-per-visit campaigns | | Measuring discovery efficiency | Track profile visit costs over time | | Funnel analysis | Compare cost per profile visit to cost per follow | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | | [TikTok Profile Visits](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-profile-visits) | Denominator in this calculation | | [TikTok Spend](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Numerator in this calculation | | [TikTok Cost per Follow](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-follows-cost) | Related efficiency metric for follower acquisition | [See all TikTok Engagement metrics →](/reference/metrics/advertising/tiktok/tiktok-engagement) # TikTok Shares: Ad Engagement Metric Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-shares Track how many times your TikTok ads were shared. Measure viral potential and organic reach extension from paid campaigns. How many times your ad was shared. Shares extend your audience organically at no extra cost. ## Formula **TikTok Shares** = **SUM** ( Shares ) || Metadata | | ||---|---| || **Type** | Number | || **Data Source** | [TikTok Ads](/sources/tiktok) | || **Aggregation** | Sum | *** ## Example Your brand campaign generated **3,245 shares** across all ad groups in June. | Campaign | Shares | Impressions | Share Rate | | --------------- | ------ | ----------- | ---------- | | Viral Challenge | 2,156 | 425,000 | 0.51% | | Product Demo | 734 | 312,000 | 0.24% | | Brand Story | 355 | 180,000 | 0.20% | *** ## How It Works TikTok counts each time a viewer shares your ad to their followers, friends, or other platforms. Shares represent the highest level of engagement—users actively distribute your content to their network. Each share extends your organic reach at no additional cost. *** ## When to Use | Scenario | Action | | ------------------------------- | ------------------------------------------------ | | Identifying viral content | High share rates indicate content worth boosting | | Measuring organic amplification | Shares extend reach beyond paid impressions | | Comparing creative performance | Shareable content resonates most with audiences | | Optimizing for awareness | Prioritize ad formats that encourage sharing | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------ | ----------------------------------------------- | | [TikTok Engagements](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-engagements) | Total of all engagement types (includes shares) | | [TikTok Likes](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-likes) | Lighter engagement signal than shares | | [TikTok Comments](/reference/metrics/advertising/tiktok/tiktok-engagement/tiktok-comments) | Indicates audience discussion and interest | [See all TikTok Engagement metrics →](/reference/metrics/advertising/tiktok/tiktok-engagement) # TikTok Spend: Ad Budget and Cost Metrics Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-spend/index Track TikTok ad spend metrics in Upstack. Monitor your TikTok Ads budget consumption and understand how your advertising dollars are allocated. Spend metrics track how much you're investing in TikTok advertising. Use these to monitor budget consumption and compare costs across campaigns. **Data Source:** [TikTok Ads](/sources/tiktok)\ **Metrics:** 1 ## Metrics in This Group | Metric | Description | When to Use | | ---------------------------------------------------------------------------------- | -------------------------------- | ------------------------ | | [TikTok Ad Spend](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on TikTok ads | Track budget consumption | ## How These Metrics Relate TikTok Ad Spend is the foundation metric for all efficiency calculations: * **TikTok ROAS** = TikTok Purchases Value ÷ TikTok Ad Spend * **TikTok CPA** = TikTok Ad Spend ÷ TikTok Purchases * **TikTok CPC** = TikTok Ad Spend ÷ TikTok Clicks * **TikTok CPM** = TikTok Ad Spend ÷ TikTok Impressions × 1,000 ## Choosing the Right Metric * **Budget tracking**: Use TikTok Ad Spend to monitor how much TikTok has billed you * **Efficiency analysis**: Combine with [TikTok Efficiency](/reference/metrics/advertising/tiktok/tiktok-efficiency) metrics (ROAS, CPA) * **Cost comparison**: Compare spend across campaigns to identify budget allocation # TikTok Spend: Total Advertising Investment Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend Track your total TikTok advertising spend. Monitor budget consumption across campaigns to optimize ad investment and maintain spend efficiency. TikTok Spend measures the total ad budget consumed by TikTok during the selected period—this is what TikTok billed you. ## Formula **TikTok Spend** = **SUM** ( Ad Spend ) | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example **Your brand spent \$12,450 on TikTok ads in March across three campaign objectives:** | Campaign Type | Spend | Share of Budget | | -------------------- | ------- | --------------- | | Conversion campaigns | \$7,800 | 62.7% | | Traffic campaigns | \$3,200 | 25.7% | | Video view campaigns | \$1,450 | 11.6% | *** ## How It Works TikTok Spend reflects the actual costs billed by TikTok for your advertising. This is a raw value pulled directly from the TikTok Ads API—it includes all spend across campaigns, ad groups, and ads within your selected date range and filters. *** ## When to Use | Scenario | Action | | ------------------------ | -------------------------------------------------- | | Budget tracking | Monitor daily/weekly spend against planned budgets | | ROAS calculation | Compare spend to attributed revenue for efficiency | | Campaign allocation | Identify which campaigns consume the most budget | | Cost per action analysis | Divide spend by conversions to calculate CPA | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------- | ------------------------------------------------- | | [TikTok CPM](/reference/metrics/advertising/tiktok/tiktok-audience/tiktok-cpm) | Cost per thousand impressions—efficiency of reach | | [TikTok CPC](/reference/metrics/advertising/tiktok/tiktok-clicks/tiktok-cpc) | Cost per click—traffic efficiency | | [TikTok ROAS](/reference/metrics/advertising/tiktok/tiktok-efficiency/tiktok-roas) | Revenue generated per dollar spent | [See all TikTok Spend metrics →](/reference/metrics/advertising/tiktok/tiktok-spend) # TikTok Video: Video Engagement and Completion Metrics Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-video/index Track TikTok video ad performance with plays, views, completion rates, and costs. Measure video engagement at every stage of viewer retention. Video metrics measure how users watch your TikTok video ads—from initial plays to full completions. Use these to optimize video creative and understand viewer retention. **Data Source:** [TikTok Ads](/sources/tiktok)\ **Metrics:** 9 ## Metrics in This Group | Metric | Description | When to Use | | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------- | -------------------------- | | [TikTok Video Plays](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-plays) | Total video starts (including auto-play) | Measure video exposure | | [TikTok Video Views](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-views) | Views of at least 6 seconds | Standard view metric | | [TikTok Cost per Video View](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-views-cost) | Cost per 6-second view | Evaluate view efficiency | | [TikTok 15s Video Views](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-views-15s) | Views of at least 15 seconds | Measure engaged views | | [TikTok Cost per 15s View](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-views-15s-cost) | Cost per 15-second view | Evaluate engaged view cost | | [TikTok Video 25% Views](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-p25-watched) | Views to 25% completion | Early retention metric | | [TikTok Video 50% Views](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-p50-watched) | Views to 50% completion | Mid-video retention | | [TikTok Video 75% Views](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-p75-watched) | Views to 75% completion | Strong retention metric | | [TikTok Video Completions](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-completions) | Views to 100% completion | Full video engagement | ## How These Metrics Relate Video metrics form a retention funnel: ``` Video Plays → Video Views (6s) → 25% → 50% → 75% → 100% Completion ``` * **Video Plays** > **Video Views** because plays include very short watches * Each completion tier is a subset of the previous * Drop-off between tiers reveals where viewers lose interest ## Choosing the Right Metric * **Awareness campaigns**: Use Video Views (6s) as the standard metric * **Engagement optimization**: Compare 25%/50%/75%/100% completion rates * **Creative testing**: High plays but low completions suggest hook issues * **Cost analysis**: Use Cost per View metrics to compare efficiency # TikTok Video Completions: 100% Watched Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-completions Track TikTok views where viewers watched your entire video. Measure the strongest video engagement signal for your campaigns. TikTok Video Completions counts views where viewers watched your entire video from start to finish — the strongest video engagement signal. ## Formula **TikTok Video Completions** = **SUM** ( Video Completions ) ### Formula Components | Metric | Definition | | --------------------- | ------------------------------------------------ | | **Video Completions** | Each instance a viewer watched 100% of the video | | Metadata | | | --------------- | ----------------------------- | | **Type** | Number | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your campaign generated **107,100 at 75%** with **85,680 full completions** — an 80% conversion from three-quarters to finish. | Video Length | 75% Views | Completions | Completion Rate | | ------------ | ----------- | ----------- | --------------- | | 15 seconds | 45,900 | 41,310 | 90.0% | | 30 seconds | 38,200 | 30,560 | 80.0% | | 60 seconds | 23,000 | 13,810 | 60.0% | | **Total** | **107,100** | **85,680** | **80.0%** | *** ## How It Works TikTok counts a completion when a viewer watches your video all the way through. This is the ultimate engagement metric — these viewers received your full message, saw your complete story, and experienced your entire call-to-action. Completion rates vary significantly by video length: shorter videos naturally achieve higher completion rates. *** ## When to Use | Scenario | Action | | ---------------------------- | -------------------------------------------------------- | | Full message delivery | Completions confirm viewers absorbed your entire message | | Video length optimization | Compare completion rates across video lengths | | High-value audience building | Create retargeting audiences from video completers | | Content effectiveness | High completions indicate compelling content throughout | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | [TikTok Video 75% Completion Views](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-p75-watched) | Previous stage in the completion funnel | | [TikTok Video Plays](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-plays) | Starting point for calculating overall completion rate | | [TikTok Video Views](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-views) | 6-second views for comparison | [See all TikTok Video metrics →](/reference/metrics/advertising/tiktok/tiktok-video) # TikTok Video 25% Completion Views: Quarter Watched Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-p25-watched Track TikTok views where viewers watched at least 25% of your video. Measure early video retention in your completion funnel. TikTok Video 25% Completion Views counts views where viewers watched at least a quarter of your video — part of the completion rate funnel. ## Formula **TikTok Video 25% Completion Views** = **SUM** ( 25% Completion Views ) ### Formula Components | Metric | Definition | | ------------------------ | -------------------------------------------------------- | | **25% Completion Views** | Each instance a viewer watched at least 25% of the video | | Metadata | | | --------------- | ----------------------------- | | **Type** | Number | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your 60-second video ad achieved **425,000 plays** with **297,500 reaching 25%** completion — a 70% first-quarter retention rate. | Video Length | Plays | 25% Views | 25% Rate | | ------------ | ----------- | ----------- | --------- | | 15 seconds | 185,000 | 148,000 | 80.0% | | 30 seconds | 145,000 | 101,500 | 70.0% | | 60 seconds | 95,000 | 48,000 | 50.5% | | **Total** | **425,000** | **297,500** | **70.0%** | *** ## How It Works TikTok tracks when viewers reach the 25% mark of your video. This represents the first stage of the completion funnel and measures initial content retention. For a 60-second video, 25% completion means 15 seconds watched. High 25% rates indicate your opening hook is effective. *** ## When to Use | Scenario | Action | | ------------------- | ---------------------------------------------------------- | | Hook effectiveness | High 25% rates mean your opening seconds capture attention | | Funnel diagnostics | Compare 25% → 50% → 75% → 100% to find drop-off points | | Content pacing | Low 25% rates suggest the intro needs improvement | | A/B testing openers | Test different hooks and compare 25% completion rates | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | [TikTok Video Plays](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-plays) | Starting point for the completion funnel | | [TikTok Video 50% Completion Views](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-p50-watched) | Next stage in the completion funnel | | [TikTok Video Completions](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-completions) | Final stage — 100% completion | [See all TikTok Video metrics →](/reference/metrics/advertising/tiktok/tiktok-video) # TikTok Video 50% Completion Views: Half Watched Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-p50-watched Track TikTok views where viewers watched at least 50% of your video. Measure mid-video engagement in your completion funnel. TikTok Video 50% Completion Views counts views where viewers watched at least half of your video — indicating moderate viewing engagement. ## Formula **TikTok Video 50% Completion Views** = **SUM** ( 50% Completion Views ) ### Formula Components | Metric | Definition | | ------------------------ | -------------------------------------------------------- | | **50% Completion Views** | Each instance a viewer watched at least 50% of the video | | Metadata | | | --------------- | ----------------------------- | | **Type** | Number | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your campaign videos achieved **297,500 at 25%** with **178,500 reaching 50%** — a 60% retention from quarter to halfway. | Video | 25% Views | 50% Views | 25→50% Retention | | ------------ | ----------- | ----------- | ---------------- | | Product Demo | 148,000 | 96,200 | 65.0% | | Brand Story | 101,500 | 55,825 | 55.0% | | Tutorial | 48,000 | 26,475 | 55.2% | | **Total** | **297,500** | **178,500** | **60.0%** | *** ## How It Works TikTok records a 50% completion when viewers reach the midpoint of your video. This metric measures sustained engagement beyond the initial hook. For a 60-second video, 50% completion means 30 seconds watched. The 50% mark is critical for delivering your core message. *** ## When to Use | Scenario | Action | | ----------------------- | ------------------------------------------------------------------ | | Mid-video retention | High 50% rates indicate content holds attention through the middle | | Content pacing analysis | Large 25%→50% drop suggests mid-video content needs work | | Message delivery timing | Ensure key information appears before the 50% mark | | Comparing video lengths | Shorter videos often have higher 50% rates | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | [TikTok Video 25% Completion Views](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-p25-watched) | Previous stage in the completion funnel | | [TikTok Video 75% Completion Views](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-p75-watched) | Next stage in the completion funnel | | [TikTok Video Completions](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-completions) | Final stage — 100% completion | [See all TikTok Video metrics →](/reference/metrics/advertising/tiktok/tiktok-video) # TikTok Video 75% Completion Views: Three-Quarters Watched Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-p75-watched Track TikTok views where viewers watched at least 75% of your video. Measure strong content retention near completion. TikTok Video 75% Completion Views counts views where viewers watched at least three quarters of your video — signaling strong content retention. ## Formula **TikTok Video 75% Completion Views** = **SUM** ( 75% Completion Views ) ### Formula Components | Metric | Definition | | ------------------------ | -------------------------------------------------------- | | **75% Completion Views** | Each instance a viewer watched at least 75% of the video | | Metadata | | | --------------- | ----------------------------- | | **Type** | Number | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your campaign achieved **178,500 at 50%** with **107,100 reaching 75%** — viewers who made it halfway are 60% likely to reach three-quarters. | Video | 50% Views | 75% Views | 50→75% Retention | | ------------ | ----------- | ----------- | ---------------- | | Product Demo | 96,200 | 62,530 | 65.0% | | Brand Story | 55,825 | 30,704 | 55.0% | | Tutorial | 26,475 | 13,866 | 52.4% | | **Total** | **178,500** | **107,100** | **60.0%** | *** ## How It Works TikTok records a 75% completion when viewers reach three-quarters through your video. This metric identifies highly engaged viewers who are likely to complete. For a 60-second video, 75% completion means 45 seconds watched. These viewers have absorbed most of your content. *** ## When to Use | Scenario | Action | | --------------------------- | -------------------------------------------------------------- | | High-intent audience sizing | 75% viewers are your most engaged audience segment | | Call-to-action placement | Viewers reaching 75% are primed for your CTA | | Content quality assessment | High 75% rates indicate compelling content throughout | | Completion prediction | 75% viewers usually complete — low 75%→100% drop-off is normal | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | [TikTok Video 50% Completion Views](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-p50-watched) | Previous stage in the completion funnel | | [TikTok Video Completions](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-completions) | Final stage — 100% completion | | [TikTok Video 25% Completion Views](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-p25-watched) | First stage of the completion funnel | [See all TikTok Video metrics →](/reference/metrics/advertising/tiktok/tiktok-video) # TikTok Video Plays: Total Video Start Count Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-plays Track total TikTok video plays including auto-plays. Understand initial video engagement before the 6-second view threshold. TikTok Video Plays counts the total times your video started playing, including auto-plays — higher than views because very short watches are excluded from "views". ## Formula **TikTok Video Plays** = **SUM** ( Video Plays ) ### Formula Components | Metric | Definition | | --------------- | ------------------------------------------------------- | | **Video Plays** | Each instance a video starts playing in the TikTok feed | | Metadata | | | --------------- | ----------------------------- | | **Type** | Number | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your TikTok campaign generated **847,500 video plays** across all ad groups last week. | Ad Group | Video Plays | Video Views | Play-to-View Rate | | -------------------- | ----------- | ----------- | ----------------- | | Awareness Creative A | 425,000 | 312,000 | 73.4% | | Awareness Creative B | 312,500 | 198,000 | 63.4% | | Awareness Creative C | 110,000 | 84,000 | 76.4% | | **Total** | **847,500** | **594,000** | **70.1%** | *** ## How It Works TikTok counts a play the moment your video starts, including auto-plays as users scroll through their feed. This number is always higher than Video Views because plays include viewers who watch less than 6 seconds. The gap between plays and views indicates how many users scroll past quickly. *** ## When to Use | Scenario | Action | | ------------------------- | ------------------------------------------------------------------ | | Measuring raw reach | Compare plays across campaigns to understand total exposure | | Analyzing scroll behavior | High plays with low views means users aren't stopping to watch | | Creative testing | Use play-to-view ratio to identify which thumbnails grab attention | | Funnel analysis | Plays → Views → Completions shows the full engagement funnel | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------- | -------------------------------------- | | [TikTok Video Views](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-views) | Views that pass the 6-second threshold | | [TikTok Video Completions](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-completions) | Users who watched the entire video | | [TikTok Impressions](/reference/metrics/advertising/tiktok/tiktok-delivery/tiktok-impressions) | Total times ads were shown | [See all TikTok Video metrics →](/reference/metrics/advertising/tiktok/tiktok-video) # TikTok Video Views: 6-Second View Count Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-views Track TikTok video views with the 6-second threshold. Measure meaningful video engagement for your TikTok ad campaigns. TikTok Video Views counts how many times your video ad was watched for at least 6 seconds — TikTok's default view threshold. ## Formula **TikTok Video Views** = **SUM** ( Video Views ) ### Formula Components | Metric | Definition | | --------------- | ------------------------------------------------------- | | **Video Views** | Each instance a video is watched for at least 6 seconds | | Metadata | | | --------------- | ----------------------------- | | **Type** | Number | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your TikTok awareness campaign generated **594,000 video views** in Q1. | Month | Video Views | Spend | Cost per View | | ------------ | ----------- | ------------ | ------------- | | January | 185,000 | \$4,625 | \$0.025 | | February | 198,000 | \$4,752 | \$0.024 | | March | 211,000 | \$4,853 | \$0.023 | | **Q1 Total** | **594,000** | **\$14,230** | **\$0.024** | *** ## How It Works TikTok registers a view when a user watches your video for at least 6 continuous seconds. This threshold filters out accidental scrolls and brief glances, providing a more meaningful engagement metric than raw plays. The 6-second view is TikTok's standard metric for video awareness campaigns. *** ## When to Use | Scenario | Action | | -------------------- | ----------------------------------------------------------- | | Awareness campaigns | Primary KPI for video awareness objectives | | Budget optimization | Use cost per view to compare campaign efficiency | | Creative performance | Higher views relative to plays indicates compelling content | | Platform comparison | Compare TikTok's 6s views against Meta's 3s ThruPlays | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | [TikTok Video Plays](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-plays) | Total starts including sub-6s watches | | [TikTok Cost per Video View](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-views-cost) | Efficiency metric for video views | | [TikTok 15-Second Video Views](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-views-15s) | Deeper engagement metric (15s threshold) | [See all TikTok Video metrics →](/reference/metrics/advertising/tiktok/tiktok-video) # TikTok 15-Second Video Views: Extended View Count Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-views-15s Track TikTok video views with the 15-second threshold. Measure deeper video engagement beyond the standard 6-second view. TikTok 15-Second Video Views counts views where the viewer watched at least 15 continuous seconds — indicating deeper engagement than the 6-second threshold. ## Formula **TikTok 15-Second Video Views** = **SUM** ( 15-Second Video Views ) ### Formula Components | Metric | Definition | | ------------------------- | ------------------------------------------------------------------- | | **15-Second Video Views** | Each instance a video is watched for at least 15 continuous seconds | | Metadata | | | --------------- | ----------------------------- | | **Type** | Number | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Sum | *** ## Example Your campaign generated **185,400 fifteen-second views** from **594,000 total video views** — a 31.2% retention rate. | Ad Group | Video Views | 15s Views | 15s Rate | | -------------- | ----------- | ----------- | --------- | | Tutorial Style | 198,000 | 79,200 | 40.0% | | UGC Creative | 245,000 | 68,600 | 28.0% | | Product Demo | 151,000 | 37,600 | 24.9% | | **Total** | **594,000** | **185,400** | **31.2%** | *** ## How It Works TikTok records a 15-second view when a user watches at least 15 continuous seconds of your video. This metric filters for genuinely engaged viewers who chose to keep watching beyond the initial hook. The 15-second threshold is especially meaningful for longer-form content where you need sustained attention to deliver your message. *** ## When to Use | Scenario | Action | | ------------------------ | ------------------------------------------------------------------ | | Content quality analysis | Higher 15s rates indicate compelling content beyond the hook | | Engaged view campaigns | Primary KPI when optimizing for sustained attention | | Message delivery | Verify viewers are watching long enough to receive key information | | Creative comparison | Compare 6s-to-15s retention across different creative approaches | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | | [TikTok Video Views](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-views) | Standard 6-second view count | | [TikTok Cost per 15-Second Video View](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-views-15s-cost) | Efficiency metric for 15s views | | [TikTok Video 25% Completion Views](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-p25-watched) | Percentage-based completion metric | [See all TikTok Video metrics →](/reference/metrics/advertising/tiktok/tiktok-video) # TikTok Cost per 15-Second Video View: Extended CPV Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-views-15s-cost Calculate TikTok cost per 15-second video view. Optimize spend for engaged video view campaigns with this deeper engagement metric. TikTok Cost per 15-Second Video View measures the average spend per 15-second video view — useful when optimizing for engaged video view campaigns. ## Formula **TikTok Cost per 15s View** = **TikTok Spend** ÷ **TikTok 15s Video Views** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [**TikTok Spend**](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on TikTok ads | | [**TikTok 15s Video Views**](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-views-15s) | Video views that reached the 15-second threshold | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your campaign spent **\$14,230** and generated **185,400 fifteen-second views**, resulting in a cost per 15s view of **\$0.077**. | Campaign | Spend | 15s Views | Cost per 15s View | | ---------------- | ------------ | ----------- | ----------------- | | Brand Story | \$5,200 | 81,250 | \$0.064 | | Product Tutorial | \$4,800 | 60,000 | \$0.080 | | User Testimonial | \$4,230 | 44,150 | \$0.096 | | **Total** | **\$14,230** | **185,400** | **\$0.077** | *** ## How It Works TikTok Cost per 15-Second Video View divides your total ad spend by the number of 15-second views. This metric measures the efficiency of acquiring deeply engaged viewers. Expect this CPV to be higher than standard 6-second CPV since fewer viewers reach the 15-second threshold. *** ## When to Use | Scenario | Action | | ------------------------------ | ----------------------------------------------------------- | | Engaged view optimization | Primary efficiency metric for sustained attention campaigns | | Content investment decisions | Lower 15s CPV justifies investment in longer-form content | | Quality vs. quantity tradeoffs | Balance 6s CPV (reach) against 15s CPV (engagement) | | Budget forecasting | Estimate costs for engaged view objectives | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------- | ------------------------------------ | | [TikTok Spend](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Numerator in the calculation | | [TikTok 15-Second Video Views](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-views-15s) | Denominator in the calculation | | [TikTok Cost per Video View](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-views-cost) | Standard 6-second CPV for comparison | [See all TikTok Video metrics →](/reference/metrics/advertising/tiktok/tiktok-video) # TikTok Cost per Video View: CPV Efficiency Source: https://docs.upstackdata.com/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-views-cost Calculate TikTok cost per video view. Optimize your video awareness campaign spend with this standard CPV efficiency metric. TikTok Cost per Video View measures the average spend per 6-second video view — the standard cost metric for video awareness campaigns. ## Formula **TikTok Cost per Video View** = **TikTok Spend** ÷ **TikTok Video Views** ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------- | ----------------------------------------------- | | [**TikTok Spend**](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Total amount spent on TikTok ads | | [**TikTok Video Views**](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-views) | Video views that reached the 6-second threshold | | Metadata | | | --------------- | ----------------------------- | | **Type** | Currency | | **Data Source** | [TikTok Ads](/sources/tiktok) | | **Aggregation** | Ratio | *** ## Example Your awareness campaign spent **\$14,230** and generated **594,000 video views**, resulting in a cost per view of **\$0.024**. | Campaign | Spend | Video Views | Cost per View | | ------------------ | ------------ | ----------- | ------------- | | Brand Awareness Q1 | \$8,500 | 354,167 | \$0.024 | | Product Launch | \$3,200 | 142,222 | \$0.023 | | Seasonal Promo | \$2,530 | 97,611 | \$0.026 | | **Total** | **\$14,230** | **594,000** | **\$0.024** | *** ## How It Works TikTok Cost per Video View divides your total ad spend by the number of 6-second video views. This metric helps you understand how efficiently you're buying video engagement. Lower CPV means more views for your budget, but should be balanced against view quality and downstream conversions. *** ## When to Use | Scenario | Action | | --------------------- | ------------------------------------------------------------------- | | Budget allocation | Compare CPV across campaigns to shift spend to efficient performers | | Creative testing | Lower CPV often indicates more engaging content | | Platform benchmarking | Compare against industry averages (\$0.01–\$0.05 typical range) | | Bid optimization | Adjust bids based on target CPV goals | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | | [TikTok Spend](/reference/metrics/advertising/tiktok/tiktok-spend/tiktok-spend) | Numerator in the CPV calculation | | [TikTok Video Views](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-views) | Denominator in the CPV calculation | | [TikTok Cost per 15-Second Video View](/reference/metrics/advertising/tiktok/tiktok-video/tiktok-video-views-15s-cost) | CPV for deeper engagement threshold | [See all TikTok Video metrics →](/reference/metrics/advertising/tiktok/tiktok-video) # ACR Percentage: Attributed Conversion Rate for Meta Events Source: https://docs.upstackdata.com/reference/metrics/data-quality/emq/acr-percentage Measure the share of conversions Meta can attribute to ad interactions. Higher ACR means better tracking and more accurate campaign optimization. ACR Percentage measures the share of your conversions that Meta can successfully attribute to ad interactions. ## Formula **ACR Percentage** = **Attributed Conversions** ÷ **Total Conversions** × 100 ### Formula Components | Metric | Definition | | -------------------------- | ---------------------------------------------- | | **Attributed Conversions** | Conversions Meta linked to an ad click or view | | **Total Conversions** | All purchase events sent through your pixel | | Metadata | | | --------------- | --------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Average | *** ## Example **Your store achieved 68.4% ACR last month**, meaning Meta attributed over two-thirds of your conversions to specific ad interactions. | Week | Total Conversions | Attributed | ACR % | | ------ | ----------------- | ---------- | ------ | | Week 1 | 1,247 | 842 | 67.52% | | Week 2 | 1,389 | 962 | 69.26% | | Week 3 | 1,156 | 791 | 68.43% | *** ## How It Works ACR reflects how well Meta can trace conversions back to ad touches. Higher ACR comes from better match key coverage—sending hashed emails, phone numbers, and external IDs with your events. When ACR is low, Meta's ad optimization algorithms have less signal to work with, reducing campaign effectiveness. *** ## When to Use | Scenario | Action | | ----------------------------------- | ---------------------------------------------------------- | | ACR below 50% | Prioritize improving event coverage and match key quality | | ACR dropping over time | Investigate changes to data collection or privacy settings | | Comparing to Coverage Potential ACR | Gauge how much headroom exists for improvement | | Evaluating EMQ investments | Higher ACR directly improves Meta campaign optimization | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------ | ----------------------------------------------- | | [EMQ Score](/reference/metrics/data-quality/emq/emq-score) | Overall quality rating that influences ACR | | [Coverage Potential ACR](/reference/metrics/data-quality/emq/coverage-potential-acr) | How much ACR could improve with better coverage | [See all EMQ metrics →](/reference/metrics/data-quality/emq) # Affected Event Count: Events Impacted by EMQ Issues Source: https://docs.upstackdata.com/reference/metrics/data-quality/emq/affected-event-count Track how many events are impacted by Meta EMQ diagnostic issues. Identify scale of data quality problems affecting your conversion matching. Affected Event Count shows the number of events impacted by a specific EMQ diagnostic issue, helping you understand the scale of data quality problems. ## Formula **Affected Event Count** = **COUNT** ( Events ) **WHERE** diagnostic\_issue = active ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | **Events** | Total events sent via Conversions API | | [**diagnostic\_issue = active**](/data-dictionary/measures-and-dimensions) | Filters to events with a specific data quality problem flagged by Meta | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example Your Purchase event has a diagnostic issue flagged for **missing phone numbers**: | Event Type | Total Events | Affected Events | Impact | | ----------- | ------------ | --------------- | -------------- | | Purchase | 12,450 | 3,847 | 30.9% affected | | AddToCart | 45,200 | 8,104 | 17.9% affected | | ViewContent | 128,000 | 15,360 | 12.0% affected | *** ## How It Works Meta's Event Match Quality system scans your Conversions API events for data quality issues. Each diagnostic issue tracks how many events are impacted. Higher counts indicate a broader problem that affects more of your conversion data and may reduce attribution accuracy. *** ## When to Use | Scenario | Action | | --------------------- | -------------------------------------------------------- | | Prioritizing fixes | Focus on diagnostics affecting the most events first | | Measuring improvement | Track affected count over time after implementing fixes | | Assessing impact | Understand how widespread a specific data issue is | | Resource allocation | Allocate engineering time based on event volume affected | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------- | ---------------------------------------- | | [Affected Events %](/reference/metrics/data-quality/emq/affected-events-percentage) | Percentage version of this metric | | [Diagnostics Count](/reference/metrics/data-quality/emq/diagnostics-count) | Total number of active diagnostic issues | [See all EMQ metrics →](/reference/metrics/data-quality/emq) # Affected Events %: Share of Events with Quality Issues Source: https://docs.upstackdata.com/reference/metrics/data-quality/emq/affected-events-percentage Track the percentage of events impacted by a specific diagnostic issue. Identify which issues affect the most events to prioritize fixes. The share of your total events impacted by a specific diagnostic issue. ## Formula **Affected Events %** = [**Affected Event Count**](/reference/metrics/data-quality/emq/affected-event-count) ÷ **Total Events** × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------ | -------------------------------------------------- | | [**Affected Event Count**](/reference/metrics/data-quality/emq/affected-event-count) | Number of events impacted by this diagnostic issue | | **Total Events** | Total number of events sent during the period | | Metadata | | | --------------- | --------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Average | *** ## Example Your pixel has **3 active diagnostics**. Here's how they affect your events: | Diagnostic Issue | Affected % | Priority | | -------------------- | ---------- | -------- | | Missing email hash | 42.3% | High | | Invalid phone format | 8.7% | Medium | | Missing external\_id | 2.1% | Low | The "Missing email hash" issue impacts 42.3% of your events and should be fixed first. *** ## How It Works Meta analyzes your event data and flags quality issues that reduce matching accuracy. Affected Events % shows what portion of your total event volume is impacted by each specific issue. Higher percentages indicate issues affecting more of your data. *** ## When to Use | Scenario | Action | | --------------------- | ------------------------------------------------ | | Prioritizing fixes | Address issues with the highest affected % first | | Measuring fix impact | Compare before/after to confirm resolution | | Tracking data quality | Monitor trends over time for quality regressions | | Resource allocation | Focus engineering time on highest-impact issues | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------- | ----------------------------------------------------------- | | [Affected Event Count](/reference/metrics/data-quality/emq/affected-event-count) | Absolute count of events (this metric shows the percentage) | | [Diagnostics Count](/reference/metrics/data-quality/emq/diagnostics-count) | Total number of active diagnostic issues | | [EMQ Score](/reference/metrics/data-quality/emq/emq-score) | Overall quality score impacted by these issues | [See all EMQ metrics →](/reference/metrics/data-quality/emq) # Browser Dedupe Coverage: Pixel Event Deduplication Source: https://docs.upstackdata.com/reference/metrics/data-quality/emq/browser-dedupe-coverage Track what percentage of your browser pixel events include a deduplication key. Higher coverage prevents double-counting conversions. Browser Dedupe Coverage measures the percentage of browser pixel events that include a deduplication key, preventing double-counting when browser and server events overlap. ## Formula **Browser Dedupe Coverage** = **Browser Events with Dedupe Key** ÷ **Total Browser Events** × 100 ### Formula Components | Metric | Definition | | ---------------------------------- | ---------------------------------------------------------------- | | **Browser Events with Dedupe Key** | Browser pixel events that include an event\_id for deduplication | | **Total Browser Events** | All browser pixel events sent to Meta | | Metadata | | | --------------- | --------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Average | *** ## Example A brand's pixel fires **12,450 browser events** in January. **11,830** include a deduplication key. | Metric | Value | | ------------------------------ | --------- | | Browser Events with Dedupe Key | 11,830 | | Total Browser Events | 12,450 | | **Browser Dedupe Coverage** | **95.0%** | *** ## How It Works When both your browser pixel and Conversions API send the same event, Meta needs a deduplication key (event\_id) to recognize them as one conversion rather than two. Browser Dedupe Coverage shows how many of your browser events include this key. Higher coverage means more accurate conversion counts and better attribution. *** ## When to Use | Scenario | Action | | ------------------------------- | ------------------------------------------------------------ | | Coverage below 90% | Verify pixel is sending event\_id with all conversion events | | Conversion counts seem inflated | Check both browser and server dedupe coverage for gaps | | Setting up Conversions API | Ensure matching event\_ids between browser and server events | | Optimizing EMQ Score | Improve dedupe coverage to prevent duplicate conversions | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | [Server Dedupe Coverage](/reference/metrics/data-quality/emq/server-dedupe-coverage) | Server-side equivalent—both should be high for accurate deduplication | | [Overall Browser Coverage](/reference/metrics/data-quality/emq/overall-browser-coverage) | Combined deduplication effectiveness across all browser events | [See all EMQ metrics →](/reference/metrics/data-quality/emq) # Coverage Potential ACR: Conversion Rate Improvement Opportunity Source: https://docs.upstackdata.com/reference/metrics/data-quality/emq/coverage-potential-acr Measure how much your attributed conversion rate could improve by increasing event coverage to Meta's recommended goal. Coverage Potential ACR shows how much your attributed conversion rate could improve if you increase event coverage to the recommended goal. ## Formula **Coverage Potential ACR** = **Coverage Gap** × **ACR Improvement Factor** ### Formula Components | Metric | Definition | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **Coverage Gap** | [Event Coverage Goal](/reference/metrics/data-quality/emq/event-coverage-goal) − [Event Coverage](/reference/metrics/data-quality/emq/event-coverage) | | **ACR Improvement Factor** | Meta's estimated conversion rate gain per coverage percentage point | | Metadata | | | --------------- | --------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Average | *** ## Example Your store currently has **72% event coverage** but Meta recommends **95%** for optimal matching. Coverage Potential ACR shows **+4.8%**. | Current State | Value | Impact | | ---------------------- | ----- | ------------------------- | | Event Coverage | 72% | Below goal | | Coverage Goal | 95% | Meta recommended | | Coverage Potential ACR | +4.8% | Potential ACR improvement | *** ## How It Works Meta calculates how much additional conversion attribution you could gain by closing the gap between your current event coverage and the recommended goal. This improvement comes from more events having valid customer identifiers that Meta can match to ad interactions. *** ## When to Use | Scenario | Action | | ----------------------------------- | --------------------------------------------------- | | Prioritizing EMQ improvements | Focus on coverage if potential ACR gain is high | | Comparing improvement opportunities | Weigh coverage gains against match key fixes | | Building the business case | Quantify revenue impact of better event coverage | | Tracking progress | Monitor potential ACR decrease as coverage improves | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------ | ----------------------------------------------------- | | [ACR Percentage](/reference/metrics/data-quality/emq/acr-percentage) | Current attributed conversion rate this could improve | | [Event Coverage](/reference/metrics/data-quality/emq/event-coverage) | Current coverage percentage to increase | | [Event Coverage Goal](/reference/metrics/data-quality/emq/event-coverage-goal) | Target coverage to achieve full potential | [See all EMQ metrics →](/reference/metrics/data-quality/emq) # Diagnostics Count: Active Event Setup Issues Source: https://docs.upstackdata.com/reference/metrics/data-quality/emq/diagnostics-count Track the number of active diagnostic issues Meta has flagged with your event setup. Resolve issues to improve your EMQ score and attribution quality. Diagnostics Count shows how many active issues Meta has flagged with your event setup that may reduce your EMQ score and attribution quality. ## Formula **Diagnostics Count** = **COUNT** ( Active Diagnostic Issues ) | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example **Your pixel has 3 active diagnostic issues** flagged by Meta this week. | Issue | Severity | Impact | | ------------------------------ | -------- | --------------- | | Missing external\_id parameter | High | −0.8 EMQ points | | Invalid phone format | Medium | −0.3 EMQ points | | Low email coverage | Low | −0.2 EMQ points | Resolving all three issues could improve your EMQ score by up to 1.3 points. *** ## How It Works Meta continuously monitors your Conversions API event data and flags issues that affect matching quality. Each diagnostic issue identifies a specific problem—like missing parameters, invalid formatting, or low coverage—that prevents Meta from matching events to users. Upstack syncs these diagnostics daily from Meta's Events Manager API. *** ## When to Use | Scenario | Action | | ------------------------ | ---------------------------------------------------- | | EMQ score dropped | Check diagnostics for new issues causing the decline | | Setting up a new pixel | Monitor diagnostics during initial configuration | | Poor attribution results | Prioritize high-severity diagnostics first | | Weekly health check | Review and resolve any new flagged issues | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------ | ------------------------------------------------------- | | [EMQ Score](/reference/metrics/data-quality/emq/emq-score) | Each diagnostic issue can reduce your overall EMQ score | | [Match Key Issues](/reference/metrics/data-quality/emq/match-key-issues) | Specific match key problems that appear as diagnostics | [See all EMQ metrics →](/reference/metrics/data-quality/emq) # EMQ Score: Meta Event Match Quality Rating Source: https://docs.upstackdata.com/reference/metrics/data-quality/emq/emq-score Track your Meta Event Match Quality score on a 0-10 scale. Higher EMQ scores improve ad delivery accuracy and attribution for your Meta campaigns. EMQ Score measures how well Meta can match your conversion events to Facebook users, rated on a 0-10 scale. ## Formula **EMQ Score** = Meta's proprietary scoring algorithm based on [**Match Key Coverage**](/reference/metrics/data-quality/emq/match-key-coverage), [**Event Coverage**](/reference/metrics/data-quality/emq/event-coverage), and deduplication ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------- | ----------------------------------------------------------- | | [**Match Key Coverage**](/reference/metrics/data-quality/emq/match-key-coverage) | Percentage of events with valid customer identifiers | | [**Event Coverage**](/reference/metrics/data-quality/emq/event-coverage) | Percentage of events with at least one matchable identifier | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Average | | **Scale** | 0-10 | *** ## Example **Your pixel achieved an EMQ score of 8.4/10 this week**, up from 7.2 last month after improving email capture rates. | Event Type | EMQ Score | Match Keys Present | | ----------- | --------- | ------------------ | | Purchase | 9.1/10 | Email, Phone, FBP | | Add to Cart | 7.8/10 | FBP, External ID | | Page View | 6.2/10 | FBP only | *** ## How It Works Meta calculates your EMQ score based on how many customer identifiers you pass with each event and how accurately those identifiers can be matched to Facebook profiles. Events with multiple high-quality match keys (hashed email, phone, external ID) receive higher scores than events with only browser-based identifiers. *** ## When to Use | Scenario | Action | | ---------------------- | ---------------------------------------------------------------- | | Score below 6.0 | Audit customer data capture at checkout and login points | | Score dropped suddenly | Check for pixel implementation changes or data collection issues | | Score plateaued at 7-8 | Focus on capturing phone numbers and secondary identifiers | | Score above 9.0 | Maintain current implementation; monitor for regressions | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------- | ----------------------------------------------------------- | | [Event Coverage](/reference/metrics/data-quality/emq/event-coverage) | Shows what percentage of events have matchable data | | [Match Key Coverage](/reference/metrics/data-quality/emq/match-key-coverage) | Shows coverage for specific identifiers like email or phone | [See all EMQ metrics →](/reference/metrics/data-quality/emq) # Event Coverage: Percentage of Events with Valid Match Keys Source: https://docs.upstackdata.com/reference/metrics/data-quality/emq/event-coverage Track what percentage of your events include valid customer identifiers for Meta matching. Improve coverage to boost EMQ scores and attribution accuracy. Event Coverage measures the percentage of your events that include at least one valid customer identifier (email, phone, etc.) that Meta can use for matching. ## Formula **Event Coverage** = **Events with Valid Match Keys** ÷ **Total Events** × 100 ### Formula Components | Metric | Definition | | -------------------------------- | ----------------------------------------------------------------- | | **Events with Valid Match Keys** | Count of events containing at least one valid customer identifier | | **Total Events** | Total events sent to Meta during the period | | Metadata | | | --------------- | --------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Average | *** ## Example **Your store sends 10,000 events to Meta in a week.** Of those, 8,500 include at least one valid match key (email, phone, or external ID). | Metric | Value | | ---------------------- | --------- | | Events with Match Keys | 8,500 | | Total Events | 10,000 | | **Event Coverage** | **85.0%** | *** ## How It Works Meta evaluates each event you send via the Conversions API to determine if it contains usable customer identifiers. Events with valid identifiers (properly hashed emails, phone numbers, or external IDs) count toward coverage. Higher coverage means more events can be matched to Facebook users for attribution. *** ## When to Use | Scenario | Action | | --------------------------------- | --------------------------------------------------------------------- | | Event coverage below 80% | Add more customer identifiers to your event payloads | | EMQ score isn't improving | Check if coverage is the limiting factor before addressing match keys | | Setting up new event types | Monitor coverage to ensure identifiers are being captured | | Comparing pixel vs. server events | Identify which channel captures more customer data | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------- | -------------------------------------------------------- | | [EMQ Score](/reference/metrics/data-quality/emq/emq-score) | Overall quality score that event coverage contributes to | | [Match Key Coverage](/reference/metrics/data-quality/emq/match-key-coverage) | Breakdown of coverage by specific identifier type | [See all EMQ metrics →](/reference/metrics/data-quality/emq) # Event Coverage Goal: Meta's Recommended Coverage Target Source: https://docs.upstackdata.com/reference/metrics/data-quality/emq/event-coverage-goal View the event coverage target Meta recommends for your pixel. Meet this goal to achieve optimal ad delivery and attribution accuracy. Event Coverage Goal is the target coverage percentage Meta recommends for your pixel to achieve optimal ad delivery and attribution. ## Formula **Event Coverage Goal** = Target percentage provided by Meta based on your event volume and account configuration | Metadata | | | --------------- | --------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Point-in-time | *** ## Example **Meta sets your Event Coverage Goal at 90.0%.** Your current Event Coverage is 82.5%, meaning you need to improve by 7.5 percentage points. | Metric | Value | | ---------------- | ----- | | Coverage Goal | 90.0% | | Current Coverage | 82.5% | | Gap to Target | 7.5% | *** ## How It Works Meta evaluates your pixel's event volume and account requirements to set a personalized coverage target. This goal represents the minimum percentage of events that should include valid match keys (email, phone, etc.) for optimal ad delivery and attribution accuracy. *** ## When to Use | Scenario | Action | | ------------------------------- | ----------------------------------------------------- | | Current coverage below goal | Prioritize adding customer identifiers to more events | | Goal recently increased | Review new event types that may lack identifiers | | Coverage equals or exceeds goal | Focus on improving match key quality instead | | Planning CAPI improvements | Use the gap between current and goal to scope work | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------ | -------------------------------------------------------- | | [Event Coverage](/reference/metrics/data-quality/emq/event-coverage) | Your current coverage percentage (compare to this goal) | | [Coverage Potential ACR](/reference/metrics/data-quality/emq/coverage-potential-acr) | Potential attribution improvement from reaching the goal | [See all EMQ metrics →](/reference/metrics/data-quality/emq) # Event Potential ACR: Conversion Rate Gains from Quality Fixes Source: https://docs.upstackdata.com/reference/metrics/data-quality/emq/event-potential-acr Measure how much your attributed conversion rate could improve by resolving event quality issues identified in Meta diagnostics. Event Potential ACR shows how much your attributed conversion rate could improve by resolving event quality issues identified in diagnostics. ## Formula **Event Potential ACR** = **Quality Issues** × **ACR Improvement Factor** ### Formula Components | Metric | Definition | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **Quality Issues** | Event setup issues flagged in [Diagnostics Count](/reference/metrics/data-quality/emq/diagnostics-count) that reduce matching | | **ACR Improvement Factor** | Meta's estimated conversion rate gain from resolving each issue | | Metadata | | | --------------- | --------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Average | *** ## Example Your store has **3 active diagnostic issues** affecting event quality. Meta estimates an Event Potential ACR of **+2.35%**. | Issue Type | Affected Events | Potential ACR Impact | | -------------------- | --------------- | -------------------- | | Missing event\_id | 12,450 | +1.2% | | Invalid phone format | 3,200 | +0.8% | | Missing user\_data | 1,800 | +0.35% | | **Total** | **17,450** | **+2.35%** | *** ## How It Works Meta analyzes event quality issues from your Conversions API setup and estimates how much attributed conversion rate you're losing. Resolving these issues—such as fixing data formatting, adding missing parameters, or correcting event timing—enables better user matching and more accurate attribution. *** ## When to Use | Scenario | Action | | ----------------------------- | ------------------------------------------------------- | | Prioritizing EMQ improvements | Focus on event quality if potential ACR gain is high | | Comparing fix opportunities | Weigh event quality fixes against coverage improvements | | Building the business case | Quantify revenue impact of resolving diagnostic issues | | Tracking remediation progress | Monitor potential ACR decrease as issues are resolved | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------ | ------------------------------------------------------ | | [ACR Percentage](/reference/metrics/data-quality/emq/acr-percentage) | Current attributed conversion rate this could improve | | [Diagnostics Count](/reference/metrics/data-quality/emq/diagnostics-count) | Number of issues contributing to potential improvement | | [Coverage Potential ACR](/reference/metrics/data-quality/emq/coverage-potential-acr) | Alternative improvement path through event coverage | [See all EMQ metrics →](/reference/metrics/data-quality/emq) # Expected EMQ Increase: Projected Score Improvement Source: https://docs.upstackdata.com/reference/metrics/data-quality/emq/expected-emq-increase Track predicted EMQ score gains from fixing specific match key issues. Prioritize data quality fixes by their potential impact on Meta event matching. Expected EMQ Increase shows how many EMQ score points you would gain by fixing a specific match key issue. ## Formula **Expected EMQ Increase** = Predicted [**EMQ Score**](/reference/metrics/data-quality/emq/emq-score) improvement from resolving the [**Match Key Coverage**](/reference/metrics/data-quality/emq/match-key-coverage) issue ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------- | ------------------------------------------------------ | | [**EMQ Score**](/reference/metrics/data-quality/emq/emq-score) | Your existing Event Match Quality score (0-10) | | [**Match Key Coverage**](/reference/metrics/data-quality/emq/match-key-coverage) | Current coverage percentage for the specific match key | | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Prediction | | **Format** | +X.XX | *** ## Example Your **email match key** has 45% coverage and is flagged as an issue. The Expected EMQ Increase shows **+1.25 points**. | Match Key | Current Coverage | Expected EMQ Increase | Priority | | ----------- | ---------------- | --------------------- | -------- | | Email | 45% | +1.25 | High | | Phone | 62% | +0.78 | Medium | | External ID | 28% | +0.42 | Low | *** ## How It Works Meta calculates the predicted score improvement based on your current EMQ score, the specific match key's coverage gap, and historical matching patterns. Higher predicted increases indicate match keys with greater potential to improve your overall event quality. *** ## When to Use | Scenario | Action | | ------------------- | ------------------------------------------------------- | | Prioritizing fixes | Address match keys with highest expected increase first | | Resource allocation | Focus engineering effort on highest-impact improvements | | Reporting progress | Track cumulative potential gains as issues are resolved | | Setting targets | Use predictions to set realistic EMQ improvement goals | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------- | ---------------------------------------------- | | [EMQ Score](/reference/metrics/data-quality/emq/emq-score) | The score this metric predicts improvement for | | [Match Key Coverage](/reference/metrics/data-quality/emq/match-key-coverage) | Coverage percentage affecting the prediction | [See all EMQ metrics →](/reference/metrics/data-quality/emq) # Event Match Quality: Meta CAPI Performance Metrics Source: https://docs.upstackdata.com/reference/metrics/data-quality/emq/index Track Meta Event Match Quality (EMQ) metrics in Upstack. Includes EMQ Score, Event Coverage, Match Key Coverage, and diagnostics with formulas and optimization tips. Event Match Quality (EMQ) metrics measure how well your conversion events match to Facebook users. Meta uses these scores to determine attribution accuracy and ad delivery optimization. Higher EMQ scores mean your events are more likely to be attributed correctly and your campaigns will perform better. **Data Source:** [Meta Ads (Pixel Quality API)](/sources/facebook-ads)\ **Metrics:** 16 ## Metrics in This Group | Metric | Description | When to Use | | ---------------------------------------------------------------------------------------- | ------------------------------------------------ | ----------------------------------- | | [EMQ Score](/reference/metrics/data-quality/emq/emq-score) | Event Match Quality score from Meta (0-10 scale) | Monitor overall tracking health | | [Event Coverage](/reference/metrics/data-quality/emq/event-coverage) | Percentage of events with valid match keys | Measure identifier completeness | | [Event Coverage Goal](/reference/metrics/data-quality/emq/event-coverage-goal) | Target event coverage percentage from Meta | Set coverage benchmarks | | [Diagnostics Count](/reference/metrics/data-quality/emq/diagnostics-count) | Number of active diagnostic issues | Identify setup problems | | [Match Key Issues](/reference/metrics/data-quality/emq/match-key-issues) | Number of match keys with identified issues | Find specific data quality problems | | [ACR Percentage](/reference/metrics/data-quality/emq/acr-percentage) | Attributed Conversion Rate percentage | Measure attribution accuracy | | [Coverage Potential ACR](/reference/metrics/data-quality/emq/coverage-potential-acr) | Potential ACR improvement from event coverage | Prioritize coverage improvements | | [Event Potential ACR](/reference/metrics/data-quality/emq/event-potential-acr) | Potential ACR improvement from event quality | Prioritize quality fixes | | [Match Key Coverage](/reference/metrics/data-quality/emq/match-key-coverage) | Coverage percentage for specific match keys | Analyze individual identifiers | | [Expected EMQ Increase](/reference/metrics/data-quality/emq/expected-emq-increase) | Predicted EMQ score increase from fixes | Estimate improvement impact | | [Match Key Potential ACR](/reference/metrics/data-quality/emq/match-key-potential-acr) | Potential ACR if match key is improved | Prioritize key fixes | | [Affected Events %](/reference/metrics/data-quality/emq/affected-events-percentage) | Percentage of events affected by issues | Assess issue severity | | [Affected Event Count](/reference/metrics/data-quality/emq/affected-event-count) | Number of events affected by issues | Quantify issue impact | | [Browser Dedupe Coverage](/reference/metrics/data-quality/emq/browser-dedupe-coverage) | Browser events with deduplication key | Monitor browser-side dedupe | | [Server Dedupe Coverage](/reference/metrics/data-quality/emq/server-dedupe-coverage) | Server events with deduplication key | Monitor server-side dedupe | | [Overall Browser Coverage](/reference/metrics/data-quality/emq/overall-browser-coverage) | Overall browser deduplication coverage | Track total dedupe health | ## How These Metrics Relate EMQ metrics form a hierarchy of data quality measurement: * **EMQ Score** is the primary health indicator—a 0-10 rating from Meta * **Event Coverage** and **Match Key Coverage** measure how complete your customer identifiers are (email, phone, etc.) * **ACR Percentage** shows what percentage of conversions Meta can actually attribute to ads * **Potential ACR** metrics show how much attribution could improve if you fix specific issues * **Diagnostics Count** and **Match Key Issues** help identify specific problems to fix * **Dedupe Coverage** metrics ensure browser and server events aren't double-counted ## Choosing the Right Metric * **Overall health check**: Start with EMQ Score to see your aggregate rating * **Diagnosing issues**: Use Diagnostics Count and Match Key Issues to find problems * **Prioritizing fixes**: Compare Potential ACR metrics to find highest-impact improvements * **Deduplication audit**: Check Browser and Server Dedupe Coverage to prevent duplicate conversions * **Setting goals**: Use Event Coverage Goal as your benchmark target # Match Key Coverage: Identifier Presence by Type Source: https://docs.upstackdata.com/reference/metrics/data-quality/emq/match-key-coverage Track what percentage of events include specific customer identifiers like email or phone. Improve coverage per match key to boost Meta matching quality. Match Key Coverage measures the percentage of events that include a specific customer identifier (email, phone, external ID, etc.). ## Formula **Match Key Coverage** = **Events with This Match Key** ÷ **Total Events** × 100 ### Formula Components | Metric | Definition | | ------------------------------ | ------------------------------------------------------- | | **Events with This Match Key** | Count of events containing the specific identifier type | | **Total Events** | Total events sent to Meta during the period | | Metadata | | | --------------- | --------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Average | *** ## Example **Your store sends 12,000 purchase events to Meta this month.** Coverage varies significantly by identifier type. | Match Key | Events Present | Coverage | | ----------- | -------------- | -------- | | Email | 10,800 | 90.0% | | Phone | 4,200 | 35.0% | | External ID | 11,400 | 95.0% | | FBP Cookie | 12,000 | 100.0% | *** ## How It Works Meta evaluates each match key type independently. Coverage is calculated per identifier—email coverage shows how many events have hashed emails, phone coverage shows phone numbers, etc. Higher coverage for high-quality identifiers (email, phone) improves your EMQ score more than browser-based identifiers alone. *** ## When to Use | Scenario | Action | | ---------------------------- | ---------------------------------------------------------------- | | Email coverage below 80% | Audit checkout and account flows to capture more emails | | Phone coverage below 30% | Add optional phone field to checkout or offer SMS signup | | External ID coverage low | Ensure logged-in users have IDs passed in all events | | Single key has zero coverage | Check if that identifier type is being hashed and sent correctly | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------- | ----------------------------------------------------------- | | [EMQ Score](/reference/metrics/data-quality/emq/emq-score) | Overall quality score improved by higher match key coverage | | [Event Coverage](/reference/metrics/data-quality/emq/event-coverage) | Shows overall percentage of events with any match key | [See all EMQ metrics →](/reference/metrics/data-quality/emq) # Match Key Issues: Data Quality Problems in Customer Identifiers Source: https://docs.upstackdata.com/reference/metrics/data-quality/emq/match-key-issues Track the number of match keys with data quality issues affecting Meta matching. Monitor email, phone, and other identifier fields to improve your EMQ score. The count of customer identifier fields (email, phone, etc.) that have data quality problems affecting Meta matching. ## Formula **Match Key Issues** = **COUNT** ( Match Keys with Identified Issues ) | Metadata | | | --------------- | --------------------------------- | | **Type** | Number | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Count | *** ## Example **Your pixel has 3 match key issues** flagged by Meta this week: | Match Key | Issue | Impact | | ----------- | ----------------------- | ------ | | Email | Invalid format detected | High | | Phone | Missing country codes | Medium | | External ID | Inconsistent hashing | Low | *** ## How It Works Meta analyzes each customer identifier field you send with conversion events and flags issues that reduce matching accuracy. Common problems include invalid email formats, phone numbers without country codes, unhashed data, or inconsistent formatting across events. *** ## When to Use | Scenario | Action | | --------------------- | ------------------------------------------------------------------------ | | Issue count increased | Review recent implementation changes to customer data capture | | Persistent high count | Audit data validation before sending events to Meta | | Count dropped to zero | Confirm fixes resolved issues; monitor for regressions | | New issue appeared | Check the specific match key field for formatting or collection problems | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------- | ------------------------------------------------------ | | [Diagnostics Count](/reference/metrics/data-quality/emq/diagnostics-count) | Total diagnostic issues (Match Key Issues is a subset) | | [Match Key Coverage](/reference/metrics/data-quality/emq/match-key-coverage) | Coverage percentage for each identifier type | [See all EMQ metrics →](/reference/metrics/data-quality/emq) # Match Key Potential ACR: Conversion Rate Improvement Opportunity Source: https://docs.upstackdata.com/reference/metrics/data-quality/emq/match-key-potential-acr See how much your attributed conversion rate could improve by fixing a specific match key. Prioritize data quality fixes by potential ACR gain. The potential improvement to your Attributed Conversion Rate if a specific match key is fixed. ## Formula **Match Key Potential ACR** = Estimated [**ACR Percentage**](/reference/metrics/data-quality/emq/acr-percentage) gain from improving coverage or quality of a specific match key (email, phone, etc.) ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------- | ------------------------------------------------------- | | [**Match Key Coverage**](/reference/metrics/data-quality/emq/match-key-coverage) | Current coverage percentage for the specific identifier | | [**ACR Percentage**](/reference/metrics/data-quality/emq/acr-percentage) | Current attributed conversion rate to improve | | Metadata | | | --------------- | --------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Average | *** ## Example Your store has a **2.4%** potential ACR gain from fixing the phone match key: | Match Key | Current Coverage | Potential ACR Gain | | ----------- | ---------------- | ------------------ | | Email | 92% | 0.3% | | Phone | 45% | 2.4% | | External ID | 78% | 0.8% | | First Name | 88% | 0.2% | Improving phone coverage would have the highest impact on your attributed conversion rate. *** ## How It Works Meta estimates how much your Attributed Conversion Rate would improve if you increase coverage or fix quality issues for each match key. This helps you prioritize which customer identifiers to focus on first for maximum attribution improvement. *** ## When to Use | Scenario | Action | | ------------------------------- | --------------------------------------------------- | | Prioritizing data quality fixes | Focus on match keys with highest potential ACR gain | | Low attributed conversions | Identify which match keys are limiting attribution | | Planning pixel improvements | Target specific identifiers for better coverage | | Comparing fix impact | Evaluate ROI of different data collection efforts | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------- | ----------------------------------------------------------------- | | [ACR Percentage](/reference/metrics/data-quality/emq/acr-percentage) | Your current attributed conversion rate this metric could improve | | [Match Key Coverage](/reference/metrics/data-quality/emq/match-key-coverage) | Coverage level that affects this potential gain | | [EMQ Score](/reference/metrics/data-quality/emq/emq-score) | Overall quality score affected by match key improvements | [See all EMQ metrics →](/reference/metrics/data-quality/emq) # Overall Browser Coverage: Deduplication Key Coverage Source: https://docs.upstackdata.com/reference/metrics/data-quality/emq/overall-browser-coverage Track combined deduplication key coverage across all browser events to prevent duplicate conversion reporting in Meta ads. Overall Browser Coverage measures the percentage of browser pixel events that include a deduplication key, reflecting how well your setup prevents duplicate conversion reporting. ## Formula **Overall Browser Coverage** = **Browser Events with Dedupe Key** ÷ **Total Browser Events** × 100 ### Formula Components | Metric | Definition | | ---------------------------------- | ------------------------------------------------------------------- | | **Browser Events with Dedupe Key** | Count of browser pixel events containing a deduplication identifier | | **Total Browser Events** | Total count of browser pixel events sent to Meta | | Metadata | | | --------------- | --------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Average | *** ## Example Your store sends **12,450 browser events** to Meta, with **11,580 including deduplication keys**. | Metric | Value | Interpretation | | ---------------------------- | --------- | ----------------------------- | | Events with Dedupe Key | 11,580 | Browser events with event IDs | | Total Browser Events | 12,450 | All browser pixel events | | **Overall Browser Coverage** | **93.0%** | Strong deduplication coverage | *** ## How It Works When both browser pixel and server Conversions API send the same conversion event, Meta uses deduplication keys to avoid double-counting. This metric shows the percentage of your browser events that include the required identifier (typically `event_id`) for accurate deduplication. *** ## When to Use | Scenario | Action | | ----------------------------- | -------------------------------------------------- | | Coverage below 90% | Check pixel configuration for missing event IDs | | Seeing duplicate conversions | Verify browser events include matching dedupe keys | | Setting up redundant tracking | Ensure browser and server events share identifiers | | Auditing data quality | Compare with server coverage for full picture | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------- | -------------------------------------------- | | [Browser Dedupe Coverage](/reference/metrics/data-quality/emq/browser-dedupe-coverage) | Per-event breakdown of browser deduplication | | [Server Dedupe Coverage](/reference/metrics/data-quality/emq/server-dedupe-coverage) | Server-side deduplication key coverage | [See all EMQ metrics →](/reference/metrics/data-quality/emq) # Server Dedupe Coverage: Conversions API Deduplication Source: https://docs.upstackdata.com/reference/metrics/data-quality/emq/server-dedupe-coverage Track what percentage of your server-side Conversions API events include a deduplication key. Higher coverage ensures accurate deduplication against browser pixel events. Server Dedupe Coverage measures the percentage of server-side Conversions API events that include a deduplication key, enabling accurate deduplication against browser pixel events. ## Formula **Server Dedupe Coverage** = **Server Events with Dedupe Key** ÷ **Total Server Events** × 100 ### Formula Components | Metric | Definition | | --------------------------------- | ------------------------------------------------------------------ | | **Server Events with Dedupe Key** | Conversions API events that include an event\_id for deduplication | | **Total Server Events** | All server-side Conversions API events sent to Meta | | Metadata | | | --------------- | --------------------------------- | | **Type** | Percentage | | **Data Source** | [Meta Ads](/sources/facebook-ads) | | **Aggregation** | Average | *** ## Example A brand's Conversions API sends **8,920 server events** in January. **8,654** include a deduplication key. | Metric | Value | | ----------------------------- | --------- | | Server Events with Dedupe Key | 8,654 | | Total Server Events | 8,920 | | **Server Dedupe Coverage** | **97.0%** | *** ## How It Works When you send events via the Conversions API, Meta needs a deduplication key (event\_id) to match them against browser pixel events and avoid double-counting. Server Dedupe Coverage shows how many of your server events include this key. Higher coverage means Meta can accurately deduplicate overlapping browser and server events, improving attribution accuracy. *** ## When to Use | Scenario | Action | | ------------------------------- | -------------------------------------------------------------------------- | | Coverage below 95% | Verify your Conversions API implementation sends event\_id with all events | | Conversion counts seem inflated | Check both server and browser dedupe coverage for mismatches | | Implementing Conversions API | Ensure event\_ids match between browser pixel and server events | | Optimizing EMQ Score | Improve server dedupe coverage to enable accurate deduplication | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | [Browser Dedupe Coverage](/reference/metrics/data-quality/emq/browser-dedupe-coverage) | Browser-side equivalent—both should be high for accurate deduplication | | [Overall Browser Coverage](/reference/metrics/data-quality/emq/overall-browser-coverage) | Combined deduplication effectiveness across all browser events | [See all EMQ metrics →](/reference/metrics/data-quality/emq) # Data Quality Metrics: Monitor Event Match Quality and Tracking Health Source: https://docs.upstackdata.com/reference/metrics/data-quality/index Track data quality metrics in Upstack. View 16 metrics including EMQ Score, Event Coverage, and Match Key Coverage with formulas, examples, and best practices. Data Quality metrics measure how well your tracking setup is performing—specifically Meta's Event Match Quality (EMQ) scores that determine how accurately your conversion events match to Facebook users. Higher quality scores mean better ad targeting, more accurate attribution, and improved campaign performance. **Data Source:** [Upstack Pixel](/pixel)\ **Metrics in Category:** 16 ## Subcategories | Subcategory | Metrics | Description | | ---------------------------------------------------------- | ------- | ----------------------------------------------------------------------------- | | [Event Match Quality](/reference/metrics/data-quality/emq) | 16 | Meta's EMQ scores, match key coverage, diagnostics, and deduplication metrics | ## When to Use * **Event Match Quality:** When you need to monitor and improve your Meta Conversions API event matching, diagnose tracking issues, or optimize your customer identifier coverage for better attribution. ## All Data Quality Metrics | Metric | Description | | ---------------------------------------------------------------------------------------- | ------------------------------------------------ | | [EMQ Score](/reference/metrics/data-quality/emq/emq-score) | Event Match Quality score from Meta (0-10 scale) | | [Event Coverage](/reference/metrics/data-quality/emq/event-coverage) | Percentage of events with valid match keys | | [Event Coverage Goal](/reference/metrics/data-quality/emq/event-coverage-goal) | Target event coverage percentage from Meta | | [Diagnostics Count](/reference/metrics/data-quality/emq/diagnostics-count) | Number of active diagnostic issues | | [Match Key Issues](/reference/metrics/data-quality/emq/match-key-issues) | Number of match keys with identified issues | | [ACR Percentage](/reference/metrics/data-quality/emq/acr-percentage) | Attributed Conversion Rate percentage | | [Coverage Potential ACR](/reference/metrics/data-quality/emq/coverage-potential-acr) | Potential ACR improvement from event coverage | | [Event Potential ACR](/reference/metrics/data-quality/emq/event-potential-acr) | Potential ACR improvement from event quality | | [Match Key Coverage](/reference/metrics/data-quality/emq/match-key-coverage) | Coverage percentage for specific match keys | | [Expected EMQ Increase](/reference/metrics/data-quality/emq/expected-emq-increase) | Predicted EMQ score increase from fixes | | [Match Key Potential ACR](/reference/metrics/data-quality/emq/match-key-potential-acr) | Potential ACR if match key is improved | | [Affected Events %](/reference/metrics/data-quality/emq/affected-events-percentage) | Percentage of events affected by issues | | [Affected Event Count](/reference/metrics/data-quality/emq/affected-event-count) | Number of events affected by issues | | [Browser Dedupe Coverage](/reference/metrics/data-quality/emq/browser-dedupe-coverage) | Browser events with deduplication key | | [Server Dedupe Coverage](/reference/metrics/data-quality/emq/server-dedupe-coverage) | Server events with deduplication key | | [Overall Browser Coverage](/reference/metrics/data-quality/emq/overall-browser-coverage) | Overall browser deduplication coverage | # Cost per Page View: Measure Traffic Acquisition Efficiency Source: https://docs.upstackdata.com/reference/metrics/funnel/awareness/cost-per-page-view Calculate cost per page view to measure how efficiently your ad spend drives traffic. Track ad efficiency at the awareness stage with formula and optimization tips. Average ad spend per page view event tracked by the Upstack pixel. ## Formula **Cost per Page View** = [**Channel Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) ÷ [**Page Views**](/reference/metrics/funnel/awareness/page-views) ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------- | ----------------------------------------------------- | | [**Channel Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total advertising spend across connected ad platforms | | [**Page Views**](/reference/metrics/funnel/awareness/page-views) | Total page load events tracked by the Upstack pixel | | Metadata | | | --------------- | ------------------------------------- | | **Type** | Currency | | **Data Source** | [Upstack Pixel](/pixel), Ad Platforms | | **Aggregation** | Ratio | *** ## Example Your store spent **\$2,400** on ads last week and generated **48,000 page views**: | Channel | Spend | Page Views | Cost per Page View | | ------- | ------- | ---------- | ------------------ | | Meta | \$1,500 | 30,000 | \$0.05 | | Google | \$900 | 18,000 | \$0.05 | *** ## How It Works Cost per Page View divides your total advertising spend by the number of page view events captured by the Upstack pixel. Lower values indicate more efficient traffic acquisition—you're paying less for each visitor touchpoint. *** ## When to Use | Scenario | Action | | ---------------------------- | ------------------------------------------------------------ | | Comparing channel efficiency | Identify which platforms drive traffic most cost-effectively | | Setting awareness budgets | Estimate spend needed to hit traffic targets | | Optimizing top-of-funnel | Reallocate budget toward lower-cost channels | | Benchmarking campaigns | Track efficiency trends over time | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------ | ---------------------------------------------------- | | [Page Views](/reference/metrics/funnel/awareness/page-views) | Denominator—total traffic volume | | [Unique Sessions](/reference/metrics/funnel/awareness/unique-sessions) | Alternative volume metric for session-based analysis | | [Page Views Value](/reference/metrics/funnel/awareness/page-views-value) | Attributed revenue from page view events | [See all Awareness metrics →](/reference/metrics/funnel/awareness) # Awareness Metrics: Visitor Traffic & Acquisition for E-commerce Source: https://docs.upstackdata.com/reference/metrics/funnel/awareness/index Track visitor awareness metrics in Upstack Funnel. Includes Page Views, Unique Sessions, Unique Visitors, and New Visitors with formulas and optimization tips. Awareness metrics measure the top of your marketing funnel—how many visitors your site attracts and whether they're new or returning. Use these to evaluate traffic volume, acquisition effectiveness, and audience growth. **Data Source:** [Upstack Pixel](/pixel)\ **Metrics:** 9 ## Metrics in This Group | Metric | Description | When to Use | | -------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------- | | [Page Views](/reference/metrics/funnel/awareness/page-views) | Total page load events across your site | Measure overall traffic volume | | [Cost per Page View](/reference/metrics/funnel/awareness/cost-per-page-view) | Ad spend divided by page views | Evaluate traffic acquisition efficiency | | [Page Views Value](/reference/metrics/funnel/awareness/page-views-value) | Monetary value attributed to page views | Measure awareness-stage value | | [Unique Sessions](/reference/metrics/funnel/awareness/unique-sessions) | Count of distinct browsing sessions | Track site visits (not just page loads) | | [Cost per Session](/reference/metrics/funnel/awareness/cost-per-session) | Ad spend divided by sessions | Evaluate session acquisition efficiency | | [Unique Visitors](/reference/metrics/funnel/awareness/unique-visitors) | Count of distinct individuals using identity resolution | Measure unique audience size | | [New Visitors](/reference/metrics/funnel/awareness/new-visitors) | First-time visitors to your store | Track customer acquisition | | [New Visitors Percentage](/reference/metrics/funnel/awareness/new-visitors-percentage) | Percentage of traffic from new visitors | Balance acquisition vs retention | | [Bounce Rate](/reference/metrics/funnel/awareness/bounce-rate) | Percentage of single-page sessions | Identify landing page engagement issues | ## How These Metrics Relate These metrics form a hierarchy of audience measurement: * **Page Views** counts every page load (one session can have many page views) * **Unique Sessions** counts browsing sessions (one visitor can have many sessions) * **Unique Visitors** counts distinct people using identity resolution * **New Visitors** is a subset: first-time visitors only * **New Visitors Percentage** = New Visitors ÷ Unique Visitors × 100 * **Bounce Rate** = Bounced Sessions ÷ Unique Sessions × 100 (measures engagement quality) Cost and value metrics help you understand efficiency: * **Cost per Page View** = Ad Spend ÷ Page Views * **Cost per Session** = Ad Spend ÷ Sessions * **Page Views Value** = Attributed value from awareness-stage events ## Choosing the Right Metric * **Traffic volume**: Use Page Views for raw traffic, Unique Sessions for visit count * **Audience size**: Use Unique Visitors to count distinct people * **Acquisition analysis**: Use New Visitors and New Visitors % to measure growth * **Efficiency**: Compare Cost per Page View or Cost per Session across channels * **Attribution value**: Use Page Views Value to see top-funnel impact on revenue * **Engagement quality**: Use Bounce Rate to identify landing pages losing visitors # New Visitors: First-Time Store Visitors Source: https://docs.upstackdata.com/reference/metrics/funnel/awareness/new-visitors Track first-time visitors to your store with the Upstack pixel. Measure customer acquisition effectiveness and identify growth opportunities. The count of visitors identified by the Upstack pixel as first-time visitors to your store. ## Formula **New Visitors** = **COUNT** ( Visitors ) **WHERE** [first\_visit = true](/data-dictionary/measures-and-dimensions#visitor-dimensions) ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | **Visitors** | Individual people identified by the Upstack pixel's identity resolution | | [**first\_visit = true**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to visitors on their first-ever tracked visit to your store | | Metadata | | | --------------- | ----------------------- | | **Type** | Number | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Count | *** ## Example Your store attracted **8,420 new visitors** last month from acquisition campaigns: | Source | New Visitors | Share | | -------------- | ------------ | ----- | | Paid Social | 4,210 | 50% | | Organic Search | 2,526 | 30% | | Direct | 1,684 | 20% | *** ## How It Works The Upstack pixel identifies first-time visitors using browser fingerprinting and cookie data. A visitor is counted as "new" only once—their first session on your store. Returning visitors are excluded from this count. *** ## When to Use | Scenario | Action | | --------------------------- | ---------------------------------------------------- | | Measuring acquisition reach | Track how many net-new people your campaigns attract | | Evaluating ad platforms | Compare which channels bring the most new traffic | | Seasonal planning | Identify when new visitor volume peaks | | Funnel analysis | Use as top-of-funnel baseline for conversion rates | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------- | ----------------------------------------- | | [Unique Visitors](/reference/metrics/funnel/awareness/unique-visitors) | Total visitors (new + returning combined) | | [New Visitors %](/reference/metrics/funnel/awareness/new-visitors-percentage) | New Visitors ÷ Unique Visitors | | [Unique Sessions](/reference/metrics/funnel/awareness/unique-sessions) | Total sessions across all visitors | [See all Awareness metrics →](/reference/metrics/funnel/awareness) # New Visitors Percentage: Measure Acquisition vs Retention Source: https://docs.upstackdata.com/reference/metrics/funnel/awareness/new-visitors-percentage Track the percentage of new visitors to your store. Measure acquisition effectiveness and balance with returning visitor retention in Upstack. Percentage of total unique visitors who are first-time visitors. High percentages indicate strong acquisition but may suggest retention challenges. ## Formula **New Visitors Percentage** = ( [**New Visitors**](/reference/metrics/funnel/awareness/new-visitors) ÷ [**Unique Visitors**](/reference/metrics/funnel/awareness/unique-visitors) ) × 100 ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------- | ---------------------------------------------------------- | | [**New Visitors**](/reference/metrics/funnel/awareness/new-visitors) | First-time visitors identified through identity resolution | | [**Unique Visitors**](/reference/metrics/funnel/awareness/unique-visitors) | Distinct individuals visiting your store | | Metadata | | | --------------- | ----------------------- | | **Type** | Percentage | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Ratio | *** ## Example Your store had **8,500 unique visitors** last month, with **5,950 being new visitors**: | Segment | Count | Percentage | | ------------------ | ----- | ---------- | | New Visitors | 5,950 | 70% | | Returning Visitors | 2,550 | 30% | A 70% new visitor rate indicates strong top-of-funnel acquisition, but you may want to invest in retention strategies to bring visitors back. *** ## How It Works The Upstack pixel identifies unique visitors using cross-device identity resolution. A visitor is classified as "new" on their first tracked visit and "returning" on subsequent visits. This metric calculates the ratio of new visitors to total unique visitors. *** ## When to Use | Scenario | Action | | -------------------------------- | ----------------------------------------------------------- | | Evaluating acquisition campaigns | High percentages indicate effective reach to new audiences | | Diagnosing retention issues | Consistently high rates may signal poor retention | | Seasonal analysis | Compare new visitor ratios across peak and off-peak periods | | Channel comparison | Identify which channels drive new vs returning traffic | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------- | -------------------------------------------------- | | [New Visitors](/reference/metrics/funnel/awareness/new-visitors) | Numerator—count of first-time visitors | | [Unique Visitors](/reference/metrics/funnel/awareness/unique-visitors) | Denominator—total distinct visitors | | [Unique Sessions](/reference/metrics/funnel/awareness/unique-sessions) | Alternative denominator for session-based analysis | [See all Awareness metrics →](/reference/metrics/funnel/awareness) # Page Views: Total Pages Viewed Across Your Site Source: https://docs.upstackdata.com/reference/metrics/funnel/awareness/page-views Track total page views across your e-commerce site. Measure traffic volume and user engagement with the Upstack pixel's page load tracking. Total number of page load events tracked by the Upstack pixel across your site in the selected period. ## Formula **Page Views** = **COUNT** ( Page Load Events ) ### Formula Components | Metric | Definition | | -------------------- | ------------------------------------------------------------------------------ | | **Page Load Events** | Individual page load events fired by the Upstack pixel on each page navigation | | Metadata | | | --------------- | ----------------------- | | **Type** | Number | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Count | *** ## Example Your skincare brand recorded **87,340 page views** during a product launch week: | Page Type | Views | Share | | ---------------- | ------ | ----- | | Homepage | 24,150 | 28% | | Product pages | 41,200 | 47% | | Collection pages | 15,890 | 18% | | Other | 6,100 | 7% | *** ## How It Works Every time a visitor loads a page tracked by the Upstack pixel, a page view event fires. Multiple views of the same page by the same visitor each count as separate page views. This metric includes all page types: homepage, product pages, collections, cart, and checkout. *** ## When to Use | Scenario | Action | | ------------------------------ | -------------------------------------------- | | Measuring overall site traffic | Track total engagement volume over time | | Identifying popular content | Compare page views across different sections | | Evaluating campaign reach | Monitor page view spikes after ad launches | | Calculating engagement rates | Use as denominator for view-through metrics | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------- | --------------------------------------------------- | | [Unique Sessions](/reference/metrics/funnel/awareness/unique-sessions) | Distinct visits (one session = multiple page views) | | [Avg. Page Views per Session](/reference/metrics/funnel/engagement/avg-page-views-per-session) | Page Views ÷ Unique Sessions | | [Page Views Value](/reference/metrics/funnel/awareness/page-views-value) | Total monetary value attributed to page view events | [See all Awareness metrics →](/reference/metrics/funnel/awareness) # Page Views Value: Total Monetary Value of Page Views Source: https://docs.upstackdata.com/reference/metrics/funnel/awareness/page-views-value Track the total monetary value of page view events. Measure awareness-stage value contribution and optimize top-of-funnel investment. The total monetary value attributed to page view events tracked by the Upstack pixel. ## Formula **Page Views Value** = **SUM** ( Page View Event Values ) ### Formula Components | Metric | Definition | | -------------------------- | ----------------------------------------------------------------------------- | | **Page View Event Values** | Monetary value assigned to each page view event based on attribution modeling | | Metadata | | | --------------- | ----------------------- | | **Type** | Currency | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Sum | *** ## Example Your store generated **\$12,450** in page views value this week across 24,900 page views: | Source | Page Views | Value | Avg Value | | ---------- | ---------- | ------- | --------- | | Meta Ads | 15,200 | \$7,600 | \$0.50 | | Google Ads | 6,800 | \$3,400 | \$0.50 | | Direct | 2,900 | \$1,450 | \$0.50 | *** ## How It Works Page Views Value sums the monetary value assigned to each page view event. This value represents the attributed contribution of awareness-stage traffic to your funnel. Higher values indicate stronger top-of-funnel performance from your marketing channels. *** ## When to Use | Scenario | Action | | ------------------------ | ---------------------------------------------------------- | | Measuring awareness ROI | Compare value generated by different traffic sources | | Evaluating ad efficiency | Assess which campaigns drive highest-value traffic | | Budget planning | Allocate spend toward channels with better awareness value | | Funnel optimization | Track value flow from page views to deeper funnel stages | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------- | ----------------------------------------------- | | [Page Views](/reference/metrics/funnel/awareness/page-views) | Count of events (this metric sums their values) | | [Cost per Page View](/reference/metrics/funnel/awareness/cost-per-page-view) | Spend efficiency for generating page views | | [Unique Sessions](/reference/metrics/funnel/awareness/unique-sessions) | Related awareness metric for unique visits | [See all Awareness metrics →](/reference/metrics/funnel/awareness) # Unique Sessions: Count of Distinct Visitor Sessions Source: https://docs.upstackdata.com/reference/metrics/funnel/awareness/unique-sessions Track the number of unique sessions on your site. Measure traffic volume and visitor engagement with the Upstack pixel's session tracking. Count of distinct sessions tracked by the Upstack pixel. Each continuous visit from a user counts as one session. ## Formula **Unique Sessions** = **COUNT** ( Distinct Sessions ) ### Formula Components | Metric | Definition | | --------------------- | ------------------------------------------------------------------------------------------------------- | | **Distinct Sessions** | Individual browsing sessions identified by the Upstack pixel, separated by 30-minute inactivity timeout | | Metadata | | | --------------- | ----------------------- | | **Type** | Number | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Count | *** ## Example Your store recorded **12,450 unique sessions** during a weekend flash sale: | Day | Sessions | Bounce Rate | | -------- | -------- | ----------- | | Saturday | 6,820 | 38% | | Sunday | 5,630 | 41% | *** ## How It Works A session begins when a visitor loads a page tracked by the Upstack pixel and ends after 30 minutes of inactivity or at midnight. Returning visitors within the timeout window continue the same session; visits after the timeout start a new session. *** ## When to Use | Scenario | Action | | ------------------------------- | ---------------------------------------------- | | Measuring traffic volume | Track total site visits over time | | Campaign effectiveness | Compare sessions before and after launches | | Identifying traffic patterns | Spot peak days and seasonal trends | | Calculating session-based rates | Use as denominator for conversion rate metrics | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | [Unique Visitors](/reference/metrics/funnel/awareness/unique-visitors) | Distinct people across sessions (one visitor = multiple sessions) | | [Page Views](/reference/metrics/funnel/awareness/page-views) | Total pages viewed across all sessions | | [Session Conversion Rate](/reference/metrics/funnel/conversions/session-conversion-rate) | Conversions ÷ Unique Sessions | [See all Awareness metrics →](/reference/metrics/funnel/awareness) # Unique Visitors: Distinct Individuals on Your Site Source: https://docs.upstackdata.com/reference/metrics/funnel/awareness/unique-visitors Track unique visitors identified by the Upstack pixel using identity resolution. Understand your audience reach and measure top-of-funnel awareness. Count of distinct individual visitors identified by the Upstack pixel using identity resolution. One visitor can have multiple sessions. ## Formula **Unique Visitors** = **COUNT DISTINCT** ( Visitors ) ### Formula Components | Metric | Definition | | ------------ | ------------------------------------------------------------------------------------ | | **Visitors** | Individual people identified by the Upstack pixel's cross-device identity resolution | | Metadata | | | --------------- | ----------------------- | | **Type** | Number | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Count (Distinct) | *** ## Example Your store attracted **12,450 unique visitors** this month across all traffic sources: | Source | Visitors | Share | | -------------- | -------- | ----- | | Paid Social | 5,230 | 42% | | Organic Search | 3,115 | 25% | | Direct | 2,490 | 20% | | Email | 1,615 | 13% | *** ## How It Works The Upstack pixel identifies visitors using identity resolution across devices and sessions. When the same person visits from their phone and laptop, they're counted as one unique visitor. This deduplication provides accurate audience measurement regardless of how many times or ways someone visits. *** ## When to Use | Scenario | Action | | ------------------------------------ | -------------------------------------------- | | Measuring audience reach | Track how many people your marketing reaches | | Calculating visitor-to-customer rate | Divide conversions by unique visitors | | Comparing traffic sources | See which channels bring the most people | | Planning capacity | Estimate demand based on visitor trends | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------- | ---------------------------------------------- | | [Unique Sessions](/reference/metrics/funnel/awareness/unique-sessions) | Total visits (one visitor = multiple sessions) | | [New Visitors](/reference/metrics/funnel/awareness/new-visitors) | Subset: first-time visitors only | | [Revenue per Visitor](/reference/metrics/funnel/conversions/revenue-per-visitor) | Total revenue ÷ Unique Visitors | [See all Awareness metrics →](/reference/metrics/funnel/awareness) # View Category Value: Total Monetary Value of Category Page Views Source: https://docs.upstackdata.com/reference/metrics/funnel/awareness/view-category-value Track the total monetary value of category page view events. Measure awareness-stage value from product category browsing and optimize category merchandising. The total monetary value attributed to category page view events tracked by the Upstack pixel. ## Formula **View Category Value** = **SUM** ( View Category Event Values ) ### Formula Components | Metric | Definition | | ------------------------------ | --------------------------------------------------------------------------------- | | **View Category Event Values** | Monetary value assigned to each view category event based on attribution modeling | | Metadata | | | --------------- | ----------------------- | | **Type** | Currency | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Sum | *** ## Example Your store generated **\$8,750** in view category value this week across 17,500 category page views: | Category | Views | Value | Avg Value | | ----------------- | ----- | ------- | --------- | | Women's Apparel | 8,200 | \$4,100 | \$0.50 | | Men's Accessories | 5,100 | \$2,550 | \$0.50 | | Sale Items | 4,200 | \$2,100 | \$0.50 | *** ## How It Works View Category Value sums the monetary value assigned to each category page view event. This value represents the attributed contribution of category browsing behavior to your funnel. Higher values indicate that visitors exploring your product categories are more likely to convert downstream. *** ## When to Use | Scenario | Action | | ----------------------------- | ------------------------------------------------------------- | | Category performance analysis | Compare value generated by different product categories | | Merchandising optimization | Identify which category pages drive highest-value traffic | | Navigation UX testing | Measure impact of category layout changes on attributed value | | Marketing attribution | Track value flow from category discovery to conversion | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------ | --------------------------------------------- | | [Page Views Value](/reference/metrics/funnel/awareness/page-views-value) | Similar value metric for all page views | | [Page Views](/reference/metrics/funnel/awareness/page-views) | Related awareness metric for total page views | | [Unique Sessions](/reference/metrics/funnel/awareness/unique-sessions) | Related awareness metric for unique visits | [See all Awareness metrics →](/reference/metrics/funnel/awareness) # Average Conversion Value (ACV) Source: https://docs.upstackdata.com/reference/metrics/funnel/conversions/average-conversion-value Calculate average revenue per conversion across all marketing channels. Compare channel performance, identify high-value segments, and optimize targeting. The average monetary value of each conversion event. ## Formula **Average Conversion Value** = [**Conversion Value**](/reference/metrics/funnel/conversions/conversion-value) ÷ [**Conversions**](/reference/metrics/funnel/conversions/conversions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------ | ---------------------------------------------------- | | [**Conversion Value**](/reference/metrics/funnel/conversions/conversion-value) | Sum of all revenue from attributed conversion events | | [**Conversions**](/reference/metrics/funnel/conversions/conversions) | Count of attributed conversion events | | Metadata | | | --------------- | ---------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Upstack Pixel](/pixel), [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example With **\$47,500** in conversion value from **950 conversions**: | Metric | Value | | ---------------------------- | ----------- | | Conversion Value | \$47,500 | | Conversions | 950 | | **Average Conversion Value** | **\$50.00** | *** ## How It Works This metric divides total conversion value by the number of conversions. It reveals the typical order size or deal value driven by your marketing, helping you understand conversion quality, not just quantity. *** ## When to Use | Scenario | Action | | ------------------- | -------------------------------------------------------------- | | ACV increasing | Campaigns attracting higher-value customers—scale them | | ACV dropping | Check if discounts or lower-tier products dominate conversions | | Comparing channels | Identify which platforms drive premium vs. budget customers | | Setting CPA targets | Ensure CPA stays below ACV for profitable acquisition | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------- | ----------------------------- | | [Conversion Value](/reference/metrics/funnel/conversions/conversion-value) | The numerator (total revenue) | | [Conversions](/reference/metrics/funnel/conversions/conversions) | The denominator (event count) | | [Unique Converters](/reference/metrics/funnel/conversions/unique-converters) | Distinct people who converted | [See all Attributed Conversions metrics →](/reference/metrics/funnel/conversions) # Conversion Value: Total Revenue from Conversions Source: https://docs.upstackdata.com/reference/metrics/funnel/conversions/conversion-value Track total revenue from attributed conversions across Meta, Google, and TikTok. Learn the formula, see examples, and optimize your marketing ROI. The sum of all revenue from attributed conversion events. ## Formula **Conversion Value** = **SUM** ( Attributed Purchase Values ) ### Formula Components | Metric | Definition | | ------------------------------ | ---------------------------------------------------------------- | | **SUM** | Aggregation function that totals all conversion values | | **Attributed Purchase Values** | Monetary value of each purchase linked to a marketing touchpoint | | Metadata | | | --------------- | ---------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Upstack Pixel](/pixel), [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your campaigns generated **\$47,500** from 950 conversions this month: | Channel | Value | Share | | ---------- | -------- | ----- | | Meta Ads | \$28,500 | 60% | | Google Ads | \$12,350 | 26% | | TikTok Ads | \$6,650 | 14% | *** ## How It Works Conversion Value sums the monetary value of each attributed conversion event. For e-commerce, this equals order totals. Values are captured at conversion and attributed to marketing touchpoints based on your attribution model. *** ## When to Use | Scenario | Action | | ------------------------- | -------------------------------------------------- | | Measuring channel revenue | Compare total revenue contribution by platform | | Calculating ROAS | Divide by Ad Spend to find return on investment | | Evaluating campaign ROI | Identify which campaigns generate the most revenue | | Budget allocation | Shift spend toward highest-value channels | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------ | ----------------------------------------------- | | [Conversions](/reference/metrics/funnel/conversions/conversions) | Count of events (this metric sums their values) | | [Average Conversion Value](/reference/metrics/funnel/conversions/average-conversion-value) | Conversion Value ÷ Conversions | | [Unique Converters](/reference/metrics/funnel/conversions/unique-converters) | Distinct people who generated this value | [See all Attributed Conversions metrics →](/reference/metrics/funnel/conversions) # Conversions: Attributed Conversion Events Source: https://docs.upstackdata.com/reference/metrics/funnel/conversions/conversions Track attributed conversion events from Meta, Google, and TikTok campaigns. Learn the formula, see channel breakdowns, and optimize your conversion rate. The total number of conversion events attributed to your marketing touchpoints. ## Formula **Conversions** = **COUNT** ( Attributed Purchase Events ) ### Formula Components | Metric | Definition | | ------------------------------ | --------------------------------------------------------------------------- | | **COUNT** | Aggregation function that counts each conversion event | | **Attributed Purchase Events** | Purchase events linked to a marketing touchpoint via your attribution model | | Metadata | | | --------------- | ---------------------------------------------------- | | **Type** | Number | | **Data Source** | [Upstack Pixel](/pixel), [Shopify](/sources/shopify) | | **Aggregation** | Count | *** ## Example Your campaigns generated **1,447 conversions** this month: | Channel | Conversions | Share | | ---------- | ----------- | ----- | | Meta Ads | 847 | 58% | | Google Ads | 312 | 22% | | TikTok Ads | 288 | 20% | *** ## How It Works Upstack attributes conversions to marketing touchpoints using your configured attribution model and window. A single customer can generate multiple conversions if they purchase more than once within the attribution window. *** ## When to Use | Scenario | Action | | ---------------------- | -------------------------------------------------------- | | Conversions increasing | Scale budget on top-performing campaigns | | Conversions dropping | Check ad delivery, landing pages, or tracking setup | | Comparing channels | Identify which platforms drive the most conversions | | Optimizing campaigns | Use as the primary goal for conversion-focused campaigns | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | | [Conversion Value](/reference/metrics/funnel/conversions/conversion-value) | Total revenue from these conversions | | [Unique Converters](/reference/metrics/funnel/conversions/unique-converters) | Distinct people (Conversions ÷ Unique Converters = repeat rate) | | [Average Conversion Value](/reference/metrics/funnel/conversions/average-conversion-value) | Conversion Value ÷ Conversions | [See all Attributed Conversions metrics →](/reference/metrics/funnel/conversions) # Cost per All Purchase: Acquisition Efficiency for All Orders Source: https://docs.upstackdata.com/reference/metrics/funnel/conversions/cost-per-all-purchase Track cost per all purchase to measure ad spend efficiency across your Shopify store. Calculate your blended CPA across all customer types. Cost per All Purchase measures the average ad spend required to generate one purchase event of any type—new customer, returning customer, subscription, or otherwise. ## Formula **Cost per All Purchase** = **Channel Spend** ÷ **All Purchases** ### Formula Components | Metric | Definition | | ----------------- | -------------------------------------------------------------------------------- | | **Channel Spend** | Total advertising spend across all connected ad platforms | | **All Purchases** | Total purchase events tracked by the Upstack pixel, including all customer types | | Metadata | | | --------------- | ----------------------- | | **Type** | Currency | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Ratio | *** ## Example Your Shopify store spent **\$12,000 on ads** this month and generated **400 total purchases** across all customer types. | Purchase Type | Count | Share | | ------------------ | ------- | -------- | | New Customer | 180 | 45% | | Returning Customer | 160 | 40% | | Subscription | 60 | 15% | | **Total** | **400** | **100%** | **Cost per All Purchase** = \$12,000 ÷ 400 = **\$30.00** *** ## How It Works This metric divides your total advertising spend by all purchase events tracked by the Upstack pixel. Unlike new customer CPA, which only counts first-time buyers, Cost per All Purchase includes every transaction—giving you a blended view of acquisition efficiency across your entire Shopify customer base. *** ## When to Use | Scenario | Action | | ------------------------------- | ------------------------------------------------------------- | | Benchmarking overall efficiency | Compare against target CPA to gauge campaign health | | High returning customer rate | This metric reflects repeat purchase value that NC CPA misses | | Budget planning | Use for total cost forecasting across all order types | | Channel comparison | Compare blended efficiency across Meta, Google, and TikTok | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------ | ------------------------------------------------------ | | [Conversions](/reference/metrics/funnel/conversions/conversions) | Attributed conversions for ROAS calculations | | [Conversion Value](/reference/metrics/funnel/conversions/conversion-value) | Revenue generated from all conversions | | [Average Conversion Value](/reference/metrics/funnel/conversions/average-conversion-value) | Average revenue per conversion for break-even analysis | [See all Attributed Conversions metrics →](/reference/metrics/funnel/conversions) # Cost per Purchase: Measure Ad Spend Efficiency Source: https://docs.upstackdata.com/reference/metrics/funnel/conversions/cost-per-purchase Track cost per purchase to measure ad spend efficiency for your Shopify store. Calculate your average advertising cost per conversion event. Cost per Purchase measures the average advertising spend required to generate one purchase event tracked by the Upstack pixel. ## Formula **Cost per Purchase** = **Channel Spend** ÷ **Purchase Events** ### Formula Components | Metric | Definition | | ------------------- | --------------------------------------------------------- | | **Channel Spend** | Total advertising spend across all connected ad platforms | | **Purchase Events** | Purchase events tracked by the Upstack pixel | | Metadata | | | --------------- | ----------------------- | | **Type** | Currency | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Ratio | *** ## Example Your Shopify store spent **\$15,000 on ads** in March and the Upstack pixel tracked **500 purchase events**. | Week | Ad Spend | Purchase Events | Cost/Purchase | | --------- | ------------ | --------------- | ------------- | | Week 1 | \$3,500 | 110 | \$31.82 | | Week 2 | \$4,000 | 130 | \$30.77 | | Week 3 | \$3,800 | 125 | \$30.40 | | Week 4 | \$3,700 | 135 | \$27.41 | | **Total** | **\$15,000** | **500** | **\$30.00** | *** ## How It Works Upstack calculates Cost per Purchase by dividing your total advertising spend across all channels by the number of purchase events tracked by the pixel. This gives you a unified cost efficiency metric that spans Meta, Google, TikTok, and any other connected ad platforms—measuring how much you spend on average to generate each Shopify purchase. *** ## When to Use | Scenario | Action | | ------------------------ | --------------------------------------------------------- | | Evaluating ad efficiency | Compare against target CPA to assess campaign health | | Budget optimization | Shift spend toward channels with lower cost per purchase | | Forecasting | Project total ad spend needed to hit revenue targets | | Channel comparison | Identify which platforms drive purchases most efficiently | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------- | ---------------------------------------------- | | [Conversions](/reference/metrics/funnel/conversions/conversions) | Attributed conversion events for ROAS analysis | | [Conversion Value](/reference/metrics/funnel/conversions/conversion-value) | Total revenue from conversions | | [Session Conversion Rate](/reference/metrics/funnel/conversions/session-conversion-rate) | Percentage of sessions that convert | [See all Attributed Conversions metrics →](/reference/metrics/funnel/conversions) # Attributed Conversions: Revenue Attribution Metrics Source: https://docs.upstackdata.com/reference/metrics/funnel/conversions/index Track attributed conversions in Upstack funnel metrics. Includes Conversions, Conversion Value, Unique Converters, Average Conversion Value, and Session Conversion Rate. Conversion metrics measure the outcomes of your marketing funnel—how many visitors complete a desired action and the value those actions generate. These metrics are the foundation of marketing attribution and ROI analysis. **Data Source:** Upstack Pixel + Shopify\ **Metrics:** 13 ## Metrics in This Group | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------ | ------------------------------------------------ | ---------------------------------- | | [Purchases](/reference/metrics/funnel/conversions/purchases) | Count of tracked purchase events | Measure conversion volume | | [Conversions](/reference/metrics/funnel/conversions/conversions) | Count of attributed conversion events | Measure action volume | | [Conversion Value](/reference/metrics/funnel/conversions/conversion-value) | Total monetary value of conversions | Measure revenue impact | | [Unique Converters](/reference/metrics/funnel/conversions/unique-converters) | Distinct individuals who converted | Count new customers | | [Average Conversion Value](/reference/metrics/funnel/conversions/average-conversion-value) | Average value per conversion | Measure quality of conversions | | [Session Conversion Rate](/reference/metrics/funnel/conversions/session-conversion-rate) | Percentage of sessions resulting in purchase | Measure store efficiency | | [Upsell Purchases](/reference/metrics/funnel/conversions/upsell-purchases) | Count of upsell purchase events | Track post-purchase revenue | | [Cost per All Purchase](/reference/metrics/funnel/conversions/cost-per-all-purchase) | Ad spend per purchase event (all types) | Measure acquisition efficiency | | [Cost per Purchase](/reference/metrics/funnel/conversions/cost-per-purchase) | Average ad spend per purchase event | Measure ad efficiency | | [High AOV Purchases](/reference/metrics/funnel/conversions/high-aov-purchases) | Purchases above average order value | Identify premium buyers | | [Low AOV Purchases](/reference/metrics/funnel/conversions/low-aov-purchases) | Purchases below average order value | Identify upsell opportunities | | [Lead Value](/reference/metrics/funnel/conversions/lead-value) | Total monetary value of lead events | Measure lead generation revenue | | [Checkout Rate](/reference/metrics/funnel/conversions/checkout-rate) | Percentage of sessions that reach checkout | Measure checkout funnel efficiency | | [Repeat Purchase Rate](/reference/metrics/funnel/conversions/repeat-purchase-rate) | Percentage of purchases from returning customers | Measure customer retention | ## How These Metrics Relate These metrics form a complete picture of conversion performance: * **Conversions** counts individual conversion events (one person can convert multiple times) * **Conversion Value** sums the monetary value of all those events * **Unique Converters** counts distinct people, regardless of how many times each converted * **Average Conversion Value** = Conversion Value ÷ Conversions * **Session Conversion Rate** = Purchases ÷ Sessions × 100 * **Cost per All Purchase** = Channel Spend ÷ All Purchases * **Cost per Purchase** = Channel Spend ÷ Purchase Events * **Checkout Rate** = Initiate Checkouts ÷ Sessions × 100 * **Repeat Purchase Rate** = Returning Customer Purchases ÷ Total Purchases × 100 The relationship between Conversions and Unique Converters reveals repeat conversion behavior—a higher ratio indicates customers converting multiple times. Repeat Purchase Rate directly measures what percentage of your purchases come from returning customers. Session Conversion Rate measures overall store efficiency, while Cost per Purchase and Cost per All Purchase show your acquisition efficiency from different perspectives. ## Choosing the Right Metric * **Volume analysis**: Use Conversions to count total conversion events * **Revenue attribution**: Use Conversion Value to measure monetary impact by channel * **New customer acquisition**: Use Unique Converters to count new customers acquired * **Quality analysis**: Compare Average Conversion Value across channels to find high-value sources * **Efficiency analysis**: Use Session Conversion Rate to measure overall store conversion efficiency * **Cost analysis**: Use Cost per Purchase to track ad efficiency per purchase event * **Funnel analysis**: Use Checkout Rate to measure how many sessions reach checkout * **Retention analysis**: Use Repeat Purchase Rate to measure customer loyalty and retention # Lead Value: Total Monetary Value of Leads Source: https://docs.upstackdata.com/reference/metrics/funnel/conversions/lead-value Track total monetary value of lead events captured by the Upstack Pixel. Measure lead generation revenue potential and optimize high-value lead sources. Lead Value measures the total monetary value assigned to lead events tracked by your Upstack Pixel. ## Formula **Lead Value** = **SUM** ( Lead Event Values ) ### Formula Components | Metric | Definition | | --------------------- | -------------------------------------------------------------------- | | **Lead Event Values** | Monetary value assigned to each lead event when tracked by the pixel | | Metadata | | | --------------- | ----------------------- | | **Type** | Currency | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Sum | *** ## Example Your marketing campaigns generated **\$125,400** in lead value from 2,090 leads this month: | Channel | Lead Value | Leads | Avg Value | | ---------- | ------------- | --------- | ----------- | | Meta Ads | \$68,970 | 1,149 | \$60.03 | | Google Ads | \$35,112 | 523 | \$67.14 | | Organic | \$21,318 | 418 | \$51.00 | | **Total** | **\$125,400** | **2,090** | **\$60.00** | *** ## How It Works Lead Value sums the monetary value assigned to each lead event captured by the Upstack Pixel. When tracking lead events, you can pass a `value` property representing the estimated worth of that lead. This allows you to differentiate between high-value and low-value leads, enabling revenue-focused optimization of lead generation campaigns. *** ## When to Use | Scenario | Action | | ---------------------- | ------------------------------------------------------------- | | Measuring lead quality | Compare lead value across channels to find high-value sources | | Calculating lead ROI | Divide Lead Value by ad spend to measure efficiency | | Prioritizing campaigns | Focus budget on campaigns generating highest lead value | | Forecasting revenue | Use lead value trends to project pipeline growth | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------- | -------------------------------------------------------------- | | [Leads](/reference/metrics/funnel/conversions/lead) | Count of lead events (Lead Value ÷ Leads = average lead value) | | [Cost per Lead](/reference/metrics/funnel/conversions/cost-per-lead) | Ad spend efficiency for lead generation | | [Conversion Value](/reference/metrics/funnel/conversions/conversion-value) | Downstream revenue from converted leads | [See all Attributed Conversions metrics →](/reference/metrics/funnel/conversions) # Purchases: Track Completed Shopify Orders Source: https://docs.upstackdata.com/reference/metrics/funnel/conversions/purchases Track total purchase events on your Shopify store. Count completed orders captured by the Upstack Pixel to measure conversion volume and marketing effectiveness. Purchases counts the total number of completed orders tracked by the Upstack Pixel on your Shopify store. ## Formula **Purchases** = **COUNT** ( Purchase Events ) ### Formula Components | Metric | Definition | | ------------------- | ---------------------------------------------------------------------------------- | | **Purchase Events** | Each completed Shopify order that fires a purchase event through the Upstack Pixel | | Metadata | | | --------------- | ---------------------------------------------------- | | **Type** | Number | | **Data Source** | [Upstack Pixel](/pixel), [Shopify](/sources/shopify) | | **Aggregation** | Count | *** ## Example Your Shopify store tracked **1,847 purchases** across attribution channels in January. | Channel | Purchases | % of Total | | ---------- | --------- | ---------- | | Meta Ads | 892 | 48.3% | | Google Ads | 512 | 27.7% | | Organic | 298 | 16.1% | | Direct | 145 | 7.9% | | **Total** | **1,847** | **100%** | *** ## How It Works Purchases counts every purchase event tracked by the Upstack Pixel. When a customer completes checkout on your Shopify store, the pixel fires a purchase event. This metric represents your actual Shopify order count as seen by the tracking pixel, giving you accurate conversion volume for attribution analysis. *** ## When to Use | Scenario | Action | | ------------------------------- | ------------------------------------------------- | | Measuring conversion volume | Track total purchases across channels | | Evaluating campaign performance | Compare purchase counts by attribution source | | Calculating conversion rates | Use as numerator for Session Conversion Rate | | Monitoring sales trends | Track daily, weekly, or monthly purchase patterns | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------- | ----------------------------------------------- | | [Revenue](/reference/metrics/funnel/conversions/revenue) | The monetary value generated by these purchases | | [Initiate Checkouts](/reference/metrics/funnel/engagement/initiate-checkouts) | Prior funnel step before purchase | | [Session Conversion Rate](/reference/metrics/funnel/conversions/session-conversion-rate) | Purchases ÷ Sessions × 100 | [See all Attributed Conversions metrics →](/reference/metrics/funnel/conversions) # Session Conversion Rate: Measure Your Shopify Store's Conversion Efficiency Source: https://docs.upstackdata.com/reference/metrics/funnel/conversions/session-conversion-rate Track the percentage of Shopify sessions that result in a purchase. Session Conversion Rate helps you measure overall store efficiency and optimize your e-commerce funnel. Session Conversion Rate measures the percentage of tracked sessions that result in a purchase on your Shopify store. ## Formula **Session Conversion Rate** = ( **Purchases** ÷ **Sessions** ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------- | -------------------------------------------------------------------------------- | | **Purchases** | Total purchase events tracked by the Upstack Pixel from completed Shopify orders | | [**Sessions**](/reference/metrics/funnel/sessions/session-count) | Total unique sessions tracked on your website | | Metadata | | | --------------- | ----------------------- | | **Type** | Percentage | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Ratio | *** ## Example Your Shopify store had **24,500 sessions** and **490 purchases** this month: | Metric | Value | | --------------------------- | --------- | | Sessions | 24,500 | | Purchases | 490 | | **Session Conversion Rate** | **2.00%** | By channel: | Channel | Sessions | Purchases | Conversion Rate | | ---------- | -------- | --------- | --------------- | | Meta Ads | 12,000 | 276 | 2.30% | | Google Ads | 8,000 | 152 | 1.90% | | Organic | 4,500 | 62 | 1.38% | *** ## How It Works Upstack tracks every session on your Shopify store using the [Upstack Pixel](/pixel) and counts purchases from completed Shopify orders. The conversion rate is calculated by dividing the number of purchases by the total sessions and multiplying by 100 to express it as a percentage. *** ## When to Use | Scenario | Action | | ------------------------- | ----------------------------------------------------------- | | Conversion rate dropping | Audit checkout flow, page speed, and product pages | | Comparing traffic sources | Identify which channels drive the highest conversion rates | | A/B testing landing pages | Measure impact of page changes on conversion rate | | Setting campaign goals | Benchmark against historical rates to set realistic targets | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------- | -------------------------------------------- | | [Session Count](/reference/metrics/funnel/sessions/session-count) | Denominator in this calculation | | [Conversions](/reference/metrics/funnel/conversions/conversions) | Total attributed conversions across channels | | [Revenue per Session](/reference/metrics/funnel/conversions/revenue-per-session) | Average revenue generated per session | [See all Attributed Conversions metrics →](/reference/metrics/funnel/conversions) # Unique Converters: Distinct Converting Users Source: https://docs.upstackdata.com/reference/metrics/funnel/conversions/unique-converters Track unique converting users across your marketing channels. Measure customer reach, calculate frequency, and optimize acquisition strategies. The number of unique individuals who completed at least one conversion. ## Formula **Unique Converters** = **COUNT DISTINCT** ( Converting User IDs ) ### Formula Components | Metric | Definition | | ----------------------- | ------------------------------------------------------------- | | **COUNT DISTINCT** | Aggregation function that counts unique values only | | **Converting User IDs** | Identity-resolved user identifiers who completed a conversion | | Metadata | | | --------------- | ---------------------------------------------------- | | **Type** | Number | | **Data Source** | [Upstack Pixel](/pixel), [Shopify](/sources/shopify) | | **Aggregation** | Count Distinct | *** ## Example Your campaigns drove **892 unique converters** who made 1,247 total conversions: | Metric | Value | | ------------------------- | ----- | | Total Conversions | 1,247 | | Unique Converters | 892 | | Conversions per Converter | 1.4× | | Repeat Converters | 28% | *** ## How It Works Upstack uses identity resolution to deduplicate converters across sessions and devices. A customer who purchases twice counts as one unique converter but two conversions. This metric reveals true customer acquisition versus repeat behavior. *** ## When to Use | Scenario | Action | | --------------------------- | ----------------------------------------------------------- | | Unique \< Total conversions | Strong repeat purchase behavior—nurture existing customers | | Unique ≈ Total conversions | Most conversions are first-time—focus on retention | | Comparing channels | Identify which platforms acquire new vs. re-engage existing | | Measuring acquisition | Track new customer growth separately from repeat purchases | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | | [Conversions](/reference/metrics/funnel/conversions/conversions) | Total events (Conversions ÷ Unique Converters = repeat rate) | | [Conversion Value](/reference/metrics/funnel/conversions/conversion-value) | Total revenue from all converters | | [Average Conversion Value](/reference/metrics/funnel/conversions/average-conversion-value) | Value per conversion event | [See all Attributed Conversions metrics →](/reference/metrics/funnel/conversions) # Upsell Purchases: Track Post-Purchase Revenue Source: https://docs.upstackdata.com/reference/metrics/funnel/conversions/upsell-purchases Count upsell purchase conversions in your Shopify store. Track revenue from post-purchase offers and optimize your upsell funnel with attribution data. Upsell Purchases counts the total number of purchases made through upsell or cross-sell offers. ## Formula **Upsell Purchases** = **COUNT** ( Upsell Purchase Events ) ### Formula Components | Metric | Definition | | -------------------------- | -------------------------------------------------------------------- | | **COUNT** | Aggregation function that counts each upsell purchase event | | **Upsell Purchase Events** | Purchase events triggered by accepting an upsell or cross-sell offer | | Metadata | | | --------------- | ---------------------------------------------------- | | **Type** | Number | | **Data Source** | [Upstack Pixel](/pixel), [Shopify](/sources/shopify) | | **Aggregation** | Count | *** ## Example Your Shopify store tracked **287 upsell purchases** this month from post-purchase offers: | Upsell Offer Type | Upsell Purchases | Conversion Rate | | -------------------- | ---------------- | --------------- | | Post-checkout upsell | 156 | 12.4% | | Cart page cross-sell | 89 | 8.2% | | Thank you page offer | 42 | 6.1% | *** ## How It Works Upstack automatically tracks upsell purchases when customers accept post-purchase or cross-sell offers in your Shopify store. Each accepted offer triggers an upsell purchase event, which is attributed to the original marketing touchpoint that brought the customer to your store. *** ## When to Use | Scenario | Action | | ------------------------------- | --------------------------------------------------- | | Measuring upsell performance | Track acceptance rates of post-purchase offers | | Optimizing offer placement | Compare upsell conversion rates across touchpoints | | Calculating incremental revenue | Measure additional revenue from upsell campaigns | | Testing upsell strategies | A/B test different offers and track purchase volume | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------ | ------------------------------------------ | | [Conversions](/reference/metrics/funnel/conversions/conversions) | Primary purchases (upsells are additional) | | [Conversion Value](/reference/metrics/funnel/conversions/conversion-value) | Total value including upsell revenue | | [Average Conversion Value](/reference/metrics/funnel/conversions/average-conversion-value) | Average order value with upsells included | [See all Attributed Conversions metrics →](/reference/metrics/funnel/conversions) # Add to Cart Rate: Measure Shopping Intent Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/add-to-cart-rate Track the percentage of product viewers who add items to cart. Analyze shopping intent and optimize product pages to increase add-to-cart conversions. Add to Cart Rate measures the percentage of product page views that result in an add-to-cart action. ## Formula **Add to Cart Rate** = ( **Add to Carts** ÷ **View Contents** ) × 100 ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------- | -------------------------------- | | [**Add to Carts**](/reference/metrics/funnel/engagement/add-to-carts) | Total add-to-cart events tracked | | [**View Contents**](/reference/metrics/funnel/engagement/view-contents) | Total product detail page views | | Metadata | | | --------------- | ----------------------- | | **Type** | Percentage | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Ratio | *** ## Example Your product pages received **8,450 view content events** in January, resulting in **1,521 add-to-cart actions**. | Metric | Value | Calculation | | -------------------- | --------- | -------------------------- | | View Contents | 8,450 | Product page views tracked | | Add to Carts | 1,521 | Items added to cart | | **Add to Cart Rate** | **18.0%** | (1,521 ÷ 8,450) × 100 | *** ## How It Works Add to Cart Rate calculates the conversion between product discovery and purchase intent. The Upstack Pixel tracks view content events when visitors land on product pages and add-to-cart events when they click the add-to-cart button. *** ## When to Use | Scenario | Action | | ------------------------- | ------------------------------------------------------------- | | Product page optimization | Compare rates across products to identify high/low performers | | A/B testing | Measure impact of price, imagery, or copy changes | | Seasonal analysis | Track intent changes during promotions or holidays | | Funnel diagnostics | Identify drop-off between viewing and carting | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------- | ----------------------------------- | | [Add to Carts](/reference/metrics/funnel/engagement/add-to-carts) | Numerator — total cart additions | | [View Contents](/reference/metrics/funnel/engagement/view-contents) | Denominator — product page views | | [ATC to IC Rate](/reference/metrics/funnel/engagement/atc-to-ic-rate) | Next funnel step — cart to checkout | | [Add to Carts Value](/reference/metrics/funnel/engagement/add-to-carts-value) | Monetary value of items added | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # Add to Carts: Track Shopping Cart Actions Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/add-to-carts Count the total add-to-cart events on your store. Measure shopping intent and analyze which products drive the most cart additions. Add to Carts counts the total number of times visitors add products to their shopping cart. ## Formula **Add to Carts** = **COUNT** ( Add to Cart Events ) ### Formula Components | Metric | Definition | | ---------------------- | --------------------------------------------------------- | | **Add to Cart Events** | Each instance a visitor clicks "Add to Cart" on a product | | Metadata | | | --------------- | ----------------------- | | **Type** | Number | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Sum | *** ## Example Your store tracked add-to-cart activity across product categories in January. | Product Category | Add to Carts | % of Total | | ---------------- | ------------ | ---------- | | Apparel | 623 | 41% | | Accessories | 412 | 27% | | Footwear | 298 | 20% | | Home Goods | 188 | 12% | | **Total** | **1,521** | **100%** | *** ## How It Works Add to Carts counts every add-to-cart event fired by the Upstack Pixel. Each click on an "Add to Cart" button triggers one event, regardless of quantity selected. Multiple adds of the same product by the same visitor count as separate events. *** ## When to Use | Scenario | Action | | ------------------- | ------------------------------------------- | | Funnel analysis | Measure volume entering the purchase funnel | | Product performance | Identify top products by cart additions | | Traffic quality | Compare cart actions across channels | | Trend monitoring | Track daily/weekly cart activity patterns | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------- | ------------------------------------ | | [Add to Cart Rate](/reference/metrics/funnel/engagement/add-to-cart-rate) | Conversion rate from views to cart | | [Add to Carts Value](/reference/metrics/funnel/engagement/add-to-carts-value) | Monetary value of cart additions | | [View Contents](/reference/metrics/funnel/engagement/view-contents) | Product views preceding cart actions | | [Initiate Checkouts](/reference/metrics/funnel/engagement/initiate-checkouts) | Next funnel step after cart | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # Add to Carts Value: Track Cart Monetary Intent Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/add-to-carts-value Measure the total monetary value of products added to cart. Analyze shopping intent in dollars to optimize high-value product pages and promotions. Add to Carts Value measures the total monetary value of all products added to shopping carts. ## Formula **Add to Carts Value** = **SUM** ( Add to Cart Event Values ) ### Formula Components | Metric | Definition | | ---------------------------- | --------------------------------------------------------------- | | **Add to Cart Event Values** | Product price multiplied by quantity for each add-to-cart event | | Metadata | | | --------------- | ----------------------- | | **Type** | Currency | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Sum | *** ## Example Your store tracked **1,521 add-to-cart events** in January with varying product values. | Product Category | Add to Carts | Avg Value | Total Value | | ---------------- | ------------ | --------- | ------------ | | Premium Items | 312 | \$89.00 | \$27,768 | | Core Products | 847 | \$45.00 | \$38,115 | | Accessories | 362 | \$18.00 | \$6,516 | | **Total** | **1,521** | — | **\$72,399** | *** ## How It Works Add to Carts Value sums the monetary value of each add-to-cart event. The Upstack Pixel captures the product price and quantity when visitors add items to cart, calculating value as price × quantity for each event. *** ## When to Use | Scenario | Action | | -------------------------- | ------------------------------------------------ | | Revenue potential analysis | Forecast potential revenue from cart intent | | Product merchandising | Identify which products drive highest cart value | | Promotion effectiveness | Compare value impact of discounts vs. full price | | Segment comparison | Analyze cart value by traffic source or audience | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------- | -------------------------------- | | [Add to Carts](/reference/metrics/funnel/engagement/add-to-carts) | Count of cart additions (volume) | | [Add to Cart Rate](/reference/metrics/funnel/engagement/add-to-cart-rate) | Conversion rate to cart | | [Initiate Checkouts Value](/reference/metrics/funnel/engagement/initiate-checkouts-value) | Value progressing to checkout | | [Cart Abandonment Rate](/reference/metrics/funnel/engagement/cart-abandonment-rate) | Percentage of cart value lost | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # ATC to IC Rate: Cart to Checkout Conversion Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/atc-to-ic-rate Measure the percentage of cart additions that proceed to checkout. Identify cart abandonment issues and optimize the path from cart to purchase. ATC to IC Rate measures the percentage of add-to-cart events that progress to initiate checkout. ## Formula **ATC to IC Rate** = ( **Initiate Checkouts** ÷ **Add to Carts** ) × 100 ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------- | ---------------------------------------- | | [**Initiate Checkouts**](/reference/metrics/funnel/engagement/initiate-checkouts) | Total checkout initiation events tracked | | [**Add to Carts**](/reference/metrics/funnel/engagement/add-to-carts) | Total add-to-cart events tracked | | Metadata | | | --------------- | ----------------------- | | **Type** | Percentage | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Ratio | *** ## Example Your store tracked **1,521 add-to-cart events** in January, with **912 progressing to checkout**. | Metric | Value | Calculation | | ------------------ | --------- | ------------------- | | Add to Carts | 1,521 | Items added to cart | | Initiate Checkouts | 912 | Checkout starts | | **ATC to IC Rate** | **60.0%** | (912 ÷ 1,521) × 100 | *** ## How It Works ATC to IC Rate calculates the conversion between cart addition and checkout initiation. The Upstack Pixel tracks add-to-cart events when visitors add products and initiate checkout events when they begin the checkout process. *** ## When to Use | Scenario | Action | | --------------------------- | -------------------------------------------- | | Cart experience audit | Identify friction preventing checkout starts | | Shipping threshold testing | Measure impact of free shipping offers | | Trust signal optimization | Test security badges, reviews, guarantees | | Mobile vs. desktop analysis | Compare checkout intent by device | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------- | --------------------------------------- | | [Add to Carts](/reference/metrics/funnel/engagement/add-to-carts) | Denominator — cart additions | | [Initiate Checkouts](/reference/metrics/funnel/engagement/initiate-checkouts) | Numerator — checkout starts | | [Add to Cart Rate](/reference/metrics/funnel/engagement/add-to-cart-rate) | Previous funnel step — views to cart | | [Checkout Conversion Rate](/reference/metrics/funnel/engagement/checkout-conversion-rate) | Next funnel step — checkout to purchase | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # Average Page Views per Session: Site Engagement Depth Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/avg-page-views-per-session Track average pages viewed per session to measure site engagement depth. Learn the formula, see examples, and identify content that keeps visitors exploring. The average number of pages visitors view during a single session on your site. ## Formula **Avg Page Views per Session** = **Page Views** ÷ **Sessions** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------- | -------------------------------------- | | [**Page Views**](/reference/metrics/funnel/awareness/page-views) | Total pages loaded across all sessions | | [**Sessions**](/reference/metrics/funnel/awareness/unique-sessions) | Unique visitor sessions on your site | | Metadata | | | --------------- | ----------------------- | | **Type** | Number | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Average | *** ## Example Your site recorded **4.2 pages per session** this month across 12,400 sessions: | Traffic Source | Avg Pages/Session | Sessions | | -------------- | ----------------- | -------- | | Organic Search | 5.1 | 4,200 | | Email Campaign | 4.8 | 2,800 | | Paid Social | 3.2 | 3,100 | | Direct | 3.9 | 2,300 | *** ## How It Works Each time a visitor lands on your site, Upstack starts a session. Every page they view increments the page view count. Dividing total page views by total sessions gives you the average browsing depth across all visitors. *** ## When to Use | Scenario | Action | | ------------------------------- | ----------------------------------------------------- | | Measuring content engagement | Higher values indicate visitors explore more pages | | Evaluating landing page quality | Low values suggest visitors leave without exploring | | Comparing traffic sources | Identify which channels bring more engaged visitors | | Optimizing site navigation | Test layout changes and measure browsing depth impact | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | [Page Views](/reference/metrics/funnel/awareness/page-views) | Numerator — total pages viewed | | [Unique Sessions](/reference/metrics/funnel/awareness/unique-sessions) | Denominator — total sessions counted | | [Avg View Contents per Session](/reference/metrics/funnel/engagement/avg-view-contents-per-session) | Similar depth metric for product views specifically | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # Average Page Visits per Session: Site Engagement Depth Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/avg-page-visits-per-session Track the average number of page visits per session to measure visitor engagement depth. Includes repeat visits to understand browsing intensity. Average Page Visits per Session measures the total number of page loads per session, including repeat visits to the same page. ## Formula **Avg Page Visits per Session** = **Page Visits** ÷ **Sessions** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------- | --------------------------------------------------------- | | **Page Visits** | Total page loads including repeat visits to the same page | | [**Sessions**](/reference/metrics/funnel/awareness/unique-sessions) | Count of distinct visitor sessions | | Metadata | | | --------------- | ----------------------- | | **Type** | Number | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Average | *** ## Example A skincare brand analyzing their collection page performance sees **8.3 average page visits per session** during a product launch week. | Day | Sessions | Total Page Visits | Avg Visits/Session | | --------- | -------- | ----------------- | ------------------ | | Monday | 4,200 | 33,600 | 8.0 | | Tuesday | 5,100 | 43,860 | 8.6 | | Wednesday | 4,800 | 40,800 | 8.5 | *** ## How It Works This metric counts every page load event during a session, including when visitors return to pages they've already viewed. A shopper who views a product page, goes to the cart, then returns to the product page counts as 3 page visits. This differs from Page Views per Session which counts only unique pages. *** ## When to Use | Scenario | Action | | --------------------------------- | --------------------------------------------------------- | | High visits but low conversions | Visitors may be confused or unable to find what they need | | Low visits per session | Consider improving internal linking and navigation | | Compare vs Page Views per Session | Large gap indicates visitors revisiting pages frequently | | A/B testing navigation | Higher visits may indicate more exploration or confusion | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | [Avg Page Views per Session](/reference/metrics/funnel/engagement/avg-page-views-per-session) | Counts unique pages only—compare to identify repeat browsing | | [Unique Sessions](/reference/metrics/funnel/awareness/unique-sessions) | Denominator in this calculation | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # Average View Contents per Session: Product Browsing Depth Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/avg-view-contents-per-session Track average product detail pages viewed per session. Measure browsing depth, catalog engagement, and identify high-intent shoppers exploring your products. Average View Contents per Session measures how many product detail pages visitors view in a typical session—indicating browsing depth across your catalog. ## Formula **Avg View Contents per Session** = **View Contents** ÷ **Sessions** ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------- | ------------------------------------ | | [**View Contents**](/reference/metrics/funnel/engagement/view-contents) | Total product detail page views | | [**Sessions**](/reference/metrics/funnel/awareness/unique-sessions) | Unique visitor sessions on your site | | Metadata | | | --------------- | ----------------------- | | **Type** | Number | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Ratio | *** ## Example A home decor store had **8,420 product views** across **3,200 sessions** last week: | Channel | View Contents | Sessions | Avg VC/Session | | -------------- | ------------- | -------- | -------------- | | Organic Search | 4,200 | 1,400 | 3.0 | | Paid Social | 2,800 | 1,200 | 2.3 | | Email | 1,420 | 600 | 2.4 | Organic search visitors browse 30% more products, signaling stronger purchase intent. *** ## How It Works Divides total View Content events by sessions. Higher values indicate visitors actively exploring multiple products rather than bouncing after one. *** ## When to Use | Scenario | Action | | ------------------------- | ----------------------------------------------- | | Catalog engagement low | Improve product discovery and recommendations | | Comparing traffic sources | Identify channels bringing engaged browsers | | Testing site navigation | Measure if changes increase product exploration | | Evaluating merchandising | Check if collections drive cross-browsing | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------- | ---------------------------------- | | [View Contents](/reference/metrics/funnel/engagement/view-contents) | Numerator—total product views | | [Unique Sessions](/reference/metrics/funnel/awareness/unique-sessions) | Denominator—total sessions | | [Avg Page Views per Session](/reference/metrics/funnel/engagement/avg-page-views-per-session) | Similar depth metric for all pages | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # Click Button Value: Button Click Revenue Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/click-button-value Track total monetary value from button click events. Measure engagement quality by seeing which button interactions lead to higher-value conversions. Total monetary value associated with button click events tracked by the Upstack pixel. ## Formula **Click Button Value** = **SUM** ( Click Button Event Values ) ### Formula Components | Metric | Definition | | ----------------------------- | ---------------------------------------------------- | | **Click Button Event Values** | Monetary value attributed to each button click event | | Metadata | | | --------------- | ----------------------- | | **Type** | Currency | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Sum | *** ## Example Your marketing landing pages generated **\$84,200** in attributed click button value last month: | Button Type | Click Value | Clicks | Avg Value/Click | | ----------- | ----------- | ------ | --------------- | | Buy Now | \$42,800 | 8,200 | \$5.22 | | Add to Cart | \$24,100 | 5,400 | \$4.46 | | Learn More | \$11,600 | 3,800 | \$3.05 | | Quick View | \$5,700 | 2,100 | \$2.71 | "Buy Now" buttons generate the highest value per click, indicating visitors who click them convert at higher order values. *** ## How It Works Click Button Value sums the monetary value attributed to each button click event tracked via the Upstack pixel. This captures the downstream revenue impact of specific button interactions. Higher values indicate that visitors clicking those buttons tend to complete purchases with larger order totals. *** ## When to Use | Scenario | Action | | ---------------------------- | ------------------------------------------------------- | | Evaluating CTA effectiveness | Compare click values across different button types | | Prioritizing page layout | Feature buttons with highest click-to-value ratios | | Assessing traffic quality | Higher click value suggests qualified visitors | | Campaign optimization | Target audiences driving high-value button interactions | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------- | ------------------------------------------ | | [Custom Events](/reference/metrics/funnel/engagement/custom-event) | Button clicks are tracked as custom events | | [View Contents Value](/reference/metrics/funnel/engagement/view-contents-value) | Product view value (similar value metric) | | [Add to Carts Value](/reference/metrics/funnel/engagement/add-to-carts-value) | Cart addition value (similar value metric) | | [Conversion Value](/reference/metrics/funnel/conversions/conversion-value) | Total revenue from completed conversions | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # Cost per Add to Cart: Acquisition Efficiency Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/cost-per-add-to-cart Track the average cost to generate an add to cart event. Calculate Channel Spend divided by Add to Cart Events to optimize your funnel efficiency. Average ad spend required to generate one add to cart event tracked by the Upstack pixel. ## Formula **Cost per Add to Cart** = **Channel Spend** ÷ **Add to Carts** ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [**Channel Spend**](/reference/metrics/advertising/blended/blended-spend/channel-spend) | Total advertising spend across all channels | | [**Add to Carts**](/reference/metrics/funnel/engagement/add-to-carts) | Count of add to cart events tracked by the Upstack pixel | | Metadata | | | --------------- | ----------------------- | | **Type** | Currency | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Ratio | *** ## Example Your campaigns spent **\$12,000** and generated **2,400 add to carts** this month: | Channel | Spend | Add to Carts | Cost/Add to Cart | | ---------- | ------------ | ------------ | ---------------- | | Meta Ads | \$7,200 | 1,800 | \$4.00 | | Google Ads | \$3,600 | 480 | \$7.50 | | TikTok Ads | \$1,200 | 120 | \$10.00 | | **Total** | **\$12,000** | **2,400** | **\$5.00** | *** ## How It Works Cost per Add to Cart measures how efficiently your advertising converts browsers into potential buyers. Lower values indicate more cost-effective top-of-funnel acquisition. The metric uses pixel-tracked add to cart events, ensuring accurate measurement regardless of platform reporting discrepancies. *** ## When to Use | Scenario | Action | | ------------------------------- | ------------------------------------------------------------- | | Evaluating creative performance | Compare cost per add to cart across ad sets | | Optimizing funnel efficiency | Identify channels with lowest acquisition costs | | Budget reallocation | Shift spend toward lower-cost channels | | Diagnosing conversion drops | Check if add to cart costs increased before purchases dropped | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------- | ----------------------------------- | | [Add to Carts](/reference/metrics/funnel/engagement/add-to-carts) | The denominator in this calculation | | [Channel Spend](/reference/metrics/advertising/blended/blended-spend/channel-spend) | The numerator in this calculation | | [Conversions](/reference/metrics/funnel/conversions/conversions) | Next step after add to cart | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # Cost per Initiate Checkout: Checkout Acquisition Cost Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/cost-per-initiate-checkout Track your cost per initiate checkout to measure checkout acquisition efficiency. Calculate spend efficiency for driving checkout initiations. Cost per Initiate Checkout measures how much you spend on advertising to generate each checkout initiation event. ## Formula **Cost per Initiate Checkout** = [**Channel Spend**](/reference/metrics/advertising/blended/blended-spend/channel-spend) ÷ [**Initiate Checkouts**](/reference/metrics/funnel/engagement/initiate-checkouts) ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------- | ------------------------------------------- | | [**Channel Spend**](/reference/metrics/advertising/blended/blended-spend/channel-spend) | Total advertising spend across all channels | | [**Initiate Checkouts**](/reference/metrics/funnel/engagement/initiate-checkouts) | Total checkout initiation events | | Metadata | | | --------------- | ----------------------- | | **Type** | Currency | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Ratio | *** ## Example Your store spent **\$5,000** on advertising last week and generated **1,000 initiate checkout events**. | Metric | Value | Calculation | | ------------------------------ | ---------- | -------------------- | | Channel Spend | \$5,000 | Total ad spend | | Initiate Checkouts | 1,000 | Checkout initiations | | **Cost per Initiate Checkout** | **\$5.00** | \$5,000 ÷ 1,000 | *** ## How It Works Cost per Initiate Checkout divides your total advertising spend by the number of checkout initiations. This metric helps you understand how efficiently your ad spend drives high-intent shopping behavior. Lower values indicate more efficient checkout acquisition. *** ## When to Use | Scenario | Action | | ------------------------------ | -------------------------------------------------------- | | Evaluating campaign efficiency | Compare CPIC across campaigns to identify top performers | | Optimizing funnel spend | Reduce CPIC by improving ad targeting or creative | | Budget allocation | Shift budget to channels with lower CPIC | | Benchmarking performance | Track CPIC trends over time to measure improvement | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------- | -------------------------------------------- | | [Initiate Checkouts](/reference/metrics/funnel/engagement/initiate-checkouts) | Denominator in this calculation | | [Channel Spend](/reference/metrics/advertising/blended/blended-spend/channel-spend) | Numerator in this calculation | | [Initiate Checkout Rate](/reference/metrics/funnel/engagement/initiate-checkout-rate) | Conversion rate from add to cart to checkout | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # Cost per View Content: Content Engagement Cost Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/cost-per-view-content Track your cost per view content to measure content engagement efficiency. Calculate spend efficiency for driving product page views. Cost per View Content measures how much you spend on advertising to generate each product page view event. ## Formula **Cost per View Content** = [**Channel Spend**](/reference/metrics/advertising/blended/blended-spend/channel-spend) ÷ [**View Contents**](/reference/metrics/funnel/engagement/view-contents) ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------- | ------------------------------------------- | | [**Channel Spend**](/reference/metrics/advertising/blended/blended-spend/channel-spend) | Total advertising spend across all channels | | [**View Contents**](/reference/metrics/funnel/engagement/view-contents) | Total product page view events | | Metadata | | | --------------- | ----------------------- | | **Type** | Currency | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Ratio | *** ## Example Your store spent **\$3,000** on advertising last week and generated **15,000 view content events**. | Metric | Value | Calculation | | ------------------------- | ---------- | ------------------ | | Channel Spend | \$3,000 | Total ad spend | | View Contents | 15,000 | Product page views | | **Cost per View Content** | **\$0.20** | \$3,000 ÷ 15,000 | *** ## How It Works Cost per View Content divides your total advertising spend by the number of product page views. This metric helps you understand how efficiently your ad spend drives product discovery. Lower values indicate more efficient top-of-funnel engagement. *** ## When to Use | Scenario | Action | | ------------------------------ | --------------------------------------------------------- | | Evaluating awareness campaigns | Compare CPVC across campaigns targeting product discovery | | Optimizing top-of-funnel spend | Reduce CPVC by improving ad relevance | | Budget allocation | Prioritize channels with lower CPVC for awareness goals | | Creative testing | Measure which ad creatives drive the most efficient views | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------- | ------------------------------- | | [View Contents](/reference/metrics/funnel/engagement/view-contents) | Denominator in this calculation | | [Channel Spend](/reference/metrics/advertising/blended/blended-spend/channel-spend) | Numerator in this calculation | | [Cost per Add to Cart](/reference/metrics/funnel/engagement/cost-per-add-to-cart) | Next step in funnel efficiency | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # Custom Events: Track Your Own Events Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/custom-event Track custom event counts fired from your site. Measure user interactions, feature usage, and custom milestones to optimize your e-commerce funnel. The total number of custom events tracked on your store via the Upstack pixel. ## Formula **Custom Events** = **COUNT** ( Custom Events ) ### Formula Components | Metric | Definition | | ----------------- | ----------------------------------------------------------------------------------------- | | **Custom Events** | Each custom event fired via the Upstack pixel `track` method with your defined event name | | Metadata | | | --------------- | ----------------------- | | **Type** | Number | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Count | *** ## Example Your outdoor gear store tracked **8,432 custom events** last week for key user interactions: | Event Name | Count | Share | | ----------------------- | ----- | ----- | | size\_guide\_opened | 3,150 | 37% | | video\_played | 2,890 | 34% | | wishlist\_added | 1,560 | 19% | | store\_locator\_clicked | 832 | 10% | *** ## How It Works Custom Events count each time your site fires a custom event via the Upstack pixel. You define the event name and properties when implementing the tracking call. Each event is counted individually regardless of the visitor or session. *** ## When to Use | Scenario | Action | | --------------------------- | -------------------------------------------------------------- | | Track feature engagement | Measure how often users interact with specific features | | Monitor user milestones | Count key actions like video plays or guide downloads | | Compare campaign variations | Track custom events tied to A/B test interactions | | Build custom funnels | Combine custom events with standard events for deeper analysis | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------- | --------------------------------------------- | | [Total Events](/reference/metrics/funnel/engagement/total-events) | Includes custom events in overall event count | | [View Contents](/reference/metrics/funnel/engagement/view-contents) | Standard event for product page views | | [Add to Carts](/reference/metrics/funnel/engagement/add-to-carts) | Standard event for cart additions | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # Engagement Metrics: Shopping Behavior & Funnel Progression Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/index Track engagement metrics in Upstack Funnel. Includes View Contents, Add to Carts, Initiate Checkouts, conversion rates, and shopping behavior analytics. Engagement metrics measure how visitors interact with your store—from viewing products to adding items to cart and starting checkout. These metrics help you identify drop-off points and optimize your conversion funnel. **Data Source:** [Upstack Pixel](/pixel)\ **Metrics:** 22 ## Metrics in This Group ### Event Counts | Metric | Description | When to Use | | ----------------------------------------------------------------------------- | ----------------------------- | -------------------------- | | [View Contents](/reference/metrics/funnel/engagement/view-contents) | Product detail page views | Measure product discovery | | [Add to Carts](/reference/metrics/funnel/engagement/add-to-carts) | Items added to shopping cart | Track purchase intent | | [Initiate Checkouts](/reference/metrics/funnel/engagement/initiate-checkouts) | Checkout sessions started | Measure checkout reach | | [Total Events](/reference/metrics/funnel/engagement/total-events) | All tracking events processed | Monitor overall activity | | [Custom Events](/reference/metrics/funnel/engagement/custom-event) | Custom events fired via pixel | Track feature interactions | ### Cost per Event | Metric | Description | When to Use | | --------------------------------------------------------------------------------------------- | --------------------------- | ------------------------------- | | [Cost per View Content](/reference/metrics/funnel/engagement/cost-per-view-content) | Ad spend per product view | Evaluate product discovery cost | | [Cost per Add to Cart](/reference/metrics/funnel/engagement/cost-per-add-to-cart) | Ad spend per cart addition | Measure intent acquisition cost | | [Cost per Initiate Checkout](/reference/metrics/funnel/engagement/cost-per-initiate-checkout) | Ad spend per checkout start | Track checkout acquisition cost | ### Event Value | Metric | Description | When to Use | | ----------------------------------------------------------------------------------------- | --------------------------------- | ----------------------------------- | | [View Contents Value](/reference/metrics/funnel/engagement/view-contents-value) | Monetary value of product views | Attribute value to discovery | | [Add to Carts Value](/reference/metrics/funnel/engagement/add-to-carts-value) | Monetary value of cart additions | Attribute value to intent | | [Initiate Checkouts Value](/reference/metrics/funnel/engagement/initiate-checkouts-value) | Monetary value of checkout starts | Attribute value to checkout | | [Click Button Value](/reference/metrics/funnel/engagement/click-button-value) | Monetary value of button clicks | Attribute value to CTA interactions | ### Conversion Rates | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------- | ---------------------------------- | --------------------------------- | | [View Content Rate](/reference/metrics/funnel/engagement/view-content-rate) | Page views → Product views % | Measure navigation effectiveness | | [Add to Cart Rate](/reference/metrics/funnel/engagement/add-to-cart-rate) | Product views → Cart additions % | Evaluate product page persuasion | | [Initiate Checkout Rate](/reference/metrics/funnel/engagement/initiate-checkout-rate) | Cart additions → Checkout starts % | Track cart-to-checkout conversion | | [Add to Cart to IC Rate](/reference/metrics/funnel/engagement/atc-to-ic-rate) | Cart → Checkout progression % | Identify cart abandonment | | [Page Views to View Contents Rate](/reference/metrics/funnel/engagement/pv-to-vc-rate) | All pages → Product pages % | Measure product discovery rate | | [View Contents to Add to Cart Rate](/reference/metrics/funnel/engagement/vc-to-atc-rate) | Product views → Cart % | Track product page effectiveness | | [Session View Product Rate](/reference/metrics/funnel/engagement/session-view-product-rate) | Sessions with product view % | Measure discovery engagement | ### Session Behavior | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------- | | [Average Page Views per Session](/reference/metrics/funnel/engagement/avg-page-views-per-session) | Pages viewed per visit | Measure browsing depth | | [Average View Contents per Session](/reference/metrics/funnel/engagement/avg-view-contents-per-session) | Products viewed per visit | Track catalog exploration | | [Average Page Visits per Session](/reference/metrics/funnel/engagement/avg-page-visits-per-session) | Page visits including repeats | Compare to unique page views | ## How These Metrics Relate Engagement metrics track progression through the shopping funnel: ``` Page Views → View Contents → Add to Carts → Initiate Checkouts → Purchase ↓ ↓ ↓ ↓ VC Rate ATC Rate IC Rate Purchase Rate ``` Each funnel stage has three metrics: 1. **Count** — How many events occurred 2. **Cost** — How much ad spend per event 3. **Value** — Revenue attributed to that stage ## Choosing the Right Metric * **Funnel health**: Compare conversion rates at each stage to find drop-offs * **Product pages**: Low ATC Rate → improve product descriptions, images, or pricing * **Cart experience**: Low IC Rate → simplify cart, reduce friction, show trust signals * **Acquisition efficiency**: Compare Cost per Event across channels * **Session quality**: High Avg Page Views/Session indicates engaged visitors * **Discovery**: Session View Product Rate shows if visitors find your products # Initiate Checkout Rate: Cart to Checkout Conversion Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/initiate-checkout-rate Track your initiate checkout rate to measure cart-to-checkout conversion. Calculate the percentage of add to carts that proceed to checkout. Initiate Checkout Rate measures the percentage of add to cart events that proceed to checkout initiation. ## Formula **Initiate Checkout Rate** = ( [**Initiate Checkouts**](/reference/metrics/funnel/engagement/initiate-checkouts) ÷ [**Add to Carts**](/reference/metrics/funnel/engagement/add-to-carts) ) × 100 ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------- | -------------------------------- | | [**Initiate Checkouts**](/reference/metrics/funnel/engagement/initiate-checkouts) | Total checkout initiation events | | [**Add to Carts**](/reference/metrics/funnel/engagement/add-to-carts) | Total add to cart events | | Metadata | | | --------------- | ----------------------- | | **Type** | Percentage | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Ratio | *** ## Example Your store had **2,500 add to cart events** and **750 initiate checkout events** last week. | Metric | Value | Calculation | | -------------------------- | ------- | -------------------- | | Add to Carts | 2,500 | Cart additions | | Initiate Checkouts | 750 | Checkout initiations | | **Initiate Checkout Rate** | **30%** | (750 ÷ 2,500) × 100 | *** ## How It Works Initiate Checkout Rate divides checkout initiations by add to carts and multiplies by 100 to express as a percentage. This metric reveals how effectively your store converts shopping intent into checkout behavior. Higher rates indicate a smoother cart-to-checkout experience. *** ## When to Use | Scenario | Action | | --------------------------- | ------------------------------------------------- | | Identifying funnel friction | Low rates indicate checkout barriers | | A/B testing cart experience | Compare rates across cart page variants | | Diagnosing conversion drops | Sudden rate changes signal UX or pricing issues | | Optimizing checkout flow | Improve rates by simplifying the path to checkout | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------- | ---------------------------------- | | [Initiate Checkouts](/reference/metrics/funnel/engagement/initiate-checkouts) | Numerator in this calculation | | [Add to Carts](/reference/metrics/funnel/engagement/add-to-carts) | Denominator in this calculation | | [Add to Cart Rate](/reference/metrics/funnel/engagement/add-to-cart-rate) | Previous step in funnel conversion | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # Initiate Checkouts: Track Checkout Intent Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/initiate-checkouts Track how many visitors initiate checkout. Use Initiate Checkouts to measure purchase intent and optimize your checkout funnel. Initiate Checkouts counts the number of times visitors begin the checkout process by loading the checkout page. ## Formula **Initiate Checkouts** = **COUNT** ( Checkout Page Loads ) ### Formula Components | Metric | Definition | | ----------------------- | ------------------------------------------------------- | | **Checkout Page Loads** | Number of times the checkout page is loaded by visitors | | Metadata | | | --------------- | ----------------------- | | **Type** | Number | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Count | *** ## Example Your store had **3,247 checkout initiations** in April, up from 2,891 in March. | Week | Initiate Checkouts | Change | | ------ | ------------------ | ------ | | Week 1 | 782 | — | | Week 2 | 845 | +8.1% | | Week 3 | 801 | −5.2% | | Week 4 | 819 | +2.2% | *** ## How It Works The Upstack Pixel fires an event each time a visitor loads your checkout page. Initiate Checkouts counts these events to measure how many visitors reach the checkout step, regardless of whether they complete a purchase. *** ## When to Use | Scenario | Action | | ------------------------------------- | ----------------------------------------------------------------------------- | | Measuring checkout funnel performance | Compare Initiate Checkouts to purchases to calculate checkout completion rate | | Evaluating cart abandonment | High initiations with low purchases indicates checkout friction | | Assessing ad campaign quality | Campaigns driving more checkout initiations show stronger purchase intent | | A/B testing cart changes | Track if cart modifications improve checkout initiation rates | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------- | --------------------------------------------- | | [Add to Carts](/reference/metrics/funnel/engagement/add-to-carts) | Precedes checkout initiation in the funnel | | [Purchases](/reference/metrics/funnel/conversion/purchases) | Measures completed conversions from checkout | | [View Contents](/reference/metrics/funnel/engagement/view-contents) | Earlier funnel stage showing product interest | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # Initiate Checkouts Value: Checkout Intent Revenue Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/initiate-checkouts-value Track your initiate checkouts value to measure total checkout intent revenue. Sum of all values from checkout initiation events. Initiate Checkouts Value measures the total monetary value associated with all checkout initiation events. ## Formula **Initiate Checkouts Value** = **SUM** ( Initiate Checkout Event Values ) ### Formula Components | Metric | Definition | | ---------------------------------- | ------------------------------------------------------ | | **Initiate Checkout Event Values** | The cart value at the time of each checkout initiation | | Metadata | | | --------------- | ----------------------- | | **Type** | Currency | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Sum | *** ## Example Your store had **500 initiate checkout events** last week with varying cart values. | Event | Cart Value | | ---------------------- | ------------ | | Checkout 1 | \$85.00 | | Checkout 2 | \$125.00 | | Checkout 3 | \$45.00 | | ... | ... | | **Total (500 events)** | **\$42,500** | *** ## How It Works Initiate Checkouts Value sums the cart value from each checkout initiation event tracked by the Upstack Pixel. This metric represents the total potential revenue from visitors who reached checkout. Compare this to actual revenue to understand checkout abandonment impact. *** ## When to Use | Scenario | Action | | ---------------------------- | -------------------------------------------------- | | Measuring checkout intent | Track total potential revenue entering checkout | | Calculating abandonment loss | Subtract completed revenue to find abandoned value | | Evaluating campaign value | Compare intent value across traffic sources | | Forecasting revenue | Use checkout value as a leading indicator | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------- | --------------------------------------------- | | [Initiate Checkouts](/reference/metrics/funnel/engagement/initiate-checkouts) | Count of events that contribute to this value | | [Add to Cart Value](/reference/metrics/funnel/engagement/add-to-cart-value) | Earlier funnel value metric | | [Conversion Value](/reference/metrics/funnel/conversions/conversion-value) | Final conversion value to compare | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # PV to VC Rate: Page View to View Content Conversion Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/pv-to-vc-rate Measure the percentage of page views that lead to product views. Use PV to VC Rate to optimize site navigation and product discovery. PV to VC Rate measures the percentage of page views that result in product detail page views, indicating how effectively your site drives product discovery. ## Formula **PV to VC Rate** = ( **View Contents** ÷ **Page Views** ) × 100 ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------- | --------------------------------------- | | [**View Contents**](/reference/metrics/funnel/engagement/view-contents) | Total product detail page views | | [**Page Views**](/reference/metrics/funnel/awareness/page-views) | Total page load events across your site | | Metadata | | | --------------- | ----------------------- | | **Type** | Percentage | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Ratio | *** ## Example Your store had **45,000 page views** and **12,150 product views** in May, producing a **27% PV to VC Rate**. | Traffic Source | Page Views | View Contents | PV to VC Rate | | -------------- | ---------- | ------------- | ------------- | | Organic Search | 18,000 | 5,400 | 30% | | Paid Social | 15,000 | 3,750 | 25% | | Direct | 12,000 | 3,000 | 25% | *** ## How It Works PV to VC Rate divides View Contents (product detail page views) by total Page Views and multiplies by 100. A higher rate indicates visitors are successfully finding and exploring products. A lower rate may suggest navigation issues or misaligned traffic. *** ## When to Use | Scenario | Action | | ------------------------------------- | -------------------------------------------------------------- | | Evaluating site navigation | Low rate indicates visitors struggle to find products | | Comparing traffic sources | Identify which channels drive more product-interested visitors | | Measuring homepage effectiveness | Track if homepage changes improve product discovery | | Analyzing collection page performance | Higher rate suggests better product merchandising | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------- | --------------------------------------- | | [View Contents](/reference/metrics/funnel/engagement/view-contents) | Numerator measuring product page views | | [Page Views](/reference/metrics/funnel/awareness/page-views) | Denominator measuring all page loads | | [VC to ATC Rate](/reference/metrics/funnel/engagement/vc-to-atc-rate) | Next conversion step after product view | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # Session View Product Rate: Sessions with Product Views Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/session-view-product-rate Measure the percentage of sessions where visitors view at least one product. Use Session View Product Rate to assess product discovery. Session View Product Rate measures the percentage of sessions where visitors viewed at least one product detail page, indicating overall product discovery effectiveness. ## Formula **Session View Product Rate** = ( **Sessions with Product View** ÷ **Total Sessions** ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | **Sessions with Product View** | Count of unique sessions containing at least one product detail page view | | [**Total Sessions**](/reference/metrics/funnel/awareness/unique-sessions) | Total number of unique visitor sessions | | Metadata | | | --------------- | ----------------------- | | **Type** | Percentage | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Ratio | *** ## Example Your store had **8,500 total sessions** in June, with **5,100 sessions** including at least one product view, producing a **60% Session View Product Rate**. | Device | Total Sessions | Sessions with Product View | Rate | | ------- | -------------- | -------------------------- | ---- | | Mobile | 5,100 | 2,856 | 56% | | Desktop | 2,890 | 1,907 | 66% | | Tablet | 510 | 337 | 66% | *** ## How It Works Session View Product Rate counts unique sessions where the visitor viewed at least one product detail page, then divides by total sessions. Unlike PV to VC Rate which measures page-level conversion, this metric measures session-level engagement—whether a visitor explored any products during their visit. *** ## When to Use | Scenario | Action | | ---------------------------- | ------------------------------------------------------------------ | | Measuring product discovery | Track what percentage of visitors engage with products | | Comparing device experiences | Identify if mobile visitors struggle to find products | | Evaluating landing pages | Low rate from specific pages suggests poor product visibility | | Assessing traffic quality | High-quality traffic sources should have higher product view rates | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------- | ------------------------------------------------- | | [Unique Sessions](/reference/metrics/funnel/awareness/unique-sessions) | Denominator measuring total sessions | | [View Contents](/reference/metrics/funnel/engagement/view-contents) | Related event that triggers session product view | | [PV to VC Rate](/reference/metrics/funnel/engagement/pv-to-vc-rate) | Page-level conversion vs session-level engagement | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # Sign Up Value: Track Registration Monetary Worth Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/sign-up-value Measure the total monetary value of sign up events. Analyze registration value to understand lead quality and optimize acquisition channels. Sign Up Value measures the total monetary value assigned to sign up events on your site. ## Formula **Sign Up Value** = **SUM** ( Sign Up Event Values ) ### Formula Components | Metric | Definition | | ------------------------ | -------------------------------------------------------------- | | **Sign Up Event Values** | Value assigned to each sign up event when tracked by the pixel | | Metadata | | | --------------- | ----------------------- | | **Type** | Currency | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Sum | *** ## Example Your site tracked **847 sign up events** in January with assigned values based on registration type. | Registration Type | Sign Ups | Avg Value | Total Value | | ----------------- | -------- | --------- | ------------ | | Newsletter | 524 | \$5.00 | \$2,620 | | Account Creation | 256 | \$25.00 | \$6,400 | | Premium Trial | 67 | \$75.00 | \$5,025 | | **Total** | **847** | — | **\$14,045** | *** ## How It Works Sign Up Value sums the monetary value assigned to each sign up event. The Upstack Pixel captures the value property when a sign up event fires. You define the value in your tracking implementation based on the registration type or estimated lead worth. *** ## When to Use | Scenario | Action | | --------------------- | ---------------------------------------------------------- | | Lead value analysis | Quantify registration pipeline in monetary terms | | Channel ROI | Compare sign up value generated by traffic source | | Campaign optimization | Identify which campaigns drive highest-value registrations | | Funnel value tracking | Monitor total value entering your registration funnel | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------- | --------------------------------- | | [Sign Ups](/reference/metrics/funnel/engagement/sign-ups) | Count of sign up events (volume) | | [Cost per Sign Up](/reference/metrics/funnel/engagement/sign-up-cost) | Acquisition cost for each sign up | | [Lead Value](/reference/metrics/funnel/engagement/lead-value) | Value of lead generation events | | [Complete Registration Value](/reference/metrics/funnel/engagement/complete-registration-value) | Value of completed registrations | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # Total Events: All Tracked Interactions Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/total-events Count all tracked events across your site. Use Total Events to monitor overall tracking health and visitor engagement volume. Total Events counts every tracked interaction captured by the Upstack Pixel, including page views, product views, add to carts, checkouts, and purchases. ## Formula **Total Events** = **COUNT** ( All Events ) ### Formula Components | Metric | Definition | | -------------- | ------------------------------------------------------- | | **All Events** | Every tracked interaction captured by the Upstack Pixel | | Metadata | | | --------------- | ----------------------- | | **Type** | Number | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Count | *** ## Example Your store tracked **127,450 total events** in July across all event types. | Event Type | Count | % of Total | | ------------------ | ------ | ---------- | | Page Views | 89,000 | 69.8% | | View Contents | 24,500 | 19.2% | | Add to Carts | 8,750 | 6.9% | | Initiate Checkouts | 3,450 | 2.7% | | Purchases | 1,750 | 1.4% | *** ## How It Works Total Events aggregates all tracked interactions captured by the Upstack Pixel. This includes standard e-commerce events (page views, product views, add to carts, checkouts, purchases) plus any custom events you've configured. Use this metric to monitor tracking health and overall site engagement. *** ## When to Use | Scenario | Action | | ----------------------------- | --------------------------------------------- | | Monitoring tracking health | Sudden drops indicate pixel or site issues | | Measuring engagement volume | Track overall interaction trends over time | | Validating pixel installation | Confirm events are firing after setup changes | | Capacity planning | Understand event volume for quota management | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------- | ------------------------------------- | | [Page Views](/reference/metrics/funnel/awareness/page-views) | Largest component of total events | | [View Contents](/reference/metrics/funnel/engagement/view-contents) | Product view events included in total | | [Purchases](/reference/metrics/funnel/conversion/purchases) | Conversion events included in total | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # View Contents to Add to Cart Rate: Product Page Effectiveness Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/vc-to-atc-rate Measure product page effectiveness with View Contents to Add to Cart Rate. Track what percentage of product views convert to cart additions in Upstack. View Contents to Add to Cart Rate measures the percentage of product page views that resulted in an item being added to cart—indicating product page persuasiveness. ## Formula **VC to ATC Rate** = ( **Add to Carts** ÷ **View Contents** ) × 100 ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------- | -------------------------------------- | | [**Add to Carts**](/reference/metrics/funnel/engagement/add-to-carts) | Number of items added to shopping cart | | [**View Contents**](/reference/metrics/funnel/engagement/view-contents) | Number of product detail page views | | Metadata | | | --------------- | ----------------------- | | **Type** | Percentage | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Ratio | *** ## Example A home decor store received **8,420 product page views** last week, resulting in **1,347 add to carts**. | Metric | Value | Calculation | | ------------------ | --------- | -------------------- | | View Contents | 8,420 | Product pages viewed | | Add to Carts | 1,347 | Items added to cart | | **VC to ATC Rate** | **16.0%** | 1,347 ÷ 8,420 × 100 | *** ## How It Works This rate is calculated by dividing total add to cart events by total view content events, then multiplying by 100. It measures how effectively your product pages convert browsers into shoppers with purchase intent. *** ## When to Use | Scenario | Action | | ------------------------------ | -------------------------------------------------- | | Low VC to ATC Rate (below 10%) | Improve product images, descriptions, or pricing | | High rate but low conversions | Focus on checkout friction, not product pages | | Comparing products | Identify which products convert browsers to buyers | | A/B testing | Measure product page layout changes | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------- | ---------------------------------- | | [View Contents](/reference/metrics/funnel/engagement/view-contents) | Denominator—total product views | | [Add to Carts](/reference/metrics/funnel/engagement/add-to-carts) | Numerator—total cart additions | | [ATC to IC Rate](/reference/metrics/funnel/engagement/atc-to-ic-rate) | Next funnel stage—cart to checkout | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # View Content Rate: Product Page Discovery Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/view-content-rate Track what percentage of page views reach product pages. Learn the formula, see examples, and optimize your site navigation to improve product discovery. The percentage of page views that resulted in a product detail page view. ## Formula **View Content Rate** = ( **View Contents** ÷ **Page Views** ) × 100 ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------- | ---------------------------------------------- | | [**View Contents**](/reference/metrics/funnel/engagement/view-contents) | Product detail page views tracked by the pixel | | [**Page Views**](/reference/metrics/funnel/awareness/page-views) | Total page load events across your site | | Metadata | | | --------------- | ----------------------- | | **Type** | Percentage | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Ratio | *** ## Example Your store had **85,000 page views** and **34,000 product page views** last month, giving a View Content Rate of **40%**: | Traffic Source | Page Views | View Contents | VC Rate | | -------------- | ---------- | ------------- | ------- | | Organic Search | 32,000 | 15,360 | 48% | | Paid Social | 28,000 | 9,800 | 35% | | Direct | 25,000 | 8,840 | 35% | *** ## How It Works View Content Rate measures how effectively your site guides visitors to product pages. A higher rate means visitors are finding and viewing products rather than bouncing from landing pages or getting lost in navigation. *** ## When to Use | Scenario | Action | | -------------------------- | ------------------------------------------------- | | Navigation optimization | Low VC Rate suggests visitors can't find products | | Landing page analysis | Compare rates across entry points | | Traffic quality assessment | Higher VC Rate indicates more engaged visitors | | Category performance | Identify which collections drive product views | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------- | ------------------------------------------------- | | [View Contents](/reference/metrics/funnel/engagement/view-contents) | The numerator—absolute count of product views | | [Page Views](/reference/metrics/funnel/awareness/page-views) | The denominator—total page loads | | [Add to Cart Rate](/reference/metrics/funnel/engagement/add-to-cart-rate) | Next funnel stage—product views to cart additions | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # View Contents: Product Page Views Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/view-contents Track how often customers view product detail pages. Measure top-of-funnel engagement and identify high-interest products to optimize your e-commerce marketing. The total number of times a product detail page was viewed on your store. ## Formula **View Contents** = **COUNT** ( Product Page Views ) ### Formula Components | Metric | Definition | | ---------------------- | --------------------------------------------------------------------------------------- | | **Product Page Views** | Each visit to a product page fires one View Content event, tracked by the Upstack pixel | | Metadata | | | --------------- | ----------------------- | | **Type** | Number | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Count | *** ## Example Your skincare brand tracked **12,847 product page views** last week: | Product | Views | Share | | ---------------------- | ----- | ----- | | Vitamin C Serum | 4,250 | 33% | | Retinol Night Cream | 3,100 | 24% | | Hyaluronic Moisturizer | 2,890 | 23% | | SPF 50 Sunscreen | 2,607 | 20% | *** ## How It Works View Contents counts each time a visitor lands on a product detail page (PDP). This includes traffic from ads, organic search, email campaigns, and direct visits. Multiple views by the same visitor are counted separately. *** ## When to Use | Scenario | Action | | -------------------------- | ------------------------------------------------------ | | Identify trending products | Find which products attract the most interest | | Measure ad effectiveness | Compare views before and after campaign launch | | Calculate conversion rates | Divide Add to Carts or Purchases by View Contents | | Optimize merchandising | Feature high-view, low-conversion products differently | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------- | ----------------------------------- | | [Add to Carts](/reference/metrics/funnel/engagement/add-to-carts) | Next step in funnel after viewing | | [View Content Rate](/reference/metrics/funnel/engagement/view-content-rate) | Views as percentage of sessions | | [VC to ATC Rate](/reference/metrics/funnel/engagement/vc-to-atc-rate) | Conversion rate from views to carts | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # View Contents Value: Product View Revenue Source: https://docs.upstackdata.com/reference/metrics/funnel/engagement/view-contents-value Track total monetary value from product view events. Measure engagement quality by seeing which product views lead to higher-value conversions. Total monetary value associated with product detail page views tracked by the Upstack pixel. ## Formula **View Contents Value** = **SUM** ( View Content Event Values ) ### Formula Components | Metric | Definition | | ----------------------------- | ---------------------------------------------------- | | **View Content Event Values** | Monetary value attributed to each product view event | | Metadata | | | --------------- | ----------------------- | | **Type** | Currency | | **Data Source** | [Upstack Pixel](/pixel) | | **Aggregation** | Sum | *** ## Example Your summer collection pages generated **\$127,400** in attributed view value last month: | Product Category | View Value | Views | Avg Value/View | | ---------------- | ---------- | ------ | -------------- | | Dresses | \$48,200 | 12,400 | \$3.89 | | Accessories | \$34,100 | 9,800 | \$3.48 | | Footwear | \$28,600 | 6,200 | \$4.61 | | Swimwear | \$16,500 | 4,100 | \$4.02 | Footwear has the highest value per view, indicating visitors viewing those products convert at higher order values. *** ## How It Works View Contents Value sums the monetary value attributed to each product view event. This captures the downstream revenue impact of product page engagement. Higher values indicate that visitors viewing those products tend to complete purchases with larger order totals. *** ## When to Use | Scenario | Action | | ------------------------------- | -------------------------------------------------- | | Evaluating product page quality | Compare view values across product categories | | Prioritizing merchandising | Feature products with highest view-to-value ratios | | Assessing traffic quality | Higher view value suggests qualified visitors | | Campaign optimization | Target audiences driving high-value product views | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------- | ----------------------------------------------- | | [View Contents](/reference/metrics/funnel/engagement/view-contents) | Count of events (this metric sums their values) | | [Cost per View Content](/reference/metrics/funnel/engagement/cost-per-view-content) | Ad spend efficiency per view event | | [Add to Carts](/reference/metrics/funnel/engagement/add-to-carts) | Next funnel step after product views | | [Conversion Value](/reference/metrics/funnel/conversions/conversion-value) | Total revenue from completed conversions | [See all Engagement metrics →](/reference/metrics/funnel/engagement) # Funnel Metrics: Track Conversions and Customer Journey Source: https://docs.upstackdata.com/reference/metrics/funnel/index Track attributed conversions and customer journey progression in Upstack. View 5 funnel metrics including Conversions, Conversion Value, Session Conversion Rate, and Unique Converters. Funnel metrics track how users progress through your conversion funnel—from initial engagement to completed purchase. These metrics help you understand attribution effectiveness and identify where customers convert. **Data Source:** Upstack Pixel + Shopify\ **Metrics in Category:** 5 ## Subcategories ### Attributed Conversions Track attributed conversion events and their monetary value across your marketing channels. These are cross-channel funnel metrics distinct from platform-reported conversions (like Meta Conversions). → [View Attributed Conversion Metrics](/reference/metrics/funnel/conversions) ## All Funnel Metrics | Metric | Description | | ------------------------------------------------------------------------------------------ | -------------------------------------------- | | [Attributed Conversions](/reference/metrics/funnel/conversions/conversions) | Attributed conversion events | | [Conversion Value](/reference/metrics/funnel/conversions/conversion-value) | Total value of conversions | | [Unique Converters](/reference/metrics/funnel/conversions/unique-converters) | Distinct customers who converted | | [Average Conversion Value](/reference/metrics/funnel/conversions/average-conversion-value) | Average value per conversion | | [Session Conversion Rate](/reference/metrics/funnel/conversions/session-conversion-rate) | Percentage of sessions resulting in purchase | ## When to Use Funnel Metrics * **Measure campaign ROI** — Compare conversion value against ad spend to calculate true return on investment * **Optimize attribution** — Understand which touchpoints drive conversions across the customer journey * **Identify high-value segments** — Use average conversion value to find and target your most valuable customers # Metrics Reference Source: https://docs.upstackdata.com/reference/metrics/index Complete reference for 846 Upstack metrics. Formulas, examples, and best practices for attribution, revenue, advertising, website events, and data quality. Upstack tracks 846 metrics across your entire marketing and e-commerce stack—from Shopify orders to ad platform performance to website engagement. Use this reference to understand what each metric measures, how it's calculated, and how to use it for analysis. ## Browse by Category **4 metrics** — Attributed conversions and customer journey progression. **305 metrics** — Spend, ROAS, CPA across Meta, Google, TikTok, and Blended. **268 metrics** — Orders, revenue, AOV, and profitability. *(coming soon)* **253 metrics** — Page views, sessions, and tracked events. *(coming soon)* **16 metrics** — Event match quality and tracking health. ## Category Overview | Category | Metrics | Status | Data Source | | ----------------------------------------------- | ------- | -------------- | ----------------------- | | [Funnel](/reference/metrics/funnel) | 4 | ✅ Available | Upstack Pixel + Shopify | | [Advertising](/reference/metrics/advertising) | 305 | ✅ Available | Ad Platforms | | Revenue & Orders | 268 | 🔜 Coming soon | Shopify | | Website Events | 253 | 🔜 Coming soon | Upstack Pixel | | [Data Quality](/reference/metrics/data-quality) | 16 | ✅ Available | Upstack Pixel | ### Advertising Platform Breakdown | Platform | Metrics | Status | | ----------------------------------------------- | ------- | -------------- | | [Meta Ads](/reference/metrics/advertising/meta) | 112 | ✅ Available | | Google Ads | 22 | 🔜 Coming soon | | TikTok Ads | 61 | 🔜 Coming soon | | Blended | 110 | 🔜 Coming soon | ## Getting Started **New to Upstack metrics?** Here's where to start based on what you're trying to do: Start with **[Funnel Metrics](/reference/metrics/funnel)**—specifically [Conversions](/reference/metrics/funnel/conversions/conversions) and [Conversion Value](/reference/metrics/funnel/conversions/conversion-value). These show attributed conversions across all your marketing channels. Then explore **[Advertising Metrics](/reference/metrics/advertising)** to see platform-specific performance like [Meta ROAS](/reference/metrics/advertising/meta/meta-efficiency/meta-roas) and [Meta CPA](/reference/metrics/advertising/meta/meta-efficiency/meta-cpa). Go directly to **[Advertising Metrics](/reference/metrics/advertising)** → **[Meta Efficiency](/reference/metrics/advertising/meta/meta-efficiency)**. Key metrics include ROAS, CPA, and cost-per-purchase. Compare with **[Meta Spend](/reference/metrics/advertising/meta/meta-spend)** to understand budget consumption. Start with **[Meta Audience](/reference/metrics/advertising/meta/meta-audience)**—Reach, Impressions, Frequency, and CPM help you understand who you're reaching and at what cost. See **[Meta Clicks](/reference/metrics/advertising/meta/meta-clicks)** for CTR, CPC, landing page views, and click costs. This subcategory has 18 metrics covering all click types. ## How Metrics Work Upstack calculates metrics from three primary data sources: 1. **Shopify** — Order data, revenue, customer information, and profitability. 2. **Ad Platforms** — Spend, impressions, clicks, and conversions from Meta, Google, TikTok. 3. **Upstack Pixel** — First-party tracking for page views, sessions, add-to-carts, and conversions with identity resolution. Metrics are aggregated by your selected date range and can be filtered by traffic source, device, campaign, or UTM parameters. ## Next Steps * **[Funnel Metrics →](/reference/metrics/funnel)** — Start with attribution basics * **[Advertising Metrics →](/reference/metrics/advertising)** — Dive into ad platform performance # Cancelled Amount: Revenue Lost to Order Cancellations Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/cancelled-amount Track total dollar value of cancelled orders. Monitor lost revenue before fulfillment and identify checkout or inventory issues in Upstack. The total dollar value of orders cancelled before fulfillment. ## Formula **Cancelled Amount** = **SUM** ( Order Value ) **WHERE** status = cancelled ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------- | -------------------------------------------------------- | | **Order Value** | The total value of each order | | [**status = cancelled**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders marked as cancelled before fulfillment | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store had **\$12,750 in cancelled orders** during Q1: | Month | Cancelled Amount | Orders Cancelled | | -------- | ---------------- | ---------------- | | January | \$3,200 | 18 | | February | \$4,850 | 27 | | March | \$4,700 | 24 | *** ## How It Works Cancelled Amount sums the total value of all orders cancelled in Shopify before fulfillment. Unlike refunds, cancellations represent potential revenue that never converted. Spikes may indicate payment failures, inventory stockouts, or checkout friction. *** ## When to Use | Scenario | Action | | ------------------------ | ----------------------------------------------- | | Track lost revenue | Monitor potential sales that didn't complete | | Identify payment issues | Compare against declined transactions | | Spot inventory problems | Correlate with stockout events | | Segment by customer type | Compare new vs returning customer cancellations | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------- | -------------------------------------------- | | [Cancelled Orders](/reference/metrics/orders/adjustments/cancelled-orders) | Count of cancelled orders (not dollar value) | | [Refund Amount](/reference/metrics/orders/adjustments/refund-amount) | Value refunded after fulfillment | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Revenue after all adjustments | | [Orders](/reference/metrics/orders/counts/orders) | All orders including cancelled | [See all Adjustment metrics →](/reference/metrics/orders/adjustments) # Cancelled Orders: Count of Orders Cancelled Before Fulfillment Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/cancelled-orders Track the number of cancelled orders in your Shopify store. Monitor checkout friction, payment failures, and inventory issues with order cancellation counts. The total number of orders cancelled before fulfillment in your Shopify store. ## Formula **Cancelled Orders** = **COUNT** ( Orders ) **WHERE** status = cancelled ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [**Orders**](/reference/metrics/orders/counts/orders) | Total number of orders placed | | [**status = cancelled**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders marked as cancelled before fulfillment | | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Count | *** ## Example Your store had **69 cancelled orders** during Q1 across 4,200 total orders: | Month | Cancelled | Cancellation Rate | | -------- | --------- | ------------------------------ | | January | 18 | 1.3% | | February | 27 | 1.9% (payment processor issue) | | March | 24 | 1.7% | *** ## How It Works Cancelled Orders counts all orders marked as cancelled in Shopify before fulfillment. Unlike refunds, cancellations represent orders that never shipped. Spikes often correlate with payment failures, inventory stockouts, or customer-initiated order changes. *** ## When to Use | Scenario | Action | | ------------------------- | ------------------------------------------------- | | Monitor checkout health | Track cancellations as percentage of total orders | | Diagnose payment issues | Compare against payment failure rates | | Detect inventory problems | Correlate spikes with stockout events | | Segment by customer type | Compare new vs returning customer cancellations | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------- | -------------------------------------- | | [Cancelled Amount](/reference/metrics/orders/adjustments/cancelled-amount) | Dollar value of these cancelled orders | | [Refund Count](/reference/metrics/orders/adjustments/refund-count) | Orders refunded after fulfillment | | [Refund Amount](/reference/metrics/orders/adjustments/refund-amount) | Dollar value of refunds | | [Orders](/reference/metrics/orders/counts/orders) | All orders including cancelled | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Revenue after all adjustments | [See all Adjustment metrics →](/reference/metrics/orders/adjustments) # Discount Amount: Total Discounts Applied to Orders Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/discount-amount Track total discount value applied across all orders from your Shopify store. Monitor promotional spend, measure discount impact on margins, and optimize strategy. The total dollar value of all discounts applied across orders in the selected period. ## Formula **Discount Amount** = **SUM** ( Discount Value ) ### Formula Components | Metric | Definition | | ------------------ | ---------------------------------------------------- | | **Discount Value** | The dollar amount of discounts applied to each order | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store applied **\$18,400 in discounts** during a spring promotion: | Week | Discount Amount | Discounted Orders | | ------ | --------------- | ----------------- | | Week 1 | \$3,200 | 412 | | Week 2 | \$5,800 | 687 | | Week 3 | \$6,100 | 723 | | Week 4 | \$3,300 | 398 | *** ## How It Works Discount Amount sums the dollar value of all discounts applied to orders—including percentage-off codes, fixed-amount coupons, and automatic discounts. High discount totals reduce gross margin and can signal over-reliance on promotions to drive sales. *** ## When to Use | Scenario | Action | | ---------------------- | ------------------------------------------------------------- | | Track promotional cost | Monitor total discount dollars during campaigns | | Protect gross margin | Set discount budgets to maintain profitability | | Compare campaigns | Measure which promotions drive the highest discount liability | | Calculate net revenue | Subtract from gross revenue alongside refunds | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------ | ---------------------------------------- | | [Discount %](/reference/metrics/orders/adjustments/discount-percent) | Discounts as percentage of gross revenue | | [Discount Per Order](/reference/metrics/orders/adjustments/discount-per-order) | This metric ÷ Order Count | | [Refund Amount](/reference/metrics/orders/adjustments/refund-amount) | Another deduction from gross revenue | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Gross Revenue − Discounts − Refunds | | [Gross Revenue](/reference/metrics/orders/revenue/gross-revenue) | Revenue before discounts and refunds | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Discount Count: Orders with Discounts Applied Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/discount-count Track how many orders had discounts applied. Monitor promotion usage frequency and compare to total orders to gauge discount dependency. Discount Count measures the number of orders that had at least one discount code or promotion applied. ## Formula **Discount Count** = **COUNT** ( Orders ) **WHERE** discount\_applied = true ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | [**Orders**](/reference/metrics/orders/counts/orders) | Total number of orders placed | | [**discount\_applied = true**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders with at least one discount code or promotion applied | | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Count | *** ## Example Your store processed **1,247 orders** in January. **843 orders** had discount codes applied. | Period | Total Orders | Discounted Orders | Discount Usage | | -------- | ------------ | ----------------- | -------------- | | January | 1,247 | 843 | 67.6% | | February | 1,089 | 412 | 37.8% | | March | 1,356 | 678 | 50.0% | *** ## How It Works Discount Count increments by one for each order where Shopify reports a discount was applied at checkout. An order with multiple discount codes still counts as one discounted order. *** ## When to Use | Scenario | Action | | ----------------------------------- | ---------------------------------------------------------- | | Evaluating promotion effectiveness | Compare discounted orders to total orders during campaigns | | Measuring discount dependency | Track if customers only buy when discounts are available | | Analyzing new vs returning behavior | See if one segment uses discounts more frequently | | Planning inventory for sales events | Estimate volume based on historical discount usage | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------ | ---------------------------------------- | | [Discount Amount](/reference/metrics/orders/adjustments/discount-amount) | Total dollar value of discounts applied | | [Discount %](/reference/metrics/orders/adjustments/discount-percent) | Discounts as share of gross revenue | | [Discount Per Order](/reference/metrics/orders/adjustments/discount-per-order) | Average discount per order | | [Orders](/reference/metrics/orders/counts/orders) | All orders regardless of discount status | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Discount Gross Rate: Discounts as % of Gross Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/discount-gross-rate Measure total discount dollars as a percentage of gross revenue. Track promotional impact on margins across all orders with Shopify order data. Total discount amount as a percentage of gross revenue—measures how much of your potential revenue is offset by promotions. ## Formula **Discount Gross Rate** = ( [**Discount Amount**](/reference/metrics/orders/adjustments/discount-amount) ÷ [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------- | ------------------------------------------- | | [**Discount Amount**](/reference/metrics/orders/adjustments/discount-amount) | Total dollar value of all discounts applied | | [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) | Total revenue before discounts and refunds | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store generated **\$237,000** in gross revenue with **\$18,960** in total discounts during a promotional period: | Metric | Value | | ----------------------- | --------- | | Gross Revenue | \$237,000 | | Discount Amount | \$18,960 | | **Discount Gross Rate** | **8.0%** | *** ## How It Works This metric divides total discount dollars by gross revenue, then multiplies by 100. It shows what portion of your potential revenue is being given away through promotions. Higher rates indicate aggressive discounting that erodes gross margins. *** ## When to Use | Scenario | Action | | ------------------------- | ------------------------------------------------------------------- | | Monitoring margin erosion | Track discount rate trends to prevent margin creep | | Evaluating promotions | Compare pre and post-campaign to measure discount escalation | | Benchmarking periods | Identify seasonal patterns in promotional intensity | | Customer segment analysis | Compare against NC and RC Discount Gross Rates for segment insights | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | ------------------------------------ | | [Discount Amount](/reference/metrics/orders/adjustments/discount-amount) | Dollar value used in numerator | | [Gross Revenue](/reference/metrics/orders/revenue/gross-revenue) | Baseline revenue in denominator | | [NC Discount Gross Rate](/reference/metrics/orders/adjustments/new-customer-discount-gross-rate) | New customer segment breakdown | | [RC Discount Gross Rate](/reference/metrics/orders/adjustments/returning-customer-discount-gross-rate) | Returning customer segment breakdown | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Discount Per Order: Average Discount Amount Per Transaction Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/discount-per-order Track the average discount amount applied per order from your Shopify store. Measure promotional impact on margins and optimize discount strategy. The average discount dollar value applied per order. ## Formula **Discount Per Order** = [**Discount Amount**](/reference/metrics/orders/adjustments/discount-amount) ÷ [**Orders**](/reference/metrics/orders/counts/orders) ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------- | ------------------------------------------- | | [**Discount Amount**](/reference/metrics/orders/adjustments/discount-amount) | Total dollar value of all discounts applied | | [**Orders**](/reference/metrics/orders/counts/orders) | Total number of completed orders | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store processed **3,200 orders** in March with **\$12,800** in total discounts: | Metric | Value | | ---------------------- | ---------- | | Discount Amount | \$12,800 | | Order Count | 3,200 | | **Discount Per Order** | **\$4.00** | *** ## How It Works Discount Per Order divides total discount dollars by all orders—not just discounted orders. This shows the average revenue given away per transaction, helping you understand the true cost of promotions across your entire customer base. *** ## When to Use | Scenario | Action | | --------------------- | ------------------------------------------------------------------- | | Evaluating promotions | Compare pre and post-campaign to measure discount escalation | | Protecting margins | Set thresholds to prevent discount creep from eroding profitability | | Segmenting customers | Compare new vs returning customer discount per order | | Benchmarking channels | Identify traffic sources that over-rely on discounts | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------ | ---------------------------------------------------------- | | [Discount Amount](/reference/metrics/orders/adjustments/discount-amount) | Numerator: total discount dollars | | [Orders](/reference/metrics/orders/counts/orders) | Denominator: transaction count | | [Discount %](/reference/metrics/orders/adjustments/discount-percent) | Discounts as percentage of gross revenue | | [Net AOV](/reference/metrics/orders/aov/net-aov) | Order value after discounts—compare to gauge margin impact | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Discount %: Discounts as Share of Gross Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/discount-percent Track total discounts as a percentage of gross revenue from your Shopify store. Monitor promotional intensity and protect gross margins. Discounts as a percentage of gross revenue—measures how much of your potential revenue is given away through promotions. ## Formula **Discount %** = ( [**Discount Amount**](/reference/metrics/orders/adjustments/discount-amount) ÷ [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------- | -------------------------------------------- | | [**Discount Amount**](/reference/metrics/orders/adjustments/discount-amount) | Total dollar value of all discounts applied | | [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) | Product revenue before discounts and refunds | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store earned **\$80,000** in gross revenue during a holiday promotion with **\$12,000** in total discounts: | Metric | Value | | --------------- | -------- | | Gross Revenue | \$80,000 | | Discount Amount | \$12,000 | | **Discount %** | **15%** | *** ## How It Works Discount % divides total discount dollars by gross revenue (before discounts and refunds). A high percentage indicates heavy promotional reliance, which erodes margins and can train customers to wait for sales. *** ## When to Use | Scenario | Action | | --------------------- | --------------------------------------------------------------- | | Evaluating promotions | Compare pre and post-campaign to measure discount escalation | | Protecting margins | Set thresholds to prevent discount creep (e.g., stay under 10%) | | Segmenting customers | Compare new vs returning customer discount % | | Benchmarking channels | Identify traffic sources over-reliant on discounts | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------ | ------------------------------------- | | [Discount Amount](/reference/metrics/orders/adjustments/discount-amount) | Numerator: total discount dollars | | [Gross Revenue](/reference/metrics/orders/revenue/gross-revenue) | Denominator: baseline product revenue | | [Discount Per Order](/reference/metrics/orders/adjustments/discount-per-order) | Average discount per transaction | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Revenue after discounts and refunds | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Adjustments: Track Refunds, Discounts, Shipping, and Tax Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/index Track order adjustment metrics in Upstack. Includes Refunds, Discounts, Shipping, Tax, and Cancelled Orders with formulas and examples. Adjustment metrics track order modifications that impact revenue—refunds, discounts, shipping collected, and tax. Use these to understand the gap between gross and net revenue. **Data Source:** [Shopify](/sources/shopify)\ **Metrics:** 51 ## Metrics in This Group ### Refunds | Metric | Description | When to Use | | -------------------------------------------------------------------------- | ----------------------------- | ------------------------ | | [Refund Amount](/reference/metrics/orders/adjustments/refund-amount) | Total refund value | Track refund liability | | [Refund Count](/reference/metrics/orders/adjustments/refund-count) | Number of refunded orders | Count problematic orders | | [Refund %](/reference/metrics/orders/adjustments/refund-percent) | Percentage of orders refunded | Monitor return rate | | [Refund Per Order](/reference/metrics/orders/adjustments/refund-per-order) | Average refund per order | Benchmark refund impact | ### Discounts | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------ | -------------------------------------------------- | --------------------------------- | | [Discount Amount](/reference/metrics/orders/adjustments/discount-amount) | Total discount value | Track promotional cost | | [Discount %](/reference/metrics/orders/adjustments/discount-percent) | Percentage of orders with discounts | Monitor discount usage | | [Discount Per Order](/reference/metrics/orders/adjustments/discount-per-order) | Average discount per order | Optimize promotion strategy | | [NC Discount %](/reference/metrics/orders/adjustments/new-customer-discount-percent) | New customer discounts as % of gross revenue | Track acquisition discount impact | | [RC Discount %](/reference/metrics/orders/adjustments/returning-customer-discount-percent) | Returning customer discounts as % of gross revenue | Track retention discount impact | ### Shipping & Tax | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------ | ---------------------------------------- | ---------------------------- | | [Shipping Revenue](/reference/metrics/orders/adjustments/shipping-revenue) | Shipping collected from customers | Track shipping contribution | | [Shipping %](/reference/metrics/orders/adjustments/shipping-percent) | Shipping as % of order value | Monitor shipping strategy | | [Tax](/reference/metrics/orders/adjustments/tax) | Tax collected | Tax reporting | | [Tax %](/reference/metrics/orders/adjustments/tax-percent) | Tax as % of order value | Understand tax impact | | [Tax Per Order](/reference/metrics/orders/adjustments/tax-per-order) | Average tax per order | Benchmark tax impact | | [NC Tax Per Order](/reference/metrics/orders/adjustments/new-customer-tax-per-order) | Average tax per new customer order | Track acquisition tax burden | | [RC Tax Per Order](/reference/metrics/orders/adjustments/returning-customer-tax-per-order) | Average tax per returning customer order | Track retention tax burden | ### Cancelled Orders | Metric | Description | When to Use | | -------------------------------------------------------------------------- | -------------------------- | ------------------------- | | [Cancelled Orders](/reference/metrics/orders/adjustments/cancelled-orders) | Number of cancelled orders | Track cancellation volume | | [Cancelled Amount](/reference/metrics/orders/adjustments/cancelled-amount) | Value of cancelled orders | Measure lost revenue | ## How These Metrics Relate Adjustments bridge the gap between gross and net revenue: * **Net Revenue** = Gross Revenue - Discounts - Refunds * **Total Revenue** = Net Revenue + Shipping + Tax Each adjustment type is available segmented by New Customer and Returning Customer. ## Choosing the Right Metric * **Refund analysis**: Use Refund % to benchmark return rates by product or campaign * **Discount strategy**: Use Discount % to understand promotional reliance * **Shipping optimization**: Compare Shipping Revenue vs Shipping Cost to find margin * **Tax compliance**: Use Tax metrics for reporting and reconciliation # New Customer Cancelled Amount: Lost First-Order Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/new-customer-cancelled-amount Track the dollar value of cancelled first-time customer orders. Identify checkout friction and reduce lost revenue from new customer cancellations. The total dollar value of cancelled orders from first-time customers. ## Formula **New Customer Cancelled Amount** = **SUM** ( Cancelled Order Value ) **WHERE** customer\_type = new ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | **Cancelled Order Value** | The total value of each cancelled order | | [**customer\_type = new**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from first-time customers with no prior purchases | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store had **\$4,850** in cancelled new customer orders this month: | Week | Cancelled Amount | Orders | Avg Value | | ------ | ---------------- | ------ | --------- | | Week 1 | \$1,200 | 8 | \$150 | | Week 2 | \$890 | 6 | \$148 | | Week 3 | \$1,560 | 11 | \$142 | | Week 4 | \$1,200 | 9 | \$133 | *** ## How It Works This metric sums the order totals for all cancelled orders where the customer had no prior purchases. Cancellations are tracked when orders are voided before fulfillment. High values may signal checkout issues, payment failures, or inventory problems affecting first-time buyers. *** ## When to Use | Scenario | Action | | ------------------------- | ------------------------------------------------------------ | | Checkout optimization | High cancellations suggest payment or UX friction | | Campaign quality audit | Compare against acquisition channels to find problem sources | | Inventory management | Spikes may indicate stockout-driven cancellations | | New vs returning analysis | Compare with returning customer cancellations for patterns | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | [Cancelled Amount](/reference/metrics/orders/adjustments/cancelled-amount) | Total cancelled amount (all customers) | | [Cancelled Orders](/reference/metrics/orders/adjustments/cancelled-orders) | Count of all cancellations | | [New Customer Cancelled Orders](/reference/metrics/orders/adjustments/new-customer-cancelled-orders) | Count of new customer cancellations | | [Returning Customer Cancelled Amount](/reference/metrics/orders/adjustments/returning-customer-cancelled-amount) | Cancelled amount from repeat buyers | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # New Customer Cancelled Orders: Cancellations by First-Time Buyers Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/new-customer-cancelled-orders Track cancelled orders from new customers. Monitor acquisition quality, identify checkout friction, and reduce lost revenue from first-time buyer cancellations. The number of orders from first-time customers that were cancelled before fulfillment. ## Formula **New Customer Cancelled Orders** = **COUNT** ( Cancelled Orders ) **WHERE** customer\_type = new ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | [**Cancelled Orders**](/reference/metrics/orders/adjustments/cancelled-orders) | Orders marked as cancelled before fulfillment | | [**customer\_type = new**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from first-time customers with no prior purchases | | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Count | *** ## Example Your store had **47 New Customer Cancelled Orders** this month out of 1,850 new customer orders: | Source | NC Cancellations | NC Orders | Cancel % | | ---------- | ---------------- | --------- | -------- | | Meta Ads | 24 | 950 | 2.5% | | Google Ads | 14 | 580 | 2.4% | | Organic | 9 | 320 | 2.8% | | **Total** | **47** | **1,850** | **2.5%** | *** ## How It Works This metric counts orders placed by first-time customers that were cancelled before fulfillment in Shopify. A customer is classified as "new" based on having no prior orders. Cancellations typically occur due to payment failures, customer requests, or fraud holds. *** ## When to Use | Scenario | Action | | ------------------------------ | ---------------------------------------------------- | | Evaluating acquisition quality | Compare cancellation counts by traffic source | | Investigating checkout issues | Spikes may indicate payment or fraud filter problems | | Measuring lost opportunity | Pair with NC Cancelled Amount for dollar impact | | Comparing customer types | Benchmark against returning customer cancellations | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | ------------------------------------------ | | [New Customer Cancelled Amount](/reference/metrics/orders/adjustments/new-customer-cancelled-amount) | Dollar value of these cancellations | | [Cancelled Orders](/reference/metrics/orders/adjustments/cancelled-orders) | Total cancellations (all customers) | | [RC Cancelled Orders](/reference/metrics/orders/adjustments/returning-customer-cancelled-orders) | Same metric for repeat buyers | | [New Customers](/reference/metrics/orders/customers/new-customers) | Total new customers (denominator for rate) | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # New Customer Discount Gross Rate: Discounts as % of Gross Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/new-customer-discount-gross-rate Measure new customer discount dollars as a percentage of gross revenue. Track acquisition discount impact on first-purchase margins with Shopify order data. New customer discount amount as a percentage of new customer gross revenue. ## Formula **NC Discount Gross Rate** = ( [**New Customer Discounts**](/reference/metrics/orders/adjustments/new-customer-discounts) ÷ [**New Customer Gross Revenue**](/reference/metrics/orders/revenue/new-customer-gross-revenue) ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | [**New Customer Discounts**](/reference/metrics/orders/adjustments/new-customer-discounts) | Total dollar value of discounts applied to first-time buyer orders | | [**New Customer Gross Revenue**](/reference/metrics/orders/revenue/new-customer-gross-revenue) | Total revenue from new customers before adjustments | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your new customers generated **\$92,000** in gross revenue with **\$8,280** in discounts: | Metric | Value | | -------------------------- | -------- | | New Customer Gross Revenue | \$92,000 | | New Customer Discounts | \$8,280 | | **NC Discount Gross Rate** | **9.0%** | *** ## How It Works This metric divides new customer discount dollars by new customer gross revenue, then multiplies by 100. It measures how much of first-time buyer revenue is offset by promotional discounts. Higher rates indicate aggressive acquisition discounting that may reduce margins on initial purchases. *** ## When to Use | Scenario | Action | | ---------------------------- | --------------------------------------------------------------------------- | | Evaluating acquisition costs | Combine with CAC to understand true cost of new customer orders | | Margin analysis | Monitor discount erosion on first-purchase profitability | | New vs. returning comparison | Benchmark against RC Discount Gross Rate for retention efficiency | | Promotion optimization | Identify if acquisition discounts can be reduced without hurting conversion | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | | [NC Discount %](/reference/metrics/orders/adjustments/new-customer-discount-percent) | Related percentage metric for new customers | | [NC Discount Per Order](/reference/metrics/orders/adjustments/new-customer-discount-per-order) | Average discount per new customer order | | [RC Discount Gross Rate](/reference/metrics/orders/adjustments/returning-customer-discount-gross-rate) | Compare acquisition vs. retention discount rates | | [Discount Amount](/reference/metrics/orders/adjustments/discount-amount) | Total discounts across all customers | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # New Customer Discount Order Rate: Acquisition Discount Dependency Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/new-customer-discount-order-rate Track what percentage of new customer orders use discount codes. Measure how dependent your customer acquisition is on promotions and optimize strategy. The share of new customer orders that used a discount code or promotion. ## Formula **NC Discount Order Rate** = ( **New Customer Discounted Orders** ÷ [**New Customers**](/reference/metrics/orders/customers/new-customers) ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------- | ------------------------------------------------------------------- | | **New Customer Discounted Orders** | Count of first-time buyer orders with at least one discount applied | | [**New Customers**](/reference/metrics/orders/customers/new-customers) | Total number of first-time buyer orders | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store had **847 new customer orders** in January, with **678 using discount codes**: | Period | NC Discounted Orders | NC Orders | Rate | | -------- | -------------------- | --------- | ----- | | January | 678 | 847 | 80.0% | | February | 412 | 623 | 66.1% | *** ## How It Works Counts first-time customer orders with discounts and divides by total new customer orders. High values indicate acquisition is discount-dependent; declining rates show customers converting without incentives. *** ## When to Use | Scenario | Action | | -------------------------------- | ---------------------------------------------------------- | | Evaluating acquisition costs | High rates mean discounts drive most new customers | | Testing discount removal | Monitor if rate drops without hurting conversion | | Comparing to returning customers | Identify if new vs repeat buyers need different incentives | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | [Returning Customer Discount Order Rate](/reference/metrics/orders/adjustments/returning-customer-discount-order-rate) | Same metric for repeat customers | | [Discount Count](/reference/metrics/orders/adjustments/discount-count) | Total orders with discounts (all customers) | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # New Customer Discount Per Order: Average First-Purchase Discount Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/new-customer-discount-per-order Track the average discount applied to new customer orders. Measure acquisition discount intensity and optimize first-purchase promotions. The average discount dollar value applied per new customer order. ## Formula **NC Discount Per Order** = [**New Customer Discounts**](/reference/metrics/orders/adjustments/new-customer-discounts) ÷ [**New Customers**](/reference/metrics/orders/customers/new-customers) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | | [**New Customer Discounts**](/reference/metrics/orders/adjustments/new-customer-discounts) | Total dollar value of discounts applied to new customer orders | | [**New Customers**](/reference/metrics/orders/customers/new-customers) | Number of orders placed by first-time buyers | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your store processed **842 new customer orders** in March with **\$12,630** in discounts: | Period | Discounts | NC Orders | Discount/Order | | -------- | --------- | --------- | -------------- | | March | \$12,630 | 842 | \$15.00 | | February | \$9,180 | 612 | \$15.00 | | January | \$7,840 | 560 | \$14.00 | *** ## How It Works This metric divides total discounts applied to new customer orders by the number of new customer orders. It reveals how much you're investing in discounts to acquire each new buyer—critical for understanding customer acquisition cost beyond ad spend. *** ## When to Use | Scenario | Action | | -------------------------------- | -------------------------------------------------------- | | Evaluating acquisition offers | Ensure welcome discounts drive profitable first orders | | Comparing to returning customers | Identify if new buyers require deeper discounts | | Optimizing promo strategy | Test whether smaller discounts maintain conversion rates | | CAC analysis | Add to ad spend for true acquisition cost | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | [New Customer Discounts](/reference/metrics/orders/adjustments/new-customer-discounts) | Numerator (total discounts for NC orders) | | [NC Discount %](/reference/metrics/orders/adjustments/new-customer-discount-percent) | Discount as percentage of gross revenue | | [Returning Customer Discount Per Order](/reference/metrics/orders/adjustments/returning-customer-discount-per-order) | Compare acquisition vs retention discounting | | [Discount Per Order](/reference/metrics/orders/adjustments/discount-per-order) | Overall average across all customer types | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # New Customer Discount %: Discount Share of Gross Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/new-customer-discount-percent Measure new customer discounts as a percentage of gross revenue. Track acquisition discount impact on first-purchase margins with Shopify order data. New customer discounts as a percentage of new customer gross revenue. ## Formula **NC Discount %** = ( [**New Customer Discounts**](/reference/metrics/orders/adjustments/new-customer-discounts) ÷ [**New Customer Gross Revenue**](/reference/metrics/orders/revenue/new-customer-gross-revenue) ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | [**New Customer Discounts**](/reference/metrics/orders/adjustments/new-customer-discounts) | Total dollar value of discounts applied to new customer orders | | [**New Customer Gross Revenue**](/reference/metrics/orders/revenue/new-customer-gross-revenue) | Total revenue from new customers before adjustments | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your new customers generated **\$85,000** in gross revenue with **\$10,200** in discounts: | Metric | Value | | --------------------------- | --------- | | New Customer Gross Revenue | \$85,000 | | New Customer Discounts | \$10,200 | | **New Customer Discount %** | **12.0%** | *** ## How It Works This metric divides new customer discounts by new customer gross revenue, then multiplies by 100. Higher percentages indicate heavier discount reliance for acquisition, which may signal necessary promotional investment or aggressive discounting that erodes first-purchase margins. *** ## When to Use | Scenario | Action | | ---------------------------- | ------------------------------------------------------------ | | Evaluating acquisition costs | Compare discount rates to CAC for true acquisition cost | | Promotion effectiveness | Monitor if first-purchase discounts drive sustainable growth | | New vs. returning comparison | Benchmark against returning customer discount rates | | Margin optimization | Identify opportunities to reduce acquisition discounts | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [New Customer Discounts](/reference/metrics/orders/adjustments/new-customer-discounts) | The numerator — total discount dollars | | [NC Discount Per Order](/reference/metrics/orders/adjustments/new-customer-discount-per-order) | Average discount per new customer order | | [RC Discount %](/reference/metrics/orders/adjustments/returning-customer-discount-percent) | Compare acquisition vs. retention discount rates | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # New Customer Discounts: First-Order Discount Total Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/new-customer-discounts Track total discount dollars applied to new customer orders. Measure acquisition discount strategy effectiveness and first-purchase incentive costs with Shopify data. The total dollar amount of discounts applied to new customer orders. ## Formula **New Customer Discounts** = **SUM** ( [**Discount Amount**](/reference/metrics/orders/adjustments/discount-amount) ) **WHERE** customer\_type = new ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | [**Discount Amount**](/reference/metrics/orders/adjustments/discount-amount) | The dollar value of discounts applied to orders | | [**customer\_type = new**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from first-time customers with no prior purchases | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store applied **\$8,240** in discounts to new customer orders in Q1: | Month | NC Discounts | NC Orders | Discount/Order | | -------- | ------------ | --------- | -------------- | | January | \$2,450 | 318 | \$7.70 | | February | \$2,780 | 356 | \$7.81 | | March | \$3,010 | 402 | \$7.49 | Stable discount per order while total discounts grow indicates scaling acquisition without eroding margins. *** ## How It Works This metric sums all discount amounts from orders placed by new customers. A customer is classified as "new" when they have no prior completed orders in Shopify. Discounts include coupon codes, automatic discounts, and manual adjustments applied at checkout. *** ## When to Use | Scenario | Action | | ------------------------------------ | ------------------------------------------------------------------ | | Measuring acquisition incentive cost | Track how much revenue is given away to convert first-time buyers | | Comparing segments | Benchmark against returning customer discounts to balance strategy | | CAC analysis | Include in customer acquisition cost alongside ad spend | | Margin optimization | Identify if acquisition discounts are too aggressive | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | [New Customer Discount %](/reference/metrics/orders/adjustments/new-customer-discount-percent) | Discounts as percentage of gross revenue | | [Returning Customer Discounts](/reference/metrics/orders/adjustments/returning-customer-discounts) | Compare retention vs. acquisition discount spending | | [Discount Amount](/reference/metrics/orders/adjustments/discount-amount) | Total discounts across all customer types | | [New Customer Refunds](/reference/metrics/orders/adjustments/new-customer-refunds) | Combined with discounts for total adjustments | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # New Customer Refund Count: Orders Refunded by First-Time Buyers Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/new-customer-refund-count Count orders from new customers that resulted in refunds. Track acquisition quality and identify product-market fit issues with first-time buyers. The number of orders from first-time customers that have been refunded. ## Formula **New Customer Refund Count** = **COUNT** ( Refunded Orders ) **WHERE** customer\_type = new ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | **Refunded Orders** | Orders that have had a full or partial refund issued | | [**customer\_type = new**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from first-time customers with no prior purchases | | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Count | *** ## Example Your store had **164 New Customer Refund Count** this quarter: | Channel | NC Refunds | NC Orders | Refund % | | ---------- | ---------- | --------- | -------- | | Meta Ads | 82 | 950 | 8.6% | | Google Ads | 54 | 680 | 7.9% | | Organic | 28 | 370 | 7.6% | | **Total** | **164** | **2,000** | **8.2%** | *** ## How It Works This metric counts orders placed by first-time customers that Shopify marks as refunded. A customer is classified as "new" based on having no prior orders in your Shopify store. The count includes full and partial refunds. *** ## When to Use | Scenario | Action | | ------------------------------- | ------------------------------------------------ | | Evaluating acquisition channels | Compare refund counts by traffic source | | Monitoring product launches | Track if new products drive higher refund volume | | Calculating refund rate | Use as numerator in New Customer Refund % | | Identifying quality issues | Spikes indicate product or expectation problems | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | [New Customer Refund %](/reference/metrics/orders/adjustments/new-customer-refund-percent) | This count divided by NC orders | | [New Customer Refunds](/reference/metrics/orders/adjustments/new-customer-refunds) | Dollar amount (this metric is the count) | | [Returning Customer Refund Count](/reference/metrics/orders/adjustments/returning-customer-refund-count) | Same metric for repeat buyers | | [Refund Count](/reference/metrics/orders/adjustments/refund-count) | Total refund count (all customers) | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # New Customer Refund Per Order: Average First-Buyer Refund Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/new-customer-refund-per-order Track average refund amount per new customer order. Measure first-buyer return costs and identify product-market fit or fulfillment issues. The average refund amount issued per new customer order. ## Formula **NC Refund Per Order** = [**New Customer Refunds**](/reference/metrics/orders/adjustments/new-customer-refunds) ÷ [**New Customers**](/reference/metrics/orders/customers/new-customers) ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------- | ------------------------------------------- | | [**New Customer Refunds**](/reference/metrics/orders/adjustments/new-customer-refunds) | Total refund dollars from first-time buyers | | [**New Customers**](/reference/metrics/orders/customers/new-customers) | Count of orders from first-time buyers | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store processed **847 new customer orders** in February with **\$2,965** in refunds: | Metric | Value | | ----------------------- | ---------- | | New Customer Refunds | \$2,965 | | New Customer Orders | 847 | | **NC Refund Per Order** | **\$3.50** | Compare this to your Returning Customer Refund Per Order of \$2.18—new customers cost 60% more in refunds per order. *** ## How It Works This metric divides total new customer refunds by total new customer orders—not just refunded orders. This gives you the average refund liability per first-time buyer transaction, helping you understand acquisition quality and the true cost of acquiring new customers after accounting for returns. *** ## When to Use | Scenario | Action | | ------------------------------- | ------------------------------------------------------------------- | | Evaluating acquisition channels | Identify campaigns driving higher new customer refund rates | | Comparing NC vs RC behavior | New customers typically have higher refund rates than repeat buyers | | Assessing product-market fit | High values may indicate targeting issues or unmet expectations | | Budgeting for returns | Factor into CAC and payback period calculations | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | [New Customer Refunds](/reference/metrics/orders/adjustments/new-customer-refunds) | Numerator: total NC refund dollars | | [New Customers](/reference/metrics/orders/customers/new-customers) | Denominator: NC transaction count | | [New Customer Refund %](/reference/metrics/orders/adjustments/new-customer-refund-percent) | Percentage of NC orders refunded | | [Returning Customer Refund Per Order](/reference/metrics/orders/adjustments/returning-customer-refund-per-order) | Compare new vs returning customer refund behavior | | [Refund Per Order](/reference/metrics/orders/adjustments/refund-per-order) | Overall refund per order across all customers | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # New Customer Refund %: Track First-Time Buyer Returns Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/new-customer-refund-percent Measure the percentage of new customer orders that result in refunds. Identify product-market fit issues with first-time buyers and optimize acquisition quality. The share of new customer orders that resulted in a refund. ## Formula **NC Refund %** = ( [**New Customer Refund Count**](/reference/metrics/orders/adjustments/new-customer-refund-count) ÷ [**New Customers**](/reference/metrics/orders/customers/new-customers) ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------ | ------------------------------------------------- | | [**New Customer Refund Count**](/reference/metrics/orders/adjustments/new-customer-refund-count) | Number of new customer orders with refunds issued | | [**New Customers**](/reference/metrics/orders/customers/new-customers) | Total orders placed by first-time buyers | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store had **8.2% New Customer Refund %** this quarter: | Metric | Value | Context | | --------------- | ----- | ------------------ | | NC Refund Count | 164 | Orders refunded | | NC Order Count | 2,000 | Total NC orders | | NC Refund % | 8.2% | Above 5% benchmark | *** ## How It Works This metric divides the number of new customer refunds by total new customer orders, expressed as a percentage. A rising refund rate among first-time buyers often signals product-expectation misalignment, misleading ads, or quality issues that disproportionately affect acquisition. *** ## When to Use | Scenario | Action | | ------------------------------- | ------------------------------------------------------- | | Launching new products | Monitor if first-time buyers return items more often | | Evaluating ad creative | High NC refund % may indicate misleading messaging | | Comparing customer segments | Benchmark against Returning Customer Refund % | | Optimizing acquisition channels | Identify which traffic sources drive low-quality buyers | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | | [New Customer Refunds](/reference/metrics/orders/adjustments/new-customer-refunds) | Dollar amount of refunds (this metric is the rate) | | [New Customer Refund Count](/reference/metrics/orders/adjustments/new-customer-refund-count) | Numerator in this formula | | [Returning Customer Refund %](/reference/metrics/orders/adjustments/returning-customer-refund-percent) | Same metric for repeat buyers | | [New Customer %](/reference/metrics/orders/customers/new-customer-percent) | Share of orders from first-time buyers | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # New Customer Refund + Discount: Combined First-Purchase Adjustments Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/new-customer-refund-plus-discount Track combined refunds and discounts from new customer orders. Understand total revenue given back on first-time buyer transactions. Combined refunds and discounts for new customer orders, reflecting total revenue given back from first-time buyer transactions. ## Formula **NC Refund + Discount** = [**New Customer Refunds**](/reference/metrics/orders/adjustments/new-customer-refunds) + [**New Customer Discounts**](/reference/metrics/orders/adjustments/new-customer-discounts) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------ | ---------------------------------------------------- | | [**New Customer Refunds**](/reference/metrics/orders/adjustments/new-customer-refunds) | Total dollar amount refunded to new customers | | [**New Customer Discounts**](/reference/metrics/orders/adjustments/new-customer-discounts) | Total discount amount applied to new customer orders | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store processed **\$4,250** in combined adjustments for new customers this month: | Component | Amount | Share | | ---------------------- | ------- | ----- | | New Customer Refunds | \$1,850 | 44% | | New Customer Discounts | \$2,400 | 56% | *** ## How It Works This metric sums refund amounts and discount amounts from orders placed by first-time customers. It represents the total revenue reduction specifically tied to new customer acquisition, helping you understand the true cost of converting first-time buyers. *** ## When to Use | Scenario | Action | | ---------------------------- | ------------------------------------------------------------------- | | Evaluating acquisition costs | Factor in adjustments when calculating true CAC | | Comparing customer segments | Assess if new customers have higher adjustment rates than returning | | Promotion impact analysis | Measure discount burden from welcome offers | | Product-market fit signals | High refunds may indicate expectation mismatches for new buyers | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | [New Customer Refunds](/reference/metrics/orders/adjustments/new-customer-refunds) | Refund component of this total | | [New Customer Discounts](/reference/metrics/orders/adjustments/new-customer-discounts) | Discount component of this total | | [Returning Customer Refund + Discount](/reference/metrics/orders/adjustments/returning-customer-refund-plus-discount) | Same metric for repeat buyers | | [Refund Amount](/reference/metrics/orders/adjustments/refund-amount) | Total refunds across all customers | | [Discount Amount](/reference/metrics/orders/adjustments/discount-amount) | Total discounts across all customers | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # New Customer Refunds: First-Time Buyer Refund Total Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/new-customer-refunds Track total refund dollars for new customers. Identify product-market fit issues with first-time buyers and measure acquisition quality. The total dollar amount refunded to new customers (first-time buyers). ## Formula **New Customer Refunds** = **SUM** ( [**Refund Amount**](/reference/metrics/orders/adjustments/refund-amount) ) **WHERE** customer\_type = new ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | [**Refund Amount**](/reference/metrics/orders/adjustments/refund-amount) | The dollar value refunded to customers | | [**customer\_type = new**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from first-time customers with no prior purchases | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store refunded **\$2,847** to new customers in March across 43 refunds: | Week | New Customer Refunds | Refund Count | | ------ | -------------------- | ------------ | | Week 1 | \$542 | 8 | | Week 2 | \$1,203 | 18 | | Week 3 | \$687 | 11 | | Week 4 | \$415 | 6 | A spike in Week 2 might indicate a product issue or misleading ad creative that attracted the wrong customers. *** ## How It Works This metric sums all refund amounts from orders placed by first-time customers. A customer is classified as "new" based on their order history in Shopify—their first completed order marks them as a new customer. High values may indicate product quality issues, unmet expectations from marketing, or sizing/fit problems affecting first impressions. *** ## When to Use | Scenario | Action | | ------------------------------- | --------------------------------------------------------------------- | | Evaluating acquisition quality | High refunds from new customers suggest targeting or messaging issues | | Identifying product problems | Compare to returning customer refunds to isolate new buyer issues | | Analyzing marketing campaigns | Check if specific campaigns drive higher first-purchase refunds | | Measuring onboarding experience | Track alongside customer feedback to improve first-order satisfaction | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [New Customer Refund Count](/reference/metrics/orders/adjustments/new-customer-refund-count) | Number of refunds (this metric sums their values) | | [New Customer Refund %](/reference/metrics/orders/adjustments/new-customer-refund-percent) | Share of new customer orders refunded | | [NC Refund Per Order](/reference/metrics/orders/adjustments/new-customer-refund-per-order) | Average refund amount per new customer order | | [Returning Customer Refunds](/reference/metrics/orders/adjustments/returning-customer-refunds) | Compare new vs. returning customer refund behavior | | [Refund Amount](/reference/metrics/orders/adjustments/refund-amount) | Combined refunds across all customer types | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # New Customer Shipping: Shipping Fees from First-Time Buyers Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/new-customer-shipping Track shipping revenue collected from new customer orders. Understand acquisition shipping economics and free shipping promotion impact. New Customer Shipping measures the total shipping fees collected from orders placed by first-time buyers. ## Formula **New Customer Shipping** = **SUM** ( Shipping Revenue ) **WHERE** customer\_type = new ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | **Shipping Revenue** | Total shipping fees collected from orders | | [**customer\_type = new**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from first-time customers with no prior purchases | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store launched a **free shipping over \$50** promotion for new customers in March. | Period | New Customer Orders | NC Shipping Revenue | NC Shipping/Order | | -------- | ------------------- | ------------------- | ----------------- | | January | 847 | \$6,352 | \$7.50 | | February | 912 | \$6,840 | \$7.50 | | March | 1,156 | \$4,045 | \$3.50 | *** ## How It Works New Customer Shipping sums all shipping fees from orders where the customer is making their first purchase. This metric helps you understand how acquisition-focused shipping promotions affect revenue and whether new customers pay differently for shipping than returning customers. *** ## When to Use | Scenario | Action | | ------------------------------------------ | --------------------------------------------------------------- | | Free shipping promotions for new customers | Measure revenue impact of acquisition shipping offers | | New vs. returning shipping comparison | Compare to Returning Customer Shipping to find patterns | | Acquisition economics | Factor shipping revenue into customer acquisition profitability | | Shipping threshold testing | Track how minimum order thresholds affect new buyer behavior | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------ | ---------------------------------------------- | | [Returning Customer Shipping](/reference/metrics/orders/adjustments/returning-customer-shipping) | Compare new vs. returning shipping patterns | | [NC Shipping %](/reference/metrics/orders/adjustments/new-customer-shipping-percent) | Shipping as percentage of new customer revenue | | [NC Shipping Per Order](/reference/metrics/orders/adjustments/new-customer-shipping-per-order) | Average shipping per new customer order | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # New Customer Shipping Per Order: Average First-Buyer Shipping Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/new-customer-shipping-per-order Track average shipping charged per new customer order. Measure first-buyer shipping economics and optimize acquisition shipping strategies. The average shipping amount charged per new customer order. ## Formula **New Customer Shipping Per Order** = [**New Customer Shipping**](/reference/metrics/orders/adjustments/new-customer-shipping) ÷ [**New Customer Orders**](/reference/metrics/orders/customers/new-customers) ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------- | ---------------------------------------------------- | | [**New Customer Shipping**](/reference/metrics/orders/adjustments/new-customer-shipping) | Total shipping fees collected from first-time buyers | | [**New Customer Orders**](/reference/metrics/orders/customers/new-customers) | Count of orders from first-time buyers | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store tested **free shipping for new customers over \$75** in March: | Period | NC Orders | NC Shipping | NC Shipping/Order | | ------------- | --------- | ----------- | ----------------- | | January | 847 | \$6,352 | \$7.50 | | February | 912 | \$6,840 | \$7.50 | | March (promo) | 1,156 | \$4,045 | \$3.50 | The threshold promotion cut shipping per order by 53%—useful for measuring how acquisition offers affect revenue mix. *** ## How It Works This metric divides total shipping revenue from new customers by total new customer orders. It shows the average shipping contribution per first-time buyer transaction, helping you understand how shipping policies affect acquisition economics differently than retention. *** ## When to Use | Scenario | Action | | ------------------------------------- | -------------------------------------------------------------------- | | Evaluating free shipping thresholds | Compare shipping per order before and after threshold changes | | New vs. returning customer comparison | Benchmark against RC Shipping Per Order to find behavior differences | | Acquisition profitability | Include shipping revenue in CAC payback calculations | | Shipping promotion testing | Measure revenue impact of new customer shipping offers | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | [New Customer Shipping](/reference/metrics/orders/adjustments/new-customer-shipping) | Numerator: total NC shipping revenue | | [New Customers](/reference/metrics/orders/customers/new-customers) | Denominator: NC transaction count | | [NC Shipping %](/reference/metrics/orders/adjustments/new-customer-shipping-percent) | Shipping as percentage of new customer revenue | | [RC Shipping Per Order](/reference/metrics/orders/adjustments/returning-customer-shipping-per-order) | Compare new vs. returning shipping patterns | | [Shipping Revenue](/reference/metrics/orders/adjustments/shipping-revenue) | Total shipping from all customers | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # New Customer Shipping %: Shipping Share of New Buyer Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/new-customer-shipping-percent Track shipping revenue as a percentage of new customer total revenue. Monitor how acquisition-focused free shipping promotions affect first-time buyer margins. New Customer Shipping % measures shipping fees as a share of total revenue from first-time buyers. ## Formula **New Customer Shipping %** = ( [**New Customer Shipping**](/reference/metrics/orders/adjustments/new-customer-shipping) ÷ [**New Customer Total Revenue**](/reference/metrics/orders/revenue/new-customer-total-revenue) ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | [**New Customer Shipping**](/reference/metrics/orders/adjustments/new-customer-shipping) | Total shipping fees collected from new customer orders | | [**New Customer Total Revenue**](/reference/metrics/orders/revenue/new-customer-total-revenue) | Total revenue from new customers including shipping and taxes | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store launched a **free shipping over \$75** promotion targeting new customers in March. | Period | NC Shipping | NC Total Revenue | NC Shipping % | | -------- | ----------- | ---------------- | ------------- | | January | \$6,350 | \$84,670 | 7.5% | | February | \$5,890 | \$89,230 | 6.6% | | March | \$2,450 | \$98,000 | 2.5% | *** ## How It Works New Customer Shipping % divides shipping revenue from new customers by their total revenue and multiplies by 100. A declining percentage often signals successful free shipping promotions or higher average order values qualifying for free shipping thresholds among first-time buyers. *** ## When to Use | Scenario | Action | | ------------------------------- | ----------------------------------------------------------------------- | | Acquisition shipping promotions | Track how free shipping offers for new customers affect margins | | Comparing customer segments | Compare to Returning Customer Shipping % to find behavioral differences | | Threshold optimization | Evaluate if free shipping minimums drive higher order values | | Profitability analysis | Factor shipping economics into new customer acquisition costs | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------ | ----------------------------------------------- | | [New Customer Shipping](/reference/metrics/orders/adjustments/new-customer-shipping) | Numerator — shipping revenue from new customers | | [New Customer Total Revenue](/reference/metrics/orders/revenue/new-customer-total-revenue) | Denominator — total revenue from new customers | | [Shipping %](/reference/metrics/orders/adjustments/shipping-percent) | Same calculation for all customers | | [RC Shipping %](/reference/metrics/orders/adjustments/returning-customer-shipping-percent) | Compare new vs. returning customer patterns | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # New Customer Tax: Tax Collected from First-Time Buyers Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/new-customer-tax Track total tax collected from new customer orders. Measure tax contribution from first-time buyers and segment revenue by customer type. Total tax collected from new customer (first-time buyer) orders. ## Formula **New Customer Tax** = **SUM** ( Tax ) **WHERE** [customer\_type = new\_customer](/data-dictionary/measures-and-dimensions#visitor-dimensions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | [**Tax**](/reference/metrics/orders/adjustments/tax) | Tax amount charged on each order | | [**customer\_type = new\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from first-time buyers with no prior completed orders | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store collected **\$8,420** in tax from new customers in Q1: | Month | New Customer Tax | NC Orders | Avg Tax Per Order | | -------- | ---------------- | --------- | ----------------- | | January | \$3,150 | 412 | \$7.65 | | February | \$2,840 | 378 | \$7.51 | | March | \$2,430 | 356 | \$6.83 | March's lower average tax aligns with a promotion that drove smaller first-time orders. *** ## How It Works This metric sums all tax collected on orders placed by first-time customers. A customer is classified as "new" when they have no prior completed orders in your Shopify store. Tax amounts are determined by Shopify's tax calculations based on shipping destination, product category, and applicable tax rules. *** ## When to Use | Scenario | Action | | -------------------- | --------------------------------------------------------------------- | | Revenue segmentation | Break down total tax by customer type for accurate reporting | | Geographic analysis | Higher NC tax may indicate expansion into states with sales tax | | Promotion impact | Track if promotions attracting new customers affect average order tax | | Financial reporting | Reconcile tax liability by customer segment | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------ | ---------------------------------------------- | | [Returning Customer Tax](/reference/metrics/orders/adjustments/returning-customer-tax) | Compare tax from new vs repeat buyers | | [Tax](/reference/metrics/orders/adjustments/tax) | Total tax collected across all customer types | | [New Customer Total Revenue](/reference/metrics/orders/revenue/new-customer-total-revenue) | Includes tax in total revenue | | [New Customers](/reference/metrics/orders/customers/new-customers) | Order count to calculate average tax per order | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # New Customer Tax Per Order: Average Tax on First-Time Orders Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/new-customer-tax-per-order Track average tax collected per new customer order. Understand tax liability on first-time purchases and compare acquisition costs across regions. The average tax amount collected per new customer (first-time buyer) order. ## Formula **New Customer Tax Per Order** = [**New Customer Tax**](/reference/metrics/orders/adjustments/new-customer-tax) ÷ [**New Customers**](/reference/metrics/orders/customers/new-customers) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------ | ------------------------------------------------ | | [**New Customer Tax**](/reference/metrics/orders/adjustments/new-customer-tax) | Total tax collected from first-time buyer orders | | [**New Customers**](/reference/metrics/orders/customers/new-customers) | Number of orders from first-time buyers | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store collected **\$1,890** in tax from **270 new customer orders** in April: | Metric | Value | | -------------------- | ---------- | | New Customer Tax | \$1,890 | | New Customer Orders | 270 | | **NC Tax Per Order** | **\$7.00** | *** ## How It Works This metric divides total tax collected from new customers by their order count. Higher values often correlate with larger first-time orders or sales in higher-tax jurisdictions. Use it alongside geographic segmentation to understand regional tax burdens affecting new customer acquisition economics. *** ## When to Use | Scenario | Action | | ----------------- | ----------------------------------------------------------------------- | | Regional analysis | Compare across states/countries to understand tax impact on acquisition | | New vs. returning | Benchmark against returning customer tax to spot purchasing differences | | Total order cost | Combine with AOV to show customers' complete cost burden | | Campaign planning | Factor regional tax into ROAS targets for new customer campaigns | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------ | --------------------------------------------------------- | | [Tax Per Order](/reference/metrics/orders/adjustments/tax-per-order) | Average tax across all customer types—baseline comparison | | [RC Tax Per Order](/reference/metrics/orders/adjustments/returning-customer-tax-per-order) | Compare new vs. returning customer tax behavior | | [New Customer Net AOV](/reference/metrics/orders/aov/new-customer-net-aov) | Order value before tax—understand price vs. tax split | | [New Customer Total AOV](/reference/metrics/orders/aov/new-customer-total-aov) | Full order value including tax | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # New Customer Tax %: Tax Share of First-Time Buyer Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/new-customer-tax-percent Measure tax as a percentage of new customer revenue. Track tax burden on first-time buyers and compare across customer segments and regions. Tax collected as a percentage of total revenue from first-time buyers. ## Formula **New Customer Tax %** = ( [**New Customer Tax**](/reference/metrics/orders/adjustments/new-customer-tax) ÷ [**New Customer Total Revenue**](/reference/metrics/orders/revenue/new-customer-total-revenue) ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | [**New Customer Tax**](/reference/metrics/orders/adjustments/new-customer-tax) | Total tax collected from first-time buyer orders | | [**New Customer Total Revenue**](/reference/metrics/orders/revenue/new-customer-total-revenue) | Total revenue from first-time buyers including shipping and tax | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store had a **6.8% New Customer Tax %** this quarter: | Metric | Value | Context | | ---------------- | -------- | ---------------------- | | NC Tax Collected | \$4,760 | Tax from new customers | | NC Total Revenue | \$70,000 | Revenue including tax | | NC Tax % | 6.8% | Effective tax rate | *** ## How It Works This metric divides total tax collected from new customers by their total revenue (which includes tax), expressed as a percentage. It represents the effective tax burden on first-time buyer transactions and varies based on customer location and product taxability. *** ## When to Use | Scenario | Action | | ------------------------------ | ----------------------------------------------------- | | Comparing customer segments | Benchmark against Returning Customer Tax % | | Analyzing regional performance | Identify geographic tax rate differences | | Financial forecasting | Project tax obligations from new customer acquisition | | Pricing strategy | Understand tax impact on customer acquisition costs | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------ | -------------------------------------------- | | [New Customer Tax](/reference/metrics/orders/adjustments/new-customer-tax) | Numerator — tax collected from new customers | | [New Customer Total Revenue](/reference/metrics/orders/revenue/new-customer-total-revenue) | Denominator in this formula | | [Tax %](/reference/metrics/orders/adjustments/tax-percent) | Same calculation for all customers | | [RC Tax %](/reference/metrics/orders/adjustments/returning-customer-tax-percent) | Compare new vs. returning customer tax rates | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Refund Amount: Total Refunds Issued to Customers Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/refund-amount Track total refund value issued to customers. Monitor refund liability, identify return trends, and understand impact on net revenue in Upstack. The total dollar amount refunded to customers in the selected period. ## Formula **Refund Amount** = **SUM** ( Refund Value ) | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store issued **\$8,450 in refunds** during March: | Week | Refund Amount | Orders Affected | | ------ | ------------- | --------------- | | Week 1 | \$1,820 | 23 | | Week 2 | \$2,340 | 31 | | Week 3 | \$1,950 | 26 | | Week 4 | \$2,340 | 29 | *** ## How It Works Refund Amount sums the dollar value of all refunds processed in Shopify during the period. This includes partial and full refunds. High refund values reduce net revenue and may indicate product quality, sizing, or fulfillment issues. *** ## When to Use | Scenario | Action | | ------------------------- | ----------------------------------------------- | | Track refund liability | Monitor total refund dollars over time | | Identify problem products | Break down by product to find high-refund items | | Calculate net revenue | Subtract refunds from gross revenue | | Compare customer segments | Analyze new vs returning customer refunds | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------- | ----------------------------------------- | | [Refund Count](/reference/metrics/orders/adjustments/refund-count) | Number of orders with refunds | | [Refund %](/reference/metrics/orders/adjustments/refund-percent) | Refund rate as percentage of orders | | [Refund Per Order](/reference/metrics/orders/adjustments/refund-per-order) | Average refund per order | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Gross revenue minus refunds and discounts | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Refund Amount (by Order Date): Refunds Attributed to Orders Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/refund-amount-by-order-date Track refund amounts attributed to original order dates. Analyze cohort return rates, identify high-refund order batches, and improve forecasting. Refund amounts attributed to the original order date, enabling cohort analysis of which order batches experienced high returns. ## Formula **Refund Amount (by Order Date)** = **SUM** ( Refund Value ) **GROUPED BY** Original Order Date | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Orders placed in **January** generated **\$12,340 in refunds** over the following months: | Month Ordered | Orders | Refund Amount | Refund Rate | | ------------- | ------ | ------------- | ----------- | | January | 1,847 | \$12,340 | 8.2% | | February | 2,103 | \$9,450 | 5.5% | | March | 1,956 | \$6,120 | 3.8% | January's higher refund rate signals a potential product or fulfillment issue during that period. *** ## How It Works Unlike standard refund metrics that group by refund date, this metric attributes refunds back to when the original order was placed. A refund processed in April for a January order appears in January's totals. This reveals which order cohorts generated the most returns. *** ## When to Use | Scenario | Action | | --------------------------- | ------------------------------------------------------------------- | | Cohort return analysis | Compare refund rates across order date cohorts | | Campaign quality assessment | Identify if specific promotions drove low-quality orders | | Seasonal pattern detection | Spot high-refund periods like post-holiday returns | | LTV accuracy | Account for future refunds when calculating customer lifetime value | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | [Refund Amount](/reference/metrics/orders/adjustments/refund-amount) | Standard refund total (grouped by refund date) | | [Refund Amount (by Refund Date)](/reference/metrics/orders/adjustments/refund-amount-by-refund-date) | Refunds grouped by when issued | | [Refund Count](/reference/metrics/orders/adjustments/refund-count) | Number of orders with refunds | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Gross revenue minus refunds and discounts | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Refund Amount (by Refund Date): Track When Refunds Are Issued Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/refund-amount-by-refund-date Track refund amounts by the date refunds were issued. Monitor cash flow impact, identify refund spikes, and understand when returns actually process. Refund amounts attributed to the date the refund was issued, showing when money actually left your account rather than when the original order was placed. ## Formula **Refund Amount (by Refund Date)** = **SUM** ( Refund Value ) **GROUPED BY** Refund Issue Date | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store processed **\$18,450 in refunds** during March, despite variable order volumes: | Date | Refunds Issued | Amount | Notes | | -------- | -------------- | ------- | -------------------------- | | March 5 | 23 | \$2,890 | Post-February sale returns | | March 15 | 47 | \$8,340 | Batch processing day | | March 28 | 31 | \$4,120 | End-of-month spike | The March 15 spike indicates a batch processing event rather than a sudden quality issue. *** ## How It Works This metric groups refunds by when they were processed, not when orders were placed. A January order refunded in March appears in March's totals. This shows the actual cash flow impact of refunds on any given day or period. *** ## When to Use | Scenario | Action | | ---------------------------- | --------------------------------------------------- | | Cash flow forecasting | Predict when refund outflows will hit your account | | Refund processing monitoring | Detect unusual spikes in daily refund activity | | Operations planning | Staff appropriately for high-refund processing days | | Reconciliation | Match refund totals with bank statement debits | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | ----------------------------------------- | | [Refund Amount (by Order Date)](/reference/metrics/orders/adjustments/refund-amount-by-order-date) | Refunds attributed to original order date | | [Refund Amount](/reference/metrics/orders/adjustments/refund-amount) | Total refund amount | | [Refund Count](/reference/metrics/orders/adjustments/refund-count) | Number of orders with refunds | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Gross revenue minus refunds and discounts | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Refund Count: Number of Refunded Orders Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/refund-count Track the number of refunded orders in your Shopify store. Monitor return volume, identify problem products, and benchmark refund rates. The total number of orders that received a full or partial refund. ## Formula **Refund Count** = **COUNT** ( Orders ) **WHERE** refund\_amount > 0 | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Count | *** ## Example Your store processed **127 refunds** in March across 2,450 total orders: | Week | Refunds | Rate | | ------ | ------- | -------------------- | | Week 1 | 28 | 4.8% | | Week 2 | 31 | 5.2% | | Week 3 | 42 | 6.9% (new SKU issue) | | Week 4 | 26 | 4.3% | *** ## How It Works Refund Count tracks every order that had any refund processed in Shopify. Both full and partial refunds increment this count. Orders with multiple refunds count once. *** ## When to Use | Scenario | Action | | ---------------------- | ------------------------------------------------------ | | Return rate analysis | Compare refund count to total orders for return rate | | Product quality issues | Spike in refunds may indicate defective batch | | Customer satisfaction | High refund counts signal experience problems | | Seasonal patterns | Track if returns increase after holidays or promotions | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------- | --------------------------------------- | | [Refund Amount](/reference/metrics/orders/adjustments/refund-amount) | Dollar value of these refunds | | [Refund %](/reference/metrics/orders/adjustments/refund-percent) | Refund Count ÷ Orders | | [Refund Per Order](/reference/metrics/orders/adjustments/refund-per-order) | Average refund value per refunded order | | [Cancelled Orders](/reference/metrics/orders/adjustments/cancelled-orders) | Orders cancelled before fulfillment | | [Orders](/reference/metrics/orders/counts/orders) | Total orders (denominator for rate) | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Refund Gross Rate: Measure Return Impact on Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/refund-gross-rate Track total refunds as a percentage of gross revenue. Identify which order cohorts have high return rates and measure the impact on your top-line. Refund Gross Rate shows what portion of your gross revenue is being returned—a key indicator of product satisfaction and sizing accuracy. ## Formula **Refund Gross Rate** = ( [**Refund Amount**](/reference/metrics/orders/adjustments/refund-amount) ÷ [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------ | ------------------------------------------ | | [**Refund Amount**](/reference/metrics/orders/adjustments/refund-amount) | Total dollar value of all refunds issued | | [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) | Total revenue before discounts and refunds | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store generated **\$125,000 in gross revenue** in January with **\$8,750 in total refunds**. | Metric | Value | Calculation | | --------------------- | --------- | ------------------------- | | Gross Revenue | \$125,000 | — | | Refund Amount | \$8,750 | — | | **Refund Gross Rate** | **7.0%** | \$8,750 ÷ \$125,000 × 100 | *** ## How It Works This metric divides total refund dollars by gross revenue, giving you the percentage of sales value being returned. Unlike Refund %, which counts refunded orders, this rate measures the financial impact of returns on your top-line revenue. *** ## When to Use | Scenario | Action | | --------------------------- | ---------------------------------------------------- | | Benchmarking return rates | Compare against industry average (8-10% for apparel) | | Evaluating product quality | Investigate products with rates above 10% | | Assessing sizing/fit issues | High rates often signal sizing guide problems | | Measuring seasonal patterns | Track holiday vs. regular period refund rates | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------ | ---------------------------------------- | | [Refund Amount](/reference/metrics/orders/adjustments/refund-amount) | Dollar value used in numerator | | [Gross Revenue](/reference/metrics/orders/revenue/gross-revenue) | Denominator — revenue before adjustments | | [Refund Net Rate](/reference/metrics/orders/adjustments/refund-net-rate) | Same calculation against net revenue | | [Discount %](/reference/metrics/orders/adjustments/discount-percent) | Another adjustment rate metric | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Refund Net Rate: Revenue Lost to Refunds Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/refund-net-rate Track the percentage of gross revenue returned as refunds. Monitor product quality, reduce revenue leakage, and benchmark refund performance. The percentage of gross revenue that was refunded to customers. ## Formula **Refund Net Rate** = ( [**Refund Amount**](/reference/metrics/orders/adjustments/refund-amount) ÷ [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------ | ---------------------------------------- | | [**Refund Amount**](/reference/metrics/orders/adjustments/refund-amount) | Total dollar value refunded to customers | | [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) | Revenue before discounts and refunds | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store generated **\$125,000** in gross revenue with **\$3,750** in refunds last month: | Month | Gross Revenue | Refunds | Refund Net Rate | | -------- | ------------- | ------- | --------------- | | January | \$125,000 | \$3,750 | 3.0% | | February | \$118,000 | \$4,720 | 4.0% | | March | \$132,000 | \$2,640 | 2.0% | *** ## How It Works Refund Net Rate measures revenue leakage from refunds as a percentage of gross revenue. Unlike Refund %, which counts the number of refunded orders, this metric shows the actual dollar impact. A 5% refund net rate means \$5 of every \$100 in gross revenue is returned. *** ## When to Use | Scenario | Action | | ----------------------- | ------------------------------------------------------ | | Monitor product quality | Spikes indicate sizing, quality, or expectation issues | | Benchmark fulfillment | Compare rates across product lines or suppliers | | Calculate true margins | Factor refund leakage into profitability models | | Evaluate promotions | High refunds after sales may signal buyer's remorse | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------- | ----------------------------------------------------- | | [Refund Amount](/reference/metrics/orders/adjustments/refund-amount) | Numerator—total dollars refunded | | [Gross Revenue](/reference/metrics/orders/revenue/gross-revenue) | Denominator—revenue before adjustments | | [Refund %](/reference/metrics/orders/adjustments/refund-percent) | Count-based rate (orders with refunds ÷ total orders) | | [Refund Per Order](/reference/metrics/orders/adjustments/refund-per-order) | Average refund amount per order | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Gross Revenue − Refunds − Discounts | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Refund Per Order: Average Refund Amount Per Order Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/refund-per-order Track the average refund amount per order from your Shopify store. Measure refund impact on profitability and identify product or fulfillment issues. The average refund amount issued per order. ## Formula **Refund Per Order** = [**Refund Amount**](/reference/metrics/orders/adjustments/refund-amount) ÷ [**Orders**](/reference/metrics/orders/counts/orders) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------ | ---------------------------------------- | | [**Refund Amount**](/reference/metrics/orders/adjustments/refund-amount) | Total dollar value of all refunds issued | | [**Orders**](/reference/metrics/orders/counts/orders) | Total number of completed orders | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store processed **2,450 orders** in February with **\$8,575** in total refunds: | Metric | Value | | -------------------- | ---------- | | Refund Amount | \$8,575 | | Order Count | 2,450 | | **Refund Per Order** | **\$3.50** | *** ## How It Works Refund Per Order divides total refund dollars by total orders—not just refunded orders. This gives you the average refund liability per transaction, helping you understand the true cost of returns across your entire order base. *** ## When to Use | Scenario | Action | | -------------------------- | -------------------------------------------------------------- | | Tracking return cost | Compare against Net AOV to understand refund impact on margins | | Evaluating product quality | Higher values may signal product issues or unmet expectations | | Assessing sizing guides | Apparel brands should track this alongside return reasons | | Comparing campaigns | Identify traffic sources with higher post-purchase refunds | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------- | -------------------------------------------------------- | | [Refund Amount](/reference/metrics/orders/adjustments/refund-amount) | Numerator: total refund dollars | | [Orders](/reference/metrics/orders/counts/orders) | Denominator: transaction count | | [Refund %](/reference/metrics/orders/adjustments/refund-percent) | Percentage of orders refunded | | [Net AOV](/reference/metrics/orders/aov/net-aov) | Order value after refunds—compare to gauge refund impact | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Refund %: Percentage of Orders Refunded Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/refund-percent Track the percentage of orders that resulted in refunds. Monitor return rates by product, campaign, or time period to identify quality issues and optimize operations. The percentage of orders that resulted in a refund. ## Formula **Refund %** = ( [**Refund Count**](/reference/metrics/orders/adjustments/refund-count) ÷ [**Orders**](/reference/metrics/orders/counts/orders) ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------- | --------------------------------------- | | [**Refund Count**](/reference/metrics/orders/adjustments/refund-count) | Number of orders with refunds processed | | [**Orders**](/reference/metrics/orders/counts/orders) | Total number of orders placed | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store processed **1,847 orders** in March with **92 refunds**: | Period | Orders | Refunds | Refund % | | ------ | ------ | ------- | -------- | | Week 1 | 423 | 18 | 4.3% | | Week 2 | 489 | 21 | 4.3% | | Week 3 | 461 | 34 | 7.4% | | Week 4 | 474 | 19 | 4.0% | Week 3's spike to 7.4% warrants investigation—check product quality or fulfillment issues. *** ## How It Works Refund % calculates the ratio of refunded orders to total orders. The metric counts any order with a refund—partial or full—as one refund. This gives you a clear view of what percentage of customers received money back. *** ## When to Use | Scenario | Action | | --------------------- | ----------------------------------------------------- | | Quality monitoring | Track refund rates by product to identify defects | | Campaign analysis | Compare refund rates across acquisition channels | | Seasonal benchmarking | Monitor how return rates change during peak seasons | | Operations review | Investigate spikes in refund % for fulfillment issues | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------- | -------------------------------- | | [Refund Count](/reference/metrics/orders/adjustments/refund-count) | Numerator (raw count of refunds) | | [Orders](/reference/metrics/orders/counts/orders) | Denominator (total orders) | | [Refund Amount](/reference/metrics/orders/adjustments/refund-amount) | Dollar value of refunds issued | | [Refund Per Order](/reference/metrics/orders/adjustments/refund-per-order) | Average refund amount per order | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Refund + Discount: Combined Revenue Adjustments Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/refund-plus-discount Track total refunds and discounts combined in one metric. See how revenue adjustments impact net revenue, gross margins, and overall profitability. The sum of total refunds and total discounts—a single view of all revenue adjustments. ## Formula **Refund + Discount** = [**Refund Amount**](/reference/metrics/orders/adjustments/refund-amount) + [**Discount Amount**](/reference/metrics/orders/adjustments/discount-amount) ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------- | ----------------------------------- | | [**Refund Amount**](/reference/metrics/orders/adjustments/refund-amount) | Dollar amount refunded to customers | | [**Discount Amount**](/reference/metrics/orders/adjustments/discount-amount) | Dollar value of discounts applied | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store had **\$12,450** in combined adjustments this month: | Component | Amount | Share | | --------- | ------- | ----- | | Refunds | \$4,200 | 34% | | Discounts | \$8,250 | 66% | With \$125,000 in gross revenue, adjustments represent 10% of your top line. *** ## How It Works Refund + Discount combines both types of revenue adjustments into a single metric. This provides visibility into total "leakage" from gross revenue without needing to track refunds and discounts separately. *** ## When to Use | Scenario | Action | | -------------------------------- | -------------------------------------------------------------------------------- | | Understanding net revenue impact | See how much revenue is adjusted away from gross | | Comparing adjustment trends | Track if total adjustments are increasing over time | | Profitability analysis | Factor combined adjustments into margin calculations | | Promotion vs. returns balance | Understand the mix of intentional (discounts) vs. reactive (refunds) adjustments | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------ | ---------------------------------------- | | [Refund Amount](/reference/metrics/orders/adjustments/refund-amount) | Refund portion of this combined metric | | [Discount Amount](/reference/metrics/orders/adjustments/discount-amount) | Discount portion of this combined metric | | [Gross Revenue](/reference/metrics/orders/revenue/gross-revenue) | Revenue before these adjustments | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Gross Revenue minus adjustments | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Returning Customer Cancelled Amount: Lost Revenue from Repeat Buyers Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/returning-customer-cancelled-amount Track cancelled order value from returning customers. Monitor repeat buyer cancellations to identify fulfillment issues and protect customer lifetime value. The total dollar value of orders from returning customers that were cancelled before fulfillment. ## Formula **Returning Customer Cancelled Amount** = **SUM** ( Cancelled Order Value ) **WHERE** [customer\_type = returning\_customer](/data-dictionary/measures-and-dimensions#visitor-dimensions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | [**Cancelled Amount**](/reference/metrics/orders/adjustments/cancelled-amount) | Total dollar value of cancelled orders | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from customers who have purchased before | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store had **\$4,250 in returning customer cancellations** during March: | Week | RC Cancelled Amount | RC Cancelled Orders | Avg Order Value | | ------ | ------------------- | ------------------- | --------------- | | Week 1 | \$890 | 4 | \$222.50 | | Week 2 | \$1,340 | 6 | \$223.33 | | Week 3 | \$1,120 | 5 | \$224.00 | | Week 4 | \$900 | 4 | \$225.00 | *** ## How It Works This metric sums the total value of cancelled orders specifically from returning customers—buyers who have completed at least one previous purchase. When a returning customer's order is cancelled before fulfillment in Shopify, the order value is added to this total. *** ## When to Use | Scenario | Action | | ------------------------------------- | ------------------------------------------------------------------------- | | Rising cancellation value | Investigate inventory issues or shipping delays affecting loyal customers | | Compare to new customer cancellations | Determine if repeat buyers have different cancellation patterns | | High-value order cancellations | Prioritize outreach to retain valuable repeat customers | | Seasonal analysis | Identify if promotions drive cancellation spikes among returning buyers | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------ | -------------------------------------------- | | [RC Cancelled Orders](/reference/metrics/orders/adjustments/returning-customer-cancelled-orders) | Count of cancelled returning customer orders | | [Cancelled Amount](/reference/metrics/orders/adjustments/cancelled-amount) | Total cancelled amount across all customers | | [NC Cancelled Amount](/reference/metrics/orders/adjustments/new-customer-cancelled-amount) | Cancelled amount from first-time buyers | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Returning Customer Cancelled Orders: Cancellations by Repeat Buyers Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/returning-customer-cancelled-orders Track cancelled orders from returning customers. Monitor repeat buyer cancellations to identify fulfillment issues and protect customer retention. The number of orders from returning customers that were cancelled before fulfillment. ## Formula **Returning Customer Cancelled Orders** = **COUNT** ( Cancelled Orders ) **WHERE** [customer\_type = returning\_customer](/data-dictionary/measures-and-dimensions#visitor-dimensions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | [**Cancelled Orders**](/reference/metrics/orders/adjustments/cancelled-orders) | Total count of cancelled orders | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from customers who have purchased before | | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Count | *** ## Example Your store had **22 Returning Customer Cancelled Orders** this month out of 2,340 returning customer orders: | Week | RC Cancellations | RC Orders | Cancel % | | --------- | ---------------- | --------- | ---------------------- | | Week 1 | 4 | 580 | 0.7% | | Week 2 | 8 | 610 | 1.3% (inventory issue) | | Week 3 | 6 | 590 | 1.0% | | Week 4 | 4 | 560 | 0.7% | | **Total** | **22** | **2,340** | **0.9%** | *** ## How It Works This metric counts orders placed by returning customers that were cancelled before fulfillment in Shopify. A customer is classified as "returning" if they have completed at least one previous purchase. Cancellations typically occur due to inventory stockouts, payment issues, or customer requests. *** ## When to Use | Scenario | Action | | ------------------------------ | ----------------------------------------------------------- | | Protecting customer retention | Monitor cancellation trends among your most valuable buyers | | Investigating inventory issues | Spikes may indicate stockouts affecting repeat purchasers | | Measuring lost opportunity | Pair with RC Cancelled Amount for dollar impact | | Comparing customer types | Benchmark against new customer cancellation rates | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------ | ------------------------------------------------ | | [RC Cancelled Amount](/reference/metrics/orders/adjustments/returning-customer-cancelled-amount) | Dollar value of these cancellations | | [Cancelled Orders](/reference/metrics/orders/adjustments/cancelled-orders) | Total cancellations (all customers) | | [NC Cancelled Orders](/reference/metrics/orders/adjustments/new-customer-cancelled-orders) | Same metric for first-time buyers | | [Returning Customers](/reference/metrics/orders/customers/returning-customers) | Total returning customers (denominator for rate) | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Returning Customer Discount Gross Rate: Discounts as % of Gross Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/returning-customer-discount-gross-rate Measure returning customer discount dollars as a percentage of gross revenue. Track loyalty discount impact on repeat-purchase margins with Shopify order data. Returning customer discount amount as a percentage of returning customer gross revenue. ## Formula **Returning Customer Discount Gross Rate** = ( [**Returning Customer Discounts**](/reference/metrics/orders/adjustments/returning-customer-discounts) ÷ [**Returning Customer Gross Revenue**](/reference/metrics/orders/revenue/returning-customer-gross-revenue) ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | [**Returning Customer Discounts**](/reference/metrics/orders/adjustments/returning-customer-discounts) | Total dollar value of discounts applied to repeat buyer orders | | [**Returning Customer Gross Revenue**](/reference/metrics/orders/revenue/returning-customer-gross-revenue) | Total revenue from returning customers before adjustments | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your returning customers generated **\$145,000** in gross revenue with **\$11,600** in loyalty discounts: | Metric | Value | | -------------------------------- | --------- | | Returning Customer Gross Revenue | \$145,000 | | Returning Customer Discounts | \$11,600 | | **RC Discount Gross Rate** | **8.0%** | *** ## How It Works This metric divides returning customer discount dollars by returning customer gross revenue, then multiplies by 100. It measures how much repeat buyer revenue is offset by loyalty or promotional discounts. High rates may indicate over-reliance on discounts to drive repeat purchases, cutting into retention margins. *** ## When to Use | Scenario | Action | | ---------------------------- | ------------------------------------------------------------------------------ | | Loyalty program evaluation | Assess whether loyalty discounts are eroding repeat-purchase profitability | | Margin analysis | Monitor discount impact on your most valuable customer segment | | New vs. returning comparison | Benchmark against NC Discount Gross Rate for acquisition vs. retention balance | | Retention strategy | Identify if repeat customers can be retained with smaller discounts | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------ | ------------------------------------------------- | | [RC Discount %](/reference/metrics/orders/adjustments/returning-customer-discount-percent) | Related percentage metric for returning customers | | [RC Discounts](/reference/metrics/orders/adjustments/returning-customer-discounts) | Total discount amount for returning customers | | [NC Discount Gross Rate](/reference/metrics/orders/adjustments/new-customer-discount-gross-rate) | Compare retention vs. acquisition discount rates | | [Discount Amount](/reference/metrics/orders/adjustments/discount-amount) | Total discounts across all customers | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Returning Customer Discount Order Rate: Retention Discount Dependency Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/returning-customer-discount-order-rate Track the percentage of returning customer orders using discounts. Measure retention discount dependency and optimize loyalty promotional strategy. The share of returning customer orders that used a discount code or promotion. ## Formula **Returning Customer Discount Order Rate** = ( [**Returning Customer Discounted Orders**](/reference/metrics/orders/adjustments/discount-count) ÷ [**Returning Customers**](/reference/metrics/orders/customers/returning-customers) ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | **Returning Customer Discounted Orders** | Count of returning customer orders with a discount applied | | [**Returning Customers**](/reference/metrics/orders/customers/returning-customers) | Total number of returning customer orders | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from customers who have purchased before | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store had **1,156 returning customer orders** in January, with **462 using discount codes**: | Period | RC Discounted Orders | RC Orders | Rate | | -------- | -------------------- | --------- | ----- | | January | 462 | 1,156 | 40.0% | | February | 387 | 1,034 | 37.4% | *** ## How It Works Counts repeat buyer orders with discounts and divides by total returning customer orders. Elevated values may signal discount dependency in retention; declining rates show loyal customers converting without incentives. *** ## When to Use | Scenario | Action | | ------------------------------ | ---------------------------------------------------------- | | Evaluating loyalty program ROI | High rates mean discounts drive most repeat purchases | | Testing discount reduction | Monitor if rate drops without hurting retention | | Comparing to new customers | Identify if new vs repeat buyers need different incentives | | Optimizing retention margins | Lower rates improve profitability on repeat orders | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------ | ---------------------------------------------- | | [NC Discount Order Rate](/reference/metrics/orders/adjustments/new-customer-discount-order-rate) | Same metric for first-time customers | | [RC Discounts](/reference/metrics/orders/adjustments/returning-customer-discounts) | Total discount dollars for returning customers | | [Discount Count](/reference/metrics/orders/adjustments/discount-count) | Total orders with discounts (all customers) | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Returning Customer Discount Per Order: Average RC Discount Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/returning-customer-discount-per-order Track the average discount amount per returning customer order from Shopify. Measure repeat buyer promotional costs and optimize retention discount strategies. The average discount dollar value applied per returning customer order. ## Formula **Returning Customer Discount Per Order** = [**Returning Customer Discounts**](/reference/metrics/orders/adjustments/returning-customer-discounts) ÷ [**Returning Customers**](/reference/metrics/orders/customers/returning-customers) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- | | [**Returning Customer Discounts**](/reference/metrics/orders/adjustments/returning-customer-discounts) | Total discount dollars applied to returning customer orders | | [**Returning Customers**](/reference/metrics/orders/customers/returning-customers) | Number of orders placed by returning customers | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store processed **856 returning customer orders** in March with **\$6,848** in discounts: | Metric | Value | | ------------------------- | ---------- | | RC Discounts | \$6,848 | | RC Order Count | 856 | | **RC Discount Per Order** | **\$8.00** | Compare to New Customer Discount Per Order (\$12.50) to see if you're over-incentivizing acquisition versus retention. *** ## How It Works Returning Customer Discount Per Order divides total discounts on repeat buyer orders by the number of those orders. Unlike the total discount figure, this metric normalizes for volume—revealing whether discount intensity is rising or falling as you scale retention. *** ## When to Use | Scenario | Action | | ------------------------ | ----------------------------------------------------------------- | | Retention cost tracking | Monitor per-order discount cost for repeat buyers | | Segment comparison | Compare against new customer discount per order | | Loyalty program analysis | Evaluate if loyalty discounts are creeping higher over time | | Margin protection | Set thresholds to prevent discount escalation on repeat purchases | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | [RC Discounts](/reference/metrics/orders/adjustments/returning-customer-discounts) | Numerator: total discount dollars for returning customers | | [Returning Customers](/reference/metrics/orders/customers/returning-customers) | Denominator: returning customer order count | | [RC Discount %](/reference/metrics/orders/adjustments/returning-customer-discount-percent) | Discounts as percentage of RC gross revenue | | [Discount Per Order](/reference/metrics/orders/adjustments/discount-per-order) | All-customer discount per order for comparison | | [NC Discount Per Order](/reference/metrics/orders/adjustments/new-customer-discount-per-order) | Acquisition discount per order for segmented analysis | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Returning Customer Discount %: Discount Share of Gross Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/returning-customer-discount-percent Measure returning customer discounts as a percentage of gross revenue. Track loyalty discount impact on repeat purchase margins with Shopify order data. Returning customer discounts as a percentage of returning customer gross revenue. ## Formula **Returning Customer Discount %** = ( [**Returning Customer Discounts**](/reference/metrics/orders/adjustments/returning-customer-discounts) ÷ [**Returning Customer Gross Revenue**](/reference/metrics/orders/revenue/returning-customer-gross-revenue) ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | [**Returning Customer Discounts**](/reference/metrics/orders/adjustments/returning-customer-discounts) | Total dollar value of discounts applied to returning customer orders | | [**Returning Customer Gross Revenue**](/reference/metrics/orders/revenue/returning-customer-gross-revenue) | Total revenue from returning customers before adjustments | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your returning customers generated **\$125,000** in gross revenue with **\$8,750** in discounts: | Metric | Value | | --------------------------------- | --------- | | Returning Customer Gross Revenue | \$125,000 | | Returning Customer Discounts | \$8,750 | | **Returning Customer Discount %** | **7.0%** | *** ## How It Works This metric divides returning customer discounts by returning customer gross revenue, then multiplies by 100. Higher percentages indicate heavier discount reliance for repeat purchases, which may signal loyalty program overuse or discount dependency in retention strategies. *** ## When to Use | Scenario | Action | | ---------------------------- | ------------------------------------------------------------- | | Evaluating loyalty programs | Compare discount rates to ensure repeat margins stay healthy | | Retention cost analysis | Monitor if discount dependency is growing over time | | New vs. returning comparison | Benchmark against new customer discount rates | | Margin optimization | Identify opportunities to reduce unnecessary repeat discounts | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | | [Returning Customer Discounts](/reference/metrics/orders/adjustments/returning-customer-discounts) | The numerator — total discount dollars | | [Returning Customer Gross Revenue](/reference/metrics/orders/revenue/returning-customer-gross-revenue) | The denominator — gross revenue from repeat buyers | | [RC Discount Per Order](/reference/metrics/orders/adjustments/returning-customer-discount-per-order) | Average discount per returning customer order | | [NC Discount %](/reference/metrics/orders/adjustments/new-customer-discount-percent) | Compare acquisition vs. retention discount rates | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Returning Customer Discount Amount: Repeat Buyer Discount Total Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/returning-customer-discounts Track total discount dollars applied to returning customer orders. Measure loyalty program impact and repeat purchase discount strategies with Shopify data. Total dollar value of discounts applied to returning customer orders. ## Formula **Returning Customer Discount Amount** = **SUM** ( Discount Amount ) **WHERE** customer\_type = returning\_customer ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | [**Discount Amount**](/reference/metrics/orders/adjustments/discount-amount) | Total discounts applied to orders | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from customers who have purchased before | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store applied **\$12,450** in discounts to returning customer orders in Q1: | Month | RC Discounts | RC Orders | Discount/Order | | -------- | ------------ | --------- | -------------- | | January | \$3,820 | 412 | \$9.27 | | February | \$4,150 | 478 | \$8.68 | | March | \$4,480 | 523 | \$8.57 | Declining discount per order while total discounts grow indicates healthy repeat purchase volume with improving margins. *** ## How It Works This metric sums all discount amounts from orders placed by returning customers. A customer is classified as "returning" when they have at least one prior completed order in Shopify. Discounts include coupon codes, automatic discounts, and manual adjustments applied at checkout. *** ## When to Use | Scenario | Action | | ------------------------------ | -------------------------------------------------------------------- | | Measuring loyalty program cost | Track how much revenue is given away to repeat buyers | | Comparing segments | Benchmark against new customer discounts to ensure balanced strategy | | Retention budget analysis | Monitor discount spend as a component of retention cost | | Margin optimization | Identify opportunities to reduce excessive repeat-purchase discounts | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | [Returning Customer Discount %](/reference/metrics/orders/adjustments/returning-customer-discount-percent) | Discounts as percentage of gross revenue | | [New Customer Discounts](/reference/metrics/orders/adjustments/new-customer-discounts) | Compare acquisition vs. retention discount spending | | [Discount Amount](/reference/metrics/orders/adjustments/discount-amount) | Total discounts across all customer types | | [Returning Customer Refunds](/reference/metrics/orders/adjustments/returning-customer-refunds) | Combined with discounts for total adjustments | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Returning Customer Refund Count: Orders Refunded by Repeat Buyers Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/returning-customer-refund-count Count orders from returning customers that resulted in refunds. Monitor loyalty program health and identify issues with repeat buyer satisfaction. The number of returning customer orders that had a refund issued. ## Formula **Returning Customer Refund Count** = **COUNT** ( Refunded Orders ) **WHERE** customer\_type = returning\_customer ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------- | ------------------------------ | | [**Refunded Orders**](/reference/metrics/orders/adjustments/refund-count) | Orders with refunds issued | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions#customer-type) | Filters to returning customers | | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Count | *** ## Example Your store had **89 returning customer refunds** this quarter: | Channel | RC Refunds | RC Orders | Refund % | | --------- | ---------- | --------- | -------- | | Meta Ads | 38 | 720 | 5.3% | | Email | 32 | 850 | 3.8% | | Organic | 19 | 430 | 4.4% | | **Total** | **89** | **2,000** | **4.5%** | *** ## How It Works This metric counts orders placed by repeat customers that Shopify marks as refunded. A customer is classified as "returning" when they have at least one prior order in your Shopify store. The count includes full and partial refunds. *** ## When to Use | Scenario | Action | | --------------------------- | ----------------------------------------------- | | Monitoring loyalty health | Compare RC refund count to NC refund count | | Evaluating product changes | Track if updates increase refunds from regulars | | Calculating refund rate | Use as numerator in Returning Customer Refund % | | Identifying retention risks | Rising counts may signal declining satisfaction | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | ---------------------------------------- | | [Returning Customer Refund %](/reference/metrics/orders/adjustments/returning-customer-refund-percent) | This count divided by RC orders | | [Returning Customer Refunds](/reference/metrics/orders/adjustments/returning-customer-refunds) | Dollar amount (this metric is the count) | | [New Customer Refund Count](/reference/metrics/orders/adjustments/new-customer-refund-count) | Same metric for first-time buyers | | [Refund Count](/reference/metrics/orders/adjustments/refund-count) | Total refund count (all customers) | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Returning Customer Refund per Order: Average Repeat-Buyer Refund Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/returning-customer-refund-per-order Track average refund amount per returning customer order. Measure repeat-buyer return costs and compare against new customer refund behavior. Average refund amount per returning customer order. ## Formula **Returning Customer Refund per Order** = **Returning Customer Refunds** ÷ **Returning Customer Order Count** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------- | ------------------------------------------- | | [**Returning Customer Refunds**](/reference/metrics/orders/adjustments/returning-customer-refunds) | Total refund amount for returning customers | | [**Returning Customer Order Count**](/reference/metrics/orders/counts/returning-customer-orders) | Total orders from returning customers | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store processed **1,603 returning customer orders** in February with **\$3,494** in refunds: | Metric | Value | | -------------------------- | ---------- | | Returning Customer Refunds | \$3,494 | | Returning Customer Orders | 1,603 | | **RC Refund per Order** | **\$2.18** | Compare this to your New Customer Refund per Order of \$3.50—repeat buyers cost 38% less in refunds per order. *** ## How It Works This metric divides total returning customer refunds by total returning customer orders—not just refunded orders. This gives you the average refund liability per repeat buyer transaction, helping you understand customer retention quality and whether loyal buyers maintain lower return rates than first-time purchasers. *** ## When to Use | Scenario | Action | | ------------------------------------ | ------------------------------------------------------------------------- | | Comparing NC vs RC behavior | Returning customers typically have lower refund rates than new customers | | Evaluating product quality over time | Rising RC refunds may indicate quality degradation affecting loyal buyers | | Measuring loyalty program impact | Track whether loyalty members have better post-purchase satisfaction | | Forecasting retention costs | Factor into LTV calculations alongside repeat purchase rates | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------- | | [Returning Customer Refunds](/reference/metrics/orders/adjustments/returning-customer-refunds) | Numerator: total RC refund dollars | | [Returning Customer Refund %](/reference/metrics/orders/adjustments/returning-customer-refund-percent) | Percentage of RC orders refunded | | [New Customer Refund per Order](/reference/metrics/orders/adjustments/new-customer-refund-per-order) | Compare new vs returning customer refund behavior | | [Refund per Order](/reference/metrics/orders/adjustments/refund-per-order) | Overall refund per order across all customers | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Returning Customer Refund %: Track Repeat Buyer Returns Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/returning-customer-refund-percent Measure the percentage of returning customer orders that result in refunds. Compare to new customer refund rates and identify retention risks. The share of returning customer orders that resulted in a refund. ## Formula **Returning Customer Refund %** = **Returning Customer Refund Count** ÷ **Returning Customer Order Count** × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | | [**Returning Customer Refund Count**](/reference/metrics/orders/adjustments/returning-customer-refund-count) | Number of returning customer orders with refunds | | [**Returning Customer Order Count**](/reference/metrics/orders/counts/returning-customer-orders) | Total returning customer orders | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store processed **1,850 returning customer orders** in Q1, with **148 resulting in refunds** (8.0%): | Month | RC Orders | RC Refunds | RC Refund % | | -------- | --------- | ---------- | ----------- | | January | 580 | 41 | 7.1% | | February | 620 | 50 | 8.1% | | March | 650 | 57 | 8.8% | *** ## How It Works Divides refunded returning customer orders by total returning customer orders. A returning customer is anyone who previously completed an order. Refunds are attributed to the original order date and include both full and partial refunds. *** ## When to Use | Scenario | Action | | ---------------------------------- | ------------------------------------------------------------------------- | | Comparing customer segments | Higher RC refund rate may signal product quality issues for repeat buyers | | Identifying retention risks | Rising refund rates among repeat buyers can predict churn | | Product category analysis | Segment by product to find categories with higher repeat-buyer returns | | Benchmarking against new customers | Compare to NC Refund % to understand segment behavior | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [Refund %](/reference/metrics/orders/adjustments/refund-percent) | Overall refund rate across all customers | | [New Customer Refund %](/reference/metrics/orders/adjustments/new-customer-refund-percent) | Compare acquisition vs retention refund behavior | | [Returning Customer Refunds](/reference/metrics/orders/adjustments/returning-customer-refunds) | Dollar amount refunded to returning customers | | [Returning Customer Refund Count](/reference/metrics/orders/adjustments/returning-customer-refund-count) | Numerator in this formula | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Returning Customer Refund + Discount: Combined Adjustments Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/returning-customer-refund-plus-discount Track total refunds and discounts from returning customers. Combine both adjustment types to measure the full impact on returning customer revenue. The combined total of refunds and discounts applied to orders from returning customers. ## Formula **Returning Customer Refund + Discount** = **Returning Customer Refunds** + **Returning Customer Discounts** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------- | | [**Returning Customer Refunds**](/reference/metrics/orders/adjustments/returning-customer-refunds) | Total refund amount for returning customer orders | | [**Returning Customer Discounts**](/reference/metrics/orders/adjustments/returning-customer-discounts) | Total discount amount for returning customer orders | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store processed **\$8,420** in returning customer adjustments this month: | Adjustment Type | Amount | Share | | --------------- | ----------- | ----- | | Refunds | \$5,180 | 62% | | Discounts | \$3,240 | 38% | | **Total** | **\$8,420** | 100% | *** ## How It Works This metric sums all refunds and discounts applied to orders placed by returning customers. Returning customers are identified as shoppers who have made at least one previous purchase. The combined value represents the total revenue adjustment for this customer segment. *** ## When to Use | Scenario | Action | | ---------------------------- | ---------------------------------------------------------------------- | | Analyzing repeat buyer costs | Compare total adjustments against returning customer gross revenue | | Loyalty program impact | Track if returning customers receive more discounts than new customers | | Retention cost analysis | Factor combined adjustments into customer lifetime value calculations | | Segment comparison | Compare against new customer adjustments to identify trends | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | ----------------------------------- | | [Returning Customer Refunds](/reference/metrics/orders/adjustments/returning-customer-refunds) | Refund component of this metric | | [Returning Customer Discounts](/reference/metrics/orders/adjustments/returning-customer-discounts) | Discount component of this metric | | [NC Refund + Discount](/reference/metrics/orders/adjustments/new-customer-refund-plus-discount) | Same metric for new customers | | [Refund + Discount](/reference/metrics/orders/adjustments/refund-plus-discount) | Combined total across all customers | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Returning Customer Refunds: Repeat Buyer Refund Total Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/returning-customer-refunds Track total refund dollars for returning customers. Monitor repeat buyer satisfaction and identify product or service issues affecting loyal customers. The total dollar amount refunded to returning customers (repeat buyers). ## Formula **Returning Customer Refunds** = **SUM** ( Refund Amount ) **WHERE** customer\_type = returning\_customer ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------- | ------------------------------- | | [**Refund Amount**](/reference/metrics/orders/adjustments/refund-amount) | Total refunds applied to orders | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions#customer-type) | Filters to returning customers | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store refunded **\$8,720** to returning customers in March across 89 refunds: | Week | Returning Customer Refunds | Refund Count | | ------ | -------------------------- | ------------ | | Week 1 | \$1,892 | 19 | | Week 2 | \$2,456 | 28 | | Week 3 | \$2,502 | 25 | | Week 4 | \$1,870 | 17 | A spike in Week 2 may indicate a quality issue with a recent product batch or fulfillment delays affecting repeat buyers. *** ## How It Works This metric sums all refund amounts from orders placed by returning customers. A customer is classified as "returning" when they have at least one prior completed order in Shopify. High values may indicate product quality degradation, unmet expectations from loyal customers, or fulfillment issues. *** ## When to Use | Scenario | Action | | ------------------------------- | -------------------------------------------------------------- | | Monitoring customer retention | High refunds from repeat buyers signal satisfaction issues | | Identifying quality problems | Compare to new customer refunds to isolate repeat buyer issues | | Evaluating product changes | Track refunds after product updates to measure impact | | Measuring loyalty program value | Correlate with loyalty tier to assess member satisfaction | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [New Customer Refunds](/reference/metrics/orders/adjustments/new-customer-refunds) | Compare new vs. returning customer refund behavior | | [Refund Amount](/reference/metrics/orders/adjustments/refund-amount) | Total refunds across all customer types | | [Returning Customer Refund %](/reference/metrics/orders/adjustments/returning-customer-refund-percent) | Share of returning customer orders refunded | | [Returning Customer Refund per Order](/reference/metrics/orders/adjustments/returning-customer-refund-per-order) | Average refund amount per returning customer order | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Returning Customer Shipping Revenue: Shipping Fees from Repeat Buyers Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/returning-customer-shipping Track total shipping fees collected from returning customer orders. Measure repeat buyer shipping contribution to revenue with Shopify order data. Returning Customer Shipping Revenue measures the total shipping fees collected from orders placed by customers who have purchased before. ## Formula **Returning Customer Shipping Revenue** = **SUM** ( Shipping Amount ) **WHERE** customer\_type = returning\_customer ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | [**Shipping Revenue**](/reference/metrics/orders/adjustments/shipping-revenue) | Total shipping fees collected from all orders | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from customers who have purchased before | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store collected **\$4,850** in shipping fees from returning customers in March: | Metric | Value | | --------------------------------- | ---------- | | Returning Customer Orders | 970 | | RC Shipping Revenue | \$4,850 | | **Average Shipping Per RC Order** | **\$5.00** | *** ## How It Works Returning Customer Shipping Revenue sums all shipping fees charged on orders placed by returning customers. A returning customer is any buyer who has at least one prior completed order in your Shopify store before the current order date. *** ## When to Use | Scenario | Action | | ------------------------------- | ---------------------------------------------------------------- | | Shipping strategy analysis | Compare RC vs NC shipping to identify loyalty opportunities | | Free shipping threshold testing | Measure impact of shipping offers on repeat purchases | | Revenue composition breakdown | Understand shipping's contribution to returning customer revenue | | Retention program evaluation | Track if loyalty perks like free shipping affect repeat volume | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | [Shipping Revenue](/reference/metrics/orders/adjustments/shipping-revenue) | Total shipping from all customers | | [New Customer Shipping](/reference/metrics/orders/adjustments/new-customer-shipping) | Compare acquisition vs retention shipping | | [RC Shipping %](/reference/metrics/orders/adjustments/returning-customer-shipping-percent) | Shipping as percentage of returning customer revenue | | [RC Shipping Per Order](/reference/metrics/orders/adjustments/returning-customer-shipping-per-order) | Average shipping per returning customer order | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Returning Customer Shipping Per Order: Average Shipping Fee Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/returning-customer-shipping-per-order Track average shipping fees collected per returning customer order. Measure repeat buyer shipping efficiency and compare against new customers. The average shipping fee collected per returning customer order. ## Formula **Returning Customer Shipping Per Order** = **Returning Customer Shipping Revenue** ÷ **Returning Customer Order Count** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | | [**Returning Customer Shipping Revenue**](/reference/metrics/orders/adjustments/returning-customer-shipping) | Total shipping fees collected from returning customers | | [**Returning Customer Order Count**](/reference/metrics/orders/counts/returning-customer-orders) | Number of orders from customers with prior purchases | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store collected **\$5,640** in shipping from **1,128 returning customer orders** in April: | Metric | Value | | --------------------------- | ---------- | | Returning Customer Shipping | \$5,640 | | Returning Customer Orders | 1,128 | | **RC Shipping Per Order** | **\$5.00** | *** ## How It Works This metric divides total shipping fees collected from returning customers by the number of returning customer orders. It reveals the average shipping contribution from repeat buyers—useful for comparing shipping behavior between new and returning customer segments. *** ## When to Use | Scenario | Action | | ------------------------- | --------------------------------------------------------------- | | Loyalty shipping analysis | Compare against NC Shipping Per Order to gauge loyalty benefits | | Free shipping threshold | Test if free shipping offers drive more repeat purchases | | Pricing strategy | Balance shipping fees with customer retention goals | | Segment profitability | Factor shipping revenue into returning customer LTV | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | [Returning Customer Shipping Revenue](/reference/metrics/orders/adjustments/returning-customer-shipping) | Numerator: total RC shipping revenue | | [New Customer Shipping Per Order](/reference/metrics/orders/adjustments/new-customer-shipping-per-order) | Compare acquisition vs retention shipping efficiency | | [Returning Customer Shipping %](/reference/metrics/orders/adjustments/returning-customer-shipping-percent) | Shipping as percentage of RC total revenue | | [Shipping Per Order](/reference/metrics/orders/adjustments/shipping-per-order) | Overall average shipping per order | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Returning Customer Shipping %: Revenue Composition Analysis Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/returning-customer-shipping-percent Track returning customer shipping as a percentage of total returning customer revenue. Analyze shipping cost composition for repeat buyers. Returning Customer Shipping % measures shipping revenue as a proportion of total revenue from returning customers. ## Formula **Returning Customer Shipping %** = **Returning Customer Shipping Revenue** ÷ **Returning Customer Total Revenue** × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | | [**Returning Customer Shipping Revenue**](/reference/metrics/orders/adjustments/returning-customer-shipping) | Shipping fees collected from returning customer orders | | [**Returning Customer Total Revenue**](/reference/metrics/orders/revenue/returning-customer-total-revenue) | Total revenue from returning customer orders | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store's returning customers generated **\$85,000** in total revenue with **\$4,250** in shipping fees. | Metric | Value | | ------------------- | -------- | | RC Shipping Revenue | \$4,250 | | RC Total Revenue | \$85,000 | | **RC Shipping %** | **5.0%** | *** ## How It Works This metric calculates the percentage of returning customer revenue attributable to shipping fees. It divides shipping revenue from returning customers by their total revenue, then multiplies by 100 to express as a percentage. *** ## When to Use | Scenario | Action | | --------------------------------------- | ------------------------------------------------------------------ | | Comparing RC vs NC shipping composition | Determine if returning customers pay different shipping rates | | Evaluating loyalty shipping perks | Measure impact of free/discounted shipping for repeat buyers | | Revenue mix analysis | Understand how shipping contributes to returning customer revenue | | Shipping policy optimization | Identify opportunities to adjust shipping thresholds for retention | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | ----------------------------------- | | [Returning Customer Shipping Revenue](/reference/metrics/orders/adjustments/returning-customer-shipping) | Numerator of this percentage | | [Returning Customer Total Revenue](/reference/metrics/orders/revenue/returning-customer-total-revenue) | Denominator of this percentage | | [New Customer Shipping %](/reference/metrics/orders/adjustments/new-customer-shipping-percent) | Comparable metric for new customers | | [Total Shipping Revenue](/reference/metrics/orders/adjustments/shipping-amount) | Overall shipping revenue | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Returning Customer Tax: Repeat Buyer Tax Collected Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/returning-customer-tax Track total sales tax collected from returning customer orders. Monitor repeat buyer tax liability and understand tax impact across customer segments. The total sales tax collected from returning customer orders. ## Formula **Returning Customer Tax Collected** = **SUM** ( Tax Amount ) **WHERE** customer\_type = returning\_customer ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------- | ------------------------------- | | [**Tax Collected**](/reference/metrics/orders/adjustments/tax) | Total tax collected from orders | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions#customer-type) | Filters to returning customers | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store collected **\$6,240 in taxes** from returning customer orders in Q1: | Month | RC Tax | RC Orders | Tax/Order | | -------- | ------- | --------- | --------- | | January | \$1,890 | 328 | \$5.76 | | February | \$2,120 | 364 | \$5.82 | | March | \$2,230 | 412 | \$5.41 | Consistent tax per order suggests stable order values from your repeat buyer segment. *** ## How It Works This metric sums all tax collected from orders placed by returning customers. A customer is classified as "returning" when they have at least one prior completed order in Shopify. Tax amounts reflect rates applied at checkout based on customer shipping address and product taxability. *** ## When to Use | Scenario | Action | | ------------------------- | ---------------------------------------------------------- | | Segment tax liability | Track tax owed from repeat buyer transactions | | Compare customer segments | Benchmark against new customer tax to understand mix | | Regional analysis | Break down by state to see where repeat buyers concentrate | | Retention program impact | Monitor how loyalty efforts affect taxable order volume | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------ | ----------------------------------------------- | | [Tax Collected](/reference/metrics/orders/adjustments/tax) | Total tax across all customer types | | [Returning Customer Tax %](/reference/metrics/orders/adjustments/returning-customer-tax-percent) | Tax as percentage of returning customer revenue | | [New Customer Tax](/reference/metrics/orders/adjustments/new-customer-tax) | Compare acquisition vs retention tax collected | | [Tax Per Order](/reference/metrics/orders/adjustments/tax-per-order) | Average tax per transaction | [See all Adjustment metrics →](/reference/metrics/orders/adjustments) # Returning Customer Tax Per Order: Average Tax on Repeat Purchases Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/returning-customer-tax-per-order Track average tax collected per returning customer order. Analyze tax liability on repeat purchases and compare retention economics across regions. Average tax amount collected per returning customer order. ## Formula **Returning Customer Tax Per Order** = **Returning Customer Tax Collected** ÷ **Returning Customer Order Count** ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [**Returning Customer Tax Collected**](/reference/metrics/orders/adjustments/returning-customer-tax) | Total tax collected from returning customer orders | | [**Returning Customer Order Count**](/reference/metrics/orders/counts/returning-customer-orders) | Total orders placed by returning customers | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store collected **\$4,320** in tax from **540 returning customer orders** in May: | Metric | Value | | ------------------------- | ---------- | | Returning Customer Tax | \$4,320 | | Returning Customer Orders | 540 | | **RC Tax Per Order** | **\$8.00** | *** ## How It Works This metric divides total tax collected from returning customers by their order count. Returning customers often purchase higher-value items, leading to higher per-order tax amounts. Compare against new customer tax to understand how buying patterns evolve after the first purchase. *** ## When to Use | Scenario | Action | | --------------------- | ------------------------------------------------------------------------ | | Retention economics | Factor tax into true cost of repeat orders for LTV calculations | | Regional segmentation | Identify which markets have higher tax burdens on loyal customers | | New vs. returning | Compare against new customer tax to spot purchasing evolution | | Pricing strategy | Understand how tax affects total order cost for price-sensitive segments | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------- | | [Tax Per Order](/reference/metrics/orders/adjustments/tax-per-order) | Average tax across all customer types—baseline comparison | | [New Customer Tax Per Order](/reference/metrics/orders/adjustments/new-customer-tax-per-order) | Compare new vs. returning customer tax behavior | | [Returning Customer Tax %](/reference/metrics/orders/adjustments/returning-customer-tax-percent) | Tax as a percentage of returning customer revenue | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Returning Customer Tax %: Tax Share of Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/returning-customer-tax-percent Track tax as a percentage of returning customer total revenue. Analyze tax burden distribution and monitor effective tax rates on repeat orders. The tax collected from returning customers expressed as a percentage of their total revenue. ## Formula **Returning Customer Tax %** = **Returning Customer Tax Collected** ÷ **Returning Customer Total Revenue** × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | [**Returning Customer Tax Collected**](/reference/metrics/orders/adjustments/returning-customer-tax) | Total tax collected from returning customer orders | | [**Returning Customer Total Revenue**](/reference/metrics/orders/revenue/returning-customer-total-revenue) | Total revenue generated by returning customer orders | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store collected **\$2,450** in tax from returning customers who generated **\$35,000** in total revenue: | Month | RC Tax | RC Revenue | RC Tax % | | -------- | ------- | ---------- | -------- | | January | \$2,450 | \$35,000 | 7.00% | | February | \$2,680 | \$38,200 | 7.02% | | March | \$2,310 | \$33,750 | 6.84% | *** ## How It Works This metric divides the tax collected from returning customers by their total revenue, then multiplies by 100. It reflects the effective tax rate applied to repeat customer orders. Geographic and product mix differences can cause this rate to vary over time. *** ## When to Use | Scenario | Action | | ------------------------- | ------------------------------------------------------------- | | Analyzing tax burden | Compare tax rates between new and returning customers | | Geographic pricing review | Identify if repeat buyers skew toward high or low tax regions | | Tax compliance monitoring | Track effective tax rate trends over time | | Margin analysis | Factor tax percentage into profitability calculations | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------- | --------------------------------- | | [Returning Customer Tax Collected](/reference/metrics/orders/adjustments/returning-customer-tax) | Numerator in this calculation | | [Returning Customer Tax Per Order](/reference/metrics/orders/adjustments/returning-customer-tax-per-order) | Tax divided by order count | | [New Customer Tax %](/reference/metrics/orders/adjustments/new-customer-tax-percent) | Same metric for first-time buyers | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Shipping Per Order: Average Shipping Fee Per Order Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/shipping-per-order Track average shipping fees collected per order. Calculate shipping revenue efficiency and optimize fulfillment pricing strategy. Shipping Per Order measures the average shipping fee collected per order, helping you understand shipping revenue efficiency. ## Formula **Shipping Per Order** = **Shipping Revenue** ÷ **Total Orders** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------ | -------------------------------------------------------------- | | [**Shipping Revenue**](/reference/metrics/orders/adjustments/shipping-revenue) | Total shipping fees collected from customers across all orders | | [**Total Orders**](/reference/metrics/orders/counts/total-orders) | Total number of orders placed in the selected period | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your store collected **\$8,160** in shipping fees across **1,500 orders** in March. | Metric | Value | Calculation | | ---------------------- | ---------- | ------------------------- | | Shipping Revenue | \$8,160 | Sum of all shipping fees | | Total Orders | 1,500 | Count of completed orders | | **Shipping Per Order** | **\$5.44** | \$8,160 ÷ 1,500 | *** ## How It Works Shipping Per Order divides total shipping fees collected by the number of orders. This average helps you understand how much shipping revenue you generate per transaction and whether your shipping pricing strategy aligns with fulfillment costs. *** ## When to Use | Scenario | Action | | --------------------------------- | ----------------------------------------------------- | | Evaluating shipping profitability | Compare against actual fulfillment costs per order | | Testing free shipping thresholds | Monitor impact when adjusting minimum order values | | Analyzing regional shipping costs | Segment by customer location to identify pricing gaps | | Benchmarking carrier performance | Compare shipping revenue vs carrier costs over time | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------- | --------------------------------------------------------------- | | [Shipping Revenue](/reference/metrics/orders/adjustments/shipping-revenue) | Numerator — total shipping fees collected | | [Total Orders](/reference/metrics/orders/counts/total-orders) | Denominator — order count for averaging | | [Average Order Value](/reference/metrics/orders/revenue/average-order-value) | Compare shipping per order to AOV for shipping-to-revenue ratio | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Shipping %: Share of Revenue from Shipping Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/shipping-percent Track shipping revenue as a percentage of total revenue. Monitor how free shipping promotions and thresholds affect your store's margins over time. Shipping % measures shipping revenue as a share of total revenue, helping you understand how free shipping promotions affect your margins. ## Formula **Shipping %** = **Shipping Revenue** ÷ **Total Revenue** × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------ | ---------------------------------------------------------- | | [**Shipping Revenue**](/reference/metrics/orders/adjustments/shipping-revenue) | Total shipping fees collected from customers | | [**Total Revenue**](/reference/metrics/orders/revenue/total-revenue) | Total revenue from all orders including shipping and taxes | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store generated **\$125,000** in total revenue last month, with **\$8,750** coming from shipping fees. | Period | Shipping Revenue | Total Revenue | Shipping % | | -------- | ---------------- | ------------- | ---------- | | January | \$8,750 | \$125,000 | 7.0% | | February | \$6,200 | \$130,000 | 4.8% | | March | \$4,500 | \$140,000 | 3.2% | *** ## How It Works Shipping % divides your shipping revenue by total revenue and multiplies by 100. A declining shipping percentage often indicates increased use of free shipping promotions or higher average order values that qualify for free shipping thresholds. *** ## When to Use | Scenario | Action | | ---------------------------------- | --------------------------------------------------------------------- | | Launching free shipping promotions | Track how promotions reduce shipping % and impact margins | | Analyzing margin trends | Compare shipping % across periods to understand profitability shifts | | Setting shipping thresholds | Evaluate if free shipping thresholds affect customer behavior | | Comparing customer segments | Check if new vs. returning customers have different shipping patterns | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------ | ----------------------------------------- | | [Shipping Revenue](/reference/metrics/orders/adjustments/shipping-revenue) | Numerator — total shipping fees collected | | [Shipping Per Order](/reference/metrics/orders/adjustments/shipping-per-order) | Average shipping per transaction | | [Discount %](/reference/metrics/orders/adjustments/discount-percent) | Similar percentage metric for discounts | | [Tax %](/reference/metrics/orders/adjustments/tax-percent) | Similar percentage metric for taxes | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Shipping Revenue: Total Shipping Fees Collected Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/shipping-revenue Track total shipping fees collected from customers. Monitor shipping revenue trends, offset fulfillment costs, and analyze free shipping promotion impact. Total shipping fees collected from customers across all orders in the selected period. ## Formula **Shipping Revenue** = **SUM** ( Shipping Fees ) ### Formula Components | Metric | Definition | | ----------------- | ------------------------------------------------------ | | **Shipping Fees** | Shipping charges collected at checkout from each order | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store collected **\$12,450 in shipping fees** during Q1: | Month | Shipping Revenue | Orders | Avg per Order | | -------- | ---------------- | ------ | ------------- | | January | \$4,850 | 892 | \$5.44 | | February | \$4,120 | 756 | \$5.45 | | March | \$3,480 | 945 | \$3.68 | March's decline reflects a free shipping promotion that increased order volume but reduced per-order shipping revenue. *** ## How It Works Shipping Revenue sums all shipping fees charged to customers at checkout across orders in the period. This includes flat-rate, weight-based, and calculated shipping. Free shipping orders contribute \$0 to this total. Use this metric to understand how much revenue you collect to offset fulfillment costs. *** ## When to Use | Scenario | Action | | ------------------------ | ---------------------------------------------------------- | | Calculate total revenue | Include shipping when computing total revenue collected | | Measure promotion impact | Track how free shipping thresholds affect shipping revenue | | Offset fulfillment costs | Compare shipping revenue to actual shipping costs | | Segment analysis | Compare shipping revenue from new vs returning customers | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------ | ------------------------------------------- | | [Shipping %](/reference/metrics/orders/adjustments/shipping-percent) | Shipping revenue as share of total revenue | | [Shipping Per Order](/reference/metrics/orders/adjustments/shipping-per-order) | Average shipping fee per order | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | Includes shipping, taxes, and product sales | | [Discount Amount](/reference/metrics/orders/adjustments/discount-amount) | Another order adjustment metric | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Tax Collected: Total Sales Tax Collected from Orders Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/tax Track total sales tax collected from customers. Monitor tax liability, understand regional tax impact, and reconcile tax remittance with Upstack. The total sales tax collected from customers across all orders. ## Formula **Tax Collected** = **SUM** ( Tax Amount ) ### Formula Components | Metric | Definition | | -------------- | ----------------------------------------------- | | **Tax Amount** | Sales tax collected at checkout from each order | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store collected **\$12,840 in sales tax** during Q1: | Month | Tax Collected | Orders | | -------- | ------------- | ------ | | January | \$3,920 | 784 | | February | \$4,160 | 832 | | March | \$4,760 | 952 | *** ## How It Works Tax Collected sums the sales tax collected from customers on all orders in the period. Tax is typically passed through to tax authorities and not retained as revenue. Rates vary by jurisdiction and product category, with some states collecting no sales tax. *** ## When to Use | Scenario | Action | | ---------------------------- | ---------------------------------------- | | Monitor tax liability | Track total tax owed to authorities | | Reconcile tax remittance | Verify collected tax matches filings | | Understand regional impact | Break down by state or country | | Calculate effective tax rate | Divide by Total Revenue for average rate | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------- | ---------------------------------- | | [Tax %](/reference/metrics/orders/adjustments/tax-percent) | Tax as percentage of total revenue | | [Tax Per Order](/reference/metrics/orders/adjustments/tax-per-order) | Average tax collected per order | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | Revenue before adjustments | | [Shipping Revenue](/reference/metrics/orders/adjustments/shipping-revenue) | Another pass-through component | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Tax Per Order: Average Tax Amount Per Transaction Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/tax-per-order Track the average tax amount collected per order from your Shopify store. Monitor tax burden by segment and reconcile collected taxes with reporting obligations. The average tax dollar amount collected per order. ## Formula **Tax Per Order** = **Tax Collected** ÷ **Total Orders** ### Formula Components | Metric | Definition | | -------------------------------------------------------------- | ---------------------------------------------------------- | | [**Tax Collected**](/reference/metrics/orders/adjustments/tax) | Total sales tax collected from customers across all orders | | [**Total Orders**](/reference/metrics/orders/counts/orders) | Total number of completed orders in the period | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store processed **2,450 orders** in April and collected **\$18,375 in taxes**: | Metric | Value | | ----------------- | ---------- | | Tax Collected | \$18,375 | | Order Count | 2,450 | | **Tax Per Order** | **\$7.50** | *** ## How It Works Tax Per Order divides total tax collected by all orders in the period. This average reflects the typical tax burden on each transaction, influenced by customer locations, product taxability, and order values. Use it to understand regional tax exposure and verify consistency with expected rates. *** ## When to Use | Scenario | Action | | -------------------- | -------------------------------------------------------------- | | Tax reconciliation | Compare to expected rates by region to catch collection errors | | Segment analysis | Identify customer segments with higher tax burdens | | Pricing strategy | Factor average tax into displayed pricing decisions | | Geographic expansion | Estimate tax impact when entering new jurisdictions | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------- | ----------------------------------------- | | [Tax Collected](/reference/metrics/orders/adjustments/tax) | Numerator: total tax collected | | [Total Orders](/reference/metrics/orders/counts/orders) | Denominator: transaction count | | [Tax %](/reference/metrics/orders/adjustments/tax-percent) | Tax as percentage of order value | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | Includes tax, shipping, and product sales | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Tax %: Sales Tax as Share of Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/adjustments/tax-percent Track sales tax collected as a percentage of total revenue. Estimate effective tax burden across markets and monitor tax compliance for your Shopify store. The percentage of total revenue that comes from sales tax collected. ## Formula **Tax %** = **Tax Collected** ÷ **Total Revenue** × 100 ### Formula Components | Metric | Definition | | -------------------------------------------------------------------- | ---------------------------------------------------------------------- | | [**Tax Collected**](/reference/metrics/orders/adjustments/tax) | Total sales tax collected from customers across all orders | | [**Total Revenue**](/reference/metrics/orders/revenue/total-revenue) | Total dollar amount collected from orders including shipping and taxes | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store collected **\$8,450** in sales tax from **\$105,625** in total revenue this month: | Region | Tax Collected | Total Revenue | Tax % | | ---------- | ------------- | ------------- | -------- | | California | \$5,200 | \$65,000 | 8.0% | | Texas | \$2,100 | \$26,250 | 8.0% | | Oregon | \$0 | \$14,375 | 0.0% | | **Total** | **\$8,450** | **\$105,625** | **8.0%** | *** ## How It Works Tax % divides total tax collected by total revenue and multiplies by 100. This shows what share of customer payments goes toward sales tax. It reflects weighted average tax rates across all orders and jurisdictions. *** ## When to Use | Scenario | Action | | ----------------------------- | ------------------------------------------------- | | Comparing regional tax burden | Identify markets with higher effective tax rates | | Estimating tax liability | Forecast sales tax obligations for planning | | Pricing strategy | Understand how tax affects customer-facing prices | | Compliance monitoring | Track tax collection trends over time | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------- | --------------------------------------- | | [Tax Collected](/reference/metrics/orders/adjustments/tax) | The numerator in this calculation | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | The denominator in this calculation | | [Tax Per Order](/reference/metrics/orders/adjustments/tax-per-order) | Average tax amount per individual order | [See all Adjustments metrics →](/reference/metrics/orders/adjustments) # Gross AOV: Average Order Value Before Discounts Source: https://docs.upstackdata.com/reference/metrics/orders/aov/gross-aov Track Gross AOV to measure your average order value before discounts and refunds — the baseline cart value customers intend to spend. Gross AOV measures your average gross product revenue per order before discounts and refunds are applied. ## Formula **Gross AOV** = [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) ÷ [**Orders**](/reference/metrics/orders/counts/orders) ### Formula Components | Metric | Definition | | -------------------------------------------------------------------- | ------------------------------------------------------------------ | | [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) | Revenue from product sales before subtracting discounts or refunds | | [**Orders**](/reference/metrics/orders/counts/orders) | Total number of completed orders placed | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store processed **1,247 orders** in January with **\$143,410** in gross revenue: | Metric | Value | | ------------- | ------------ | | Gross Revenue | \$143,410 | | Orders | 1,247 | | **Gross AOV** | **\$115.00** | *** ## How It Works Gross AOV divides your total gross product revenue by order count. Unlike [Net AOV](/reference/metrics/orders/aov/net-aov), it shows what customers add to cart before any discounts or refunds are applied — giving you the baseline cart value customers intend to spend. *** ## When to Use | Scenario | Action | | ------------------------------ | ------------------------------------------------------------------------------------------------------ | | Measuring baseline cart value | Compare to [Net AOV](/reference/metrics/orders/aov/net-aov) to see discount impact on transaction size | | Evaluating product pricing | Track Gross AOV to understand cart composition before promotions | | Analyzing bundle effectiveness | Higher Gross AOV indicates successful cross-sell and upsell | | Setting discount thresholds | Use Gross AOV to determine minimum order amounts for promotions | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------ | ---------------------------------------------- | | [Net AOV](/reference/metrics/orders/aov/net-aov) | AOV after discounts and refunds | | [Total AOV](/reference/metrics/orders/aov/total-aov) | AOV including shipping and taxes | | [Gross Revenue](/reference/metrics/orders/revenue/gross-revenue) | Numerator — product revenue before adjustments | | [New Customer Gross AOV](/reference/metrics/orders/aov/new-customer-gross-aov) | Gross AOV for first-time buyers | [See all AOV metrics →](/reference/metrics/orders/aov) # Average Order Value: Track AOV by Revenue Type Source: https://docs.upstackdata.com/reference/metrics/orders/aov/index Track AOV metrics in Upstack. Includes Total AOV, Gross AOV, Net AOV by customer type with formulas and optimization tips. Average Order Value (AOV) metrics measure the average revenue per order at different calculation levels. Use these to optimize cart value and compare customer segments. **Data Source:** [Shopify](/sources/shopify)\ **Metrics:** 9 ## Metrics in This Group | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------ | --------------------------------------- | ------------------------------ | | [Total AOV](/reference/metrics/orders/aov/total-aov) | Average order value using total revenue | Headline AOV reporting | | [Gross AOV](/reference/metrics/orders/aov/gross-aov) | Average order value using gross revenue | Full-price basket analysis | | [Net AOV](/reference/metrics/orders/aov/net-aov) | Average order value using net revenue | Actual collection per order | | [New Customer Total AOV](/reference/metrics/orders/aov/new-customer-total-aov) | Total AOV for new customers | Benchmark new customer baskets | | [New Customer Gross AOV](/reference/metrics/orders/aov/new-customer-gross-aov) | Gross AOV for new customers | New customer full-price demand | | [New Customer Net AOV](/reference/metrics/orders/aov/new-customer-net-aov) | Net AOV for new customers | Actual new customer value | | [Returning Customer Total AOV](/reference/metrics/orders/aov/returning-customer-total-aov) | Total AOV for returning customers | Track loyalty basket growth | | [Returning Customer Gross AOV](/reference/metrics/orders/aov/returning-customer-gross-aov) | Gross AOV for returning customers | Returning customer demand | | [Returning Customer Net AOV](/reference/metrics/orders/aov/returning-customer-net-aov) | Net AOV for returning customers | Returning customer collections | ## How These Metrics Relate AOV metrics are calculated as Revenue ÷ Orders: * **Total AOV** = Total Revenue ÷ Orders * **Gross AOV** = Gross Revenue ÷ Orders * **Net AOV** = Net Revenue ÷ Orders Each variant is segmented by New Customer and Returning Customer for comparison. ## Choosing the Right Metric * **Headline reporting**: Use Total AOV for general reporting * **Discount impact**: Compare Gross AOV vs Net AOV to see discount effect * **Customer comparison**: Compare New Customer AOV vs Returning Customer AOV * **Upsell optimization**: Track Net AOV to measure actual value optimization # Net AOV: Average Order Value After Discounts Source: https://docs.upstackdata.com/reference/metrics/orders/aov/net-aov Track Net AOV to measure your average order value after discounts and refunds — the most reliable AOV for profitability and ROAS calculations. Net AOV measures your average net revenue per order after discounts and refunds have been applied. ## Formula **Net AOV** = [**Net Revenue**](/reference/metrics/orders/revenue/net-revenue) ÷ [**Orders**](/reference/metrics/orders/counts/orders) ### Formula Components | Metric | Definition | | ---------------------------------------------------------------- | ------------------------------------------------------------------ | | [**Net Revenue**](/reference/metrics/orders/revenue/net-revenue) | Revenue after subtracting discounts and refunds from gross revenue | | [**Orders**](/reference/metrics/orders/counts/orders) | Total number of completed orders placed | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store processed **1,247 orders** in January with **\$124,700** in net revenue: | Metric | Value | | ----------- | ------------ | | Net Revenue | \$124,700 | | Orders | 1,247 | | **Net AOV** | **\$100.00** | *** ## How It Works Net AOV divides net revenue by order count. Unlike [Gross AOV](/reference/metrics/orders/aov/gross-aov), it reflects actual retained revenue after discounts and refunds — the most accurate AOV for profitability and ROAS calculations. *** ## When to Use | Scenario | Action | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Profitability analysis | Use Net AOV for accurate margin and contribution calculations | | ROAS calculations | Pair with ad spend for true return on investment | | Evaluating promotions | Compare Net vs [Gross AOV](/reference/metrics/orders/aov/gross-aov) to see discount impact | | Customer segmentation | Compare [New Customer Net AOV](/reference/metrics/orders/aov/new-customer-net-aov) vs [Returning Customer Net AOV](/reference/metrics/orders/aov/returning-customer-net-aov) | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------- | ------------------------------------- | | [Gross AOV](/reference/metrics/orders/aov/gross-aov) | AOV before discounts and refunds | | [Total AOV](/reference/metrics/orders/aov/total-aov) | AOV including shipping and taxes | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Numerator — revenue after adjustments | | [New Customer Net AOV](/reference/metrics/orders/aov/new-customer-net-aov) | Net AOV for first-time buyers | [See all AOV metrics →](/reference/metrics/orders/aov) # New Customer Gross AOV: First-Time Buyer Baseline Cart Value Source: https://docs.upstackdata.com/reference/metrics/orders/aov/new-customer-gross-aov Track average gross revenue per order for new customers before discounts and refunds. Understand your first-time buyer baseline cart value. Average gross revenue per order for new customers before discounts and refunds. ## Formula **New Customer Gross AOV** = [**New Customer Gross Revenue**](/reference/metrics/orders/revenue/new-customer-gross-revenue) ÷ [**New Customers**](/reference/metrics/orders/customers/new-customers) ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | [**New Customer Gross Revenue**](/reference/metrics/orders/revenue/new-customer-gross-revenue) | Revenue from first-time buyers before discounts or refunds | | [**New Customers**](/reference/metrics/orders/customers/new-customers) | Count of distinct first-time buyers in the period | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your store acquired **125 new customers** this month with **\$18,750** in gross revenue: | Metric | Value | | ---------------- | ------------ | | NC Gross Revenue | \$18,750 | | New Customers | 125 | | **NC Gross AOV** | **\$150.00** | *** ## How It Works New Customer Gross AOV divides total gross revenue from first-time buyers by the number of [new customers](/reference/metrics/orders/customers/new-customers). Gross revenue includes the full order amount before discounts, returns, or refunds are applied — giving you the "list price" view of new customer order value. *** ## When to Use | Scenario | Action | | -------------------------------- | -------------------------------------------------------------------------------------------------------- | | Evaluating acquisition campaigns | Measure if new customers are purchasing at target values | | Setting discount limits | Ensure acquisition discounts don't erode profitability | | Comparing customer segments | Contrast with [Returning Customer Gross AOV](/reference/metrics/orders/aov/returning-customer-gross-aov) | | Planning CAC targets | Use AOV to set acceptable customer acquisition costs | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------ | ----------------------------------------- | | [New Customer Net AOV](/reference/metrics/orders/aov/new-customer-net-aov) | After discounts/refunds (actual received) | | [Returning Customer Gross AOV](/reference/metrics/orders/aov/returning-customer-gross-aov) | Same metric for repeat buyers | | [Gross AOV](/reference/metrics/orders/aov/gross-aov) | All customers combined (gross) | | [New Customer Gross Revenue](/reference/metrics/orders/revenue/new-customer-gross-revenue) | The numerator in this formula | [See all AOV metrics →](/reference/metrics/orders/aov) # New Customer Net AOV: First-Time Buyer Actual Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/aov/new-customer-net-aov Track average order value for first-time buyers after discounts and refunds. Key input for payback calculations and acquisition efficiency analysis. Average net revenue per order for first-time buyers after discounts and refunds. ## Formula **New Customer Net AOV** = [**New Customer Net Revenue**](/reference/metrics/orders/revenue/new-customer-net-revenue) ÷ [**New Customers**](/reference/metrics/orders/customers/new-customers) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------- | | [**New Customer Net Revenue**](/reference/metrics/orders/revenue/new-customer-net-revenue) | Revenue from first-time buyers after discounts and refunds | | [**New Customers**](/reference/metrics/orders/customers/new-customers) | Count of distinct first-time buyers in the period | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your store acquired **385 new customers** in March with **\$32,340** in net revenue: | Metric | Value | | -------------- | ----------- | | NC Net Revenue | \$32,340 | | New Customers | 385 | | **NC Net AOV** | **\$84.00** | Compared to a [Gross AOV](/reference/metrics/orders/aov/new-customer-gross-aov) of \$98.50, discounts reduced the average order by 15%. *** ## How It Works Divides first-time buyer net revenue (after discounts and refunds) by [new customer](/reference/metrics/orders/customers/new-customers) count. This gives the clearest measure of actual revenue collected per first order. *** ## When to Use | Scenario | Action | | ------------------------ | ------------------------------------------------------------------------------------ | | Calculate payback period | Divide CAC by NC Net AOV | | Measure promotion impact | Compare against [NC Gross AOV](/reference/metrics/orders/aov/new-customer-gross-aov) | | Set CM1 targets | Use as revenue base for margin calculations | | Benchmark acquisition | Compare NC vs [RC Net AOV](/reference/metrics/orders/aov/returning-customer-net-aov) | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------- | ------------------------------------- | | [New Customer Net Revenue](/reference/metrics/orders/revenue/new-customer-net-revenue) | Numerator of this metric | | [New Customer Total AOV](/reference/metrics/orders/aov/new-customer-total-aov) | Same segment, includes shipping/taxes | | [Returning Customer Net AOV](/reference/metrics/orders/aov/returning-customer-net-aov) | Retention counterpart | | [New Customer Gross AOV](/reference/metrics/orders/aov/new-customer-gross-aov) | Before discounts and refunds | [See all AOV metrics →](/reference/metrics/orders/aov) # New Customer Total AOV: First-Time Buyer Average Order Value Source: https://docs.upstackdata.com/reference/metrics/orders/aov/new-customer-total-aov Track average order value for first-time buyers including shipping and taxes. Compare against returning customers to benchmark acquisition basket size. The average total transaction value for first-time buyers, including shipping and taxes. ## Formula **New Customer Total AOV** = [**New Customer Total Revenue**](/reference/metrics/orders/revenue/new-customer-total-revenue) ÷ [**New Customers**](/reference/metrics/orders/customers/new-customers) ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | [**New Customer Total Revenue**](/reference/metrics/orders/revenue/new-customer-total-revenue) | Sum of all revenue from first-time buyers including shipping and taxes | | [**New Customers**](/reference/metrics/orders/customers/new-customers) | Count of distinct first-time buyers in the period | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your store acquired **412 new customers** in February with **\$48,620** in total revenue: | Metric | Value | | ---------------- | ------------ | | NC Total Revenue | \$48,620 | | New Customers | 412 | | **NC Total AOV** | **\$118.01** | *** ## How It Works New Customer Total AOV divides your first-time buyer revenue (including shipping and taxes) by the number of [new customers](/reference/metrics/orders/customers/new-customers). Shopify determines new vs returning status based on email address match against prior orders. *** ## When to Use | Scenario | Action | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | Benchmark acquisition baskets | Compare NC Total AOV against [RC Total AOV](/reference/metrics/orders/aov/returning-customer-total-aov) to see if new customers spend more or less | | Evaluate first-order promotions | Track whether welcome offers attract larger or smaller baskets | | Calculate acquisition ROAS | Combine with ad spend to measure first-order efficiency | | Set free shipping thresholds | Position threshold above NC AOV to encourage larger carts | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------ | -------------------------------------------- | | [Total AOV](/reference/metrics/orders/aov/total-aov) | All customers combined (NC + RC) | | [Returning Customer Total AOV](/reference/metrics/orders/aov/returning-customer-total-aov) | The retention counterpart to compare against | | [New Customer Total Revenue](/reference/metrics/orders/revenue/new-customer-total-revenue) | The numerator of this metric | | [New Customer Net AOV](/reference/metrics/orders/aov/new-customer-net-aov) | Same segment, after discounts and refunds | [See all AOV metrics →](/reference/metrics/orders/aov) # Returning Customer Gross AOV: Repeat Buyer Baseline Cart Value Source: https://docs.upstackdata.com/reference/metrics/orders/aov/returning-customer-gross-aov Track average gross revenue per order for returning customers before discounts and refunds. Measure repeat buyer basket value to optimize retention. Average gross revenue per order for returning customers before discounts and refunds. ## Formula **Returning Customer Gross AOV** = [**Returning Customer Gross Revenue**](/reference/metrics/orders/revenue/returning-customer-gross-revenue) ÷ [**Returning Customers**](/reference/metrics/orders/customers/returning-customers) ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | [**Returning Customer Gross Revenue**](/reference/metrics/orders/revenue/returning-customer-gross-revenue) | Revenue from repeat buyers before discounts or refunds | | [**Returning Customers**](/reference/metrics/orders/customers/returning-customers) | Count of distinct customers with at least one prior purchase | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your store processed **847 returning customer orders** this month with **\$101,640** in gross revenue: | Metric | Value | | ------------------- | ------------ | | RC Gross Revenue | \$101,640 | | Returning Customers | 847 | | **RC Gross AOV** | **\$120.00** | *** ## How It Works Returning Customer Gross AOV divides total gross revenue from repeat buyers by the number of [returning customers](/reference/metrics/orders/customers/returning-customers). Gross revenue includes the full order amount before discounts, returns, or refunds are applied. This metric typically exceeds [new customer AOV](/reference/metrics/orders/aov/new-customer-gross-aov) as loyal customers tend to purchase more per order. *** ## When to Use | Scenario | Action | | --------------------------- | -------------------------------------------------------------------------------------------- | | Measuring loyalty impact | Track whether repeat buyers increase basket size over time | | Optimizing retention offers | Ensure loyalty discounts don't erode order value | | Comparing customer segments | Contrast with [New Customer Gross AOV](/reference/metrics/orders/aov/new-customer-gross-aov) | | Planning LTV projections | Use RC AOV to forecast customer lifetime value | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | ----------------------------------------- | | [Returning Customer Net AOV](/reference/metrics/orders/aov/returning-customer-net-aov) | After discounts/refunds (actual received) | | [New Customer Gross AOV](/reference/metrics/orders/aov/new-customer-gross-aov) | Same metric for first-time buyers | | [Gross AOV](/reference/metrics/orders/aov/gross-aov) | All customers combined (gross) | | [Returning Customer Gross Revenue](/reference/metrics/orders/revenue/returning-customer-gross-revenue) | The numerator in this formula | [See all AOV metrics →](/reference/metrics/orders/aov) # Returning Customer Net AOV: Repeat Buyer Actual Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/aov/returning-customer-net-aov Track average net revenue per order from returning customers after discounts and refunds. Essential for retention strategy and LTV calculations. Average net revenue per order from returning customers, after discounts and refunds. ## Formula **Returning Customer Net AOV** = [**Returning Customer Net Revenue**](/reference/metrics/orders/revenue/returning-customer-net-revenue) ÷ [**Returning Customers**](/reference/metrics/orders/customers/returning-customers) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | | [**Returning Customer Net Revenue**](/reference/metrics/orders/revenue/returning-customer-net-revenue) | Revenue from repeat buyers after discounts and refunds | | [**Returning Customers**](/reference/metrics/orders/customers/returning-customers) | Count of distinct customers with at least one prior purchase | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your store's returning customers placed **1,200 orders** in March with **\$111,000** in net revenue: | Customer Segment | Net AOV | Orders | Net Revenue | | ------------------- | ------- | ------ | ----------- | | Returning Customers | \$92.50 | 1,200 | \$111,000 | | New Customers | \$78.25 | 800 | \$62,600 | Returning customers spend **18% more** per order than [new customers](/reference/metrics/orders/aov/new-customer-net-aov). *** ## How It Works Net AOV divides total net revenue by [returning customer](/reference/metrics/orders/customers/returning-customers) count. Net revenue excludes discounts and refunds, giving you the actual realized value per repeat purchase. This metric isolates the spending behavior of your existing customer base. *** ## When to Use | Scenario | Action | | ------------------------- | ----------------------------------------------------------------------------------------------------------------- | | Measuring retention value | Compare RC Net AOV to [NC Net AOV](/reference/metrics/orders/aov/new-customer-net-aov) to quantify loyalty impact | | LTV projections | Use as baseline for expected repeat purchase value | | Promotion effectiveness | Check if loyalty discounts compress net AOV too much | | Segment profitability | Pair with RC order count to calculate repeat revenue contribution | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | -------------------------------------- | | [Net AOV](/reference/metrics/orders/aov/net-aov) | All-customer average (blended NC + RC) | | [New Customer Net AOV](/reference/metrics/orders/aov/new-customer-net-aov) | First-purchase comparison | | [Returning Customer Gross AOV](/reference/metrics/orders/aov/returning-customer-gross-aov) | Before discounts and refunds | | [Returning Customer Net Revenue](/reference/metrics/orders/revenue/returning-customer-net-revenue) | Numerator for this calculation | [See all AOV metrics →](/reference/metrics/orders/aov) # Returning Customer Total AOV: Repeat Buyer Average Order Value Source: https://docs.upstackdata.com/reference/metrics/orders/aov/returning-customer-total-aov Track average order value for returning customers including shipping and taxes. Compare against new customers to measure loyalty-driven basket growth. The average total transaction value for returning buyers, including shipping and taxes. ## Formula **Returning Customer Total AOV** = [**Returning Customer Total Revenue**](/reference/metrics/orders/revenue/returning-customer-total-revenue) ÷ [**Returning Customers**](/reference/metrics/orders/customers/returning-customers) ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | [**Returning Customer Total Revenue**](/reference/metrics/orders/revenue/returning-customer-total-revenue) | Sum of all revenue from repeat buyers including shipping and taxes | | [**Returning Customers**](/reference/metrics/orders/customers/returning-customers) | Count of distinct customers with at least one prior purchase | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your store had **837 returning customers** in March with **\$112,450** in total revenue: | Metric | Value | | ------------------- | ------------ | | RC Total Revenue | \$112,450 | | Returning Customers | 837 | | **RC Total AOV** | **\$134.35** | *** ## How It Works Returning Customer Total AOV divides your repeat buyer revenue (including shipping and taxes) by the number of [returning customers](/reference/metrics/orders/customers/returning-customers). Shopify determines returning status when a customer's email matches a previous order. *** ## When to Use | Scenario | Action | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Measure loyalty impact | Compare RC Total AOV against [NC Total AOV](/reference/metrics/orders/aov/new-customer-total-aov) — returning customers typically spend 15-25% more | | Evaluate retention programs | Track whether loyalty rewards or subscriptions increase basket size | | Calculate retention value | Combine with purchase frequency to estimate repeat buyer contribution | | Optimize upsell strategies | Target returning customers with higher-value product recommendations | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | | [Total AOV](/reference/metrics/orders/aov/total-aov) | All customers combined (NC + RC) | | [New Customer Total AOV](/reference/metrics/orders/aov/new-customer-total-aov) | The acquisition counterpart to compare against | | [Returning Customer Total Revenue](/reference/metrics/orders/revenue/returning-customer-total-revenue) | The numerator of this metric | | [Returning Customer Net AOV](/reference/metrics/orders/aov/returning-customer-net-aov) | Same segment, after discounts and refunds | [See all AOV metrics →](/reference/metrics/orders/aov) # Total AOV: Average Order Value Including Shipping & Taxes Source: https://docs.upstackdata.com/reference/metrics/orders/aov/total-aov Track average order value including shipping and taxes from your Shopify orders. Learn the formula, see examples, and optimize transaction size. The average total revenue collected per order, including shipping and taxes. ## Formula **Total AOV** = [**Total Revenue**](/reference/metrics/orders/revenue/total-revenue) ÷ [**Orders**](/reference/metrics/orders/counts/orders) ### Formula Components | Metric | Definition | | -------------------------------------------------------------------- | ----------------------------------------------------------- | | [**Total Revenue**](/reference/metrics/orders/revenue/total-revenue) | Sum of all revenue from orders including shipping and taxes | | [**Orders**](/reference/metrics/orders/counts/orders) | Total number of completed orders placed | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your store processed **1,247 orders** in January with **\$156,820** in total revenue: | Metric | Value | | ------------- | ------------ | | Total Revenue | \$156,820 | | Orders | 1,247 | | **Total AOV** | **\$125.76** | *** ## How It Works Total AOV divides your total revenue (including shipping charges and taxes) by the number of orders. This gives you the complete average transaction size, reflecting what customers actually pay at checkout rather than just product value. *** ## When to Use | Scenario | Action | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Measuring checkout value | Compare against [Gross AOV](/reference/metrics/orders/aov/gross-aov) or [Net AOV](/reference/metrics/orders/aov/net-aov) to see shipping/tax impact | | Setting free shipping thresholds | Set threshold above Total AOV to encourage larger carts | | Evaluating upsell strategies | Track Total AOV lift from bundles or recommended products | | Comparing customer segments | Compare [New Customer Total AOV](/reference/metrics/orders/aov/new-customer-total-aov) vs [Returning Customer Total AOV](/reference/metrics/orders/aov/returning-customer-total-aov) | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------ | ---------------------------------------------- | | [Gross AOV](/reference/metrics/orders/aov/gross-aov) | Product revenue only (excludes shipping/taxes) | | [Net AOV](/reference/metrics/orders/aov/net-aov) | After discounts and refunds | | [New Customer Total AOV](/reference/metrics/orders/aov/new-customer-total-aov) | Total AOV for first-time buyers | | [Returning Customer Total AOV](/reference/metrics/orders/aov/returning-customer-total-aov) | Total AOV for repeat customers | [See all AOV metrics →](/reference/metrics/orders/aov) # COGS: Cost of Goods Sold for All Orders Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/cogs Track your total cost of goods sold from Shopify orders. Use COGS to calculate gross profit, gross margin, and product-level profitability. The total cost of products sold, including manufacturing or purchase costs. ## Formula **COGS** = **SUM** ( Product Cost × Quantity ) ### Formula Components | Metric | Definition | | ---------------- | --------------------------------------- | | **Product Cost** | Cost per unit from Shopify variant data | | **Quantity** | Number of units sold per line item | | Metadata | | | --------------- | ----------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Sum | *** ## Example Your store sold **\$125,000** in January with **\$47,500** in product costs: | Metric | Value | | ------------ | --------- | | Net Revenue | \$125,000 | | COGS | \$47,500 | | Gross Profit | \$77,500 | | Gross Margin | 62% | *** ## How It Works COGS sums the cost-per-item values from your Shopify product variants multiplied by units sold. If product costs aren't set in Shopify, those items contribute \$0 to COGS. You can also override COGS in Upstack Cost Settings (e.g., "10% of net revenue"). *** ## When to Use | Scenario | Action | | ------------------------ | ------------------------------------------- | | Calculating gross profit | Subtract COGS from Net Revenue | | Setting pricing | Ensure prices cover COGS plus target margin | | Comparing product lines | Identify high-cost vs low-cost products | | Evaluating suppliers | Track cost changes over time | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------- | ----------------------------------- | | [COGS Per Order](/reference/metrics/orders/cogs/cogs-per-order) | Average product cost per order | | [New Customer COGS](/reference/metrics/orders/cogs/new-customer-cogs) | COGS from first-time buyers only | | [Returning Customer COGS](/reference/metrics/orders/cogs/returning-customer-cogs) | COGS from repeat buyers only | | [Gross Profit](/reference/metrics/orders/contribution-margin/gross-profit) | Net Revenue minus COGS | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Revenue used in margin calculations | [See all COGS metrics →](/reference/metrics/orders/cogs) # COGS Gross Rate: Cost of Goods as % of Gross Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/cogs-gross-rate Track COGS as a percentage of gross revenue. The inverse of gross margin—COGS Gross Rate + Gross Margin = 100%. Analyze product cost structure. Cost of goods sold as a percentage of gross revenue—the complement of gross margin rate. ## Formula **COGS Gross Rate** = ( [**COGS**](/reference/metrics/orders/cogs/cogs) ÷ [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) ) × 100 ### Formula Components | Metric | Definition | | -------------------------------------------------------------------- | --------------------------------------------- | | [**COGS**](/reference/metrics/orders/cogs/cogs) | Total cost of products sold across all orders | | [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) | Total revenue before discounts and refunds | | Metadata | | | --------------- | ----------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Ratio | *** ## Example Your store generated **\$185,000** in gross revenue with **\$68,450** in product costs this quarter: | Metric | Value | | ------------------- | --------- | | Gross Revenue | \$185,000 | | COGS | \$68,450 | | **COGS Gross Rate** | **37.0%** | This means 37% of your top-line revenue goes toward product costs, leaving 63% gross margin. *** ## How It Works This metric divides total COGS by gross revenue, then multiplies by 100. COGS Gross Rate + Gross Margin Rate always equals 100%. A lower rate indicates higher product margins, while increases suggest rising supply costs or a shift toward lower-margin products. *** ## When to Use | Scenario | Action | | --------------------- | --------------------------------------------- | | Quick margin check | Subtract from 100% to find gross margin | | Supplier negotiations | Monitor impact of cost changes on margin | | Product mix analysis | Track if sales shift toward higher-cost items | | Period comparison | Compare cost structure across months/quarters | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------- | ------------------------------- | | [COGS](/reference/metrics/orders/cogs/cogs) | Dollar value used in numerator | | [Gross Revenue](/reference/metrics/orders/revenue/gross-revenue) | Revenue baseline in denominator | | [New Customer COGS Gross Rate](/reference/metrics/orders/cogs/new-customer-cogs-gross-rate) | First-time buyer cost structure | | [Returning Customer COGS Gross Rate](/reference/metrics/orders/cogs/returning-customer-cogs-gross-rate) | Repeat buyer cost structure | | [Gross Profit](/reference/metrics/orders/contribution-margin/gross-profit) | Revenue minus COGS | [See all COGS metrics →](/reference/metrics/orders/cogs) # COGS Net Rate: Product Cost as % of Net Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/cogs-net-rate Measure what percentage of net revenue goes to product costs. Track cost efficiency after discounts and refunds with formula and examples. COGS as a percentage of net revenue—higher than gross rate because discounts and refunds reduce the denominator. ## Formula **COGS Net Rate** = ( [**COGS**](/reference/metrics/orders/cogs/cogs) ÷ [**Net Revenue**](/reference/metrics/orders/revenue/net-revenue) ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------- | ----------------------------------- | | [**COGS**](/reference/metrics/orders/cogs/cogs) | Total cost of products sold | | [**Net Revenue**](/reference/metrics/orders/revenue/net-revenue) | Revenue after discounts and refunds | | Metadata | | | --------------- | ----------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Ratio | *** ## Example Your store generated **\$125,000** in net revenue with **\$47,500** in product costs this month: | Metric | Value | | ----------------- | --------- | | Net Revenue | \$125,000 | | COGS | \$47,500 | | **COGS Net Rate** | **38.0%** | This means 38% of your retained revenue goes toward product costs, leaving 62% gross margin on net revenue. *** ## How It Works Divides total COGS by net revenue (after discounts and refunds), then multiplies by 100. This rate is higher than the gross rate because discounts and refunds reduce the denominator. A lower percentage indicates better margin retention after adjustments. *** ## When to Use | Scenario | Action | | ------------------- | ------------------------------------------------------------- | | True profitability | Use after-adjustment baseline for margin analysis | | Discount impact | Compare to gross rate to see how discounts affect cost ratios | | Margin benchmarking | Track trends to ensure costs don't outpace net revenue | | Segment comparison | Compare against NC and RC rates for customer-type insights | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------- | ------------------------------- | | [COGS](/reference/metrics/orders/cogs/cogs) | Dollar value used in numerator | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Revenue baseline in denominator | | [New Customer COGS Net Rate](/reference/metrics/orders/cogs/new-customer-cogs-net-rate) | First-time buyer segment | | [Returning Customer COGS Net Rate](/reference/metrics/orders/cogs/returning-customer-cogs-net-rate) | Repeat buyer segment | [See all COGS metrics →](/reference/metrics/orders/cogs) # COGS Per Order: Average Product Cost Per Order Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/cogs-per-order Track average cost of goods sold per order. Understand your per-order cost structure for pricing and profitability analysis. Average product cost per order—useful for understanding the cost structure of a typical transaction. ## Formula **COGS Per Order** = [**COGS**](/reference/metrics/orders/cogs/cogs) ÷ [**Total Orders**](/reference/metrics/orders/counts/total-orders) ### Formula Components | Metric | Definition | | ----------------------------------------------------------------- | --------------------------- | | [**COGS**](/reference/metrics/orders/cogs/cogs) | Total cost of products sold | | [**Total Orders**](/reference/metrics/orders/counts/total-orders) | Number of orders placed | | Metadata | | | --------------- | ----------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Ratio | *** ## Example Your store had **\$47,500** in COGS across **1,250** orders this month: | Metric | Value | | ------------------ | ----------- | | COGS | \$47,500 | | Total Orders | 1,250 | | **COGS Per Order** | **\$38.00** | *** ## How It Works Divides total COGS by the number of orders to calculate the average product cost per transaction. This metric helps you understand how much of each order's value goes to product costs, enabling better pricing and margin decisions. *** ## When to Use | Scenario | Action | | ----------------- | --------------------------------------------------- | | Pricing decisions | Ensure AOV covers COGS per order plus target margin | | Unit economics | Calculate per-order profit contribution | | Segment analysis | Compare to NC and RC COGS per order | | Cost monitoring | Track if product costs per transaction are rising | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------- | ------------------------------------ | | [COGS](/reference/metrics/orders/cogs/cogs) | Total product costs (numerator) | | [Total Orders](/reference/metrics/orders/counts/total-orders) | Order count (denominator) | | [New Customer COGS Per Order](/reference/metrics/orders/cogs/new-customer-cogs-per-order) | First-time buyer average | | [Returning Customer COGS Per Order](/reference/metrics/orders/cogs/returning-customer-cogs-per-order) | Repeat buyer average | | [Net AOV](/reference/metrics/orders/aov/net-aov) | Revenue per order to compare against | [See all COGS metrics →](/reference/metrics/orders/cogs) # Cost of Goods Sold: Track Product and Variable Costs Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/index Track COGS metrics in Upstack. Includes COGS, Variable Costs, Other Costs by customer type with formulas and margin analysis. Cost of Goods Sold (COGS) metrics track the direct costs of products sold. Use these to calculate gross profit margins and understand cost structures. **Data Source:** [Shopify](/sources/shopify)\ **Metrics:** 22 ## Metrics in This Group | Metric | Description | When to Use | | ----------------------------------------------------------------------------------------------------- | ---------------------------------- | ---------------------------- | | [COGS](/reference/metrics/orders/cogs/cogs) | Cost of goods sold | Calculate gross profit | | [New Customer COGS](/reference/metrics/orders/cogs/new-customer-cogs) | COGS for new customer orders | Segment cost analysis | | [Returning Customer COGS](/reference/metrics/orders/cogs/returning-customer-cogs) | COGS for returning customer orders | Compare customer segments | | [COGS Per Order](/reference/metrics/orders/cogs/cogs-per-order) | Average COGS per order | Benchmark order costs | | [New Customer COGS Per Order](/reference/metrics/orders/cogs/new-customer-cogs-per-order) | COGS per new customer order | New customer profitability | | [New Customer COGS Gross Rate](/reference/metrics/orders/cogs/new-customer-cogs-gross-rate) | COGS as % of NC gross revenue | New customer margin analysis | | [Returning Customer COGS Per Order](/reference/metrics/orders/cogs/returning-customer-cogs-per-order) | COGS per returning customer order | Returning customer margins | | [Other Cost](/reference/metrics/orders/cogs/other-cost) | Additional product costs | Track miscellaneous costs | | [Other Cost Per Order](/reference/metrics/orders/cogs/other-cost-per-order) | Average other cost per order | Per-order analysis | | [Other Cost %](/reference/metrics/orders/cogs/other-cost-percent) | Other cost as % of revenue | Cost proportion | | [Variable Costs](/reference/metrics/orders/cogs/variable-costs) | Total variable costs | Unit economics | | [Variable Costs Per Order](/reference/metrics/orders/cogs/variable-costs-per-order) | Variable cost per order | Per-order economics | | [Variable Costs %](/reference/metrics/orders/cogs/variable-costs-percent) | Variable costs as % of revenue | Cost structure | | [COGS Gross Rate](/reference/metrics/orders/cogs/cogs-gross-rate) | COGS as % of gross revenue | Gross margin inverse | | [COGS Net Rate](/reference/metrics/orders/cogs/cogs-net-rate) | COGS as % of net revenue | Net margin analysis | ## How These Metrics Relate COGS metrics build the foundation for margin analysis: * **Gross Profit** = Revenue - COGS * **COGS Rate** = COGS ÷ Revenue (inverse of gross margin) * **Variable Costs** include COGS + fulfillment + transaction costs * **CM1** = Revenue - COGS (first contribution margin level) ## Choosing the Right Metric * **Margin analysis**: Use COGS and COGS Rate to calculate gross margins * **Per-order economics**: Use COGS Per Order for unit economics * **Customer profitability**: Compare New vs Returning COGS to find profitable segments * **Cost structure**: Use Variable Costs % to understand total variable burden # New Customer COGS: Cost of Goods for First-Time Buyers Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/new-customer-cogs Track cost of goods sold for new customer orders. Calculate first-order gross margin and analyze acquisition cost structure by customer type. Cost of goods sold for orders placed by new customers—used to calculate new customer gross margin. ## Formula **New Customer COGS** = **SUM** ( Product Cost ) **WHERE** [customer\_type = new\_customer](/data-dictionary/measures-and-dimensions#customer-type) ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | **Product Cost** | Cost of products in the order from Shopify inventory | | [**customer\_type = new\_customer**](/data-dictionary/measures-and-dimensions#customer-type) | Filters to orders from first-time buyers | | Metadata | | | --------------- | ----------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Sum | *** ## Example Your store generated **\$18,340** in new customer COGS this month from 412 first-time orders: | Segment | COGS | Revenue | Gross Margin | | ------------------- | ------------ | ------------- | ------------ | | New Customers | \$18,340 | \$47,200 | 61.1% | | Returning Customers | \$24,680 | \$68,400 | 63.9% | | **All Orders** | **\$43,020** | **\$115,600** | **62.8%** | New customers have slightly lower margins due to higher average discount rates on acquisition offers. *** ## How It Works New Customer COGS sums the product costs for all orders placed by first-time buyers during the selected period. Product costs come from Shopify variant cost data. This metric is essential for calculating whether your customer acquisition costs can be recovered from first-order profit. *** ## When to Use | Scenario | Action | | ------------------------- | --------------------------------------------------------- | | Acquisition profitability | Subtract from NC Revenue to find first-order gross profit | | CAC payback analysis | Compare NC COGS + ad spend to NC Revenue | | Segment cost structure | Identify if new customers buy higher-cost products | | Margin by cohort | Track if acquisition channel affects product mix | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------ | ------------------------------------- | | [COGS](/reference/metrics/orders/cogs/cogs) | All customers combined | | [Returning Customer COGS](/reference/metrics/orders/cogs/returning-customer-cogs) | Repeat buyer comparison | | [New Customer COGS Per Order](/reference/metrics/orders/cogs/new-customer-cogs-per-order) | Average cost per first-time order | | [New Customer Gross Revenue](/reference/metrics/orders/revenue/new-customer-gross-revenue) | Used with NC COGS to calculate margin | [See all COGS metrics →](/reference/metrics/orders/cogs) # New Customer COGS Gross Rate: First-Time Buyer Cost Ratio Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/new-customer-cogs-gross-rate Measure new customer COGS as a percentage of their gross revenue. Track first-time buyer cost efficiency and compare margin ratios across segments. New customer COGS as a share of their gross revenue—shows what percentage of first-time buyer revenue goes to product costs. ## Formula **New Customer COGS Gross Rate** = ( [**New Customer COGS**](/reference/metrics/orders/cogs/new-customer-cogs) ÷ [**New Customer Gross Revenue**](/reference/metrics/orders/revenue/new-customer-gross-revenue) ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------- | | [**New Customer COGS**](/reference/metrics/orders/cogs/new-customer-cogs) | Cost of goods sold for first-time buyer orders | | [**New Customer Gross Revenue**](/reference/metrics/orders/revenue/new-customer-gross-revenue) | Gross revenue from new customers before discounts | | Metadata | | | --------------- | ----------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Ratio | *** ## Example Your new customers generated **\$47,200** in gross revenue with **\$18,340** in product costs: | Segment | COGS | Gross Revenue | COGS/Gross Rate | | ------------------- | -------- | ------------- | --------------- | | New Customers | \$18,340 | \$47,200 | 38.9% | | Returning Customers | \$24,680 | \$68,400 | 36.1% | New customers have a higher COGS rate—they often purchase starter bundles or lower-margin acquisition products. *** ## How It Works This metric divides New Customer COGS by New Customer Gross Revenue. Higher percentages indicate new customers are buying higher-cost products relative to revenue. Compare to returning customer rate to understand how cost efficiency differs by segment. *** ## When to Use | Scenario | Action | | --------------------- | ------------------------------------------------------------------ | | Segment cost analysis | Compare to returning customer COGS rate for efficiency differences | | Acquisition strategy | Evaluate if starter products are eating into margins | | Product mix review | Identify if new customers gravitate toward high-cost items | | Pricing validation | Ensure acquisition pricing maintains healthy cost ratios | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | [New Customer COGS](/reference/metrics/orders/cogs/new-customer-cogs) | Numerator—product costs for first-time orders | | [New Customer Gross Revenue](/reference/metrics/orders/revenue/new-customer-gross-revenue) | Denominator—pre-discount revenue | | [COGS Gross Rate](/reference/metrics/orders/cogs/cogs-gross-rate) | All-customer comparison | | [Returning Customer COGS Gross Rate](/reference/metrics/orders/cogs/returning-customer-cogs-gross-rate) | Repeat buyer comparison | [See all COGS metrics →](/reference/metrics/orders/cogs) # New Customer COGS Net Rate: First-Time Buyer Cost vs Net Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/new-customer-cogs-net-rate Measure new customer COGS as a percentage of net revenue. Track true cost efficiency for first-time buyers after discounts and refunds. New customer COGS as a share of their net revenue—shows the true cost ratio after discounts and refunds. ## Formula **New Customer COGS Net Rate** = ( [**New Customer COGS**](/reference/metrics/orders/cogs/new-customer-cogs) ÷ [**New Customer Net Revenue**](/reference/metrics/orders/revenue/new-customer-net-revenue) ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------- | | [**New Customer COGS**](/reference/metrics/orders/cogs/new-customer-cogs) | Cost of goods sold for first-time buyer orders | | [**New Customer Net Revenue**](/reference/metrics/orders/revenue/new-customer-net-revenue) | Net revenue from new customers after discounts and refunds | | Metadata | | | --------------- | ----------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Ratio | *** ## Example Your new customers generated **\$42,400** in net revenue with **\$18,340** in product costs: | Segment | COGS | Net Revenue | COGS/Net Rate | | ------------------- | -------- | ----------- | ------------- | | New Customers | \$18,340 | \$42,400 | 43.3% | | Returning Customers | \$24,680 | \$65,100 | 37.9% | New customers have higher COGS net rate due to acquisition discounts reducing net revenue. *** ## How It Works This metric divides New Customer COGS by New Customer Net Revenue. It's typically higher than the gross rate because discounts and refunds reduce the denominator. Use this for true profitability analysis after accounting for all adjustments. *** ## When to Use | Scenario | Action | | --------------------- | -------------------------------------------- | | True acquisition cost | See COGS burden after discounts are applied | | Margin reality check | Understand actual first-order profitability | | Discount impact | Compare to gross rate to see discount effect | | CAC payback | Use with NC revenue for payback analysis | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------- | ------------------------------------ | | [New Customer COGS](/reference/metrics/orders/cogs/new-customer-cogs) | Numerator—product costs | | [New Customer Net Revenue](/reference/metrics/orders/revenue/new-customer-net-revenue) | Denominator—after-adjustment revenue | | [COGS Net Rate](/reference/metrics/orders/cogs/cogs-net-rate) | All-customer comparison | | [Returning Customer COGS Net Rate](/reference/metrics/orders/cogs/returning-customer-cogs-net-rate) | Repeat buyer comparison | [See all COGS metrics →](/reference/metrics/orders/cogs) # New Customer COGS Per Order: Average Cost for First-Time Orders Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/new-customer-cogs-per-order Track average cost of goods sold per new customer order. Understand first-time buyer cost structure for CAC payback and margin analysis. Average product cost per new customer order—compare to returning customers to assess cost mix differences. ## Formula **New Customer COGS Per Order** = [**New Customer COGS**](/reference/metrics/orders/cogs/new-customer-cogs) ÷ [**New Customer Orders**](/reference/metrics/orders/counts/new-customer-orders) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------- | ----------------------------------------------- | | [**New Customer COGS**](/reference/metrics/orders/cogs/new-customer-cogs) | Total product costs for first-time buyer orders | | [**New Customer Orders**](/reference/metrics/orders/counts/new-customer-orders) | Number of orders from first-time buyers | | Metadata | | | --------------- | ----------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Ratio | *** ## Example Your store had **\$18,340** in new customer COGS across **412** first-time orders: | Segment | COGS | Orders | COGS/Order | | ------------------- | -------- | ------ | ---------- | | New Customers | \$18,340 | 412 | \$44.51 | | Returning Customers | \$24,680 | 589 | \$41.90 | New customers have higher COGS per order—they tend to buy starter bundles with higher product costs. *** ## How It Works Divides New Customer COGS by the count of new customer orders. This metric reveals the average product cost burden for first-time transactions, helping you understand whether new customers are buying higher or lower-cost products compared to returning customers. *** ## When to Use | Scenario | Action | | -------------------- | ------------------------------------------- | | CAC payback modeling | Factor into first-order profit calculation | | Product mix analysis | See if new customers buy different products | | Pricing strategy | Ensure first-order pricing covers costs | | Segment comparison | Compare to RC COGS/Order for insights | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------------- | ------------------------- | | [New Customer COGS](/reference/metrics/orders/cogs/new-customer-cogs) | Total costs (numerator) | | [New Customer Orders](/reference/metrics/orders/counts/new-customer-orders) | Order count (denominator) | | [COGS Per Order](/reference/metrics/orders/cogs/cogs-per-order) | All-customer average | | [Returning Customer COGS Per Order](/reference/metrics/orders/cogs/returning-customer-cogs-per-order) | Repeat buyer average | [See all COGS metrics →](/reference/metrics/orders/cogs) # New Customer Other COGS: User-Defined COGS for First-Time Buyers Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/new-customer-other-cogs Track user-defined cost of goods sold for new customer orders. Capture packaging, duties, and other COGS not in Shopify product variants. User-defined COGS from cost entries for new customer orders—captures costs beyond Shopify product variants. ## Formula **New Customer Other COGS** = **SUM** ( Order Cost Entries ) **WHERE** category = COGS **AND** [customer\_type = new\_customer](/data-dictionary/measures-and-dimensions#customer-type) ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------- | -------------------------------------------- | | **Order Cost Entries** | User-defined cost entries with COGS category | | [**customer\_type = new\_customer**](/data-dictionary/measures-and-dimensions#customer-type) | Filters to orders from first-time buyers | | Metadata | | | --------------- | ------------------------------------------ | | **Type** | Currency | | **Data Source** | [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Sum | *** ## Example Your new customer orders incurred **\$1,850** in other COGS this month: | Cost Entry | NC Total | | ------------------- | ----------- | | Packaging materials | \$920 | | Import duties | \$640 | | Quality inspection | \$290 | | **NC Other COGS** | **\$1,850** | *** ## How It Works New Customer Other COGS sums all cost entries categorized as COGS for first-time buyer orders. These are costs you've configured in Upstack—like packaging, duties, or inspection fees—that aren't stored on Shopify product variants. Combined with NC COGS, this gives you complete product cost visibility for acquisition analysis. *** ## When to Use | Scenario | Action | | ------------------------ | ------------------------------------------------- | | Complete NC cost picture | Add to NC COGS for total product costs | | Cost entry validation | Verify user-defined COGS are allocating correctly | | Segment comparison | Compare to RC Other COGS for differences | | Margin accuracy | Include in NC margin calculations | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------- | -------------------------------- | | [Other COGS](/reference/metrics/orders/cogs/other-cogs) | All customers combined | | [Returning Customer Other COGS](/reference/metrics/orders/cogs/returning-customer-other-cogs) | Repeat buyer comparison | | [New Customer COGS](/reference/metrics/orders/cogs/new-customer-cogs) | Product-level costs from Shopify | | [Total COGS](/reference/metrics/orders/cogs/total-cogs) | COGS + Other COGS combined | [See all COGS metrics →](/reference/metrics/orders/cogs) # Other COGS: User-Defined Cost of Goods Sold Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/other-cogs Track user-defined cost of goods sold from order cost entries. Combine with product COGS to calculate Total COGS for accurate margin analysis. User-defined cost of goods sold from order cost entries with category COGS. Combined with product COGS to calculate Total COGS. ## Formula **Other COGS** = **SUM** ( Order Cost Entries ) **WHERE** category = COGS ### Formula Components | Metric | Definition | | ---------------------- | ----------------------------------------------- | | **Order Cost Entries** | Cost entries you've configured in Upstack Costs | | **category = COGS** | Filters to entries categorized as cost of goods | | Metadata | | | --------------- | ------------------------------------------ | | **Type** | Currency | | **Data Source** | [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Sum | *** ## Example Your store has **\$12,400** in product-level COGS from Shopify variants, plus additional costs you've configured: | Cost Entry | Monthly Total | | ------------------- | ------------- | | Packaging materials | \$2,150 | | Quality inspection | \$890 | | Import duties | \$1,460 | | **Other COGS** | **\$4,500** | | Product COGS | \$12,400 | | **Total COGS** | **\$16,900** | *** ## How It Works Other COGS captures cost of goods that aren't stored on Shopify product variants. Configure these as order cost entries with the COGS category. They're summed across all orders and combined with product-level COGS to calculate Total COGS—giving you a complete picture of goods costs for margin analysis. *** ## When to Use | Scenario | Action | | ------------------------ | ------------------------------------- | | Tracking packaging costs | Add as COGS cost entry | | Including import duties | Capture costs not in product variants | | Calculating true margins | Combine with COGS for Total COGS | | Analyzing cost structure | Break down COGS components | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------- | ---------------------------------------- | | [COGS](/reference/metrics/orders/cogs/cogs) | Product-level cost from Shopify variants | | [Total COGS](/reference/metrics/orders/cogs/total-cogs) | COGS + Other COGS combined | | [New Customer Other COGS](/reference/metrics/orders/cogs/new-customer-other-cogs) | Other COGS for first-time buyers | | [Returning Customer Other COGS](/reference/metrics/orders/cogs/returning-customer-other-cogs) | Other COGS for repeat buyers | | [CM1](/reference/metrics/orders/contribution-margin/cm1) | Uses Total COGS in calculation | [See all COGS metrics →](/reference/metrics/orders/cogs) # Other Cost: Additional Variable Order Costs Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/other-cost Track additional variable order costs including per-order fees, per-item fees, and percentage-based costs. Part of Variable Costs calculation. Additional variable order costs beyond handling, gateway, and shipping—includes per-order fees, per-item fees, and percentage-based costs. ## Formula **Other Cost** = **SUM** ( Per-Order Fees + Per-Item Fees + Percentage Fees ) ### Formula Components | Metric | Definition | | ------------------- | --------------------------------------------------------- | | **Per-Order Fees** | Fixed fees charged per order (e.g., insurance, packaging) | | **Per-Item Fees** | Fees charged per line item or unit | | **Percentage Fees** | Costs calculated as % of order value | | Metadata | | | --------------- | ------------------------------------------ | | **Type** | Currency | | **Data Source** | [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Sum | *** ## Example Your store incurred **\$3,420** in other costs this month across 1,140 orders: | Cost Type | Total | | -------------------- | ----------- | | Insurance per order | \$1,140 | | Pick & pack per item | \$1,680 | | Platform fees (1.5%) | \$600 | | **Other Cost** | **\$3,420** | *** ## How It Works Other Cost aggregates variable order costs that aren't captured by handling, gateway, or shipping. Configure these in Upstack Cost Settings as per-order fees, per-item fees, or percentage-based costs. These costs are included in Variable Costs and affect CM2 calculations. *** ## When to Use | Scenario | Action | | -------------------- | --------------------------------------------- | | Full cost accounting | Include insurance, pick & pack, platform fees | | CM2 accuracy | Ensure all variable costs are captured | | Cost optimization | Identify and reduce miscellaneous fees | | Vendor comparison | Track fees across different service providers | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------- | -------------------------------- | | [Variable Costs](/reference/metrics/orders/cogs/variable-costs) | Includes Other Cost as component | | [Other Cost Per Order](/reference/metrics/orders/cogs/other-cost-per-order) | Average per transaction | | [Other Cost %](/reference/metrics/orders/cogs/other-cost-percent) | As percentage of net revenue | | [CM2](/reference/metrics/orders/contribution-margin/cm2) | Deducts Variable Costs from CM1 | [See all COGS metrics →](/reference/metrics/orders/cogs) # Other Cost Per Order: Average Additional Cost Per Transaction Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/other-cost-per-order Track average other variable costs per order. Monitor per-transaction fees for insurance, pick & pack, and platform costs. Average other variable cost per order—shows the per-transaction burden of miscellaneous fees. ## Formula **Other Cost Per Order** = [**Other Cost**](/reference/metrics/orders/cogs/other-cost) ÷ [**Total Orders**](/reference/metrics/orders/counts/total-orders) ### Formula Components | Metric | Definition | | ----------------------------------------------------------------- | ---------------------------------------------- | | [**Other Cost**](/reference/metrics/orders/cogs/other-cost) | Per-order, per-item, and percentage-based fees | | [**Total Orders**](/reference/metrics/orders/counts/total-orders) | Number of orders placed | | Metadata | | | --------------- | ------------------------------------------ | | **Type** | Currency | | **Data Source** | [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Ratio | *** ## Example Your store had **\$3,420** in other costs across **1,140** orders: | Metric | Value | | ------------------------ | ---------- | | Other Cost | \$3,420 | | Total Orders | 1,140 | | **Other Cost Per Order** | **\$3.00** | Each order incurs \$3.00 in miscellaneous variable fees on average. *** ## How It Works Divides total Other Cost by order count. This metric helps you understand the fixed-cost-like burden of per-order fees. Use it alongside AOV to ensure pricing covers all variable costs including these miscellaneous fees. *** ## When to Use | Scenario | Action | | ----------------- | ---------------------------------------- | | Unit economics | Factor into per-order profit calculation | | Pricing floors | Ensure pricing covers this cost layer | | Cost optimization | Identify expensive per-order fees | | Vendor comparison | Compare service provider costs | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------- | ---------------------------- | | [Other Cost](/reference/metrics/orders/cogs/other-cost) | Total costs (numerator) | | [Total Orders](/reference/metrics/orders/counts/total-orders) | Order count (denominator) | | [Other Cost %](/reference/metrics/orders/cogs/other-cost-percent) | As percentage of revenue | | [Variable Costs Per Order](/reference/metrics/orders/cogs/variable-costs-per-order) | All variable costs per order | [See all COGS metrics →](/reference/metrics/orders/cogs) # Other Cost %: Additional Costs as % of Net Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/other-cost-percent Track other variable costs as a percentage of net revenue. Monitor the impact of per-order, per-item, and percentage fees on margins. Other variable costs as a percentage of net revenue—shows the margin impact of miscellaneous per-order fees. ## Formula **Other Cost %** = ( [**Other Cost**](/reference/metrics/orders/cogs/other-cost) ÷ [**Net Revenue**](/reference/metrics/orders/revenue/net-revenue) ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------- | ---------------------------------------------- | | [**Other Cost**](/reference/metrics/orders/cogs/other-cost) | Per-order, per-item, and percentage-based fees | | [**Net Revenue**](/reference/metrics/orders/revenue/net-revenue) | Revenue after discounts and refunds | | Metadata | | | --------------- | ------------------------------------------ | | **Type** | Percentage | | **Data Source** | [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Ratio | *** ## Example Your store had **\$3,420** in other costs against **\$125,000** net revenue: | Metric | Value | | ---------------- | --------- | | Other Cost | \$3,420 | | Net Revenue | \$125,000 | | **Other Cost %** | **2.7%** | This means 2.7% of net revenue goes to miscellaneous variable fees. *** ## How It Works Divides Other Cost by Net Revenue and multiplies by 100. This percentage helps you understand how much of your margin is consumed by fees beyond the core costs (handling, gateway, shipping). Monitor this to ensure miscellaneous costs don't creep up over time. *** ## When to Use | Scenario | Action | | ------------------- | ---------------------------------- | | Margin leakage | Identify if other fees are growing | | Cost benchmarking | Compare across periods or segments | | Fee negotiation | Quantify impact of vendor fees | | Break-even analysis | Factor into pricing models | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------- | ------------------------------ | | [Other Cost](/reference/metrics/orders/cogs/other-cost) | Dollar value (numerator) | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Revenue baseline (denominator) | | [Other Cost Per Order](/reference/metrics/orders/cogs/other-cost-per-order) | Per-transaction average | | [Variable Costs %](/reference/metrics/orders/cogs/variable-costs-percent) | All variable costs as % | [See all COGS metrics →](/reference/metrics/orders/cogs) # Returning Customer COGS: Cost of Goods for Repeat Buyers Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/returning-customer-cogs Track cost of goods sold for returning customer orders. Calculate repeat-buyer gross margin and compare cost structure across segments. Cost of goods sold for orders placed by returning customers—used to calculate repeat buyer gross margin. ## Formula **Returning Customer COGS** = **SUM** ( Product Cost ) **WHERE** [customer\_type = returning\_customer](/data-dictionary/measures-and-dimensions#customer-type) ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | **Product Cost** | Cost of products in the order from Shopify inventory | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions#customer-type) | Filters to orders from customers who have purchased before | | Metadata | | | --------------- | ----------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Sum | *** ## Example Your returning customers generated **\$24,680** in COGS this month from 589 repeat orders: | Segment | COGS | Revenue | Gross Margin | | ------------------- | ------------ | ------------- | ------------ | | Returning Customers | \$24,680 | \$68,400 | 63.9% | | New Customers | \$18,340 | \$47,200 | 61.1% | | **All Orders** | **\$43,020** | **\$115,600** | **62.8%** | Returning customers have better margins—they buy fewer discounted starter products. *** ## How It Works Returning Customer COGS sums the product costs for all orders placed by repeat buyers during the selected period. Product costs come from Shopify variant cost data. Compare to new customer COGS to understand how product mix differs by customer segment. *** ## When to Use | Scenario | Action | | ----------------------- | -------------------------------------------- | | Retention profitability | Calculate repeat-order gross profit | | LTV modeling | Use RC COGS in lifetime value calculations | | Segment cost structure | Compare to NC COGS for product mix insights | | Margin by cohort | Track if retention campaigns affect cost mix | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | ------------------------------------- | | [COGS](/reference/metrics/orders/cogs/cogs) | All customers combined | | [New Customer COGS](/reference/metrics/orders/cogs/new-customer-cogs) | First-time buyer comparison | | [Returning Customer COGS Per Order](/reference/metrics/orders/cogs/returning-customer-cogs-per-order) | Average cost per repeat order | | [Returning Customer Gross Revenue](/reference/metrics/orders/revenue/returning-customer-gross-revenue) | Used with RC COGS to calculate margin | [See all COGS metrics →](/reference/metrics/orders/cogs) # Returning Customer COGS Gross Rate: Repeat-Buyer Cost Ratio Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/returning-customer-cogs-gross-rate Measure returning customer COGS as a percentage of their gross revenue. Track repeat-buyer cost efficiency and compare margin ratios across segments. Returning customer COGS as a share of their gross revenue—shows what percentage of repeat-buyer revenue goes to product costs. ## Formula **Returning Customer COGS Gross Rate** = ( [**Returning Customer COGS**](/reference/metrics/orders/cogs/returning-customer-cogs) ÷ [**Returning Customer Gross Revenue**](/reference/metrics/orders/revenue/returning-customer-gross-revenue) ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | [**Returning Customer COGS**](/reference/metrics/orders/cogs/returning-customer-cogs) | Cost of goods sold for repeat buyer orders | | [**Returning Customer Gross Revenue**](/reference/metrics/orders/revenue/returning-customer-gross-revenue) | Gross revenue from returning customers before discounts | | Metadata | | | --------------- | ----------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Ratio | *** ## Example Your returning customers generated **\$68,400** in gross revenue with **\$24,680** in product costs: | Segment | COGS | Gross Revenue | COGS/Gross Rate | | ------------------- | -------- | ------------- | --------------- | | Returning Customers | \$24,680 | \$68,400 | 36.1% | | New Customers | \$18,340 | \$47,200 | 38.9% | Returning customers have a lower COGS rate—they purchase higher-margin products without introductory bundles. *** ## How It Works This metric divides Returning Customer COGS by Returning Customer Gross Revenue. Lower percentages indicate better cost efficiency. Unlike margins which show what you keep, this rate shows what percentage goes directly to product costs. *** ## When to Use | Scenario | Action | | --------------------- | ---------------------------------------------------------------- | | Segment cost analysis | Compare to new customer COGS rate for efficiency differences | | Margin benchmarking | Track whether repeat buyers maintain cost efficiency over time | | Product mix review | Identify if returning customers shift toward lower-cost products | | Pricing validation | Confirm retention pricing preserves healthy cost ratios | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | ----------------------------------------- | | [Returning Customer COGS](/reference/metrics/orders/cogs/returning-customer-cogs) | Numerator—product costs for repeat orders | | [Returning Customer Gross Revenue](/reference/metrics/orders/revenue/returning-customer-gross-revenue) | Denominator—pre-discount revenue | | [COGS Gross Rate](/reference/metrics/orders/cogs/cogs-gross-rate) | All-customer comparison | | [New Customer COGS Gross Rate](/reference/metrics/orders/cogs/new-customer-cogs-gross-rate) | First-time buyer comparison | [See all COGS metrics →](/reference/metrics/orders/cogs) # Returning Customer COGS Net Rate: Repeat-Buyer Cost vs Net Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/returning-customer-cogs-net-rate Measure returning customer COGS as a percentage of net revenue. Track true cost efficiency for repeat buyers after discounts and refunds. Returning customer COGS as a share of their net revenue—shows the true cost ratio after discounts and refunds. ## Formula **Returning Customer COGS Net Rate** = ( [**Returning Customer COGS**](/reference/metrics/orders/cogs/returning-customer-cogs) ÷ [**Returning Customer Net Revenue**](/reference/metrics/orders/revenue/returning-customer-net-revenue) ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | | [**Returning Customer COGS**](/reference/metrics/orders/cogs/returning-customer-cogs) | Cost of goods sold for repeat buyer orders | | [**Returning Customer Net Revenue**](/reference/metrics/orders/revenue/returning-customer-net-revenue) | Net revenue from returning customers after discounts and refunds | | Metadata | | | --------------- | ----------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Ratio | *** ## Example Your returning customers generated **\$65,100** in net revenue with **\$24,680** in product costs: | Segment | COGS | Net Revenue | COGS/Net Rate | | ------------------- | -------- | ----------- | ------------- | | Returning Customers | \$24,680 | \$65,100 | 37.9% | | New Customers | \$18,340 | \$42,400 | 43.3% | Returning customers have lower COGS net rate—better margins even after adjustments. *** ## How It Works This metric divides Returning Customer COGS by Returning Customer Net Revenue. It's typically higher than the gross rate because discounts and refunds reduce the denominator. Use this for true profitability analysis of your repeat buyer segment. *** ## When to Use | Scenario | Action | | ---------------------------- | -------------------------------------- | | True retention profitability | See COGS burden after adjustments | | LTV accuracy | Use net-based rates for lifetime value | | Loyalty program impact | Compare before/after loyalty discounts | | Segment benchmarking | Compare to NC rate for insights | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | ------------------------------------ | | [Returning Customer COGS](/reference/metrics/orders/cogs/returning-customer-cogs) | Numerator—product costs | | [Returning Customer Net Revenue](/reference/metrics/orders/revenue/returning-customer-net-revenue) | Denominator—after-adjustment revenue | | [COGS Net Rate](/reference/metrics/orders/cogs/cogs-net-rate) | All-customer comparison | | [New Customer COGS Net Rate](/reference/metrics/orders/cogs/new-customer-cogs-net-rate) | First-time buyer comparison | [See all COGS metrics →](/reference/metrics/orders/cogs) # Returning Customer COGS Per Order: Average Cost for Repeat Orders Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/returning-customer-cogs-per-order Track average cost of goods sold per returning customer order. Understand repeat buyer cost structure for LTV and margin analysis. Average product cost per returning customer order—compare to new customers to assess cost mix differences. ## Formula **Returning Customer COGS Per Order** = [**Returning Customer COGS**](/reference/metrics/orders/cogs/returning-customer-cogs) ÷ [**Returning Customer Orders**](/reference/metrics/orders/counts/returning-customer-orders) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------- | ------------------------------------------- | | [**Returning Customer COGS**](/reference/metrics/orders/cogs/returning-customer-cogs) | Total product costs for repeat buyer orders | | [**Returning Customer Orders**](/reference/metrics/orders/counts/returning-customer-orders) | Number of orders from repeat buyers | | Metadata | | | --------------- | ----------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Ratio | *** ## Example Your store had **\$24,680** in returning customer COGS across **589** repeat orders: | Segment | COGS | Orders | COGS/Order | | ------------------- | -------- | ------ | ---------- | | Returning Customers | \$24,680 | 589 | \$41.90 | | New Customers | \$18,340 | 412 | \$44.51 | Returning customers have lower COGS per order—they buy fewer starter bundles and more replenishment items. *** ## How It Works Divides Returning Customer COGS by the count of returning customer orders. This metric reveals the average product cost burden for repeat transactions, helping you understand whether returning customers are buying higher or lower-cost products compared to new customers. *** ## When to Use | Scenario | Action | | -------------------- | ------------------------------------------------ | | LTV modeling | Factor into repeat-order profit calculation | | Product mix analysis | See if repeat buyers shift to different products | | Retention strategy | Understand cost impact of loyalty programs | | Segment comparison | Compare to NC COGS/Order for insights | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------- | ------------------------- | | [Returning Customer COGS](/reference/metrics/orders/cogs/returning-customer-cogs) | Total costs (numerator) | | [Returning Customer Orders](/reference/metrics/orders/counts/returning-customer-orders) | Order count (denominator) | | [COGS Per Order](/reference/metrics/orders/cogs/cogs-per-order) | All-customer average | | [New Customer COGS Per Order](/reference/metrics/orders/cogs/new-customer-cogs-per-order) | First-time buyer average | [See all COGS metrics →](/reference/metrics/orders/cogs) # Returning Customer Other COGS: User-Defined COGS for Repeat Buyers Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/returning-customer-other-cogs Track user-defined cost of goods sold for returning customer orders. Capture packaging, duties, and other COGS not in Shopify product variants. User-defined COGS from cost entries for returning customer orders—captures costs beyond Shopify product variants. ## Formula **Returning Customer Other COGS** = **SUM** ( Order Cost Entries ) **WHERE** category = COGS **AND** [customer\_type = returning\_customer](/data-dictionary/measures-and-dimensions#customer-type) ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | **Order Cost Entries** | User-defined cost entries with COGS category | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions#customer-type) | Filters to orders from customers who have purchased before | | Metadata | | | --------------- | ------------------------------------------ | | **Type** | Currency | | **Data Source** | [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Sum | *** ## Example Your returning customer orders incurred **\$2,650** in other COGS this month: | Cost Entry | RC Total | | ------------------- | ----------- | | Packaging materials | \$1,230 | | Import duties | \$820 | | Quality inspection | \$600 | | **RC Other COGS** | **\$2,650** | *** ## How It Works Returning Customer Other COGS sums all cost entries categorized as COGS for repeat buyer orders. These are costs you've configured in Upstack—like packaging, duties, or inspection fees—that aren't stored on Shopify product variants. Combined with RC COGS, this gives you complete product cost visibility for retention analysis. *** ## When to Use | Scenario | Action | | ------------------------ | ------------------------------------------------- | | Complete RC cost picture | Add to RC COGS for total product costs | | Cost entry validation | Verify user-defined COGS are allocating correctly | | Segment comparison | Compare to NC Other COGS for differences | | LTV accuracy | Include in repeat-order margin calculations | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------- | -------------------------------- | | [Other COGS](/reference/metrics/orders/cogs/other-cogs) | All customers combined | | [New Customer Other COGS](/reference/metrics/orders/cogs/new-customer-other-cogs) | First-time buyer comparison | | [Returning Customer COGS](/reference/metrics/orders/cogs/returning-customer-cogs) | Product-level costs from Shopify | | [Total COGS](/reference/metrics/orders/cogs/total-cogs) | COGS + Other COGS combined | [See all COGS metrics →](/reference/metrics/orders/cogs) # Total COGS: Complete Cost of Goods Sold Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/total-cogs Track your complete cost of goods sold combining product costs and user-defined COGS entries. Essential for accurate CM1 and margin analysis. The total cost of goods sold, combining product variant costs from Shopify and user-defined COGS entries. ## Formula **Total COGS** = [**COGS**](/reference/metrics/orders/cogs/cogs) + [**Other COGS**](/reference/metrics/orders/cogs/other-cogs) ### Formula Components | Metric | Definition | | ----------------------------------------------------------- | ------------------------------------------------- | | [**COGS**](/reference/metrics/orders/cogs/cogs) | Product-level cost of goods from Shopify variants | | [**Other COGS**](/reference/metrics/orders/cogs/other-cogs) | User-defined cost entries with category COGS | | Metadata | | | --------------- | ----------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Sum | *** ## Example Your store had **\$16,900** in Total COGS for January: | Component | Value | Source | | ------------------- | ------------ | ---------------- | | Product COGS | \$12,400 | Shopify variants | | Packaging materials | \$2,150 | Cost entry | | Import duties | \$1,460 | Cost entry | | Quality inspection | \$890 | Cost entry | | **Total COGS** | **\$16,900** | Combined | *** ## How It Works Total COGS combines two sources: product variant costs from Shopify (COGS) and any additional cost-of-goods entries you've configured (Other COGS). This complete picture of goods costs is deducted from Net Revenue to calculate CM1—your first contribution margin. *** ## When to Use | Scenario | Action | | --------------------- | ------------------------------------------ | | Calculating CM1 | Subtract Total COGS from Net Revenue | | Margin analysis | Use for accurate gross profit calculations | | Cost tracking | Monitor all goods costs in one metric | | Product profitability | Compare Total COGS against revenue | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------- | -------------------------------------------- | | [COGS](/reference/metrics/orders/cogs/cogs) | Product costs only (this metric includes it) | | [Other COGS](/reference/metrics/orders/cogs/other-cogs) | User-defined costs (this metric includes it) | | [CM1](/reference/metrics/orders/contribution-margin/cm1) | Net Revenue − Total COGS | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Revenue used in CM1 calculation | | [Gross Profit](/reference/metrics/orders/contribution-margin/gross-profit) | Related margin metric | [See all COGS metrics →](/reference/metrics/orders/cogs) # Variable Costs: Total Variable Order Costs Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/variable-costs Track total variable order costs including handling, gateway fees, shipping, and other costs. Use for unit economics and contribution margin analysis. Variable Costs measures the total variable order costs—including handling, gateway fees, shipping, and other costs—that change with each order. ## Formula **Variable Costs** = **Handling Cost** + **Gateway Cost** + **Shipping Cost** + [**Other Cost**](/reference/metrics/orders/cogs/other-cost) ### Formula Components | Metric | Definition | | ----------------------------------------------------------- | -------------------------------------------------- | | **Handling Cost** | Per-order fulfillment and handling fees | | **Gateway Cost** | Payment processor and transaction fees | | **Shipping Cost** | Carrier shipping charges | | [**Other Cost**](/reference/metrics/orders/cogs/other-cost) | Additional per-order, per-item, or percentage fees | | Metadata | | | --------------- | ----------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Sum | *** ## Example Your store processed **1,842 orders** in March with the following variable costs: | Cost Type | Total | | ------------------ | ------------ | | Handling fees | \$3,684 | | Gateway fees | \$4,238 | | Shipping costs | \$9,210 | | Other costs | \$1,289 | | **Variable Costs** | **\$18,421** | *** ## How It Works Variable Costs aggregates all per-order costs that scale with order volume. These costs are deducted from CM1 (Gross Profit) to calculate CM2 (Contribution Margin after variable costs). Tracking variable costs separately helps isolate product margin from operational costs. *** ## When to Use | Scenario | Action | | ------------------------------- | ----------------------------------------- | | Calculating CM2 | Subtract Variable Costs from Gross Profit | | Analyzing unit economics | Track per-order variable burden | | Setting pricing floors | Ensure prices cover COGS + Variable Costs | | Evaluating fulfillment partners | Compare handling and shipping costs | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------- | -------------------------------------------- | | [COGS](/reference/metrics/orders/cogs/cogs) | Product costs (separate from variable costs) | | [Other Cost](/reference/metrics/orders/cogs/other-cost) | Component of Variable Costs | | [Variable Costs Per Order](/reference/metrics/orders/cogs/variable-costs-per-order) | Average variable cost per order | | [Variable Costs %](/reference/metrics/orders/cogs/variable-costs-percent) | Variable costs as % of net revenue | [See all COGS metrics →](/reference/metrics/orders/cogs) # Variable Costs Per Order: Average Variable Cost Per Transaction Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/variable-costs-per-order Track average variable costs per order including handling, gateway, shipping, and other fees. Essential for unit economics and pricing analysis. Average variable cost per order—shows the per-transaction burden of handling, gateway, shipping, and other operational fees. ## Formula **Variable Costs Per Order** = [**Variable Costs**](/reference/metrics/orders/cogs/variable-costs) ÷ [**Total Orders**](/reference/metrics/orders/counts/total-orders) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------- | ------------------------------------------- | | [**Variable Costs**](/reference/metrics/orders/cogs/variable-costs) | Handling + Gateway + Shipping + Other costs | | [**Total Orders**](/reference/metrics/orders/counts/total-orders) | Number of orders placed | | Metadata | | | --------------- | ----------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Ratio | *** ## Example Your store had **\$18,421** in variable costs across **1,842** orders: | Metric | Value | | ---------------------------- | ----------- | | Variable Costs | \$18,421 | | Total Orders | 1,842 | | **Variable Costs Per Order** | **\$10.00** | Each order incurs \$10.00 in variable operational costs on average. *** ## How It Works Divides total Variable Costs by order count. This metric helps you understand the fixed-cost-like burden of per-order operational fees. Add this to COGS Per Order to see the total cost per transaction before margin. *** ## When to Use | Scenario | Action | | ------------------- | ------------------------------------------------- | | Unit economics | Calculate per-order profit after all costs | | Pricing floors | Ensure AOV covers COGS + Variable Costs per order | | Cost optimization | Identify which variable costs are highest | | Break-even analysis | Factor into minimum order value | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------- | -------------------------------------- | | [Variable Costs](/reference/metrics/orders/cogs/variable-costs) | Total costs (numerator) | | [Total Orders](/reference/metrics/orders/counts/total-orders) | Order count (denominator) | | [Variable Costs %](/reference/metrics/orders/cogs/variable-costs-percent) | As percentage of revenue | | [COGS Per Order](/reference/metrics/orders/cogs/cogs-per-order) | Product cost per order (add for total) | [See all COGS metrics →](/reference/metrics/orders/cogs) # Variable Costs %: Variable Costs as Percentage of Net Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/cogs/variable-costs-percent Track total variable costs as a percentage of net revenue. Monitor the margin impact of handling, gateway, shipping, and other variable fees. Variable costs as a percentage of net revenue—shows how much of your margin is consumed by operational costs. ## Formula **Variable Costs %** = ( [**Variable Costs**](/reference/metrics/orders/cogs/variable-costs) ÷ [**Net Revenue**](/reference/metrics/orders/revenue/net-revenue) ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------- | ------------------------------------------- | | [**Variable Costs**](/reference/metrics/orders/cogs/variable-costs) | Handling + Gateway + Shipping + Other costs | | [**Net Revenue**](/reference/metrics/orders/revenue/net-revenue) | Revenue after discounts and refunds | | Metadata | | | --------------- | ----------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/dashboard/settings/costs) | | **Aggregation** | Ratio | *** ## Example Your store had **\$18,421** in variable costs against **\$125,000** net revenue: | Metric | Value | | -------------------- | --------- | | Variable Costs | \$18,421 | | Net Revenue | \$125,000 | | **Variable Costs %** | **14.7%** | This means 14.7% of net revenue goes to variable operational costs beyond product costs. *** ## How It Works Divides Variable Costs by Net Revenue and multiplies by 100. This percentage helps you understand the operational cost burden on each dollar of revenue. Combined with COGS rates, it gives you a complete picture of where your margin goes. *** ## When to Use | Scenario | Action | | ---------------------- | ---------------------------------------- | | Margin analysis | See operational cost impact on CM2 | | Cost benchmarking | Compare across periods or segments | | Pricing strategy | Factor into minimum pricing requirements | | Operational efficiency | Track if variable costs are creeping up | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------- | ------------------------------ | | [Variable Costs](/reference/metrics/orders/cogs/variable-costs) | Dollar value (numerator) | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Revenue baseline (denominator) | | [Variable Costs Per Order](/reference/metrics/orders/cogs/variable-costs-per-order) | Per-transaction average | | [CM2](/reference/metrics/orders/contribution-margin/cm2) | Margin after variable costs | [See all COGS metrics →](/reference/metrics/orders/cogs) # Contribution Margin: Profit After All Variable Costs Source: https://docs.upstackdata.com/reference/metrics/orders/contribution-margin/contribution-margin Track your true marketing profit with Contribution Margin (CM3). Calculate profit after deducting COGS, fulfillment, transaction, marketing, and ad spend. Total contribution margin (CM3) after deducting all variable costs including COGS, fulfillment, transaction fees, and marketing/ad spend from net revenue. ## Formula **Contribution Margin** = **CM2** − **Marketing Cost** − **Ad Spend** − **Agency Fees** ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | **CM2** | Margin after deducting COGS, fulfillment, and transaction costs from net revenue | | [**Marketing Cost**](/reference/metrics/orders/contribution-margin/marketing-cost) | User-defined marketing costs allocated per order | | [**Ad Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Total advertising spend across all connected platforms | | **Agency Fees** | User-defined agency fees allocated per order | | Metadata | | | --------------- | -------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Sum | *** ## Example Your store generated **\$125,000** in net revenue last month. After all variable costs: | Line Item | Amount | Running Margin | | --------------------------- | --------- | ------------------ | | Net Revenue | \$125,000 | \$125,000 | | − COGS | \$37,500 | \$87,500 (CM1) | | − Fulfillment + Transaction | \$12,500 | \$75,000 (CM2) | | − Marketing Cost | \$8,000 | \$67,000 | | − Ad Spend | \$15,000 | \$52,000 | | − Agency Fees | \$2,000 | **\$50,000 (CM3)** | Your Contribution Margin is **\$50,000**, representing 40% of net revenue. *** ## How It Works Contribution Margin (CM3) represents profit remaining after subtracting all variable costs from net revenue. It's calculated as a layered waterfall: Net Revenue → CM1 (minus COGS) → CM2 (minus fulfillment and transaction costs) → CM3 (minus marketing, ad spend, and agency fees). This metric shows true marketing profitability before fixed operating expenses. *** ## When to Use | Scenario | Action | | ----------------------- | --------------------------------------------------------- | | Measuring marketing ROI | Compare contribution margin to total marketing investment | | Setting ad budgets | Ensure campaigns maintain positive CM3 | | Pricing decisions | Verify products cover all variable costs | | Profitability analysis | Identify which channels generate real profit | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------ | ------------------------------------- | | [Gross Profit](/reference/metrics/orders/contribution-margin/gross-profit) | Net Revenue minus COGS (CM1) | | [Marketing Cost](/reference/metrics/orders/contribution-margin/marketing-cost) | User-defined marketing cost component | | [Total Cost](/reference/metrics/orders/contribution-margin/total-cost) | Sum of all cost components | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Starting point before deductions | [See all Contribution Margin metrics →](/reference/metrics/orders/contribution-margin) # Contribution Margin %: Percent of Revenue as Profit Source: https://docs.upstackdata.com/reference/metrics/orders/contribution-margin/contribution-margin-percent Track what percentage of net revenue remains as contribution margin (CM3) after all variable costs. Calculate true marketing profitability. Percentage of net revenue remaining as contribution margin (CM3) after all variable costs. ## Formula **Contribution Margin %** = ( **Contribution Margin** ÷ **Net Revenue** ) × 100 ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | [**Contribution Margin**](/reference/metrics/orders/contribution-margin/contribution-margin) | Profit after COGS, fulfillment, transaction, marketing, and ad spend | | [**Net Revenue**](/reference/metrics/orders/revenue/net-revenue) | Revenue after discounts and refunds | | Metadata | | | --------------- | -------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Ratio | *** ## Example Your store generated **\$125,000 in net revenue** with a **22.4% contribution margin** in March: | Month | Net Revenue | Contribution Margin | CM % | | -------- | ----------- | ------------------- | ----- | | January | \$98,500 | \$19,700 | 20.0% | | February | \$112,300 | \$24,706 | 22.0% | | March | \$125,000 | \$28,000 | 22.4% | *** ## How It Works Contribution Margin % expresses Contribution Margin as a percentage of net revenue. It shows how much of each revenue dollar becomes profit after all variable costs—COGS, fulfillment, transaction fees, marketing costs, and ad spend. This percentage is your true marketing profitability rate. *** ## When to Use | Scenario | Action | | ----------------------------- | -------------------------------------------------- | | Benchmark profitability | Compare CM % across periods to track margin trends | | Evaluate marketing efficiency | Higher CM % means more profit per marketing dollar | | Set pricing strategy | Ensure prices support target contribution margins | | Compare channels | Identify which channels deliver the best margin | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------- | ------------------------------------------- | | [Contribution Margin](/reference/metrics/orders/contribution-margin/contribution-margin) | The dollar amount (this metric's numerator) | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | The denominator for this calculation | | [Total Cost %](/reference/metrics/orders/contribution-margin/total-cost-percent) | Inverse view—what percentage goes to costs | | [Marketing Cost %](/reference/metrics/orders/contribution-margin/marketing-cost-percent) | Marketing spend as percentage of revenue | [See all Contribution Margin metrics →](/reference/metrics/orders/contribution-margin) # Contribution Margin: Track CM1-CM4 Per Order Source: https://docs.upstackdata.com/reference/metrics/orders/contribution-margin/index Track contribution margin metrics in Upstack. Includes CM1, CM2, CM3, CM4 per order with cost components and margin analysis. Contribution margin metrics track profitability at multiple levels—from gross margin (CM1) through operating profit (CM4). These build progressively as costs are deducted. **Data Source:** [Shopify](/sources/shopify)\ **Metrics:** 24 ## Contribution Margin Levels | Level | Name | Formula | | ----- | ------------------- | ------------------------------------------- | | CM1 | Gross Margin | Revenue - COGS | | CM2 | After Fulfillment | CM1 - Fulfillment Costs - Transaction Costs | | CM3 | Contribution Margin | CM2 - Marketing Cost - Agency Fees | | CM4 | Operating Profit | CM3 - Opex | ## Metrics in This Group ### CM Per Order | Metric | Description | When to Use | | ---------------------------------------------------------------------------- | --------------------------------- | ------------------------------- | | [CM1 Per Order](/reference/metrics/orders/contribution-margin/cm1-per-order) | Gross margin per order | Benchmark product profitability | | [CM2 Per Order](/reference/metrics/orders/contribution-margin/cm2-per-order) | Post-fulfillment margin per order | Include variable costs | | [CM3 Per Order](/reference/metrics/orders/contribution-margin/cm3-per-order) | Contribution margin per order | Include marketing costs | | [CM4 Per Order](/reference/metrics/orders/contribution-margin/cm4-per-order) | Operating profit per order | Full cost allocation | ### New Customer CM Per Order | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------------------ | -------------------------- | ----------------------------------- | | [New Customer CM1 Per Order](/reference/metrics/orders/contribution-margin/new-customer-cm1-per-order) | NC gross margin per order | New customer profitability | | [New Customer CM2 Per Order](/reference/metrics/orders/contribution-margin/new-customer-cm2-per-order) | NC post-fulfillment margin | Include new customer variable costs | | [New Customer CM3 Per Order](/reference/metrics/orders/contribution-margin/new-customer-cm3-per-order) | NC contribution margin | Acquisition profitability | | [New Customer CM4 Per Order](/reference/metrics/orders/contribution-margin/new-customer-cm4-per-order) | NC operating profit | Full new customer economics | ### Cost Components | Metric | Description | When to Use | | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------- | | [Total Cost](/reference/metrics/orders/contribution-margin/total-cost) | All costs combined (COGS + fulfillment + transaction + marketing + fees + opex) | Measure complete cost structure | | [New Customer Total Cost](/reference/metrics/orders/contribution-margin/new-customer-total-cost) | All costs for first-time buyer orders | Measure acquisition cost structure | | [Marketing Cost](/reference/metrics/orders/contribution-margin/marketing-cost) | User-defined marketing costs | Track marketing spend allocation | | [Marketing Cost Per Order](/reference/metrics/orders/contribution-margin/marketing-cost-per-order) | Average marketing cost per order | Measure per-order marketing efficiency | | [Agency Fees](/reference/metrics/orders/contribution-margin/agency-fees) | User-defined agency fees | Track agency spend allocation | | [Opex](/reference/metrics/orders/contribution-margin/opex) | Operating expenses | Track overhead allocation | ## How These Metrics Relate Contribution margins build progressively: 1. **CM1** (Gross Margin) = Revenue - COGS 2. **CM2** (After Fulfillment) = CM1 - Fulfillment - Transaction Costs 3. **CM3** (Contribution Margin) = CM2 - Marketing - Agency Fees 4. **CM4** (Operating Profit) = CM3 - Opex Each level shows profitability after deducting the next set of costs. ## Choosing the Right Metric * **Product profitability**: Use CM1 to evaluate products before variable costs * **Order economics**: Use CM2 to see profit after all variable costs * **Marketing efficiency**: Use CM3 to measure contribution after marketing * **Business profitability**: Use CM4 for bottom-line order profitability * **Customer acquisition**: Compare New Customer CM metrics to justify CAC # Marketing Cost: User-Defined Marketing Spend Allocated to Orders Source: https://docs.upstackdata.com/reference/metrics/orders/contribution-margin/marketing-cost Track user-defined marketing costs allocated to orders in Upstack. Separate from platform ad spend—includes influencer fees, sponsorships, and affiliate commissions. User-defined marketing costs allocated to orders, separate from platform ad spend. Configured in Cost Settings. ## Formula **Marketing Cost** = **SUM** ( Order Cost Entries ) **WHERE** category = marketing ### Formula Components | Metric | Definition | | -------------------------------------------------------------------- | ----------------------------------------------------- | | **Order Cost Entries** | User-defined cost entries configured in Cost Settings | | [**category = marketing**](/data-dictionary/measures-and-dimensions) | Filters to marketing cost entries | | Metadata | | | --------------- | --------------------------------------- | | **Type** | Currency | | **Data Source** | [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Sum | *** ## Example Your store allocated **\$12,500 in marketing costs** across orders in Q1: | Month | Marketing Cost | Orders | Cost Per Order | | -------- | -------------- | ------ | -------------- | | January | \$3,800 | 1,247 | \$3.05 | | February | \$4,200 | 1,389 | \$3.02 | | March | \$4,500 | 1,512 | \$2.98 | *** ## How It Works Marketing Cost aggregates user-defined cost entries tagged with the "Marketing" category. These are costs you configure in Cost Settings—influencer fees, affiliate commissions, sponsorships, or other marketing spend not captured by ad platform integrations. Marketing Cost is deducted from CM2 (alongside Agency Fees) to calculate CM3 Contribution Margin. *** ## When to Use | Scenario | Action | | ---------------------------- | ------------------------------------------------------------ | | Track non-ad marketing spend | Capture influencer fees, affiliate commissions, sponsorships | | Calculate true CM3 | Include all marketing costs for accurate contribution margin | | Allocate overhead | Distribute fixed marketing costs across orders | | Compare cost sources | Separate user-defined costs from platform ad spend | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [Marketing Cost Per Order](/reference/metrics/orders/contribution-margin/marketing-cost-per-order) | This metric ÷ Total Orders | | [CM2 Per Order](/reference/metrics/orders/contribution-margin/cm2-per-order) | Margin before marketing costs are deducted | | [CM3 Per Order](/reference/metrics/orders/contribution-margin/cm3-per-order) | Result after deducting marketing and agency fees | | [Agency Fees](/reference/metrics/orders/contribution-margin/agency-fees) | Another cost component deducted from CM2 | | [Total Cost](/reference/metrics/orders/contribution-margin/total-cost) | All costs combined including marketing | [See all Contribution Margin metrics →](/reference/metrics/orders/contribution-margin) # Marketing Cost Per Order: Ad Spend Efficiency Source: https://docs.upstackdata.com/reference/metrics/orders/contribution-margin/marketing-cost-per-order Measure marketing spend per order in your Shopify store. Track how much ad spend is allocated to each attributed conversion. Marketing Cost Per Order measures the average marketing spend allocated to each attributed order. ## Formula **Marketing Cost Per Order** = **Total Marketing Cost** ÷ **Orders** ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------- | --------------------------------------- | | [**Total Marketing Cost**](/reference/metrics/orders/contribution-margin/marketing-cost) | Sum of all ad spend allocated to orders | | [**Orders**](/reference/metrics/orders/conversions/orders) | Total number of attributed orders | | Metadata | | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok-ads), [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your Shopify store spent \$30,000 on marketing and generated 1,500 attributed orders. | Component | Value | | ---------------------------- | ----------- | | Total Marketing Cost | \$30,000 | | Orders | 1,500 | | **Marketing Cost Per Order** | **\$20.00** | *** ## How It Works Marketing Cost Per Order divides total marketing spend by attributed orders. This metric helps you understand how much ad spend is required to generate a single conversion. It factors into CM3 calculations and is essential for evaluating marketing efficiency. Marketing cost includes spend from all connected ad platforms (Meta, Google, TikTok, etc.) allocated via your attribution model. *** ## When to Use | Scenario | Action | | ------------------------------- | -------------------------------------------------------- | | Evaluating marketing efficiency | Lower Marketing Cost Per Order = more efficient | | Setting CPA targets | Use as baseline for cost-per-acquisition goals | | Comparing channels | Identify which channels deliver lower cost per order | | Protecting CM3 margins | Ensure Marketing Cost Per Order leaves acceptable margin | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | [New Customer Marketing Cost Per Order](/reference/metrics/orders/contribution-margin/new-customer-marketing-cost-per-order) | Marketing cost for first-time buyers | | [Returning Customer Marketing Cost Per Order](/reference/metrics/orders/contribution-margin/returning-customer-marketing-cost-per-order) | Marketing cost for repeat buyers | | [Marketing Cost %](/reference/metrics/orders/contribution-margin/marketing-cost-percent) | Marketing as percentage of revenue | | [CM3 Per Order](/reference/metrics/orders/contribution-margin/cm3-per-order) | Margin after marketing | [See all Contribution Margin metrics →](/reference/metrics/orders/contribution-margin) # Marketing Cost %: Marketing Spend as Share of Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/contribution-margin/marketing-cost-percent Track marketing costs as a percentage of net revenue. Measure how much revenue goes to user-defined marketing spend for contribution margin analysis. Marketing cost as a percentage of net revenue, showing what portion of revenue is spent on marketing. ## Formula **Marketing Cost %** = ( **Marketing Cost** ÷ **Net Revenue** ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------- | ---------------------------------------------------- | | [**Marketing Cost**](/reference/metrics/orders/contribution-margin/marketing-cost) | User-defined marketing costs from order cost entries | | [**Net Revenue**](/reference/metrics/orders/revenue/net-revenue) | Revenue after discounts and refunds | | Metadata | | | --------------- | -------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Ratio | *** ## Example Your store earned **\$250,000** in net revenue with **\$12,500** allocated to marketing costs: | Month | Net Revenue | Marketing Cost | Marketing Cost % | | -------- | ----------- | -------------- | ---------------- | | January | \$78,000 | \$3,800 | 4.9% | | February | \$82,000 | \$4,200 | 5.1% | | March | \$90,000 | \$4,500 | 5.0% | *** ## How It Works Marketing Cost % divides user-defined marketing costs by net revenue, showing what percentage of revenue goes to marketing expenses not captured by ad platform integrations. This includes influencer fees, affiliate commissions, sponsorships, and other marketing spend entered as order cost entries. *** ## When to Use | Scenario | Action | | ----------------- | -------------------------------------------------------- | | Budget planning | Set target marketing cost % thresholds for profitability | | Margin analysis | Monitor marketing's impact on contribution margin | | Cost benchmarking | Compare marketing spend across periods or segments | | CM3 optimization | Reduce marketing cost % to improve contribution margin | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------ | ------------------------------------------------ | | [Marketing Cost](/reference/metrics/orders/contribution-margin/marketing-cost) | Numerator—total marketing spend | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Denominator—revenue after adjustments | | [CM2 Per Order](/reference/metrics/orders/contribution-margin/cm2-per-order) | Margin before marketing costs are deducted | | [CM3 Per Order](/reference/metrics/orders/contribution-margin/cm3-per-order) | Result after deducting marketing and agency fees | [See all Contribution Margin metrics →](/reference/metrics/orders/contribution-margin) # New Customer Contribution Margin: First-Order Profitability Source: https://docs.upstackdata.com/reference/metrics/orders/contribution-margin/new-customer-contribution-margin Track contribution margin from new customer orders in Upstack. Measures first-time buyer profitability after deducting all variable costs from net revenue. Total contribution margin from new customer orders only—net revenue minus all variable costs for first-time buyers. ## Formula **New Customer Contribution Margin** = [**New Customer Net Revenue**](/reference/metrics/orders/revenue/new-customer-net-revenue) − [**New Customer Total Cost**](/reference/metrics/orders/contribution-margin/new-customer-total-cost) ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | [**New Customer Net Revenue**](/reference/metrics/orders/revenue/new-customer-net-revenue) | Net revenue from first-time buyers after discounts and refunds | | [**New Customer Total Cost**](/reference/metrics/orders/contribution-margin/new-customer-total-cost) | Sum of all variable costs for new customer orders (COGS, fulfillment, transaction, marketing) | | [**customer\_type = new\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from customers making their first purchase | | Metadata | | | --------------- | -------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Sum | *** ## Example Your store generated **\$45,200 in new customer contribution margin** in Q1: | Month | NC Net Revenue | NC Total Cost | NC Contribution Margin | | -------- | -------------- | ------------- | ---------------------- | | January | \$52,400 | \$40,860 | \$11,540 | | February | \$61,200 | \$46,980 | \$14,220 | | March | \$68,500 | \$49,060 | \$19,440 | *** ## How It Works New Customer Contribution Margin isolates profitability from first-time buyer orders. It takes net revenue from new customers (after discounts and refunds) and subtracts all variable costs—COGS, fulfillment, transaction fees, and marketing. The result shows true profit generated from customer acquisition before fixed costs. *** ## When to Use | Scenario | Action | | ---------------------------------- | ------------------------------------------------------------------- | | Evaluate acquisition profitability | Compare NC contribution margin to ad spend for true acquisition ROI | | Set marketing budgets | Use NC contribution margin trends to determine sustainable spend | | Compare customer segments | Benchmark new vs. returning customer profitability | | Forecast unit economics | Project profitability based on expected new customer volume | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------- | | [New Customer Net Revenue](/reference/metrics/orders/revenue/new-customer-net-revenue) | Revenue component before cost deductions | | [New Customer Total Cost](/reference/metrics/orders/contribution-margin/new-customer-total-cost) | Cost component subtracted from revenue | | [Contribution Margin](/reference/metrics/orders/contribution-margin/contribution-margin) | All customers combined | | [Returning Customer Contribution Margin](/reference/metrics/orders/contribution-margin/returning-customer-contribution-margin) | Repeat buyer comparison | [See all Contribution Margin metrics →](/reference/metrics/orders/contribution-margin) # New Customer Contribution Margin %: Acquisition Efficiency Source: https://docs.upstackdata.com/reference/metrics/orders/contribution-margin/new-customer-contribution-margin-percent Track what percentage of new customer revenue remains as contribution margin. Measure acquisition profitability and optimize customer acquisition costs. Percentage of new customer net revenue remaining as contribution margin, filtered by customer\_type = new\_customer. ## Formula **New Customer Contribution Margin %** = ( [**New Customer Contribution Margin**](/reference/metrics/orders/contribution-margin/new-customer-contribution-margin) ÷ [**New Customer Net Revenue**](/reference/metrics/orders/revenue/new-customer-net-revenue) ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | [**New Customer Contribution Margin**](/reference/metrics/orders/contribution-margin/new-customer-contribution-margin) | Total profit from new customers after COGS, fulfillment, transaction, and marketing costs | | [**New Customer Net Revenue**](/reference/metrics/orders/revenue/new-customer-net-revenue) | Net revenue from new customers after discounts and refunds | | [**customer\_type = new\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from first-time buyers only | | Metadata | | | --------------- | -------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Ratio | *** ## Example Your store generated **\$45,200** in new customer contribution margin from **\$125,000** in net revenue, yielding a **36.2%** margin rate: | Customer Type | Net Revenue | Contribution Margin | Margin % | | ------------------- | ----------- | ------------------- | -------- | | New Customers | \$125,000 | \$45,200 | 36.2% | | Returning Customers | \$200,000 | \$142,000 | 71.0% | | All Customers | \$325,000 | \$187,200 | 57.6% | *** ## How It Works This metric divides new customer contribution margin by new customer net revenue to show what portion of acquisition revenue converts to profit. Lower percentages indicate higher relative costs (COGS, fulfillment, marketing) against first-order revenue—common for brands investing heavily in customer acquisition. *** ## When to Use | Scenario | Action | | --------------------------------- | ------------------------------------------------------------------ | | Evaluating acquisition efficiency | Compare margin % between new and returning customers | | Setting CAC targets | Ensure acquisition costs don't exceed acceptable margin thresholds | | Channel optimization | Identify which channels acquire customers with better margins | | Pricing analysis | Determine if new customer promotions erode profitability | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | [New Customer Contribution Margin](/reference/metrics/orders/contribution-margin/new-customer-contribution-margin) | The numerator (dollar amount before percentage) | | [New Customer Net Revenue](/reference/metrics/orders/revenue/new-customer-net-revenue) | The denominator (revenue base for the percentage) | | [Returning Customer Contribution Margin %](/reference/metrics/orders/contribution-margin/returning-customer-contribution-margin-percent) | Same calculation for repeat buyers | | [Contribution Margin %](/reference/metrics/orders/contribution-margin/contribution-margin-percent) | Blended margin across all customer types | [See all Contribution Margin metrics →](/reference/metrics/orders/contribution-margin) # New Customer Marketing Cost: Acquisition Marketing Spend Source: https://docs.upstackdata.com/reference/metrics/orders/contribution-margin/new-customer-marketing-cost Track user-defined marketing costs for new customer orders in Upstack. Includes influencer fees, affiliate commissions, and non-ad marketing spend for first-time buyers. Marketing costs allocated to new customer orders only, filtered by customer\_type = new\_customer. ## Formula **New Customer Marketing Cost** = **Marketing Cost** **WHERE** customer\_type = new\_customer ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | [**Marketing Cost**](/reference/metrics/orders/contribution-margin/marketing-cost) | User-defined marketing costs from order cost entries | | [**customer\_type = new\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from first-time buyers | | Metadata | | | --------------- | --------------------------------------- | | **Type** | Currency | | **Data Source** | [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Sum | *** ## Example Your store allocated **\$8,500 in marketing costs** to new customer orders in Q1: | Month | NC Marketing Cost | NC Orders | Cost Per NC Order | | -------- | ----------------- | --------- | ----------------- | | January | \$2,600 | 412 | \$6.31 | | February | \$2,800 | 458 | \$6.11 | | March | \$3,100 | 521 | \$5.95 | *** ## How It Works New Customer Marketing Cost filters [Marketing Cost](/reference/metrics/orders/contribution-margin/marketing-cost) to orders placed by first-time buyers only. This isolates acquisition-related marketing spend from retention spend, enabling accurate calculation of new customer contribution margin (NC CM3). Configure marketing cost entries in your Upstack cost settings to capture spend not tracked by ad platform integrations. *** ## When to Use | Scenario | Action | | ------------------------------ | ------------------------------------------------------------ | | Calculate NC acquisition costs | Combine with NC Ad Spend for total customer acquisition cost | | Analyze NC contribution margin | Include in NC CM3 to see true first-order profitability | | Compare NC vs RC marketing | Benchmark acquisition vs retention marketing efficiency | | Budget acquisition spend | Track and optimize non-ad marketing for new customers | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | [Marketing Cost](/reference/metrics/orders/contribution-margin/marketing-cost) | All-customer version (NC + RC combined) | | [Returning Customer Marketing Cost](/reference/metrics/orders/contribution-margin/returning-customer-marketing-cost) | Retention counterpart to this metric | | [New Customer Contribution Margin](/reference/metrics/orders/contribution-margin/new-customer-contribution-margin) | Deducts this cost to calculate NC CM3 | | [New Customer Total Cost](/reference/metrics/orders/contribution-margin/new-customer-total-cost) | Sum of all NC cost components | [See all Contribution Margin metrics →](/reference/metrics/orders/contribution-margin) # New Customer Total Cost: Acquisition Cost Stack Source: https://docs.upstackdata.com/reference/metrics/orders/contribution-margin/new-customer-total-cost Track total cost for new customer orders. Understand your complete acquisition cost structure including COGS and marketing. New Customer Total Cost measures the complete cost stack for first-time buyer orders, including all attributed costs for acquisition. ## Formula **NC Total Cost** = **NC COGS** + **NC Fulfillment** + **NC Marketing** + **NC Agency Fees** + **NC Opex** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------------------- | ------------------------------------------- | | [**NC COGS**](/reference/metrics/orders/cogs/new-customer-cogs) | COGS for new customer orders | | [**NC Fulfillment**](/reference/metrics/orders/fulfillment/new-customer-fulfillment-cost) | Fulfillment costs for new customer orders | | **NC Marketing** | Marketing spend attributed to new customers | | [**NC Agency Fees**](/reference/metrics/orders/contribution-margin/new-customer-agency-fees) | Agency fees attributed to new customers | | [**NC Opex**](/reference/metrics/orders/contribution-margin/new-customer-opex) | Opex attributed to new customers | | Metadata | | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Sum | *** ## Example Your Shopify store's new customer orders incurred: | Cost Component | Value | | ----------------- | ------------ | | NC COGS | \$18,000 | | NC Fulfillment | \$4,000 | | NC Marketing | \$20,000 | | NC Agency Fees | \$4,000 | | NC Opex | \$6,000 | | **NC Total Cost** | **\$52,000** | An NC total cost of \$52,000 represents your complete investment in acquiring new customers. *** ## How It Works NC Total Cost aggregates all costs attributed to new customer acquisition. This includes the costs of products they buy, shipping their orders, and the marketing investment needed to acquire them. *** ## When to Use | Scenario | Action | | ------------------------- | -------------------------------------- | | Acquisition profitability | Compare NC total cost to NC revenue | | CAC calculation | Understand true cost to acquire | | Budget planning | Allocate resources to acquisition | | NC vs RC comparison | Compare acquisition vs retention costs | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------- | ---------------------------------------- | | [Total Cost](/reference/metrics/orders/contribution-margin/total-cost) | Total cost for all orders | | [RC Total Cost](/reference/metrics/orders/contribution-margin/returning-customer-total-cost) | Total cost for returning customer orders | | [NC Revenue](/reference/metrics/orders/revenue/new-customer-net-revenue) | Revenue generated by new customers | | [NC CM3](/reference/metrics/orders/contribution-margin/new-customer-cm3) | NC profit after all variable costs | [See all Contribution Margin metrics →](/reference/metrics/orders/contribution-margin) # New Customer Total Cost %: Cost Structure Analysis Source: https://docs.upstackdata.com/reference/metrics/orders/contribution-margin/new-customer-total-cost-percent Measure total costs for new customers as a percentage of net revenue. Understand acquisition cost structure and profitability before margin analysis. Total cost as a percentage of new customer net revenue, filtered to first-time buyers only. ## Formula **New Customer Total Cost %** = ( [**New Customer Total Cost**](/reference/metrics/orders/contribution-margin/new-customer-total-cost) ÷ [**New Customer Net Revenue**](/reference/metrics/orders/revenue/new-customer-net-revenue) ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | [**New Customer Total Cost**](/reference/metrics/orders/contribution-margin/new-customer-total-cost) | Sum of all costs allocated to new customer orders (COGS, fulfillment, marketing, overhead) | | [**New Customer Net Revenue**](/reference/metrics/orders/revenue/new-customer-net-revenue) | Revenue from new customers after discounts and refunds | | [**customer\_type = new\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from customers making their first purchase | | Metadata | | | --------------- | -------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Ratio | *** ## Example Your store spent **62%** of new customer net revenue on total costs in Q1: | Cost Category | Amount | % of NC Revenue | | -------------- | ------------ | --------------- | | COGS | \$18,500 | 37% | | Variable Costs | \$6,250 | 12.5% | | Marketing | \$5,000 | 10% | | Other | \$1,250 | 2.5% | | **Total Cost** | **\$31,000** | **62%** | With \$50,000 in new customer net revenue, **38%** remains as contribution margin. *** ## How It Works New Customer Total Cost % sums all costs attributed to first-time buyer orders—including product costs (COGS), variable fulfillment costs, marketing spend, and overhead—then divides by net revenue. This shows how much of each new customer dollar is consumed by costs before profit. *** ## When to Use | Scenario | Action | | ------------------------- | ------------------------------------------------------ | | Acquisition cost analysis | Identify cost drivers eating into new customer margins | | Budget planning | Determine sustainable CAC based on total cost burden | | Efficiency benchmarking | Compare total cost % against returning customers | | Profitability alerts | Flag when costs exceed acceptable thresholds | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | [New Customer Contribution Margin %](/reference/metrics/orders/contribution-margin/new-customer-contribution-margin-percent) | The inverse—profit remaining after costs (100% minus cost %) | | [New Customer Net Revenue](/reference/metrics/orders/revenue/new-customer-net-revenue) | The denominator for this calculation | | [Returning Customer Total Cost %](/reference/metrics/orders/contribution-margin/returning-customer-total-cost-percent) | Same metric for repeat buyers—compare to evaluate customer economics | | [Total Cost %](/reference/metrics/orders/contribution-margin/total-cost-percent) | All customers combined (this metric filters to new only) | [See all Contribution Margin metrics →](/reference/metrics/orders/contribution-margin) # Returning Customer Contribution Margin: Repeat Buyer Profitability Source: https://docs.upstackdata.com/reference/metrics/orders/contribution-margin/returning-customer-contribution-margin Track contribution margin from returning customer orders in Upstack. Measures repeat buyer profitability after deducting all variable costs from net revenue. Total contribution margin from returning customer orders only—net revenue minus all variable costs for repeat buyers. ## Formula **Returning Customer Contribution Margin** = [**Returning Customer Net Revenue**](/reference/metrics/orders/revenue/returning-customer-net-revenue) − **Returning Customer Total Cost** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | [**Returning Customer Net Revenue**](/reference/metrics/orders/revenue/returning-customer-net-revenue) | Net revenue from repeat buyers after discounts and refunds | | **Returning Customer Total Cost** | Sum of all variable costs for returning customer orders (COGS, fulfillment, transaction, marketing) | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from customers who have purchased before | | Metadata | | | --------------- | -------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Sum | *** ## Example Your store generated **\$62,800 in returning customer contribution margin** in Q1: | Month | RC Net Revenue | RC Total Cost | RC Contribution Margin | | -------- | -------------- | ------------- | ---------------------- | | January | \$78,200 | \$52,340 | \$25,860 | | February | \$84,500 | \$57,260 | \$27,240 | | March | \$91,300 | \$81,600 | \$9,700 | *** ## How It Works Returning Customer Contribution Margin isolates profitability from repeat buyer orders. It takes net revenue from returning customers (after discounts and refunds) and subtracts all variable costs—COGS, fulfillment, transaction fees, and marketing. The result shows true profit generated by repeat customers before fixed costs. *** ## When to Use | Scenario | Action | | -------------------------------- | ------------------------------------------------------------------------ | | Evaluate retention profitability | Compare RC contribution margin to retention spend for true retention ROI | | Set retention budgets | Use RC contribution margin trends to determine sustainable loyalty spend | | Compare customer segments | Benchmark returning vs. new customer profitability | | Forecast unit economics | Project profitability based on expected returning customer volume | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | [Returning Customer Net Revenue](/reference/metrics/orders/revenue/returning-customer-net-revenue) | Revenue component before cost deductions | | [Contribution Margin](/reference/metrics/orders/contribution-margin/contribution-margin) | All customers combined | | [New Customer Contribution Margin](/reference/metrics/orders/contribution-margin/new-customer-contribution-margin) | First-time buyer comparison | | [Returning Customer Contribution Margin %](/reference/metrics/orders/contribution-margin/returning-customer-contribution-margin-percent) | Same metric as a percentage of RC Net Revenue | [See all Contribution Margin metrics →](/reference/metrics/orders/contribution-margin) # Returning Customer Contribution Margin %: Repeat Buyer Profitability Rate Source: https://docs.upstackdata.com/reference/metrics/orders/contribution-margin/returning-customer-contribution-margin-percent Track the percentage of returning customer net revenue remaining as contribution margin. Measure repeat buyer profitability rate. Percentage of returning customer net revenue remaining as contribution margin. ## Formula **Returning Customer Contribution Margin %** = ( **Returning Customer Contribution Margin** ÷ **Returning Customer Net Revenue** ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | [**Returning Customer Contribution Margin**](/reference/metrics/orders/contribution-margin/returning-customer-contribution-margin) | Profit from returning customers after COGS, fulfillment, transaction, and marketing costs | | [**Returning Customer Net Revenue**](/reference/metrics/orders/revenue/returning-customer-net-revenue) | Revenue from returning customers after discounts and refunds | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from customers who have purchased before | | Metadata | | | --------------- | -------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Ratio | *** ## Example Your returning customers generated **\$89,640** in net revenue with **\$31,374** in contribution margin, yielding a **35%** margin rate: | Metric | Value | | ---------------------------- | -------- | | RC Net Revenue | \$89,640 | | RC Contribution Margin | \$31,374 | | **RC Contribution Margin %** | **35%** | *** ## How It Works Returning Customer Contribution Margin % measures what share of repeat buyer revenue becomes profit after all variable costs. A higher percentage indicates returning customers are more profitable per dollar of revenue, helping you evaluate retention economics. *** ## When to Use | Scenario | Action | | --------------------------- | -------------------------------------------------------------------- | | Compare customer segments | Benchmark RC margin % vs NC margin % to see retention profitability | | Evaluate retention programs | Track if loyalty discounts erode repeat buyer margins | | Assess marketing efficiency | Higher margin % means more profit per marketing dollar on retention | | Set pricing strategy | Low margins may indicate need for price adjustments on repeat orders | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- | | [Returning Customer Contribution Margin](/reference/metrics/orders/contribution-margin/returning-customer-contribution-margin) | The dollar amount numerator of this percentage | | [Returning Customer Net Revenue](/reference/metrics/orders/revenue/returning-customer-net-revenue) | The denominator; total RC revenue after adjustments | | [New Customer Contribution Margin %](/reference/metrics/orders/contribution-margin/new-customer-contribution-margin-percent) | Compare acquisition vs retention profitability | | [Contribution Margin %](/reference/metrics/orders/contribution-margin/contribution-margin-percent) | Blended margin across all customers | [See all Contribution Margin metrics →](/reference/metrics/orders/contribution-margin) # Returning Customer Marketing Cost: Retention Marketing Spend Source: https://docs.upstackdata.com/reference/metrics/orders/contribution-margin/returning-customer-marketing-cost Track marketing costs allocated to returning customer orders in Upstack. Filtered by customer_type to isolate retention marketing spend for contribution margin analysis. Marketing costs allocated to returning customer orders, filtered by customer\_type = returning\_customer. ## Formula **Returning Customer Marketing Cost** = [**Marketing Cost**](/reference/metrics/orders/contribution-margin/marketing-cost) **WHERE** [customer\_type = returning\_customer](/data-dictionary/measures-and-dimensions#visitor-dimensions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | [**Marketing Cost**](/reference/metrics/orders/contribution-margin/marketing-cost) | User-defined marketing costs from order cost entries | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from customers who have purchased before | | Metadata | | | --------------- | --------------------------------------- | | **Type** | Currency | | **Data Source** | [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Sum | *** ## Example Your store allocated **\$7,800 in marketing costs to returning customers** in Q1: | Month | RC Marketing Cost | RC Orders | Cost Per Order | | -------- | ----------------- | --------- | -------------- | | January | \$2,400 | 892 | \$2.69 | | February | \$2,600 | 978 | \$2.66 | | March | \$2,800 | 1,064 | \$2.63 | *** ## How It Works Returning Customer Marketing Cost filters [Marketing Cost](/reference/metrics/orders/contribution-margin/marketing-cost) to include only orders where [customer\_type = returning\_customer](/data-dictionary/measures-and-dimensions#visitor-dimensions). This isolates retention marketing spend from acquisition spend, enabling accurate calculation of returning customer contribution margin. *** ## When to Use | Scenario | Action | | -------------------------------- | ------------------------------------------------------------------------- | | Track retention marketing spend | Capture loyalty program costs, email marketing, or referral rewards | | Calculate RC contribution margin | Include all returning customer marketing costs for accurate profitability | | Compare NC vs RC marketing | Separate acquisition vs retention marketing investment | | Budget retention spend | Track and optimize marketing costs for repeat customers | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- | | [Marketing Cost](/reference/metrics/orders/contribution-margin/marketing-cost) | Unfiltered version across all customers | | [New Customer Marketing Cost](/reference/metrics/orders/contribution-margin/new-customer-marketing-cost) | Acquisition counterpart filtered by new customers | | [Returning Customer Contribution Margin](/reference/metrics/orders/contribution-margin/returning-customer-contribution-margin) | Deducts this cost to calculate RC CM3 | | [Total Cost](/reference/metrics/orders/contribution-margin/total-cost) | All costs combined | [See all Contribution Margin metrics →](/reference/metrics/orders/contribution-margin) # Returning Customer Total Cost %: Cost Structure Analysis Source: https://docs.upstackdata.com/reference/metrics/orders/contribution-margin/returning-customer-total-cost-percent Measure total costs for returning customers as a percentage of net revenue. Understand repeat buyer cost structure and compare against new customer economics. The total costs for returning customer orders expressed as a percentage of their net revenue. ## Formula **Returning Customer Total Cost %** = ( **Returning Customer Total Cost** ÷ **Returning Customer Net Revenue** ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | **Returning Customer Total Cost** | Sum of all costs allocated to returning customer orders (COGS, fulfillment, transaction, marketing) | | [**Returning Customer Net Revenue**](/reference/metrics/orders/revenue/returning-customer-net-revenue) | Revenue from returning customers after discounts and refunds | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from customers who have purchased before | | Metadata | | | --------------- | -------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Ratio | *** ## Example Your store spent **48%** of returning customer net revenue on total costs in Q1: | Cost Category | Amount | % of RC Revenue | | -------------- | ------------ | --------------- | | COGS | \$37,500 | 30% | | Variable Costs | \$11,250 | 9% | | Marketing | \$7,500 | 6% | | Other | \$3,750 | 3% | | **Total Cost** | **\$60,000** | **48%** | With \$125,000 in returning customer net revenue, **52%** remains as operating profit margin. *** ## How It Works Returning Customer Total Cost % sums all costs attributed to repeat buyer orders—including product costs (COGS), variable fulfillment costs, marketing spend, and transaction fees—then divides by net revenue. This shows how much of each returning customer dollar is consumed by costs before profit. *** ## When to Use | Scenario | Action | | -------------------------------- | ------------------------------------------------------------------ | | Retention profitability analysis | Verify repeat buyers have lower cost % than new customers | | Loyalty program ROI | Check if retention discounts inflate total cost % | | Efficiency benchmarking | Compare RC cost % against NC cost % to validate retention strategy | | Margin optimization | Identify cost drivers specific to repeat orders | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | | [Returning Customer Contribution Margin](/reference/metrics/orders/contribution-margin/returning-customer-contribution-margin) | Operating profit margin (100% minus cost %) | | [Returning Customer Net Revenue](/reference/metrics/orders/revenue/returning-customer-net-revenue) | The denominator for this calculation | | [New Customer Total Cost %](/reference/metrics/orders/contribution-margin/new-customer-total-cost-percent) | Same metric for first-time buyers—compare to evaluate customer economics | | [Total Cost %](/reference/metrics/orders/contribution-margin/total-cost-percent) | Blended cost % across all customers | [See all Contribution Margin metrics →](/reference/metrics/orders/contribution-margin) # Total Cost: Complete Order Cost Stack Source: https://docs.upstackdata.com/reference/metrics/orders/contribution-margin/total-cost Track total cost per order including COGS, fulfillment, marketing, and overhead. Understand your complete cost structure. Total Cost measures the complete cost stack for your orders, including COGS, fulfillment, marketing costs, agency fees, and operating expenses. ## Formula **Total Cost** = **COGS** + **Fulfillment** + **Marketing** + **Agency Fees** + **Opex** ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------- | ------------------------------- | | [**COGS**](/reference/metrics/orders/cogs/cogs) | Cost of goods sold for products | | [**Fulfillment**](/reference/metrics/orders/fulfillment/fulfillment-cost) | Shipping and handling costs | | [**Marketing**](/reference/metrics/orders/performance/total-ad-spend) | Total advertising spend | | [**Agency Fees**](/reference/metrics/orders/contribution-margin/agency-fees) | Marketing agency costs | | [**Opex**](/reference/metrics/orders/contribution-margin/opex) | Operating expenses | | Metadata | | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Sum | *** ## Example Your Shopify store incurred the following costs: | Cost Component | Value | | -------------- | ------------ | | COGS | \$40,000 | | Fulfillment | \$8,000 | | Marketing | \$25,000 | | Agency Fees | \$5,000 | | Opex | \$12,000 | | **Total Cost** | **\$90,000** | A total cost of \$90,000 means you need at least \$90K in revenue to break even. *** ## How It Works Total Cost aggregates all cost categories attributed to your orders. This includes direct product costs (COGS), logistics (fulfillment), customer acquisition (marketing), and operating overhead. It's the complete picture of what it costs to generate your revenue. *** ## When to Use | Scenario | Action | | ---------------------- | --------------------------------- | | Profitability analysis | Compare total cost to revenue | | Break-even planning | Understand minimum revenue needed | | Cost optimization | Identify largest cost drivers | | Budget allocation | See where money is being spent | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------- | ---------------------------------------- | | [NC Total Cost](/reference/metrics/orders/contribution-margin/new-customer-total-cost) | Total cost for new customer orders | | [RC Total Cost](/reference/metrics/orders/contribution-margin/returning-customer-total-cost) | Total cost for returning customer orders | | [Net Profit](/reference/metrics/orders/contribution-margin/net-profit) | Revenue minus total cost | | [CM3](/reference/metrics/orders/contribution-margin/cm3) | Profit after all variable costs | [See all Contribution Margin metrics →](/reference/metrics/orders/contribution-margin) # Total Cost %: All Costs as Share of Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/contribution-margin/total-cost-percent Track total costs as a percentage of net revenue. Understand what portion of revenue is consumed by all variable costs. Total cost as a percentage of net revenue, showing what portion of revenue is consumed by all variable costs. ## Formula **Total Cost %** = ( **Total Cost** ÷ **Net Revenue** ) × 100 ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | [**Total Cost**](/reference/metrics/orders/contribution-margin/total-cost) | Sum of all variable costs: COGS + fulfillment + transaction + marketing costs | | [**Net Revenue**](/reference/metrics/orders/revenue/net-revenue) | Gross revenue minus refunds and discounts | | Metadata | | | --------------- | -------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Ratio | *** ## Example Your store generated **\$125,000** in net revenue with **\$87,500** in total costs, resulting in a **70%** Total Cost %. | Cost Category | Amount | % of Revenue | | ------------------ | ------------ | ------------ | | COGS | \$43,750 | 35% | | Fulfillment | \$12,500 | 10% | | Transaction | \$3,750 | 3% | | Marketing | \$21,250 | 17% | | Agency Fees + Opex | \$6,250 | 5% | | **Total Cost** | **\$87,500** | **70%** | *** ## How It Works Total Cost % aggregates all cost categories—COGS, fulfillment, transaction fees, and marketing expenses—and expresses them as a percentage of net revenue. A lower percentage indicates better overall margin efficiency. This metric is the inverse of your [Contribution Margin %](/reference/metrics/orders/contribution-margin/contribution-margin-percent). *** ## When to Use | Scenario | Action | | ------------------- | ------------------------------------------------------------ | | Margin health check | Monitor overall cost structure relative to revenue | | Cost optimization | Identify which cost categories consume the most margin | | Pricing decisions | Understand if prices support your cost structure | | Benchmarking | Compare cost efficiency across time periods or product lines | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | -------------------------------------- | | [Total Cost](/reference/metrics/orders/contribution-margin/total-cost) | The numerator in this calculation | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | The denominator in this calculation | | [Contribution Margin %](/reference/metrics/orders/contribution-margin/contribution-margin-percent) | The inverse: 100% minus Total Cost % | | [COGS](/reference/metrics/orders/cogs/cogs) | Largest cost component for most stores | [See all Contribution Margin metrics →](/reference/metrics/orders/contribution-margin) # Order Counts: Track Order Volume and Units Sold Source: https://docs.upstackdata.com/reference/metrics/orders/counts/index Track order volume metrics in Upstack. Includes Orders, Units Sold, Units Per Order, and Subscription metrics with formulas and examples. Order count metrics track the volume of orders and products sold. Use these to measure sales velocity, basket size, and subscription acquisition. **Data Source:** [Shopify](/sources/shopify)\ **Metrics:** 9 ## Metrics in This Group | Metric | Description | When to Use | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | --------------------------------- | | [Orders](/reference/metrics/orders/counts/orders) | Total number of orders placed | Measure overall sales volume | | [Units Sold](/reference/metrics/orders/counts/units-sold) | Total product units sold | Track inventory movement | | [New Customer Units Sold](/reference/metrics/orders/counts/new-customer-units-sold) | Units sold to new customers | Analyze new customer basket size | | [Returning Customer Units Sold](/reference/metrics/orders/counts/returning-customer-units-sold) | Units sold to returning customers | Compare returning vs new behavior | | [Units Per Order](/reference/metrics/orders/counts/units-per-order) | Average units per order | Optimize bundle offers | | [New Customer Units Per Order](/reference/metrics/orders/counts/new-customer-units-per-order) | Average units per new customer order | Benchmark new customer baskets | | [Returning Customer Units Per Order](/reference/metrics/orders/counts/returning-customer-units-per-order) | Average units per returning customer order | Track loyalty basket growth | | [Subscription Initial Purchase Orders](/reference/metrics/orders/counts/subscription-initial-purchase-orders) | First-time subscription orders | Measure subscription acquisition | | [Subscription Initial Purchase %](/reference/metrics/orders/counts/subscription-initial-purchase-percent) | Percentage of orders that are subscription initial purchases | Track subscription mix | ## How These Metrics Relate * **Orders** is the foundational count of all completed transactions * **Units Sold** measures total product quantity across all orders * **Units Per Order** = Units Sold ÷ Orders (basket size indicator) * **Subscription metrics** track the subset of orders that start new subscriptions ## Choosing the Right Metric * **Volume tracking**: Use Orders for transaction counts, Units Sold for inventory * **Basket optimization**: Use Units Per Order to identify upsell opportunities * **Customer segmentation**: Compare New vs Returning customer metrics to identify behavior differences * **Subscription health**: Use Subscription Initial Purchase % to track subscription mix trends # New Customer Units Per Order: First-Purchase Basket Size Source: https://docs.upstackdata.com/reference/metrics/orders/counts/new-customer-units-per-order Track average units per order for new customers to understand first-purchase basket behavior. Compare against returning customers to optimize acquisition. The average number of product units included in each new customer's order. ## Formula **New Customer Units Per Order** = [**New Customer Units Sold**](/reference/metrics/orders/counts/new-customer-units-sold) ÷ **New Customer Orders** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [**New Customer Units Sold**](/reference/metrics/orders/counts/new-customer-units-sold) | Total product units purchased by first-time buyers | | **New Customer Orders** | Count of orders placed by first-time customers | | [**customer\_type = new\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filter applied to both numerator and denominator | | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store's new customers averaged **2.4 units per order** in January: | Segment | Units/Order | Orders | Total Units | | ------------------- | ----------- | ------ | ----------- | | New Customers | 2.4 | 1,850 | 4,440 | | Returning Customers | 3.1 | 2,200 | 6,820 | | All Customers | 2.8 | 4,050 | 11,260 | *** ## How It Works This metric divides total units purchased by new customers by the number of first-time orders. It measures initial basket size behavior, helping you understand whether new customers buy single items or multiple products on their first visit. *** ## When to Use | Scenario | Action | | ------------------------------ | ----------------------------------------------------- | | Analyzing acquisition quality | Compare new vs. returning to spot basket size gaps | | Optimizing product bundles | Track if bundle promotions increase first-order units | | Evaluating channel performance | Identify which channels bring customers who buy more | | Forecasting inventory | Project unit demand from new customer acquisition | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | [New Customer Units Sold](/reference/metrics/orders/counts/new-customer-units-sold) | Numerator: total units from new customers | | [Units Per Order](/reference/metrics/orders/counts/units-per-order) | Overall average across all customer types | | [Returning Customer Units Per Order](/reference/metrics/orders/counts/returning-customer-units-per-order) | Comparison metric for repeat buyers | | [New Customers](/reference/metrics/orders/customers/new-customers) | Count of first-time buyers | [See all Order Counts metrics →](/reference/metrics/orders/counts) # New Customer Units Sold: First-Time Buyer Quantity Source: https://docs.upstackdata.com/reference/metrics/orders/counts/new-customer-units-sold Track product units purchased by first-time customers. Measure acquisition basket size and compare to returning customers for retention insights. Total product units purchased by new customers in first-time orders. ## Formula **New Customer Units Sold** = **SUM** ( Units ) **WHERE** [customer\_type = new\_customer](/data-dictionary/measures-and-dimensions#visitor-dimensions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------- | ---------------------------------------- | | **Units** | Product quantity from order line items | | [**customer\_type = new\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from first-time buyers | | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store sold **2,847 units** to new customers this month: | Week | NC Units | NC Orders | Units/Order | | ------ | -------- | --------- | ----------- | | Week 1 | 712 | 285 | 2.5 | | Week 2 | 698 | 310 | 2.3 | | Week 3 | 745 | 298 | 2.5 | | Week 4 | 692 | 277 | 2.5 | *** ## How It Works New Customer Units Sold sums the quantity of all line items from orders placed by first-time customers. A customer is classified as "new" if the order is their first recorded purchase in Shopify. This metric helps you understand how many products new customers buy in their initial transaction. *** ## When to Use | Scenario | Action | | --------------------------------- | ------------------------------------------------------------------ | | Measuring acquisition basket size | Compare units per order for new vs returning customers | | Evaluating bundle promotions | Track if first-time buyers purchase more units after bundle launch | | Inventory planning | Forecast demand from new customer acquisition campaigns | | Retention analysis | Benchmark against returning customer units to measure loyalty | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------- | ------------------------------------------------- | | [Units Sold](/reference/metrics/orders/counts/units-sold) | Total units across all customers | | [Returning Customer Units Sold](/reference/metrics/orders/counts/returning-customer-units-sold) | Units from repeat buyers (compare to this metric) | | [New Customer Units Per Order](/reference/metrics/orders/counts/new-customer-units-per-order) | This metric ÷ New Customer Orders | | [New Customers](/reference/metrics/orders/customers/new-customers) | Count of first-time buyers | [See all Order Counts metrics →](/reference/metrics/orders/counts) # Orders: Total Order Count Source: https://docs.upstackdata.com/reference/metrics/orders/counts/orders Track total orders placed in your Shopify store. Learn how order count drives revenue analysis, customer segmentation, and fulfillment planning. The total number of orders placed in the selected period. ## Formula **Total Orders** = **COUNT** ( Orders ) **WHERE** [status = completed](/data-dictionary/measures-and-dimensions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------ | ---------------------------------------------- | | **Orders** | Each completed checkout transaction in Shopify | | [**status = completed**](/data-dictionary/measures-and-dimensions) | Excludes cancelled and fully refunded orders | | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Count | *** ## Example Your store received **1,247 orders** in January: | Week | Orders | Trend | | ------ | ------ | -------------- | | Week 1 | 287 | Baseline | | Week 2 | 312 | +8.7% | | Week 3 | 298 | −4.5% | | Week 4 | 350 | +17.4% (promo) | *** ## How It Works Orders counts every completed checkout in Shopify. Each transaction counts as one order regardless of quantity purchased. Cancelled and fully refunded orders are excluded. *** ## When to Use | Scenario | Action | | --------------------- | ---------------------------------------------------- | | Volume trending | Monitor order count over time to spot demand changes | | Conversion analysis | Combine with sessions to calculate conversion rate | | Fulfillment planning | Forecast staffing and inventory needs | | Customer segmentation | Break down by new vs returning customers | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------ | ------------------------------------- | | [Units Sold](/reference/metrics/orders/counts/units-sold) | Total product units across all orders | | [Units Per Order](/reference/metrics/orders/counts/units-per-order) | Average basket size in units | | [Unique Customers](/reference/metrics/orders/customers/unique-customers) | Distinct buyers who placed orders | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | Monetary value of all orders | | [Total AOV](/reference/metrics/orders/aov/total-aov) | Revenue ÷ Orders | [See all Order Counts metrics →](/reference/metrics/orders/counts) # Returning Customer Units Per Order: Repeat Buyer Basket Size Source: https://docs.upstackdata.com/reference/metrics/orders/counts/returning-customer-units-per-order Track average units per order for returning customers to measure repeat buyer basket size. Compare against new customers to identify loyalty-driven purchasing patterns. The average number of product units included in each returning customer's order. ## Formula **Returning Customer Units Per Order** = [**Returning Customer Units Sold**](/reference/metrics/orders/counts/returning-customer-units-sold) ÷ **Returning Customer Orders** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [**Returning Customer Units Sold**](/reference/metrics/orders/counts/returning-customer-units-sold) | Total product units purchased by repeat buyers | | **Returning Customer Orders** | Count of orders placed by returning customers | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filter applied to both numerator and denominator | | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store's returning customers averaged **3.1 units per order** in January: | Segment | Units/Order | Orders | Total Units | | ------------------- | ----------- | ------ | ----------- | | Returning Customers | 3.1 | 2,200 | 6,820 | | New Customers | 2.4 | 1,850 | 4,440 | | All Customers | 2.8 | 4,050 | 11,260 | *** ## How It Works This metric divides total units purchased by returning customers by the number of repeat orders. Higher values than new customers suggest that loyal buyers are more comfortable adding multiple items to their cart, indicating trust and familiarity with your product catalog. *** ## When to Use | Scenario | Action | | -------------------------------- | ----------------------------------------------------------------- | | Measuring loyalty impact | Compare against new customers to quantify repeat buyer engagement | | Evaluating retention programs | Track if loyalty perks increase basket size over time | | Optimizing cross-sell strategies | Identify if returning customers respond to bundle offers | | Forecasting inventory | Project unit demand from your retained customer base | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------- | ----------------------------------------------- | | [Returning Customer Units Sold](/reference/metrics/orders/counts/returning-customer-units-sold) | Numerator: total units from returning customers | | [Units Per Order](/reference/metrics/orders/counts/units-per-order) | Overall average across all customer types | | [New Customer Units Per Order](/reference/metrics/orders/counts/new-customer-units-per-order) | Comparison metric for first-time buyers | | [Returning Customers](/reference/metrics/orders/customers/returning-customers) | Count of repeat buyers | [See all Order Counts metrics →](/reference/metrics/orders/counts) # Returning Customer Units Sold: Repeat Buyer Quantity Source: https://docs.upstackdata.com/reference/metrics/orders/counts/returning-customer-units-sold Track total product units purchased by returning customers. Analyze repeat buyer basket size and loyalty trends compared to first-time buyers. Total product units purchased by returning customers who have previously placed an order. ## Formula **Returning Customer Units Sold** = **SUM** ( Units ) **WHERE** [customer\_type = returning\_customer](/data-dictionary/measures-and-dimensions#visitor-dimensions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | **Units** | Product quantity from order line items | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to orders from customers who have purchased before | | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store sold **5,895 units** to returning customers this month: | Week | RC Units | RC Orders | Units/Order | | ------ | -------- | --------- | ----------- | | Week 1 | 1,412 | 398 | 3.5 | | Week 2 | 1,523 | 435 | 3.5 | | Week 3 | 1,489 | 426 | 3.5 | | Week 4 | 1,471 | 420 | 3.5 | *** ## How It Works Returning Customer Units Sold sums the quantity of all line items from orders placed by customers who have previously purchased. A customer is classified as "returning" if they have at least one prior order in Shopify. This metric helps you understand the purchasing volume of your loyal customer base. *** ## When to Use | Scenario | Action | | ----------------------------- | --------------------------------------------------------------- | | Measuring loyalty basket size | Compare units per order for returning vs new customers | | Evaluating retention programs | Track if repeat buyers purchase more units after loyalty launch | | Inventory planning | Forecast demand from returning customer segments | | Lifetime value analysis | Monitor unit volume growth from your retained base | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | [Units Sold](/reference/metrics/orders/counts/units-sold) | Total units across all customers | | [New Customer Units Sold](/reference/metrics/orders/counts/new-customer-units-sold) | Units from first-time buyers (compare to this metric) | | [Returning Customer Units Per Order](/reference/metrics/orders/counts/returning-customer-units-per-order) | This metric ÷ Returning Customer Orders | | [Returning Customers](/reference/metrics/orders/customers/returning-customers) | Count of repeat buyers | [See all Order Counts metrics →](/reference/metrics/orders/counts) # Subscription Initial Purchase Orders: First-Time Subscription Count Source: https://docs.upstackdata.com/reference/metrics/orders/counts/subscription-initial-purchase-orders Track first-time subscription orders in Shopify. Measure subscription acquisition, analyze program growth, and optimize your recurring revenue strategy. The count of orders where a customer starts a new subscription for the first time. ## Formula **Subscription Initial Purchase Orders** = **COUNT** ( Orders ) **WHERE** [order\_type = subscription\_initial\_purchase](/data-dictionary/measures-and-dimensions) ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | **Orders** | Each completed checkout transaction | | [**order\_type = subscription\_initial\_purchase**](/data-dictionary/measures-and-dimensions) | Filters to orders where a customer starts their first subscription | | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Count | *** ## Example Your store acquired **324 new subscribers** in Q1: | Month | New Subscriptions | Growth | | -------- | ----------------- | -------- | | January | 98 | Baseline | | February | 107 | +9.2% | | March | 119 | +11.2% | *** ## How It Works This metric counts orders where a customer subscribes for the first time. It excludes recurring subscription renewals and one-time purchases. Use it to measure subscription program acquisition separate from retention. *** ## When to Use | Scenario | Action | | ------------------------- | ------------------------------------------------------ | | Program growth tracking | Monitor new subscriber acquisition over time | | Campaign attribution | Identify which campaigns drive subscription signups | | Subscription mix analysis | Compare initial subscriptions to total orders | | LTV forecasting | Estimate future recurring revenue from new subscribers | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | [Orders](/reference/metrics/orders/counts/orders) | Total orders (includes all order types) | | [Subscription Initial Purchase %](/reference/metrics/orders/counts/subscription-initial-purchase-percent) | Initial subscriptions as percentage of total orders | | [New Customers](/reference/metrics/orders/customers/new-customers) | First-time buyers (different from first-time subscribers) | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | Revenue from all orders including subscriptions | [See all Order Counts metrics →](/reference/metrics/orders/counts) # Subscription Initial Purchase %: Percentage of Subscription Orders Source: https://docs.upstackdata.com/reference/metrics/orders/counts/subscription-initial-purchase-percent Measure what percentage of your orders are subscription initial purchases. Track subscription acquisition trends and forecast recurring revenue. The percentage of total orders that are subscription initial purchases. ## Formula **Subscription Initial Purchase %** = ( [**Subscription Initial Purchase Orders**](/reference/metrics/orders/counts/subscription-initial-purchase-orders) ÷ [**Orders**](/reference/metrics/orders/counts/orders) ) × 100 ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | [**Subscription Initial Purchase Orders**](/reference/metrics/orders/counts/subscription-initial-purchase-orders) | Orders where a customer starts a new subscription | | [**Orders**](/reference/metrics/orders/counts/orders) | Total orders in the selected period | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store received **2,450 orders** in March, with **367 subscription initial purchases** — a rate of **14.98%**: | Period | Orders | Initial Subs | Rate | | -------- | ------ | ------------ | ------ | | Week 1–2 | 1,180 | 165 | 13.98% | | Week 3–4 | 1,270 | 202 | 15.91% | *** ## How It Works Subscription initial purchases are identified by matching a `subscription_initial_purchase` event with the same order ID. This excludes recurring renewals and one-time purchases. *** ## When to Use | Scenario | Action | | ---------------------------- | -------------------------------------------------- | | Tracking subscription growth | Monitor rate changes week-over-week | | Evaluating campaigns | Compare rates across subscriber-targeted campaigns | | Forecasting LTV | Higher rates indicate more recurring revenue | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | [Subscription Initial Purchase Orders](/reference/metrics/orders/counts/subscription-initial-purchase-orders) | Numerator: count of initial subscriptions | | [Orders](/reference/metrics/orders/counts/orders) | Denominator: total order count | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | Revenue context for subscription mix | [See all Order Counts metrics →](/reference/metrics/orders/counts) # Units Per Order: Average Basket Quantity Source: https://docs.upstackdata.com/reference/metrics/orders/counts/units-per-order Track the average number of product units per order to measure basket size. Optimize bundling, cross-sells, and product mix to increase order volume. The average number of product units included in each order. ## Formula **Units Per Order** = [**Units Sold**](/reference/metrics/orders/counts/units-sold) ÷ [**Orders**](/reference/metrics/orders/counts/orders) ### Formula Components | Metric | Definition | | ------------------------------------------------------------- | --------------------------------------------- | | [**Units Sold**](/reference/metrics/orders/counts/units-sold) | Total product quantity sold across all orders | | [**Orders**](/reference/metrics/orders/counts/orders) | Total number of completed orders | | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store averaged **3.0 units per order** in March with 2,914 orders: | Week | Orders | Units Sold | Units/Order | | ------ | ------ | ---------- | ----------- | | Week 1 | 687 | 1,923 | 2.8 | | Week 2 | 712 | 2,279 | 3.2 | | Week 3 | 745 | 2,384 | 3.2 | | Week 4 | 770 | 2,156 | 2.8 | *** ## How It Works Units Per Order divides total units sold by total orders. Higher values indicate customers are adding more items per transaction—either through bundles, cross-sells, or natural multi-item purchases. *** ## When to Use | Scenario | Action | | --------------------- | -------------------------------------------------------------------- | | Low units per order | Test product bundles or "frequently bought together" recommendations | | Declining trend | Review cross-sell placements, shipping thresholds, or product mix | | Comparing segments | Analyze new vs. returning customer basket sizes | | Evaluating promotions | Measure impact of volume discounts or bundle offers | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------- | ---------------------------------------- | | [Units Sold](/reference/metrics/orders/counts/units-sold) | Numerator: total product quantity | | [Orders](/reference/metrics/orders/counts/orders) | Denominator: transaction count | | [NC Units Per Order](/reference/metrics/orders/counts/new-customer-units-per-order) | Same formula for new customers only | | [Total AOV](/reference/metrics/orders/aov/total-aov) | Revenue version—measures value per order | [See all Order Counts metrics →](/reference/metrics/orders/counts) # Units Sold: Total Product Quantity Sold Source: https://docs.upstackdata.com/reference/metrics/orders/counts/units-sold Track total product units sold across all orders. Monitor inventory movement, basket sizes, and product demand with this e-commerce metric. The total quantity of individual product units sold across all orders in the selected period. ## Formula **Units Sold** = **SUM** ( Quantity ) **FOR EACH** Line Item ### Formula Components | Metric | Definition | | ------------- | ---------------------------------------------- | | **Quantity** | Number of units for each line item in an order | | **Line Item** | Individual product entry within an order | | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store sold **8,742 units** across 2,914 orders in March: | Product Category | Units | % of Total | | ---------------- | ----- | ---------- | | Apparel | 4,120 | 47% | | Accessories | 2,621 | 30% | | Footwear | 2,001 | 23% | *** ## How It Works Units Sold sums the quantity field from every line item across all completed orders. If a customer orders 3 t-shirts and 2 hats in one transaction, that order contributes 5 units to this metric. *** ## When to Use | Scenario | Action | | --------------------- | ---------------------------------------------------- | | Inventory planning | Forecast stock needs based on unit velocity | | Basket size analysis | Combine with Orders to calculate units per order | | Product demand trends | Compare unit sales across categories or time periods | | Promotion impact | Measure volume lift from sales or bundles | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | [Orders](/reference/metrics/orders/counts/orders) | Number of transactions (this metric sums their line quantities) | | [Units Per Order](/reference/metrics/orders/counts/units-per-order) | Units Sold ÷ Orders | | [New Customer Units Sold](/reference/metrics/orders/counts/new-customer-units-sold) | Units from first-time buyers only | | [Returning Customer Units Sold](/reference/metrics/orders/counts/returning-customer-units-sold) | Units from repeat customers only | [See all Order Counts metrics →](/reference/metrics/orders/counts) # Average Orders Per Customer: Purchase Frequency Source: https://docs.upstackdata.com/reference/metrics/orders/customers/average-orders-per-customer Track average orders per customer to measure repeat purchase behavior. Higher values indicate stronger customer loyalty and engagement. The average number of orders placed per unique customer in the selected period. ## Formula **Avg Orders Per Customer** = [**Orders**](/reference/metrics/orders/counts/orders) ÷ [**Unique Customers**](/reference/metrics/orders/customers/unique-customers) ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------- | ------------------------------------------------ | | [**Orders**](/reference/metrics/orders/counts/orders) | Total number of orders placed in the period | | [**Unique Customers**](/reference/metrics/orders/customers/unique-customers) | Distinct customers who placed at least one order | | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store had **1.42 average orders per customer** in Q1: | Month | Orders | Unique Customers | Avg Orders/Customer | | -------- | ------ | ---------------- | ------------------- | | January | 1,247 | 892 | 1.40 | | February | 1,156 | 798 | 1.45 | | March | 1,324 | 934 | 1.42 | *** ## How It Works This metric divides total orders by unique customers to reveal purchase frequency. A value of 1.0 means every customer ordered exactly once. Values above 1.0 indicate repeat purchases—the higher the number, the more frequently customers return to buy. *** ## When to Use | Scenario | Action | | ----------------------------- | ----------------------------------------------------- | | Measuring loyalty | Track purchase frequency trends over time | | Evaluating retention programs | Compare before/after launching loyalty initiatives | | Benchmarking cohorts | See which acquisition channels drive repeat buyers | | Identifying seasonality | Monitor if holidays or promotions boost repeat orders | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------- | ----------------------------------- | | [Unique Customers](/reference/metrics/orders/customers/unique-customers) | Denominator—total distinct buyers | | [Orders](/reference/metrics/orders/counts/orders) | Numerator—total order count | | [New Customer %](/reference/metrics/orders/customers/new-customer-percent) | Shows mix of first-time vs repeat | | [Returning Customer %](/reference/metrics/orders/customers/returning-customer-percent) | Direct indicator of repeat behavior | [See all Customers metrics →](/reference/metrics/orders/customers) # Customer Metrics: Track New vs Returning Customers Source: https://docs.upstackdata.com/reference/metrics/orders/customers/index Track customer metrics in Upstack. Includes Unique Customers, New Customers, Returning Customers, and customer rates with formulas and examples. Customer metrics track acquisition and retention by segmenting orders into new and returning customers. Use these to understand your customer mix and loyalty trends. **Data Source:** [Shopify](/sources/shopify)\ **Metrics:** 8 ## Metrics in This Group | Metric | Description | When to Use | | -------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------ | | [Unique Customers](/reference/metrics/orders/customers/unique-customers) | Distinct customers who placed orders | Count total customer base | | [New Customers](/reference/metrics/orders/customers/new-customers) | First-time customers | Track customer acquisition | | [Returning Customers](/reference/metrics/orders/customers/returning-customers) | Customers with prior purchases | Track customer retention | | [New Customer %](/reference/metrics/orders/customers/new-customer-percent) | Percentage of orders from new customers | Monitor acquisition vs retention mix | | [Returning Customer %](/reference/metrics/orders/customers/returning-customer-percent) | Percentage of orders from returning customers | Track repeat purchase rate | | [New Customer Gross Rate](/reference/metrics/orders/customers/new-customer-gross-rate) | New customer revenue as % of gross | Revenue contribution by segment | | [Returning Customer Gross Rate](/reference/metrics/orders/customers/returning-customer-gross-rate) | Returning customer revenue as % of gross | Retention revenue share | | [Average Orders Per Customer](/reference/metrics/orders/customers/average-orders-per-customer) | Average number of orders per customer | Measure purchase frequency | ## How These Metrics Relate * **Unique Customers** = New Customers + Returning Customers (by customer count) * **New Customer %** + **Returning Customer %** = 100% (by order count) * **New Customer Gross Rate** + **Returning Customer Gross Rate** = 100% (by revenue) * **Average Orders Per Customer** = Orders ÷ Unique Customers ## Choosing the Right Metric * **Acquisition tracking**: Use New Customers and New Customer % for acquisition reporting * **Retention analysis**: Use Returning Customers and Returning Customer % for loyalty * **Revenue mix**: Use Gross Rate metrics to see revenue contribution by segment * **Purchase frequency**: Use Average Orders Per Customer to measure engagement # New Customer Gross Rate: Acquisition Revenue Share Source: https://docs.upstackdata.com/reference/metrics/orders/customers/new-customer-gross-rate Measure the percentage of gross revenue from new customers. Track acquisition efficiency and balance new vs returning customer mix for growth. The percentage of gross revenue generated by first-time customers. ## Formula **New Customer Gross Rate** = ( [**NC Gross Revenue**](/reference/metrics/orders/revenue/new-customer-gross-revenue) ÷ [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------ | --------------------------------------------------- | | [**NC Gross Revenue**](/reference/metrics/orders/revenue/new-customer-gross-revenue) | Gross revenue from first-time buyers | | [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) | Total revenue from product sales before adjustments | | [**customer\_type = new\_customer**](/data-dictionary/measures-and-dimensions) | Filter applied to identify first-time buyers | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store generated **\$185,000** in gross revenue in Q1, with **\$74,000** from new customers: | Segment | Gross Revenue | Rate | | ------------------- | ------------- | ------- | | New Customers | \$74,000 | **40%** | | Returning Customers | \$111,000 | 60% | A 40% new customer gross rate shows meaningful acquisition-driven revenue. *** ## How It Works This metric divides new customer gross revenue by total gross revenue, then multiplies by 100 to express as a percentage. It measures how much of your top-line product sales comes from first-time buyers versus repeat purchasers. *** ## When to Use | Scenario | Action | | --------------------------------- | ----------------------------------------------------- | | Evaluating acquisition investment | Higher rate may justify continued acquisition spend | | Diagnosing revenue concentration | Track dependency on new vs repeat buyers | | Comparing acquisition costs | Balance CAC against new customer revenue contribution | | Seasonal trend analysis | Monitor how customer mix shifts over time | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | [Returning Customer Gross Rate](/reference/metrics/orders/customers/returning-customer-gross-rate) | Inverse metric (NC Rate + RC Rate = 100%) | | [New Customers](/reference/metrics/orders/customers/new-customers) | Count of first-time buyers generating this revenue | | [New Customer %](/reference/metrics/orders/customers/new-customer-percent) | Order count share (this metric measures revenue share) | | [New Customer Gross Revenue](/reference/metrics/orders/revenue/new-customer-gross-revenue) | Numerator in this calculation | [See all Customers metrics →](/reference/metrics/orders/customers) # New Customer %: First-Time Buyer Order Share Source: https://docs.upstackdata.com/reference/metrics/orders/customers/new-customer-percent Track the percentage of orders from first-time buyers. Learn the formula, see examples, and optimize your acquisition vs retention balance. The percentage of total orders placed by first-time customers. ## Formula **New Customer %** = ( **NC Orders** ÷ [**Total Orders**](/reference/metrics/orders/counts/orders) ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------ | -------------------------------------------- | | **NC Orders** | Orders placed by first-time buyers | | [**Total Orders**](/reference/metrics/orders/counts/orders) | Complete count of all orders in the period | | [**customer\_type = new\_customer**](/data-dictionary/measures-and-dimensions) | Filter applied to identify first-time buyers | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store processed **2,450 orders** in March with **980 from first-time buyers**: | Customer Type | Orders | Share | | ------------------- | ------ | ------- | | New Customers | 980 | **40%** | | Returning Customers | 1,470 | 60% | *** ## How It Works Shopify tracks whether each customer has previous orders. New Customer % divides orders from customers with no prior purchase history by total orders. This ratio reveals your acquisition vs retention balance. *** ## When to Use | Scenario | Action | | ------------------------------ | ------------------------------------------------------- | | Evaluating acquisition efforts | Higher % indicates successful new customer acquisition | | Assessing retention health | Lower % suggests strong repeat purchase behavior | | Seasonal trend analysis | Compare % across periods to spot shifting customer mix | | Marketing strategy alignment | Balance acquisition spend against retention initiatives | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------ | ----------------------------------- | | [Returning Customer %](/reference/metrics/orders/customers/returning-customer-percent) | The inverse (100% − New Customer %) | | [Orders](/reference/metrics/orders/counts/orders) | Total orders (the denominator) | | [New Customers](/reference/metrics/orders/customers/new-customers) | Distinct first-time buyers | | [New Customer Gross Revenue](/reference/metrics/orders/revenue/new-customer-gross-revenue) | Revenue from first-time buyers | [See all Customers metrics →](/reference/metrics/orders/customers) # New Customers: First-Time Buyers in Period Source: https://docs.upstackdata.com/reference/metrics/orders/customers/new-customers Track the number of first-time customers who made their first purchase. Measure customer acquisition independently of order volume. The count of distinct customers making their first-ever purchase in the period. ## Formula **New Customers** = **COUNT DISTINCT** ( Customer ID ) **WHERE** [customer\_type = new\_customer](/data-dictionary/measures-and-dimensions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------ | --------------------------------------------------- | | **Customer ID** | Unique identifier for each customer from Shopify | | [**customer\_type = new\_customer**](/data-dictionary/measures-and-dimensions) | Filters to customers with no prior purchase history | | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Count | *** ## Example Your store acquired **1,247 new customers** in March: | Week | New Customers | NC Orders | NC Revenue | | ------ | ------------- | --------- | ---------- | | Week 1 | 312 | 318 | \$24,560 | | Week 2 | 287 | 295 | \$22,140 | | Week 3 | 341 | 352 | \$27,830 | | Week 4 | 307 | 319 | \$25,470 | Each customer appears only once—in the week of their first-ever purchase. The NC Orders count is slightly higher because some new customers placed multiple orders in the same week. *** ## How It Works A customer is classified as "new" based on their entire purchase history with your store, not just the selected period. If someone has never ordered before and places their first order during the reporting period, they count as a new customer. This classification uses Shopify's customer records to verify first-purchase status. *** ## When to Use | Scenario | Action | | ----------------------- | ------------------------------------------------------------ | | Measuring acquisition | Track how many first-time buyers you're acquiring | | Ad performance analysis | Evaluate campaigns by new customer generation | | Growth forecasting | Use new customer trends to project future revenue | | CAC calculations | Combine with ad spend to calculate customer acquisition cost | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------ | ------------------------------------------ | | [Unique Customers](/reference/metrics/orders/customers/unique-customers) | Total distinct customers (New + Returning) | | [Returning Customers](/reference/metrics/orders/customers/returning-customers) | Complement to new customers | | [New Customer %](/reference/metrics/orders/customers/new-customer-percent) | New Customers as percentage of orders | | [New Customer Gross Revenue](/reference/metrics/orders/revenue/new-customer-gross-revenue) | Revenue from new customers | [See all Customers metrics →](/reference/metrics/orders/customers) # Returning Customer Gross Rate: Retention Revenue Share Source: https://docs.upstackdata.com/reference/metrics/orders/customers/returning-customer-gross-rate Track what percentage of gross revenue comes from returning customers. Measure retention revenue contribution and balance acquisition vs loyalty. The percentage of gross revenue generated by returning customers. ## Formula **Returning Customer Gross Rate** = ( [**RC Gross Revenue**](/reference/metrics/orders/revenue/returning-customer-gross-revenue) ÷ [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------ | --------------------------------------------------- | | [**RC Gross Revenue**](/reference/metrics/orders/revenue/returning-customer-gross-revenue) | Gross revenue from customers with prior purchases | | [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) | Total revenue from product sales before adjustments | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions) | Filter applied to identify repeat buyers | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store generated **\$185,000** in gross revenue in Q1, with **\$111,000** from returning customers: | Segment | Gross Revenue | Rate | | ------------------- | ------------- | ------- | | Returning Customers | \$111,000 | **60%** | | New Customers | \$74,000 | 40% | A 60% returning customer gross rate indicates strong retention revenue contribution. *** ## How It Works This metric divides returning customer gross revenue by total gross revenue, then multiplies by 100 to express as a percentage. It measures how much of your product revenue comes from repeat buyers versus first-time purchasers. *** ## When to Use | Scenario | Action | | -------------------------------- | -------------------------------------------------- | | Evaluating retention investment | High rate justifies loyalty program spend | | Diagnosing revenue concentration | Track dependency on repeat buyers vs acquisition | | Comparing acquisition costs | Balance CAC against retention revenue contribution | | Seasonal trend analysis | Monitor how customer mix shifts over time | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | | [New Customer Gross Rate](/reference/metrics/orders/customers/new-customer-gross-rate) | Inverse metric (NC Rate + RC Rate = 100%) | | [Returning Customers](/reference/metrics/orders/customers/returning-customers) | Count of repeat buyers generating this revenue | | [Returning Customer %](/reference/metrics/orders/customers/returning-customer-percent) | Order count share (this metric measures revenue share) | | [Returning Customer Gross Revenue](/reference/metrics/orders/revenue/returning-customer-gross-revenue) | Numerator in this calculation | [See all Customers metrics →](/reference/metrics/orders/customers) # Returning Customer %: Repeat Buyer Order Share Source: https://docs.upstackdata.com/reference/metrics/orders/customers/returning-customer-percent Track the percentage of orders from repeat buyers. Learn the formula, see examples, and measure customer loyalty and retention strength. The percentage of total orders placed by customers who have purchased before. ## Formula **Returning Customer %** = ( **RC Orders** ÷ [**Total Orders**](/reference/metrics/orders/counts/orders) ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------ | ----------------------------------------------------------- | | **RC Orders** | Orders placed by customers with at least one prior purchase | | [**Total Orders**](/reference/metrics/orders/counts/orders) | Complete count of all orders in the period | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions) | Filter applied to identify repeat buyers | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store processed **2,450 orders** in March with **1,470 from returning customers**: | Customer Type | Orders | Share | | ------------------- | ------ | ------- | | Returning Customers | 1,470 | **60%** | | New Customers | 980 | 40% | *** ## How It Works Shopify tracks whether each customer has previous orders. Returning Customer % divides orders from customers with at least one prior purchase by total orders. A high rate signals strong customer loyalty and retention. *** ## When to Use | Scenario | Action | | ---------------------------------- | ----------------------------------------------------------- | | Measuring retention success | Higher % indicates loyal customers placing repeat orders | | Evaluating LTV potential | Strong repeat rates suggest healthy customer lifetime value | | Seasonal trend analysis | Compare % across periods to spot retention changes | | Balancing acquisition vs retention | Use alongside New Customer % for complete picture | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | ----------------------------------------- | | [New Customer %](/reference/metrics/orders/customers/new-customer-percent) | The inverse (100% − Returning Customer %) | | [Orders](/reference/metrics/orders/counts/orders) | Total orders (the denominator) | | [Returning Customers](/reference/metrics/orders/customers/returning-customers) | Distinct repeat buyers | | [Returning Customer Gross Revenue](/reference/metrics/orders/revenue/returning-customer-gross-revenue) | Revenue from repeat buyers | [See all Customers metrics →](/reference/metrics/orders/customers) # Returning Customers: Repeat Buyers in Period Source: https://docs.upstackdata.com/reference/metrics/orders/customers/returning-customers Track the count of repeat buyers who placed orders in your selected period. Measure customer retention and loyalty with actual repeat customer numbers. The count of customers who placed orders and have at least one prior purchase on record. ## Formula **Returning Customers** = **COUNT DISTINCT** ( Customer ID ) **WHERE** [customer\_type = returning\_customer](/data-dictionary/measures-and-dimensions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------ | ----------------------------------------------------- | | **Customer ID** | Unique identifier for each customer from Shopify | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions) | Filters to customers with at least one prior purchase | | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Count | *** ## Example Your store served **1,847 returning customers** in February: | Week | Returning Customers | New Customers | Total Unique | | ------ | ------------------- | ------------- | ------------ | | Week 1 | 428 | 284 | 712 | | Week 2 | 412 | 272 | 684 | | Week 3 | 467 | 289 | 756 | | Week 4 | 540 | 155 | 695 | Your returning customer base grew throughout the month as early February buyers placed repeat orders. *** ## How It Works Shopify tracks each customer's purchase history. A returning customer is anyone who has completed at least one order before the current one. This metric counts distinct returning customers—each repeat buyer counts once regardless of how many orders they placed in the period. *** ## When to Use | Scenario | Action | | ----------------------------- | -------------------------------------------------------------- | | Tracking retention success | Monitor growth in repeat buyers month over month | | Evaluating loyalty programs | Compare returning customer counts before and after initiatives | | Sizing your repeat buyer base | Understand how many loyal customers are actively purchasing | | Cohort retention analysis | Track which acquisition cohorts produce the most repeat buyers | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | ------------------------------------------ | | [New Customers](/reference/metrics/orders/customers/new-customers) | First-time buyers (the complement) | | [Unique Customers](/reference/metrics/orders/customers/unique-customers) | Total distinct customers (New + Returning) | | [Returning Customer %](/reference/metrics/orders/customers/returning-customer-percent) | Returning orders as percentage of total | | [Returning Customer Gross Revenue](/reference/metrics/orders/revenue/returning-customer-gross-revenue) | Revenue from repeat buyers | [See all Customers metrics →](/reference/metrics/orders/customers) # Unique Customers: Distinct Buyers in Period Source: https://docs.upstackdata.com/reference/metrics/orders/customers/unique-customers Track the number of distinct customers who placed orders in your selected period. Understand buyer count independently of order volume. The count of distinct customers who placed at least one order in the period. ## Formula **Unique Customers** = **COUNT DISTINCT** ( Customer ID ) **WHERE** order placed in period ### Formula Components | Metric | Definition | | --------------- | ------------------------------------------------ | | **Customer ID** | Unique identifier for each customer from Shopify | | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Count Distinct | *** ## Example Your store served **2,847 unique customers** in February: | Week | Unique Customers | Orders | Avg Orders/Customer | | ------ | ---------------- | ------ | ------------------- | | Week 1 | 712 | 892 | 1.25 | | Week 2 | 684 | 821 | 1.20 | | Week 3 | 756 | 934 | 1.24 | | Week 4 | 695 | 847 | 1.22 | The monthly unique customers (2,847) is less than the sum of weekly counts because some customers purchased in multiple weeks. *** ## How It Works Each customer is counted once regardless of how many orders they placed. A customer who placed 5 orders counts the same as one who placed 1 order. This metric uses Shopify customer identifiers to deduplicate across the selected time period. *** ## When to Use | Scenario | Action | | --------------------------- | ---------------------------------------------- | | Measuring acquisition reach | Track unique buyers separate from order volume | | Calculating repeat rate | Compare unique customers to total orders | | Sizing customer base | Understand how many people you served | | Cohort analysis | Track unique customers by acquisition period | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------ | ----------------------------------------------- | | [New Customers](/reference/metrics/orders/customers/new-customers) | First-time buyers subset | | [Returning Customers](/reference/metrics/orders/customers/returning-customers) | Repeat buyers subset | | [Orders](/reference/metrics/orders/counts/orders) | Total order count (may exceed unique customers) | | [Avg Orders Per Customer](/reference/metrics/orders/customers/average-orders-per-customer) | Orders ÷ Unique Customers | [See all Customers metrics →](/reference/metrics/orders/customers) # Handling Cost: Total Order Fulfillment Handling Expense Source: https://docs.upstackdata.com/reference/metrics/orders/fulfillment/handling-cost Track Handling Cost to measure total warehouse and packaging expenses — essential for contribution margin and unit economics analysis. Handling Cost measures total warehouse and packaging expenses incurred to prepare orders for shipment. ## Formula **Handling Cost** = **SUM** ( Handling Cost per Order ) ### Formula Components | Metric | Definition | | --------------------------- | ----------------------------------------------------------------------- | | **Handling Cost per Order** | Individual handling fees applied per order from your cost configuration | | Metadata | | | --------------- | -------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Sum | *** ## Example Your store fulfilled **3,240 orders** in March with total handling expenses of **\$9,720**, averaging **\$3.00** per order. | Month | Orders | Handling Cost | Per Order | | ----- | ------ | ------------- | --------- | | March | 3,240 | \$9,720 | \$3.00 | | April | 2,980 | \$9,536 | \$3.20 | *** ## How It Works Handling Cost aggregates warehouse expenses from your cost configuration — global per-order handling fees plus per-product handling charges. These costs cover picking, packing, and materials. The metric is deducted from CM1 when calculating contribution margin at the CM2 level. *** ## When to Use | Scenario | Action | | ---------------------------- | --------------------------------------------------- | | Contribution margin analysis | Deduct from CM1 to calculate CM2 | | 3PL evaluation | Compare handling costs across fulfillment providers | | Packaging optimization | Track cost impact of material changes | | Volume efficiency | Monitor if scale reduces per-order handling | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------- | -------------------------------------------- | | [Handling Cost Per Order](/reference/metrics/orders/fulfillment/handling-cost-per-order) | Average handling expense per order | | [Handling Cost %](/reference/metrics/orders/fulfillment/handling-cost-percent) | Handling as percentage of net revenue | | [Shipping Cost](/reference/metrics/orders/fulfillment/shipping-cost) | Partner fulfillment cost component | | [Total Fulfillment Cost](/reference/metrics/orders/fulfillment/total-fulfillment-cost) | Combined shipping, handling, and fulfillment | [See all Fulfillment metrics →](/reference/metrics/orders/fulfillment) # Handling Cost per Order: Average Handling Expense Source: https://docs.upstackdata.com/reference/metrics/orders/fulfillment/handling-cost-per-order Track handling cost per order for your Shopify store. Measure the average handling and labor cost per order fulfilled. Handling Cost per Order measures the average labor and handling expense per order—picking, packing, and processing costs. ## Formula **Handling Cost per Order** = **Total Handling Cost** ÷ **Orders** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------ | ----------------------- | | [**Total Handling Cost**](/reference/metrics/orders/fulfillment/handling-cost) | Total handling expenses | | [**Orders**](/reference/metrics/orders/counts/orders) | Count of orders | | Metadata | | | --------------- | --------------------------------------- | | **Type** | Currency | | **Data Source** | [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Average | *** ## Example Your Shopify store has **\$12,000** handling costs across **1,000** orders. | Component | Value | Calculation | | --------------------------- | -------- | ------------------- | | Total Handling Cost | \$12,000 | Picking and packing | | Orders | 1,000 | Order count | | **Handling Cost per Order** | **\$12** | \$12,000 ÷ 1,000 | *** ## How It Works Handling Cost per Order is configured in Cost Settings. You can set a fixed cost per order or a variable cost based on order complexity (units, weight, etc.). *** ## When to Use | Scenario | Action | | ---------------------- | --------------------------------------- | | CM2 calculation | Handling reduces CM1 to CM2 | | Fulfillment efficiency | Track cost per order over time | | 3PL comparison | Compare handling costs across providers | | Pricing decisions | Include handling in unit economics | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------- | --------------------------- | | [Handling Cost](/reference/metrics/orders/fulfillment/handling-cost) | Total handling costs | | [Shipping Cost per Order](/reference/metrics/orders/fulfillment/shipping-cost-per-order) | Carrier costs per order | | [Fulfillment Cost per Order](/reference/metrics/orders/fulfillment/fulfillment-cost-per-order) | Total fulfillment per order | [See all Fulfillment metrics →](/reference/metrics/orders/fulfillment) # Handling Cost %: Handling Expense as Share of Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/fulfillment/handling-cost-percent Track Handling Cost % to measure handling expenses as a percentage of net revenue — essential for monitoring fulfillment cost efficiency and margin impact. Handling Cost % measures what percentage of your net revenue is consumed by order handling expenses. ## Formula **Handling Cost %** = ( [**Handling Cost**](/reference/metrics/orders/fulfillment/handling-cost) ÷ [**Net Revenue**](/reference/metrics/orders/revenue/net-revenue) ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------ | --------------------------------------------- | | [**Handling Cost**](/reference/metrics/orders/fulfillment/handling-cost) | Total warehouse and order processing expenses | | [**Net Revenue**](/reference/metrics/orders/revenue/net-revenue) | Revenue after refunds and discounts | | Metadata | | | --------------- | -------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Ratio | *** ## Example Your store generated **\$185,000** in net revenue in March with **\$9,250** in handling costs, resulting in a **5.0%** handling cost percentage. | Month | Net Revenue | Handling Cost | Handling Cost % | | ----- | ----------- | ------------- | --------------- | | March | \$185,000 | \$9,250 | 5.0% | | April | \$192,000 | \$8,640 | 4.5% | *** ## How It Works Handling Cost % divides your total handling expenses by net revenue. This gives you a normalized view of handling burden that can be tracked month-over-month regardless of revenue fluctuations. Lower percentages indicate more efficient fulfillment operations. *** ## When to Use | Scenario | Action | | ----------------------- | --------------------------------------------------- | | Margin analysis | Monitor handling burden on contribution margin | | Efficiency benchmarking | Compare against industry standards (typically 3-8%) | | Seasonal planning | Track how fulfillment scales during peak periods | | 3PL evaluation | Compare handling costs across fulfillment providers | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------- | ------------------------------------- | | [Handling Cost](/reference/metrics/orders/fulfillment/handling-cost) | Absolute handling expense (numerator) | | [Handling Cost Per Order](/reference/metrics/orders/fulfillment/handling-cost-per-order) | Per-order handling expense | | [Shipping Cost %](/reference/metrics/orders/fulfillment/shipping-cost-percent) | Shipping as percentage of revenue | [See all Fulfillment metrics →](/reference/metrics/orders/fulfillment) # Fulfillment Costs: Track Shipping and Handling Expenses Source: https://docs.upstackdata.com/reference/metrics/orders/fulfillment/index Track fulfillment cost metrics in Upstack. Includes Handling Cost, Shipping Cost, and fulfillment expenses by customer type. Fulfillment cost metrics track the expenses of getting orders to customers—handling, shipping, and other fulfillment operations. **Data Source:** [Shopify](/sources/shopify), [Upstack Costs](/sources/upstack-costs)\ **Metrics:** 15 ## Metrics in This Group | Metric | Description | When to Use | | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ------------------------ | | [Handling Cost](/reference/metrics/orders/fulfillment/handling-cost) | Order handling expenses | Track warehouse costs | | [Handling Cost Per Order](/reference/metrics/orders/fulfillment/handling-cost-per-order) | Handling cost per order | Per-order analysis | | [Handling Cost %](/reference/metrics/orders/fulfillment/handling-cost-percent) | Handling as % of revenue | Cost proportion | | [Shipping Cost](/reference/metrics/orders/fulfillment/shipping-cost) | Shipping expenses | Track carrier costs | | [Shipping Cost Per Order](/reference/metrics/orders/fulfillment/shipping-cost-per-order) | Shipping cost per order | Per-order shipping | | [Shipping Cost %](/reference/metrics/orders/fulfillment/shipping-cost-percent) | Shipping as % of revenue | Shipping burden | | [Other Fulfillment Cost](/reference/metrics/orders/fulfillment/other-fulfillment-cost) | Additional fulfillment expenses | Track misc expenses | | [Total Fulfillment Cost](/reference/metrics/orders/fulfillment/total-fulfillment-cost) | All fulfillment costs combined | Total fulfillment burden | | [New Customer Shipping Cost](/reference/metrics/orders/fulfillment/new-customer-shipping-cost) | Shipping for new customers | Segment analysis | | [Returning Customer Shipping Cost](/reference/metrics/orders/fulfillment/returning-customer-shipping-cost) | Shipping for returning customers | Compare segments | | [New Customer Handling Cost](/reference/metrics/orders/fulfillment/new-customer-handling-cost) | Handling for new customers | New customer costs | | [Returning Customer Handling Cost](/reference/metrics/orders/fulfillment/returning-customer-handling-cost) | Handling for returning customers | Returning costs | | [New Customer Other Fulfillment Cost](/reference/metrics/orders/fulfillment/new-customer-other-fulfillment-cost) | Custom fulfillment for new customers | Track custom fees | | [Returning Customer Other Fulfillment Cost](/reference/metrics/orders/fulfillment/returning-customer-other-fulfillment-cost) | Custom fulfillment for returning | Compare segments | | [New Customer Fulfillment Cost](/reference/metrics/orders/fulfillment/new-customer-fulfillment-cost) | All fulfillment costs for new customers | NC profitability | ## How These Metrics Relate Fulfillment costs impact contribution margin at the CM2 level: * **Total Fulfillment Cost** = Handling Cost + Shipping Cost + Other Fulfillment Cost * **CM2** = CM1 − Fulfillment Costs (contribution margin after fulfillment) * Compare **Shipping Revenue** vs **Shipping Cost** to find shipping margin ## Choosing the Right Metric * **Fulfillment optimization**: Use Total Fulfillment Cost to track total burden * **Shipping margin**: Compare Shipping Cost vs Shipping Revenue collected * **Per-order economics**: Use Per Order metrics for unit economics * **Customer profitability**: Compare New vs Returning fulfillment costs # New Customer Handling Cost: First-Time Buyer Fulfillment Fees Source: https://docs.upstackdata.com/reference/metrics/orders/fulfillment/new-customer-handling-cost Track total handling costs for new customer orders. Understand first-time buyer fulfillment expenses including global and per-product handling fees. Total handling costs for orders placed by new (first-time) customers. ## Formula **New Customer Handling Cost** = **SUM** ( [**Handling Cost**](/reference/metrics/orders/fulfillment/handling-cost) ) **WHERE** [customer\_type = new\_customer](/data-dictionary/measures-and-dimensions#visitor-dimensions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | [**Handling Cost**](/reference/metrics/orders/fulfillment/handling-cost) | Total handling costs including global handling fees and per-product handling fees | | [**customer\_type = new\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to customers placing their first order with your store | | Metadata | | | --------------- | -------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Sum | *** ## Example Your store processed **\$2,340** in handling costs for new customers last month: | Customer Type | Handling Cost | Orders | Per Order | | ------------------- | ------------- | ------- | ---------- | | New Customers | \$2,340 | 312 | \$7.50 | | Returning Customers | \$1,890 | 468 | \$4.04 | | **Total** | **\$4,230** | **780** | **\$5.42** | *** ## How It Works New Customer Handling Cost sums all handling fees from orders where the customer is making their first purchase. Handling costs include both global per-order fees and per-product handling charges configured in your cost settings. Customer type is determined by whether they have prior orders in your Shopify history. *** ## When to Use | Scenario | Action | | -------------------------- | --------------------------------------------------------------------- | | New customer profitability | Calculate if first-time orders are profitable after fulfillment costs | | CAC payback analysis | Include in total acquisition costs for new customers | | Pricing decisions | Ensure pricing covers higher handling costs for new buyers | | Segment comparison | Compare with returning customer handling to identify efficiency gaps | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [Handling Cost](/reference/metrics/orders/fulfillment/handling-cost) | Parent metric including all customer types | | [Returning Customer Handling Cost](/reference/metrics/orders/fulfillment/returning-customer-handling-cost) | Counterpart for repeat buyers | | [Handling Cost Per Order](/reference/metrics/orders/fulfillment/handling-cost-per-order) | Average handling cost across all orders | | [Handling Cost %](/reference/metrics/orders/fulfillment/handling-cost-percent) | Handling as percentage of net revenue | | [Total Fulfillment Cost](/reference/metrics/orders/fulfillment/total-fulfillment-cost) | Sum of shipping, handling, and other fulfillment | [See all Fulfillment metrics →](/reference/metrics/orders/fulfillment) # New Customer Other Fulfillment Cost: Custom Fulfillment Expenses Source: https://docs.upstackdata.com/reference/metrics/orders/fulfillment/new-customer-other-fulfillment-cost Track user-defined fulfillment costs for new customer orders. Includes packaging, custom fees, and other fulfillment expenses for first-time buyers. User-defined fulfillment costs from order cost entries for new customer orders. ## Formula **New Customer Other Fulfillment Cost** = **SUM** ( [**Other Fulfillment Cost**](/reference/metrics/orders/fulfillment/other-fulfillment-cost) ) **WHERE** [customer\_type = new\_customer](/data-dictionary/measures-and-dimensions#visitor-dimensions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | [**Other Fulfillment Cost**](/reference/metrics/orders/fulfillment/other-fulfillment-cost) | User-defined fulfillment costs from order cost entries with category Fulfillment | | [**customer\_type = new\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to customers placing their first order with your store | | Metadata | | | --------------- | --------------------------------------- | | **Type** | Currency | | **Data Source** | [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Sum | *** ## Example Your store incurred **\$1,560** in custom fulfillment costs for new customers last month: | Customer Type | Other Fulfillment | Orders | Per Order | | ------------------- | ----------------- | ------- | ---------- | | New Customers | \$1,560 | 312 | \$5.00 | | Returning Customers | \$1,170 | 468 | \$2.50 | | **Total** | **\$2,730** | **780** | **\$3.50** | *** ## How It Works New Customer Other Fulfillment Cost sums all user-defined fulfillment expenses from orders where the customer is making their first purchase. These costs come from order cost entries you configure with the Fulfillment category—packaging materials, custom handling fees, and other fulfillment-related expenses beyond standard shipping and handling. *** ## When to Use | Scenario | Action | | -------------------------- | -------------------------------------------------------------------------- | | New customer profitability | Include in total costs when calculating first-order margins | | Custom packaging analysis | Track branded packaging or gift wrapping costs for new buyers | | Acquisition cost modeling | Add to CAC calculations for complete customer acquisition costs | | Segment comparison | Compare with returning customer costs to identify efficiency opportunities | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [Other Fulfillment Cost](/reference/metrics/orders/fulfillment/other-fulfillment-cost) | Parent metric including all customer types | | [Returning Customer Other Fulfillment Cost](/reference/metrics/orders/fulfillment/returning-customer-other-fulfillment-cost) | Counterpart for repeat buyers | | [Total Fulfillment Cost](/reference/metrics/orders/fulfillment/total-fulfillment-cost) | Sum of shipping, handling, and other fulfillment | | [New Customer Handling Cost](/reference/metrics/orders/fulfillment/new-customer-handling-cost) | Standard handling fees for new customers | | [New Customer Shipping Cost](/reference/metrics/orders/fulfillment/new-customer-shipping-cost) | Shipping expenses for new customers | [See all Fulfillment metrics →](/reference/metrics/orders/fulfillment) # New Customer Shipping Cost: First-Time Buyer Shipping Expenses Source: https://docs.upstackdata.com/reference/metrics/orders/fulfillment/new-customer-shipping-cost Track total shipping costs for new customer orders. Understand first-time buyer fulfillment expenses to analyze acquisition profitability. Total shipping costs for orders placed by new (first-time) customers. ## Formula **New Customer Shipping Cost** = **SUM** ( [**Shipping Cost**](/reference/metrics/orders/fulfillment/shipping-cost) ) **WHERE** [customer\_type = new\_customer](/data-dictionary/measures-and-dimensions#visitor-dimensions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | [**Shipping Cost**](/reference/metrics/orders/fulfillment/shipping-cost) | Total shipping expenses incurred to fulfill orders | | [**customer\_type = new\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to customers placing their first order with your store | | Metadata | | | --------------- | -------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Sum | *** ## Example Your store spent **\$3,120** on shipping for new customers last month: | Customer Type | Shipping Cost | Orders | Per Order | | ------------------- | ------------- | --------- | ---------- | | New Customers | \$3,120 | 416 | \$7.50 | | Returning Customers | \$2,480 | 620 | \$4.00 | | **Total** | **\$5,600** | **1,036** | **\$5.41** | *** ## How It Works New Customer Shipping Cost sums shipping expenses from orders where the customer is making their first purchase. Shipping costs are applied based on rules you configure—flat rate, weight-based, zone-based, or carrier-calculated. Customer type is determined by whether they have prior orders in your Shopify history. *** ## When to Use | Scenario | Action | | -------------------------- | -------------------------------------------------------------------- | | New customer profitability | Calculate if first-time orders are profitable after shipping | | CAC payback analysis | Include in total acquisition costs for payback calculation | | Free shipping impact | Measure cost of free shipping promotions targeting new buyers | | Segment comparison | Compare with returning customer shipping to identify efficiency gaps | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | [Shipping Cost](/reference/metrics/orders/fulfillment/shipping-cost) | Parent metric including all customer types | | [Returning Customer Shipping Cost](/reference/metrics/orders/fulfillment/returning-customer-shipping-cost) | Counterpart for repeat buyers | | [Shipping Cost Per Order](/reference/metrics/orders/fulfillment/shipping-cost-per-order) | Average shipping cost across all orders | | [New Customer Handling Cost](/reference/metrics/orders/fulfillment/new-customer-handling-cost) | Handling costs for new customers | [See all Fulfillment metrics →](/reference/metrics/orders/fulfillment) # Other Fulfillment Cost: Custom Fulfillment Expenses Source: https://docs.upstackdata.com/reference/metrics/orders/fulfillment/other-fulfillment-cost Track user-defined fulfillment costs like packaging and custom fees. Learn how Other Fulfillment Cost contributes to total fulfillment and CM2 calculations. User-defined fulfillment costs from order cost entries, including packaging materials and other fulfillment fees. ## Formula **Other Fulfillment Cost** = **SUM** ( Order Cost Entries ) **WHERE** [category = Fulfillment](/data-dictionary/measures-and-dimensions) ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------- | ------------------------------------------------------ | | **Order Cost Entries** | Cost line items you configure in Settings → Costs | | [**category = Fulfillment**](/data-dictionary/measures-and-dimensions) | Cost entries classified under the Fulfillment category | | Metadata | | | --------------- | --------------------------------------- | | **Type** | Currency | | **Data Source** | [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Sum | *** ## Example Your store incurred **\$2,730** in custom fulfillment costs last month across 780 orders: | Cost Type | Amount | Per Order | | --------------------------- | ----------- | ---------- | | Packaging Materials | \$1,560 | \$2.00 | | Gift Wrapping | \$624 | \$0.80 | | Custom Inserts | \$546 | \$0.70 | | **Total Other Fulfillment** | **\$2,730** | **\$3.50** | *** ## How It Works Other Fulfillment Cost sums all user-defined fulfillment expenses from your order cost entries. These are costs you configure with the Fulfillment category—packaging materials, branded inserts, gift wrapping fees, and other fulfillment-related expenses beyond standard shipping and handling. This metric combines with Shipping Cost and Handling Cost to form Total Fulfillment Cost. *** ## When to Use | Scenario | Action | | ------------------------------- | --------------------------------------------------------------- | | Packaging cost tracking | Monitor branded packaging and materials expenses | | Contribution margin analysis | Include as part of Total Fulfillment Cost for CM2 | | Custom fulfillment optimization | Identify opportunities to reduce non-shipping fulfillment costs | | Per-order profitability | Add to fulfillment burden when analyzing order-level margins | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | [Total Fulfillment Cost](/reference/metrics/orders/fulfillment/total-fulfillment-cost) | Sum of shipping, handling, and this metric | | [Shipping Cost](/reference/metrics/orders/fulfillment/shipping-cost) | Carrier expenses (separate from this metric) | | [Handling Cost](/reference/metrics/orders/fulfillment/handling-cost) | Warehouse fees (separate from this metric) | | [New Customer Other Fulfillment Cost](/reference/metrics/orders/fulfillment/new-customer-other-fulfillment-cost) | This metric filtered to first-time buyers | | [Returning Customer Other Fulfillment Cost](/reference/metrics/orders/fulfillment/returning-customer-other-fulfillment-cost) | This metric filtered to repeat buyers | [See all Fulfillment metrics →](/reference/metrics/orders/fulfillment) # Returning Customer Handling Cost: Repeat Buyer Fulfillment Fees Source: https://docs.upstackdata.com/reference/metrics/orders/fulfillment/returning-customer-handling-cost Track total handling costs for returning customer orders. Analyze repeat buyer fulfillment expenses to optimize pricing and profitability. Total handling costs for orders placed by returning (repeat) customers. ## Formula **Returning Customer Handling Cost** = **SUM** ( [**Handling Cost**](/reference/metrics/orders/fulfillment/handling-cost) ) **WHERE** [customer\_type = returning\_customer](/data-dictionary/measures-and-dimensions#visitor-dimensions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | [**Handling Cost**](/reference/metrics/orders/fulfillment/handling-cost) | Total handling costs including global handling fees and per-product handling fees | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to customers who have placed at least one prior order | | Metadata | | | --------------- | -------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Sum | *** ## Example Your store incurred **\$1,890** in handling costs for returning customers last month: | Customer Type | Handling Cost | Orders | Per Order | | ------------------- | ------------- | ------- | ---------- | | Returning Customers | \$1,890 | 468 | \$4.04 | | New Customers | \$2,340 | 312 | \$7.50 | | **Total** | **\$4,230** | **780** | **\$5.42** | *** ## How It Works Returning Customer Handling Cost sums all handling fees from orders where the customer has made at least one previous purchase. Handling costs include both global per-order fees and per-product handling charges configured in your cost settings. Customer type is determined by whether they have prior orders in your Shopify history. *** ## When to Use | Scenario | Action | | -------------------------- | ------------------------------------------------------------------------------------ | | Repeat buyer profitability | Evaluate if returning customer orders remain profitable after handling costs | | Loyalty program ROI | Factor handling costs into lifetime value calculations | | Operational efficiency | Compare with new customers to identify if repeat buyers have lower handling overhead | | Segment comparison | Compare with new customer handling to identify cost efficiency patterns | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [Handling Cost](/reference/metrics/orders/fulfillment/handling-cost) | Parent metric including all customer types | | [New Customer Handling Cost](/reference/metrics/orders/fulfillment/new-customer-handling-cost) | Counterpart for first-time buyers | | [Handling Cost Per Order](/reference/metrics/orders/fulfillment/handling-cost-per-order) | Average handling cost across all orders | | [Handling Cost %](/reference/metrics/orders/fulfillment/handling-cost-percent) | Handling as percentage of net revenue | | [Total Fulfillment Cost](/reference/metrics/orders/fulfillment/total-fulfillment-cost) | Sum of shipping, handling, and other fulfillment | [See all Fulfillment metrics →](/reference/metrics/orders/fulfillment) # Returning Customer Other Fulfillment Cost: Custom Fulfillment Expenses Source: https://docs.upstackdata.com/reference/metrics/orders/fulfillment/returning-customer-other-fulfillment-cost Track user-defined fulfillment costs for returning customer orders. Includes packaging, custom fees, and other fulfillment expenses for repeat buyers. User-defined fulfillment costs from order cost entries for returning customer orders. ## Formula **Returning Customer Other Fulfillment Cost** = **SUM** ( [**Other Fulfillment Cost**](/reference/metrics/orders/fulfillment/other-fulfillment-cost) ) **WHERE** [customer\_type = returning\_customer](/data-dictionary/measures-and-dimensions#visitor-dimensions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | [**Other Fulfillment Cost**](/reference/metrics/orders/fulfillment/other-fulfillment-cost) | User-defined fulfillment costs from order cost entries with category Fulfillment | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to customers who have placed at least one prior order | | Metadata | | | --------------- | --------------------------------------- | | **Type** | Currency | | **Data Source** | [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Sum | *** ## Example Your store incurred **\$1,170** in custom fulfillment costs for returning customers last month: | Customer Type | Other Fulfillment | Orders | Per Order | | ------------------- | ----------------- | ------- | ---------- | | Returning Customers | \$1,170 | 468 | \$2.50 | | New Customers | \$1,560 | 312 | \$5.00 | | **Total** | **\$2,730** | **780** | **\$3.50** | *** ## How It Works Returning Customer Other Fulfillment Cost sums all user-defined fulfillment expenses from orders where the customer has purchased before. These costs come from order cost entries you configure with the Fulfillment category—packaging materials, custom handling fees, and other fulfillment-related expenses beyond standard shipping and handling. *** ## When to Use | Scenario | Action | | -------------------------------- | --------------------------------------------------------------------- | | Customer retention profitability | Include in total costs when calculating repeat-order margins | | Segment comparison | Compare with new customer costs to identify efficiency opportunities | | Contribution margin by segment | Track fulfillment costs separately for NC vs RC profitability | | LTV analysis | Include in lifetime value calculations for total customer cost burden | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [Other Fulfillment Cost](/reference/metrics/orders/fulfillment/other-fulfillment-cost) | Parent metric including all customer types | | [New Customer Other Fulfillment Cost](/reference/metrics/orders/fulfillment/new-customer-other-fulfillment-cost) | Counterpart for first-time buyers | | [Total Fulfillment Cost](/reference/metrics/orders/fulfillment/total-fulfillment-cost) | Sum of shipping, handling, and other fulfillment | | [Returning Customer Handling Cost](/reference/metrics/orders/fulfillment/returning-customer-handling-cost) | Standard handling fees for returning customers | | [Returning Customer Shipping Cost](/reference/metrics/orders/fulfillment/returning-customer-shipping-cost) | Shipping expenses for returning customers | [See all Fulfillment metrics →](/reference/metrics/orders/fulfillment) # Returning Customer Shipping Cost: Repeat Buyer Delivery Fees Source: https://docs.upstackdata.com/reference/metrics/orders/fulfillment/returning-customer-shipping-cost Track total shipping costs for returning customer orders. Analyze repeat buyer delivery expenses to optimize fulfillment pricing and profitability. Total shipping costs for orders placed by returning (repeat) customers. ## Formula **Returning Customer Shipping Cost** = **SUM** ( [**Shipping Cost**](/reference/metrics/orders/fulfillment/shipping-cost) ) **WHERE** [customer\_type = returning\_customer](/data-dictionary/measures-and-dimensions#visitor-dimensions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | [**Shipping Cost**](/reference/metrics/orders/fulfillment/shipping-cost) | Shipping costs from your configured cost rules | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions#visitor-dimensions) | Filters to customers who have placed at least one prior order | | Metadata | | | --------------- | -------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Sum | *** ## Example Your store incurred **\$3,120** in shipping costs for returning customers last month: | Customer Type | Shipping Cost | Orders | Per Order | | ------------------- | ------------- | ------- | ---------- | | Returning Customers | \$3,120 | 468 | \$6.67 | | New Customers | \$2,496 | 312 | \$8.00 | | **Total** | **\$5,616** | **780** | **\$7.20** | *** ## How It Works Returning Customer Shipping Cost sums all shipping expenses from orders where the customer has made at least one previous purchase. Shipping costs are calculated based on your configured cost rules in Upstack. Customer type is determined by whether they have prior orders in your Shopify history. *** ## When to Use | Scenario | Action | | -------------------------- | ----------------------------------------------------------------------- | | Repeat buyer profitability | Evaluate if returning customer orders remain profitable after shipping | | Loyalty program ROI | Factor shipping costs into lifetime value calculations | | Free shipping threshold | Determine if repeat buyers qualify for reduced shipping costs | | Segment comparison | Compare with new customer shipping to identify cost efficiency patterns | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------ | | [Shipping Cost](/reference/metrics/orders/fulfillment/shipping-cost) | Parent metric including all customer types | | [New Customer Shipping Cost](/reference/metrics/orders/fulfillment/new-customer-shipping-cost) | Counterpart for first-time buyers | | [Shipping Cost Per Order](/reference/metrics/orders/fulfillment/shipping-cost-per-order) | Average shipping cost across all orders | | [Shipping Cost %](/reference/metrics/orders/fulfillment/shipping-cost-percent) | Shipping as percentage of net revenue | | [Total Fulfillment Cost](/reference/metrics/orders/fulfillment/total-fulfillment-cost) | Sum of shipping, handling, and other fulfillment | [See all Fulfillment metrics →](/reference/metrics/orders/fulfillment) # Shipping Cost: Total Order Fulfillment Shipping Expense Source: https://docs.upstackdata.com/reference/metrics/orders/fulfillment/shipping-cost Track Shipping Cost to measure total fulfillment shipping expenses across all orders — essential for contribution margin and profitability analysis. Shipping Cost measures the total shipping expenses incurred to fulfill orders, based on your configured shipping cost rules. ## Formula **Shipping Cost** = **SUM** ( Shipping Cost per Order ) ### Formula Components | Metric | Definition | | --------------------------- | ----------------------------------------------------------------------- | | **Shipping Cost per Order** | Individual shipping fees applied per order from your cost configuration | | Metadata | | | --------------- | -------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Sum | *** ## Example Your store fulfilled **2,847 orders** in February with total shipping expenses of **\$14,235**, averaging **\$5.00** per order shipped. | Month | Orders | Shipping Cost | Per Order | | -------- | ------ | ------------- | --------- | | February | 2,847 | \$14,235 | \$5.00 | | March | 3,120 | \$15,288 | \$4.90 | *** ## How It Works Shipping Cost aggregates the shipping expenses from your cost configuration. These costs are applied to each order based on rules you define — flat rate, weight-based, zone-based, or carrier-calculated. The metric is deducted from revenue when calculating contribution margin. *** ## When to Use | Scenario | Action | | ---------------------------- | ----------------------------------------------------- | | Contribution margin analysis | Deduct from CM1 to calculate CM2 | | Carrier negotiation | Track trends to justify volume discounts | | Free shipping threshold | Compare shipping cost vs revenue lift from higher AOV | | Regional profitability | Segment by shipping zone to identify cost outliers | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------- | -------------------------------------------- | | [Shipping Cost Per Order](/reference/metrics/orders/fulfillment/shipping-cost-per-order) | Average shipping expense per order | | [Shipping Cost %](/reference/metrics/orders/fulfillment/shipping-cost-percent) | Shipping as percentage of net revenue | | [Total Fulfillment Cost](/reference/metrics/orders/fulfillment/total-fulfillment-cost) | Combined shipping, handling, and fulfillment | [See all Fulfillment metrics →](/reference/metrics/orders/fulfillment) # Shipping Cost per Order: Average Carrier Cost Source: https://docs.upstackdata.com/reference/metrics/orders/fulfillment/shipping-cost-per-order Track shipping cost per order for your Shopify store. Measure the average carrier shipping cost per order. Shipping Cost per Order measures the average carrier cost per order—the postage and freight expenses to deliver orders to customers. ## Formula **Shipping Cost per Order** = **Total Shipping Cost** ÷ **Orders** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------ | ---------------------------- | | [**Total Shipping Cost**](/reference/metrics/orders/fulfillment/shipping-cost) | Total carrier shipping costs | | [**Orders**](/reference/metrics/orders/counts/orders) | Count of orders | | Metadata | | | --------------- | -------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Upstack Costs](/sources/upstack-costs), [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your Shopify store has **\$15,000** shipping costs across **1,000** orders. | Component | Value | Calculation | | --------------------------- | -------- | ---------------- | | Total Shipping Cost | \$15,000 | Carrier costs | | Orders | 1,000 | Order count | | **Shipping Cost per Order** | **\$15** | \$15,000 ÷ 1,000 | *** ## How It Works Shipping Cost per Order can be calculated from actual carrier costs (ShipStation, ShipBob integrations) or configured as an average in Cost Settings. *** ## When to Use | Scenario | Action | | ----------------------- | -------------------------------------- | | CM2 calculation | Shipping reduces CM1 to CM2 | | Free shipping threshold | Set thresholds based on shipping costs | | Carrier comparison | Compare costs across carriers | | Pricing decisions | Factor shipping into product pricing | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------- | ------------------------------ | | [Shipping Cost](/reference/metrics/orders/fulfillment/shipping-cost) | Total shipping costs | | [Shipping Revenue](/reference/metrics/orders/adjustments/shipping-revenue) | Revenue collected for shipping | | [Fulfillment Cost per Order](/reference/metrics/orders/fulfillment/fulfillment-cost-per-order) | Total fulfillment per order | | [Handling Cost per Order](/reference/metrics/orders/fulfillment/handling-cost-per-order) | Picking/packing per order | [See all Fulfillment metrics →](/reference/metrics/orders/fulfillment) # Shipping Cost %: Fulfillment Shipping as Share of Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/fulfillment/shipping-cost-percent Track Shipping Cost % to measure shipping expenses as a percentage of revenue — essential for profitability analysis and optimizing fulfillment economics. Shipping Cost % measures your shipping expenses as a share of net revenue, showing the fulfillment burden on your margins. ## Formula **Shipping Cost %** = ( [**Shipping Cost**](/reference/metrics/orders/fulfillment/shipping-cost) ÷ [**Net Revenue**](/reference/metrics/orders/revenue/net-revenue) ) × 100 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------ | -------------------------------------------------- | | [**Shipping Cost**](/reference/metrics/orders/fulfillment/shipping-cost) | Total shipping expenses from configured cost rules | | [**Net Revenue**](/reference/metrics/orders/revenue/net-revenue) | Revenue after discounts and refunds | | Metadata | | | --------------- | -------------------------------------------------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Ratio | *** ## Example Your store generated **\$125,000** in net revenue last month, with **\$6,250** in shipping costs. | Period | Shipping Cost | Net Revenue | Shipping Cost % | | -------- | ------------- | ----------- | --------------- | | January | \$6,250 | \$125,000 | 5.0% | | February | \$7,150 | \$130,000 | 5.5% | | March | \$5,600 | \$140,000 | 4.0% | *** ## How It Works Shipping Cost % divides your total shipping expenses by net revenue. Unlike Shipping %, which tracks shipping revenue collected from customers, this metric tracks your actual fulfillment cost burden. A lower percentage indicates better shipping economics or improved carrier negotiations. *** ## When to Use | Scenario | Action | | ---------------------------- | ---------------------------------------------- | | Contribution margin analysis | Track CM2 impact from fulfillment costs | | Carrier negotiation | Benchmark trends before and after rate changes | | Free shipping strategy | Compare cost burden vs revenue impact | | Profitability optimization | Identify when shipping costs erode margins | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------- | ------------------------------------------------ | | [Shipping Cost](/reference/metrics/orders/fulfillment/shipping-cost) | Numerator — total shipping expenses | | [Shipping Cost Per Order](/reference/metrics/orders/fulfillment/shipping-cost-per-order) | Per-order shipping expense | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Denominator — revenue basis | | [Shipping %](/reference/metrics/orders/adjustments/shipping-percent) | Shipping revenue as % of total (customer-facing) | [See all Fulfillment metrics →](/reference/metrics/orders/fulfillment) # Total Fulfillment Cost: Combined Shipping and Handling Expenses Source: https://docs.upstackdata.com/reference/metrics/orders/fulfillment/total-fulfillment-cost Track Total Fulfillment Cost to measure combined shipping, handling, and fulfillment expenses — a key input for contribution margin analysis. Total Fulfillment Cost measures all expenses related to getting orders to customers—shipping, handling, and any additional user-defined fulfillment costs. ## Formula **Total Fulfillment Cost** = [**Shipping Cost**](/reference/metrics/orders/fulfillment/shipping-cost) + [**Handling Cost**](/reference/metrics/orders/fulfillment/handling-cost) + [**Other Fulfillment Cost**](/reference/metrics/orders/fulfillment/other-fulfillment-cost) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | | [**Shipping Cost**](/reference/metrics/orders/fulfillment/shipping-cost) | Total shipping expenses from your cost configuration | | [**Handling Cost**](/reference/metrics/orders/fulfillment/handling-cost) | Order handling expenses including warehouse and picking fees | | [**Other Fulfillment Cost**](/reference/metrics/orders/fulfillment/other-fulfillment-cost) | User-defined fulfillment costs from order cost entries | | Metadata | | | --------------- | -------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify), [Upstack Costs](/sources/upstack-costs) | | **Aggregation** | Sum | *** ## Example Your store processed **3,215 orders** in March with total fulfillment costs of **\$22,505**: | Component | Amount | Share | | ----------------- | -------- | ----- | | Shipping Cost | \$16,075 | 71% | | Handling Cost | \$4,823 | 21% | | Other Fulfillment | \$1,607 | 8% | *** ## How It Works Total Fulfillment Cost aggregates all costs related to order fulfillment. Shipping and handling costs are calculated from your cost configuration rules. Other fulfillment costs come from user-defined entries with the Fulfillment category. This total is deducted from CM1 when calculating CM2 contribution margin. *** ## When to Use | Scenario | Action | | ---------------------------- | ------------------------------------------------------------------ | | Contribution margin analysis | Deduct from CM1 to calculate CM2 | | Fulfillment optimization | Identify largest cost drivers across shipping, handling, and other | | 3PL cost comparison | Benchmark total fulfillment against third-party logistics quotes | | Profitability by channel | Compare fulfillment burden across acquisition sources | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | [Shipping Cost](/reference/metrics/orders/fulfillment/shipping-cost) | Carrier and delivery expenses included in this total | | [Handling Cost](/reference/metrics/orders/fulfillment/handling-cost) | Warehouse and order processing fees included in this total | | [Other Fulfillment Cost](/reference/metrics/orders/fulfillment/other-fulfillment-cost) | User-defined fulfillment expenses included in this total | | [CM1](/reference/metrics/orders/contribution-margin/cm1) | Gross margin before fulfillment costs | | [CM2](/reference/metrics/orders/contribution-margin/cm2) | Margin after deducting fulfillment costs | [See all Fulfillment metrics →](/reference/metrics/orders/fulfillment) # Orders Metrics: Track Revenue, Orders, and Profitability Source: https://docs.upstackdata.com/reference/metrics/orders/index Track orders and revenue metrics in Upstack. View 190+ metrics including Revenue, AOV, COGS, Contribution Margin, and Customer Segmentation with formulas and examples. Orders metrics track your Shopify store's revenue, order volume, and profitability. These metrics help you understand sales performance, customer behavior, and margin analysis across new and returning customers. **Data Source:** [Shopify](/sources/shopify)\ **Metrics in Category:** 190+ ## Subcategories | Subcategory | Metrics | Description | | -------------------------------------------------------------------- | ------- | ------------------------------------------------- | | [Order Counts](/reference/metrics/orders/counts) | 9 | Order volume, units sold, and subscription orders | | [Revenue](/reference/metrics/orders/revenue) | 10 | Total, gross, and net revenue by customer type | | [Average Order Value](/reference/metrics/orders/aov) | 9 | AOV calculations across revenue types | | [Customers](/reference/metrics/orders/customers) | 8 | Customer counts and new vs returning rates | | [Adjustments](/reference/metrics/orders/adjustments) | 51 | Refunds, discounts, shipping, and tax | | [Cost of Goods Sold](/reference/metrics/orders/cogs) | 22 | Product costs and variable costs | | [Fulfillment Costs](/reference/metrics/orders/fulfillment) | 14 | Handling, shipping, and fulfillment expenses | | [Transaction Costs](/reference/metrics/orders/transaction) | 9 | Payment gateway and transaction fees | | [Contribution Margin](/reference/metrics/orders/contribution-margin) | 23 | CM1-CM4 margin calculations per order | | [Product Margin](/reference/metrics/orders/product-margin) | 9 | Gross profit and product-level margins | | [Performance](/reference/metrics/orders/performance) | 25 | ROAS, MER, CPA, and RAAD metrics | | [Lifetime Value](/reference/metrics/orders/ltv) | 6 | LTV and cohort analysis metrics | ## When to Use * **Order Counts:** When measuring order volume, units sold, or subscription acquisition * **Revenue:** When analyzing top-line sales performance by customer segment * **Average Order Value:** When optimizing cart value or comparing customer segments * **Customers:** When tracking customer acquisition and retention rates * **Adjustments:** When analyzing refund rates, discount impact, or tax/shipping revenue * **Cost of Goods Sold:** When calculating product margins and cost structures * **Fulfillment Costs:** When analyzing fulfillment efficiency and shipping expenses * **Transaction Costs:** When evaluating payment processing costs * **Contribution Margin:** When measuring profit contribution at different levels (CM1-CM4) * **Product Margin:** When analyzing gross profit and product-level profitability * **Performance:** When evaluating marketing efficiency with ROAS, MER, or CPA * **Lifetime Value:** When analyzing customer value and retention over time ## All Orders Metrics ### Order Counts | Metric | Description | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | [Orders](/reference/metrics/orders/counts/orders) | Total number of orders placed | | [Units Sold](/reference/metrics/orders/counts/units-sold) | Total product units sold | | [New Customer Units Sold](/reference/metrics/orders/counts/new-customer-units-sold) | Units sold to new customers | | [Returning Customer Units Sold](/reference/metrics/orders/counts/returning-customer-units-sold) | Units sold to returning customers | | [Units Per Order](/reference/metrics/orders/counts/units-per-order) | Average units per order | | [New Customer Units Per Order](/reference/metrics/orders/counts/new-customer-units-per-order) | Average units per new customer order | | [Returning Customer Units Per Order](/reference/metrics/orders/counts/returning-customer-units-per-order) | Average units per returning customer order | | [Subscription Initial Purchase Orders](/reference/metrics/orders/counts/subscription-initial-purchase-orders) | First-time subscription orders | | [Subscription Initial Purchase %](/reference/metrics/orders/counts/subscription-initial-purchase-percent) | Percentage of orders that are subscription initial purchases | ### Revenue | Metric | Description | | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | Sum of all order revenue | | [Gross Revenue](/reference/metrics/orders/revenue/gross-revenue) | Revenue before discounts and refunds | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Revenue after discounts and refunds | | [New Customer Total Revenue](/reference/metrics/orders/revenue/new-customer-total-revenue) | Total revenue from new customers | | [New Customer Gross Revenue](/reference/metrics/orders/revenue/new-customer-gross-revenue) | Gross revenue from new customers | | [New Customer Net Revenue](/reference/metrics/orders/revenue/new-customer-net-revenue) | Net revenue from new customers | | [Returning Customer Total Revenue](/reference/metrics/orders/revenue/returning-customer-total-revenue) | Total revenue from returning customers | | [Returning Customer Gross Revenue](/reference/metrics/orders/revenue/returning-customer-gross-revenue) | Gross revenue from returning customers | | [Returning Customer Net Revenue](/reference/metrics/orders/revenue/returning-customer-net-revenue) | Net revenue from returning customers | | [Subscription Initial Purchase Revenue](/reference/metrics/orders/revenue/subscription-initial-purchase-revenue) | Revenue from first-time subscription orders | ### Average Order Value | Metric | Description | | ------------------------------------------------------------------------------------------ | --------------------------------------- | | [Total AOV](/reference/metrics/orders/aov/total-aov) | Average order value using total revenue | | [Gross AOV](/reference/metrics/orders/aov/gross-aov) | Average order value using gross revenue | | [Net AOV](/reference/metrics/orders/aov/net-aov) | Average order value using net revenue | | [New Customer Total AOV](/reference/metrics/orders/aov/new-customer-total-aov) | Total AOV for new customers | | [New Customer Gross AOV](/reference/metrics/orders/aov/new-customer-gross-aov) | Gross AOV for new customers | | [New Customer Net AOV](/reference/metrics/orders/aov/new-customer-net-aov) | Net AOV for new customers | | [Returning Customer Total AOV](/reference/metrics/orders/aov/returning-customer-total-aov) | Total AOV for returning customers | | [Returning Customer Gross AOV](/reference/metrics/orders/aov/returning-customer-gross-aov) | Gross AOV for returning customers | | [Returning Customer Net AOV](/reference/metrics/orders/aov/returning-customer-net-aov) | Net AOV for returning customers | ### Customers | Metric | Description | | -------------------------------------------------------------------------------------------------- | --------------------------------------------- | | [Unique Customers](/reference/metrics/orders/customers/unique-customers) | Distinct customers who placed orders | | [New Customers](/reference/metrics/orders/customers/new-customers) | First-time customers | | [Returning Customers](/reference/metrics/orders/customers/returning-customers) | Customers with prior purchases | | [New Customer %](/reference/metrics/orders/customers/new-customer-percent) | Percentage of orders from new customers | | [Returning Customer %](/reference/metrics/orders/customers/returning-customer-percent) | Percentage of orders from returning customers | | [New Customer Gross Rate](/reference/metrics/orders/customers/new-customer-gross-rate) | New customer revenue as % of gross | | [Returning Customer Gross Rate](/reference/metrics/orders/customers/returning-customer-gross-rate) | Returning customer revenue as % of gross | | [Average Orders Per Customer](/reference/metrics/orders/customers/average-orders-per-customer) | Average number of orders per customer | ### Performance (ROAS, MER, CPA) | Metric | Description | | ---------------------------------------------------------------------------------------- | -------------------------------------- | | [CPA](/reference/metrics/orders/performance/cpa) | Cost per acquisition | | [New Customer CPA](/reference/metrics/orders/performance/new-customer-cpa) | Cost per new customer acquisition | | [Returning Customer CPA](/reference/metrics/orders/performance/returning-customer-cpa) | Cost per returning customer order | | [Total ROAS](/reference/metrics/orders/performance/total-roas) | Return on ad spend using total revenue | | [Gross ROAS](/reference/metrics/orders/performance/gross-roas) | Return on ad spend using gross revenue | | [Net ROAS](/reference/metrics/orders/performance/net-roas) | Return on ad spend using net revenue | | [New Customer Total ROAS](/reference/metrics/orders/performance/new-customer-total-roas) | New customer total ROAS | | [New Customer Gross ROAS](/reference/metrics/orders/performance/new-customer-gross-roas) | New customer gross ROAS | | [New Customer Net ROAS](/reference/metrics/orders/performance/new-customer-net-roas) | New customer net ROAS | | [Total MER](/reference/metrics/orders/performance/total-mer) | Marketing efficiency ratio (total) | | [Gross MER](/reference/metrics/orders/performance/gross-mer) | Marketing efficiency ratio (gross) | | [Net MER](/reference/metrics/orders/performance/net-mer) | Marketing efficiency ratio (net) | # CLV 120: 120-Day Cohort Lifetime Value Source: https://docs.upstackdata.com/reference/metrics/orders/ltv/clv-120 Track total cohort revenue within 120 days of first purchase. Use CLV 120 to evaluate acquisition quality and measure mid-term customer value. Total revenue generated by all customers within 120 days of their first purchase—a cohort-level sum, not a per-customer average. ## Formula **CLV 120** = **SUM** ( Customer Revenue ) **WHERE** days since first order ≤ 120 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | [**Customer Revenue**](/reference/metrics/orders/revenue/total-revenue) | Total revenue from all customer orders | | [**days since first order ≤ 120**](/data-dictionary/measures-and-dimensions) | Filters to orders placed within 120 days of each customer's first purchase | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Customers acquired in January generated **\$188,160** in total CLV 120: | Cohort | Customers | First Orders | Repeat Orders (120d) | CLV 120 | | ------- | --------- | ------------ | -------------------- | ------------- | | January | 1,200 | \$72,000 | \$116,160 | **\$188,160** | This is the combined revenue from all 1,200 customers' orders within their first 120 days. To get the average per customer (\$156.80), divide by customer count—that metric is [LTV 120](/reference/metrics/orders/ltv/ltv-120). *** ## How It Works CLV 120 sums all revenue from each customer's orders placed within 120 days of their first purchase. This 4-month window captures 1-2 repeat purchase cycles for most e-commerce brands, providing a balance between short-term payback evaluation and longer-term value projection without waiting a full year. *** ## When to Use | Scenario | Action | | ---------------------------- | ------------------------------------------------------------------ | | Evaluating acquisition spend | Compare CLV 120 to total acquisition cost for the cohort | | Measuring campaign ROI | Track total revenue generated from a specific campaign's customers | | Forecasting cohort value | Use CLV 120 growth curves to project longer-term revenue | | Budget allocation | Shift spend toward channels producing higher CLV 120 totals | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------ | ------------------------------------------------ | | [LTV 120](/reference/metrics/orders/ltv/ltv-120) | Average per-customer value (CLV 120 ÷ Customers) | | [CLV 90](/reference/metrics/orders/ltv/clv-90) | Shorter 90-day cohort value window | | [CLV 180](/reference/metrics/orders/ltv/clv-180) | Extended 180-day cohort value window | | [New Customers](/reference/metrics/orders/customers/new-customers) | Cohort customer count | [See all Lifetime Value metrics →](/reference/metrics/orders/ltv) # CLV 180: 180-Day Cohort Lifetime Value Source: https://docs.upstackdata.com/reference/metrics/orders/ltv/clv-180 Track total revenue from all customers within 180 days of first purchase. Learn the formula, see examples, and measure 6-month cohort revenue performance. Total revenue generated by all customers within 180 days (6 months) of their first purchase. ## Formula **CLV 180** = **SUM** ( Customer Revenue ) **WHERE** days since first order ≤ 180 ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | [**Customer Revenue**](/reference/metrics/orders/revenue/total-revenue) | Total revenue from all customer orders | | [**days since first order ≤ 180**](/data-dictionary/measures-and-dimensions#cohort-filters) | Filters to orders placed within 180 days of each customer's first purchase | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Analyzing customers acquired in January shows **\$127,800** in CLV 180: | Cohort | Customers | First Orders | Repeat Orders (180d) | CLV 180 | | -------- | --------- | ------------ | -------------------- | --------- | | January | 1,200 | \$72,000 | \$55,800 | \$127,800 | | February | 1,450 | \$87,000 | \$71,050 | \$158,050 | | March | 1,100 | \$66,000 | \$52,800 | \$118,800 | The January cohort's CLV 180 of \$127,800 represents all revenue from those 1,200 customers within 6 months of their first purchase. *** ## How It Works CLV 180 sums all revenue from each customer's orders within 180 days of their first purchase. This includes their initial order plus any repeat purchases made in that window. Unlike [LTV 180](/reference/metrics/orders/ltv/ltv-180) which calculates an average per customer, CLV 180 shows the total dollar value generated by the entire cohort—making it ideal for measuring aggregate cohort performance and ROI. *** ## When to Use | Scenario | Action | | ------------------------------ | ----------------------------------------------------------------- | | Measuring cohort ROI | Compare CLV 180 against total acquisition spend for the cohort | | Budgeting acquisition spend | Set monthly acquisition budgets based on expected CLV 180 returns | | Evaluating marketing campaigns | Track CLV 180 for customers acquired during specific campaigns | | Forecasting 6-month revenue | Project total revenue from newly acquired customer cohorts | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------- | ----------------------------------------------------------- | | [CLV 90](/reference/metrics/orders/ltv/clv-90) | Shorter 90-day window for faster cohort performance signals | | [CLV 365](/reference/metrics/orders/ltv/clv-365) | Full-year total for complete cohort value assessment | | [LTV 180](/reference/metrics/orders/ltv/ltv-180) | Average per-customer value (same 180-day window) | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | Total revenue across all customers and timeframes | [See all Lifetime Value metrics →](/reference/metrics/orders/ltv) # CLV 30: 30-Day Cohort Lifetime Value Source: https://docs.upstackdata.com/reference/metrics/orders/ltv/clv-30 Track total cohort revenue within 30 days of first purchase. Use CLV 30 to evaluate acquisition quality and project early customer value. Total revenue generated by all customers within 30 days of their first purchase—a cohort-level sum, not a per-customer average. ## Formula **CLV 30** = **SUM** ( Customer Revenue ) **WHERE** days since first order ≤ 30 ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | [**Customer Revenue**](/reference/metrics/orders/revenue/total-revenue) | Total revenue from all customer orders | | [**days since first order ≤ 30**](/data-dictionary/measures-and-dimensions) | Filters to orders placed within 30 days of each customer's first purchase | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Customers acquired in January generated **\$89,400** in total CLV 30: | Cohort | Customers | First Orders | Repeat Orders (30d) | CLV 30 | | ------- | --------- | ------------ | ------------------- | ------------ | | January | 1,200 | \$72,000 | \$17,400 | **\$89,400** | This is the combined revenue from all 1,200 customers' orders within their first 30 days. To get the average per customer (\$74.50), divide by customer count—that metric is [LTV 30](/reference/metrics/orders/ltv/ltv-30). *** ## How It Works CLV 30 sums all revenue from each customer's orders placed within 30 days of their first purchase. This includes initial orders plus any repeat purchases in that window. The metric captures total cohort value rather than per-customer averages, making it useful for aggregate financial analysis. *** ## When to Use | Scenario | Action | | ---------------------------- | ------------------------------------------------------------------ | | Evaluating acquisition spend | Compare CLV 30 to total acquisition cost for the cohort | | Measuring campaign ROI | Track total revenue generated from a specific campaign's customers | | Forecasting cohort value | Use CLV 30 growth curves to project longer-term revenue | | Budget allocation | Shift spend toward channels producing higher CLV 30 totals | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------ | ----------------------------------------------- | | [LTV 30](/reference/metrics/orders/ltv/ltv-30) | Average per-customer value (CLV 30 ÷ Customers) | | [CLV 60](/reference/metrics/orders/ltv/clv-60) | Extended 60-day cohort value window | | [CLV 90](/reference/metrics/orders/ltv/clv-90) | Extended 90-day cohort value window | | [New Customers](/reference/metrics/orders/customers/new-customers) | Cohort customer count | [See all Lifetime Value metrics →](/reference/metrics/orders/ltv) # CLV 365: 365-Day Cohort Lifetime Value Source: https://docs.upstackdata.com/reference/metrics/orders/ltv/clv-365 Track total cohort revenue within 365 days of first purchase. Use CLV 365 to measure annual customer value and benchmark acquisition ROI. Total revenue generated by all customers within 365 days of their first purchase—a cohort-level sum, not a per-customer average. ## Formula **CLV 365** = **SUM** ( Customer Revenue ) **WHERE** days since first order ≤ 365 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | [**Customer Revenue**](/reference/metrics/orders/revenue/total-revenue) | Total revenue from all customer orders | | [**days since first order ≤ 365**](/data-dictionary/measures-and-dimensions) | Filters to orders placed within 365 days of each customer's first purchase | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Customers acquired in January generated **\$892,500** in total CLV 365: | Cohort | Customers | First Orders | Repeat Orders (365d) | CLV 365 | | ------- | --------- | ------------ | -------------------- | ------------- | | January | 2,500 | \$312,500 | \$580,000 | **\$892,500** | This is the combined revenue from all 2,500 customers' orders within their first year. To get the average per customer (\$357), divide by customer count—that metric is [LTV 365](/reference/metrics/orders/ltv/ltv-365). *** ## How It Works CLV 365 sums all revenue from each customer's orders placed within 365 days (one year) of their first purchase. This includes initial orders plus any repeat purchases in that window. The metric captures total annual cohort value rather than per-customer averages, making it the standard benchmark for yearly acquisition ROI. *** ## When to Use | Scenario | Action | | --------------------------------- | ------------------------------------------------------------- | | Evaluating annual acquisition ROI | Compare CLV 365 to total acquisition cost for the cohort | | Setting yearly revenue targets | Use CLV 365 trends to forecast annual cohort revenue | | Measuring campaign effectiveness | Track total yearly revenue generated from campaign customers | | Budget planning | Allocate acquisition spend based on projected CLV 365 returns | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------ | ------------------------------------------------ | | [LTV 365](/reference/metrics/orders/ltv/ltv-365) | Average per-customer value (CLV 365 ÷ Customers) | | [CLV 180](/reference/metrics/orders/ltv/clv-180) | Shorter 180-day cohort value window | | [CLV 90](/reference/metrics/orders/ltv/clv-90) | Shorter 90-day cohort value window | | [New Customers](/reference/metrics/orders/customers/new-customers) | Cohort customer count | [See all Lifetime Value metrics →](/reference/metrics/orders/ltv) # CLV 60: 60-Day Cohort Lifetime Value Source: https://docs.upstackdata.com/reference/metrics/orders/ltv/clv-60 Track total cohort revenue within 60 days of first purchase. Use CLV 60 to evaluate acquisition quality and project early customer value. Total revenue generated by all customers within 60 days of their first purchase—a cohort-level sum, not a per-customer average. ## Formula **CLV 60** = **SUM** ( Customer Revenue ) **WHERE** days since first order ≤ 60 ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | [**Customer Revenue**](/reference/metrics/orders/revenue/total-revenue) | Total revenue from all customer orders | | [**days since first order ≤ 60**](/data-dictionary/measures-and-dimensions) | Filters to orders placed within 60 days of each customer's first purchase | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Customers acquired in January generated **\$142,800** in total CLV 60: | Cohort | Customers | First Orders | Repeat Orders (60d) | CLV 60 | | ------- | --------- | ------------ | ------------------- | ------------- | | January | 1,200 | \$72,000 | \$70,800 | **\$142,800** | This is the combined revenue from all 1,200 customers' orders within their first 60 days. To get the average per customer (\$119.00), divide by customer count—that metric is [LTV 60](/reference/metrics/orders/ltv/ltv-60). *** ## How It Works CLV 60 sums all revenue from each customer's orders placed within 60 days of their first purchase. This includes initial orders plus any repeat purchases in that window. The metric captures total cohort value rather than per-customer averages, making it useful for aggregate financial analysis and comparing total returns across acquisition channels. *** ## When to Use | Scenario | Action | | ---------------------------- | ------------------------------------------------------------------ | | Evaluating acquisition spend | Compare CLV 60 to total acquisition cost for the cohort | | Measuring campaign ROI | Track total revenue generated from a specific campaign's customers | | Forecasting cohort value | Use CLV 60 growth curves to project longer-term revenue | | Budget allocation | Shift spend toward channels producing higher CLV 60 totals | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------ | ----------------------------------------------- | | [LTV 60](/reference/metrics/orders/ltv/ltv-60) | Average per-customer value (CLV 60 ÷ Customers) | | [CLV 30](/reference/metrics/orders/ltv/clv-30) | Shorter 30-day cohort value window | | [CLV 90](/reference/metrics/orders/ltv/clv-90) | Extended 90-day cohort value window | | [New Customers](/reference/metrics/orders/customers/new-customers) | Cohort customer count | [See all Lifetime Value metrics →](/reference/metrics/orders/ltv) # CLV 90: 90-Day Cohort Lifetime Value - Total Source: https://docs.upstackdata.com/reference/metrics/orders/ltv/clv-90 Track total revenue from customers within 90 days of first purchase. Measure cohort-level revenue performance and early customer value realization. Total revenue generated by all customers within 90 days of their first purchase. ## Formula **CLV 90** = **SUM** ( Customer Revenue ) **WHERE** days since first order ≤ 90 ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | [**Customer Revenue**](/reference/metrics/orders/revenue/total-revenue) | Total revenue from all customer orders | | [**days since first order ≤ 90**](/data-dictionary/measures-and-dimensions#customer-type) | Filters to orders placed within 90 days of each customer's first purchase | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your January cohort generated **\$153,000** in total revenue within their first 90 days: | Cohort | Customers | CLV 90 | | ------------- | --------- | --------- | | January 2024 | 1,200 | \$153,000 | | February 2024 | 980 | \$118,580 | | March 2024 | 1,450 | \$195,750 | The March cohort has the highest CLV 90 despite February having fewer customers—indicating stronger early purchase behavior in that acquisition period. *** ## How It Works CLV 90 sums all revenue from orders placed within 90 days of each customer's first purchase. Unlike [LTV 90](/reference/metrics/orders/ltv/ltv-90) which calculates the average per customer, CLV 90 shows the total dollar value realized from a cohort. This makes it useful for measuring aggregate revenue performance and forecasting cohort-level returns. *** ## When to Use | Scenario | Action | | ----------------------- | ------------------------------------------------------------ | | Cohort revenue tracking | Measure total revenue generated by acquisition cohorts | | Budget forecasting | Project aggregate revenue from recent customer cohorts | | Marketing ROI analysis | Compare total cohort revenue to total acquisition spend | | Cohort comparison | Identify which acquisition periods generate more total value | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------- | ------------------------------------------------- | | [LTV 90](/reference/metrics/orders/ltv/ltv-90) | Average revenue per customer (CLV 90 ÷ Customers) | | [CLV 180](/reference/metrics/orders/ltv/clv-180) | Extended 180-day total revenue window | | [CLV 365](/reference/metrics/orders/ltv/clv-365) | Full-year total cohort revenue | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | All-time total revenue (not cohort-windowed) | [See all LTV metrics →](/reference/metrics/orders/ltv) # Lifetime Value Metrics Source: https://docs.upstackdata.com/reference/metrics/orders/ltv/index Measure customer lifetime value, payback periods, and long-term profitability from Shopify order data. Lifetime Value metrics help you understand the long-term profitability of your customers and evaluate the sustainability of your acquisition strategy. ## Available Metrics | Metric | Description | | ---------------------------------------------------------- | ------------------------------------------------------------------- | | [LTV](/reference/metrics/orders/ltv/ltv) | Average total revenue per customer across all purchases | | [CLV 30](/reference/metrics/orders/ltv/clv-30) | Total revenue from customers within 30 days of first purchase | | [CLV 180](/reference/metrics/orders/ltv/clv-180) | Total revenue from customers within 180 days of first purchase | | [LTV:CAC](/reference/metrics/orders/ltv/ltv-cac) | Ratio of customer lifetime value to acquisition cost | | [Payback Days](/reference/metrics/orders/ltv/payback-days) | Days until cumulative contribution margin recovers acquisition cost | ## Why LTV Matters Understanding customer lifetime value allows you to: * **Set sustainable CAC targets** — Know how much you can afford to spend acquiring customers * **Evaluate channel quality** — Compare which acquisition channels produce the most valuable customers * **Plan cash flow** — Predict when acquisition investments will become profitable * **Optimize retention** — Focus on strategies that extend customer lifetime and increase repeat purchases # LTV: Customer Lifetime Value Source: https://docs.upstackdata.com/reference/metrics/orders/ltv/ltv Track cumulative customer lifetime value in Upstack. Measure total revenue generated per customer across all purchases since their first order. Average total revenue generated per customer across all their purchases since their first order. ## Formula **LTV** = **Total Customer Revenue** ÷ **Customer Count** ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------- | ---------------------------------------------------------------- | | [**Total Customer Revenue**](/reference/metrics/orders/revenue/total-revenue) | Sum of all order revenue across each customer's purchase history | | [**Customer Count**](/reference/metrics/orders/customers/unique-customers) | Number of unique customers who placed at least one order | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your store has **2,500 customers** who have generated **\$625,000** in total revenue since they first purchased: | Metric | Value | | ------------------------ | ------------ | | Total Revenue (All-Time) | \$625,000 | | Unique Customers | 2,500 | | **LTV** | **\$250.00** | *** ## How It Works LTV calculates the average total revenue per customer across their entire purchase history. It sums all orders for each customer from their first purchase to present, then averages across all customers. Unlike time-bounded LTV metrics (90d, 180d, 365d), this captures full customer lifetime value. *** ## When to Use | Scenario | Action | | --------------------------------------------- | ----------------------------------------------------------- | | Evaluating customer acquisition profitability | Compare LTV to Customer Acquisition Cost (CAC) | | Setting max CPA targets | Use LTV to determine sustainable acquisition spend | | Segmenting high-value customers | Identify customers above average LTV for retention programs | | Forecasting long-term revenue | Project revenue based on expected customer acquisition | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------ | ------------------------------------- | | [LTV 90d](/reference/metrics/orders/ltv/ltv-90) | 90-day customer value | | [LTV 180d](/reference/metrics/orders/ltv/ltv-180) | 180-day customer value | | [LTV 365d](/reference/metrics/orders/ltv/ltv-365) | Full-year customer value | | [Unique Customers](/reference/metrics/orders/customers/unique-customers) | Denominator for LTV calculation | | [AOV](/reference/metrics/orders/aov/total-aov) | Per-order value vs per-customer value | [See all LTV metrics →](/reference/metrics/orders/ltv) # LTV 120: 120-Day Customer Lifetime Value Source: https://docs.upstackdata.com/reference/metrics/orders/ltv/ltv-120 Measure average revenue per customer within 120 days of their first purchase. Use LTV 120 to evaluate mid-term acquisition payback and retention trends. Average revenue generated per customer within 120 days (4 months) of their first purchase. ## Formula **LTV 120** = **Total Revenue (120d Window)** ÷ **Customer Count** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------- | ------------------------------------------------------ | | [**Total Revenue**](/reference/metrics/orders/revenue/total-revenue) | Sum of order revenue within 120 days of first purchase | | [**Customer Count**](/reference/metrics/orders/customers/unique-customers) | Number of customers in the cohort | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your January cohort of **850 new customers** generated **\$80,750** within their first 120 days: | Cohort | Customers | Revenue (120d) | LTV 120 | | -------- | --------- | -------------- | -------- | | January | 850 | \$80,750 | \$95.00 | | February | 920 | \$92,000 | \$100.00 | | March | 780 | \$70,200 | \$90.00 | *** ## How It Works LTV 120 calculates the average total revenue per customer within 120 days of their first purchase. Each customer's orders placed within this 120-day window are summed, then averaged across all customers in the cohort. The 4-month window captures mid-term repurchase behavior and provides a balance between short-term payback (LTV 90) and longer evaluation periods (LTV 180/365). *** ## When to Use | Scenario | Action | | ------------------------------ | ----------------------------------------------------------- | | Quarterly acquisition planning | Compare LTV 120 against CAC to evaluate 4-month payback | | Retention program evaluation | Track if loyalty programs improve LTV 120 vs baseline | | Subscription product analysis | Assess value from initial purchase plus first renewal cycle | | Seasonal cohort comparison | Compare cohorts acquired in different quarters | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------- | ---------------------------------------------------- | | [LTV 90](/reference/metrics/orders/ltv/ltv-90) | Shorter window (90 days) for faster payback analysis | | [LTV 180](/reference/metrics/orders/ltv/ltv-180) | Extended window (180 days) for longer-term value | | [LTV 365](/reference/metrics/orders/ltv/ltv-365) | Full-year customer value benchmark | | [AOV](/reference/metrics/orders/aov/total-aov) | Per-order value vs per-customer value | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | Revenue without time-window constraints | [See all LTV metrics →](/reference/metrics/orders/ltv) # LTV 180: 6-Month Customer Lifetime Value Source: https://docs.upstackdata.com/reference/metrics/orders/ltv/ltv-180 Track customer lifetime value at 180 days post-acquisition. Measure 6-month revenue per customer to evaluate mid-term acquisition ROI. Average revenue generated per customer within 180 days (6 months) of their first purchase. ## Formula **LTV 180** = **Total Revenue (180d Window)** ÷ **Customer Count** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | [**Total Revenue**](/reference/metrics/orders/revenue/total-revenue) | Sum of all order revenue within 180 days of each customer's first purchase | | **Customer Count** | Number of unique customers in the cohort who made their first purchase during the selected period | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your Q1 cohort of **2,500 new customers** generated **\$312,500** within their first 180 days: | Cohort | Customers | Revenue (180d) | LTV 180 | | ------- | --------- | -------------- | -------- | | Q1 2024 | 2,500 | \$312,500 | \$125.00 | | Q2 2024 | 2,800 | \$378,000 | \$135.00 | | Q3 2024 | 2,200 | \$308,000 | \$140.00 | If your average CAC is \$45, the Q3 cohort's 6-month LTV:CAC ratio is **3.1×**—indicating healthy acquisition economics. *** ## How It Works LTV 180 calculates the average total revenue per customer within 180 days of their first purchase. This 6-month window captures two to three typical purchase cycles for most repeat-buy categories like consumables, skincare, and apparel—making it ideal for evaluating mid-term acquisition payback. *** ## When to Use | Scenario | Action | | ----------------------------------------- | ----------------------------------------------------------------------------------------- | | Evaluating acquisition channel efficiency | Compare LTV 180 across channels to identify which sources deliver the best mid-term value | | Setting CAC targets for paid media | Use LTV 180 to establish maximum acceptable acquisition costs with 6-month payback | | Measuring retention program impact | Track LTV 180 before and after launching loyalty or subscription programs | | Forecasting cohort revenue | Project 6-month revenue for new customer cohorts based on historical LTV 180 | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------ | -------------------------------------------------- | | [LTV 90](/reference/metrics/orders/ltv/ltv-90) | Shorter 90-day window for faster payback analysis | | [LTV 120](/reference/metrics/orders/ltv/ltv-120) | 4-month window between short and mid-term | | [LTV 365](/reference/metrics/orders/ltv/ltv-365) | Full-year LTV for long-term acquisition benchmarks | | [AOV](/reference/metrics/orders/revenue/aov) | Per-order value vs per-customer value | [See all LTV metrics →](/reference/metrics/orders/ltv) # LTV 30: 30-Day Customer Lifetime Value Source: https://docs.upstackdata.com/reference/metrics/orders/ltv/ltv-30 Measure average revenue per customer within 30 days of first purchase. Track early customer value to optimize acquisition spend and onboarding. Average revenue generated per customer within the first 30 days following their initial purchase. ## Formula **LTV 30** = **Total Revenue (30d Window)** ÷ **Customer Count** ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------- | --------------------------------------------------------------------- | | [**Total Revenue**](/reference/metrics/orders/revenue/total-revenue) | Sum of order revenue within 30 days of first purchase | | [**Unique Customers**](/reference/metrics/orders/customers/unique-customers) | Count of customers who made their first purchase in the cohort period | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Customers acquired in January generated **\$127.50** average revenue within their first 30 days: | Metric | Value | | -------------------- | ------------ | | Total 30-day Revenue | \$63,750 | | New Customers | 500 | | **LTV 30** | **\$127.50** | A customer who spent \$80 on their first order and \$60 on a second order within 30 days contributes \$140 to the numerator. Orders placed after day 30 are excluded from this metric. *** ## How It Works LTV 30 cohorts customers by their initial order date, then sums all revenue from orders placed within 30 days of that first purchase. The total is divided by the number of customers in the cohort. This 30-day window captures early repeat purchase behavior before longer-term retention patterns emerge. *** ## When to Use | Scenario | Action | | --------------------------- | ---------------------------------------------------------------------- | | Setting acquisition budgets | Compare LTV 30 to Customer Acquisition Cost (CAC) for payback planning | | Evaluating channel quality | Identify which sources bring customers with higher early value | | Measuring onboarding impact | Track whether welcome flows increase revenue in the first month | | Quick cohort comparison | Compare cohorts without waiting for longer LTV windows to mature | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------ | ---------------------------------------------------- | | [LTV 60](/reference/metrics/orders/ltv/ltv-60) | Extended 60-day lifetime value window | | [LTV 90](/reference/metrics/orders/ltv/ltv-90) | Extended 90-day lifetime value window | | [Total AOV](/reference/metrics/orders/aov/total-aov) | Per-order average vs. per-customer average over time | | [New Customers](/reference/metrics/orders/customers/new-customers) | First-time buyer count used in cohort denominators | [See all LTV metrics →](/reference/metrics/orders/ltv) # LTV 365: Full-Year Customer Lifetime Value Source: https://docs.upstackdata.com/reference/metrics/orders/ltv/ltv-365 Track customer lifetime value at 365 days from first purchase. The standard full-year LTV benchmark for evaluating acquisition quality and long-term retention. Average revenue generated per customer within 365 days (1 year) of their first purchase—the standard full-year LTV benchmark. ## Formula **LTV 365** = **Total Revenue (365d Window)** ÷ **Customer Count** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | [**Total Revenue**](/reference/metrics/orders/revenue/total-revenue) | Sum of order revenue within 365 days of first purchase | | [**Customer Count**](/reference/metrics/orders/customers/unique-customers) | Number of unique customers in the cohort who made their first purchase during the selected period | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your January cohort of **500 new customers** generated **\$175,000** in total revenue within their first 365 days: | Cohort | Customers | Revenue (365d) | LTV 365 | | -------- | --------- | -------------- | -------- | | January | 500 | \$175,000 | \$350.00 | | February | 450 | \$144,000 | \$320.00 | | March | 525 | \$199,500 | \$380.00 | If your average CAC is \$75, the January cohort's full-year LTV:CAC ratio is **4.7×**—indicating strong acquisition economics with annual payback. *** ## How It Works LTV 365 calculates the average revenue per customer over their first full year. Customers are grouped by first purchase date (cohort), and their cumulative spending is tracked for 365 days. This provides the industry-standard timeframe to compare customer value across acquisition channels, campaigns, and seasons. *** ## When to Use | Scenario | Action | | ------------------------------- | ------------------------------------------------------------------------------------------------ | | Annual acquisition benchmarking | Compare full-year LTV across Meta, Google, TikTok, and organic to identify highest-value sources | | Setting annual CAC targets | Use LTV 365 to determine sustainable acquisition costs with 12-month payback expectations | | Measuring retention program ROI | Track how loyalty and subscription programs affect long-term customer value | | Forecasting annual revenue | Project year-over-year revenue from recent cohorts using historical LTV 365 data | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------ | -------------------------------------------------------- | | [LTV 180](/reference/metrics/orders/ltv/ltv-180) | 6-month mid-term value for faster payback analysis | | [LTV 120](/reference/metrics/orders/ltv/ltv-120) | 4-month window for quarterly payback assessment | | [LTV 90](/reference/metrics/orders/ltv/ltv-90) | 90-day short-term value for quick acquisition evaluation | | [LTV](/reference/metrics/orders/ltv/ltv) | All-time lifetime value without time cap | | [LTV:CAC](/reference/metrics/orders/ltv/ltv-cac) | Ratio of customer value to acquisition cost | [See all LTV metrics →](/reference/metrics/orders/ltv) # LTV 60: 60-Day Customer Lifetime Value Source: https://docs.upstackdata.com/reference/metrics/orders/ltv/ltv-60 Track 60-day customer lifetime value to measure early revenue per customer. Evaluate acquisition quality and predict long-term customer profitability. Average revenue generated per customer within 60 days of their first purchase. ## Formula **LTV 60** = **Total Revenue (60d Window)** ÷ **Customer Count** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------- | ----------------------------------------------------- | | [**Total Revenue**](/reference/metrics/orders/revenue/total-revenue) | Sum of order revenue within 60 days of first purchase | | **Customer Count** | Number of unique customers in the cohort | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Customers acquired in January generated **\$89.50** average LTV within 60 days: | Cohort | Customers | Total Revenue | LTV 60 | | ------------- | --------- | ------------- | ------- | | January 2024 | 1,247 | \$111,612 | \$89.50 | | February 2024 | 1,089 | \$103,455 | \$95.00 | | March 2024 | 1,456 | \$116,480 | \$80.00 | *** ## How It Works LTV 60 measures the cumulative revenue each customer generates within their first 60 days. Upstack tracks each customer's first order date, then sums all subsequent orders within the 60-day window. The metric is calculated per cohort (customers acquired in the same period). *** ## When to Use | Scenario | Action | | ------------------------------ | ---------------------------------------------------------- | | Evaluating acquisition quality | Compare 60-day LTV across marketing channels | | Predicting long-term value | Use LTV 60 as an early indicator for LTV 90/180/365 | | Setting CAC targets | Ensure customer acquisition cost stays below LTV 60 | | Optimizing retention efforts | Identify cohorts with low early LTV for targeted campaigns | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------ | ----------------------------------------------- | | [LTV 30](/reference/metrics/orders/ltv/ltv-30) | Shorter 30-day window for earliest value signal | | [LTV 90](/reference/metrics/orders/ltv/ltv-90) | Extended 90-day window for fuller picture | | [LTV 180](/reference/metrics/orders/ltv/ltv-180) | Captures mid-term customer value | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | The numerator summed across all customers | | [New Customers](/reference/metrics/orders/customers/new-customers) | Contributes to the cohort customer count | [See all Lifetime Value metrics →](/reference/metrics/orders/ltv) # LTV 90: 90-Day Customer Lifetime Value Source: https://docs.upstackdata.com/reference/metrics/orders/ltv/ltv-90 Track customer lifetime value at 90 days from first purchase. Evaluate short-term payback on acquisition spend and optimize marketing ROI. Average revenue generated per customer within 90 days of their first purchase. ## Formula **LTV 90** = **Total Revenue (90d Window)** ÷ **Customer Count** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------- | ----------------------------------------------------- | | [**Total Revenue**](/reference/metrics/orders/revenue/total-revenue) | Sum of order revenue within 90 days of first purchase | | [**Customer Count**](/reference/metrics/orders/customers/unique-customers) | Number of customers in the cohort | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your January cohort of **1,200 new customers** generated **\$84,000** within their first 90 days: | Cohort | Customers | Revenue (90d) | LTV 90 | | -------- | --------- | ------------- | ------- | | January | 1,200 | \$84,000 | \$70.00 | | February | 1,450 | \$101,500 | \$70.00 | | March | 1,100 | \$88,000 | \$80.00 | *** ## How It Works LTV 90 calculates the average total revenue per customer within 90 days of their first purchase. Each customer's orders placed within this 90-day window are summed, then averaged across all customers in the cohort. This captures short-term repurchase behavior and helps evaluate acquisition payback. *** ## When to Use | Scenario | Action | | ------------------------------ | ------------------------------------------------------------------ | | Evaluating acquisition payback | Compare LTV 90 to Customer Acquisition Cost (CAC) | | Optimizing ad spend | Ensure LTV 90 exceeds blended CPA for sustainability | | Comparing cohort quality | Identify which acquisition channels produce higher-value customers | | Forecasting revenue | Project short-term revenue from new customer acquisition | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------- | ---------------------------------------------------- | | [LTV 60](/reference/metrics/orders/ltv/ltv-60) | Shorter window (60 days) for faster payback analysis | | [LTV 180](/reference/metrics/orders/ltv/ltv-180) | Extended window (180 days) for longer-term value | | [LTV 365](/reference/metrics/orders/ltv/ltv-365) | Full-year customer value | | [AOV](/reference/metrics/orders/aov/total-aov) | Per-order value vs per-customer value | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | Revenue without time-window constraints | [See all LTV metrics →](/reference/metrics/orders/ltv) # LTV:CAC: Customer Lifetime Value to Acquisition Cost Ratio Source: https://docs.upstackdata.com/reference/metrics/orders/ltv/ltv-cac Track LTV:CAC ratio to measure customer acquisition efficiency. Compare lifetime value to acquisition cost and optimize marketing spend for sustainable growth. The ratio of customer lifetime value to customer acquisition cost—a healthy LTV:CAC is 3:1 or higher, meaning each customer generates \$3 in value for every \$1 spent acquiring them. ## Formula **LTV:CAC** = **Customer Lifetime Value (LTV)** ÷ **Customer Acquisition Cost (CAC)** ### Formula Components | Metric | Definition | | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | [**Customer Lifetime Value (LTV)**](/reference/metrics/orders/ltv/ltv-365) | Average total revenue generated per customer over 365 days from first purchase | | [**Customer Acquisition Cost (CAC)**](/reference/metrics/orders/performance/cac) | Total advertising spend divided by number of new customers acquired | | Metadata | | | --------------- | ------------------------------------------------------------------------------------------------- | | **Type** | Ratio | | **Data Source** | [Shopify](/sources/shopify), [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads) | | **Aggregation** | Ratio | *** ## Example Your store acquired **500 new customers** last quarter with a **\$45,000** marketing spend, and your customers have an average 365-day lifetime value of **\$270**: | Metric | Value | | ----------- | --------- | | LTV (365d) | \$270 | | CAC | \$90 | | **LTV:CAC** | **3.0:1** | A **3:1 LTV:CAC ratio** means each customer generates \$3 in lifetime value for every \$1 spent acquiring them—the industry benchmark for healthy unit economics. *** ## How It Works LTV:CAC divides the average revenue a customer generates over their lifetime (typically measured at 365 days) by the cost to acquire that customer. This ratio reveals whether your customer acquisition is sustainable—if you spend more to acquire customers than they're worth, growth becomes unprofitable. *** ## When to Use | Scenario | Action | | ------------------------------------- | ------------------------------------------------------------------------ | | Evaluating acquisition sustainability | Ensure LTV:CAC stays above 3:1 for healthy unit economics | | Setting marketing budgets | Use LTV:CAC to determine maximum sustainable CAC | | Comparing acquisition channels | Identify which channels produce highest-value customers relative to cost | | Forecasting profitability | Project long-term returns on customer acquisition investments | *** ## Interpretation Guide | LTV:CAC Ratio | Interpretation | | ------------- | ---------------------------------------------------------------- | | Below 1:1 | Unsustainable—spending more to acquire than customers generate | | 1:1 to 2:1 | Marginally profitable—limited room for overhead and reinvestment | | 3:1 | Industry benchmark—healthy acquisition economics | | Above 5:1 | May indicate underinvestment in growth opportunities | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------- | --------------------------------------------- | | [LTV 365d](/reference/metrics/orders/ltv/ltv-365) | Numerator—full-year customer lifetime value | | [CAC](/reference/metrics/orders/performance/cac) | Denominator—cost to acquire each new customer | | [LTV 90d](/reference/metrics/orders/ltv/ltv-90) | Short-term LTV for faster payback analysis | | [Payback Days](/reference/metrics/orders/ltv/payback-days) | Time to recover acquisition cost | [See all LTV metrics →](/reference/metrics/orders/ltv) # Payback Days: Time to Recover Acquisition Cost Source: https://docs.upstackdata.com/reference/metrics/orders/ltv/payback-days Measure how many days it takes to recover customer acquisition costs through cumulative contribution margin from Shopify order data. The number of days it takes for a customer cohort's cumulative contribution margin to equal the cost of acquiring them. ## Formula **Payback Days** = **Days** until **Cumulative Contribution Margin** ≥ **CAC** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | [**Cumulative Contribution Margin**](/reference/metrics/orders/contribution-margin/contribution-margin) | Running total of contribution margin generated by a customer cohort over time | | [**CAC**](/reference/metrics/orders/performance/cac) | Customer Acquisition Cost — total ad spend divided by new customers acquired | | Metadata | | | --------------- | --------------------------- | | **Type** | Number (Days) | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your January cohort of **500 new customers** cost **\$25,000** to acquire (CAC = \$50/customer): | Days Since Acquisition | Cumulative CM | % of CAC Recovered | | ---------------------- | ------------- | ------------------ | | 30 days | \$15,000 | 60% | | 60 days | \$22,500 | 90% | | **75 days** | **\$25,000** | **100%** | | 90 days | \$30,000 | 120% | **Payback Days = 75** — it took 75 days for this cohort to generate enough contribution margin to cover their acquisition cost. *** ## How It Works Payback Days tracks a customer cohort from acquisition through subsequent purchases, summing the contribution margin from each order. The metric identifies the day when cumulative contribution margin equals or exceeds the original customer acquisition cost. Shorter payback periods indicate healthier unit economics and faster reinvestment of marketing capital. *** ## When to Use | Scenario | Action | | --------------------------------- | ----------------------------------------------------------------- | | Evaluating acquisition efficiency | Compare payback across channels to find fastest-returning sources | | Cash flow planning | Shorter payback means faster capital recovery for reinvestment | | LTV:CAC analysis | Payback under 12 months typically indicates sustainable growth | | Seasonal planning | Account for longer payback during low-margin periods | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | [Contribution Margin](/reference/metrics/orders/contribution-margin/contribution-margin) | The margin used to calculate cumulative payback | | [CAC](/reference/metrics/orders/performance/cac) | The acquisition cost that payback recovers | | [LTV](/reference/metrics/orders/ltv/ltv) | Lifetime value — compare to CAC alongside payback | | [LTV:CAC](/reference/metrics/orders/ltv/ltv-cac) | Ratio showing how many times over customers repay acquisition cost | [See all Lifetime Value metrics →](/reference/metrics/orders/ltv) # Average Days Between Orders: Purchase Frequency Metric Source: https://docs.upstackdata.com/reference/metrics/orders/performance/average-days-between-orders Measure how many days pass between repeat purchases. Track customer buying frequency to optimize retention campaigns and predict reorder timing. The average number of days between a customer's consecutive orders. ## Formula **Average Days Between Orders** = **Sum of Days Between Consecutive Orders** ÷ **Number of Repeat Purchase Intervals** ### Formula Components | Metric | Definition | | ----------------------------- | -------------------------------------------------------------- | | **Days Between Orders** | Calendar days from one order to the next for the same customer | | **Repeat Purchase Intervals** | Count of order pairs (2nd order, 3rd order, etc.) | | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your store's customers place repeat orders an average of **32 days** apart: | Customer Segment | Avg Days | Interpretation | | ------------------- | -------- | -------------------------- | | Subscription buyers | 28 days | Regular monthly cycle | | Consumables | 35 days | Product lifespan \~5 weeks | | Apparel | 62 days | Seasonal buying patterns | *** ## How It Works Average Days Between Orders calculates the time gap between each customer's consecutive purchases, then averages across all repeat purchase intervals in your selected period. Only customers with 2+ orders contribute to this metric—first-time buyers are excluded since they have no interval to measure. *** ## When to Use | Scenario | Action | | ---------------------- | ---------------------------------------------------------- | | Setting email cadence | Time win-back flows to trigger before the average interval | | Subscription pricing | Set billing cycles to match natural purchase frequency | | Inventory planning | Forecast demand based on typical reorder timing | | Retention benchmarking | Compare segments to identify high-frequency cohorts | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------- | --------------------------------------------------------- | | [Purchase Frequency](/reference/metrics/orders/performance/purchase-frequency) | Orders per customer (inverse relationship) | | [Returning Customer %](/reference/metrics/orders/customers/returning-customer-percent) | % of customers who reorder (prerequisite for this metric) | | [LTV 365](/reference/metrics/orders/ltv/ltv-365) | Shorter intervals often correlate with higher LTV | [See all Performance metrics →](/reference/metrics/orders/performance) # CAC: Customer Acquisition Cost Source: https://docs.upstackdata.com/reference/metrics/orders/performance/cac Track your Customer Acquisition Cost (CAC) to understand how much you spend to acquire each new customer. Optimize marketing efficiency and improve profitability. The average cost to acquire a new customer, calculated by dividing total ad spend by the number of new customers. ## Formula **Customer Acquisition Cost** = **Total Ad Spend** ÷ **New Customers** ### Formula Components | Metric | Definition | | --------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | [**Blended Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Sum of advertising costs across all connected ad platforms | | [**New Customers**](/reference/metrics/orders/customers/new-customers) | Count of unique first-time buyers in the period | | Metadata | | | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | | **Type** | Currency | | **Data Source** | [Meta Ads](/sources/facebook-ads), [Google Ads](/sources/google-ads), [TikTok Ads](/sources/tiktok), [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store acquired **312 new customers** in January with a total ad spend of **\$15,600**: | Metric | Value | | -------------- | ----------- | | Total Ad Spend | \$15,600 | | New Customers | 312 | | **CAC** | **\$50.00** | A \$50 CAC means you spend \$50 on average to acquire each new customer. *** ## How It Works CAC divides your total advertising spend by the number of unique new customers acquired during the period. Unlike CPA (Cost Per Acquisition), which measures cost per order, CAC focuses specifically on customer-level acquisition—counting each person once regardless of how many orders they place. *** ## When to Use | Scenario | Action | | --------------------------------- | ---------------------------------------------------------------------------- | | Evaluating acquisition efficiency | Compare CAC to customer lifetime value (LTV) | | Budget planning | Set target CAC based on first-order margins | | Channel comparison | Identify which platforms acquire customers most efficiently | | Profitability analysis | Ensure CAC stays below first-order profit to maintain healthy unit economics | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------ | ----------------------------------------------------------- | | [LTV](/reference/metrics/orders/ltv/ltv) | Customer lifetime value—compare to CAC for payback analysis | | [Blended CPA](/reference/metrics/advertising/blended/blended-efficiency/blended-cpa) | Cost per conversion (orders, not customers) | | [New Customers](/reference/metrics/orders/customers/new-customers) | Denominator for CAC calculation | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Numerator for CAC calculation | [See all Performance metrics →](/reference/metrics/orders/performance) # Cost Per Unit: Average Product Cost Per Item Sold Source: https://docs.upstackdata.com/reference/metrics/orders/performance/cost-per-unit Track the average cost of goods sold per unit. Learn the formula, see examples, and optimize product cost efficiency across your catalog. The average cost of goods sold per unit sold. ## Formula **Cost Per Unit** = **COGS** ÷ **Units Sold** ### Formula Components | Metric | Definition | | ------------------------------------------------------------- | ------------------------------------------------------------------ | | [**COGS**](/reference/metrics/orders/cogs/cogs) | Total cost of goods sold including manufacturing or purchase costs | | [**Units Sold**](/reference/metrics/orders/counts/units-sold) | Total quantity of individual product units sold | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your store sold **8,500 units** this month with a total COGS of **\$42,500**: | Metric | Value | | ----------------- | ---------- | | Total COGS | \$42,500 | | Units Sold | 8,500 | | **Cost Per Unit** | **\$5.00** | *** ## How It Works Cost Per Unit divides your total cost of goods sold by the number of units sold. This gives you the average cost to produce or acquire each unit in your catalog. Unlike COGS Per Order, this metric focuses on individual items rather than order baskets. *** ## When to Use | Scenario | Action | | -------------------------- | ------------------------------------------------- | | Evaluating product margins | Compare cost per unit against selling price | | Pricing decisions | Ensure prices cover unit costs plus target margin | | Supplier negotiations | Benchmark against industry standards | | Inventory optimization | Identify high-cost products to prioritize | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------- | ---------------------------------------------------- | | [COGS](/reference/metrics/orders/cogs/cogs) | Numerator—total cost divided to get per-unit average | | [Units Sold](/reference/metrics/orders/counts/units-sold) | Denominator—count of items sold | | [COGS Per Order](/reference/metrics/orders/cogs/cogs-per-order) | Similar metric but per order instead of per unit | | [Gross Profit](/reference/metrics/orders/contribution-margin/gross-profit) | Revenue impact after subtracting product costs | [See all Performance metrics →](/reference/metrics/orders/performance) # Performance Metrics Source: https://docs.upstackdata.com/reference/metrics/orders/performance/index Order performance and efficiency metrics. Cost per unit, operational efficiency, and performance ratios from Shopify order data. Performance metrics help you understand operational efficiency at the unit level. These metrics focus on per-item costs and ratios that reveal how efficiently you're selling products. ## Available Metrics Average cost of goods sold per unit. ## Key Insights | Metric | Use Case | | -------------------------------------------------------------------- | --------------------------------------------------- | | [Cost Per Unit](/reference/metrics/orders/performance/cost-per-unit) | Track per-item profitability and pricing efficiency | ## Data Source Performance metrics are calculated from [Shopify](/sources/shopify) order data, specifically using cost of goods sold and unit quantities from your order history. # MER: Marketing Efficiency Ratio Source: https://docs.upstackdata.com/reference/metrics/orders/performance/mer Track what percentage of revenue you spend on advertising. Calculate MER to monitor ad spend efficiency—lower MER means more revenue per dollar spent. MER (Marketing Efficiency Ratio) measures what percentage of your total revenue is spent on advertising—lower is better. ## Formula **Marketing Efficiency Ratio** = ( **Total Ad Spend** ÷ **Total Revenue** ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------- | | [**Total Ad Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Sum of advertising spend across all connected platforms | | [**Total Revenue**](/reference/metrics/orders/revenue/total-revenue) | Complete order revenue including shipping and taxes | | Metadata | | | --------------- | ------------------------------------------------------------------ | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify), [Ad Platforms](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your store generated **\$250,000** in order revenue while spending **\$50,000** on ads: | Total Revenue | Total Ad Spend | MER | | ------------- | -------------- | --- | | \$250,000 | \$50,000 | 20% | | \$250,000 | \$75,000 | 30% | | \$250,000 | \$30,000 | 12% | A 20% MER means you spent \$0.20 on ads for every \$1.00 of revenue. Lower MER indicates better efficiency—you're keeping more of each revenue dollar. *** ## How It Works MER divides your total advertising spend by your total order revenue, then multiplies by 100 to express it as a percentage. Unlike ROAS (which is Revenue ÷ Spend), MER shows the inverse—what fraction of your revenue goes to advertising. Lower MER values indicate better efficiency. *** ## When to Use | Scenario | Action | | -------------------------- | ----------------------------------------------------- | | Setting efficiency targets | Define maximum acceptable ad spend as % of revenue | | Comparing time periods | Track if marketing efficiency improves over time | | Budget planning | Determine how much revenue to reinvest in ads | | Profitability analysis | Combine with margin data to ensure ads are profitable | *** ## Related Metrics | Metric | Relationship | | ----------------------------------------------------------------------------------- | -------------------------------------------------- | | [ROAS](/reference/metrics/orders/performance/roas) | Inverse metric: Revenue ÷ Spend (higher is better) | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | The denominator in MER calculation | | [Blended Spend](/reference/metrics/advertising/blended/blended-spend/blended-spend) | The numerator in MER calculation | | [CAC](/reference/metrics/orders/performance/cac) | Cost per new customer acquired | [See all Performance metrics →](/reference/metrics/orders/performance) # New Customer Order Ratio: Measure Acquisition Mix Source: https://docs.upstackdata.com/reference/metrics/orders/performance/new-customer-order-ratio Track the ratio of new customer orders to total orders from Shopify. Monitor customer acquisition mix and balance growth vs. retention strategies. The ratio of orders from first-time buyers compared to all orders in a given period. ## Formula **New Customer Order Ratio** = **New Customer Orders** ÷ **Total Orders** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------- | --------------------------------------------------------------- | | [**New Customer Orders**](/reference/metrics/orders/counts/new-customer-orders) | Count of orders placed by customers making their first purchase | | [**Total Orders**](/reference/metrics/orders/counts/orders) | Count of all completed orders in the selected period | | Metadata | | | --------------- | --------------------------- | | **Type** | Ratio | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store processed **1,247 orders** in January with **623 from new customers**: | Metric | Value | Interpretation | | ------------------- | -------- | ------------------- | | New Customer Orders | 623 | First-time buyers | | Total Orders | 1,247 | All orders | | **NC Order Ratio** | **0.50** | 50% acquisition mix | A ratio of 0.50 means half your orders come from new customers—a balanced acquisition/retention split. *** ## How It Works Shopify identifies new customers by checking if the order is their first completed purchase in your store. The NC Order Ratio divides these first-time buyer orders by your total order count, giving you a decimal between 0 and 1 that represents your acquisition mix. *** ## When to Use | Scenario | Action | | -------------------------------- | --------------------------------------------------------- | | Balancing growth vs. retention | Target 0.3–0.5 ratio for healthy DTC businesses | | Evaluating acquisition campaigns | Rising ratio during campaigns confirms new customer reach | | Diagnosing declining revenue | Low ratio with flat sales suggests retention issues | | Seasonal planning | Compare ratios across holiday periods to set expectations | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------- | -------------------------------------------- | | [New Customer %](/reference/metrics/orders/customers/new-customer-percent) | This ratio expressed as a percentage (× 100) | | [Returning Customer %](/reference/metrics/orders/customers/returning-customer-percent) | The inverse (1 − NC Order Ratio) | | [New Customers](/reference/metrics/orders/customers/new-customers) | The numerator count | | [Total Orders](/reference/metrics/orders/counts/orders) | The denominator count | | [New Customer Revenue Ratio](/reference/metrics/orders/performance/new-customer-revenue-ratio) | Revenue version of this metric | [See all Performance metrics →](/reference/metrics/orders/performance) # New Customer Revenue Ratio: Revenue from First-Time Buyers Source: https://docs.upstackdata.com/reference/metrics/orders/performance/new-customer-revenue-ratio Measure the percentage of total revenue from new customers. Track acquisition revenue contribution and balance your customer mix for sustainable growth. The percentage of total revenue generated by new (first-time) customers. ## Formula **New Customer Revenue Ratio** = **New Customer Total Revenue** ÷ **Total Revenue** ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------- | ----------------------------------------------- | | [**New Customer Total Revenue**](/reference/metrics/orders/revenue/new-customer-total-revenue) | Revenue from orders placed by first-time buyers | | [**Total Revenue**](/reference/metrics/orders/revenue/total-revenue) | Combined revenue from all orders in the period | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store generated **38% of revenue from new customers** in Q1, with \$152,000 from first-time buyers out of \$400,000 total revenue. | Segment | Revenue | Share | | ------------------- | --------- | ----- | | New Customers | \$152,000 | 38% | | Returning Customers | \$248,000 | 62% | *** ## How It Works Divides new customer revenue by total revenue and multiplies by 100. Shopify classifies each order as new or returning at purchase time based on the customer's order history. *** ## When to Use | Scenario | Action | | -------------------------- | ----------------------------------------------------------- | | Evaluating acquisition ROI | Higher ratios justify continued acquisition spend | | Retention health check | Declining ratios may indicate strong repeat purchasing | | Channel comparison | Compare acquisition revenue share across marketing channels | | Seasonal analysis | Track how promotions affect new vs returning revenue mix | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------- | | [New Customer Total Revenue](/reference/metrics/orders/revenue/new-customer-total-revenue) | The numerator in this calculation | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | The denominator in this calculation | | [New Customer %](/reference/metrics/orders/customers/new-customer-percent) | Order count equivalent (this metric uses revenue) | | [Returning Customer Total Revenue](/reference/metrics/orders/revenue/returning-customer-total-revenue) | Complement showing returning customer revenue | | [New Customer Order Ratio](/reference/metrics/orders/performance/new-customer-order-ratio) | Order count version of this metric | [See all Performance metrics →](/reference/metrics/orders/performance) # New Customer ROAS: First-Order Return on Ad Spend Source: https://docs.upstackdata.com/reference/metrics/orders/performance/new-customer-roas Track new customer ROAS for your Shopify store. Measure revenue generated from first orders per dollar of ad spend. New Customer ROAS measures how much revenue you generate from first-time customer orders per dollar of ad spend. ## Formula **New Customer ROAS** = **New Customer Total Revenue** ÷ **Ad Spend** ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------- | ------------------------------------ | | [**New Customer Total Revenue**](/reference/metrics/orders/revenue/new-customer-total-revenue) | Revenue from first-time buyer orders | | [**Ad Spend**](/reference/metrics/ads/total-spend) | Total advertising spend | | Metadata | | | --------------- | --------------------------------------------------------------------------- | | **Type** | Ratio | | **Data Source** | [Shopify](/sources/shopify), [Advertising Platforms](/sources/facebook-ads) | | **Aggregation** | Ratio | *** ## Example Your Shopify store generates **\$50,000** from new customer orders and spends **\$15,000** on ads. | Component | Value | Calculation | | --------------------- | -------- | ------------------- | | New Customer Revenue | \$50,000 | First-order sales | | Ad Spend | \$15,000 | Marketing cost | | **New Customer ROAS** | **3.33** | \$50,000 ÷ \$15,000 | *** ## How It Works New Customer ROAS shows acquisition efficiency at the revenue level. A ROAS of 3.33 means you're generating \$3.33 of first-order revenue for every \$1 spent on ads. However, revenue doesn't equal profit—use CM ROAS for margin-adjusted efficiency. *** ## Benchmarks | Rating | Range | | ----------- | --------- | | Excellent | > 4.0 | | Good | 2.5 – 4.0 | | Moderate | 1.5 – 2.5 | | Challenging | \< 1.5 | Note: Required ROAS varies by margin structure. High-margin products need lower ROAS to be profitable. *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------ | -------------------------- | | [New Customer Total Revenue](/reference/metrics/orders/revenue/new-customer-total-revenue) | Numerator (revenue) | | [ROAS](/reference/metrics/orders/performance/total-roas) | Overall return on ad spend | | [Returning Customer ROAS](/reference/metrics/orders/performance/returning-customer-roas) | Repeat order ROAS | | [New Customer CM2 ROAS](/reference/metrics/orders/performance/new-customer-cm2-roas) | Margin-adjusted ROAS | [See all Performance metrics →](/reference/metrics/orders/performance) # Purchase Frequency: Average Orders per Customer Source: https://docs.upstackdata.com/reference/metrics/orders/performance/purchase-frequency Track how many times customers purchase from your store on average. Learn the formula, see examples, and optimize retention strategies. The average number of orders placed per unique customer in the selected period. ## Formula **Purchase Frequency** = **Total Orders** ÷ **Unique Customers** ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------- | ------------------------------------------------ | | [**Total Orders**](/reference/metrics/orders/counts/orders) | Number of orders placed in the period | | [**Unique Customers**](/reference/metrics/orders/customers/unique-customers) | Distinct customers who placed at least one order | | Metadata | | | --------------- | --------------------------- | | **Type** | Number | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store had **2,847 orders** from **1,890 unique customers** this month: | Metric | Value | | ---------------------- | -------- | | Total Orders | 2,847 | | Unique Customers | 1,890 | | **Purchase Frequency** | **1.51** | On average, each customer placed 1.51 orders during the month, indicating healthy repeat purchasing behavior. *** ## How It Works Purchase Frequency divides total orders by the count of unique customers who placed those orders. A frequency of 1.0 means every customer ordered exactly once. Higher values indicate stronger repeat purchase behavior and customer loyalty. *** ## When to Use | Scenario | Action | | ----------------------------- | ------------------------------------------------------------- | | Measuring customer loyalty | Higher frequency signals stronger retention and repeat buyers | | Evaluating retention programs | Track if loyalty initiatives increase repeat purchases | | Comparing customer segments | New vs. returning customers often show different frequencies | | Forecasting revenue | Combine with AOV to project customer lifetime value | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------ | ----------------------------------------------------------- | | [Average Order Value](/reference/metrics/orders/aov/total-aov) | Revenue per order; multiply by frequency for customer value | | [Total Orders](/reference/metrics/orders/counts/orders) | Numerator in the frequency calculation | | [Unique Customers](/reference/metrics/orders/customers/unique-customers) | Denominator in the frequency calculation | [See all Performance metrics →](/reference/metrics/orders/performance) # Repeat Rate: Measure Customer Retention Performance Source: https://docs.upstackdata.com/reference/metrics/orders/performance/repeat-rate Track what percentage of orders come from returning customers. Learn the formula, see examples, and use Repeat Rate to measure customer loyalty and retention. The percentage of total orders placed by returning customers. ## Formula **Repeat Rate** = **Returning Customer Orders** ÷ **Total Orders** × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | [**Returning Customer Orders**](/reference/metrics/orders/customers/returning-customers) | Orders placed by customers with at least one prior purchase | | [**Total Orders**](/reference/metrics/orders/counts/orders) | All orders placed in the selected period | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store processed **1,247 orders** in January with a **38% Repeat Rate**: | Customer Type | Orders | Share | | ------------------- | ------ | ----- | | New Customers | 773 | 62% | | Returning Customers | 474 | 38% | *** ## How It Works Repeat Rate measures customer loyalty by calculating what percentage of orders come from customers who have purchased before. Shopify identifies returning customers based on their email address matching a previous order. Higher repeat rates indicate stronger customer retention and brand loyalty. *** ## When to Use | Scenario | Action | | ----------------------------- | ----------------------------------------------------------- | | Measuring retention health | Track repeat rate trends to gauge customer loyalty | | Evaluating loyalty programs | Compare repeat rate before and after launching initiatives | | Assessing acquisition quality | Low repeat rates may indicate poor customer-product fit | | Forecasting revenue | Higher repeat rates enable more predictable revenue streams | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------ | ------------------------------------------------------- | | [Orders](/reference/metrics/orders/counts/orders) | The denominator in the Repeat Rate formula | | [Returning Customers](/reference/metrics/orders/customers/returning-customers) | The numerator in the Repeat Rate formula | | [New Customer %](/reference/metrics/orders/customers/new-customer-percent) | The inverse segment (100% − Repeat Rate) | | [Customer Lifetime Value](/reference/metrics/orders/ltv/ltv-365) | Higher repeat rates typically correlate with higher LTV | | [Average Order Value](/reference/metrics/orders/aov/total-aov) | Compare AOV between new and returning customers | [See all Performance metrics →](/reference/metrics/orders/performance) # ROAS: Return on Ad Spend from Shopify Orders Source: https://docs.upstackdata.com/reference/metrics/orders/performance/roas Track ROAS to measure how many dollars of order revenue you generate for every dollar spent on advertising. The core efficiency metric for e-commerce. ROAS (Return on Ad Spend) measures how many dollars of order revenue you generate for every dollar spent on advertising. ## Formula **Return on Ad Spend** = **Total Revenue** ÷ **Total Ad Spend** ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------- | | [**Total Revenue**](/reference/metrics/orders/revenue/total-revenue) | Complete order revenue including shipping and taxes | | [**Total Ad Spend**](/reference/metrics/advertising/blended/blended-spend/blended-spend) | Sum of advertising spend across all connected platforms | | Metadata | | | --------------- | --------------------------- | | **Type** | Multiplier (e.g., 3.5×) | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store spent **\$25,000** on advertising last month and generated **\$87,500** in order revenue: | Metric | Value | | -------------- | -------- | | Total Revenue | \$87,500 | | Total Ad Spend | \$25,000 | | **ROAS** | **3.5×** | A ROAS of 3.5× means you generated \$3.50 in revenue for every \$1 spent on ads. *** ## How It Works ROAS divides your total Shopify order revenue by your total advertising spend. A ROAS of 3× means every advertising dollar returns \$3 in revenue. This metric helps you evaluate whether your ad spend is profitable and compare efficiency across campaigns and time periods. *** ## When to Use | Scenario | Action | | ------------------------ | -------------------------------------------------------- | | Evaluating ad efficiency | Compare ROAS against your break-even threshold | | Setting budget targets | Use ROAS to determine sustainable spend levels | | Campaign comparisons | Identify which campaigns deliver the best return | | Profitability analysis | Combine with margin data to assess true ad profitability | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------- | ---------------------------------------------- | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | Numerator — total order revenue | | [CAC](/reference/metrics/orders/performance/cac) | Cost per new customer acquired | | [New Customer ROAS](/reference/metrics/orders/performance/new-customer-roas) | ROAS from first-time buyers only | | [MER](/reference/metrics/orders/performance/mer) | Inverse ratio — spend as percentage of revenue | [See all Performance metrics →](/reference/metrics/orders/performance) # Product Margin Metrics Source: https://docs.upstackdata.com/reference/metrics/orders/product-margin/index Measure product profitability using cost of goods data from Shopify. Track margin percentages to optimize pricing and product mix decisions. Product margin metrics help you understand the profitability of your products by comparing revenue to cost of goods sold. These metrics use product cost data from Shopify to calculate margins. ## Available Metrics | Metric | Description | | ----------------------------------------------------------------------------------- | -------------------------------------------------- | | [Product Margin %](/reference/metrics/orders/product-margin/product-margin-percent) | Percentage of revenue retained after product costs | ## Data Requirements Product margin calculations require cost of goods data in Shopify. Configure product costs through: * **Shopify inventory settings** — Set cost per item on product variants * **Shopify metafields** — Store custom cost data for advanced scenarios [Learn how to configure contribution margin →](/get-started/configure-contribution-margin) # New Customer Product Margin: Profitability from First-Time Buyers Source: https://docs.upstackdata.com/reference/metrics/orders/product-margin/new-customer-product-margin Track product margin from new customer orders. Measure gross revenue minus COGS for first-time buyers to evaluate acquisition profitability. The total product-level profit from new customer orders, calculated as gross revenue minus cost of goods sold (COGS). ## Formula **New Customer Product Margin** = [**New Customer Gross Revenue**](/reference/metrics/orders/revenue/new-customer-gross-revenue) − [**New Customer COGS**](/reference/metrics/orders/cogs/new-customer-cogs) ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | [**New Customer Gross Revenue**](/reference/metrics/orders/revenue/new-customer-gross-revenue) | Total revenue from first-time buyer orders before deductions | | [**New Customer COGS**](/reference/metrics/orders/cogs/new-customer-cogs) | Cost of goods sold for products purchased by new customers | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store acquired **847 new customers** in March with **\$42,350** in product margin: | Segment | Revenue | COGS | Product Margin | | ------------------- | --------- | --------- | -------------- | | New Customers | \$127,050 | \$84,700 | **\$42,350** | | Returning Customers | \$198,200 | \$118,920 | \$79,280 | New customer product margin is **\$42,350**, representing a 33% gross margin on acquisition revenue. *** ## How It Works New Customer Product Margin isolates profitability from first-time buyers by subtracting [New Customer COGS](/reference/metrics/orders/cogs/new-customer-cogs) from [New Customer Gross Revenue](/reference/metrics/orders/revenue/new-customer-gross-revenue). This excludes returning customer orders, showing only the product-level profit generated by customer acquisition. *** ## When to Use | Scenario | Action | | --------------------------------- | ------------------------------------------------------------ | | Evaluating acquisition ROI | Compare product margin against customer acquisition cost | | Setting CPA targets | Use as the ceiling for profitable acquisition spend | | Analyzing new vs returning mix | Compare profitability between customer segments | | Product selection for acquisition | Identify which products drive profitable new customer orders | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | [Product Margin](/reference/metrics/orders/product-margin/product-margin) | Total product margin across all customers | | [Returning Customer Product Margin](/reference/metrics/orders/product-margin/returning-customer-product-margin) | Same calculation for repeat buyers | | [New Customer Gross Revenue](/reference/metrics/orders/revenue/new-customer-gross-revenue) | Revenue component before subtracting COGS | | [New Customer COGS](/reference/metrics/orders/cogs/new-customer-cogs) | Cost component subtracted from revenue | [See all Product Margin metrics →](/reference/metrics/orders/product-margin) # New Customer Product Margin %: First-Time Buyer Gross Profit Rate Source: https://docs.upstackdata.com/reference/metrics/orders/product-margin/new-customer-product-margin-percent Track what percentage of new customer revenue remains as gross profit after product costs. Measure first-time buyer margin efficiency. The percentage of first-time buyer revenue remaining as gross profit after subtracting product costs. ## Formula **New Customer Product Margin %** = ( [**New Customer Gross Revenue**](/reference/metrics/orders/revenue/new-customer-gross-revenue) − [**New Customer COGS**](/reference/metrics/orders/cogs/new-customer-cogs) ) ÷ [**New Customer Gross Revenue**](/reference/metrics/orders/revenue/new-customer-gross-revenue) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | [**New Customer Gross Revenue**](/reference/metrics/orders/revenue/new-customer-gross-revenue) | Total product revenue from first-time buyers before discounts and refunds | | [**New Customer COGS**](/reference/metrics/orders/cogs/new-customer-cogs) | Cost of goods sold for first-time buyer orders | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example A supplement brand analyzes first-time buyer margins across quarters: | Quarter | NC Gross Revenue | NC COGS | NC Product Margin % | | ------- | ---------------- | -------- | ------------------- | | Q1 | \$42,000 | \$14,700 | **65.0%** | | Q2 | \$56,500 | \$18,645 | **67.0%** | | Q3 | \$61,200 | \$19,584 | **68.0%** | Q3's higher margin (68%) indicates improved product mix or cost efficiency for new customers. *** ## How It Works This metric calculates the percentage of gross revenue retained after product costs for new customer orders only. It divides the difference between [New Customer Gross Revenue](/reference/metrics/orders/revenue/new-customer-gross-revenue) and [New Customer COGS](/reference/metrics/orders/cogs/new-customer-cogs) by gross revenue, then multiplies by 100. Higher percentages mean more margin retained per dollar of new customer revenue. *** ## When to Use | Scenario | Action | | ----------------------------- | --------------------------------------------------------------------- | | Evaluating acquisition offers | Check if new customer promotions erode product margins | | Comparing customer segments | Compare to returning customer margin to identify differences | | Product mix analysis | Identify if first-time buyers gravitate toward higher-margin products | | Setting pricing strategy | Ensure prices support target margins for customer acquisition | *** ## Related Metrics | Metric | Relationship | | --------------------------------------------------------------------------------------------------- | --------------------------------------- | | [New Customer COGS](/reference/metrics/orders/cogs/new-customer-cogs) | Product costs subtracted from revenue | | [New Customer Gross Revenue](/reference/metrics/orders/revenue/new-customer-gross-revenue) | The revenue base for this calculation | | [New Customer COGS Gross Rate](/reference/metrics/orders/cogs/new-customer-cogs-gross-rate) | The inverse—shows costs as % of revenue | | [New Customer Product Margin](/reference/metrics/orders/product-margin/new-customer-product-margin) | Dollar amount instead of percentage | [See all Product Margin metrics →](/reference/metrics/orders/product-margin) # Product Margin: Revenue Minus Cost of Goods Sold Source: https://docs.upstackdata.com/reference/metrics/orders/product-margin/product-margin Track product-level profitability by subtracting cost of goods from revenue. Learn the formula, see examples, and optimize your product mix for profit. The profit remaining after subtracting cost of goods sold (COGS) from gross revenue. ## Formula **Product Margin** = [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) − [**COGS**](/reference/metrics/orders/cogs/cogs) ### Formula Components | Metric | Definition | | -------------------------------------------------------------------- | -------------------------------------------------------------------- | | [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) | Total revenue from order line items before discounts and adjustments | | [**COGS**](/reference/metrics/orders/cogs/cogs) | Cost of goods sold based on product costs in Shopify | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store generated **\$85,000** in gross revenue with **\$42,500** in COGS: | Period | Gross Revenue | COGS | Product Margin | | -------- | ------------- | -------- | -------------- | | January | \$85,000 | \$42,500 | \$42,500 | | February | \$92,000 | \$44,160 | \$47,840 | | March | \$78,000 | \$39,780 | \$38,220 | Product Margin shows how much profit remains from each sale before fulfillment, transaction costs, and marketing expenses are deducted. *** ## How It Works Product Margin calculates the difference between what you charge customers and what you paid for the products. COGS is pulled from product cost data in Shopify. This metric represents your first layer of profitability before operational costs. *** ## When to Use | Scenario | Action | | -------------------------------- | -------------------------------------------------------------------- | | Evaluating product profitability | Compare margin across product lines or SKUs | | Pricing decisions | Ensure prices cover costs and target margin | | Supplier negotiations | Identify products where COGS reduction would have the biggest impact | | Product mix optimization | Shift marketing toward higher-margin products | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------- | --------------------------------------------------- | | [Gross Revenue](/reference/metrics/orders/revenue/gross-revenue) | Revenue component in the Product Margin calculation | | [COGS](/reference/metrics/orders/cogs/cogs) | Cost component subtracted from revenue | | [Contribution Margin](/reference/metrics/orders/contribution-margin/contribution-margin) | Product Margin minus additional variable costs | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Revenue after discounts and refunds | [See all Product Margin metrics →](/reference/metrics/orders/product-margin) # Product Margin Per Order: Average Profit Per Transaction Source: https://docs.upstackdata.com/reference/metrics/orders/product-margin/product-margin-per-order Track average product margin per order to measure per-transaction profitability. Learn the formula, see examples, and optimize your product mix. The average profit from products per order, calculated before fulfillment and transaction costs. ## Formula **Product Margin Per Order** = [**Product Margin**](/reference/metrics/orders/product-margin/product-margin) ÷ [**Orders**](/reference/metrics/orders/counts/orders) ### Formula Components | Metric | Definition | | ----------------------------------------------------------------------------- | ---------------------------------------------- | | [**Product Margin**](/reference/metrics/orders/product-margin/product-margin) | Gross revenue minus cost of goods sold | | [**Orders**](/reference/metrics/orders/counts/orders) | Total number of completed orders in the period | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your store processed **1,247 orders** in January with a total Product Margin of **\$31,175**: | Metric | Value | Calculation | | ---------------------------- | ----------- | -------------------- | | Gross Product Revenue | \$87,290 | Sum of product sales | | Product COGS | \$56,115 | Sum of product costs | | Product Margin | \$31,175 | \$87,290 − \$56,115 | | **Product Margin Per Order** | **\$25.00** | \$31,175 ÷ 1,247 | *** ## How It Works Product Margin Per Order divides total [Product Margin](/reference/metrics/orders/product-margin/product-margin) by [Order Count](/reference/metrics/orders/counts/orders). Product Margin is the difference between [Gross Revenue](/reference/metrics/orders/revenue/gross-revenue) and [COGS](/reference/metrics/orders/cogs/cogs). This metric isolates product profitability before fulfillment costs, transaction fees, and other variable expenses are applied. *** ## When to Use | Scenario | Action | | ------------------------------------ | --------------------------------------------------- | | Evaluating product mix profitability | Compare margin per order across product categories | | Setting free shipping thresholds | Ensure threshold covers product margin | | Analyzing bundle performance | Check if bundles improve per-order margin | | Identifying margin erosion | Track trends to catch declining profitability early | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------- | ------------------------------------------- | | [Product Margin](/reference/metrics/orders/product-margin/product-margin) | Numerator: total margin across all orders | | [Orders](/reference/metrics/orders/counts/orders) | Denominator: order count for averaging | | [COGS Per Order](/reference/metrics/orders/cogs/cogs-per-order) | The cost component per transaction | | [Gross Revenue](/reference/metrics/orders/revenue/gross-revenue) | Revenue component of the margin calculation | [See all Product Margin metrics →](/reference/metrics/orders/product-margin) # Product Margin %: Profitability as Percentage of Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/product-margin/product-margin-percent Track the percentage of revenue retained after product costs. Learn the formula, see examples, and optimize product profitability across your Shopify store. The percentage of revenue remaining after subtracting the cost of goods sold. ## Formula **Product Margin %** = ( [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) − [**COGS**](/reference/metrics/orders/cogs/cogs) ) ÷ [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) × 100 ### Formula Components | Metric | Definition | | -------------------------------------------------------------------- | ----------------------------------------------------------------- | | [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) | Total revenue from product sales before discounts and adjustments | | [**COGS**](/reference/metrics/orders/cogs/cogs) | Cost of goods sold from Shopify product inventory data | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Weighted Average | *** ## Example Your store generated **\$50,000** in revenue with **\$30,000** in product costs, resulting in a **40%** product margin: | Category | Revenue | COGS | Margin % | | ----------- | ------------ | ------------ | -------- | | Apparel | \$25,000 | \$12,500 | 50% | | Accessories | \$15,000 | \$10,500 | 30% | | Home Goods | \$10,000 | \$7,000 | 30% | | **Total** | **\$50,000** | **\$30,000** | **40%** | *** ## How It Works Product Margin % calculates the percentage of each revenue dollar that remains after covering product costs. Shopify provides product cost data through inventory settings or metafields. This metric aggregates across all line items in orders, weighted by revenue contribution. *** ## When to Use | Scenario | Action | | -------------------------------- | --------------------------------------------- | | Evaluating product profitability | Identify high-margin products to promote | | Pricing decisions | Adjust prices on low-margin items | | Supplier negotiations | Flag products with eroding margins | | Ad spend allocation | Focus budget on products with healthy margins | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------- | --------------------------------------- | | [Gross Revenue](/reference/metrics/orders/revenue/gross-revenue) | Revenue before deductions (denominator) | | [COGS](/reference/metrics/orders/cogs/cogs) | Product costs subtracted from revenue | | [Product Margin](/reference/metrics/orders/product-margin/product-margin) | Dollar amount instead of percentage | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Revenue after discounts and refunds | [See all Product Margin metrics →](/reference/metrics/orders/product-margin) # Returning Customer Product Margin: Repeat Buyer Profitability Source: https://docs.upstackdata.com/reference/metrics/orders/product-margin/returning-customer-product-margin Track product-level profitability from returning customers. Calculate margin after COGS to measure repeat buyer value and retention economics. The total product margin generated by returning customer orders, calculated as gross revenue minus cost of goods sold. ## Formula **Returning Customer Product Margin** = [**Returning Customer Gross Revenue**](/reference/metrics/orders/revenue/returning-customer-gross-revenue) − [**Returning Customer COGS**](/reference/metrics/orders/cogs/returning-customer-cogs) ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | [**Returning Customer Gross Revenue**](/reference/metrics/orders/revenue/returning-customer-gross-revenue) | Gross revenue from repeat buyers before discounts and refunds | | [**Returning Customer COGS**](/reference/metrics/orders/cogs/returning-customer-cogs) | Cost of goods sold for returning customer orders | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your returning customers generated **\$28,400** in product margin last month: | Segment | Gross Revenue | COGS | Product Margin | | ------------------- | ------------- | -------- | -------------- | | Returning Customers | \$85,200 | \$56,800 | **\$28,400** | | New Customers | \$42,100 | \$29,470 | \$12,630 | *** ## How It Works Returning Customer Product Margin captures the gross profit from repeat buyers at the product level. It subtracts [Returning Customer COGS](/reference/metrics/orders/cogs/returning-customer-cogs) from [Returning Customer Gross Revenue](/reference/metrics/orders/revenue/returning-customer-gross-revenue), showing how much you keep after product costs. This metric excludes fulfillment, transaction fees, and marketing costs. *** ## When to Use | Scenario | Action | | ----------------------------- | -------------------------------------------------------------------------- | | Measuring retention value | Compare RC margin to NC margin to see if repeat buyers are more profitable | | Evaluating loyalty economics | High RC margin indicates sustainable retention without heavy discounting | | Setting retention goals | Use as a target for retention campaigns and loyalty programs | | Analyzing customer mix impact | Track how shifts in NC/RC ratio affect overall profitability | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | ----------------------------------------- | | [New Customer Product Margin](/reference/metrics/orders/product-margin/new-customer-product-margin) | Same calculation for first-time buyers | | [Product Margin](/reference/metrics/orders/product-margin/product-margin) | Total product margin across all customers | | [Returning Customer Gross Revenue](/reference/metrics/orders/revenue/returning-customer-gross-revenue) | Revenue component of this calculation | | [Returning Customer COGS](/reference/metrics/orders/cogs/returning-customer-cogs) | Cost component subtracted from revenue | [See all Product Margin metrics →](/reference/metrics/orders/product-margin) # Gross Revenue: Product Sales Before Adjustments Source: https://docs.upstackdata.com/reference/metrics/orders/revenue/gross-revenue Track gross revenue from product sales before discounts and refunds. Use for margin calculations and understanding baseline product revenue. Revenue from product sales before subtracting discounts or refunds. ## Formula **Gross Revenue** = **SUM** ( Product Line Item Prices ) ### Formula Components | Metric | Definition | | ---------------------------- | ---------------------------------------------------------------- | | **Product Line Item Prices** | Original price of each product at time of sale, before discounts | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store generated **\$125,000** in gross revenue in March: | Product Category | Gross Revenue | Share | | ---------------- | ------------- | ----- | | Apparel | \$62,500 | 50% | | Accessories | \$37,500 | 30% | | Footwear | \$25,000 | 20% | After applying discounts (\$8,750) and processing refunds (\$3,125), your Net Revenue was \$113,125. *** ## How It Works Gross Revenue sums the `grossSalePrice` field from each order—the total of all product line item prices at time of sale. This excludes shipping, taxes, discounts, and refunds, representing your theoretical maximum revenue if every order paid full price and no products were returned. *** ## When to Use | Scenario | Action | | ---------------------------- | ----------------------------------------------------- | | Calculating gross margin | Compare against COGS to find product profitability | | Measuring discount impact | Compare Gross vs Net Revenue to quantify promotions | | Tracking refund rates | Divide refunds by Gross Revenue for return percentage | | Forecasting baseline revenue | Use as the starting point for financial projections | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------- | ----------------------------------- | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | Includes shipping and taxes | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Gross Revenue − Discounts − Refunds | | [Average Order Value](/reference/metrics/orders/averages/aov) | Revenue per order | | [Orders](/reference/metrics/orders/counts/orders) | Count of completed orders | [See all Revenue metrics →](/reference/metrics/orders/revenue) # Revenue Metrics: Track Total, Gross, and Net Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/revenue/index Track revenue metrics in Upstack. Includes Total Revenue, Gross Revenue, Net Revenue by customer type with formulas and examples. Revenue metrics track the monetary value of orders at different calculation levels. Use these to analyze top-line performance across customer segments. **Data Source:** [Shopify](/sources/shopify)\ **Metrics:** 10 ## Metrics in This Group | Metric | Description | When to Use | | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------- | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | Sum of all order revenue | High-level sales reporting | | [Gross Revenue](/reference/metrics/orders/revenue/gross-revenue) | Revenue before discounts and refunds | Measure full price demand | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Revenue after discounts and refunds | Actual cash collected | | [New Customer Total Revenue](/reference/metrics/orders/revenue/new-customer-total-revenue) | Total revenue from new customers | Track acquisition revenue | | [New Customer Gross Revenue](/reference/metrics/orders/revenue/new-customer-gross-revenue) | Gross revenue from new customers | New customer full-price demand | | [New Customer Net Revenue](/reference/metrics/orders/revenue/new-customer-net-revenue) | Net revenue from new customers | Actual new customer collections | | [Returning Customer Total Revenue](/reference/metrics/orders/revenue/returning-customer-total-revenue) | Total revenue from returning customers | Track retention revenue | | [Returning Customer Gross Revenue](/reference/metrics/orders/revenue/returning-customer-gross-revenue) | Gross revenue from returning customers | Returning customer demand | | [Returning Customer Net Revenue](/reference/metrics/orders/revenue/returning-customer-net-revenue) | Net revenue from returning customers | Returning customer collections | | [Subscription Initial Purchase Revenue](/reference/metrics/orders/revenue/subscription-initial-purchase-revenue) | Revenue from first-time subscription orders | Value subscription acquisitions | ## How These Metrics Relate Revenue metrics follow a hierarchy: * **Gross Revenue** = Product price × Quantity (before any adjustments) * **Net Revenue** = Gross Revenue - Discounts - Refunds * **Total Revenue** = Net Revenue + Shipping + Tax (what customer paid) Each level is available segmented by New Customer and Returning Customer. ## Choosing the Right Metric * **Sales reporting**: Use Total Revenue for headline numbers * **Demand analysis**: Use Gross Revenue to see full-price demand * **Cash flow**: Use Net Revenue for actual money collected * **Customer segmentation**: Compare New vs Returning to understand revenue mix * **Subscription value**: Use Subscription Initial Purchase Revenue to value subscriptions # Net Revenue: Revenue After Discounts and Refunds Source: https://docs.upstackdata.com/reference/metrics/orders/revenue/net-revenue Track net revenue from Shopify orders after discounts and refunds. The primary metric for profitability analysis with formula and examples. Revenue after subtracting discounts and refunds from gross revenue—the primary metric for profitability analysis. ## Formula **Net Revenue** = **Gross Revenue** − **Discounts** − **Refunds** ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------- | -------------------------------------------- | | [**Gross Revenue**](/reference/metrics/orders/revenue/gross-revenue) | Product revenue before discounts and refunds | | [**Discounts**](/reference/metrics/orders/adjustments/discount-amount) | Total discount amount applied to orders | | [**Refunds**](/reference/metrics/orders/adjustments/refund-amount) | Total refund amount issued | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store generated **\$156,400** in net revenue this quarter: | Component | Amount | Impact | | --------------- | ------------- | ------------------ | | Gross Revenue | \$178,200 | Starting point | | Discounts | −\$15,400 | 8.6% discount rate | | Refunds | −\$6,400 | 3.6% refund rate | | **Net Revenue** | **\$156,400** | Final revenue | *** ## How It Works Net Revenue starts with Gross Revenue (product sales before adjustments), then subtracts all discount codes and promotional offers applied at checkout, and all refunds issued post-purchase. This gives you the actual revenue retained from customer transactions. *** ## When to Use | Scenario | Action | | -------------------------- | -------------------------------------------------------- | | Profitability analysis | Use Net Revenue as your baseline for margin calculations | | Discount impact assessment | Compare to Gross Revenue to measure promotion costs | | Refund rate monitoring | Track refund amount as a percentage of gross | | Financial reporting | Report Net Revenue as actual earned revenue | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------- | ------------------------------------------------------------- | | [Gross Revenue](/reference/metrics/orders/revenue/gross-revenue) | Revenue before deductions (Net = Gross − Discounts − Refunds) | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | Includes shipping and taxes | | [Net AOV](/reference/metrics/orders/aov/net-aov) | Net Revenue ÷ Order Count | | [Orders](/reference/metrics/orders/counts/orders) | Count of orders generating this revenue | [See all Revenue metrics →](/reference/metrics/orders/revenue) # New Customer Gross Revenue: First-Purchase Product Sales Source: https://docs.upstackdata.com/reference/metrics/orders/revenue/new-customer-gross-revenue Track gross revenue from first-time buyers before discounts and refunds. Measure acquisition value, compare to returning customers, and calculate new customer gross margin. Gross product revenue from new customers before discounts and refunds. ## Formula **New Customer Gross Revenue** = **SUM** ( Product Revenue ) **WHERE** customer\_type = new\_customer ### Formula Components | Metric | Definition | | ---------------------------------- | ------------------------------------------------------------------------------ | | **Product Revenue** | Sum of product line item totals before discounts, refunds, shipping, and taxes | | **customer\_type = new\_customer** | Filter for customers placing their first order | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store generated **\$47,200** in new customer gross revenue this month: | Week | New Customer Gross Revenue | Orders | | ------ | -------------------------- | ------ | | Week 1 | \$12,450 | 89 | | Week 2 | \$11,800 | 84 | | Week 3 | \$10,950 | 78 | | Week 4 | \$12,000 | 86 | *** ## How It Works New Customer Gross Revenue sums the product line item totals from first-time buyer orders. It excludes shipping, taxes, discounts, and refunds—giving you the raw product sales value before any deductions. A customer is classified as "new" if this is their first order in your Shopify store. *** ## When to Use | Scenario | Action | | ------------------------------- | -------------------------------------------------- | | Measuring acquisition value | Compare new customer gross revenue to ad spend | | Calculating new customer margin | Subtract COGS from gross revenue for profitability | | Comparing customer segments | Compare to returning customer gross revenue | | Evaluating product mix | Identify which products drive first purchases | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | --------------------------- | | [New Customer Net Revenue](/reference/metrics/orders/revenue/new-customer-net-revenue) | After discounts and refunds | | [New Customer Total Revenue](/reference/metrics/orders/revenue/new-customer-total-revenue) | Includes shipping and taxes | | [Gross Revenue](/reference/metrics/orders/revenue/gross-revenue) | All customers combined | | [Returning Customer Gross Revenue](/reference/metrics/orders/revenue/returning-customer-gross-revenue) | Repeat buyer comparison | [See all Orders Revenue metrics →](/reference/metrics/orders/revenue) # New Customer Net Revenue: First-Order Revenue After Deductions Source: https://docs.upstackdata.com/reference/metrics/orders/revenue/new-customer-net-revenue Track net revenue from first-time buyers after discounts and refunds. The clearest measure of first-order monetization for acquisition profitability analysis. Net revenue from new customers after discounts and refunds—the clearest measure of first-order monetization. ## Formula **New Customer Net Revenue** = [**New Customer Gross Revenue**](/reference/metrics/orders/revenue/new-customer-gross-revenue) − **New Customer Discounts** − **New Customer Refunds** ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | [**New Customer Gross Revenue**](/reference/metrics/orders/revenue/new-customer-gross-revenue) | Product revenue from new customers before deductions | | [**New Customer Discounts**](/reference/metrics/orders/adjustments/new-customer-discounts) | Discount amount applied to new customer orders | | [**New Customer Refunds**](/reference/metrics/orders/adjustments/new-customer-refunds) | Refund amount issued on new customer orders | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store generated **\$38,640** in new customer net revenue this month: | Component | Amount | Impact | | ------------------ | ------------ | ------------------- | | NC Gross Revenue | \$47,200 | Starting point | | NC Discounts | −\$6,120 | 13.0% discount rate | | NC Refunds | −\$2,440 | 5.2% refund rate | | **NC Net Revenue** | **\$38,640** | Actual retained | *** ## How It Works New Customer Net Revenue starts with gross product sales from first-time buyers, then subtracts discounts applied at checkout and any refunds issued post-purchase. This gives you the actual revenue retained from acquisition efforts—critical for calculating true customer acquisition cost payback. *** ## When to Use | Scenario | Action | | ---------------------------- | ----------------------------------------------------- | | Acquisition profitability | Compare NC Net Revenue to ad spend for true ROI | | Discount strategy evaluation | Monitor if acquisition discounts are sustainable | | Refund impact analysis | Track refund rates on first-time orders | | LTV baseline | Use as the true first-order value for LTV projections | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------- | ---------------------------- | | [New Customer Gross Revenue](/reference/metrics/orders/revenue/new-customer-gross-revenue) | Before discounts and refunds | | [New Customer Total Revenue](/reference/metrics/orders/revenue/new-customer-total-revenue) | Includes shipping and taxes | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | All customers combined | | [Returning Customer Net Revenue](/reference/metrics/orders/revenue/returning-customer-net-revenue) | Repeat buyer comparison | [See all Revenue metrics →](/reference/metrics/orders/revenue) # New Customer Total Revenue: First-Time Buyer Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/revenue/new-customer-total-revenue Track total revenue from first-time buyers including shipping and taxes. Measure acquisition value and compare against returning customer revenue. Total revenue collected from first-time buyers including shipping and taxes. ## Formula **New Customer Total Revenue** = **SUM** ( Order Total ) **WHERE** customer\_type = new\_customer ### Formula Components | Metric | Definition | | ---------------------------------- | -------------------------------------------------------------------- | | **Order Total** | Complete order value including product subtotal, shipping, and taxes | | **customer\_type = new\_customer** | Filter for customers placing their first order | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store generated **\$127,450** from new customers in April: | Week | NC Revenue | Orders | Avg Order | | ------ | ---------- | ------ | --------- | | Week 1 | \$28,340 | 312 | \$90.83 | | Week 2 | \$35,120 | 389 | \$90.28 | | Week 3 | \$31,890 | 347 | \$91.90 | | Week 4 | \$32,100 | 356 | \$90.17 | *** ## How It Works New Customer Total Revenue sums the complete order value—product subtotal, shipping, and taxes—for every customer placing their first order. Shopify determines new vs returning status based on email address match against prior orders. *** ## When to Use | Scenario | Action | | -------------------------------- | -------------------------------------------------------------- | | Measure acquisition ROI | Compare against ad spend to calculate new customer ROAS | | Track revenue mix | Monitor the split between new and returning customer revenue | | Evaluate acquisition campaigns | Assess whether promotions attract high-value first-time buyers | | Forecast customer lifetime value | Use as the first-order revenue baseline for LTV projections | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | ---------------------------------------- | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | All customers combined (NC + RC) | | [Returning Customer Total Revenue](/reference/metrics/orders/revenue/returning-customer-total-revenue) | The retention counterpart to this metric | | [New Customer Net Revenue](/reference/metrics/orders/revenue/new-customer-net-revenue) | Same segment, excludes shipping/taxes | | [New Customer Total AOV](/reference/metrics/orders/aov/new-customer-total-aov) | This metric ÷ New Customer Orders | [See all Revenue metrics →](/reference/metrics/orders/revenue) # Returning Customer Gross Revenue: Repeat Buyer Product Sales Source: https://docs.upstackdata.com/reference/metrics/orders/revenue/returning-customer-gross-revenue Track gross revenue from returning customers before discounts and refunds. Compare against new customer gross revenue to measure retention product value. Gross product revenue from returning customers before discounts and refunds. ## Formula **Returning Customer Gross Revenue** = **SUM** ( Product Revenue ) **WHERE** customer\_type = returning\_customer ### Formula Components | Metric | Definition | | ---------------------------------------- | ------------------------------------------------------------------------------ | | **Product Revenue** | Sum of product line item totals before discounts, refunds, shipping, and taxes | | **customer\_type = returning\_customer** | Filter for customers who have placed at least one prior order | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store generated **\$87,500** in returning customer gross revenue in March: | Category | RC Gross Revenue | Share | | ----------- | ---------------- | ----- | | Apparel | \$43,750 | 50% | | Accessories | \$26,250 | 30% | | Footwear | \$17,500 | 20% | After applying loyalty discounts (\$6,125) and refunds (\$1,750), your RC Net Revenue was \$79,625. *** ## How It Works Returning Customer Gross Revenue sums the product line item totals from customers who have placed at least one prior order. Shopify identifies returning customers by matching the customer email against previous orders. This metric excludes shipping, taxes, discounts, and refunds—representing your theoretical repeat-buyer revenue before any deductions. *** ## When to Use | Scenario | Action | | ---------------------------------------- | ------------------------------------------------------ | | Calculate returning customer margin | Compare against RC COGS for repeat-buyer profitability | | Measure discount impact on repeat buyers | Compare RC Gross vs RC Net Revenue | | Track retention product value | Monitor how much returning customers spend on products | | Segment revenue analysis | Compare against New Customer Gross Revenue | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | ------------------------------------------ | | [Gross Revenue](/reference/metrics/orders/revenue/gross-revenue) | All customers combined (NC + RC) | | [New Customer Gross Revenue](/reference/metrics/orders/revenue/new-customer-gross-revenue) | The acquisition counterpart to this metric | | [Returning Customer Net Revenue](/reference/metrics/orders/revenue/returning-customer-net-revenue) | Same segment, minus discounts and refunds | | [Returning Customer Total Revenue](/reference/metrics/orders/revenue/returning-customer-total-revenue) | Includes shipping and taxes | [See all Revenue metrics →](/reference/metrics/orders/revenue) # Returning Customer Net Revenue: Repeat Buyer Collections Source: https://docs.upstackdata.com/reference/metrics/orders/revenue/returning-customer-net-revenue Track net revenue from returning customers after discounts and refunds. Key input for repeat-purchase profitability and retention analysis. Net revenue from returning customers after discounts and refunds—key input for repeat-purchase profitability. ## Formula **Returning Customer Net Revenue** = **RC Gross Revenue** − **RC Discounts** − **RC Refunds** ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | | [**RC Gross Revenue**](/reference/metrics/orders/revenue/returning-customer-gross-revenue) | Product revenue from returning customers before discounts and refunds | | [**RC Discounts**](/reference/metrics/orders/adjustments/returning-customer-discounts) | Total discount amount applied to returning customer orders | | [**RC Refunds**](/reference/metrics/orders/adjustments/returning-customer-refunds) | Total refund amount issued on returning customer orders | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your returning customers generated **\$89,640** in net revenue this month: | Component | Amount | Impact | | ------------------ | ------------ | ------------------ | | RC Gross Revenue | \$102,800 | Starting point | | RC Discounts | −\$9,240 | 9.0% discount rate | | RC Refunds | −\$3,920 | 3.8% refund rate | | **RC Net Revenue** | **\$89,640** | Final collections | *** ## How It Works Returning Customer Net Revenue starts with gross product revenue from customers who have placed at least one prior order, then subtracts all discounts and refunds for those orders. Shopify identifies returning customers by email address match against previous orders. *** ## When to Use | Scenario | Action | | ------------------------- | ---------------------------------------------------------------------- | | Retention profitability | Use as the revenue baseline for returning customer margin calculations | | Compare customer segments | Measure whether returning customers use more discounts than new | | Track refund patterns | Monitor if repeat buyers have different refund rates | | LTV analysis | Factor into customer lifetime value calculations | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | -------------------------------------------- | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | All customers combined (NC + RC Net Revenue) | | [New Customer Net Revenue](/reference/metrics/orders/revenue/new-customer-net-revenue) | The acquisition counterpart to this metric | | [Returning Customer Total Revenue](/reference/metrics/orders/revenue/returning-customer-total-revenue) | Same segment, includes shipping and taxes | | [Returning Customer Gross Revenue](/reference/metrics/orders/revenue/returning-customer-gross-revenue) | Same segment, before discounts and refunds | [See all Revenue metrics →](/reference/metrics/orders/revenue) # Returning Customer Total Revenue: Repeat Buyer Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/revenue/returning-customer-total-revenue Track total revenue from returning customers including shipping and taxes. Measure retention value and compare against new customer revenue. Total revenue from repeat buyers including shipping and taxes. ## Formula **Returning Customer Total Revenue** = **SUM** ( Order Total ) **WHERE** customer\_type = returning\_customer ### Formula Components | Metric | Definition | | ---------------------------------------- | -------------------------------------------------------------------- | | **Order Total** | Complete order value including product subtotal, shipping, and taxes | | **customer\_type = returning\_customer** | Filter for customers who have placed at least one prior order | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store generated **\$215,780** from returning customers in April: | Week | RC Revenue | Orders | Avg Order | | ------ | ---------- | ------ | --------- | | Week 1 | \$48,920 | 412 | \$118.74 | | Week 2 | \$56,340 | 478 | \$117.87 | | Week 3 | \$52,180 | 439 | \$118.86 | | Week 4 | \$58,340 | 491 | \$118.82 | *** ## How It Works Returning Customer Total Revenue sums the complete order value—product subtotal, shipping, and taxes—for every customer who has placed at least one prior order. Shopify determines returning status based on email address match against previous orders. *** ## When to Use | Scenario | Action | | --------------------------------- | ------------------------------------------------------------ | | Measure retention value | Quantify revenue from your existing customer base | | Track revenue mix | Monitor the split between new and returning customer revenue | | Evaluate loyalty programs | Assess whether retention efforts drive repeat purchases | | Calculate customer lifetime value | Use as the repeat-order revenue component for LTV | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------ | ------------------------------------------ | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | All customers combined (NC + RC) | | [New Customer Total Revenue](/reference/metrics/orders/revenue/new-customer-total-revenue) | The acquisition counterpart to this metric | | [Returning Customer Net Revenue](/reference/metrics/orders/revenue/returning-customer-net-revenue) | Same segment, excludes shipping/taxes | | [Returning Customer Gross Revenue](/reference/metrics/orders/revenue/returning-customer-gross-revenue) | Same segment, before discounts and refunds | [See all Revenue metrics →](/reference/metrics/orders/revenue) # Subscription Initial Purchase Revenue: First-Time Subscription Value Source: https://docs.upstackdata.com/reference/metrics/orders/revenue/subscription-initial-purchase-revenue Track revenue from first-time subscription orders in Shopify. Measure subscription program value, compare acquisition revenue, and optimize recurring revenue growth. Total revenue from orders where a customer starts a new subscription for the first time. ## Formula **Subscription Initial Purchase Revenue** = **SUM** ( Order Revenue ) **WHERE** order\_type = subscription\_initial\_purchase ### Formula Components | Metric | Definition | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | **Order Revenue** | Total revenue value of each order | | **order\_type = subscription\_initial\_purchase** | Filter for orders that initiate a new subscription (excludes recurring renewals and one-time purchases) | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store generated **\$18,630** in subscription initial purchase revenue in Q1: | Month | Revenue | New Subscribers | Avg Initial Order | | -------- | ------- | --------------- | ----------------- | | January | \$5,390 | 98 | \$55.00 | | February | \$6,205 | 107 | \$58.00 | | March | \$7,035 | 119 | \$59.12 | *** ## How It Works This metric sums revenue from a customer's first subscription order. It excludes subsequent recurring charges and one-time purchases. Subscription initial purchases are identified by matching a `subscription_initial_purchase` event with the same order ID. *** ## When to Use | Scenario | Action | | ------------------------------- | ---------------------------------------------------------- | | Value subscription acquisitions | Measure revenue from new subscriber signups | | Calculate subscription CAC | Compare against marketing spend for subscriber acquisition | | Analyze subscription pricing | Track average first-order value for new subscribers | | Forecast recurring revenue | Project LTV from initial subscription value | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | [Subscription Initial Purchase Orders](/reference/metrics/orders/counts/subscription-initial-purchase-orders) | Count of initial subscriptions (this metric sums their value) | | [Total Revenue](/reference/metrics/orders/revenue/total-revenue) | All order revenue including subscriptions | | [New Customer Total Revenue](/reference/metrics/orders/revenue/new-customer-total-revenue) | Revenue from first-time buyers (different from first-time subscribers) | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Revenue after discounts and refunds | [See all Revenue metrics →](/reference/metrics/orders/revenue) # Total Revenue: Complete Order Revenue Including Shipping and Taxes Source: https://docs.upstackdata.com/reference/metrics/orders/revenue/total-revenue Track total revenue from all orders including shipping and taxes. The headline revenue number showing complete customer payments. The total dollar amount collected from all orders including product prices, shipping, and taxes—before any refunds. ## Formula **Total Revenue** = **SUM** ( Order Total Price ) ### Formula Components | Metric | Definition | | --------------------- | ---------------------------------------------------------------- | | **Order Total Price** | Complete checkout amount including products, shipping, and taxes | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store collected **\$156,250** in total revenue in January: | Component | Amount | % of Total | | --------- | --------- | ---------- | | Products | \$125,000 | 80.0% | | Shipping | \$18,750 | 12.0% | | Tax | \$12,500 | 8.0% | This headline number represents everything customers paid—use it for high-level sales reporting and trend analysis. *** ## How It Works Total Revenue captures the full order amount at checkout before any post-purchase adjustments like refunds. It includes product revenue, shipping fees, and taxes—giving you the complete picture of customer payments rather than just product sales. *** ## When to Use | Scenario | Action | | --------------------- | ---------------------------------------------------- | | Sales reporting | Use as the headline revenue figure for stakeholders | | Trend analysis | Track week-over-week or month-over-month growth | | Revenue forecasting | Project future revenue based on historical totals | | Customer segmentation | Compare against New/Returning Customer Total Revenue | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | | [Gross Revenue](/reference/metrics/orders/revenue/gross-revenue) | Product revenue before discounts/refunds (excludes shipping/tax) | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Gross Revenue − Discounts − Refunds | | [New Customer Total Revenue](/reference/metrics/orders/revenue/new-customer-total-revenue) | Total Revenue from first-time buyers | | [Orders](/reference/metrics/orders/counts/orders) | Count of completed orders | [See all Revenue metrics →](/reference/metrics/orders/revenue) # Gateway Cost: Track Payment Processing Fees Source: https://docs.upstackdata.com/reference/metrics/orders/transaction/gateway-cost Track total payment gateway processing fees in Upstack. Includes flat fees and percentage-based charges from Stripe, PayPal, and other processors. Gateway Cost measures the total payment gateway processing fees charged by payment processors like Stripe, PayPal, or Shopify Payments. ## Formula **Gateway Cost** = **SUM** ( Payment Gateway Fees ) ### Formula Components | Metric | Definition | | ------------------------ | ------------------------------------------------------------------------------- | | **Payment Gateway Fees** | Flat fees + percentage-based fees charged per transaction by payment processors | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store processed **\$125,000** in revenue across **1,247 orders** in January. With a 2.9% + \$0.30 fee structure: | Component | Calculation | Amount | | ---------------------- | ---------------- | ----------- | | Percentage fees | \$125,000 × 2.9% | \$3,625 | | Flat fees | 1,247 × \$0.30 | \$374 | | **Total Gateway Cost** | | **\$3,999** | *** ## How It Works Gateway Cost aggregates all payment processing fees from your payment processor. This includes both the percentage-based fee (typically 2.4-3.5% of transaction value) and any flat per-transaction fees (\$0.30 is common). The metric pulls from Shopify's transaction data. *** ## When to Use | Scenario | Action | | ------------------------------- | ----------------------------------------------------------------------- | | Evaluating payment processors | Compare Gateway Cost across different processors to find the best rates | | Calculating contribution margin | Deduct from revenue at CM2 level for accurate profitability | | Benchmarking processing costs | Target 2-3% of revenue for typical e-commerce | | Analyzing per-order economics | Combine with per-order metrics to understand unit costs | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------- | ----------------------------------------- | | [Gateway Cost Per Order](/reference/metrics/orders/transaction/gateway-cost-per-order) | Average gateway fee per order | | [Gateway Cost %](/reference/metrics/orders/transaction/gateway-cost-percent) | Gateway fees as percentage of net revenue | | [Total Transaction Cost](/reference/metrics/orders/transaction/total-transaction-cost) | Gateway Cost + Other Transaction costs | [See all Transaction Cost metrics →](/reference/metrics/orders/transaction) # Gateway Cost Per Order: Average Processing Fee Per Transaction Source: https://docs.upstackdata.com/reference/metrics/orders/transaction/gateway-cost-per-order Track average payment gateway processing fees per order in Upstack. Monitor per-transaction costs from Stripe, PayPal, Shopify Payments, and other processors. Gateway Cost Per Order measures the average payment gateway processing fee charged per order by payment processors like Stripe, PayPal, or Shopify Payments. ## Formula **Gateway Cost Per Order** = [**Gateway Cost**](/reference/metrics/orders/transaction/gateway-cost) ÷ [**Orders**](/reference/metrics/orders/counts/orders) ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------- | ------------------------------------- | | [**Gateway Cost**](/reference/metrics/orders/transaction/gateway-cost) | Total payment gateway processing fees | | [**Orders**](/reference/metrics/orders/counts/orders) | Total number of orders in the period | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Average | *** ## Example Your store processed **1,247 orders** in January with a total **Gateway Cost of \$3,999**: | Metric | Value | | -------------------------- | ---------- | | Gateway Cost | \$3,999 | | Orders | 1,247 | | **Gateway Cost Per Order** | **\$3.21** | With a typical fee structure of 2.9% + \$0.30, an average order value of \$100 results in roughly \$3.20 per order in gateway fees. *** ## How It Works Gateway Cost Per Order divides total payment processing fees by the number of orders. This metric helps you understand the fixed and variable components of your payment costs on a per-transaction basis. Higher AOV orders typically have higher absolute gateway costs but lower costs as a percentage of revenue. *** ## When to Use | Scenario | Action | | ---------------------------- | -------------------------------------------------------------------- | | Evaluating flat-fee impact | Compare against AOV to see how the flat fee (\$0.30) impacts margins | | Unit economics analysis | Include in per-order cost calculations for profitability | | Payment processor comparison | Compare per-order costs across different payment methods | | Pricing decisions | Factor into minimum order thresholds or small-cart surcharges | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------- | ----------------------------------------- | | [Gateway Cost](/reference/metrics/orders/transaction/gateway-cost) | Numerator: total processing fees | | [Orders](/reference/metrics/orders/counts/orders) | Denominator: order count | | [Gateway Cost %](/reference/metrics/orders/transaction/gateway-cost-percent) | Gateway fees as percentage of net revenue | [See all Transaction Cost metrics →](/reference/metrics/orders/transaction) # Gateway Cost %: Payment Fees as Share of Revenue Source: https://docs.upstackdata.com/reference/metrics/orders/transaction/gateway-cost-percent Track gateway cost as a percentage of net revenue. Measure payment processing fee burden and optimize processor selection for your Shopify store. Payment gateway cost as a percentage of net revenue. ## Formula **Gateway Cost %** = ( [**Gateway Cost**](/reference/metrics/orders/transaction/gateway-cost) ÷ [**Net Revenue**](/reference/metrics/orders/revenue/net-revenue) ) × 100 ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------- | ------------------------------------- | | [**Gateway Cost**](/reference/metrics/orders/transaction/gateway-cost) | Total payment gateway processing fees | | [**Net Revenue**](/reference/metrics/orders/revenue/net-revenue) | Revenue after discounts and refunds | | Metadata | | | --------------- | --------------------------- | | **Type** | Percentage | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Ratio | *** ## Example Your store processed **\$125,000** in net revenue with **\$3,125** in gateway fees: | Month | Net Revenue | Gateway Cost | Gateway Cost % | | -------- | ----------- | ------------ | -------------- | | January | \$125,000 | \$3,125 | 2.5% | | February | \$142,000 | \$3,692 | 2.6% | | March | \$118,000 | \$2,832 | 2.4% | *** ## How It Works Gateway Cost % divides total payment gateway fees by net revenue, showing what percentage of each sale goes to payment processing. This metric helps benchmark processor costs—typical rates range from 2% to 3% depending on payment method mix and processor agreements. *** ## When to Use | Scenario | Action | | ----------------------- | ------------------------------------------------------- | | Processor benchmarking | Compare your rate against industry standards (2-3%) | | Negotiating rates | Use historical data to negotiate better processor terms | | Payment method analysis | Identify high-cost payment methods driving up fees | | Margin optimization | Find opportunities to reduce transaction costs | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------- | --------------------------------------------- | | [Gateway Cost](/reference/metrics/orders/transaction/gateway-cost) | Numerator—total gateway fees | | [Net Revenue](/reference/metrics/orders/revenue/net-revenue) | Denominator—revenue after adjustments | | [Gateway Cost Per Order](/reference/metrics/orders/transaction/gateway-cost-per-order) | Per-order view of gateway fees | | [Total Transaction Cost](/reference/metrics/orders/transaction/total-transaction-cost) | Includes gateway plus other transaction costs | [See all Transaction Cost metrics →](/reference/metrics/orders/transaction) # Transaction Costs: Track Payment Gateway Fees Source: https://docs.upstackdata.com/reference/metrics/orders/transaction/index Track transaction cost metrics in Upstack. Includes Gateway Cost, Transaction Fees, and payment processing expenses by customer type. Transaction cost metrics track payment processing expenses—gateway fees, interchange costs, and other transaction charges. **Data Source:** [Shopify](/sources/shopify)\ **Metrics:** 11 ## Metrics in This Group | Metric | Description | When to Use | | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | --------------------------- | | [Gateway Cost](/reference/metrics/orders/transaction/gateway-cost) | Payment gateway fees | Track processing costs | | [Gateway Cost Per Order](/reference/metrics/orders/transaction/gateway-cost-per-order) | Gateway cost per order | Per-order fees | | [Gateway Cost %](/reference/metrics/orders/transaction/gateway-cost-percent) | Gateway as % of revenue | Fee burden | | [Other Transaction Cost](/reference/metrics/orders/transaction/other-transaction-cost) | Additional transaction fees | Misc processing costs | | [Total Transaction Cost](/reference/metrics/orders/transaction/total-transaction-cost) | All transaction costs combined | Total processing burden | | [New Customer Gateway Cost](/reference/metrics/orders/transaction/new-customer-gateway-cost) | Gateway fees for new customers | Segment analysis | | [Returning Customer Gateway Cost](/reference/metrics/orders/transaction/returning-customer-gateway-cost) | Gateway fees for returning customers | Compare segments | | [New Customer Other Transaction Cost](/reference/metrics/orders/transaction/new-customer-other-transaction-cost) | Other fees for new customers | Detailed new customer costs | | [Returning Customer Other Transaction Cost](/reference/metrics/orders/transaction/returning-customer-other-transaction-cost) | Other fees for returning customers | Detailed returning costs | | [New Customer Total Transaction Cost](/reference/metrics/orders/transaction/new-customer-total-transaction-cost) | All transaction costs for new customers | Total NC payment burden | | [Returning Customer Transaction Cost](/reference/metrics/orders/transaction/returning-customer-transaction-cost) | All transaction costs for returning customers | Total RC payment burden | ## How These Metrics Relate Transaction costs impact contribution margin at the CM2 level: * **Total Transaction Cost** = Gateway Cost + Other Transaction Cost * **New Customer Total Transaction Cost** = NC Gateway Cost + NC Other Transaction Cost * **Returning Customer Transaction Cost** = RC Gateway Cost + RC Other Transaction Cost * **CM2** = CM1 - Fulfillment Costs - Transaction Costs * Gateway Cost % typically ranges from 2-3% of revenue for most processors ## Choosing the Right Metric * **Payment optimization**: Use Gateway Cost % to benchmark processor fees * **Per-order economics**: Use Per Order metrics for unit economics * **Total processing**: Use Total Transaction Cost for full payment burden * **Customer profitability**: Compare New vs Returning transaction costs # New Customer Gateway Cost: Payment Processing for First-Time Buyers Source: https://docs.upstackdata.com/reference/metrics/orders/transaction/new-customer-gateway-cost Track payment gateway fees from new customer orders. Understand first-time buyer processing costs and segment transaction expenses by customer type. Total payment gateway fees for orders placed by new customers. ## Formula **New Customer Gateway Cost** = **SUM** ( [**Gateway Cost**](/reference/metrics/orders/transaction/gateway-cost) ) **WHERE** [customer\_type = new\_customer](/data-dictionary/measures-and-dimensions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | | [**Gateway Cost**](/reference/metrics/orders/transaction/gateway-cost) | Payment gateway processing fees including flat fees and percentage-based fees | | [**customer\_type = new\_customer**](/data-dictionary/measures-and-dimensions) | Filter to include only first-time purchasers | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store processed **\$1,247** in gateway fees from new customers in January: | Customer Type | Orders | Gateway Cost | Avg per Order | | ------------------- | ------ | ------------ | ------------- | | New Customers | 412 | \$1,247 | \$3.03 | | Returning Customers | 835 | \$2,089 | \$2.50 | New customers have higher per-order gateway costs due to smaller average order values. *** ## How It Works This metric sums all payment gateway processing fees—including percentage-based fees and flat per-transaction charges—for orders placed by first-time customers. Shopify identifies new customers as those with no prior order history in your store. *** ## When to Use | Scenario | Action | | ----------------------------- | ----------------------------------------------------------------- | | Customer acquisition analysis | Compare gateway costs between new and returning segments | | LTV modeling | Include acquisition-phase transaction costs in customer economics | | Processor negotiation | Benchmark new customer fees to negotiate better rates | | CM2 segmentation | Understand how transaction costs vary by customer type | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | [Gateway Cost](/reference/metrics/orders/transaction/gateway-cost) | Parent metric (all customers combined) | | [Returning Customer Gateway Cost](/reference/metrics/orders/transaction/returning-customer-gateway-cost) | Same metric for repeat buyers | | [Total Transaction Cost](/reference/metrics/orders/transaction/total-transaction-cost) | Includes gateway plus other transaction fees | | [New Customer Revenue](/reference/metrics/orders/revenue/new-customer-total-revenue) | Revenue side of new customer economics | [See all Transaction Cost metrics →](/reference/metrics/orders/transaction) # New Customer Other Transaction Cost: Custom Fees for First-Time Buyers Source: https://docs.upstackdata.com/reference/metrics/orders/transaction/new-customer-other-transaction-cost Track user-defined transaction costs from order cost entries for new customer orders. Analyze custom processing fees and interchange expenses affecting first-time buyer profitability. The total user-defined transaction costs from order cost entries for new customer orders. ## Formula **New Customer Other Transaction Cost** = **SUM** ( [**Other Transaction Cost**](/reference/metrics/orders/transaction/other-transaction-cost) ) **WHERE** [customer\_type = new\_customer](/data-dictionary/measures-and-dimensions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- | | [**Other Transaction Cost**](/reference/metrics/orders/transaction/other-transaction-cost) | User-defined transaction costs from order cost entries | | [**customer\_type = new\_customer**](/data-dictionary/measures-and-dimensions) | Filter to orders placed by first-time buyers with no prior purchase history | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store incurred **\$1,247** in custom transaction costs for new customer orders in March: | Week | NC Other Transaction Cost | NC Orders | Cost/Order | | ------ | ------------------------- | --------- | ---------- | | Week 1 | \$287 | 142 | \$2.02 | | Week 2 | \$324 | 168 | \$1.93 | | Week 3 | \$298 | 151 | \$1.97 | | Week 4 | \$338 | 176 | \$1.92 | Stable per-order costs indicate consistent payment method mix among new customers. *** ## How It Works This metric sums all user-defined transaction costs from order cost entries specifically for new customer orders. A customer is classified as "new" when they have no prior completed orders in Shopify. These costs are distinct from gateway fees and typically include interchange markups, currency conversion charges, or custom payment processing fees you've defined in your order cost configuration. *** ## When to Use | Scenario | Action | | ------------------------ | -------------------------------------------------------------- | | Analyzing CAC components | Include in total customer acquisition cost calculations | | Comparing payment costs | Benchmark new vs. returning customer transaction costs | | Margin optimization | Identify if payment method preferences differ by customer type | | Unit economics analysis | Calculate true per-order costs for new customer acquisition | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [Returning Customer Other Transaction Cost](/reference/metrics/orders/transaction/returning-customer-other-transaction-cost) | Compare new vs. returning customer costs | | [New Customer Gateway Cost](/reference/metrics/orders/transaction/new-customer-gateway-cost) | Primary payment processing fees for new customers | | [Other Transaction Cost](/reference/metrics/orders/transaction/other-transaction-cost) | Total other transaction costs across all customers | | [Total Transaction Cost](/reference/metrics/orders/transaction/total-transaction-cost) | Combined gateway and other transaction fees | [See all Transaction Cost metrics →](/reference/metrics/orders/transaction) # Other Transaction Cost: Custom Payment Processing Fees Source: https://docs.upstackdata.com/reference/metrics/orders/transaction/other-transaction-cost Track user-defined transaction costs from order cost entries. Includes additional payment processing fees beyond standard gateway charges. User-defined transaction costs from order cost entries—additional payment processing fees beyond standard gateway charges. ## Formula **Other Transaction Cost** = **SUM** ( Order Cost Entries ) **WHERE** [category = Transaction](/data-dictionary/measures-and-dimensions) ### Formula Components | Metric | Definition | | ---------------------------------------------------------------------- | --------------------------------------------------- | | **Order Cost Entries** | Custom costs you've assigned to orders in Shopify | | [**category = Transaction**](/data-dictionary/measures-and-dimensions) | Filter for entries categorized as transaction costs | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store had **\$1,247** in other transaction costs this month across 892 orders: | Cost Type | Amount | Per Order | | ------------------------ | ------ | --------- | | Currency conversion fees | \$523 | \$0.59 | | Cross-border processing | \$412 | \$0.46 | | Chargeback fees | \$312 | \$0.35 | *** ## How It Works Other Transaction Cost sums custom transaction-related expenses you've added to order cost entries with the Transaction category. These fees are separate from standard gateway processing fees and typically include currency conversion, cross-border charges, or specialized payment method costs. *** ## When to Use | Scenario | Action | | ------------------------ | ---------------------------------------------------- | | Track non-gateway fees | Monitor currency conversion and cross-border costs | | Calculate true CM2 | Include all transaction costs in contribution margin | | Audit payment expenses | Identify hidden costs beyond standard gateway fees | | Optimize payment methods | Compare total cost of different payment options | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | [Gateway Cost](/reference/metrics/orders/transaction/gateway-cost) | Standard payment gateway fees (this metric captures additional fees) | | [Total Transaction Cost](/reference/metrics/orders/transaction/total-transaction-cost) | Gateway Cost + Other Transaction Cost | | [New Customer Other Transaction Cost](/reference/metrics/orders/transaction/new-customer-other-transaction-cost) | This metric filtered to new customers | | [Returning Customer Other Transaction Cost](/reference/metrics/orders/transaction/returning-customer-other-transaction-cost) | This metric filtered to returning customers | [See all Transaction Cost metrics →](/reference/metrics/orders/transaction) # Returning Customer Gateway Cost: Payment Processing for Repeat Buyers Source: https://docs.upstackdata.com/reference/metrics/orders/transaction/returning-customer-gateway-cost Track payment gateway fees from returning customer orders. Analyze repeat buyer processing costs and compare transaction expenses across customer segments. Total payment gateway fees for orders placed by returning customers. ## Formula **Returning Customer Gateway Cost** = **SUM** ( [**Gateway Cost**](/reference/metrics/orders/transaction/gateway-cost) ) **WHERE** [customer\_type = returning\_customer](/data-dictionary/measures-and-dimensions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | | [**Gateway Cost**](/reference/metrics/orders/transaction/gateway-cost) | Payment gateway processing fees including flat fees and percentage-based fees | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions) | Filter to include only repeat purchasers | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store processed **\$2,089** in gateway fees from returning customers in January: | Customer Type | Orders | Gateway Cost | Avg per Order | | ------------------- | ------ | ------------ | ------------- | | Returning Customers | 835 | \$2,089 | \$2.50 | | New Customers | 412 | \$1,247 | \$3.03 | Returning customers have lower per-order gateway costs due to higher average order values and repeat purchase patterns. *** ## How It Works This metric sums all payment gateway processing fees—including percentage-based fees and flat per-transaction charges—for orders placed by returning customers. Shopify identifies returning customers as those who have at least one prior order in your store history. *** ## When to Use | Scenario | Action | | ------------------- | --------------------------------------------------------------------- | | Retention economics | Evaluate profitability of repeat buyers including transaction costs | | LTV refinement | Include returning customer transaction costs in lifetime value models | | Segment comparison | Compare gateway costs between new and returning customers | | CM2 calculation | Factor transaction costs into contribution margin by segment | *** ## Related Metrics | Metric | Relationship | | ------------------------------------------------------------------------------------------------ | -------------------------------------------- | | [Gateway Cost](/reference/metrics/orders/transaction/gateway-cost) | Parent metric (all customers combined) | | [New Customer Gateway Cost](/reference/metrics/orders/transaction/new-customer-gateway-cost) | Same metric for first-time buyers | | [Total Transaction Cost](/reference/metrics/orders/transaction/total-transaction-cost) | Includes gateway plus other transaction fees | | [Returning Customer Revenue](/reference/metrics/orders/revenue/returning-customer-total-revenue) | Revenue side of returning customer economics | [See all Transaction Cost metrics →](/reference/metrics/orders/transaction) # Returning Customer Other Transaction Cost: Custom Fees for Repeat Buyers Source: https://docs.upstackdata.com/reference/metrics/orders/transaction/returning-customer-other-transaction-cost Track user-defined transaction costs from order cost entries for returning customer orders. Analyze custom processing fees and interchange expenses affecting repeat buyer profitability. The total user-defined transaction costs from order cost entries for returning customer orders. ## Formula **Returning Customer Other Transaction Cost** = **SUM** ( [**Other Transaction Cost**](/reference/metrics/orders/transaction/other-transaction-cost) ) **WHERE** [customer\_type = returning\_customer](/data-dictionary/measures-and-dimensions) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | | [**Other Transaction Cost**](/reference/metrics/orders/transaction/other-transaction-cost) | User-defined transaction costs from order cost entries | | [**customer\_type = returning\_customer**](/data-dictionary/measures-and-dimensions) | Filter to orders placed by customers with at least one prior completed purchase | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store incurred **\$2,856** in custom transaction costs for returning customer orders in March: | Week | RC Other Transaction Cost | RC Orders | Cost/Order | | ------ | ------------------------- | --------- | ---------- | | Week 1 | \$687 | 342 | \$2.01 | | Week 2 | \$724 | 368 | \$1.97 | | Week 3 | \$698 | 351 | \$1.99 | | Week 4 | \$747 | 376 | \$1.99 | Consistent per-order costs indicate stable payment method preferences among returning customers. *** ## How It Works This metric sums all user-defined transaction costs from order cost entries specifically for returning customer orders. A customer is classified as "returning" when they have at least one prior completed order in Shopify. These costs are distinct from gateway fees and typically include interchange markups, currency conversion charges, or custom payment processing fees you've defined in your order cost configuration. *** ## When to Use | Scenario | Action | | --------------------------------- | ------------------------------------------------------------------ | | Analyzing retention profitability | Include in contribution margin calculations for repeat buyers | | Comparing payment costs | Benchmark new vs. returning customer transaction costs | | Margin optimization | Identify if payment method preferences differ by customer type | | LTV analysis | Factor transaction costs into customer lifetime value calculations | *** ## Related Metrics | Metric | Relationship | | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | [New Customer Other Transaction Cost](/reference/metrics/orders/transaction/new-customer-other-transaction-cost) | Compare new vs. returning customer costs | | [Returning Customer Gateway Cost](/reference/metrics/orders/transaction/returning-customer-gateway-cost) | Primary payment processing fees for returning customers | | [Other Transaction Cost](/reference/metrics/orders/transaction/other-transaction-cost) | Total other transaction costs across all customers | | [Total Transaction Cost](/reference/metrics/orders/transaction/total-transaction-cost) | Combined gateway and other transaction fees | [See all Transaction Cost metrics →](/reference/metrics/orders/transaction) # Total Transaction Cost: Combined Payment Processing Fees Source: https://docs.upstackdata.com/reference/metrics/orders/transaction/total-transaction-cost Track total transaction costs including gateway fees and user-defined transaction costs. Understand payment processing impact on contribution margin. The total cost of processing payments, combining gateway fees and any additional user-defined transaction costs. ## Formula **Total Transaction Cost** = [**Gateway Cost**](/reference/metrics/orders/transaction/gateway-cost) + [**Other Transaction Cost**](/reference/metrics/orders/transaction/other-transaction-cost) ### Formula Components | Metric | Definition | | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | | [**Gateway Cost**](/reference/metrics/orders/transaction/gateway-cost) | Payment gateway processing fees including flat and percentage-based fees | | [**Other Transaction Cost**](/reference/metrics/orders/transaction/other-transaction-cost) | User-defined transaction costs from order cost entries | | Metadata | | | --------------- | --------------------------- | | **Type** | Currency | | **Data Source** | [Shopify](/sources/shopify) | | **Aggregation** | Sum | *** ## Example Your store processed **\$125,000** in orders this month with **\$4,875** in total transaction costs: | Component | Amount | % of Revenue | | -------------------------- | ----------- | ------------ | | Gateway Cost | \$3,750 | 3.0% | | Other Transaction Cost | \$1,125 | 0.9% | | **Total Transaction Cost** | **\$4,875** | **3.9%** | *** ## How It Works Total Transaction Cost aggregates all payment-related fees from your orders. Gateway costs are pulled from Shopify's transaction data, while Other Transaction costs come from user-defined order cost entries with the "Transaction" category. This metric is deducted from CM1 to calculate CM2. *** ## When to Use | Scenario | Action | | ------------------------------- | ---------------------------------------------- | | Calculating contribution margin | Deduct from CM1 alongside fulfillment costs | | Evaluating payment processors | Compare total processing costs across gateways | | Pricing strategy | Factor transaction costs into product margins | | Profitability analysis | Track how payment fees impact net margins | *** ## Related Metrics | Metric | Relationship | | -------------------------------------------------------------------------------------- | ----------------------------------------------- | | [Gateway Cost](/reference/metrics/orders/transaction/gateway-cost) | Component: payment processor fees | | [Other Transaction Cost](/reference/metrics/orders/transaction/other-transaction-cost) | Component: user-defined transaction costs | | [Gateway Cost %](/reference/metrics/orders/transaction/gateway-cost-percent) | Gateway fees as percentage of revenue | | [CM1](/reference/metrics/orders/contribution-margin/cm1) | Margin before transaction and fulfillment costs | | [CM2](/reference/metrics/orders/contribution-margin/cm2) | Margin after deducting this cost | [See all Transaction Cost metrics →](/reference/metrics/orders/transaction) # How to find my Upstack Data Pixel ID? Source: https://docs.upstackdata.com/resources/how-to-find-my-upstack-data-pixel-id Find your Upstack Data Pixel ID in the dashboard under Settings → Pixel — required for installing the tracking script on Shopify, headless storefronts, and third-party landing pages. *** ## **Prerequisites** * An [Upstack Data](https://app.upstackdata.com/login) account with the email and password you used during sign-up. * The Upstack Data app installed on your Shopify store (your Pixel ID is generated when the app is installed). ## **Steps to Locate Your Pixel ID** ## **Step 1: Sign in to your Upstack Data account** * Go to [https://app.upstackdata.com/login](https://app.upstackdata.com/login). * Enter your **email and password**. * Click **Sign In**. *** ## **Step 2: Open the Event Health page** * Once signed in, click **Settings** in the bottom-left of the [Upstack dashboard](https://app.upstackdata.com). * In the Settings menu, open **Event Health**. Upstack dashboard Settings menu with Event Health option

Upstack dashboard Settings menu with Event Health option

*** ## **Step 3: Locate your Pixel ID** * Your Pixel ID is displayed at the top of the **Event Health** page, clearly labelled **Pixel ID**. Event Health page displaying the Pixel ID at the top

Event Health page displaying the Pixel ID at the top

Your Upstack Pixel ID format is a UUID like: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX` For example: `58284d43-85f6-41fb-b2e0-f32f8ecb4e9b` **Note:** Your Pixel ID will be different from this example as it is unique to your Shopify store. *** ## **Step 4: Copy and save your Pixel ID** * **Copy** your Pixel ID for use in your setup, and **store** it in a secure location for future reference. * Paste it exactly as shown — Pixel IDs are case-sensitive and any extra whitespace will break tracking. *** ## **Step 5: Verify the Pixel ID works** * Paste the Pixel ID into the destination you're configuring (landing page, GTM, Checkout Champ, etc.). * Visit the page in a browser and use the [Upstack Data Pixel Helper](/guides/shopify/how-to-install-upstack-data-pixel-helper) to confirm the pixel fires with this Pixel ID. * In the [Upstack dashboard](https://app.upstackdata.com) under **Event Health**, confirm the new events arrive against your Pixel ID. *** ## **Can't see your Pixel ID?** * Make sure you're on the **Event Health** page in the [Upstack dashboard](https://app.upstackdata.com). * Confirm the Upstack Data app is still installed in your Shopify Admin under **Settings → Apps and sales channels**. * Contact Upstack support at [support@upstackdata.com](mailto:support@upstackdata.com). # How to invite a team member to your Upstack account Source: https://docs.upstackdata.com/resources/how-to-invite-a-team-member-to-your-upstack-account A step-by-step guide for account owners and admins to invite a teammate, agency partner, or stakeholder to their Upstack workspace, including roles and common scenarios. This is a step-by-step guide for account owners and admins who need to add a teammate — a developer, marketer, agency partner, or another stakeholder — to their Upstack workspace. ## Steps Sign in to your Upstack account. Open **Settings**. It sits in the bottom-left of the navigation. Upstack dashboard navigation with Settings in the bottom-left

Upstack dashboard navigation with Settings in the bottom-left

Go to the **Team** tab inside Settings, then click **Add Team member**. Team tab inside Upstack Settings

Add team member form in Upstack Settings

* Enter the new teammate's **email address** in the email field. * Choose a **role**. For full access — including the ability to invite others, manage billing, and remove users — select **Admin**. * Click **Add Email** for each user you add. You can add multiple users. When you're done, click **Send Invitations** to invite everyone you added. Adding emails and sending invitations to team members

Adding emails and sending invitations to team members

The user receives an invite like the following: Example team invitation email from Upstack

After accepting the invite, the user is prompted to create their credentials. They can then log in and see the organization's dashboard in the platform. ## What the invitee should expect An email invite arrives in the inbox of the address you entered. If they don't see it, ask them to search their inbox for "upstack" — the from address and subject line both reference the brand. Check the spam folder in case it isn't in the main inbox. They click the link in the email to confirm the invite and finish signing in. Invites are time-limited. They are valid for 5 days before the invitee link expires. To send a fresh one, go back to the Team page and re-add the email. If they already have an Upstack login under that email, accepting the invite simply attaches the new account to their existing user. They can switch between accounts from the account switcher. ## Common scenarios A teammate may accidentally create their own Upstack account instead of joining yours. Invite their email to the correct account as an admin. Have them log out, accept the invite from their email, sign back in, and switch into the shared account. They can then cancel the duplicate account they created. Yes. Use the same flow — add their work email as an admin, or a more limited role if available on your plan. Remove them from the Team page when the engagement ends. Re-send by re-adding the email on the Team page. The previous invite is automatically superseded. ## Roles | Role | Typical use | | ------ | -------------------------------------------------------------------------------- | | Admin | Full access — manage users, billing, integrations, and data. | | Owner | Account creator; only another owner can remove an owner. | | Member | Can view dashboards and event streams but cannot modify integrations or billing. | # How to Set up Upstack Data on a Landing Page or Subdomain Source: https://docs.upstackdata.com/resources/how-to-set-up-upstack-data-on-a-landing-page-or-subdomain Install the Upstack Data Pixel on a landing page or subdomain by adding the script with your Pixel ID into the page's head — enabling tracking and attribution for non-Shopify domains. *** ## **Quick Summary** * **Copy your Pixel ID** from the [Upstack dashboard](https://app.upstackdata.com). * **Insert the Pixel ID** into the script below. * Place the script **inside the `` section** of your webpage. * **Publish** or **update** your landing page. * **Verify** your installation. *** ## **Prerequisites** * An [Upstack Data](https://app.upstackdata.com) account with the Upstack Data app installed on your Shopify store. * Your Upstack Pixel ID (UUID format: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`, e.g., `58284d43-85f6-41fb-b2e0-f32f8ecb4e9b`). See [How to find my Upstack Data Pixel ID](/resources/how-to-find-my-upstack-data-pixel-id). * Edit access to the landing page or subdomain (admin access in the page builder, CMS, or static host). * Ability to add code to the `` section (Custom Code / Header Code area in your tool). *** ## **Configuration Steps** ## **Step 1: Find and copy your Upstack Pixel ID** Your **Upstack Pixel ID** is a unique identifier linked to your Shopify store. This ID is used to track browser events and associate them with your account. For step-by-step instructions on locating your Upstack Pixel ID, see: [How to find my Upstack Data Pixel ID?](/resources/how-to-find-my-upstack-data-pixel-id) *** ## **Step 2: Insert your Pixel ID into the script** * Open the Upstack Pixel script provided below. * Replace the placeholder Pixel ID with your own ID. ### Upstack Pixel Snippet ```html theme={null} ``` **Important:** * **Replace `XXXX-XXXX-XXXXX-XXXX` with the Pixel ID** you obtained in Step 1 (UUID format: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`). * Enter the Pixel ID exactly as provided — extra whitespace or quotation mismatches will break tracking. *** ## **Step 3: Add the script to your landing page** * Open the landing page editor or HTML settings of your third-party tool. * Locate the **Custom Code** or **Header Code** section. * Paste the complete script into the `` section of the page. *** ## **Step 4: Publish or update your landing page** * Save and republish the page so the script goes live. *** ## **Step 5: Verify the installation** * Visit your landing page in a browser. * Use the [Upstack Data Pixel Helper](/guides/shopify/how-to-install-upstack-data-pixel-helper) to confirm the pixel is firing correctly with your Pixel ID. * In the [Upstack dashboard](https://app.upstackdata.com) under **Event Health**, confirm `PageView` events from the new landing page arrive within a few minutes. *** **Need help?** If you encounter any issues during setup, contact our support team and we'll help diagnose the problem. # How to Set up Upstack Data on Checkout Champ Source: https://docs.upstackdata.com/resources/how-to-set-up-upstack-data-on-checkout-champ Install the Upstack Data Pixel on Checkout Champ by pasting the script with your Pixel ID into the Global Scripts section — enabling tracking and attribution across all funnels. *** ## Quick Summary * **Copy your Pixel ID** from the [Upstack dashboard](https://app.upstackdata.com). * **Insert the Pixel ID** into the script below. * Add the script to the **Global Scripts** section in your Checkout Champ admin, loaded in the `` of every funnel. * **Disable the native Checkout Champ Facebook Pixel** to avoid duplicate tracking. * **Save** your changes. * **Verify** your installation. *** ## Prerequisites * An [Upstack Data](https://app.upstackdata.com) account with the Upstack Data app installed on your Shopify store. * Your Upstack Pixel ID (UUID format: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`, e.g., `58284d43-85f6-41fb-b2e0-f32f8ecb4e9b`). See [How to find my Upstack Data Pixel ID](/resources/how-to-find-my-upstack-data-pixel-id). * Admin access to your Checkout Champ admin panel with permission to edit **Global Scripts** and disable native pixel integrations. * Coordination with the Upstack Data team to receive the **full** Checkout Champ tracking script block during onboarding. *** ## Configuration Steps ## Step 1: Find and copy your Upstack Pixel ID Your **Upstack Pixel ID** is a unique identifier linked to your store. This ID is used to track browser events and associate them with your account. For step-by-step instructions on locating your Upstack Pixel ID, see: [How to find my Upstack Data Pixel ID?](/resources/how-to-find-my-upstack-data-pixel-id) *** ## Step 2: Disable the native Checkout Champ Facebook Pixel **Critical: do this first!** Before adding the Upstack scripts, you **must** disable the native Checkout Champ Facebook Pixel integration. Running both simultaneously will cause **duplicate event tracking**, which leads to inflated metrics and poor ad optimization. * Sign in to your Checkout Champ admin panel. * Navigate to the **Facebook Pixel** settings (typically found under tracking or integration settings). * **Remove or disable** any existing Facebook Pixel ID configured in the native integration. * **Save** your changes. This ensures Upstack Data is the sole source of pixel events, preventing duplication and ensuring accurate attribution. *** ## Step 3: Insert your Pixel ID into the script * Open the Upstack Pixel script provided below. * Replace the placeholder Pixel ID with your own ID. ### Upstack Pixel Snippet ```html theme={null} ``` **Important:** * **Replace `XXXX-XXXX-XXXXX-XXXX` with the Pixel ID** you obtained in Step 1 (UUID format: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`). * Enter the Pixel ID exactly as provided — extra whitespace or quotation mismatches will break tracking. The complete Checkout Champ tracking script includes additional event tracking scripts for **ccpurchase**, **initiate\_checkout**, **shared utilities**, **add\_to\_cart**, **add\_shipping\_info**, and **add\_payment\_info**. The full script block will be provided by the Upstack Data team during onboarding. Paste the Global Script above along with all event tracking scripts together into the Global Scripts section. *** ## Step 4: Add the script to Checkout Champ Global Scripts * Sign in to your Checkout Champ admin panel. * Navigate to the **Global Scripts** section. * Paste the **entire script block** (Global Script plus all event tracking scripts). * Ensure the script is set to load in the `` of every funnel page. * **Save** your changes. *** ## Step 5: Verify the installation * Visit one of your funnel pages in a browser. * Use the [Upstack Data Pixel Helper](/guides/shopify/how-to-install-upstack-data-pixel-helper) (or your browser developer console) to confirm the pixel is firing correctly with your Pixel ID. * Walk through a test checkout end-to-end to verify each event fires. * In the [Upstack dashboard](https://app.upstackdata.com) under **Event Health**, confirm `page`, `initiate_checkout`, and `purchase` events arrive against your Pixel ID. *** ## Events tracked Once installed, the following events are automatically tracked: * **page** — Fires on every page load. * **initiate\_checkout** — Fires when a customer enters their email or an order begins. * **add\_to\_cart** — Fires when items are added to the cart. * **add\_shipping\_info** — Fires when shipping information is provided. * **add\_payment\_info** — Fires when payment details are entered. * **purchase** — Fires on completed (non-partial) orders. *** **Need help?** If you encounter any issues during setup, contact our support team and we'll help diagnose the problem. # Implementing Upstack Data on Landing Pages, Subdomains, and Third-Party Sites Source: https://docs.upstackdata.com/resources/implementing-upstack-data-on-landing-pages Install the Upstack Data Pixel on landing pages, subdomains, headless storefronts, and third-party platforms — track events and attribute conversions beyond your Shopify store. When your marketing funnel extends beyond your Shopify storefront — landing pages, subdomains, headless commerce frontends, WordPress sites, or third-party quiz/survey platforms — you need to install the Upstack Pixel manually to capture events and maintain attribution continuity. This guide covers two implementation methods: * **Direct installation** — Add the pixel script directly to your page's HTML * **Google Tag Manager (GTM)** — Deploy via your GTM container for centralized tag management For the full event payload reference — including all required and optional properties — see [Standard Events Reference](/pixel/standard-events) and [Properties & Context](/pixel/properties). *** ## When You Need This Guide Install the Upstack Pixel manually when you have: * **Landing pages** — Unbounce, Instapage, Webflow, Carrd, or custom HTML pages * **Subdomains** — `shop.yourdomain.com` or `promo.yourdomain.com` running outside Shopify * **Headless storefronts** — Custom React, Next.js, or Vue frontends using Shopify's Storefront API * **WordPress / WooCommerce** — Sites that redirect to Shopify checkout * **Quiz or survey tools** — Octane AI, Typeform, or Jotform funnels * **Third-party checkout platforms** — Checkout Champ, ClickFunnels, or custom checkout flows *** ## Prerequisites * An [Upstack Data](https://app.upstackdata.com) account with the Upstack Data app installed on your Shopify store * Your Upstack Pixel ID (UUID format: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`, e.g., `58284d43-85f6-41fb-b2e0-f32f8ecb4e9b`). See [How to find my Upstack Data Pixel ID](/resources/how-to-find-my-upstack-data-pixel-id) * Edit access to the site or landing page (admin access in your page builder, CMS, or GTM container) *** ## Step 1: Find Your Upstack Pixel ID Your **Upstack Pixel ID** is a unique identifier linked to your Shopify store. This ID connects browser events from external sites to your Upstack account. For step-by-step instructions, see: [How to find my Upstack Data Pixel ID?](/resources/how-to-find-my-upstack-data-pixel-id) *** ## Step 2: Choose Your Implementation Method Add the pixel script directly to your page's `` section. This is the simplest approach for landing pages and sites without a tag manager. ### Base Pixel Snippet (Required on Every Page) ```html theme={null} ``` **Replace `YOUR_PIXEL_ID`** with the Pixel ID you obtained in Step 1 (UUID format: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`). Deploy the pixel via GTM for centralized tag management and conditional triggering. 1. Sign in to [Google Tag Manager](https://tagmanager.google.com) and open your container 2. Navigate to **Tags → New** 3. Select **Custom HTML** as the tag type 4. Paste the pixel snippet into the HTML editor 5. Set the trigger to **All Pages** (or specific page conditions) ### GTM Custom HTML Tag ```html theme={null} ``` For e-commerce events, you can use GTM Data Layer variables to dynamically populate event properties. See Step 3 for event snippets. *** ## Step 3: Track Events Beyond page views, you'll want to track key conversion events. Each event follows the same pattern: ```javascript theme={null} window._upstack('track', 'event_name', { /* event properties */ }); ``` For the complete list of standard events and their required properties, see the [Standard Events Reference](/pixel/standard-events). ### Event Snippets Reference Fires when a visitor views a product or content page. ```html theme={null} ``` **Required properties:** `value`, `currency`, `items` See [ViewContent in Standard Events](/pixel/standard-events) for the full specification. Fires when a visitor adds an item to their cart. ```html theme={null} ``` **Required properties:** `value`, `currency`, `items` See [AddToCart in Standard Events](/pixel/standard-events) for the full specification. Fires when a visitor starts the checkout flow. ```html theme={null} ``` **Required properties:** `value`, `currency`, `items` **Recommended:** Include identity fields (`email`, `phone`, `firstName`, `lastName`) to improve destination match quality. See [InitiateCheckout in Standard Events](/pixel/standard-events) for the full specification. Fires when an order is completed. This is the most important conversion event. ```html theme={null} ``` **Required properties:** `transactionId` or `orderId`, `value`, `currency`, `items` **Recommended:** Include all identity fields for maximum match quality at destinations. See [Purchase in Standard Events](/pixel/standard-events) for the full specification. Fires when a visitor submits a lead form, quiz, or survey. ```html theme={null} ``` **Required properties:** At least one identity field (`email` or `phone`) See [Lead in Standard Events](/pixel/standard-events) for the full specification. Fires when a visitor subscribes to email or SMS marketing. ```html theme={null} ``` See [Subscribe in Standard Events](/pixel/standard-events) for the full specification. *** ## Step 4: Preserve UTM Parameters Across Pages If your landing page links to your Shopify store or checkout, preserve UTM parameters and click IDs to maintain attribution continuity. Add this script to automatically append the current page's query string to all outbound links: ```html theme={null} ``` This ensures `fbclid`, `gclid`, `ttclid`, and UTM parameters flow through to Shopify checkout. *** ## Step 5: Verify Your Installation 1. **Visit your site** and trigger each event you configured (page view, lead capture, purchase, etc.) 2. **Use the Pixel Helper** — Install the [Upstack Data Pixel Helper](/guides/shopify/how-to-install-upstack-data-pixel-helper) browser extension to confirm events fire with the expected parameters 3. **Check Event Health** — In the [Upstack dashboard](https://app.upstackdata.com) under **Event Health**, confirm events arrive with your Pixel ID and correct properties If using GTM, use **Preview / Debug** mode to verify tags fire on the correct triggers before publishing. *** ## Platform-Specific Guides Quick setup for Unbounce, Instapage, Webflow, and custom landing pages. Full integration guide for Checkout Champ implementations. *** ## Reference Documentation Overview of the Upstack event model and how events flow through the pipeline. Complete specification for every standard event — required properties, optional fields, and example payloads. Full reference for user data, custom data, and context fields attached to events. Define your own events for interactions beyond the standard taxonomy. *** **Health and Wellness stores:** If you're in the health/wellness category and need to use custom event names for platform compliance, see [Health and Wellness Custom Event Mappings →](/guides/facebook-ads/health-and-wellness-custom-event-mappings) # Upstack-Enhanced Klaviyo Abandonment Flows (Overview & FAQs) Source: https://docs.upstackdata.com/resources/upstack-enhanced-klaviyo-abandonment-flows-overview-faqs Recover 30-50% more cart, checkout, and browse abandonment revenue with Upstack-enhanced Klaviyo flows — how identity resolution feeds Klaviyo with more triggerable shoppers, plus setup FAQs. *** ## **Summary** **Klaviyo “abandonment” flows** *(browse, cart, checkout abandonment emails)* are a proven way to recover otherwise lost sales by reminding shoppers to finish their purchase. Upstack Data integrates with Klaviyo to supercharge these flows – ensuring **more of your visitors actually receive those follow-up emails**. In fact, most brands see a **30 to 50% lift** in triggered abandonment emails (and revenue) within the first few weeks of Upstack Data. Below, we willll explain how the abandonment flows are set up with Upstack Data, their purpose and mechanics, and answer frequently asked questions (FAQs). *** ## **What Are Klaviyo Abandonment Flows and Why Do They Matter?** **Abandonment flows** in Klaviyo are automated email sequences that reach out to customers who *almost* bought something but left before completing a purchase. These typically include: * **Browse Abandonment** – triggers when a known visitor views a product page but leaves without adding it to cart or purchasing. * **Cart Abandonment** – triggers when a shopper adds items to their cart but doesn’t check out. * **Checkout Abandonment** – triggers when a shopper begins the checkout process (e.g. enters their email at checkout) but doesn’t finish the purchase. Each of these flows will send a timely email (or series of emails) reminding the customer of what they viewed or left in their cart, often with a gentle nudge or incentive to return and complete the purchase. The goal is to **re-engage the shopper and recover the sale** that might otherwise be lost. This is a well-known high-ROI tactic – for example, sending an abandoned cart email with a discount can win back a significant portion of would-be drop-offs. However, **these automated emails only work if the shopper’s identity (email) is recognized** at the time they abandon. Klaviyo needs to know *who* to email – typically this means the customer is already in your Klaviyo database (e.g. they subscribed or made a past purchase) *and* is identified during their session. If the customer isn’t identified (no email captured or no cookie linking to their profile), the abandonment flow **won’t trigger at all**. For instance, if someone visits your site, enters their email for a discount code, but later returns on a different device or a cleared browser, Klaviyo might not realize it’s the same person – so an abandoned cart event could go un-emailed. **Capturing the visitor’s email** (via a sign-up pop-up or at least at checkout) is a crucial first step for any abandonment flow to work *** ## **Why Some Shoppers Don’t Get Abandonment Emails (The Identification Gap)** In today’s world, shoppers often switch devices, use private browsing, or reject cookies – which can break the chain of identity needed for Klaviyo’s flows. If a returning visitor isn’t recognized as an existing contact, **Klaviyo’s flow won’t fire at all**, meaning no abandonment email is sent. This is a common gap: you might be “dropping” a large chunk of potential follow-ups simply because the customer’s sessions appear fragmented. In fact, without advanced identity resolution, as much as *half* of returning visitors can go unrecognized by marketing tools – resulting in many would-be abandonment emails never being delivered. Consider a simple example: **Customer Bob** signs up with his email to get a 10% off coupon. A week later, Bob comes back to browse products but does so on a different browser or device; he adds something to his cart but doesn’t buy. Klaviyo sees an anonymous cart abandoner (because Bob isn’t identified in that new session), so **no cart abandonment email goes out**. The opportunity to remind Bob about his cart is lost entirely. This scenario is surprisingly common – cookies expire or get cleared, mobile in-app browsers don’t share identifiers, etc. – and it means **missed revenue** because your customer engagement system didn’t realize Bob was the same person who had given his email before. *** ## **How Upstack Data Enhances Your Abandonment Flows** Upstack Data fixes this problem by using **identity resolution** to connect those fragmented sessions and ensure the shopper *is* recognized. Upstack Data’s technology “stitches” together data from multiple visits and devices, so we know when Bob comes back even if he looks anonymous to Klaviyo. Upstack Data is especially strong at recognizing returning buyers **even months later across devices**. In practice, **Upstack Data ensures that the abandonment flow *will* trigger for Bob** by matching him to his known email/profile – in other words, we *“trigger the flow that would otherwise be left untriggered.”* This dramatically increases the reach of your abandonment emails and recaptures revenue that would have been lost. *** ## **What does Upstack Data do in Klaviyo?** We set up **“enriched” abandonment flows** in your Klaviyo account that run in **parallel** with your standard flows. Each Upstack flow acts as a safety net to catch the customers your normal flows miss. Here’s how it works: ### **Dual-Flow Setup** * For each type of abandonment (browse, cart, checkout), you keep your **standard Klaviyo flow** intact, and we create an **Upstack flow** alongside it. The Upstack flow is essentially a duplicate automation that will send the same kind of email – but only to shoppers who *didn’t* get captured by the standard flow. ### **Timing Coordination** * The Upstack-triggered flow is set to wait a short period (e.g. \~30 minutes) after the abandonment event before it sends anything. This delay gives the standard Klaviyo flow time to fire first if it’s going to. If the standard email was sent, great – **we don’t need to send another.** If the standard flow did *not* send (because the user wasn’t identified in time), then Upstack’s flow will now kick in and send the abandonment email. ### **No Duplicate Emails** * We configure the Upstack flows with proper filters so that **anyone who already received the standard Klaviyo email is excluded** from the Upstack flow. This means your customer will **never get two emails** for the same abandoned cart. Either they get the normal one, or (if that failed) they get the Upstack Data one – but **not both**. We’re only capturing the missed opportunities, not doubling up on messaging. ### **“Enriched” Identification** * Upstack Data’s script on your site works behind the scenes to identify visitors by their email or other identifiers. If someone abandons and Klaviyo didn’t recognize them initially, Upstack Data may identify them moments later (for example, by matching their device or browsing behavior to a known profile in our system). Once identified, we send that info to Klaviyo and trigger the Upstack flow email to that person. These are **emails that would have never been sent if not for Upstack’s data enrichment**. ### **Content and Branding** * You don’t have to craft entirely new emails for the Upstack flows – typically, we’ll mirror the content and timing of your existing abandonment emails (or whatever you prefer). The customer experience remains on-brand; the only difference is *more* of your shoppers will actually receive the messages. (If you haven’t set up abandonment emails yet, we’ll help you get the basic flows in place – Upstack’s team can even advise on content best practices while configuring the flows.) ## **Setting it up** The configuration of these parallel flows is handled by our team as part of your Upstack Data onboarding. We will usually ask you to **invite our team to your Klaviyo account** as a manager/admin user so we can create and test the necessary flow rules. If you prefer to do it yourself, we can walk you through it, but most clients let us take care of this step for speed and accuracy. We make sure the triggers, delays, and exclusion conditions are correct so that everything runs smoothly. Once set up, **Upstack Data’s enrichment flows run automatically in the background** – you don’t need to babysit them. They work alongside your normal Klaviyo operations without interfering in any way (you continue business as usual with campaigns, other flows, etc.). ## **What impact can you expect?** In short, significantly more recovered revenue. By “plugging the leaks” in identification, Upstack typically **increases the audience for your abandonment emails by \~30% on average**. That means about 30% more would-be buyers get an email that brings them back, which often translates to a substantial jump in monthly sales from these flows. Many brands using Upstack Data see on the order of one-third to one-half more revenue from abandonment flows compared to before. For example, one apparel brand’s standard Klaviyo flows were generating about $115k/month, and after Upstack Data they saw **an additional $95k per month\*\* from the Upstack-triggered abandonment emails – roughly an **80% increase** in recovered revenue (an exceptional case, but it shows what’s possible). In their case this was equivalent to a **90× ROI** on the Upstack product. Even if your results are more average, capturing 30% to 50% more abandoned carts can easily mean tens of thousands in recouped sales. And because Upstack Data keeps learning (every new visitor identified today is one more person we’ll recognize tomorrow), these benefits can **compound over time** as your repeat visitors grow. In summary, **Upstack Data’s enriched abandonment flows ensure no potential customer falls through the cracks**. You spend money and effort to get these shoppers to your site. Upstack Data helps make sure a faulty identification or cookie doesn’t prevent your follow-up emails from doing their job. It’s a seamless enhancement on top of Klaviyo that boosts one of your most important revenue-driving automations. *** ## **Frequently Asked Questions (FAQ)** ### **Will my customers get duplicate abandonment emails?** * **No.** Upstack’s flows are specifically configured *not* to double-email anyone. The Upstack flow only targets people who *did not* get the standard Klaviyo email, and we exclude anyone who already received the normal flow. In practice, a customer either gets your usual abandonment email or an Upstack Data one – never both for the same event. ### **How much of a lift in sales/emails will we see with Upstack Data?** * Most brands see on the order of a **30–50% increase** in the volume of abandonment emails sent (and proportional uplift in recovered revenue) after Upstack Data is implemented. This can vary based on your business – e.g. stores with lots of repeat customers or long purchase cycles tend to benefit even more over time as Upstack Data recognizes more return visitors. In one case study, a merchant’s abandonment flow revenue jumped from $115k to about $210k per month (a \~80% increase) by using Upstack Data’s enriched flows. While that was an unusually strong result, it underscores that the upside can be very large. Generally, you should expect at least a few tens of percent improvement relatively quickly, since **Upstack Data will capture those extra abandonment events that were previously invisible**. ### **Which abandonment flows does Upstack Data set up or enhance?** * We typically focus on the three core flows: **browse abandonment, cart abandonment, and checkout abandonment**. These cover the key stages where shoppers drop off. (If you have other Klaviyo flows like a post-purchase or win-back series, Upstack Data doesn’t need to modify those – we target the flows related to pre-purchase abandonment.) * We can also work alongside your **welcome flow** (for new subscribers) in the sense that Upstack Data helps identify leads, but welcome emails send normally since those don’t require a second-chance trigger. The main lift comes from the browse/cart/checkout abandon sequences. ### **Do I need to create new emails or content for the Upstack flows?** * Not necessarily. In most cases, we **reuse your existing abandonment email content and timing** – essentially cloning your email templates into the Upstack-triggered flow. This keeps messaging consistent. If you already have effective emails for cart or browse recovery, those same emails will be sent, just to more people now. If you **don’t yet have these flows set up** or lack content, we’ll help you get the basics in place (for example, a simple 1- or 2-email sequence for each abandonment type) and you can always refine the content later. Upstack Data’s primary job is making sure the *right people get the email*; the content of the email remains under your control, just as with any Klaviyo flow. ### **How will Upstack Data get added to my Klaviyo account?** * Our team will coordinate with you to do the setup. Typically, we ask you to **invite an Upstack Data specialist as a user in your Klaviyo** (with manager or admin permissions) so we can build the flow logic for you. This is usually done during your onboarding call. We’ll create the additional flows, set the triggers and filters, and test that everything works. It’s a quick process (often we complete it in the same session). If you prefer, we can also send you instructions to implement the flows yourself, but most clients find it easier to let us handle it. After setup, you can always review the flows in Klaviyo – they will be clearly labeled (e.g. “Upstack Cart Abandonment”) – and you retain full control over them. ### **Does this integration disrupt anything in my store or Klaviyo?** * **No, not at all.** Upstack Data doesn’t require you to remove or pause your existing Klaviyo flows; we **operate in the background** and only augment what’s there. Your standard flows, Shopify checkout, and other tracking all remain unchanged. Upstack Data simply adds extra data to Klaviyo and uses Klaviyo’s normal flow mechanism to send more emails to those who qualify. There’s no impact on site performance either – the identification happens via a lightweight script on your site and server-side matching. In short, it’s a seamless addition, and if for any reason you disabled Upstack Data, your original flows would continue as they were. ### **What if we haven’t set up Klaviyo flows (or we use a different email platform)?** * You’ll get the most value if you are using Klaviyo’s abandonment flows, since that’s what Upstack Data ties into. If you’re new to Klaviyo or just migrating, we recommend first creating the basic browse, cart, and checkout flow in Klaviyo (even a simple one-email flow to start). Our team can guide you on this. Once those flows exist (even if inactive), **let us know and we will configure the advanced Upstack Data portions** for you. * Currently, Upstack Data’s enhanced flows are purpose-built for Klaviyo on Shopify. We do integrate with many marketing platforms, but the out-of-the-box abandonment email solution is via Klaviyo. If you use a different email tool, Upstack Data’s identity resolution will still improve your data (which could help your other platform in theory), but we may not be able to set up parallel flows automatically as we do with Klaviyo. Feel free to discuss your setup with us – we can often find a workaround or at least you’ll know what benefits to expect. ### **Will Upstack Data affect my email deliverability or subscriber list?** * **No** – Upstack Datadoes **not** add any new contacts who weren’t already in your system. We only target people who have engaged with your site and provided their email (or are existing customers). In other words, we’re not injecting third-party emails or doing cold outreach. We’re simply making sure your **own leads and customers** get the emails they *should* be getting. In fact, this approach is healthier than some alternatives where third-party data is used: one brand we onboarded had been feeding purchased contact lists into Klaviyo (via another tool), which hurt their deliverability (spam complaints, etc.). Upstack Data helped them remove that practice and instead capture more revenue *organically* by emailing *real visitors* who showed intent – leading to better deliverability and engagement. So you should see **no negative impact on deliverability** since we stick to your opt-in audience. *** These illustrate the typical setup and benefits of Upstack Data’s enriched abandonment flows, as well as real-world results seen by merchants. This feature is a key driver of ROI for many Upstack Data clients, and we want to ensure you’re fully set up to take advantage of it. By closing the gaps in who gets your abandonment emails, **Upstack Data helps you convert more sales on autopilot** – leveraging the customer interest you already generated. It’s a “low hanging fruit” win for your email marketing, and we’re here to help you make the most of it. Enjoy those recovered carts and happy emailing! 🚀 *** If you have any other questions about Upstack Data’s Klaviyo abandonment flow integration, please reach out to our support team. For further reading or specific examples, please refer to the Upstack Data knowledge base or contact us for detailed case studies. **Sources:** Upstack Data internal case studies, onboarding guides, and FAQ documentation have informed the above (e.g. Perfect White Tee Klaviyo flow case study, and Upstack Data Customer FAQ docs. # Connect Facebook Ads Source: https://docs.upstackdata.com/sources/facebook-ads Connect your Facebook Ads account as a source to import campaign spend, impressions, clicks, and performance metrics into Upstack Data. **Data direction:** This is a **source** — data flows **into** Upstack from this platform for analytics, reporting, and enrichment. Connecting Facebook Ads as a source brings ad spend and campaign performance data into Upstack, enabling cost-per-acquisition (CPA) reporting, return on ad spend (ROAS) calculations, and blended attribution across paid and organic channels. ## Prerequisites **Prerequisites:** * An Upstack Data account ([sign up for free](https://app.upstackdata.com)) * Access to your workspace in the Upstack dashboard You'll also need: * A **Meta Business Manager** account with admin access * At least one **Facebook Ads account** with active or historical campaigns * The **Ad Account ID** you want to connect (found in Meta Business Settings → Ad Accounts) This is a **source** connection — it pulls cost and performance data **into** Upstack. To send conversion events **to** Meta, see the [Meta CAPI destination guide](/destinations/meta-capi). ## Setup In the Upstack dashboard, navigate to **Integrations → Sources** and click **Connect Facebook Ads**. Click **Sign in with Meta** to begin the OAuth flow. Log in to your Meta Business Manager account and grant Upstack permission to read your advertising data. Upstack requests read-only permissions: `ads_read` and `read_insights`. No permissions to create, modify, or spend on campaigns are requested. After authentication, Upstack displays all ad accounts associated with your Meta Business Manager. Select the account(s) you want to sync. You can connect multiple ad accounts if you manage separate accounts for different brands or regions. Each account appears as a separate source in the Upstack dashboard. **Select the correct accounts.** Upstack imports spend data for the selected accounts and uses it for ROAS calculations. If you connect the wrong account, your cost metrics won't match your conversion data. Review the data access summary and click **Confirm**. Upstack immediately begins syncing your ad account data. The initial sync imports the last 90 days of campaign performance data. After the initial sync, Upstack pulls updated metrics every 6 hours. ## What Data Flows In | Metric | Description | Granularity | | --------------- | ----------------------------------------- | ------------------ | | **Spend** | Total amount spent per campaign/ad set/ad | Daily | | **Impressions** | Number of times ads were shown | Daily | | **Clicks** | Link clicks on ads | Daily | | **CPM** | Cost per thousand impressions | Daily (calculated) | | **CPC** | Cost per click | Daily (calculated) | | **CTR** | Click-through rate | Daily (calculated) | | **Reach** | Unique accounts that saw ads | Daily | ### Campaign Structure Upstack also imports the full campaign hierarchy: * **Campaigns** — name, objective, status, budget * **Ad Sets** — name, targeting, placement, bid strategy * **Ads** — name, creative ID, status This structure enables drill-down reporting from campaign-level ROAS down to individual ad performance inside the Upstack dashboard. Upstack syncs data at the **ad level** and aggregates up. This means you can report at any level of the campaign hierarchy — campaign, ad set, or ad — without any additional configuration. ## You'll Know It's Working When... **Verification checklist:** Complete all items below to confirm your setup is working correctly. If any check fails, see the troubleshooting section below or the relevant [troubleshooting guide](/troubleshooting/events-not-reaching-destination). * [ ] Your Facebook Ads source shows **Connected** status in the Upstack dashboard under **Integrations → Sources** * [ ] Campaign data appears in the **Sources → Facebook Ads** detail page within 30 minutes of initial connection * [ ] Spend metrics are visible in **Analytics → Attribution** reports alongside your conversion data * [ ] ROAS calculations populate for campaigns that have both spend data and attributed conversions ## Troubleshooting **Check the sync status** in **Integrations → Sources → Facebook Ads**. The initial 90-day backfill can take up to 30 minutes depending on the volume of campaigns. If no data appears after 1 hour: 1. Verify the connected ad account has campaigns with spend in the last 90 days 2. Check that your Meta Business Manager token hasn't been revoked (go to **Meta Business Settings → Users → System Users** and verify the Upstack integration is still authorized) 3. Try disconnecting and reconnecting the source Small discrepancies (under 5%) between Upstack and Meta Ads Manager are normal due to timezone differences and Meta's post-attribution adjustments. **Common causes of larger discrepancies:** * **Timezone mismatch** — Upstack normalizes spend to UTC. If your Meta account uses a different timezone, daily totals may shift between days. * **Attribution window differences** — Upstack imports raw spend (actual dollars spent), not attributed spend. If you're comparing to a Meta report using attributed metrics, the totals will differ. * **Multiple ad accounts** — ensure you've connected all ad accounts that contribute spend for your store. Meta OAuth tokens can expire or be revoked if your Business Manager permissions change. If the source status shows an error: 1. Go to **Integrations → Sources → Facebook Ads** 2. Click **Reconnect** to re-authenticate with Meta 3. Re-select your ad accounts and confirm Data sync resumes automatically after reconnection. Any data missed during the disconnection is backfilled during the next sync cycle. *** **Still stuck?** Contact [support@upstackdata.com](mailto:support@upstackdata.com) with your Pixel ID and a description of the issue. We typically respond within a few hours. ## Related Send conversion events **to** Meta — the outbound counterpart to this inbound source. How Upstack blends ad spend data with conversion events to calculate ROAS and CPA. Import Google Ads spend data to get a complete picture of your paid media performance. Browse all available sources and destinations. # Connect Google Ads Source: https://docs.upstackdata.com/sources/google-ads Connect your Google Ads account as a source to import campaign spend, clicks, impressions, and performance metrics into Upstack Data. **Data direction:** This is a **source** — data flows **into** Upstack from this platform for analytics, reporting, and enrichment. Connecting Google Ads as a source brings campaign cost data into Upstack, enabling cost-per-acquisition (CPA) reporting, return on ad spend (ROAS) calculations, and unified attribution across Google Search, Shopping, Display, and YouTube campaigns. ## Prerequisites **Prerequisites:** * An Upstack Data account ([sign up for free](https://app.upstackdata.com)) * Access to your workspace in the Upstack dashboard You'll also need: * A **Google Ads account** with active or historical campaigns * **Admin** or **Standard** access to the Google Ads account you want to connect * If you use a **Google Ads Manager Account** (MCC), you'll need access to the specific sub-accounts you want to sync ## Setup In the Upstack dashboard, navigate to **Integrations → Sources** and click **Connect Google Ads**. Click **Sign in with Google** to begin the OAuth flow. Log in with the Google account that has access to your Google Ads account and grant Upstack permission to read your advertising data. Upstack requests read-only access to your Google Ads data. No permissions to create, modify, or spend on campaigns are requested. After authentication, Upstack lists all Google Ads accounts (including sub-accounts under an MCC) accessible to your Google account. Select the account(s) you want to sync. Each selected account appears as a separate data source in the Upstack dashboard with its own sync status and metrics. **Match accounts to your store.** Select only the Google Ads accounts that drive traffic to the Shopify store connected to Upstack. Connecting unrelated accounts will skew your ROAS and CPA metrics. Review the data access summary and click **Confirm**. Upstack begins syncing your Google Ads data immediately. The initial sync imports the last 90 days of campaign performance data. After the initial sync, Upstack pulls updated metrics every 6 hours. ## What Data Flows In | Metric | Description | Granularity | | --------------- | -------------------------------------------- | ------------------ | | **Spend** | Total cost per campaign/ad group/ad | Daily | | **Clicks** | Total clicks on ads | Daily | | **Impressions** | Number of times ads were shown | Daily | | **Conversions** | Google-reported conversions (for comparison) | Daily | | **CPC** | Cost per click | Daily (calculated) | | **CPM** | Cost per thousand impressions | Daily (calculated) | | **CTR** | Click-through rate | Daily (calculated) | ### Campaign Structure Upstack imports the full Google Ads hierarchy: * **Campaigns** — name, type (Search, Shopping, Display, Video, Performance Max), status, budget * **Ad Groups** — name, targeting, bid strategy * **Ads** — name, type, status Google Ads data is synced at the **ad group level** and aggregated up. Performance Max campaigns are reported at the campaign level since Google doesn't expose ad group details for pMax. ### Click ID Tracking When visitors arrive at your store from Google Ads, the `gclid` (Google Click ID) parameter is captured by the Upstack Pixel and stored in the visitor's session. This `gclid` links the ad click to any subsequent conversion events, enabling deterministic click-to-conversion attribution. ## You'll Know It's Working When... **Verification checklist:** Complete all items below to confirm your setup is working correctly. If any check fails, see the troubleshooting section below or the relevant [troubleshooting guide](/troubleshooting/events-not-reaching-destination). * [ ] Your Google Ads source shows **Connected** status in the Upstack dashboard under **Integrations → Sources** * [ ] Campaign data appears in the **Sources → Google Ads** detail page within 30 minutes of initial connection * [ ] Spend metrics are visible in **Analytics → Attribution** reports alongside your conversion data * [ ] ROAS calculations populate for campaigns that have both spend data and attributed conversions ## Troubleshooting **Check the sync status** in **Integrations → Sources → Google Ads**. The initial 90-day backfill can take up to 30 minutes. If no data appears after 1 hour: 1. Verify the connected account has campaigns with spend in the last 90 days 2. Confirm you selected the correct account (check the Account ID matches what you see in Google Ads) 3. If using an MCC, ensure you selected the sub-account, not the manager account itself 4. Try disconnecting and reconnecting the source Small discrepancies (under 5%) are normal due to timezone normalization and Google's post-click adjustments. **Common causes of larger discrepancies:** * **Timezone mismatch** — Upstack normalizes spend to UTC. Google Ads accounts may use a different timezone, causing daily totals to shift between days. * **Currency conversion** — if your Google Ads account bills in a different currency than your Shopify store, exchange rate timing can cause minor differences. * **Invalid clicks** — Google periodically removes invalid click charges. These adjustments may not be reflected in Upstack's data until the next sync cycle. Google OAuth tokens can expire if you change your Google account password, revoke third-party access, or if the token's refresh cycle fails. To fix: 1. Go to **Integrations → Sources → Google Ads** 2. Click **Reconnect** to re-authenticate with Google 3. Re-select your ad accounts and confirm Data sync resumes immediately. Any data missed during the disconnection is backfilled during the next sync. *** **Still stuck?** Contact [support@upstackdata.com](mailto:support@upstackdata.com) with your Pixel ID and a description of the issue. We typically respond within a few hours. ## Related Send server-side conversion events to GA4 — the outbound counterpart to this inbound source. How Upstack blends ad spend data with conversion events to calculate ROAS and CPA. Import Facebook Ads spend data for a complete view of paid media performance. Browse all available sources and destinations. # Sources Source: https://docs.upstackdata.com/sources/overview Connect the platforms that feed data into Upstack Data for analytics, attribution, and activation. Sources are integrations that bring data **into** Upstack Data. They provide the raw signals — page views, add-to-carts, purchases, ad spend, campaign metadata — that power everything from real-time dashboards to multi-touch attribution. ## How Sources Work Each source connects to an external platform and pulls (or receives) data on your behalf: * **Shopify** streams storefront events via the browser pixel and receives order/product updates through webhooks. This is your primary event source. * **Ad platform sources** (Facebook Ads, Google Ads, TikTok) sync campaign structure, spend, and performance metrics on a recurring schedule so you can blend cost data with conversion data inside Upstack. Every Upstack account starts with Shopify as its first source. Ad platform sources are optional and unlock cost-per-acquisition reporting and ROAS calculations. ## Available Sources Storefront events, orders, products, and customer data via pixel and webhooks. **Required** — this is the foundation of your tracking. Campaign structure, ad spend, and performance metrics from your Facebook and Instagram ad accounts. Campaign structure, ad spend, and performance metrics from your Google Ads account. Campaign structure, ad spend, and performance metrics from your TikTok Ads account. Customer-configured costs including COGS overrides, handling, fulfillment, fixed costs, and OPEX for margin calculations. ## What Happens After Connection Once a source is connected, Upstack immediately begins ingesting data: 1. **Events are normalized** into a consistent schema regardless of which source produced them. 2. **Identity resolution** links anonymous visitor sessions to known customer profiles across sources. 3. **Data becomes queryable** in your dashboard and available for forwarding to any configured destination. You can monitor ingestion health and event volume for each source from the **Sources** tab in your Upstack dashboard. # Connect Shopify Source: https://docs.upstackdata.com/sources/shopify Connect your Shopify store as a source to capture storefront events, orders, products, and customer data via the Upstack Pixel and webhooks. **Data direction:** This is a **source** — data flows **into** Upstack from this platform for analytics, reporting, and enrichment. Shopify is your primary data source. Once connected, Upstack installs a lightweight pixel on your storefront to capture real-time visitor events and registers webhooks to receive order, product, and customer updates directly from Shopify's backend. ## Prerequisites **Prerequisites:** * An Upstack Data account ([sign up for free](https://app.upstackdata.com)) * Access to your workspace in the Upstack dashboard You'll also need: * An **active Shopify store** on any plan (Basic, Shopify, Advanced, or Plus) * **Store owner** or **staff** access with permission to install apps ## Setup Visit the [Shopify App Store listing for Upstack Data](https://apps.shopify.com) and click **Install**. Alternatively, in the Upstack dashboard navigate to **Integrations → Sources** and click **Connect Shopify** to be redirected to the Shopify install flow. If your organization manages multiple Shopify stores, you'll repeat this process for each store. Each store gets its own Pixel ID and appears as a separate source in your Upstack dashboard. Shopify prompts you to review the permissions Upstack requires: * **Read products** — to sync your product catalog for content ID matching * **Read orders** — to ingest purchase events and revenue data * **Read customers** — to enrich identity resolution with customer profiles * **Read and write script tags** — to install the Upstack tracking pixel on your storefront Click **Install app** to grant access. Upstack immediately begins configuring your store connection. After installation, navigate to **Settings → Pixel** in the Upstack dashboard. You should see your Shopify store listed with a **Connected** status and a Pixel ID assigned. Open your Shopify storefront in a browser, browse a product page, and check the **Live Event Stream** in the Upstack dashboard. Events should appear within 60 seconds. ## What Data Is Ingested Shopify provides three categories of data to Upstack: | Data Type | Source | Frequency | Key Fields | | --------------------- | ------------------- | -------------- | ----------------------------------------------------------------- | | **Storefront events** | Browser pixel | Real-time | Page views, product views, add-to-cart, checkout, purchase | | **Order data** | Webhooks | Near real-time | Order ID, line items, revenue, discounts, shipping, customer info | | **Product catalog** | API sync | Every 6 hours | Product ID, title, variants, price, images, inventory status | | **Customer profiles** | API sync + webhooks | Near real-time | Email, name, address, order history, tags | Upstack also performs a **historical backfill** of your last 90 days of orders and customer data during initial setup. This gives you attribution data from day one without waiting for new events to accumulate. ## You'll Know It's Working When... **Verification checklist:** Complete all items below to confirm your setup is working correctly. If any check fails, see the troubleshooting section below or the relevant [troubleshooting guide](/troubleshooting/events-not-reaching-destination). * [ ] Your Shopify store shows **Connected** status in the Upstack dashboard under **Integrations → Sources** * [ ] A Pixel ID is assigned and visible under **Settings → Pixel** * [ ] Browsing your storefront generates `PageView` events in the **Live Event Stream** within 60 seconds * [ ] A test order generates a `Purchase` event with correct revenue and order details ## Troubleshooting **Check that the pixel is installed correctly** by inspecting your storefront's page source. Search for `upstack` in the HTML — you should see the pixel script tag in the `` section. **Steps to fix:** 1. Go to **Settings → Pixel** in the Upstack dashboard and confirm the status is **Connected** 2. Open your storefront in an incognito/private browser window (extensions and ad blockers can interfere) 3. Browse a product page, then check the Live Event Stream 4. If still no events, go to your Shopify admin → **Settings → Customer events** and verify the Upstack pixel is listed and enabled If the pixel is missing from Shopify's customer events, try uninstalling and reinstalling the Upstack app. Order data arrives via Shopify webhooks. If orders are missing: 1. Check **Integrations → Sources → Shopify** in the Upstack dashboard for any webhook error indicators 2. Verify your Shopify store hasn't hit webhook rate limits (common during flash sales) 3. Confirm the Upstack app still has **Read orders** permission in your Shopify admin → **Settings → Apps and sales channels → Upstack Data** Webhooks that fail are retried automatically by Shopify for up to 48 hours. If data is delayed but eventually arrives, this is normal behavior during high-traffic periods. The initial backfill of historical orders and customers can take up to 2 hours depending on your store's volume. Check the **Sources** tab for a progress indicator. If backfill hasn't completed after 4 hours, contact [support@upstackdata.com](mailto:support@upstackdata.com) with your Pixel ID. *** **Still stuck?** Contact [support@upstackdata.com](mailto:support@upstackdata.com) with your Pixel ID and a description of the issue. We typically respond within a few hours. ## Related Complete reference for automatically captured Shopify events. How Upstack uses Shopify webhooks for real-time order and customer updates. Step-by-step guide to confirm your Shopify source is working end-to-end. Learn how the Upstack Pixel captures events and why server-side delivery matters. # Shopify Automatic Event Tracking Source: https://docs.upstackdata.com/sources/shopify-automatic-tracking How Upstack Data automatically captures all customer journey events from your Shopify store — page views, add to cart, checkout, and purchases with no config. When you install Upstack on your Shopify store, we automatically capture customer journey events without any additional configuration. This document explains what events are tracked and when they fire. No manual setup required — all standard e-commerce events are captured automatically once the Upstack app is installed. ## Tracking Methods Upstack captures events through two complementary methods: ### Customer Events API (Checkout) Shopify's official [Customer Events API](https://shopify.dev/docs/api/customer-events) provides real-time checkout events. This is the most reliable method for conversion tracking and captures: * Checkout started, progressed, and completed * Payment information entered * Shipping information entered * Cart interactions during checkout ### URL-Based Detection (Storefront) For storefront browsing, Upstack automatically detects page types based on URL patterns: | URL Pattern | Event Fired | | ---------------- | --------------- | | `/products/*` | `view_content` | | `/collections/*` | `view_category` | | `/cart` | `view_cart` | | `/search?*` | `search` | No configuration required — events fire automatically when visitors browse these pages. *** ## Event Mapping The following table shows all automatically captured events: | Customer Action | Upstack Event | Data Captured | | ----------------------- | --------------------------- | ------------------------------------------------- | | Views any page | `page_view` | URL, title, referrer | | Views a product page | `view_content` | Product ID, name, price, variant, URL | | Views a collection | `view_category` | Collection handle, URL | | Searches the store | `search` | Search query, results count | | Views their cart | `view_cart` | All cart items, cart value, currency | | Adds item to cart | `add_to_cart` | Product ID, name, price, quantity, variant | | Removes item from cart | `product_removed_from_cart` | Product ID, quantity removed | | Starts checkout | `initiate_checkout` | Cart items, value, currency | | Enters contact info | `add_shipping_info` | Email, phone (+ triggers identity capture) | | Enters shipping address | `add_shipping_info` | Address fields (+ triggers identity capture) | | Selects shipping method | `add_shipping_info` | Shipping tier selection | | Enters payment info | `add_payment_info` | Payment method type (no card data) | | Completes order | `purchase` | Full order: items, value, tax, shipping, customer | *** ## Data Payloads The JSON examples below show **destination wire format** — what Meta CAPI, TikTok, and other destinations receive after Upstack transforms the event. Event names are converted to PascalCase (e.g., `AddToCart`) for destination compatibility. When using the SDK directly, always use **snake\_case** (e.g., `add_to_cart`). ### Product View (`view_content`) Automatically captured when a visitor views any `/products/*` page: ```json theme={null} // Destination wire format (what Meta CAPI receives) { "event_name": "ViewContent", "event_time": "2026-02-18T14:31:12.000Z", "event_source_url": "https://example-store.com/products/classic-tee", "user_data": { "client_ip_address": "203.0.113.42", "client_user_agent": "Mozilla/5.0...", "fbp": "fb.1.1708271400.XyZ789" }, "custom_data": { "content_ids": ["8012345678"], "content_type": "product", "content_name": "Classic Cotton Tee", "value": 34.99, "currency": "USD" } } ``` ### Add to Cart (`add_to_cart`) Captured when a visitor adds an item to their cart: ```json theme={null} // Destination wire format (what Meta CAPI receives) { "event_name": "AddToCart", "event_time": "2026-02-18T14:32:05.000Z", "event_source_url": "https://example-store.com/products/classic-tee", "user_data": { "client_ip_address": "203.0.113.42", "client_user_agent": "Mozilla/5.0...", "fbp": "fb.1.1708271400.XyZ789" }, "custom_data": { "content_ids": ["8012345678"], "content_type": "product", "content_name": "Classic Cotton Tee", "value": 34.99, "currency": "USD", "num_items": 1 } } ``` ### Checkout Started (`initiate_checkout`) Captured when checkout begins: ```json theme={null} // Destination wire format (what Meta CAPI receives) { "event_name": "InitiateCheckout", "event_time": "2026-02-18T14:33:45.000Z", "event_source_url": "https://example-store.com/checkout", "user_data": { "client_ip_address": "203.0.113.42", "client_user_agent": "Mozilla/5.0...", "fbc": "fb.1.1708271400.AbC123", "fbp": "fb.1.1708271400.XyZ789" }, "custom_data": { "content_ids": ["8012345678", "8012345679"], "content_type": "product", "value": 89.98, "currency": "USD", "num_items": 2 } } ``` ### Purchase (`purchase`) Captured when an order is completed: ```json theme={null} // Destination wire format (what Meta CAPI receives) { "event_name": "Purchase", "event_time": "2026-02-18T14:35:20.000Z", "event_source_url": "https://example-store.com/thank-you", "user_data": { "em": "a1b2c3d4e5f6...hashed", "ph": "f6e5d4c3b2a1...hashed", "client_ip_address": "203.0.113.42", "client_user_agent": "Mozilla/5.0...", "fbc": "fb.1.1708271400.AbC123", "fbp": "fb.1.1708271400.XyZ789", "external_id": "cust_12345" }, "custom_data": { "content_ids": ["8012345678", "8012345679"], "content_type": "product", "value": 89.98, "currency": "USD", "order_id": "#1042", "num_items": 2 } } ``` *** ## Identity Capture When customers enter contact information during checkout, Upstack automatically: 1. **Captures email and phone** from the contact info step 2. **Associates the session** with the customer identity 3. **Persists identity** for cross-session attribution This happens when customers enter contact or address information during checkout. No additional configuration is required. Identity data enables cross-device attribution and improves match quality with ad platforms like Meta and TikTok. *** ## Consent Handling Upstack respects Shopify's customer consent settings: * If **analytics consent** is not granted, tracking is limited to essential events * **Marketing consent** affects which destinations receive forwarded events * Consent state is captured and included with each event ```json theme={null} { "consent": { "analytics": true, "marketing": false, "preferences": true } } ``` *** ## What's NOT Automatically Tracked The following events require manual implementation: | Event | Why Not Automatic | How to Track | | ------------------ | ------------------------- | -------------------------------------------------------------------------------------------------- | | Product list views | No standard Shopify event | Call `_upstack('track', 'view_item_list', {...})` | | Newsletter signups | Form depends on theme | Use [Form Capture Integrations](/guides/integrations/form-capture-integrations) or manual tracking | | Wishlist actions | Third-party apps vary | Call `_upstack('track', 'add_to_wishlist', {...})` | | Custom conversions | Business-specific | Define and track [custom events](/pixel/custom-events) | ## Related Documentation Full reference with JavaScript snippets for manual event tracking. Complete API reference for the Upstack JavaScript SDK. Reference for item arrays, customer data, and auto-captured fields. Track custom interactions beyond the standard taxonomy. Automatic lead capture from Klaviyo, Postscript, and more. Initial setup guide for connecting your Shopify store. # Shopify Webhooks Source: https://docs.upstackdata.com/sources/shopify-webhooks How Upstack uses Shopify webhooks for real-time order, customer, and product updates — which webhooks are registered, what they do, and how to verify they're working. **Data direction:** This is a **source** — data flows **into** Upstack from this platform for analytics, reporting, and enrichment. Shopify webhooks deliver real-time notifications to Upstack whenever data changes in your store — new orders, customer updates, product modifications, and app lifecycle events. This ensures your Upstack dashboard reflects changes within seconds instead of waiting for periodic API syncs. ## Registered Webhooks When you install the Upstack Data app, the following webhooks are automatically registered with your Shopify store: | Webhook Topic | Fires When | What Upstack Does | | ------------------ | ----------------------------------------------------------------- | ---------------------------------------------------------------- | | `orders/create` | A new order is placed | Ingests order data for purchase attribution and revenue tracking | | `orders/updated` | An existing order is modified (fulfillment, refund, cancellation) | Updates attributed revenue and order status | | `orders/cancelled` | An order is cancelled | Marks the conversion as cancelled and adjusts revenue | | `customers/create` | A new customer account is created | Adds the customer to the identity graph | | `customers/update` | Customer profile changes (email, address, tags) | Merges updated data into the existing identity profile | | `products/create` | A new product is published | Updates the product catalog for content ID matching | | `products/update` | A product is modified (price, title, variants) | Syncs product changes for accurate event parameters | | `app/uninstalled` | The Upstack app is removed from the store | Deactivates the source and stops data collection | Upstack does not register webhooks for draft orders, inventory, or fulfillment events. These may be added in future releases based on customer demand. ## How Webhook Processing Works When Shopify fires a webhook, the following pipeline executes: 1. **Receive** — Upstack's ingestion endpoint receives the webhook payload and validates the HMAC signature to confirm it originated from Shopify. 2. **Normalize** — The raw Shopify payload is transformed into Upstack's internal event schema. For example, an `orders/create` webhook becomes a `Purchase` event with standardized fields. 3. **Enrich** — The event is passed through identity resolution. If the order includes a customer email, Upstack links it to any existing anonymous sessions from that visitor. 4. **Store and forward** — The normalized event is stored for analytics and simultaneously queued for delivery to any active destinations. **HMAC validation is mandatory.** Every incoming webhook is verified against your store's shared secret. If validation fails, the payload is rejected and logged as a security event. You do not need to configure this — it's handled automatically during app installation. ## Retry and Reliability Shopify's webhook infrastructure includes automatic retry logic: * If Upstack's endpoint returns a non-2xx response, Shopify retries the webhook up to **19 times** over a 48-hour period with exponential backoff. * If all retries fail, Shopify marks the webhook as failed. Upstack's daily reconciliation sync catches these gaps by pulling any missing orders via the Shopify API. * Webhooks that consistently fail may cause Shopify to automatically remove the webhook registration. If this happens, Upstack detects the removal and re-registers the webhook. This dual approach (webhooks + daily reconciliation) ensures no data is permanently lost, even during extended outages or high-traffic events like flash sales. ## Verifying Webhooks Are Working Navigate to **Integrations → Sources → Shopify**. The source detail page shows a **Webhook Health** indicator: * **Healthy** (green) — webhooks are being received and processed normally * **Delayed** (yellow) — some webhooks have failed but retries are in progress * **Failing** (red) — webhooks are consistently failing; check Shopify admin for details Place a test order on your Shopify store (you can use Shopify's **Bogus Gateway** for free test transactions). Within 30 seconds, the order should appear in the Upstack **Live Event Stream** as a `Purchase` event. In your Shopify admin, go to **Settings → Notifications → Webhooks**. Shopify shows recent webhook deliveries with status codes. Look for deliveries to Upstack's endpoint — they should all show `200` responses. Shopify's webhook log in the admin panel shows the last 30 days of delivery attempts. Use this to diagnose intermittent failures. ## Troubleshooting If Shopify reports webhook delivery failures to Upstack's endpoint: 1. Check the [Upstack status page](https://status.upstackdata.com) for any ongoing incidents 2. Verify your Shopify store hasn't recently changed its domain (this can invalidate webhook registrations) 3. In the Upstack dashboard, go to **Integrations → Sources → Shopify** and click **Reconnect** to re-register webhooks Failed webhooks are retried by Shopify for up to 48 hours, and Upstack's daily reconciliation sync fills any remaining gaps. Brief delays (under 5 minutes) are normal during high-traffic periods. Shopify queues webhooks and delivers them in order, which can introduce latency during peak times like Black Friday. If delays consistently exceed 30 minutes, check whether your Shopify store is near its API rate limit. High-volume stores on the Basic plan may experience more webhook queuing than stores on Advanced or Plus plans. Shopify automatically removes webhook registrations if the receiving endpoint returns errors for an extended period. Upstack monitors for this and re-registers webhooks automatically. If you notice a gap in data, check **Integrations → Sources → Shopify** for a "Webhooks re-registered" notification. Any missed data during the gap is recovered during the next daily reconciliation sync. *** **Still stuck?** Contact [support@upstackdata.com](mailto:support@upstackdata.com) with your Pixel ID and a description of the issue. We typically respond within a few hours. ## Related Step-by-step setup guide for connecting your Shopify store. End-to-end diagnostic guide when source data stops flowing into Upstack. How Shopify webhook events map to Upstack's standard event taxonomy. # TikTok Ads source Source: https://docs.upstackdata.com/sources/tiktok Connect your TikTok Ads account to Upstack to import ad spend, campaign structure, and performance data for unified reporting. **Data direction:** This is a **source** — data flows **into** Upstack from this platform for analytics, reporting, and enrichment. Connecting TikTok Ads as a source brings ad spend and campaign performance data into Upstack, enabling cost-per-acquisition (CPA) reporting, return on ad spend (ROAS) calculations, and blended attribution alongside your other paid channels. This is a **source** connection — it pulls cost and performance data **into** Upstack for reporting. To send conversion events **to** TikTok for ad optimization, see the [TikTok Events API destination](/destinations/tiktok). ## Prerequisites **Prerequisites:** * An Upstack Data account ([sign up for free](https://app.upstackdata.com)) * Access to your workspace in the Upstack dashboard You'll also need: * A **TikTok Business Center** account with admin access * At least one **TikTok Ads account** with active or historical campaigns * The **Advertiser ID** for the ad account you want to connect (found in TikTok Ads Manager → Account Info) ## What This Source Provides | Metric | Description | Granularity | | --------------- | -------------------------------------------- | ------------------ | | **Spend** | Total cost per campaign / ad group / ad | Daily | | **Impressions** | Number of times ads were shown | Daily | | **Clicks** | Total clicks on ads | Daily | | **CPM** | Cost per thousand impressions | Daily (calculated) | | **CPC** | Cost per click | Daily (calculated) | | **CTR** | Click-through rate | Daily (calculated) | | **Conversions** | TikTok-reported conversions (for comparison) | Daily | ### Campaign Structure Upstack imports the full TikTok Ads hierarchy: * **Campaigns** — name, objective, status, budget * **Ad Groups** — name, targeting, placement, bid strategy * **Ads** — name, creative, status This structure powers drill-down reporting from campaign-level ROAS down to individual ad performance inside the Upstack dashboard. ### Click ID Tracking When visitors arrive at your store from a TikTok ad, the `ttclid` (TikTok Click ID) parameter is captured by the Upstack Pixel and stored in the visitor's session. This `ttclid` links the ad click to subsequent conversion events for deterministic click-to-conversion attribution. ## Why It Matters The TikTok Ads source pairs with the [TikTok Events API destination](/destinations/tiktok) to give you a full closed-loop view: * **The destination** sends purchases, add-to-carts, and checkouts **to** TikTok so its algorithm can optimize ad delivery. * **The source** pulls the resulting **spend, impression, and click data back** into Upstack so you can calculate true ROAS, compare TikTok performance to other channels, and report on blended attribution. Without the source connected, you'll see TikTok-attributed conversions in Upstack but no cost data to divide them against. ## Setup In the Upstack dashboard, navigate to **Integrations → Sources** and click **Connect TikTok Ads**. Follow the prompts to authorize Upstack to read data from your TikTok Business Center. Upstack requests read-only access to your TikTok Ads data. No permissions to create, modify, or spend on campaigns are requested. After connecting, Upstack lists all ad accounts accessible from your TikTok Business Center. Select the account(s) you want to sync. Each selected account appears as a separate data source in the Upstack dashboard with its own sync status and metrics. **Match accounts to your store.** Select only the TikTok Ads accounts that drive traffic to the Shopify store connected to Upstack. Connecting unrelated accounts will skew your ROAS and CPA metrics. Review the data access summary and click **Confirm**. Upstack begins syncing your TikTok Ads data immediately. The initial sync imports the last 90 days of campaign performance data. After the initial sync, Upstack pulls updated metrics every 6 hours. ## You'll Know It's Working When... **Verification checklist:** Complete all items below to confirm your setup is working correctly. If any check fails, see the troubleshooting section below or the relevant [troubleshooting guide](/troubleshooting/events-not-reaching-destination). * [ ] Your TikTok Ads source shows **Connected** status in the Upstack dashboard under **Integrations → Sources** * [ ] Campaign data appears in the **Sources → TikTok Ads** detail page within 30 minutes of initial connection * [ ] Spend metrics are visible in **Analytics → Attribution** reports alongside your conversion data * [ ] ROAS calculations populate for campaigns that have both spend data and attributed conversions ## Troubleshooting **Check the sync status** in **Integrations → Sources → TikTok Ads**. The initial 90-day backfill can take up to 30 minutes depending on the volume of campaigns. If no data appears after 1 hour: 1. Verify the connected ad account has campaigns with spend in the last 90 days 2. Confirm you selected the correct account (check the Advertiser ID matches what you see in TikTok Ads Manager) 3. Try disconnecting and reconnecting the source Small discrepancies (under 5%) between Upstack and TikTok Ads Manager are normal due to timezone differences and TikTok's post-attribution adjustments. **Common causes of larger discrepancies:** * **Timezone mismatch** — Upstack normalizes spend to UTC. If your TikTok account uses a different timezone, daily totals may shift between days. * **Currency conversion** — if your TikTok Ads account bills in a different currency than your Shopify store, exchange rate timing can cause minor differences. * **Multiple ad accounts** — ensure you've connected all ad accounts that contribute spend for your store. If the source status shows an error, the connection to TikTok may need to be re-established. To fix: 1. Go to **Integrations → Sources → TikTok Ads** 2. Click **Reconnect** 3. Re-select your ad accounts and confirm Data sync resumes immediately. Any data missed during the disconnection is backfilled during the next sync cycle. *** **Still stuck?** Contact [support@upstackdata.com](mailto:support@upstackdata.com) with your Pixel ID and a description of the issue. We typically respond within a few hours. ## Related Send conversion events **to** TikTok — the outbound counterpart to this inbound source. Step-by-step walkthrough for setting up TikTok end-to-end in Upstack. Import Facebook Ads spend data for a complete view of paid social performance. How Upstack blends ad spend data with conversion events to calculate ROAS and CPA. # Support Source: https://docs.upstackdata.com/support Contact Upstack Data support — chat with an agent via Intercom, email support@upstackdata.com, or browse troubleshooting guides for events, destinations, and attribution issues. We're here to help you get the most out of Upstack Data. Whether you're stuck on installation, debugging events, or planning a complex destination setup, our support team is ready to assist. ## Get help now The fastest way to reach us is in-app chat. Click below to start a conversation with the support team. Prefer email? Reach us at [support@upstackdata.com](mailto:support@upstackdata.com). ## Support channels Open the chat widget to talk with a support agent. Most messages get a response within a few hours during business hours. For longer questions, account issues, or screenshots, email us at [support@upstackdata.com](mailto:support@upstackdata.com). Browse troubleshooting guides for the most common issues. Step-by-step guides for installation, destinations, and platform concepts. ## Support hours Our support team is available Monday through Friday, 9am–6pm ET. Outside business hours, you can still send a message — we'll respond first thing the next business day. For urgent issues affecting production tracking, mark your message as **Urgent** and we'll route it to an on-call engineer. ## Before you reach out To help us resolve issues faster, include the following when possible: * **Pixel ID** (find it in **Settings → Pixel** in your dashboard) * **Store URL** or domain you're tracking * **Affected destination** (Meta, TikTok, Klaviyo, etc.) * **Browser and OS** if the issue is in the dashboard * **Screenshots** of error messages or unexpected behavior * **Time range** when the issue started You can also directly and share these details in the conversation. ## Common issues If you're hitting a known issue, our troubleshooting guides may resolve it without waiting for support: Verify your pixel is loading and events are reaching Upstack. Check destination credentials, mapping, and forwarding rules. Reconcile differences between Upstack reporting and your ad platform. Diagnose and resolve double-counted conversions. ## Account and billing For subscription, billing, or plan questions, see [Subscriptions and billing FAQ](/billing/subscriptions-and-billing) or . # Troubleshooting: Attribution Numbers Don't Match Source: https://docs.upstackdata.com/troubleshooting/attribution-mismatch Diagnose attribution mismatches between Upstack Data and Meta Ads Manager, Google Analytics, or Shopify caused by attribution models, lookback windows, timezones, and event deduplication. ## Quick Diagnostic **Start here:** Small discrepancies (5–15%) between Upstack and other platforms are expected and normal. Every analytics platform uses different attribution models, lookback windows, and counting methods. This guide helps you understand *why* numbers differ and when a discrepancy signals an actual problem. ## Symptoms and Fixes **Likely cause:** Upstack and Meta use different attribution models. Meta defaults to **7-day click / 1-day view** attribution, meaning it credits a conversion to an ad if the user clicked within 7 days or viewed within 1 day. Upstack uses a **last-touch** model by default, which credits the most recent touchpoint regardless of platform. **How to reconcile:** 1. Understand that these are fundamentally different measurements — neither is "wrong." 2. In your Upstack dashboard, go to **Analytics → Attribution** and note which model is active (last-touch, first-touch, or linear). 3. In Meta Ads Manager, click **Columns → Customize** and check the **Attribution setting** at the bottom. Note the click and view windows. 4. Common reasons Upstack shows *more* conversions than Meta: * Upstack attributes organic and direct conversions that Meta doesn't claim. * Meta's attribution window may have expired for some conversions. 5. Common reasons Upstack shows *fewer* conversions than Meta: * Meta uses view-through attribution — Upstack's last-touch model won't credit an ad the user only saw but didn't click. * Meta may attribute the same conversion to multiple campaigns (especially with overlapping audiences). 6. For the closest comparison, set Meta to **7-day click only** (disable view-through) and compare with Upstack's last-touch model. **Likely cause:** Differences in how revenue is calculated — Shopify reports gross revenue including taxes and shipping by default, while Upstack reports the `Purchase` event value as sent by the pixel, which typically reflects the cart subtotal. **How to reconcile:** 1. In Shopify admin, go to **Analytics → Reports** and export the order data for the time range you're comparing. 2. Note whether Shopify includes taxes, shipping, discounts, and refunds in the total. 3. In Upstack, the `Purchase` event captures the `value` property from the checkout. This usually equals the cart subtotal before tax and shipping. 4. To compare accurately: * Shopify gross revenue **minus** taxes **minus** shipping should approximate Upstack's reported revenue. * If you've configured Upstack to include tax/shipping in the event value, the numbers should be closer. 5. Refunds also cause drift — Shopify retroactively adjusts revenue, while Upstack records the purchase at the time it occurred. Check **Events → Purchase** and filter by the date range to see the raw event values. **Likely cause:** Timezone mismatch between platforms. If Upstack, Meta, and Google Analytics use different reporting timezones, a conversion at 11 PM EST may appear on different calendar days depending on each platform's setting. **How to reconcile:** 1. Check your Upstack reporting timezone: go to **Settings → Workspace** and note the timezone. 2. Check Meta Ads Manager: go to **Ad Account Settings** and note the timezone. 3. Check Google Analytics: go to **Admin → Property Settings** and note the timezone. 4. Align all platforms to the same timezone for the most accurate comparison. In Upstack, you can change the reporting timezone under **Settings → Workspace** (this only affects how data is displayed, not how it's collected). 5. When comparing, always specify the exact same date range in UTC or use the same local timezone across all tools. **Likely cause:** Deduplication differences. Upstack and destination platforms use different deduplication keys. Upstack deduplicates by `event_id` before forwarding, but the destination may further deduplicate by user + event type + time window. **How to reconcile:** 1. A gap of 5–10% is normal and expected due to deduplication differences. 2. Check Upstack's **Live Event Stream** — if you see duplicate `event_id` values, your pixel may be firing the same event multiple times (see [Duplicate Events](/troubleshooting/duplicate-events)). 3. For Meta specifically: if you send both browser pixel events *and* Upstack server events for the same conversion, Meta deduplicates them using `event_id`. Ensure your Upstack events include the same `event_id` as the browser pixel fires. 4. For Google Analytics: GA4 automatically deduplicates events with the same `event_name`, `event_timestamp`, and user identifiers within a short window. This means GA4 may show fewer events than Upstack. 5. To reduce discrepancies, ensure deduplication keys are consistent across your pixel and Upstack's server-side events. ## Escalation If you're seeing discrepancies greater than 20% consistently, collect the following before contacting support: * Your **Pixel ID** and the **platforms** you're comparing (e.g., Meta Ads Manager, GA4, Shopify) * The **date range** and **timezone** for each platform's report * **Screenshots** of the numbers from each platform for the same period * The **attribution model and lookback window** configured in each platform *** **Still stuck?** Contact [support@upstackdata.com](mailto:support@upstackdata.com) with your Pixel ID and a description of the issue. We typically respond within a few hours. ## Related guides Understand how Upstack attributes conversions across marketing touchpoints. Explore Upstack's attribution reporting dashboard and multi-touch models. # Troubleshooting: Data Stopped Syncing Source: https://docs.upstackdata.com/troubleshooting/data-stopped-syncing Resolve stale Shopify data, missing ad spend updates, and stopped webhook events in Upstack Data — covers revoked permissions, expired tokens, webhook failures, and source connection health. ## Quick Diagnostic **Start here:** Go to **Settings → Sources** in your Upstack dashboard. Each connected source shows a **Last synced** timestamp and a health indicator. If any source shows a red status or a "last synced" time older than expected, click into it to see the specific error. ## Symptoms and Fixes **Likely cause:** The Shopify app's API permissions were revoked or the app was uninstalled and reinstalled without completing the full OAuth flow. Shopify stops sending webhooks and blocks API access when permissions are incomplete. **Fix:** 1. In your Shopify admin, go to **Settings → Apps and sales channels**. 2. Find **Upstack Data** in the list. If it shows a warning icon or says "Access limited," the permissions need to be re-granted. 3. Click **Upstack Data** → **App settings** → look for a **Re-authorize** or **Update permissions** prompt. 4. Complete the OAuth flow — ensure you approve all requested scopes (orders, customers, products, checkouts). 5. After re-authorizing, return to Upstack → **Settings → Sources → Shopify** and click **Test Connection**. The status should change to green. 6. Upstack will automatically backfill missed data for the period it was disconnected (up to 7 days). For longer gaps, contact support to trigger a full historical sync. **Likely cause:** The OAuth token for the ad platform source has expired. Meta tokens expire every 60 days unless refreshed, and Google Ads tokens can be revoked if the authorizing user changes their password or disables third-party app access. **Fix:** 1. Go to **Settings → Sources** and click the affected ad platform source (e.g., Facebook Ads, Google Ads). 2. If the status shows **Auth Error** or **Token Expired**, click **Reconnect**. 3. Sign in with the same account that originally authorized the connection. Ensure this account still has access to the ad accounts you want to sync. 4. After reconnecting, click **Sync Now** to trigger an immediate data pull. 5. To prevent future expiration issues: * **Meta:** Upstack automatically refreshes tokens, but if the user's Meta account password changes or 2FA is reset, a manual reconnection is required. * **Google Ads:** Use a service account or a dedicated Google account that won't have its password changed frequently. 6. Ad spend data syncs every 6 hours. After reconnecting, the next sync will backfill up to 30 days of missed data. **Likely cause:** Shopify automatically removes webhooks that consistently fail to respond. If Upstack's webhook endpoint experienced downtime or returned errors for 48+ hours, Shopify may have deleted the webhook subscription. **Fix:** 1. Go to **Settings → Sources → Shopify** in your Upstack dashboard. 2. Check the **Webhook Status** section. It lists all registered webhooks and their health. 3. If webhooks show as **Inactive** or **Not Registered**: * Click **Re-register Webhooks**. Upstack will re-create all required webhook subscriptions with Shopify. * This process takes about 30 seconds. 4. After re-registration, trigger a test event by placing a test order in your Shopify store (you can use Shopify's **Bogus Gateway** for test orders). 5. Check the Live Event Stream for the incoming webhook event within 2 minutes. 6. If webhooks fail to register, verify that your Shopify plan supports webhooks (all paid plans do — the Shopify Starter plan has limited webhook support). **Likely cause:** The connection is authenticated but the sync job is stuck or paused. This can happen after a plan downgrade (which may reduce sync frequency) or if the source data volume exceeds your plan's limits. **Fix:** 1. Go to **Settings → Sources** and click the affected source. 2. Check the **Sync History** log — look for the most recent sync attempt and its status. 3. If the last sync shows an **error**: * Note the error message (e.g., "Rate limited," "Timeout," or "Quota exceeded"). * Click **Sync Now** to trigger a manual sync attempt. 4. If the last sync shows **success** but the "Last synced" time is old: * Your sync schedule may have changed. Check **Settings → Subscription** to confirm your plan's sync frequency (hourly, every 6 hours, or daily). * Free plans sync once per day. [Upgrading your plan](/billing/upgrading-and-downgrading) increases sync frequency. 5. If manual sync also fails, try disconnecting and reconnecting the source. This resets the sync cursor without losing historical data. 6. After reconnection, monitor the Sync History for 15 minutes to confirm data starts flowing. ## Check your subscription **Before troubleshooting further:** Verify your Upstack subscription is active. An expired trial, failed payment, or paused subscription will stop data syncing. Check **Settings → Subscription** in the Upstack dashboard or see [Subscriptions and billing](/billing/subscriptions-and-billing) for help. ## Escalation If none of the above resolved the issue, collect the following before contacting support: * Your **Pixel ID** and the **source name** (e.g., Shopify, Facebook Ads) * The **last successful sync timestamp** from Settings → Sources * Any **error messages** from the Sync History log * Your **Shopify plan** name and your **Upstack subscription tier** *** **Still stuck?** Contact [support@upstackdata.com](mailto:support@upstackdata.com) with your Pixel ID and a description of the issue. We typically respond within a few hours. ## Related guides Confirm that your Shopify store is sending tracking events to the Upstack pipeline. See every source Upstack supports and how to connect them. # Troubleshooting: Duplicate Events Source: https://docs.upstackdata.com/troubleshooting/duplicate-events Fix duplicate events, inflated revenue, and doubled conversion counts in Upstack Data — covers client/server overlap, page reloads, Shopify thank-you page behavior, and deduplication settings. ## Quick Diagnostic **Start here:** Open the **Live Event Stream** in your Upstack dashboard and filter by `Purchase` events. If you see two events with identical timestamps and order IDs, you likely have both the Shopify native pixel and the Upstack server-side integration firing for the same conversion. Upstack deduplicates automatically when both events share the same `event_id` — the fix is usually ensuring consistent event IDs. ## Symptoms and Fixes **Likely cause:** Both a client-side pixel (e.g., Shopify's native conversion tracking or a custom script) and Upstack's server-side integration are capturing the same purchase event. Without matching `event_id` values, Upstack treats them as separate events. **Fix:** 1. Go to **Live Event Stream** and click on the duplicate purchase events. Compare their `source` field: * If one shows `pixel` (client-side) and the other shows `webhook` or `server` — this confirms the overlap. 2. **Recommended approach — rely on server-side only:** In your Shopify admin, go to **Settings → Customer events** and disable any custom purchase tracking scripts that duplicate what Upstack already captures via server-side webhooks. 3. **Alternative — keep both with deduplication:** If you need client-side events for latency reasons, ensure both the client pixel and the Shopify webhook send the same `event_id` (the Shopify order ID works well). Upstack deduplicates events sharing the same `event_id` within a 5-minute window. 4. After making changes, monitor the Live Event Stream for 30 minutes to confirm duplicates have stopped. **Likely cause:** A page reload or client-side navigation quirk is causing the Upstack pixel to fire twice. Common triggers include Shopify's AJAX cart updates (which some themes handle as full page reloads) and single-page app themes that fire both a `popstate` event and a full page load. **Fix:** 1. Open your store in Chrome → DevTools → **Network** tab. Filter by `upstack` or your pixel endpoint. 2. Navigate to the page where duplicates occur. Watch for two network requests firing for the same event. 3. If you see two requests: * Check if your theme uses AJAX cart functionality — some themes trigger a full page reload after adding to cart, which fires `PageView` again. * Check if you have a custom Upstack initialization script in addition to the app embed — only one should be active. 4. Go to **Online Store → Themes → Customize → App embeds** and ensure only the official **Upstack Data** embed is enabled. Remove any manual `