REST Resource: exchanges.orders.products

  • The Product resource details the properties and configurations of a product, including its display name, external ID, transaction type, pricing type, and time frame.

  • Product configurations can include creative requirements for different types like display or video, audience targeting settings, and frequency caps.

  • Targeting criteria and forecast results are specified, particularly for Instant Deal Scenarios, along with potential error details.

  • The CreativeConfig resource outlines requirements for creatives based on type, with specific configurations for display dimensions and video duration/skippable type.

  • Several enums define possible values for fields such as CreativeType, DurationMatchType, SkippableMatchType, CreativeSource, AudienceType, TargetingType, InstantDealErrorStatus, and TimeUnit.

Resource: Product

Product

JSON representation 
{
  "name": string,
  "displayName": string,
  "externalDealId": string,
  "transactionType": enum (TransactionType),
  "pricingType": enum (PricingType),
  "updateTime": string,
  "startTime": string,
  "endTime": string,
  "rateDetails": {
    object (RateDetails)
  },
  "creativeConfig": [
    {
      object (CreativeConfig)
    }
  ],
  "makegood": boolean,
  "makegoodDetails": {
    object (MakegoodDetails)
  },
  "creativeSource": enum (CreativeSource),
  "mediumType": enum (MediumType),
  "audienceTargetingConfig": {
    object (AudienceTargetingConfig)
  },
  "targetingCriteria": {
    object (TargetingCriteria)
  },
  "forecastResult": {
    object (ForecastResult)
  },
  "errorDetails": {
    object (ErrorDetails)
  },
  "frequencyCap": {
    object (FrequencyCap)
  },
  "etag": string
}
Fields
name

string

Relative route name for product. Generated by server. Example: "exchanges/1234/orders/5678/products/abc". Output only.
displayName

string

The display name of the product.

Must be UTF-8 encoded with a maximum size of 240 bytes. Required.
externalDealId

string

External ID. This is the deal ID on exchange system. Max 100 characters. Allowed characters are alphanumeric, underscore, dash, and dot. Must be unique across all products. Required.
transactionType

enum (TransactionType)

Product transaction type. Required.
pricingType

enum (PricingType)

Pricing type for product. Required.
updateTime
(deprecated)

string (Timestamp format)

The timestamp when the product was last updated.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
startTime

string (Timestamp format)

Time when this product becomes active. Must be earlier than endTime. Start time cannot be more than 1 year in the future. Required.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

Time when this product becomes inactive. Currently cannot be later than year 2036. Required.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
rateDetails

object (RateDetails)

Rate details. Required.
creativeConfig[]

object (CreativeConfig)

The creative requirements for a product. Required for reserved transaction type product.
makegood
(deprecated)

boolean

Denotes whether a product is a makegood product.
makegoodDetails
(deprecated)

object (MakegoodDetails)

The makegood details for a product. Required when the product is a makegood.
creativeSource

enum (CreativeSource)

Creative source for a product. Optional, defaults to CREATIVE_SOURCE_ADVERTISER. Cannot be changed after product creation.
mediumType

enum (MediumType)

Medium type for a product. Defaults to DIGITAL if not specified for backwards compatibility. Cannot be changed after product creation.
audienceTargetingConfig

object (AudienceTargetingConfig)

Optional. Audience targeting config selected applied at deal level on Exchange.
targetingCriteria

object (TargetingCriteria)

Output only. Product targeting criteria references. Only applicable to Instant Deal Scenarios.
forecastResult

object (ForecastResult)

Product forecast results. Required when the targeting criteria are not empty and the forecast is not provided. Only applicable to Instant Deal Scenarios.
errorDetails

object (ErrorDetails)

Error details must be specified when specific product fields cannot be updated. Required when the forecast result cannot be provided due to a targeting criterion or an update cannot be made to the product. Only applicable to Instant Deal Scenarios.
frequencyCap

object (FrequencyCap)

Output only. Frequency cap selected by the buyer. Only applicable to Instant Deal Scenarios.
etag

string

An etag that needs to be specified when updating a product. It only needs to be specified for an update if the etag field is not empty. Only applicable to Instant Deal Scenarios.

