Service eligibility and regional restrictions
PuppyIP serves only compliant overseas businesses and their authorized personnel. Proxy services are not available in mainland China. The service may only be used for lawful business activities outside mainland China. Use of this service within mainland China is prohibited.
Hosting a proxy IP or server overseas does not change these restrictions. The service must not be provided to end users in mainland China through relaying, forwarding, sharing or resale. Before use, read the Terms of Service.
Key Takeaways
- Shopify opened shop_campaign_insights on August 10, 2026, enabling campaign and cohort performance queries through the existing shopifyqlQuery.
- Apps with read_reports and working ShopifyQL access need no new scope, but still must verify merchant authorization and the current token.
- Metrics include ad spend, sales, orders, ROAS, average order value and average customer-acquisition cost, with time granularity from hours to years.
- Time dimensions use the store time zone. Align date boundaries, currency, attribution windows and campaign filters before cross-system reconciliation.
- Before launch, use one campaign and a short time window to check totals, nulls and parsing errors, then gradually add caching, pagination and visualization.
Who needs this update
If your app already uses ShopifyQL for sales or marketing reports, Shop Campaigns data can now join the same query path. The aim is not merely copying admin numbers, but letting authorized merchants inspect performance by campaign, customer cohort and time in the app.
Teams not using Shop Campaigns, lacking read_reports authorization or needing only manual admin viewing do not need to change code. First establish an ongoing business need for reporting.
How the new schema differs from the old approach
Previously, apps could not directly query Shop Campaigns performance through this dedicated schema. They can now use the existing shopifyqlQuery field with shop_campaign_insights as the data source to read campaign- and cohort-level metrics.
This introduces no new marketing-attribution rule and does not automatically repair historical reports. It opens a query entry point only; metric definitions, merchant eligibility and data availability remain determined by Shopify responses.
Permissions and pre-integration checks
Confirm read_reports scope, a current access token representing the target store, and actual merchant use of Shop Campaigns. Official guidance says existing ShopifyQL integrations require no additional scope, but first-time integrations should still test authorization errors and empty data in a test store.
Record Admin GraphQL API version, query text, store identifier and request ID. Do not put access tokens in browser logs, tutorials or support tickets. For 401/403, check authorization and scopes before repeated retries.
Organizing queries and fields
Start with a few dimensions and metrics from shop_campaign_insights, such as campaign name, date, ad spend, sales, orders, ROAS, average order value and average acquisition cost. Limit to one campaign and a short date range first, confirming column names, types and nulls before expanding.
Do not assume every metric is additive. Recalculate ratios and averages from official definitions or base quantities, and do not combine cohort rows with campaign totals at the same aggregation level. Read parseErrors returned by shopifyqlQuery for parsing failures.
The store time zone is an easy boundary to miss
Shopify explicitly says time dimensions use the store time zone, with granularity from hours to years. If a reporting service stores everything in UTC, retain the store time zone and original time dimension too, avoiding day-boundary, daylight-saving and month-end mismatches.
Before comparing ad platforms or financial systems, align date boundaries, currencies, refund treatment, attribution windows and campaign statuses. Narrow discrepancies item by item rather than covering them with one correction multiplier.
Pre-launch validation checklist
Choose one merchant, one campaign and one complete date interval, then compare query results field by field with Shopify’s visible reports. Check column types, nulls, zeros, duplicate rows, time boundaries, currency and totals, retaining query and reconciliation evidence.
During canary rollout, monitor GraphQL errors, parseErrors, empty-result rate, query duration and cache hits. Stop expansion for missing fields, metric jumps or authorization anomalies, return to the old report and retain original responses.
Separate network errors from data errors
401, 403 and ShopifyQL parsing errors generally concern authorization or queries; DNS, TLS and connection timeouts belong to the network layer. Start with API Key, Base URL and error-layer guidance, then use the proxy connection troubleshooting checklist when clear network evidence exists.
Cross-border teams needing stable Shopify documentation and admin access can visit the PuppyIP website to learn about fixed network egress. Egress cannot grant merchant authorization, read_reports scope or change data definitions.
Sources
Frequently Asked Questions
What permissions are needed to query Shop Campaigns data?
read_reports scope and a valid token for the authorized merchant are required. Existing ShopifyQL integrations generally need no additional scope.
Which metrics are available through shop_campaign_insights?
Officially listed metrics are ad spend, sales, orders, ROAS, average order value and average acquisition cost, queryable by campaign, customer cohort and time.
Which time zone does the report use?
Time dimensions use the store time zone. Explicitly convert and retain the original zone when reconciling with UTC data warehouses or ad platforms.
Why does a query return no results?
Check merchant use of Shop Campaigns, valid authorization and whether dates and filters match, then inspect parseErrors. Do not treat empty results directly as zero.
Can ROAS and averages be added directly across campaigns?
No. Recalculate ratios and averages using base quantities and official definitions, avoiding double aggregation of campaign totals and cohort rows.
Can a proxy solve read_reports permission errors?
No. A proxy affects the connection path only, not OAuth scopes or merchant authorization. Check application permissions first for 401/403.