Microsoft Ads Connector

The Microsoft Ads Connector sends your tracked events to Microsoft Ads both through the Microsoft Universal Event Tracking (UET) tag in the browser and server-side. There are two server-side delivery methods, and the connector page in Tracklution has one section for each:

• Conversions API (recommended): every mapped event is also delivered server-to-server to Microsoft's Conversions API, alongside your UET tag. Use this for all new setups.
• Online & Offline conversion goals (legacy): the original connector: UET conversion goals plus offline conversion uploads matched with the Microsoft Click ID (MSCLKID). Existing connectors keep working exactly as before.

Already using the Microsoft Ads connector? Your existing connector is not changed or upgraded automatically. You can add the Conversions API next to it whenever you like from the connector settings.

Prerequisites

You will need the following to complete the setup of the connector successfully:

• A Microsoft Ads account
• For the Conversions API: access to Microsoft Advertising with a role that can edit UET tags (needed to copy the Conversions API token)
• Auto-tagging of msclkid enabled in your Microsoft Ads account, so click IDs reach your site and conversions can be attributed (Tracklution shows a warning in the connector if it is off)

Which connector should I use: Conversions API or legacy?

• New connector: set up the Conversions API. When you open the connector, the "Conversions API (recommended)" section is open by default. The legacy setup is still available via "Set up the legacy Online/Offline connector instead".
• Existing legacy connector: keep it running and add the Conversions API in parallel with the "Add the Conversions API in parallel (recommended)" button. Both can run at the same time, see the section on existing connectors below for how the goals are counted.

Authenticating with Microsoft Ads (both setups)

Both the Conversions API (with Connect with Microsoft) and the legacy Online & Offline conversion goals connector authenticate the same way: click Start Authentication, log in to Microsoft Ads and accept the permissions for 'Tracklution Oy'. You are then redirected back to Tracklution to continue with the next step.

If you are unable to authenticate with Microsoft Ads, try the following:

If you are unable to authenticate with Microsoft Ads, try the following:

1. Grant admin consent directly. A Microsoft Entra admin with at least the Cloud Application Administrator role should open this link and approve the Tracklution app:

    https://login.microsoftonline.com/common/adminconsent?client_id=5671eb64-1451-45ab-8ea3-a1af7b9b1b36&redirect_uri=https://api.tracking.leadspark.io/network/integration/microsoft-ads/callback
   

2. Use a personal Microsoft account. In Microsoft Ads settings, add or switch to a personal email (e.g. outlook.com). Personal accounts are not subject to tenant-level admin consent requirements.

3. Verify your admin role. Microsoft Ads super admin and Microsoft Entra admin are separate. The connector requires a tenant-level role - check your assigned roles in the Microsoft Entra admin center.

Conversions API Setup (recommended)

Choose the Microsoft Ads Connector from the "Connectors" section on your tracking container dashboard, click "Add" or "Edit", and expand the section Conversions API (recommended).

Step 1: Choose setup method: Connect with Microsoft or Manual setup

The Conversions API needs three things: the UET tag to send the events to, the Conversions API token of that tag, and a conversion goal in Microsoft Ads for each event you send. The setup method decides how much of this Tracklution does for you.

Connect with Microsoft (recommended)

You log in to Microsoft once and give Tracklution access to your Microsoft Ads account, the same authentication as in the legacy connector. Tracklution then:

• shows your Microsoft Ads accounts and their UET tags, so you pick the tag from a list (or let Tracklution create a new one),
• creates the conversion goals in Microsoft Advertising for you when you enable events.

You still copy the Conversions API token from Microsoft Advertising and paste it into Tracklution (Step 4). Microsoft does not allow it to be fetched automatically. Choose this option unless you cannot authenticate with Microsoft.

Manual setup

No Microsoft login. You do the steps by hand:

• type the UET tag id (Microsoft Advertising → Tools → UET tags),
• copy and paste the Conversions API token (Step 4),
• create an Event conversion goal in Microsoft Advertising for each event you enable (Step 5 lists what to create).

Choose this if you cannot or do not want to authenticate with Microsoft - for example when your Microsoft Entra tenant blocks the consent, or when the UET tag is managed by someone else who only hands you the tag id and the token. If your container already has a connected legacy Microsoft Ads connector, Manual setup reuses its Microsoft connection: you can pick the account and tag from dropdowns and the conversion goals are still created automatically.

In both cases the events are delivered to Microsoft in exactly the same way - the setup method only affects how the connector is configured.

Step 2: Authenticate and select your Microsoft Ads account (Connect with Microsoft)