CreativeConfig

Creative requirements config for a product.

JSON representation 
{
  "creativeType": enum (CreativeType),
  "dimensionCreativeConfig": {
    object (DimensionCreativeConfig)
  },
  "durationCreativeConfig": {
    object (DurationCreativeConfig)
  }
}
Fields
creativeType

enum (CreativeType)

Creative type. Required.
dimensionCreativeConfig

object (DimensionCreativeConfig)

The config for the display creatives.

This field is not supported for Native creatives (CREATIVE_TYPE_NATIVE).
durationCreativeConfig

object (DurationCreativeConfig)

The config for the video creatives.

CreativeType

Possible creative types.

Enums
CREATIVE_TYPE_UNSPECIFIED Creative type unspecified. Not valid input value.
CREATIVE_TYPE_DISPLAY Creative type of display.
CREATIVE_TYPE_VIDEO Creative type of video.
CREATIVE_TYPE_AUDIO Creative type of audio.
CREATIVE_TYPE_NATIVE Creative type of native.

DimensionCreativeConfig

Display creative dimension in pixels.

JSON representation 
{
  "width": integer,
  "height": integer
}
Fields
width

integer

Display creative width. Required.
height

integer

Display creative height. Required.

DurationCreativeConfig

The config for the creative in duration.

JSON representation 
{
  "duration": string,
  "durationMatchType": enum (DurationMatchType),
  "skippableMatchType": enum (SkippableMatchType)
}
Fields
duration

string (Duration format)

The duration of the video creative in seconds. Required

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
durationMatchType

enum (DurationMatchType)

The duration match criteria.
skippableMatchType

enum (SkippableMatchType)

The skippable type of a video creative.

DurationMatchType

Possible formats for the duration match criterion.

Enums
DURATION_MATCH_TYPE_UNSPECIFIED The duration match criterion is not specified or is unknown in this version. Not valid input value.
DURATION_MATCH_TYPE_EQUAL_TO The creative duration needs to be the same as the required duration.
DURATION_MATCH_TYPE_LESS_THAN_OR_EQUAL_TO The creative duration needs to be the same as or less than required duration.

SkippableMatchType

Possible formats for an product.

Enums
SKIPPABLE_MATCH_TYPE_UNSPECIFIED The skippable type is not specified or is unknown in this version. Not valid input value.
SKIPPABLE_MATCH_TYPE_SKIPPABLE The creative needs to be skippable.
SKIPPABLE_MATCH_TYPE_NOT_SKIPPABLE The creative needs to be not skippable.
SKIPPABLE_MATCH_TYPE_ANY The creative can be skippable or non-skippable.

MakegoodDetails

The config for the makegood details.

JSON representation 
{
  "originalExternalDealId": string,
  "reason": string
}
Fields
originalExternalDealId

string

The original external deal id which requests makegood. Max 100 characters. Allowed characters are alphanumeric, underscore, dash, and dot. Required.
reason

string

Seller-initiated Makegood reason. Max 250 characters. Required.

CreativeSource

Creative source; where the creatives will be served from.

Enums
CREATIVE_SOURCE_UNSPECIFIED The creative source is not specified or unknown in this version. Not valid input value.
CREATIVE_SOURCE_ADVERTISER Creatives will be served by DV3.
CREATIVE_SOURCE_PUBLISHER Creatives will be served by the publisher. Publisher-hosted creatives are not currently supported; any request attempting to set creative source to CREATIVE_SOURCE_PUBLISHER will fail.

AudienceTargetingConfig

The config for the audience targeting.

JSON representation 
{
  "audienceType": enum (AudienceType)
}
Fields
audienceType

enum (AudienceType)

The audience type. Required.

AudienceType

Audience type.

Enums
AUDIENCE_TYPE_UNSPECIFIED Unspecified audience type. Not valid for input.
AUDIENCE_TYPE_COMMERCE Commerce audience type.

TargetingCriteria

Targeting criteria specified.

JSON representation 
{
  "selectedTargetingOptions": [
    {
      object (SelectedTargetingOption)
    }
  ]
}
Fields
selectedTargetingOptions[]

object (SelectedTargetingOption)

