> For the complete documentation index, see [llms.txt](https://docs.adpage.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.adpage.io/integrations-marketingtools/microsoft-ads.md).

# Microsoft Ads

Configure the Microsoft UET tag and Conversions API with event ID deduplication.

Set up the Microsoft UET tag in the web container first. Then send matching events through the Microsoft Conversions API (CAPI) from the server container.

Both tags send the same conversion. Give both the same UET Tag ID, the same event name and the same event ID. Microsoft can then deduplicate the events and count one conversion.

This hybrid setup is what Microsoft recommends. UET captures browser context such as the click ID and page details. CAPI adds a server-side path that is not affected by ad blockers and browser cookie restrictions, and that can also report conversions that happen later, outside the browser.

{% hint style="info" %}
This page covers **tracking**: sending conversions to Microsoft Ads. To get Microsoft cost and conversion data into AdPage reports and the Marketing Mix Model, see [Microsoft Advertising](https://claude.ai/data-and-insights/marketing-integrations/microsoft-advertising).
{% endhint %}

#### What you'll configure

You will create:

* A Microsoft UET tag setup in the GTM web container, with consent mode.
* A **Microsoft Ads UET Conversion API** tag in the GTM server container.
* One shared `event_id` for each matching browser and server event.

Use this page for the complete implementation. See also:

* [Where to find the UET Tag ID, Customer ID and API token](https://docs.adpage.io/integrations-marketingtools/microsoft-ads/where-to-find-the-uet-tag-id-customer-id-and-api-token.md)
* [Microsoft Ads event ID deduplication](https://docs.adpage.io/integrations-marketingtools/microsoft-ads/microsoft-ads-event-id-deduplication.md)
* [Click ID, cookies and consent](https://docs.adpage.io/integrations-marketingtools/microsoft-ads/click-id-cookies-and-consent.md)
* [Webhook and offline conversions](https://docs.adpage.io/integrations-marketingtools/microsoft-ads/webhook-and-offline-conversions.md)

#### Before you start

Make sure you have:

* [ ] &#x20;A GTM web container with GA4 event tags.
* [ ] A GTM server container that receives the GA4 events.
* [ ] The **UET Tag ID**, the **Conversions API token** and the **Customer ID** from Microsoft Advertising. See [Where to find the UET Tag ID, Customer ID and API token](https://docs.adpage.io/integrations-marketingtools/microsoft-ads/where-to-find-the-uet-tag-id-customer-id-and-api-token.md).
* [ ] At least one **conversion goal** in Microsoft Advertising that uses this UET tag.
* [ ] A **Unique Event ID** variable in the web container.
* [ ] Auto-tagging enabled in Microsoft Advertising, so ad clicks carry `msclkid` in the landing page URL.

{% hint style="warning" %}
The API token belongs to one specific UET tag. Use the token and the Tag ID of the same tag, in both containers. A token generated for a different UET tag returns `401 Unauthorized`.
{% endhint %}

### Part 1: Set up client-side tracking

#### **Step 1: Create a UET Tag ID variable**

1. Open your GTM web container and go to **Variables**.
2. Create a **Constant** variable.
3. Set its value to the UET Tag ID and save it.

#### **Step 2: Create the UET base tag**

1. Go to **Tags** and create a new tag.
2. Choose **Microsoft Advertising Universal Event Tracking** as the tag configuration. If it is not available yet, add it from the **Community Template Gallery**.
3. Select your UET Tag ID variable.
4. Set the tag type to **Page view**.
5. Use the trigger you use for all pages (Page View or `cookie_consent_update`).

#### **Step 3: Configure UET consent mode**

Microsoft requires UET consent mode for visitors in the EEA, the UK and Switzerland. UET reads one signal, `ad_storage`. It must default to `denied` and update to `granted` only when the visitor accepts marketing cookies.

Open the consent settings in the UET tag and enable the options that take over the GTM consent state and listen for consent updates. This only works when your CMP sets the Google Consent Mode default to `denied` before the UET tag loads. See [Consent Management](https://docs.adpage.io/optimize-your-setup/consent-management.md).

Details and alternatives are on [Click ID, cookies and consent](https://docs.adpage.io/integrations-marketingtools/microsoft-ads/click-id-cookies-and-consent.md).

#### **Step 4: Create the conversion tags**

1. Create a new **Microsoft Advertising Universal Event Tracking** tag.
2. Select your UET Tag ID variable.
3. Set the tag type to a **custom event** and fill in the **Event Action** that your conversion goal in Microsoft Advertising expects, for example `purchase`.
4. For a purchase, add the revenue value and currency.
5. Add a custom parameter named `event_id`:
   * For a purchase, use the order ID.
   * For all other events, use your Unique Event ID variable.
6. Use the same trigger as the matching GA4 event tag.

Repeat this for every event you want to track.

{% hint style="info" %}
Why the order ID for purchases? A purchase can reach the server container from the browser or from a shop webhook. The order ID is the only value both routes know. See [Microsoft Ads event ID deduplication](https://docs.adpage.io/integrations-marketingtools/microsoft-ads/microsoft-ads-event-id-deduplication.md).&#x20;
{% endhint %}

#### **Step 5: Pass the event ID to GA4**

Add the same event ID to every matching GA4 event tag:

1. Open the GA4 event tag.
2. Add an event parameter named `event_id`.
3. Set its value to the same variable you used in the UET tag for that event.
4. Save the tag.

The server container can now read the event ID from the GA4 event.

### Part 2: Set up server-side tracking

#### **Step 6: Add the Conversions API template**

1. Open your GTM server container and go to **Templates**.
2. Under **Tag Templates**, click **Search Gallery**.
3. Add the **Microsoft Ads UET Conversion API** template by Stape.

#### **Step 7: Store the credentials**

Create two **Constant** variables in the server container: one for the UET Tag ID and one for the Conversions API token. You then only have one place to change them.

#### **Step 8: Create the server-side tag**

1. Create a new **Microsoft Ads UET Conversion API** tag.
2. Under **Event Type Setup Method**, choose **Inherit from client**. Choose **Standard** only when you need to set the event type and name by hand.
3. Fill in the **UET Tag ID** and **Authorization Token** variables.
4. Enable **Client-Side ID Sync** and fill in the **Customer ID**. This is not the UET Tag ID.
5. Leave **Use Optimistic Scenario** off. With it on, the tag always reports success, even when Microsoft rejects the request.
6. Add the **User Data Parameters** you have, at least one. Email and phone are hashed by the tag.
7. Keep **Auto-mapping** enabled under **Server Event Data Parameters** and **Event Parameters**.

#### **Step 9: Pass the event ID to Microsoft**

1. Create an **Event Data** variable with key path `event_id`.
2. Open the Microsoft Ads UET Conversion API tag.
3. Under **Server Event Data Parameters**, add **Event ID**.
4. Set its value to the `event_id` variable.

#### **Step 10: Configure consent and the trigger**

The Conversions API treats every event as consented unless it is told otherwise. Gate the tag so it only fires for visitors who accepted marketing cookies:

* Add the consent condition from [Consent Management, step 3](https://docs.adpage.io/optimize-your-setup/consent-management.md#step-3-configure-server-side-triggers-based-on-consent) to the trigger.
* Under **Server Event Data Parameters**, set the **Ad Storage Consent** parameter to granted for these events.

Create a trigger for the events you want to send. Use both conditions:

* `{{Event Name}}` matches RegEx `page_view|purchase` (extend this with your other events).
* `{{Client Name}}` equals `GA4`.

Send `page_view` as well as your conversions. Page load events are what Microsoft uses for destination URL goals and remarketing.

{% hint style="info" %}
The UET tag and the Conversions API tag must use the same UET Tag ID, event name and event ID. A difference in any of the three prevents deduplication.
{% endhint %}

### Test and validate the complete setup in preview mode

Before you publish, confirm that the click ID reaches the server container and that the Conversions API tag forwards it to Microsoft.

{% hint style="danger" %}
The Microsoft Conversions API has no test mode. Every event you send during testing is recorded as a real event. Test with a small number of conversions and keep track of them.&#x20;
{% endhint %}

**Prepare the test**

1. Open a fresh browser session. Connect GTM preview mode for both the web container and the server container.
2. Work in a separate workspace.
3. Open a landing page with a test click ID, for example `https://yourdomain.com/?msclkid=0123456789abcdef0123456789abcdef`. A real `msclkid` is a 32-character hexadecimal string. You can also click a live ad.

**Where to look in server preview**

| Location                        | What to check                                                                                                                                                                                                                                       |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Incoming request (client)       | The `cookie` header contains `_uetmsclkid` and `_uetvid` from the UET tag, or `uet_msclkid` and `uet_vid` set by the server tag. If they are missing, the server container probably does not run on a first-party domain of the website.            |
| Event Data                      | `page_location` contains `msclkid` on the landing page. `event_id` is present. The consent state shows marketing consent granted.                                                                                                                   |
| Microsoft tag → Request         | The URL is `https://capi.uet.microsoft.com/v1/<UET-TAG-ID>/events`. The `Authorization` header uses the Bearer scheme. The body contains `eventType`, `eventId`, `eventName`, `eventTime` and a `userData` object with `msclkid` and `anonymousId`. |
| Microsoft tag → Response        | Status `200`. A `401` means the token and Tag ID do not belong together. A `400` lists the failing field.                                                                                                                                           |
| Browser → Application → Cookies | `uet_msclkid` and `uet_vid` exist with the expected domain and expiry.                                                                                                                                                                              |

**Run the test scenarios**

| # | Scenario                                                          | Expected result                                                                                                                                                       |
| - | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | Landing page with `msclkid` in the URL, marketing consent granted | The first event contains `msclkid`, equal to the URL value without hyphens. The `uet_msclkid` cookie is set.                                                          |
| 2 | Second page view without `msclkid` in the URL                     | `msclkid` comes from the cookie and has the same value.                                                                                                               |
| 3 | Second ad click with a different `msclkid`                        | The new value is sent and the cookie is overwritten.                                                                                                                  |
| 4 | Direct visit without `msclkid`                                    | `msclkid` is omitted from the body. It is not an empty string.                                                                                                        |
| 5 | Marketing consent denied                                          | No request goes to Microsoft and the UET tag stays in denied mode.                                                                                                    |
| 6 | Consent given after the landing page loaded                       | The first Microsoft event after the consent update still contains `msclkid` from the landing page URL.                                                                |
| 7 | UET and Conversions API together                                  | Both send the same event name and event ID, so only one conversion counts.                                                                                            |
| 8 | Purchase sent from a shop webhook                                 | No browser cookies are available. See [Webhook and offline conversions](https://claude.ai/integrations-marketingtools/microsoft-ads/webhook-and-offline-conversions). |

**Check the response for warnings**

A `200` response does not mean every field was accepted. Microsoft removes optional fields it cannot use, such as an invalid hash or currency, and still accepts the event. Open the response body in preview. Every entry with `isWarning: true` is a field that did not reach Microsoft.

**Check the result after publishing**

In the outgoing request logs, confirm that:

* Landing pages with `msclkid` in the URL carry `msclkid` in the request body.
* Follow-up page views carry the same value.
* Purchases carry the same `eventId` as the order ID.
* The number of non-2xx responses does not increase.

In Microsoft Advertising, conversions can take several hours to appear in the conversion goal columns.

{% hint style="warning" %}
Only send the click ID, hashed emails and cookie values for visitors who granted marketing consent.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.adpage.io/integrations-marketingtools/microsoft-ads.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
