Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.upstackdata.com/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
Prerequisites

Prerequisites:
  • An Upstack Data account (sign up for free)
  • 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

MetricDescriptionGranularity
SpendTotal cost per campaign / ad group / adDaily
ImpressionsNumber of times ads were shownDaily
ClicksTotal clicks on adsDaily
CPMCost per thousand impressionsDaily (calculated)
CPCCost per clickDaily (calculated)
CTRClick-through rateDaily (calculated)
ConversionsTikTok-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 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

1

Connect your TikTok Ads account

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.
2

Select ad accounts

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.
3

Confirm and start sync

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.
  • 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 with your Pixel ID and a description of the issue. We typically respond within a few hours.

TikTok Events API Destination

Send conversion events to TikTok — the outbound counterpart to this inbound source.

TikTok onboarding guide

Step-by-step walkthrough for setting up TikTok end-to-end in Upstack.

Connect Facebook Ads

Import Facebook Ads spend data for a complete view of paid social performance.

Attribution and Reporting

How Upstack blends ad spend data with conversion events to calculate ROAS and CPA.