Selected options.

SelectedTargetingOption

The selected targeting option or options for a single targeting type.

JSON representation 
{
  "type": enum (TargetingType),

  // Union field value can be only one of the following:
  "audienceSelection": {
    object (AudienceSelection)
  },
  "targetingSelection": {
    object (TargetingSelection)
  }
  // End of list of possible types for union field value.
}
Fields
type

enum (TargetingType)

Targeting type associated with the selected options.
Union field value. Only one type of selection can be included. The selection chosen must correspond to the TargetingType chosen for the "type" field. value can be only one of the following:
audienceSelection

object (AudienceSelection)

Selected audience.
targetingSelection

object (TargetingSelection)

Generic set of selected option ids.

TargetingType

Targeting types.

Enums
TARGETING_TYPE_UNSPECIFIED Unspecified targeting type, not valid for input.
TARGETING_TYPE_AUDIENCE Targeting type audience.
TARGETING_TYPE_COUNTRY Targeting type country.
TARGETING_TYPE_DMA Targeting type dma.
TARGETING_TYPE_PROGRAMMER Targeting type programmer.
TARGETING_TYPE_BRAND Targeting type brand.
TARGETING_TYPE_CONTENT_GENRE Targeting type content genre.
TARGETING_TYPE_DEVICE Targeting type device.
TARGETING_TYPE_OPERATING_SYSTEM Targeting type operating system.
TARGETING_TYPE_RATING Targeting type rating.
TARGETING_TYPE_ENVIRONMENT Targeting type environment.
TARGETING_TYPE_LANGUAGE Targeting type language.
TARGETING_TYPE_GEO Targeting type geography.
TARGETING_TYPE_AGE Targeting type age.
TARGETING_TYPE_GENDER Targeting type gender.
TARGETING_TYPE_CONTEXTUAL_SEGMENT Targeting type contextual segment.
TARGETING_TYPE_REQUEST_FORMAT Targeting type request format.
TARGETING_TYPE_PUBLISHER Targeting type publisher.
TARGETING_TYPE_INVENTORY_SIZE Targeting type size.
TARGETING_TYPE_NETWORK Targeting type network.
TARGETING_TYPE_PLATFORM Targeting type platform.
TARGETING_TYPE_VIDEO_DELIVERY_TYPE Targeting type video delivery type.
TARGETING_TYPE_VIDEO_MINIMUM_PLAYER_SIZE Targeting type video minimum player size.

AudienceSelection

Selected audience targeting options.

JSON representation 
{
  "includedOrGroups": [
    {
      object (OrGroup)
    }
  ],
  "excludedOptionIds": [
    string
  ]
}
Fields
includedOrGroups[]

object (OrGroup)

Included options are conjuncted with AND, each included option can be an individual option, or a group of options conjuncted with OR.
excludedOptionIds[]

string (int64 format)

Excluded options are conjuncted with OR.

OrGroup

A group of selected options conjuncted by OR.

JSON representation 
{
  "optionIds": [
    string
  ]
}
Fields
optionIds[]

string (int64 format)

Selected option ids.

TargetingSelection

A set of one or more selected option ids, applicable for most targeting types.

JSON representation 
{
  "optionIds": [
    string
  ]
}
Fields
optionIds[]

string (int64 format)

Selected option ids.

ForecastResult

Forecast result specified.

JSON representation 
{
  "forecasts": [
    {
      object (Forecast)
    }
  ]
}
Fields
forecasts[]

object (Forecast)

Forecast. "forecastCategory" must be unique for each element specified.

Forecast

Forecast of the specified forecast category.

JSON representation 
{
  "forecastCategory": enum (ForecastCategory),

  // Union field forecast_data can be only one of the following:
  "number": string,
  "percentage": integer,
  "cpmPrice": {
    object (Money)
  },
  "cpmRange": {
    object (CpmRange)
  },
  "forecastBreakdownData": {
    object (ForecastBreakdownData)
  }
  // End of list of possible types for union field forecast_data.
}
Fields
forecastCategory

enum (ForecastCategory)

The specified forecast category the forecast stat represented.
Union field forecast_data. Only one type of stat data can be included. The data populated must correspond to the "forecastCategory" field. forecast_data can be only one of the following:
number

