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

# How to Connect TikTok Ads to Upstack Data

> Connect your TikTok Ads account under System → Data Sources so Upstack Data imports spend, impressions, clicks, and campaign structure for ROAS reporting.

> [!NOTE]
>
> **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.

> [!NOTE]
>
> 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](https://docs.upstackdata.com/destinations/catalog/tiktok.md). Without the source, you'll see TikTok-attributed conversions in Upstack but no TikTok spend to calculate ROAS against.

> [!TIP]
>
> * Sign in to [Upstack Data](https://app.upstackdata.com) and open **System → [Data Sources](https://app.upstackdata.com/integrations)**.
> * Click the **TikTok** card, then click **Connect TikTok**.
> * Sign in to TikTok For Business in the popup and authorize Upstack.
> * Select your **ad accounts**, click **Save & Complete Setup**, and check that the card shows **Connected**.

## Prerequisites

> [!NOTE]
>
> **Prerequisites:**
>
> * An Upstack Data account ([sign up for free](https://app.upstackdata.com))
> * Access to your workspace in the Upstack dashboard

You'll also need:

* A TikTok For Business login with access to the **ad accounts** (advertisers) you want to connect
* At least one TikTok ad account with active or historical campaigns
* Popups allowed for app.upstackdata.com (the TikTok sign-in opens in a popup)

## Setup

**1. Open Data Sources**

Sign in to your [Upstack Data](https://app.upstackdata.com) account and open **System → [Data Sources](https://app.upstackdata.com/integrations)**.

![Upstack Data Sources page under System, with the TikTok card showing Not Configured](https://mintcdn.com/upstackdata-afbed50d/iBK5HcAVuU80LdGi/images/data-sources/data-sources-page.png?fit=max\&auto=format\&n=iBK5HcAVuU80LdGi\&q=85\&s=c003e75bbe36146b76c9dc7356fc7606)

**2. Open the TikTok settings**

Click the **TikTok** card. The **TikTok Integration Settings** dialog opens with the connection status.

![TikTok Integration Settings dialog with status Not Configured and the Connect TikTok button](https://mintcdn.com/upstackdata-afbed50d/iBK5HcAVuU80LdGi/images/data-sources/tiktok-integration-settings.png?fit=max\&auto=format\&n=iBK5HcAVuU80LdGi\&q=85\&s=a16d12b93abb8a113338962b07c1cea2)

**3. Connect TikTok**

Click **Connect TikTok**. In the popup, sign in to TikTok For Business and authorize Upstack to access your advertiser accounts. The popup closes when you're done.

The card status changes to **Pending** until you finish the next step.

**4. Select ad accounts**

Back in the dialog, the **Ad Accounts** section lists the TikTok ad accounts you authorized, with each account's name and ID. Select one or more accounts to sync. If an account is missing, click **Refresh**.

> [!WARNING]
>
> **Match accounts to your store.** Select only the TikTok ad accounts that drive traffic to this store. Connecting unrelated accounts skews your ROAS and CPA metrics.

**5. Save**

Click **Save & Complete Setup**. The dialog closes and the **TikTok** card shows **Connected**.

The initial import covers up to 36 months of history. After that, Upstack checks for updated metrics every 15 minutes, re-pulling the most recent 2 days so late-arriving spend is captured.

> [!NOTE]
>
> If you close the dialog before saving, Upstack asks you to confirm. Choosing **Close & Finish Later** leaves the card in **Pending**, and nothing syncs until you select an ad account and save.

## Change, reconnect, or disconnect

Click the **TikTok** card on **System → Data Sources** to manage the connection:

* **Add or remove ad accounts:** click **Edit**, change the selection, and click **Save Changes**.
* **Reconnect:** if the card shows **Error** or **Disconnected**, click **Reconnect** and sign in again.
* **Disconnect:** click **Disconnect** to stop syncing TikTok spend.

## What Data Flows In

Upstack imports performance data at the advertiser, campaign, ad group, and ad level, by day and by hour:

| Data | Includes |
| - | - |
| **Delivery** | Spend, impressions, reach, frequency, cost per 1,000 people reached |
| **Clicks** | Clicks, CTR, CPC, CPM |
| **TikTok-reported results** | Conversions, results, complete payments and payment ROAS, total purchase value, add to cart, checkout, view content |
| **Engagement and video** | Likes, shares, video plays, and watch milestones |

Upstack also imports the campaign structure (campaigns, ad groups, and ads), including names, objective, status, bid type, budget, optimization goal, and billing event.

> [!NOTE]
>
> Spend is stored in the ad account's currency and each day follows the ad account's time zone. Reports convert spend to your [reporting currency](https://docs.upstackdata.com/concepts/reporting-currency.md) using daily exchange rates.

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

## You'll Know It's Working When...

> [!TIP]
>
> **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](https://docs.upstackdata.com/troubleshooting/destination-token-expired-or-auth-error.md).

* [ ] The **TikTok** card on **System → Data Sources** shows **Connected**
* [ ] TikTok spend appears in the **Attribution** dashboard once the initial import completes
* [ ] ROAS populates for campaigns that have both spend data and attributed conversions

## Troubleshooting

> [accordion] No data appearing after connecting
>
> Check that the **TikTok** card shows **Connected**, not **Pending**. A **Pending** card means no ad account was saved: click the card, select your accounts, and click **Save & Complete Setup**.
>
> If the card shows **Connected** and no data appears after a few hours:
>
> 1. Verify the selected ad accounts had spend in the last 36 months (the import window)
> 2. Confirm you selected the right account (check the ID matches the Advertiser ID in TikTok Ads Manager)
> 3. Contact support with your Pixel ID

> [accordion] An ad account is missing from the list
>
> The list shows the ad accounts you authorized in the TikTok popup. Click **Refresh** to reload it. If the account is still missing, click **Reconnect** and make sure you authorize that ad account when TikTok asks which advertisers Upstack can access.

> [accordion] Spend numbers don't match TikTok Ads Manager
>
> Small discrepancies are normal while the most recent days are still being re-pulled.
>
> **Common causes of larger discrepancies:**
>
> * **Time zone** — each day follows the ad account's time zone. If your Upstack reporting timezone differs, compare the same date range in both time zones.
> * **Currency** — if your TikTok ad account bills in a different currency than your reporting currency, Upstack converts with daily exchange rates, which can cause small differences.
> * **Ad accounts** — make sure every ad account that spends for your store is selected.

> [accordion] Card shows Error
>
> The saved TikTok authorization no longer works, usually because access was revoked in TikTok For Business. Syncing stops until you reconnect.
>
> 1. Click the **TikTok** card on **System → Data Sources**
> 2. Click **Reconnect** and authorize Upstack again
> 3. Check that your ad accounts are still selected
>
> Recent days are re-pulled automatically after you reconnect. If spend for older dates is still missing, contact support.

***

**Still stuck?** Contact [support@upstackdata.com](mailto:support@upstackdata.com) with your Pixel ID and a description of the issue. We typically respond within a few hours.

## Related

> [card] [TikTok Events API Destination](https://docs.upstackdata.com/destinations/catalog/tiktok.md)
>
> Send conversion events **to** TikTok — the outbound counterpart to this inbound source.

> [card] [TikTok onboarding guide](https://docs.upstackdata.com/destinations/catalog/tiktok/complete-how-to-guide-for-onboarding-tiktok-ads-in-upstack-data.md)
>
> Step-by-step walkthrough for setting up TikTok end-to-end in Upstack.

> [card] [Connect Facebook Ads](https://docs.upstackdata.com/sources/catalog/meta-ads/how-to-connect-meta-ads-to-upstack-data.md)
>
> Import Facebook Ads spend data for a complete view of paid social performance.

> [card] [Attribution and Reporting](https://docs.upstackdata.com/concepts/attribution-and-reporting.md)
>
> How Upstack blends ad spend data with conversion events to calculate ROAS and CPA.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.