Edit

Manage delivery lines

  • Article

Use these methods in the Microsoft Store promotions API to create one or more delivery lines to buy inventory and deliver your ads for a promotional ad campaign. For each delivery line, you can set targeting, set your bid price, and decide how much you want to spend by setting a budget and linking to creatives you want to use.

For more information about the relationship between delivery lines and ad campaigns, targeting profiles, and creatives, see Run ad campaigns using Microsoft Store services.

Note  Before you can successfully create delivery lines for ad campaigns using this API, you must first create one paid ad campaign using the Ad campaigns page in Partner Center, and you must add at least one payment instrument on this page. After you do this, you will be able to successfully create billable delivery lines for ad campaigns using this API. Ad campaigns you create using the API will automatically bill the default payment instrument chosen on the Ad campaigns page in Partner Center.

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 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/line Creates a new delivery line.
PUT https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/{lineId} Edits the delivery line specified by lineId.
GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/{lineId} Gets the delivery line specified by lineId.
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.

Request body

The POST and PUT methods require a JSON request body with the required fields of a Delivery line 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 a delivery line.

POST https://manage.devcenter.microsoft.com/v1.0/my/promotion/line HTTP/1.1
Authorization: Bearer <your access token>

{
    "name": "Contoso App Campaign - Paid Line",
    "configuredStatus": "Active",
    "startDateTime": "2017-01-19T12:09:34Z",
    "endDateTime": "2017-01-31T23:59:59Z",
    "bidAmount": 0.4,
    "dailyBudget": 20,
    "targetProfileId": {
        "id": 310021746
    },
    "creatives": [
        {
            "id": 106851
        }
    ],
    "campaignId": 31043481,
    "minMinutesPerImp ": 1
}

The following example demonstrates how to call the GET method to retrieve a delivery line.

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/31019990  HTTP/1.1
Authorization: Bearer <your access token>

Response

These methods return a JSON response body with a Delivery line object that contains information about the delivery line that was created, updated, or retrieved. The following example demonstrates a response body for these methods.

{
    "Data": {
        "id": 31043476,
        "name": "Contoso App Campaign - Paid Line",
        "configuredStatus": "Active",
        "effectiveStatus": "Active",
        "effectiveStatusReasons": [
            "{\"ValidationStatusReasons\":null}"
        ],
        "startDateTime": "2017-01-19T12:09:34Z",
        "endDateTime": "2017-01-31T23:59:59Z",
        "createdDateTime": "2017-01-17T10:28:34Z",
        "bidType": "CPM",
        "bidAmount": 0.4,
        "dailyBudget": 20,
        "targetProfileId": {
            "id": 310021746
        },
        "creatives": [
            {
                "id": 106126
            }
        ],
        "campaignId": 31043481,
        "minMinutesPerImp ": 1,
        "pacingType ": "SpendEvenly",
        "currencyId ": 732
    }
}

Delivery line 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 or PUT methods.

Field Type Description Read only Default Required for POST/PUT
id integer The ID of the delivery line. Yes No
name string The name of the delivery line. No POST
configuredStatus string One of the following values that specifies the status of the delivery line specified by the developer:
  • Active
  • Inactive
 No POST
effectiveStatus string One of the following values that specifies the effective status of the delivery line based on system validation:
  • Active
  • Inactive
  • Processing
  • Failed
 Yes No
effectiveStatusReasons array One or more of the following values that specify the reason for the effective status of the delivery line:
  • AdCreativesInactive
  • ValidationFailed
 Yes No
startDatetime string The start date and time for the delivery line, in ISO 8601 format. This value cannot be changed if it is already in the past. No POST, PUT
endDatetime string The end date and time for the delivery line, in ISO 8601 format. This value cannot be changed if it is already in the past. No POST, PUT
createdDatetime string The date and time the delivery line was created, in ISO 8601 format. Yes No
bidType string A value that specifies the bidding type of the delivery line. Currently, the only supported value is CPM. No CPM No
bidAmount decimal The bid amount to be used for bidding any ad request. No The average CPM value based on target markets (this value is revised periodically). No
dailyBudget decimal The daily budget for the delivery line. Either dailyBudget or lifetimeBudget must be set. No POST, PUT (if lifetimeBudget is not set)
lifetimeBudget decimal The lifetime budget for the delivery line. Either lifetimeBudget* or dailyBudget must be set. No POST, PUT (if dailyBudget is not set)
targetingProfileId object On object that identifies the targeting profile that describes the users, geographies and inventory types that you want to target for this delivery line. This object consists of a single id field that specifies the ID of the targeting profile. No No
creatives array One or more objects that represent the creatives that are associated with the delivery line. Each object in this field consists of a single id field that specifies the ID of a creative. No No
campaignId integer The ID of the parent ad campaign. No No
minMinutesPerImp integer Specifies the minimum time interval (in minutes) between two impressions shown to the same user from this delivery line. No 4000 No
pacingType string One of the following values that specify the pacing type:
  • SpendEvenly
  • SpendAsFastAsPossible
 No SpendEvenly No
currencyId integer The ID of the currency of the campaign. Yes The currency of the developer account (you do not need to specify this field in POST or PUT calls) No