string (int64 format)

Number data.
percentage

integer

Percentage data.
cpmPrice

object (Money)

CPM price data.
cpmRange

object (CpmRange)

CPM price range data.
forecastBreakdownData

object (ForecastBreakdownData)

Forecast breakdown data.

ForecastCategory

Forecast category.

Enums
FORECAST_CATEGORY_UNSPECIFIED Unspecified category. Not valid for input.
FORECAST_CATEGORY_TOTAL_OPPORTUNITIES Total opportunities. Number data.
FORECAST_CATEGORY_TOTAL_AUDIENCE Total audience. Number data.
FORECAST_CATEGORY_DIGITAL_TRP Digital target rating points. Percentage data.
FORECAST_CATEGORY_SUGGESTED_CPM Suggested CPM price. CPM range or CPM price data.
FORECAST_CATEGORY_UNIQUE_REACH Forecast unique reach. Number data.
FORECAST_CATEGORY_FORECAST_BREAKDOWN Forecast breakdown. Forecast breakdown data.

CpmRange

CPM Range contains the min and max of the CPM.

JSON representation 
{
  "minCpm": {
    object (Money)
  },
  "maxCpm": {
    object (Money)
  }
}
Fields
minCpm

object (Money)

Lower bound of the CPM range.
maxCpm

object (Money)

Upper bound of the CPM range.

ForecastBreakdownData

Forecast breakdown data holds a list of forecast breakdown.

JSON representation 
{
  "forecastBreakdowns": [
    {
      object (ForecastBreakdown)
    }
  ]
}
Fields
forecastBreakdowns[]

object (ForecastBreakdown)

A list of forecast breakdowns.

ForecastBreakdown

Forecast breakdown of the selected targeting option.

JSON representation 
{
  "selectedTargetingOption": {
    object (SelectedTargetingOption)
  },

  // Union field breakdown_data can be only one of the following:
  "impressions": string
  // End of list of possible types for union field breakdown_data.
}
Fields
selectedTargetingOption

object (SelectedTargetingOption)

The selected targeting option or options for a single targeting type.
Union field breakdown_data. Only one type of breakdown data can be included. breakdown_data can be only one of the following:
impressions

string (int64 format)

Forecast impressions.

ErrorDetails

Error details specified when update has errors.

JSON representation 
{
  "message": string,
  "instantDealErrorStatus": enum (InstantDealErrorStatus)
}
Fields
message

string

The message specified when update has errors.
instantDealErrorStatus

enum (InstantDealErrorStatus)

The error status specified when update has errors for the instant deals.

InstantDealErrorStatus

Error status specified when instant deal update has errors.

Enums
INSTANT_DEAL_ERROR_STATUS_UNSPECIFIED Unspecified error status.
INSTANT_DEAL_ERROR_STATUS_INVENTORY_UNAVAILABLE Error status indicates inventory unavailable.
INSTANT_DEAL_ERROR_STATUS_FORECAST_UNAVAILABLE Error status indicates forecast unavailable.
INSTANT_DEAL_ERROR_STATUS_INVALID_INPUT Error status indicates there are invalid input fields.

FrequencyCap

The number of times a user may be shown with the same ad during a given time period

JSON representation 
{
  "timeUnit": enum (TimeUnit),
  "maxImpressions": string
}
Fields
timeUnit

enum (TimeUnit)

The time unit in which the frequency cap will be applied.
maxImpressions

string (int64 format)

The maximum number of times a user may be shown with the same ad during this period.

TimeUnit

The time unit in which the frequency cap will be applied.

Enums
TIME_UNIT_UNSPECIFIED Unspecified time unit.
TIME_UNIT_LIFETIME The frequency cap will be applied to the whole life time.
TIME_UNIT_MONTHS The frequency cap will be applied to a number of months.
TIME_UNIT_WEEKS The frequency cap will be applied to a number of weeks.
TIME_UNIT_DAYS The frequency cap will be applied to a number of days.

Methods

create

 Creates a product.

get

 Gets product.

list

 Lists product.

patch

 Updates a product.