Upload Shopify Ads Report
Upload Shopify Ads Report
Shopify Ads data lives behind the Partner Dashboard and isn't available through the Partner API. To see your ads
performance in Ranksy, you export a CSV from Shopify and upload it here. Once imported, you get a full breakdown of
spend, installs, revenue, and ROAS per search term, country, shop plan, and device type.
What You'll Get
After uploading, Ranksy shows:
- Search term performance: Spend, clicks, installs, CVR, and ROAS per keyword
- Geography breakdown: Which countries convert best
- Shop plan breakdown: Performance by Basic, Shopify, Advanced, Plus
- Device breakdown: Desktop vs. mobile vs. tablet
- Cannibalization signals: Paid keywords where you already rank organically
- Waste analysis: High-spend keywords with low returns
Before You Start
Make sure you have:
✅ Access to your Shopify Partner Dashboard ✅ At least one active or past ad campaign ✅ Admin permissions for the app in
Ranksy
Step 1: Export the CSV from Partner Dashboard
You need to export the Ad data for campaign by search terms report with all three breakdowns enabled. This is the only
report format Ranksy supports, because it contains the keyword-level detail needed for analysis.
Open Your Campaign
1. Log into partners.shopify.com
2. Go to Apps and select the app you're running ads for
3. Click Ads in the left sidebar
4. Click into the campaign you want to export
Select the Date Range
1. In the top right of the campaign page, click the date range picker
2. Choose the period you want to analyze
⚠️ Important: Ranksy prevents overlapping date ranges for the same campaign. If you've already uploaded a report for
part of this period, pick a date range that doesn't overlap — or delete the existing report first.
Configure the Export
1. Click the Export button
2. Under report type, select Ad data for campaign by search terms
3. Check all three breakdown boxes:
- ✅ Include breakdown by country/region
- ✅ Include breakdown by shop plan
- ✅ Include breakdown by device type
All three breakdowns are required. Ranksy validates the file has the full 28-column format and will reject exports that
are missing columns.
Download the File
1. Click Export at the bottom of the dialog
2. Shopify generates the CSV (this can take a few seconds to a minute for large campaigns)
3. Save the file somewhere you can find it
The file will be named something like campaign-name-search-terms.csv.
🎥 Watch the export flow (18 seconds) — opens the video in a new tab.
Step 2: Upload the CSV to Ranksy
Open the Shopify Ads Page
1. In Ranksy, go to My Apps and select your app
2. Click Shopify Ads in the sidebar
Upload Your File
1. Drag your CSV directly onto the upload area, or click Choose files to browse
2. You can upload up to 20 files at once if you're importing multiple campaigns
3. Each file must be 10MB or smaller
4. Accepted formats: .csv and .txt
Each file shows its own progress indicator as it uploads: pending → uploading → queued → processing → completed.
🎥 Watch the upload flow (20 seconds) — opens the video in a new tab.
Step 3: What Happens Next
Once the file is uploaded, Ranksy runs a series of checks before importing:
1. Header validation: Confirms the CSV has all 28 expected columns in the correct format
2. App matching: Reads the app name from the CSV and matches it to the correct app in your team
3. Duplicate check: Computes a hash of the file and rejects it if you've uploaded the same file before
4. Date overlap check: Rejects the upload if its date range overlaps with an existing report for the same campaign
If all checks pass, Ranksy queues the file for background processing.
Processing
The import runs in the background, so you don't have to keep the page open:
- Rows are processed in batches of 500
- Each row becomes a searchable record with its keyword, country, shop plan, device, spend, and conversion metrics
- Summary totals (impressions, clicks, installs, spend, revenue) are calculated for the whole report
Most reports finish in under a minute. Very large exports (50,000+ rows) may take a few minutes.
Notification
When processing finishes, the page updates in real time and your new report appears in the list with summary stats. You
can click into it to see the full search-term breakdown.
Viewing Your Ads Data
Once imported, your data is available across several views:
- Overview: Totals for spend, installs, revenue, and ROAS across all reports
- Search Terms: Per-keyword performance table, sortable by any metric
- Geography: Country-level breakdown with conversion rates
- Devices: Desktop / mobile / tablet comparison
- Shop Plans: Performance segmented by merchant plan
- Wasters: High-spend keywords that aren't converting
- Cannibalization: Paid keywords where you're already ranking organically
Troubleshooting
Error: "Invalid CSV format" or "Missing required columns"
Fix:
- Re-export from Partner Dashboard and confirm you selected Ad data for campaign by search terms, not a different
report type
- Confirm all three breakdown checkboxes (country, shop plan, device) were checked
- Don't edit the CSV before uploading — column names must match exactly
Error: "This report has already been uploaded"
Fix:
- Ranksy detected you've uploaded this exact file before
- If you want to re-import, delete the existing report from the Shopify Ads page first
- If the content changed, re-export fresh from Partner Dashboard
Error: "Date range overlaps with an existing report"
Fix:
- Another report for this campaign already covers part of this date range
- Either shorten your date range to avoid the overlap, or delete the conflicting report first
- You can see existing reports and their date ranges in the reports list
Error: "App not found"
Fix:
- The app name in the CSV doesn't match any app in your Ranksy team
- Make sure the app you're exporting for has been added to My Apps in Ranksy
- Check that the app name in Partner Dashboard matches the one in Ranksy
Upload fails or file is too large
Fix:
- Files must be under 10MB — if yours is larger, export a shorter date range and upload multiple files
- Check your internet connection
- Try a different browser if the issue persists
Processing stuck on "queued"
Fix:
- Most reports start processing within a few seconds
- Wait 5 minutes before assuming something is wrong
- Refresh the page — the status updates in real time
- If still stuck after 15 minutes, contact support
FAQ
Q: Why can't Ranksy pull this data automatically? A: Shopify Ads data isn't exposed through the Partner API. CSV upload
is currently the only way to get it into any analytics tool.
Q: How often should I upload? A: Weekly uploads give you a good rhythm for spotting trends. Upload a fresh report
covering the new week each time.
Q: Can I upload historical campaigns? A: Yes. Export as far back as Partner Dashboard lets you, and upload the file.
Ranksy will process it the same way.
Q: What if I re-export the same date range with updated numbers? A: Delete the existing report first, then upload the
new file. The duplicate check prevents accidental re-uploads but doesn't stop you from refreshing a report deliberately.
Q: Do I need the breakdown checkboxes if I don't care about geography or devices? A: Yes. The CSV structure requires all
three breakdowns. Reports without them will be rejected.
Q: Can I upload reports for multiple campaigns at once? A: Yes. Drag up to 20 files in at once. Each is processed
independently.
Q: Is my data visible to other teams? A: No. Reports are scoped to your team only.
Need help? Contact [email protected] or use the chat widget. Include the name of the campaign and the error message if
you hit one.