Creates an Ad Order.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Campaign Budget Types
Ad Orders inherit their budget type from the Campaign they belong to. The Campaign's budget type determines which budget fields are required:
MONETARY Campaigns
- Required:
lifetimeBudget(in USD) - Optional:
dailyBudget(in USD) - Not applicable:
lifetimeImpressions,dailyImpressions(these fields will be ignored)
IMPRESSIONS Campaigns
- Required:
lifetimeImpressions - Optional:
dailyImpressions - Not applicable:
lifetimeBudget,dailyBudget(these fields will be ignored)
The API validates the appropriate fields based on the Campaign's budget type.
Note
io_number and externalAdOrderId both serve the same purpose and refer to the same value: an external ID for use by clients. These fields point to the same value; on input, a caller should use one field or the other, not both; on output, both fields are provided (currently), and will have the same value.
Submitting a record with both fields is an error condition, and will result in a 400 response.
Optimization Goals
The optimizationGoal field accepts the following values. On create, only the goal field that matches optimizationGoal is honored; all other goal fields are cleared.
| optimizationGoal | Required goal field on create | Other goal fields |
|---|---|---|
CPM | none | nulled |
CPC | ctr_goal | nulled |
CPA | cpa_goal | nulled |
VIDEO_COMPLETION_RATE | completion_rate_goal | nulled |
VCR is accepted as a case-insensitive alias for VIDEO_COMPLETION_RATE on input and is normalized to VIDEO_COMPLETION_RATE in the response.
Request Body
| Name | Type | Description | Required |
|---|---|---|---|
| id | Number | Ad order ID. | Required for update. |
| name | String | Ad order name. | Yes |
| campaignId | Number | Campaign ID associated with the ad order. The campaign's budget type determines which budget fields are required. | Yes |
| optimizationGoal | String | Optimization goal for the ad order. One of: CPM, CPC, CPA, VIDEO_COMPLETION_RATE (alias: VCR). | Yes |
| startDate | Number | Start date of the ad order, passed as Unix time in milliseconds. | Yes for creation. After creation the flight endpoint must be used to update and modify. |
| endDate | Number | End date of the ad order, passed as Unix time in milliseconds. | Yes for creation. After creation the flight endpoint must be used to update and modify. |
| lifetimeBudget | Number | The total lifetime budget for the ad order in USD. | Required if campaign budget type is MONETARY. Optional (ignored) if IMPRESSIONS. |
| dailyBudget | Number | The daily budget limit in USD. | Optional. Only applicable for MONETARY campaigns. |
| lifetimeImpressions | Number | The total lifetime impressions budget for the ad order. | Required if campaign budget type is IMPRESSIONS. After creation the flight endpoint must be used to update and modify. |
| dailyImpressions | Number | The daily impressions budget limit. | Optional. Only applicable for IMPRESSIONS campaigns. |
| frequencyCap | Object | Holds all frequency cap settings. If not present, defaults to null. | No |
| frequencyCap.limit | Number | The maximum number of impressions a user is exposed to per frequency cap time period duration. See frequencyCap.duration and frequencyCap.timePeriod. | Yes (if parent object present) |
| frequencyCap.duration | Number | The number of given frequencyCap.timePeriod | Yes (if parent object present) |
| frequencyCap.timePeriod | String | One of: MINUTE, HOUR, DAY | Yes (if parent object present) |
| channelsV2 | String Array/Null | Channels the Ad Order will be capable of serving on: Display, Video, Native, Audio, DOOH, CTV, LTV, LTV Wide Orbit | No |
| max_bid | Number | The maximum bid. Default values apply when no values are present. | No |
| audienceWeightsEnabled | Boolean | Controls whether audience weights are enabled. If null or absent, defaults to false on create, and left untouched on update. | No |
| ctr_goal | Number | CTR goal (e.g. 0.002). | Required when optimizationGoal=CPC. |
| cpa_goal | Number | CPA goal value. | Required when optimizationGoal=CPA. |
| completion_rate_goal | Number | Video completion rate goal (0.0–1.0). | Required when optimizationGoal=VIDEO_COMPLETION_RATE. |
| minBidMultiplier | Number | Minimum bid multiplier for bid matrix entries. | No |
| maxBidMultiplier | Number | Maximum bid multiplier for bid matrix entries. | No |
| goalMode | String | One of: PERFORMANCE, SPEND. | No |
Examples
Creating an Ad Order for a MONETARY Campaign
{
"name": "Q1 Display Campaign",
"campaignId": 401814,
"optimizationGoal": "CPA",
"startDate": 1766476800000,
"endDate": 1769088800000,
"lifetimeBudget": 10000,
"dailyBudget": 500,
"channelsV2": ["Display"]
}Creating an Ad Order for an IMPRESSIONS Campaign
{
"name": "Q1 Display Campaign",
"campaignId": 541584,
"optimizationGoal": "CPM",
"startDate": 1766476800000,
"endDate": 1769088800000,
"lifetimeImpressions": 250000,
"dailyImpressions": 10000,
"channelsV2": ["Display"]
}Creating an Ad Order with Video Completion Rate (VCR) optimization
{
"name": "Q1 VCR Campaign",
"campaignId": 549552,
"optimizationGoal": "VIDEO_COMPLETION_RATE",
"completion_rate_goal": 0.5,
"max_bid": 2.0,
"goalMode": "SPEND",
"audiences": [
{"name": "Default Line", "status": "enabled", "lifetimeFrequencyCap": 0}
],
"lifetimeBudget": 10.0,
"startDate": 1745452800000,
"endDate": 1746057600000
}Error response — Invalid Optimization Goal
When optimizationGoal is set to a value outside the allowed enum, the API returns a structured error in the response body instead of a 500.
{
"messages": [
{"message": "Invalid Optimization Goal: INVALID_GOAL", "level": "ERROR", "code": ""},
{"message": "Optimization Goal is required", "level": "ERROR", "code": ""}
],
"entity": null
}Unauthorized
Forbidden
Not Found