Managing Budgets

Budget are used to specify budget constraints for one or more Seller-Campaigns of the same Seller. You have different types of budgets :

Uncapped : Define an unlimited amount,
Capped : Define a limited amount,
Daily : Define a limited daily amount.

A Budget can specify a startDate and an endDate :

startDate: date at which you want your budget to be taken into consideration.
endDate: date until which the budget is taken into consideration.

A Budget status can be either :

Active : this budget can be consumed in one or more Seller-Campaigns for delivering ads. A budget is active when all the following conditions are met:
- the budget has not been suspended (see "Suspending budgets" section),
- the current date is between startDate and endDate,
- the spent amount of the budget is smaller than the specified amount.
Inactive : when a budget is not Active, it is Inactive. It cannot be consumed in any Seller-Campaign for delivering ads.

⚠️
Notice that there is at most one active daily budget and one active non-daily budget

Creating Budgets for Seller-Campaigns

In order to create Budgets for Seller-Campaigns, you need to make the following call:

/marketplace-performance-outcomes/budgets

Sample response

[{
    "sellerId": "1",
    "campaignIds": ["10001"],
    "budgetType": "Capped",
    "amount": 10.00,
    "startDate": "2019-05-01",
    "endDate": "2019-05-31"
},{
    "sellerId": "2",
    "campaignIds": ["10001"],
    "budgetType": "Capped",
    "amount": 20.00,
    "startDate": "2019-05-01",
    "endDate": "2019-05-31"
},{
    "sellerId": "3",
    "campaignIds": ["10001"],
    "budgetType": "Capped",
    "amount": 30.00,
    "startDate": "2019-05-01",
    "endDate": "2019-05-31"
}]

SellerId The sellerId of the Seller for which you want to create a budget.

campaignIds Array of campaignIds of the campaigns for which you want the budgets.

budgetType Type of budget. You have 3 possible values for this Uncapped, Capped, Daily.

amount Amount of money you want to specify for this budget.

startDate Date at which you want your budget to be taken into consideration.

endDate Date until which the budget is taken into consideration.

Creating Capped Budgets

When creating budgets, you have the choice between 3 different types of budgets. One of these is the capped budget, it enables you to define the maximum amount of money you would like to spend on a given time period.

Creating Uncapped Budgets

If you don't want to define a maximum amount of money you would like to spend on a given time period, you can create Uncapped budgets.

/marketplace-performance-outcomes/budgets

Sample response

[{
    "sellerId": "1",
    "campaignIds": ["10001"],
    "budgetType": "Uncapped",
    "startDate": "2019-05-01",
    "endDate": "2019-05-31"
},{
    "sellerId": "2",
    "campaignIds": ["10001"],
    "budgetType": "Uncapped",
    "startDate": "2019-05-01",
    "endDate": "2019-05-31"
},{
    "sellerId": "3",
    "campaignIds": ["10001"],
    "budgetType": "Uncapped",
    "startDate": "2019-05-01",
    "endDate": "2019-05-31"
}]

If you want to control how fast the money is spent, you can combine the Uncapped budget with a Daily budget.

Creating Daily Budgets

Additionally to the Capped and Uncapped budgets, you can define Daily budgets. This means that you can define how fast you want to spend your budget for a given time period.

📘
The Daily budget defines the maximum amount of money you would like to spend in average in the 7 last days with a maximum of 150% of the daily budget in a day.

Notice that Daily Budgets only work if you have also specified a Total budget. This Total budget is specified either by a Capped or Uncapped budget.

If you have not specified a Total budget, your Seller-Campaigns will not deliver ads (even if you specified a Daily-Budget). For example, you can create a daily Budget of $5 for the Sellers 1,2, and 3 and back them with an unlimited total budget (Uncapped Budget):

/marketplace-performance-outcomes/budgets

Sample response