Click Start Authentication. You'll be redirected to log in to Microsoft Ads and accept permissions for 'Tracklution Oy' before you are redirected back to continue with the next step in Tracklution.

If you are unable to authenticate, see "If you are unable to authenticate with Microsoft Ads, try the followin g" above the admin consent link, personal account and admin role tips apply to this setup as well.

Select the Microsoft Ads account you want to connect and click Continue.

With Manual setup this step is skipped.

Step 3: Select the UET tag

Choose the UET tag the Conversions API sends events to:

• Use an existing tag: for example the tag your website or your legacy Microsoft Ads connector already uses. If the same tag also runs the UET browser pixel, Microsoft deduplicates the events by event id.
• Create a new tag: a separate tag counts its own goals independently.

With Manual setup, type the UET Tag Id (found in Microsoft Advertising under Tools → UET tags). If your container already has a connected legacy Microsoft Ads connector, you can instead pick the ad account and tag from dropdowns, or create a new tag, using that existing connection.

Click Submit.

Step 4: Conversions API token

Microsoft protects the Conversions API with a token that belongs to your UET tag. Copy it from Microsoft Advertising and paste it into Tracklution:

1. In Microsoft Advertising, open UET tags.

2. Choose Edit UET tag for your tag (the pen icon next to the tag name) and click Save and next.

3. Open Set up tagging and choose Use Conversions API.

4. Click Copy Token, then Next and Done.

5. Paste the token into the Conversions API token field in Tracklution and click Save Token.

The token looks like 12345678-abcd-1234-abcd-1234567890ab. Make sure you copy the UET tag's Conversions API token, not another key.

Step 5: Events & conversion goals

Enable each event you want to send to Microsoft Ads, choose whether it is a Primary or Secondary conversion goal, and click Create. At least one event must be enabled for the connector to become active.

• Connect with Microsoft (or Manual setup with a connected legacy connector on the same container): the conversion goals are created automatically in Microsoft Advertising when you save. They are named (CAPI) Tracklution <event> - <date>.
• If the Conversions API uses the same UET tag as your legacy connector, the existing (UET) goals are reused for the same events ("Counts on legacy goal …"). No duplicate goals are created.
• Manual setup without a Microsoft connection: the table tells you which goals to create yourself. In Microsoft Advertising, create an Event conversion goal per enabled event on the same UET tag, with the action equal to the event name shown in Tracklution (for example Purchase).

Step 6: Settings and test

Once events are enabled, the Conversions API Settings card lets you:

• ID Sync Pixel(on by default) - fires a small Microsoft ID Sync pixel on your site. Required for audiences, recommended for measurement.
• Send PageView via Conversions API (off by default) - sends page loads server-side. Only used when no UET pixel for the same tag is active on your site.
• UET Pixel (on by default) - loads the UET tag pixel for this connector on your site. Skipped automatically when the legacy connector already loads the same tag.
• Test Connection - sends a test event to Microsoft. The card also shows the last accepted event and the last error, if any.

After connecting: "Delivery deferred (warming up)"

Right after you save the token, events can show as #*Delivery deferred (warming up)"*in your container's Events view for roughly the first 20 minutes while the connection settles. This is expected: the events are retried automatically once the warm-up window has passed, and nothing needs to be done on your end. The same applies to a failed Test Connection shortly after generating the token.

Adding the Conversions API to an existing connector

If you already use the Microsoft Ads connector, nothing changes on its own: the existing Online & Offline conversion goals connector keeps delivering exactly as before, and the Conversions API is not switched on automatically.

To add it, open the Microsoft Ads connector and click Add the Conversions API in parallel (recommended), then follow the Conversions API setup steps above. Two things to decide:

• Setup method. "Connect with Microsoft" asks you to authenticate once more for the Conversions API. "Manual setup" can reuse the Microsoft connection of your existing connector to list your ad accounts and UET tags and to create the conversion goals, you only paste the Conversions API token.
• Same or separate UET tag.
  • Same tag as the legacy connector: Microsoft deduplicates the browser and server events by event id, and the existing (UET) goals count once, the Conversions API reuses them instead of creating new goals. The legacy (API) offline conversion goals still count separately. Once you are confident the Conversions API is delivering, set one goal set to Secondary or pause the Online & Offline conversion goals connector to avoid counting conversions twice.
  • Separate tag: each tag counts its own goals independently.

Both connectors can stay active side by side; the connector page shows an info banner describing how the goals are counted in your setup. Reset Conversions API only resets the Conversions API setup, it never touches the legacy connector or its conversion goals.

Online & Offline Conversion Goals Setup (legacy)

