S2S Integration — Upload revenue to Bing Ads with JavaScript

Find out how to interact with Bing Ads API without an SDK

Image for post
Image for post
Photo by Campaign Creators on Unsplash

If you are using Bing to advertise your product or generate leads, you might want to use Bing Ads platform to track conversion and revenue. You can add revenue manually or through an excel bulk upload but as your company grows, you are more likely to look into automation by using an API.

The Bing Ads API uses Simple Object Access Protocol (or SOAP) requests and responses, an XML message which looks like this:

Not great.

To facilitate the implementation of Bing Ads APIs in your application, Microsoft provides a Software Development Kit (or SDK) for several languages (C#, Java, PHP, and Python), which means you don’t have to write any SOAP request. Unfortunately, there is no SDK available for JavaScript, so we will have to make peace with SOAP requests.

I’m going to use Postman, a great tool to test APIs without writing a single line of code, to show you how you can use Bing Ads API without an SDK.

I. Getting Started

What you need to get started:

  • Microsoft Ads account (sign in here: https://ads.microsoft.com/)
  • Access to the Azure portal
  • A valid Microsoft click id (a unique 32 characters long GUID generated when an ad is clicked)
  • Basic understanding of Postman

II. Create an Offline Conversion Goal

To be able to upload revenue, you first need to create a conversion goal with a unique name. Go to Microsoft Ads platform, open the campaign for which you want to upload revenue, and click on Tools > Conversion tracking > Conversion Goal.

Click on Create Conversion Goal, enter a unique name, and select Offline Conversions. Click on Next and fill in your preferences. For more details on the possible options, check out Microsoft documentation here.

Once created, note that you will have to wait 2 hours before uploading revenue against this conversion goal.

III. Authenticate and get and access token

Every time you send a request to the API, you need to use a short-lived access token (typically expires in 60 minutes).

There are 2 ways to get an access token:

  • Live Connect
  • Microsoft identity platform

Microsoft recommends using the Microsoft identity platform so I will use this method to authenticate. If you get stuck in one of the below steps, don’t hesitate to check the official documentation here.

1. Register your application

First, register your application in the Azure Portal by clicking on New Registration. Once you registered your application, it will generate an application id also called client id (eg: 6731de76–14a6–49ae-97bc-6eba6914391e) which you will need for the next step.

Select the Add a redirect URI link and make sure to select at least the redirect URI: https://login.microsoftonline.com/common/oauth2/nativeclient.

2. Request user consent

You need to provide consent for your application by generating an authorization code. Copy the below URL and fill in your client id.

Paste the URL in your browser (note that this won’t work through Postman). It will prompt you to the Microsoft login portal where you’ll need to authenticate and consent permission for your app to manage your Microsoft accounts. Once done, you should be redirected to a blank page with an authorization code in the URL:

Save that authorization code for the next step. Note that it will expire after a few minutes.

3. Get a Refresh Token

Create a Postman POST request to https://login.microsoftonline.com/common/oauth2/v2.0/token/

Selected body x-www-form-urlencoded and fill with the following values:

  • client_id: your client id
  • code: the authorization code obtained earlier
  • grant_type: code
  • redirect_uri: https://login.microsoftonline.com/common/oauth2/nativeclient
  • scope: https://ads.microsoft.com/ads.manage offline_access
  • tenant: common
Image for post
Image for post

Hit Send. You should get back an access token and a refresh token.

4. Refresh the access token

The access token generated above will only last for 60 minutes.

To refresh your access token, create a Postman POST request to https://login.microsoftonline.com/common/oauth2/v2.0/token/

Selected body x-www-form-urlencoded and fill with the following values:

  • client_id: your client id
  • refresh_token: your refresh token
  • grant_type: refresh_token
  • redirect_uri: https://login.microsoftonline.com/common/oauth2/nativeclient
  • scope: https://ads.microsoft.com/ads.manage offline_access
  • tenant: common
Image for post
Image for post

Hit Send. You should get back a new access token. As the refresh token is long-lived, you should be able to reuse this request every time you need a new access token.

IV. ApplyOfflineConversions

Now that you have your access token, you can finally interact with Bing Ads API! We are close to making our first revenue upload!

Create a new Postman POST request to https://campaign.api.bingads.microsoft.com/Api/Advertiser/CampaignManagement/V13/CampaignManagementService.svc?singleWsdl

Set the headers to:

  • Content-Type: text/xml;charset=utf-8
  • SOAPAction: ApplyOfflineConversions

In body, select the type “raw” and “XML”. Copy the request SOAP template provided in Microsoft’s documentation, paste it in the body of your Postman request and fill in the missing values:

Envelope headers:

  • AuthenticationToken: access token from Part III
  • CustomerAccountId and CustomerId: you can find it on Microsoft Ads web application’s url when selecting an account: https://ui.ads.microsoft.com/campaign/vnext/overview?cid=CustomerIdHere&aid=CustomerAccountIdHere
    You can also call GetUser and GetAccountInfo to obtain it through an API request.
  • Your developer token: more info here

Envelope body:

  • Currency Code (eg: GBP)
  • Conversion Name: the name you gave to the conversion goal in Part II
  • Conversion Time: a date and time value (eg: 2021–01–27T15:13:13+00:00). Make sure the date and time value is later than the date and time of the recorded click and is within the conversion window (max 90 days from click).
  • ConversionValue: revenue generated
  • MicrosoftClickId: make sure the click id has been generated from the account id set in the header CustomerAccountId.

It should look like the below (with your account ids and tokens filled in of course):

Image for post
Image for post

Hit Send. You should get back a response with an empty PartialErrors tag.
The revenue will show up in Tools>Conversion Tracking > Conversion Goals within 5 hours.

Wrapping Up

I hope this article gave you an idea of how to use Bing Ads APIs without an SDK. Do not hesitate to leave a comment if you have a question and I’ll try my best to help you. Otherwise, you can ask a question on Microsoft Developer Forum.

JavaScript Mid-Level Developer, I write blogs to learn and share what I learn.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store