Microsoft Advertising

Microsoft Advertising is a traffic source (search). Its own documentation: https://learn.microsoft.com/en-us/advertising/guides/.

Note

This platform sends a visitor to the ad’s final URL itself, so no visit passes through the campaign’s URL first. Tallyray protects no lander such a campaign reaches.

What it connects

• Sends your conversions back to Microsoft Advertising.
• Pulls your spend from its API.
• Pauses and resumes its campaigns, ad groups and ads.
• Sets bids on its ad groups.
• Sets daily budgets on its campaigns.
• Checks the connection with a harmless request when you test it.

How to connect it

OAuth. The workspace’s owner connects the connection: Tallyray sends them to login.microsoftonline.com to give consent to these scopes: https://ads.microsoft.com/msads.manage, offline_access. Tallyray refreshes the token. If the platform refuses a refresh for good, the connection shows as needing authorization, its deliveries wait, and its owner connects it again.

The OAuth client is the product’s own registration at the platform (microsoft-ads), so you bring no client of your own.

Set these on the connection:

Field	Name	Kind	What to enter
Customer id	customer_id	string, required	The cid in the address of Microsoft Advertising’s Campaigns page
Account id	account_id	string, required	The aid in the same address, not the account number
Account time zone	time_zone	string	For spend, your account’s time zone as an IANA name, such as America/New_York for Eastern Time; Microsoft reports by its days, and it can’t change once spend is reported
Account currency	account_currency	string	For bids and budgets, your account’s currency, such as USD, in its Accounts summary

Tracking macros

Each token is a query parameter on the campaign URL; the source replaces its macro with the value when it sends the visitor. The columns say which part of the visit it fills and which report column (v1 to v20) it lands in.

Parameter	Macro	Fills	Report column
msclkid	added by the platform itself	The source’s click id
cmp	{CampaignId}	Source campaign	v1 (Campaign)
adg	{AdGroupId}	Custom value	v2 (Ad group)
ad	{AdId}	Creative	v3 (Ad)
kw	{keyword}	Keyword	v4 (Keyword)
mt	{MatchType}	Custom value	v5 (Match type)
net	{Network}	Custom value	v6 (Network)
dev	{Device}	Custom value	v7 (Device (Microsoft))

The campaign URL you paste into the source is the tracking domain, the campaign’s key and the tokens the source fills, in this order (the domain below is an example, and {url_key} stands for the campaign’s own key):

https://trk.example.com/{url_key}?cmp={CampaignId}&adg={AdGroupId}&ad={AdId}&kw={keyword}&mt={MatchType}&net={Network}&dev={Device}

Cost models, the first the default: api (the spend pulled from the source’s API), cpc (cost per click).

Preview the campaign URL

Your tracking domain

Campaign URL

https://trk.example.com/{url_key}?cmp={CampaignId}&adg={AdGroupId}&ad={AdId}&kw={keyword}&mt={MatchType}&net={Network}&dev={Device}

Copy

Paste the campaign URL into the source's ad. {url_key} stands for the campaign's own key, which the portal fills in; the macros are the source's, which it replaces with each visit's values.

How conversions get back to it

Tallyray sends a conversion to Microsoft Advertising when it enters one of these statuses: approved. A conversion is sent once per status it enters; an adjustment, with revenue moving and its status not, isn’t sent. A conversion older than 90d isn’t sent.

Tallyray’s event kinds, and the name each is sent as. A conversion of a kind not listed isn’t sent:

Tallyray event	Sent to Microsoft Advertising as
lead	lead
registration	registration
sale	sale
deposit	deposit
subscription	subscription

The request: POST https://campaign.api.bingads.microsoft.com/CampaignManagement/v13/OfflineConversions/Apply (in batches, up to 1000 conversions each).

A conversion is sent only when this holds:

=visit.external_click_id != '' || conv.user.em != '' || conv.user.ph_e164 != ''

This template sends personal data, so it honors consent: for a visit from the EEA, the UK or Switzerland without ad_user_data granted, the conversion goes without anything personal, including the platform’s click id, and is not sent when nothing is left to match on. An explicit denial withholds the person’s hashed identifiers wherever the visit came from.

Conversions are retried when the source can’t be reached or answers with an error that can pass; see the limits below.

Spend

Tallyray pulls spend from the source’s API every 3h, covering the last 3d again, as sources restate spend, 7d at most per request, by day, in the zone =conn.time_zone != '' ? conn.time_zone : 'set the account time zone'. The source builds an asynchronous report first. With api among the cost models, a campaign is priced by it.

Pulling spend needs the API’s credential. A connection without it goes on sending conversions and pulls no spend.

Pausing and resuming

Rules and reports can pause and resume the source’s own objects at these levels. Tallyray reads an object before it writes, and writes only what isn’t so already, so a repeated pause never toggles anything.

Level	Named by
campaigns	cmp
ad groups	cmp + adg
ads	adg + ad

A write may take up to 2m to show in a read; a read within that time that disagrees is read again later, not taken for a person’s change at the source.

Bids

Rules and reports can set the source’s bids at these levels. Each value is read before it’s written, in the account’s currency, never converted; a value the source sets itself isn’t written.

Level	Named by	Prices	Bounds	Notes
ad groups	cmp + adg	cpc	step minor

Daily budgets

Rules and reports can set the source’s daily budgets at these levels, read before they’re written, in the account’s currency.

Level	Named by	Prices	Bounds	Notes
campaigns	cmp	daily	step minor

Limits

• Rate: at most 5/s per connection, 2 at once.
• Retries: up to 15 attempts, waiting from 1m and doubling up to 6h, longer when the source’s Retry-After asks, and never past the conversion’s age limit.
• Hosts it reaches: login.microsoftonline.com, campaign.api.bingads.microsoft.com, reporting.api.bingads.microsoft.com, bingadsappsstorageprod.blob.core.windows.net. No other.
• What a connection may override: /conversions/events, /conversions/send_on, /tokens. Hosts, authentication and requests never are, and an override may only lower the limits.

This page describes version 2 of the Microsoft Advertising template, the latest published. The version your connection runs is the one your administrators approved, and the portal shows it.