shop_campaign_insights schema added. Query ad spend, sales, order count, ROAS, AOV, and average customer acquisition cost using the existing shopifyqlQuery field and read_reports scope as-is. No new scopes, no extra implementation.
shop_campaign_insights schemahas been added to ShopifyQL.shopifyqlQuery field plus the read_reports scope, exactly as they do today.
ShopifyQL could already query other schemas, but no shop_campaign_insights existed for pulling Shop Campaigns performance data.
Just point the same shopifyqlQuery at the new schema name.If your app already calls ShopifyQL, no new scopes and no integration work are required— stated explicitly.
shopifyqlQuery, and the required permission is unchanged: read_reports.
The only thing that changed is the list of schema names you can query.
| Dimension | Description |
|---|---|
| Campaign name | Break metrics down at the campaign level |
| Customer segment | Break metrics down at the segment level |
| Time | Hourly through yearly hourly / ... / yearly.the merchant's shop time zoneis used |
| Item | What changed |
|---|---|
| Schema | Added shop_campaign_insights is now available in ShopifyQL |
| Query fields | No change Use the existing shopifyqlQuery as-is |
| Required scopes | No change read_reports.No new scopes needed |
| Integration work | If you already query ShopifyQL,no additional integration work is requiredis stated explicitly |
| Who runs the query | Analytics / reporting appson behalf of authorized merchantsquery |
| Time zone | Returned based on the merchant's shop time zone |
read_reports ScopesThe same scopes as your existing ShopifyQL queries. No additional scopes are needed.
Queries run on behalf of "authorized merchants". Only data from authorized stores is covered.
If you already use shopifyqlQuery , you can reuse that code path.
read_reports Confirm you have it. If you already query ShopifyQL, it's usually unchanged.
With the same shopifyqlQuery shop_campaign_insights and query it.
Specify a campaign name, segment, and time granularity (hourly to yearly) to build the report.
Shop Campaigns metrics can beembedded directly into your own app's UIwith this web component.no data storage requiredis stated explicitly. It's a route to putting metrics on screen without building your own fetching, storage, and rendering.
An API that cancreate annotationson a merchant's analytics charts. The examples in the post are "campaign started" and "budget changed" — a way to pin "why it moved" onto the points where the numbers change.
The endpoint and authorization are unchanged.shopifyqlQuery — if your app already has a wrapper for it, adding an argument to pass the schema name through is about all it takes. The kind of change that keeps the diff review small.
read_reports stays as is = no re-authorization flowAdding a scope normally means re-consent across every existing install. Here it's stated explicitly that this isn't needed, soyou can ship without asking merchants to re-approve— practically speaking, that's the biggest win.
hourly through yearly. You can see spend efficiency by time of day, but a fine granularity over a wide range makes responses heavy.Design the granularity and range limits on the app sideto be safe.
The time axis returned uses the merchant's shop time zone. If your own dashboard is built on a fixed UTC or JST, the date boundaries will drift from your other data sources. If you plan to reconcile them, decide on a conversion policy first.
To surface the same metrics, two routes shipped at once:fetch with ShopifyQL and render it yourself, andembed with Analytics Web Components (no data storage). If you need to transform, reconcile, or export, go with ShopifyQL; if you just want it on screen, the component takes less code. Decide which one is enough before building out both.
shopifyqlQuery call, add a shop_campaign_insights query, and surface ad spend, revenue, order count, and ROAS in a table by campaign name × time period.shop_campaign_insights schemacan now be queried.shopifyqlQuery and read_reports stay as they are — no new scopes and no extra integrations needed to add campaign performance to your reports.