Microsoft Ads Integration

Server-side conversion forwarding to Microsoft Advertising via the Offline Conversions API (opens in a new tab). Convultra authenticates with OAuth 2.0, maps your tracked events to Microsoft Ads conversion goals, and delivers them directly to Microsoft's servers — bypassing ad blockers, cookie restrictions, and browser-based tracking limitations.

Requirements

Requirement	Details
Microsoft Advertising account	With access to at least one ad account.
Convultra SDK	Installed and tracking events on your site.
UET tag (recommended)	A Universal Event Tracking tag for your account. Required if you want Microsoft to correlate offline conversions with on-site behavior.
Enhanced Conversions (optional)	Requires your SDK calls to include user data (`email`, `phone`, etc.).

You do not need to manually configure API credentials. Convultra handles authentication through OAuth and manages token refresh automatically.

Setup

Navigate to Integrations

Go to Dashboard → Integrations and click Connect on the Microsoft Ads card.

Complete OAuth Flow

A Microsoft sign-in window opens. Sign in with the Microsoft account that has access to your Microsoft Advertising account. Convultra requests the necessary permissions to manage conversions on your behalf.

OAuth tokens are stored encrypted and refresh automatically in the background.

💡

If you manage multiple Microsoft accounts, make sure you sign in with the one that has access to the correct Microsoft Advertising account.

Select Microsoft Ads Account

After authentication, Convultra lists all Microsoft Advertising accounts accessible to the authenticated user. Select the account you want to connect.

You can connect multiple accounts — each is configured independently with its own conversion mapping, UET tag configuration, and settings.

Configure UET Tag (Optional, Recommended)

Enter your UET tag ID to link server-side conversions with on-site tracking data. This allows Microsoft to correlate offline conversion uploads with user sessions tracked by the UET tag.

UET Tag ID: 12345678

You can find your UET tag ID in Microsoft Advertising under Tools → UET tag.

⚠️

Without a UET tag configured, Microsoft cannot correlate server-side conversions with on-site user behavior. The UET tag is recommended for the best attribution accuracy.

Map Conversion Goals

Map each Convultra event type to a Microsoft Ads conversion goal. This tells Convultra which goal to target when forwarding each event.

Convultra Event	Example Microsoft Ads Conversion Goal
`purchase`	Purchase
`lead`	Lead Form Submit
`signup`	Account Registration
`subscription`	Subscription
Custom events	Any custom conversion goal

Events that are not mapped will not be forwarded. You can update mappings at any time without disconnecting.

Enable Enhanced Conversions (Optional)

Toggle on Enhanced Conversions to send hashed customer data alongside conversions. This improves Microsoft's ability to match offline conversions to ad clicks.

When enabled, Convultra sends SHA-256 hashed PII from your SDK calls:

Set user data for the session before tracking:

Convultra.enhance({
  email: '[email protected]',
  phone: '+1234567890',
  address: {
    first_name: 'Jane',
    last_name: 'Doe',
    street: '123 Main St',
    city: 'Austin',
    region: 'TX',
    postal_code: '78701',
    country: 'US'
  }
});
 
Convultra.trackPurchase({
  value: 79.99,
  currency: 'USD',
  transaction_id: 'TXN-55555'
});

All PII is hashed with SHA-256 before leaving the browser.

Test with Test Center

Click Send Test Conversion to verify the integration end-to-end. Convultra sends a test event to the Microsoft Ads Offline Conversions API and reports the result.

A green confirmation shows the conversion goal name, timestamp, and Microsoft's response. Your integration is ready for production.

Done

Conversions are now forwarded automatically. No further action required.

Click ID

Convultra automatically captures Microsoft's click identifier from your landing page URLs:

Click ID	Parameter	Description
msclkid	`?msclkid=...`	Microsoft click identifier. Appended to URLs when users click on Microsoft Ads (Bing, Edge, Outlook, etc.).

The SDK captures msclkid from the URL on page load and includes it in every conversion forwarded to Microsoft for accurate click-to-conversion attribution.

You do not need to parse or store the msclkid yourself. Convultra handles capture, storage, and forwarding automatically.

Conversion Forwarding

When a tracked event fires and matches a mapped conversion goal, Convultra forwards it to the Microsoft Ads Offline Conversions API with the following data:

{
  "conversionName": "Purchase",
  "conversionTime": "2025-01-15T14:30:00-06:00",
  "conversionValue": 79.99,
  "conversionCurrency": "USD",
  "microsoftClickId": "abc123def456...",
  "externalAttributionModel": "LastTouch",
  "hashedEmailAddress": "a1b2c3d4e5f6...",
  "hashedPhoneNumber": "7a8b9c0d1e2f..."
}

Automatic retry — Failed deliveries are retried with exponential backoff.
Deduplication — Conversions are deduplicated by transaction_id to prevent double-counting.

Forward Logs

Navigate to the Forward Logs tab within the Microsoft Ads integration to inspect every forwarded conversion:

Field	Description
Timestamp	When the conversion was forwarded
Conversion goal	The mapped Microsoft Ads conversion goal name
Event data	Value, currency, transaction ID
Click ID	The `msclkid` used for attribution
Delivery status	`delivered`, `pending`, `failed`, or `retrying`
Error details	Microsoft API error code and message (if any)

Multi-Account Support

Connect multiple Microsoft Advertising accounts from the Integrations page. Each account has independent:

Conversion goal mappings
UET tag configuration
Enhanced Conversions settings
Forward Logs
Test Center

This is useful for agencies or businesses that run campaigns across multiple Microsoft Ads accounts.

UET Tag Integration

The Universal Event Tracking (UET) tag is Microsoft's browser-based tracking snippet. When you configure a UET tag ID in Convultra:

Server-side conversions are linked to on-site UET tracking data.
Microsoft can correlate the offline conversion upload with the user's browsing session.
Attribution accuracy improves because Microsoft has both client-side and server-side signals.

If you are not using a UET tag at all, Convultra can still forward conversions using the msclkid alone, but attribution may be less precise.

Troubleshooting

Problem	Solution
No conversion goals in dropdown	Create conversion goals in Microsoft Advertising first (Tools → Conversion goals).
Permission denied errors	Verify the connected Microsoft account has the correct access level for the selected ad account.
Conversions not appearing in Microsoft Ads	Microsoft can take up to 24-48 hours to process offline conversion uploads. Check Forward Logs for delivery confirmation.
OAuth token errors	Disconnect and reconnect the integration from Dashboard → Integrations.
Invalid UET tag error	Verify the UET tag ID in Microsoft Advertising under Tools → UET tag.
Test conversion fails	Check Forward Logs for the specific error. Verify conversion mapping and account permissions.

Meta (Facebook)Google Search Console