Ads Table

ads_table

The Ads table aggregates data on advertising campaigns from various platforms, detailing when ads were run, through which channels, and their performance metrics such as spend, clicks, and conversions. By querying this table, users can uncover insights into the effectiveness of their ad campaigns across different platforms, optimize ad spend, and improve targeting strategies to enhance overall ad performance.

📘

Note

event_date is a required field for queries on this table.

Dimensions

Dimensions are immutable properties that can be used for grouping data.

Title	ID	Type	Description
Event Hour	event_hour	string	The hour of the day the ad was run, according to a 24-hour clock. Based on the time zone of the shop at the moment of publishing. Example values: 07, 16, 21
Event Date	event_date	date	The date the ad was run. Based on the time zone of the shop at the moment of publishing.
Event Day	event_date.day	date	The day on which the event occurred. Derived from event_date.
Event Week	event_date.week	date	The Sunday of the week during which the event occurred. Derived from event_date.
Event Month	event_date.month	date	The month during which the event occurred. Derived from event_date.
Event Quarter	event_date.quarter	date	The first month of the quarter during which the event occurred. Derived from event_date.
Event Year	event_date.year	date	The year during which the event occurred. Derived from event_date.
Ad Bid Amount	ad_bid_amount	string	The bid amount for the ad. Example values: 15, 28, 30
Ad Copy	ad_copy	string	The full text (copy) of the ad.
Ad ID	ad_id	string	The unique ad ID. Assigned by the publisher platform. Example value: 120210439891110007
Ad Image URL	ad_image_url	string	The URL of the ad image. Example value: https://www.example.com/ad-image.jpg
Ad Name	ad_name	string	The name of the specific ad. Example values: Kids Ad 1, Read Our Latest Blog 03/12/2023, 8 best fall looks
Ad Status	ad_status	string	The status of the ad. Example values: active, paused
Ad Type	ad_type	string	The format of the ad. Example values: video, image, copy
Adset Bid Amount	adset_bid_amount	string	The bid amount for the adset. Example values: 25, 35, 40
Adset Bid Strategy	adset_bid_strategy	string	The bidding strategy for the adset. Example values: LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS
Adset Daily Budget	adset_daily_budget	string	The daily budget set for the adset within a campaign. By default shown in the shop's currency. Example values: 1750, 6000, 40000
Adset ID	adset_id	string	The unique ID for the adset associated with the ad click. Assigned by the publisher platform. Example value: 120210439890740003
Adset Lifetime Budget	adset_lifetime_budget	string	The total budget set for the adset within a campaign over its lifetime. By default shown in the shop's currency. Example values: 5000, 10000, 20000
Adset Name	adset_name	string	The name of the adset within a campaign. Example values: Broad Audience, Bracelets, Wellness
Adset Status	adset_status	string	The status of the adset. Example values: active, paused
Adset Targeting	adset_targeting	record repeated	Details on targeting parameters for the adset, including specific audience segments. Learn more about adset targeting data
Target Key	adset_targeting.target_key	string	The targeting category key within the adset (e.g., location, age, gender). Learn more about adset targeting data Example values: age_min, age_max, geo_locations_countries, device_platforms, genders
Target Values	adset_targeting.target_values	record repeated	The specific values associated with the targeting category key, returned as an array. Learn more about adset targeting data
Amazon Marketplace ID	amazon_marketplace_id	string	The Amazon marketplace ID for the marketplace associated with the order. See list of marketplace IDs.
Amazon Report Type	amazon_report_type	string	The type of report generated for Amazon advertising activities (e.g. sponsored products, sponsored brands, sponsored display).
Breakdown Dimension	breakdown_dimension	string	The dimension used to break down the data, e.g., Country, Gender, Age, Publisher Platform, Frequency.
Breakdown Value	breakdown_value	string	The value of the breakdown dimension.
Campaign Bid Strategy	campaign_bid_strategy	string	The bidding strategy for the campaign. Example values: LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS
Campaign Daily Budget	campaign_daily_budget	string	The daily budget for the campaign. Example values: 8000, 10000, 15000
Campaign ID	campaign_id	string	The unique ID for the marketing campaign associated with the ad. Assigned by the publisher platform. Example values: 23852438666180053, 531011533, 20620285829
Campaign Lifetime Budget	campaign_lifetime_budget	string	The lifetime budget for the campaign. Example values: 5000, 10000, 20000
Campaign Name	campaign_name	string	The name of the marketing campaign associated with the ad. Example values: Catalog Retargeting, US Generic Search, Breakfast of Champions Campaign
Campaign Status	campaign_status	string	The status of the campaign. Example values: active, paused
Channel	channel	string	The platform through which the ad was delivered. Example values: facebook-ads, google-ads, tiktok-ads
Currency	currency	string	The currency used in the ad platform. Example values: USD, GBP, EUR
Destination URL	destination_url	string	The destination URL where users land after clicking the ad. Example value: https://www.myshop.com/products/productA
URL Template	url_template	string	A template URL used to dynamically populate ad URLs with relevant tracking parameters. Example value: utm_source=facebook&utm_campaign={{campaign.name}}
Video URL	video_url	string	The URL of the ad video. Example values: https://www.youtube.com/embed/example