[{
    "sellerId": "1",
    "campaignIds": ["10001"],
    "budgetType": "Uncapped",
    "startDate": "2019-05-01",
    "endDate": "2019-05-31"
},{
    "sellerId": "2",
    "campaignIds": ["10001"],
    "budgetType": "Uncapped",
    "startDate": "2019-05-01",
    "endDate": "2019-05-31"
},{
    "sellerId": "3",
    "campaignIds": ["10001"],
    "budgetType": "Uncapped",
    "startDate": "2019-05-01",
    "endDate": "2019-05-31"
},{
    "sellerId": "1",
    "campaignIds": ["10001"],
    "budgetType": "Daily",
    "startDate": "2019-05-01",
    "endDate": "2019-05-31",
    "amount": 5
},{
    "sellerId": "2",
    "campaignIds": ["10001"],
    "budgetType": "Daily",
    "startDate": "2019-05-01",
    "endDate": "2019-05-31",
    "amount": 5
},{
    "sellerId": "3",
    "campaignIds": ["10001"],
    "budgetType": "Daily",
    "startDate": "2019-05-01",
    "endDate": "2019-05-31",
    "amount": 5
}]

Getting Budgets

You can list of your budgets with following calls:

/marketplace-performance-outcomes/budgets

Response example

[{
    "id" : "101",
    "sellerId": "1",
    "campaignIds": ["10001"],
    "budgetType": "Capped",
    "amount": 30.00,
    "startDate": "2019-05-01",
    "endDate": "2019-05-31",
    "spend" : 0,
    "status" : "Scheduled",
    "suspended" : false
},{
    "id" : "102",
    "sellerId": "2",
    "campaignIds": ["10001"],
    "budgetType": "Capped",
    "amount": 30.00,
    "startDate": "2019-05-01",
    "endDate": "2019-05-31",
    "spend" : 0,
    "status" : "Scheduled",
    "suspended" : false
},{
    "id" : "103",
    "sellerId": "3",
    "campaignIds": ["10001"],
    "budgetType": "Capped",
    "amount": 30.00,
    "startDate": "2019-05-01",
    "endDate": "2019-05-31",
    "spend" : 0,
    "status" : "Scheduled",
    "suspended" : false
}]

sellerId The internal ID that our system has attributed to your seller.

spend Amount of money already spent on this budget.

suspended The suspension status of your budget. If your budget is suspended, the system will stop using this budget for delivery clicks in the associated Seller-Campaigns.

status

Scheduled : the budget will be used in the future starting at the startDate,
Current : the budget is currently being used to deliver ads,
Archived : the budget is not used anymore because it's endDate has been reached.

Parameter	Definition	Type	Required?
`advertiserId`	Return only budgets that pay for a given advertiser. Default is to not filter on advertiser	integer	No
`campaignId`	Return only budgets that pay for a given campaign. Default is to not filter on campaign	integer	No
`sellerId`	Return only budgets belonging to the given seller. Default is to not filter on seller.	string	No
`endAfterDate`	Return budgets that end after the given date. The default is the `startBeforeDate`(`yyyy-MM-DD`).	string	No
`startBeforeDate`	Return budgets that start on or before the given date. The default is today (`yyyy-MM-DD`).	string	No
`status`	Return only budgets with the given status. Default is to not filter on status. Possible values: Archived, Current, Scheduled	string	No
`type`	Return only budgets of the given type. Default is to not filter on budget type. Possible values: Capped, Uncapped, Daily	string	No
`withBalance`	Return budgets with remaining balance. Default is to not filter on balance.	boolean	No
`withSpend`	Return budgets with any positive spend. Default is to not filter on spend	boolean	No

Get one specific budget

You can also fetch the details of a single budget using the following request:

/marketplace-performance-outcomes/budgets/{budgetId}

Sample response

{
  "id": "1759183",
  "sellerId": "321392",
  "campaignIds": [
    143962
  ],
  "budgetType": "Capped",
  "amount": 1000,
  "startDate": "2021-01-11",
  "endDate": "2021-01-12",
  "spend": null,
  "status": "Active"
}

Updating Budgets

Once you have created budgets, you can modify them for:

