Update ad order

Time	Status	User Agent
Retrieving recent requests…

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 apply.

MONETARY Campaigns

Applicable: lifetimeBudget (in USD), dailyBudget (in USD)
Not applicable: lifetimeImpressions, dailyImpressions (these fields will be ignored)

IMPRESSIONS Campaigns

Applicable: lifetimeImpressions, dailyImpressions
Not applicable: lifetimeBudget, dailyBudget (these fields will be ignored)

After creation, the flight endpoint must be used to update startDate, endDate, lifetimeBudget, and lifetimeImpressions.

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:

optimizationGoal	Goal field	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.

Partial Update Behavior

When updating an existing Ad Order, the following fields preserve their stored values if omitted from the request body:

minBidMultiplier
maxBidMultiplier
completion_rate_goal (when optimizationGoal = VIDEO_COMPLETION_RATE)

To explicitly clear any of these values, pass null.

Request Body

Name	Type	Description	Required
id	Number	Ad order ID.	Yes
name	String	Ad order name.	Yes
campaignId	Number	Campaign ID associated with the ad order.	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. Use the flight endpoint for changes after creation.	No
endDate	Number	End date of the ad order, passed as Unix time in milliseconds. Use the flight endpoint for changes after creation.	No
lifetimeBudget	Number	The total lifetime budget for the ad order in USD. Use the flight endpoint for changes after creation.	No
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. Use the flight endpoint for changes after creation.	No
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 absent on update, the existing value is left untouched.	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). If omitted on update, the existing stored value is preserved.	No (preserved if omitted)
minBidMultiplier	Number	Minimum bid multiplier for bid matrix entries. If omitted on update, the existing stored value is preserved.	No (preserved if omitted)
maxBidMultiplier	Number	Maximum bid multiplier for bid matrix entries. If omitted on update, the existing stored value is preserved.	No (preserved if omitted)
goalMode	String	One of: `PERFORMANCE`, `SPEND`.	No

Examples

Updating only `max_bid` on a VCR-optimized Ad Order (completion_rate_goal preserved)

{
  "id": 12345,
  "name": "Q1 VCR Campaign",
  "campaignId": 549552,
  "optimizationGoal": "VIDEO_COMPLETION_RATE",
  "max_bid": 3.0,
  "goalMode": "SPEND",
  "audiences": [
    {"id": 7288043, "name": "Default Line", "status": "enabled", "lifetimeFrequencyCap": 0}
  ]
}

Updating only `max_bid` on a CPM Ad Order (bid multipliers preserved)

{
  "id": 67890,
  "name": "Q1 CPM Campaign",
  "campaignId": 552546,
  "optimizationGoal": "CPM",
  "max_bid": 1.5,
  "goalMode": "SPEND",
  "audiences": [
    {"id": 7286969, "name": "Default Line", "status": "enabled", "lifetimeFrequencyCap": 0}
  ]
}

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
}