Measures

Measures are numeric fields that can be aggregated and/or combined to calculate new metrics.

Title	ID	Type	Description
All Conversion Value	all_conversion_value	numeric	Revenue generated from channel-reported conversions of all types (e.g. purchases, registrations, subscriptions, applications).
All Conversions	all_conversions	numeric	The total number of channel-reported conversions of all types (e.g. purchases, registrations, subscriptions, applications).
Clicks	clicks	numeric	Number of channel-reported clicks.
Channel-Reported Conversion Value	conversion_value	numeric	Revenue generated from channel-reported conversions (purchases).
Channel-Reported Conversions (Purchases)	conversions	numeric	Number of channel-reported conversions (purchases).
Engagements	engagements	numeric	Number of interactions with the ad (likes, shares, etc).
Follows	follows	numeric	Number of new follows attributed to the ad.
Impressions	impressions	numeric	Number of channel-reported impressions.
Inline Post Engagement	inline_post_engagement	numeric	Number of inline engagement (likes, shares, comments) with the ad.
One-Day View Conversion Value	one_day_view_conversion_value	numeric	The total value of channel-reported purchases made within one day of viewing the ad.
One-Day View Purchases	one_day_view_purchases	numeric	The total number of channel-reported purchases made within one day of viewing the ad.
Onsite Conversion Value	onsite_conversion_value	numeric	Revenue from channel-reported purchases made on the ad channel shop (e.g. Meta Shop, TikTok Shop).
Onsite Purchases	onsite_purchases	numeric	Number of channel-reported purchases made on the ad channel shop (e.g. Meta Shop, TikTok Shop).
Outbound Clicks	outbound_clicks	numeric	Number of channel-reported outbound clicks.
Reach	reach	numeric	The total number of unique individuals who saw the ad.
Ad Spend	spend	numeric	Channel-reported ad spend, excluding any custom expenses marked as ad spend.
Three-Second Video View	three_second_video_view	numeric	The number of times a video ad was viewed for at least 3 seconds (thumbstop ratio).
Thruplays	thruplays	numeric	The number of times a video ad was played to completion or for at least 15 seconds.
Visits	visits	numeric	Number of channel-reported visits.

Derived

Derived fields are metrics that are pre-calculated using multiple measures or advanced formulas.

Title	ID	Type	Description
All Cost Per Acquisition (All CPA)	all_cpa	formula	Cost per conversion of all types (e.g. purchases, registrations, subscriptions, applications). All CPA = Ad Spend / All Conversions
All Return on Ad Spend	all_roas	formula	Revenue generated per dollar spent on ads, for channel-reported conversions of all types (e.g. purchases, registrations, subscriptions, applications). All ROAS = All Conversion Value / Ad Spend
Average Order Value	aov	formula	The average order value as reported by the ad channel. Channel-Reported AOV = Channel-Reported Conversion Value / Number of Channel-Reported Conversions
Conversion Rate	conversion_rate	formula	The percentage of visits that convert into orders, as reported by the channel. Channel-Reported Conversion Rate = Number of Channel-Reported Conversions / Number of Visits
Cost Per Acquisition	cpa	formula	The cost to acquire a single conversion, as reported by the channel. Channel-Reported CPA = Ad Spend / Number of Channel-Reported Conversions
Cost Per Click	cpc	formula	The average cost for each ad click. CPC = Ad Spend / Clicks
Cost Per Mille	cpm	formula	The cost for 1,000 ad impressions. CPM = Ad Spend / Impressions x 1000
Cost Per Outbound Click	cpoc	formula	Cost for each click leading out from the publisher platform to an external website. CPOC = Ad Spend / Outbound Clicks
Cost Per Visit	cpv	formula	The cost for each visit driven by ads. CPV = Ad Spend / Number of Visits
Click-Through Rate	ctr	formula	The percentage of impressions that result in a click. Click-Through Rate (CTR) = Clicks / Impressions
Revenue Per Link Click	revenue_per_link_click	formula	Average revenue generated from each outbound click on the ad. Revenue Per Link Click = Conversion Value / Outbound Clicks
Channel-Reported Return on Ad Spend	roas	formula	Revenue generated per dollar spent on ads, as reported by the channel. Channel-Reported ROAS = Channel-Reported Conversion Value / Ad Spend