Manage ad campaigns
Use these methods in the Microsoft Store promotions API to create, edit and get promotional ad campaigns for your app. Each campaign you create using this method can be associated with only one app.
Note You can also create and manage ad campaigns using Partner Center, and campaigns that you create programmatically can be accessed in Partner Center. For more information about managing ad campaigns in Partner Center, see Create an ad campaign for your app.
When you use these methods to create or update a campaign, you typically also call one or more of the following methods to manage the delivery lines, targeting profiles, and creatives that are associated with the campaign. For more information about the relationship between campaigns, delivery lines, targeting profiles, and creatives, see Run ad campaigns using Microsoft Store services.
- Manage delivery lines for ad campaigns
- Manage targeting profiles for ad campaigns
- Manage creatives for ad campaigns
Prerequisites
To use these methods, you need to first do the following:
If you have not done so already, complete all the prerequisites for the Microsoft Store promotions API.
Note As part of the prerequisites, be sure that you create at least one paid ad campaign in Partner Center and that you add at least one payment instrument for the ad campaign in Partner Center. Delivery lines for ad campaigns you create using this API will automatically bill the default payment instrument chosen on the Ad campaigns page in Partner Center.
Obtain an Azure AD access token to use in the request header for these methods. After you obtain an access token, you have 60 minutes to use it before it expires. After the token expires, you can obtain a new one.
Request
These methods have the following URIs.
Method type | Request URI | Description |
---|---|---|
POST | https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign |
Creates a new ad campaign. |
PUT | https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/{campaignId} |
Edits the ad campaign specified by campaignId. |
GET | https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/{campaignId} |
Gets the ad campaign specified by campaignId. |
GET | https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign |
Queries for ad campaigns. See the Parameters section for the supported query parameters. |
Header
Header | Type | Description |
---|---|---|
Authorization | string | Required. The Azure AD access token in the form Bearer <token>. |
Tracking ID | GUID | Optional. An ID that tracks the call flow. |
Parameters
The GET method to query for ad campaigns supports the following optional query parameters.
Name | Type | Description |
---|---|---|
skip | int | The number of rows to skip in the query. Use this parameter to page through data sets. For example, fetch=10 and skip=0 retrieves the first 10 rows of data, top=10 and skip=10 retrieves the next 10 rows of data, and so on. |
fetch | int | The number of rows of data to return in the request. |
campaignSetSortColumn | string | Orders the Campaign objects in the response body by the specified field. The syntax is CampaignSetSortColumn=field, where the field parameter can be one of the following strings:
The default is createdDateTime. |
isDescending | Boolean | Sorts the Campaign objects in the response body in descending or ascending order. |
storeProductId | string | Use this value to return only the ad campaigns that are associated with the app with the specified Store ID. An example Store ID for a product is 9nblggh42cfd. |
label | string | Use this value to return only the ad campaigns that include the specified label in the Campaign object. |
Request body
The POST and PUT methods require a JSON request body with the required fields of a Campaign object and any additional fields you want to set or change.
Request examples
The following example demonstrates how to call the POST method to create an ad campaign.
POST https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign HTTP/1.1
Authorization: Bearer <your access token>
{
"name": "Contoso App Campaign",
"storeProductId": "9nblggh42cfd",
"configuredStatus": "Active",
"objective": "DriveInstalls",
"type": "Community"
}
The following example demonstrates how to call the GET method to retrieve a specific ad campaign.
GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/31043481 HTTP/1.1
Authorization: Bearer <your access token>
The following example demonstrates how to call the GET method to query for a set of ad campaigns, sorted by the created date.
GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign?storeProductId=9nblggh42cfd&fetch=100&skip=0&campaignSetSortColumn=createdDateTime HTTP/1.1
Authorization: Bearer <your access token>
Response
These methods return a JSON response body with one or more Campaign objects, depending on the method you called. The following example demonstrates a response body for the GET method for a specific campaign.
{
"Data": {
"id": 31043481,
"name": "Contoso App Campaign",
"createdDate": "2017-01-17T10:12:15Z",
"storeProductId": "9nblggh42cfd",
"configuredStatus": "Active",
"effectiveStatus": "Active",
"effectiveStatusReasons": [
"{\"ValidationStatusReasons\":null}"
],
"labels": [],
"objective": "DriveInstalls",
"type": "Paid",
"lines": [
{
"id": 31043476,
"name": "Contoso App Campaign - Paid Line"
}
]
}
}
Campaign object
The request and response bodies for these methods contain the following fields. This table shows which fields are read-only (meaning that they cannot be changed in the PUT method) and which fields are required in the request body for the POST method.
Field | Type | Description | Read only | Default | Required for POST |
---|---|---|---|---|---|
id | integer | The ID of the ad campaign. | Yes | No | |
name | string | The name of the ad campaign. | No | Yes | |
configuredStatus | string | One of the following values that specifies the status of the ad campaign specified by the developer:
|
No | Active | Yes |
effectiveStatus | string | One of the following values that specifies the effective status of the ad campaign based on system validation:
|
Yes | No | |
effectiveStatusReasons | array | One or more of the following values that specify the reason for the effective status of the ad campaign:
|
Yes | No | |
storeProductId | string | The Store ID for the app that this ad campaign is associated with. An example Store ID for a product is 9nblggh42cfd. | Yes | Yes | |
labels | array | One or more strings that represent custom labels for the campaign. These labels be used for searching and tagging campaigns. | No | null | No |
type | string | One of the following values that specifies the campaign type:
|
Yes | Yes | |
objective | string | One of the following values that specifies the objective of the campaign:
|
No | DriveInstall | Yes |
lines | array | One or more objects that identify the delivery lines that are associated with the ad campaign. Each object in this field consists of an id and name field that specifies the ID and name of the delivery line. | No | No | |
createdDate | string | The date and time the ad campaign was created, in ISO 8601 format. | Yes | No |