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:

https://api.criteo.com/legacy/offsite-ads/budgets

[{
    "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.

https://api.criteo.com/legacy/offsite-ads/budgets

[{
    "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, on a given time period you can define how fast you want to spend your budget.

The Daily budget defines the maximum amount of money you would like to spend every day on a given time period.

 
Notice that Daily Budgets only works 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 adds (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):

https://api.criteo.com/legacy/offsite-ads/budgets

[{
    "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:

https://api.criteo.com/legacy/offsite-ads/budgets

[{
    "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  

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

https://api.criteo.com/legacy/offsite-ads/budgets

[{
    "id" : "101",  //id of the budget
	"campaignIds": ["10001"],
    "amount": 10.00,
    "startDate": "2019-05-01",
    "endDate": "2019-05-31"
},{
    "id" : "102",  //id of the budget
	"campaignIds": ["10001"],
    "amount": 20.00,
    "startDate": "2019-05-01",
    "endDate": "2019-05-31"
},{
    "id" : "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.

https://api.criteo.com/legacy/offsite-ads/budgets

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

Decrease Capped Budget amounts

When decreasing a capped budget amount we will take 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).

https://api.criteo.com/legacy/offsite-ads/budgets

[{
    "id": "101",
	"amount": 5.00,
},{
    "id": "102",
	"amount": 15.00,
},{
    "id": "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).

https://api.criteo.com/legacy/offsite-ads/budgets

[{
    "id": "101",
	"amount": 5.00,
},{
    "id": "102",
	"amount": 5.00,
},{
    "id": "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 be before the startDate  

https://api.criteo.com/legacy/offsite-ads/budgets

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

Sharing Budgets between campaigns

In case you have several COA-Campaigns, you can make that a Seller budget can be used within several COA-Campaign. For this, you just 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):

https://api.criteo.com/legacy/offsite-ads/budgets

[{
	"id" : "101",
	"campaignIds": ["10001","10002"]
},{
    "id" : "102",
	"campaignIds": ["10001","10002"]
},{
    "id" : "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.

https://api.criteo.com/legacy/offsite-ads/budgets

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