Microsoft Advertising — UET and Conversions API

Server-side conversion uploads to Bing Ads through Beaconry's OAuth broker. The broker holds the central Microsoft Developer Token, you connect your account in two minutes via the standard Microsoft consent screen.

Why a broker

The Microsoft Advertising API requires a Developer Token on every conversion upload. Approval takes two to four weeks. Beaconry runs a central Cloudflare Worker (the same one used for Google Ads OAuth) that holds an approved Developer Token for you. You connect your own Microsoft account via OAuth and the broker proxies the OfflineConversions calls. Refresh tokens stay in the broker's KV, the plugin only stores a HMAC-signed site-bearer.

What you'll need

• A Microsoft Advertising account with Super Admin or Standard User role.
• A Microsoft account (work, school or personal MSA) that can sign in to Microsoft Advertising.
• About 5 minutes.

1. Connect with Microsoft Advertising

WordPress Admin → Beaconry → Tracking → Microsoft Ads. Click Connect Microsoft account. You're redirected to login.microsoftonline.com.

Sign in with the Microsoft account that has access to your Microsoft Advertising data. Approve the requested scope (msads.manage + offline_access) on the consent screen. Microsoft redirects back to the Tracking tab and the broker stores the refresh-token under an opaque site-id. Beaconry holds only the resulting site-bearer, encrypted at rest with AES-256-GCM.

The broker uses Microsoft Identity Platform v2.0 on the multi-tenant /common endpoint, so both work or school AAD accounts and personal MSAs (the most common Bing Ads case) work.

2. Find your Customer ID and Account ID

Microsoft Advertising uses two numeric IDs to address an account, both required.

• Open Microsoft Advertising at ads.microsoft.com.
• Top-right account switcher shows your Customer ID (the parent customer / manager scope).
• Below it, the Account ID for the actual Bing Ads account that runs your campaigns.
• Paste both into Beaconry → Customer ID and Account ID on the Tracking tab. Both are 6 to 12 digit numerics, Beaconry strips any formatting characters automatically.

3. Create conversion goals in Microsoft Ads

Microsoft addresses conversions by goal name, not by numeric ID. You name a goal once in the Microsoft Advertising UI and reference it as a string from Beaconry.

• Microsoft Advertising → Tools → Conversion tracking → Conversion goals → Create conversion goal.
• Goal type: Offline conversion. Not "Event" — that one wires up only the browser UET tag.
• Pick a category that matches the event (Purchase, Add to cart, Begin checkout, Lead, Subscribe, Schedule, Sign up, Contact).
• Set the value model and attribution windows per Microsoft's recommendation.
• Save. Note the goal name string exactly as you typed it — Beaconry references it case-sensitively.

4. Map the goals to Beaconry's event slots

Beaconry has eight slots, one per conversion type. Paste the matching goal-name string into each slot you actually want to track. Leave the others empty.

5. Send a test event

Save the form, click Send Microsoft Ads test event. Beaconry posts a synthetic conversion through the broker. HTTP 200 with no error means the bearer, the IDs and at least one goal name are valid.

Microsoft Advertising does not have a real-time test view comparable to Meta's Test Events. Live conversions surface in Tools → Conversion tracking within ~3 hours.

About the click identifier

Microsoft requires a msclkid (Microsoft Click ID) on every offline conversion to attribute it back to the originating ad. Bing search ads append ?msclkid=... to every click landing URL automatically. Beaconry captures it on first page-load and persists it in the nl_ext cookie alongside gclid, fbclid and ttclid. Conversions without a captured msclkid are silently skipped, that's how Microsoft's API is designed.

Hybrid mode — UET tag

Hybrid mode loads the Microsoft Universal Event Tracking (UET) tag in the browser alongside the server-side dispatch. Beaconry sends the same per-event eventId string from both sides so Microsoft can deduplicate (UET supports event-level dedup since 2024). Better match-rate, slightly more bytes shipped to the visitor. Off by default.

Toggle in Beaconry → Tracking → Microsoft Ads → Hybrid mode. You also need to enter your UET Tag ID (the numeric value Microsoft shows in Tools → UET tag).

What ships automatically

• WooCommerce funnel: AddToCart, InitiateCheckout, Purchase, with order value and currency.
• Form leads: Kadence Blocks Form and Fluent Forms submissions mapped to the Lead slot.
• msclkid capture from URL parameters on Bing-ad-click landings, persisted in nl_ext.
• Hashed PII (email, phone) sent server-side per Microsoft's enhanced-conversions guidelines.
• Stable per-order event IDs for hybrid-mode UET deduplication.

Troubleshooting

• "AuthenticationTokenExpired": the broker auto-refreshes access tokens, but the underlying refresh-token expires after 90 days of inactivity. Click Disconnect, then Connect Microsoft account again. Your Customer ID, Account ID and goal-name slots stay configured.
• Conversions uploaded but counter stays at zero: the goal name in Beaconry does not match the goal name in Microsoft Advertising exactly (case-sensitive, including spaces). Recheck both sides.
• "MicrosoftClickId required": the visitor landed without an msclkid. Direct visits and visits from non-Bing sources don't have one, that's expected. Only Bing ad clicks attribute back.
• "Customer not authorized": the Microsoft account you connected has no role on the Customer ID you entered. Reconnect with an account that has Super Admin or Standard User access on that customer.