This is the original Microsoft Ads connector. In the connector page it is the section Online & Offline conversion goals.

Authenticate Microsoft Ads, click the Start Authentication button. You'll be redirected to login to Microsoft Ads and accept permissions for 'Tracklution Oy' before you are redirected back to continue with the next step in Tracklution.

Next you should select the Microsoft Ads account you want to connect. This will create a Microsoft Universal Event Tracking (UET) tag for Tracklution to use. Click Continue.

Select which events you want to send as conversion goals to Microsoft Ads. Click Create on the event you want to send. This will open up a selection where you choose whether you want the event to be a Primary or Secondary conversion goal. Make your choice and click Create again and the conversion goal will be configured with Microsoft Ads. Once connected, it'll look like this:

Enhanced Conversions

Conversions API

No manual setup is needed. Tracklution sends the hashed email address and phone number (when available) together with the Microsoft Click ID with every event, and creates the (CAPI) goals with enhanced conversions enabled whenever your Microsoft Ads account allows it.

Online & Offline conversion goals (legacy)

To add enhanced conversions to your offline conversion goals added via Tracklution, select the conversion goal inside your Microsoft Ads account and configure its settings. Here you can choose to use or not use enhanced conversions for the conversion goal.

Continue through the setup by selecting "Yes, I have the tag installed", and the manual option until you are able to save and exit. You do not need to do any actual manual installation. When you send your events to your Tracklution server, Tracklution will manage these tags for you automatically when the Microsoft Ads connector is active.

How Conversions Are Counted in Microsoft Ads

Conversions API

The Conversions API creates one conversion goal per enabled event (or reuses your existing (UET) goal when it shares the tag with the legacy connector). Each event is delivered once, server-side, with the Microsoft Click ID and hashed identifiers, and Microsoft attributes it to the ad click, view or engagement. If the UET pixel for the same tag is also active on your site, Microsoft deduplicates the browser and server events by event id, so nothing is counted twice.

Online & Offline conversion goals (legacy): two conversion lists

The legacy Tracklution Microsoft Ads integration generates two conversion goals for a single conversion action:

1. Offline Conversions: Tracklution sends conversions to Microsoft Ads via the Offline Conversions API (server-to-server). Microsoft Ads uses the Microsoft Click ID (MSCLKID) to match conversions to ad clicks.
2. UET (Universal Event Tracking) Conversions: Tracklution sends conversions through Universal Event Tracking (UET). Microsoft Ads uses available identifiers, including MSCLKID, cookies, and Enhanced Data, to match conversions to ad interactions.

Double data? Tracklution sends conversions to both goals whenever the required data is available. Since these are separate conversion goals, Microsoft Ads does not automatically deduplicate conversions between them. This means the same conversion may be reported in both goals, potentially resulting in double counting.

Note: The newer Microsoft Conversions API (CAPI) integration uses a single Online conversion goal. When the same event is sent through both the UET pixel and CAPI, Microsoft Ads deduplicates it using the Event ID.

Troubleshooting

My account is unable to open the login when I try to activate the Microsoft Ads connector.

-> The Microsoft Entra (Azure AD) tenant must have the Microsoft Advertising API service principal registered. This is a prerequisite before any user in that tenant can consent to apps requesting Microsoft Advertising API permissions. The admin needs to create the service principal for Microsoft Advertising API in their tenant.

I can open the login, but the authentication fails or the consent is blocked

→ See"Authenticating with Microsoft Ads (both setups)": grant admin consent directly, use a personal Microsoft account, or verify your Microsoft Entra admin role. This applies to both the Conversions API and the legacy connector.

The Conversions API token is rejected (401).

→ Either the token does not belong to the UET tag you selected in Tracklution, or it was generated less than 15 minutes ago and has not activated yet. Check that you copied the token of the right tag and try again in a few minutes.

My events show "Delivery deferred (warming up).

→ Expected for roughly the first 20 minutes after saving the token. The events are retried automatically; no action needed.

Test Connection fails right after setup.

-> After creating a UET tag or a Conversions API token, it can take Microsoft up to 15 minutes to start accepting events. Retry after a while before changing anything.

Auto-tagging of msclkid is disabled for this Microsoft Ads account.

→ Enable auto-tagging in Microsoft Advertising so click IDs reach your site and Microsoft can attribute the conversions.

Your Microsoft authentication for the Conversions API has expired.

-> Click Re-authenticate in the connector.

The Microsoft Ads connection this connector was using is no longer available.

→ Shown for example when the legacy connector the Conversions API borrowed its connection from has been reset. Event delivery continues normally on the saved token; click Connect with Microsoft to restore automatic goal creation and token management.