Increasing their budget amount.
Decreasing their budget amount.
Changing their dates.
Changing the Campaigns that uses these budget.
Suspending budgets.

📘
Notice that you can do all this changes with one single PATCH request or separately

/marketplace-performance-outcomes/budgets

Sample response

[{
  "budgetId" : "101",  //id of the budget
  "campaignIds": ["10001"],
  "amount": 10.00,
  "startDate": "2019-05-01",
  "endDate": "2019-05-31"
},{
  "budgetId" : "102",  //id of the budget
  "campaignIds": ["10001"],
  "amount": 20.00,
  "startDate": "2019-05-01",
  "endDate": "2019-05-31"
},{
  "budgetId" : "103",  //id of the budget
  "campaignIds": ["10001"],
  "amount": 30.00,
  "startDate": "2019-05-01",
  "endDate": "2019-05-31"
}]

Increase Budget amounts

When updating budgets, you can increase the budget amounts. The increased amount will be taken into account immediately.

/marketplace-performance-outcomes/budgets

Sample response

[{
  "budgetId": "101",
  "amount": 20.00,
},{
  "budgetId": "102",
  "amount": 30.00,
},{
  "budgetId": "103",
  "amount": 40.00,
}]

Decrease Capped Budget amounts

When decreasing a capped budget amount, the new amount will be taken into account this new budget immediately. However, the spend amount can continue decreasing a little bit after your change. This is because some clicks that occurred just before your change were not yet taken into account in the spend at the moment of the change.

This means that the spend amount can exceed this new decreased amount (even if the set amount was above the spend at the moment of the decrease). For example, if your current budget has an amount of $100 with a spend of $49, and you decrease your budget to $50, the new spend might still reach $52 (to take into account the few clicks that occurred before the change).

/marketplace-performance-outcomes/budgets

Sample response

[{
  "budgetId": "101",
  "amount": 5.00,
},{
  "budgetId": "102",
  "amount": 15.00,
},{
  "budgetId": "103",
  "amount": 25.00,
}]

Decrease Daily Budget amounts

When decreasing a daily budget amount, we will try to achieve this new decreased daily amount as soon as possible. However, it can take up to seven days so that your 7-day average reflects the new daily amount (although, most of the time, it will take much less time).

/marketplace-performance-outcomes/budgets

Sample response

[{
  "budgetId": "101",
  "amount": 5.00,
},{
  "budgetId": "102",
  "amount": 5.00,
},{
  "budgetId": "103",
  "amount": 5.00,
}]

Changing the dates of Budgets

You can change the startDate and endDate of a Budget if :

the current and new values of startDate and endDate are in the future,
the endDate is not anterior to the startDate

/marketplace-performance-outcomes/budgets

Sample response

[{
  "budgetId" : "101",
  "startDate": "2019-05-01",
  "endDate": "2019-05-31"
},{
  "budgetId" : "102",
  "startDate": "2019-05-01",
  "endDate": "2019-05-31"
},{
  "budgetId" : "103",
  "startDate": "2019-05-01",
  "endDate": "2019-05-31"
}]

Sharing Budgets between campaigns

A Seller budget can be used within several MPO-Campaign.
To set it up, you need to provide several campaignIds at the creation of the Budget. After the creation of the budget, you can update the budget and replace the current list of campaigns (containing only 1 campaigns) with a new list of campaigns (containing multiple campaigns):

/marketplace-performance-outcomes/budgets

Sample response

[{
  "budgetId" : "101",
  "campaignIds": ["10001","10002"]
},{
  "budgetId" : "102",
  "campaignIds": ["10001","10002"]
},{
  "budgetId" : "103",
  "campaignIds": ["10001","10002"]
}]

Suspending Budgets

In case you want to stop using a budget, you can suspend it. After a budget is suspended, we will stop delivering ads for the Seller-Campaigns using this budget.

/marketplace-performance-outcomes/budgets

Sample response

[{
  "budgetId" : "101",
  "suspended": true
},{
  "budgetId" : "102",
  "suspended": true
},{
  "budgetId" : "103",
  "suspended": true
}]