REST Resource: buyers.proposals.deals

Resource: Deal

A deal represents a segment of inventory for displaying ads that contains the terms and targeting information that is used for serving as well as the deal stats and status. Note: A proposal may contain multiple deals.

JSON representation
{
  "name": string,
  "createTime": string,
  "updateTime": string,
  "proposalRevision": string,
  "displayName": string,
  "billedBuyer": string,
  "publisherProfile": string,
  "dealType": enum (DealType),
  "estimatedGrossSpend": {
    object (Money)
  },
  "sellerTimeZone": {
    object (TimeZone)
  },
  "description": string,
  "flightStartTime": string,
  "flightEndTime": string,
  "targeting": {
    object (MarketplaceTargeting)
  },
  "creativeRequirements": {
    object (CreativeRequirements)
  },
  "deliveryControl": {
    object (DeliveryControl)
  },

  // Union field negotiating_buyer can be only one of the following:
  "buyer": string,
  "client": string
  // End of list of possible types for union field negotiating_buyer.

  // Union field pricing_terms can be only one of the following:
  "programmaticGuaranteedTerms": {
    object (ProgrammaticGuaranteedTerms)
  },
  "preferredDealTerms": {
    object (PreferredDealTerms)
  },
  "privateAuctionTerms": {
    object (PrivateAuctionTerms)
  }
  // End of list of possible types for union field pricing_terms.
}
Fields
name

string

Immutable. The unique identifier of the deal. Auto-generated by the server when a deal is created. Format: buyers/{accountId}/proposals/{proposalId}/deals/{dealId}

createTime

string (Timestamp format)

Output only. The time of the deal creation.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

updateTime

string (Timestamp format)

Output only. The time when the deal was last updated.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

proposalRevision

string (int64 format)

Output only. The revision number for the proposal and is the same value as proposal.proposal_revision. Each update to deal causes the proposal revision number to auto-increment. The buyer keeps track of the last revision number they know of and pass it in when making an update. If the head revision number on the server has since incremented, then an ABORTED error is returned during the update operation to let the buyer know that a subsequent update was made.

displayName

string

Output only. The name of the deal. Maximum length of 255 unicode characters is allowed. Control characters are not allowed. Buyers cannot update this field. Note: Not to be confused with name, which is a unique identifier of the deal.

billedBuyer

string

Output only. When the client field is populated, this field refers to the buyer who creates and manages the client buyer and gets billed on behalf of the client buyer; when the buyer field is populated, this field is the same value as buyer. Format : buyers/{buyerAccountId}

publisherProfile

string

Immutable. Reference to the seller on the deal. Format: buyers/{buyerAccountId}/publisherProfiles/{publisherProfileId}

dealType

enum (DealType)

Output only. Type of deal.

estimatedGrossSpend

object (Money)

Specified by buyers in request for proposal (RFP) to notify publisher the total estimated spend for the proposal. Publishers will receive this information and send back proposed deals accordingly.

sellerTimeZone

object (TimeZone)

Output only. Time zone of the seller used to mark the boundaries of a day for daypart targeting and CPD billing.

description

string

Output only. Free text description for the deal terms.

flightStartTime

string (Timestamp format)

Proposed flight start time of the deal. This will generally be stored in the granularity of one second since deal serving starts at seconds boundary. Any time specified with more granularity (e.g., in milliseconds) will be truncated towards the start of time in seconds.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

flightEndTime

string (Timestamp format)

Proposed flight end time of the deal. This will generally be stored in a granularity of a second. A value is not necessary for Private Auction deals.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

targeting

object (MarketplaceTargeting)

Specifies the subset of inventory targeted by the deal. Can be updated by the buyer before the deal is finalized.

creativeRequirements

object (CreativeRequirements)

Output only. Metadata about the creatives of this deal.

deliveryControl

object (DeliveryControl)

Output only. Specifies the pacing set by the publisher.

Union field negotiating_buyer. The buyer who negotiates this deal with publishers. Can be either a buyer or client. negotiating_buyer can be only one of the following:
buyer

string

Output only. Refers to a buyer in [The Realtime-bidding API][google.ads.realtimebidding.v1.Buyer]. Format: buyers/{buyerAccountId}

client

string

Output only. Refers to a Client. Format: buyers/{buyerAccountId}/clients/{clientAccountid}

Union field pricing_terms. The pricing terms for the deal. pricing_terms can be only one of the following:
programmaticGuaranteedTerms

object (ProgrammaticGuaranteedTerms)

The terms for programmatic guaranteed deals.

preferredDealTerms

object (PreferredDealTerms)

The terms for preferred deals.

privateAuctionTerms

object (PrivateAuctionTerms)

The terms for private auction deals.

ProgrammaticGuaranteedTerms

Pricing terms for Programmatic Guaranteed Deals.

JSON representation
{
  "guaranteedLooks": string,
  "fixedPrice": {
    object (Price)
  },
  "minimumDailyLooks": string,
  "reservationType": enum (ReservationType),
  "impressionCap": string,
  "percentShareOfVoice": string
}
Fields
guaranteedLooks

string (int64 format)

Count of guaranteed looks.

fixedPrice

object (Price)

Fixed price for the deal.

minimumDailyLooks

string (int64 format)

Daily minimum looks for CPD deal types.

reservationType

enum (ReservationType)

The reservation type for a Programmatic Guaranteed deal. This indicates whether the number of impressions is fixed, or a percent of available impressions. If not specified, the default reservation type is STANDARD.

impressionCap

string (int64 format)

The lifetime impression cap for CPM Sponsorship deals. Deal will stop serving when cap is reached.

percentShareOfVoice

string (int64 format)

For sponsorship deals, this is the percentage of the seller's eligible impressions that the deal will serve until the cap is reached. Valid value is within range 0~100.

Price

Represents a price and a pricing type for a deal.

JSON representation
{
  "type": enum (Type),
  "amount": {
    object (Money)
  }
}
Fields
type

enum (Type)

The pricing type for the deal.

amount

object (Money)

The actual price with currency specified.

Type

Specifies the pricing type for a deal.

Enums
TYPE_UNSPECIFIED A placeholder for an undefined pricing type. If the pricing type is unspecified, CPM will be used instead.
CPM Cost per thousand impressions.
CPD Cost per day.

Money

Represents an amount of money with its currency type.

JSON representation
{
  "currencyCode": string,
  "units": string,
  "nanos": integer
}
Fields
currencyCode

string

The three-letter currency code defined in ISO 4217.

units

string (int64 format)

The whole units of the amount. For example if currencyCode is "USD", then 1 unit is one US dollar.

nanos

integer

Number of nano (10^-9) units of the amount. The value must be between -999,999,999 and +999,999,999 inclusive. If units is positive, nanos must be positive or zero. If units is zero, nanos can be positive, zero, or negative. If units is negative, nanos must be negative or zero. For example $-1.75 is represented as units=-1 and nanos=-750,000,000.

ReservationType

The reservation type for a Programmatic Guaranteed deal.

Enums
RESERVATION_TYPE_UNSPECIFIED An unspecified reservation type.
STANDARD Non-sponsorship deal.
SPONSORSHIP Sponsorship deals don't have impression goal (guaranteedLooks) and they are served based on the flight dates. For CPM Sponsorship deals, impressionCap is the lifetime impression limit.

PreferredDealTerms

Pricing terms for Preferred Deals.

JSON representation
{
  "fixedPrice": {
    object (Price)
  }
}
Fields
fixedPrice

object (Price)

Fixed price for the deal.

PrivateAuctionTerms

Pricing terms for Private Auctions.

JSON representation
{
  "floorPrice": {
    object (Price)
  },
  "openAuctionAllowed": boolean
}
Fields
floorPrice

object (Price)

The minimum price buyer has to bid to compete in the private auction.

openAuctionAllowed

boolean

Output only. True if open auction buyers are allowed to compete with invited buyers in this private auction.

TimeZone

Represents a time zone from the IANA Time Zone Database.

JSON representation
{
  "id": string,
  "version": string
}
Fields
id

string

IANA Time Zone Database time zone, e.g. "America/New_York".

version

string

Optional. IANA Time Zone Database version number, e.g. "2019a".

MarketplaceTargeting

Targeting represents different criteria that can be used to target inventory. For example, they can choose to target inventory only if the user is in the US. Multiple types of targeting are always applied as a logical AND, unless noted otherwise.

JSON representation
{
  "geoTargeting": {
    object (CriteriaTargeting)
  },
  "inventorySizeTargeting": {
    object (InventorySizeTargeting)
  },
  "technologyTargeting": {
    object (TechnologyTargeting)
  },
  "placementTargeting": {
    object (PlacementTargeting)
  },
  "videoTargeting": {
    object (VideoTargeting)
  },
  "userListTargeting": {
    object (CriteriaTargeting)
  },
  "daypartTargeting": {
    object (DayPartTargeting)
  }
}
Fields
geoTargeting

object (CriteriaTargeting)

Output only. Geo criteria IDs to be included/excluded.

inventorySizeTargeting

object (InventorySizeTargeting)

Output only. Inventory sizes to be included/excluded.

technologyTargeting

object (TechnologyTargeting)

Output only. Technology targeting information, e.g., operating system, device category.

placementTargeting

object (PlacementTargeting)

Output only. Placement targeting information, e.g., URL, mobile applications.

videoTargeting

object (VideoTargeting)

Output only. Video targeting information.

userListTargeting

object (CriteriaTargeting)

Buyer user list targeting information. User lists can be uploaded via https://developers.google.com/authorized-buyers/rtb/bulk-uploader.

daypartTargeting

object (DayPartTargeting)

Daypart targeting information.

CriteriaTargeting

Generic targeting used for targeting dimensions that contains a list of included and excluded numeric IDs. This cannot be filtered using list filter syntax.

JSON representation
{
  "targetedCriteriaIds": [
    string
  ],
  "excludedCriteriaIds": [
    string
  ]
}
Fields
targetedCriteriaIds[]

string (int64 format)

A list of numeric IDs to be included.

excludedCriteriaIds[]

string (int64 format)

A list of numeric IDs to be excluded.

InventorySizeTargeting

Represents the size of an ad unit that can be targeted on a bid request.

JSON representation
{
  "targetedInventorySizes": [
    {
      object (AdSize)
    }
  ],
  "excludedInventorySizes": [
    {
      object (AdSize)
    }
  ]
}
Fields
targetedInventorySizes[]

object (AdSize)

A list of inventory sizes to be included.

excludedInventorySizes[]

object (AdSize)

A list of inventory sizes to be excluded.

AdSize

Represents size of a single ad slot, or a creative.

JSON representation
{
  "width": string,
  "height": string,
  "type": enum (Type)
}
Fields
width

string (int64 format)

The width of the ad slot in pixels. This field will be present only when size type is PIXEL.

height

string (int64 format)

The height of the ad slot in pixels. This field will be present only when size type is PIXEL.

type

enum (Type)

The type of the ad slot size.

Type

Represents different types of ad slot/creative sizing.

Enums
TYPE_UNSPECIFIED A placeholder for an undefined size type.
PIXEL Ad slot with size specified by height and width in pixels.
INTERSTITIAL Special size to describe an interstitial ad slot.
NATIVE Native (mobile) ads rendered by the publisher.
FLUID Fluid size (i.e., responsive size) can be resized automatically with the change of outside environment.

TechnologyTargeting

Represents targeting about various types of technology.

JSON representation
{
  "deviceCategoryTargeting": {
    object (CriteriaTargeting)
  },
  "deviceCapabilityTargeting": {
    object (CriteriaTargeting)
  },
  "operatingSystemTargeting": {
    object (OperatingSystemTargeting)
  }
}
Fields
deviceCategoryTargeting

object (CriteriaTargeting)

IDs of device categories to be included/excluded.

deviceCapabilityTargeting

object (CriteriaTargeting)

IDs of device capabilities to be included/excluded.

operatingSystemTargeting

object (OperatingSystemTargeting)

Operating system related targeting information.

OperatingSystemTargeting

Represents targeting information for operating systems.

JSON representation
{
  "operatingSystemCriteria": {
    object (CriteriaTargeting)
  },
  "operatingSystemVersionCriteria": {
    object (CriteriaTargeting)
  }
}
Fields
operatingSystemCriteria

object (CriteriaTargeting)

IDs of operating systems to be included/excluded.

operatingSystemVersionCriteria

object (CriteriaTargeting)

IDs of operating system versions to be included/excluded.

PlacementTargeting

Represents targeting about where the ads can appear, e.g., certain sites or mobile applications. Different placement targeting types will be logically OR'ed.

JSON representation
{
  "uriTargeting": {
    object (UriTargeting)
  },
  "mobileApplicationTargeting": {
    object (MobileApplicationTargeting)
  }
}
Fields
uriTargeting

object (UriTargeting)

URLs to be included/excluded.

mobileApplicationTargeting

object (MobileApplicationTargeting)

Mobile application targeting information in a deal. This doesn't apply to Auction Packages.

UriTargeting

Represents a list of targeted and excluded URLs (e.g., google.com). For Private Auction Deals, URLs are either included or excluded. For Programmatic Guaranteed and Preferred Deals, this doesn't apply.

JSON representation
{
  "targetedUris": [
    string
  ],
  "excludedUris": [
    string
  ]
}
Fields
targetedUris[]

string

A list of URLs to be included.

excludedUris[]

string

A list of URLs to be excluded.

MobileApplicationTargeting

Mobile application targeting settings.

JSON representation
{
  "firstPartyTargeting": {
    object (FirstPartyMobileApplicationTargeting)
  }
}
Fields
firstPartyTargeting

object (FirstPartyMobileApplicationTargeting)

Publisher owned apps to be targeted or excluded by the publisher to display the ads in.

FirstPartyMobileApplicationTargeting

Represents a list of targeted and excluded mobile application IDs that publishers own. Android App ID, for example, com.google.android.apps.maps, can be found in Google Play Store URL. iOS App ID (which is a number) can be found at the end of iTunes store URL. First party mobile applications is either included or excluded.

JSON representation
{
  "targetedAppIds": [
    string
  ],
  "excludedAppIds": [
    string
  ]
}
Fields
targetedAppIds[]

string

A list of application IDs to be included.

excludedAppIds[]

string

A list of application IDs to be excluded.

VideoTargeting

Represents targeting information about video.

JSON representation
{
  "targetedPositionTypes": [
    enum (PositionType)
  ],
  "excludedPositionTypes": [
    enum (PositionType)
  ]
}
Fields
targetedPositionTypes[]

enum (PositionType)

A list of video positions to be included. When this field is populated, the excludedPositionTypes field must be empty.

excludedPositionTypes[]

enum (PositionType)

A list of video positions to be excluded. When this field is populated, the targetedPositionTypes field must be empty.

PositionType

Represents a targetable position within a video.

Enums
POSITION_TYPE_UNSPECIFIED A placeholder for an undefined video position.
PREROLL Ad is played before the video.
MIDROLL Ad is played during the video.
POSTROLL Ad is played after the video.

DayPartTargeting

Represents Daypart targeting.

JSON representation
{
  "dayParts": [
    {
      object (DayPart)
    }
  ],
  "timeZoneType": enum (TimeZoneType)
}
Fields
dayParts[]

object (DayPart)

The targeted weekdays and times

timeZoneType

enum (TimeZoneType)

The time zone type of the day parts

TimeZoneType

Represents the time zone the dayparts are scheduled in.

Enums
TIME_ZONE_TYPE_UNSPECIFIED Default value. This field is unused.
SELLER The publisher's time zone
USER The user's time zone

DayPart

Defines targeting for a period of time on a specific week day.

JSON representation
{
  "dayOfWeek": enum (DayOfWeek),
  "startTime": {
    object (TimeOfDay)
  },
  "endTime": {
    object (TimeOfDay)
  }
}
Fields
dayOfWeek

enum (DayOfWeek)

Day of week for the period.

startTime

object (TimeOfDay)

Hours in 24 hour time between 0 and 24, inclusive. Note: 24 is logically equivalent to 0, but is supported since in some cases there may need to be differentiation made between midnight on one day and midnight on the next day. Accepted values for minutes are [0, 15, 30, 45]. 0 is the only acceptable minute value for hour 24. Seconds and nanos are ignored.

endTime

object (TimeOfDay)

Hours in 24 hour time between 0 and 24, inclusive. Note: 24 is logically equivalent to 0, but is supported since in some cases there may need to be differentiation made between midnight on one day and midnight on the next day. Accepted values for minutes are [0, 15, 30, 45]. 0 is the only acceptable minute value for hour 24. Seconds and nanos are ignored.

DayOfWeek

Represents a day of the week.

Enums
DAY_OF_WEEK_UNSPECIFIED The day of the week is unspecified.
MONDAY Monday
TUESDAY Tuesday
WEDNESDAY Wednesday
THURSDAY Thursday
FRIDAY Friday
SATURDAY Saturday
SUNDAY Sunday

TimeOfDay

Represents a time of day. The date and time zone are either not significant or are specified elsewhere. An API may choose to allow leap seconds. Related types are google.type.Date and google.protobuf.Timestamp.

JSON representation
{
  "hours": integer,
  "minutes": integer,
  "seconds": integer,
  "nanos": integer
}
Fields
hours

integer

Hours of day in 24 hour format. Should be from 0 to 23. An API may choose to allow the value "24:00:00" for scenarios like business closing time.

minutes

integer

Minutes of hour of day. Must be from 0 to 59.

seconds

integer

Seconds of minutes of the time. Must normally be from 0 to 59. An API may allow the value 60 if it allows leap-seconds.

nanos

integer

Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999.

CreativeRequirements

Message captures data about the creatives in the deal.

JSON representation
{
  "creativePreApprovalPolicy": enum (CreativePreApprovalPolicy),
  "creativeSafeFrameCompatibility": enum (CreativeSafeFrameCompatibility),
  "programmaticCreativeSource": enum (ProgrammaticCreativeSource)
}
Fields
creativePreApprovalPolicy

enum (CreativePreApprovalPolicy)

Output only. Specifies the creative pre-approval policy.

creativeSafeFrameCompatibility

enum (CreativeSafeFrameCompatibility)

Output only. Specifies whether the creative is safeFrame compatible.

programmaticCreativeSource

enum (ProgrammaticCreativeSource)

Output only. Specifies the creative source for programmatic deals. PUBLISHER means creative is provided by seller and ADVERTISER means creative is provided by the buyer.

CreativePreApprovalPolicy

Specifies the creative pre-approval policy requirements.

Enums
CREATIVE_PRE_APPROVAL_POLICY_UNSPECIFIED A placeholder for an undefined creative pre-approval policy.
SELLER_PRE_APPROVAL_REQUIRED The seller needs to approve each creative before it can serve.
SELLER_PRE_APPROVAL_NOT_REQUIRED The seller does not need to approve each creative before it can serve.

CreativeSafeFrameCompatibility

Specifies whether the creative needs to be safe-frame compatible or not.

Enums
CREATIVE_SAFE_FRAME_COMPATIBILITY_UNSPECIFIED A placeholder for an undefined creative safe-frame compatibility.
COMPATIBLE The creatives need to be compatible with the safe frame option.
INCOMPATIBLE The creatives can be incompatible with the safe frame option.

ProgrammaticCreativeSource

Specifies the creative source for the programmatic deal.

Enums
PROGRAMMATIC_CREATIVE_SOURCE_UNSPECIFIED A placeholder for an undefined programmatic creative source.
ADVERTISER The advertiser provides the creatives.
PUBLISHER The publisher provides the creatives to be served.

DeliveryControl

Message contains details about how the deal will be paced.

JSON representation
{
  "deliveryRateType": enum (DeliveryRateType),
  "frequencyCap": [
    {
      object (FrequencyCap)
    }
  ],
  "roadblockingType": enum (RoadblockingType),
  "companionDeliveryType": enum (CompanionDeliveryType),
  "creativeRotationType": enum (CreativeRotationType)
}
Fields
deliveryRateType

enum (DeliveryRateType)

Output only. Specifies how the impression delivery will be paced.

frequencyCap[]

object (FrequencyCap)

Output only. Specifies any frequency caps. Cannot be filtered within ListDealsRequest.

roadblockingType

enum (RoadblockingType)

Output only. Specifies the roadblocking type in display creatives.

companionDeliveryType

enum (CompanionDeliveryType)

Output only. Specifies roadblocking in a master companion lineitem.

creativeRotationType

enum (CreativeRotationType)

Output only. Specifies strategy to use for selecting a creative when multiple creatives of the same size are available.

DeliveryRateType

Specifies how the impression delivery will be paced.

Enums
DELIVERY_RATE_TYPE_UNSPECIFIED A placeholder for an undefined delivery rate type.
EVENLY Impressions are served uniformly over the life of the deal.
FRONT_LOADED Impressions are served front-loaded.
AS_FAST_AS_POSSIBLE Impressions are served as fast as possible.

FrequencyCap

Message contains details about publisher-set frequency caps of the delivery.

JSON representation
{
  "maxImpressions": integer,
  "timeUnitsCount": integer,
  "timeUnitType": enum (TimeUnitType)
}
Fields
maxImpressions

integer

The maximum number of impressions that can be served to a user within the specified time period.

timeUnitsCount

integer

The amount of time, in the units specified by timeUnitType. Defines the amount of time over which impressions per user are counted and capped.

timeUnitType

enum (TimeUnitType)

The time unit. Along with num_time_units defines the amount of time over which impressions per user are counted and capped.

TimeUnitType

Specifies the time-unit type for delivery control.

Enums
TIME_UNIT_TYPE_UNSPECIFIED A placeholder for an undefined time unit type. This just indicates the variable with this value hasn't been initialized.
MINUTE Minute unit.
HOUR Hour unit.
DAY Day unit.
WEEK Week unit.
MONTH Month unit.
LIFETIME Lifecycle/Lifetime unit.
POD Pod unit.
STREAM Stream unit.

RoadblockingType

Describes the roadblocking types.

Enums
ROADBLOCKING_TYPE_UNSPECIFIED A placeholder for an unspecified roadblocking type.
ONLY_ONE Only one creative from a deal can serve per ad request. https://support.google.com/admanager/answer/177277.
ONE_OR_MORE Any number of creatives from a deal can serve together per ad request.
AS_MANY_AS_POSSIBLE As many creatives from a deal as can fit on a page will serve. This could mean anywhere from one to all of a deal's creatives given the size constraints of ad slots on a page.
ALL_ROADBLOCK All or none of the creatives from a deal will serve.
CREATIVE_SET A master/companion creative set roadblocking type.

CompanionDeliveryType

Specifies Master/Companion delivery options.

Enums
COMPANION_DELIVERY_TYPE_UNSPECIFIED A placeholder for an unspecified companion delivery type.
DELIVERY_OPTIONAL Companions are not required to serve a creative set. The creative set can serve an inventory that has zero or more matching companions.
DELIVERY_AT_LEAST_ONE At least one companion must be served in order for the creative set to be used.
DELIVERY_ALL All companions in the set must be served in order for the creative set to be used. This can still serve to inventory that has more companions than can be filled.

CreativeRotationType

The strategy to use for selecting a creative when multiple creatives of the same size is available.

Enums
CREATIVE_ROTATION_TYPE_UNSPECIFIED Creatives are displayed roughly the same number of times over the duration of the deal.
ROTATION_EVEN Creatives are displayed roughly the same number of times over the duration of the deal.
ROTATION_OPTIMIZED Creatives are served roughly proportionally to their performance.
ROTATION_MANUAL Creatives are served roughly proportionally to their weights.
ROTATION_SEQUENTIAL Creatives are served exactly in sequential order, aka Storyboarding.

Methods

batchUpdate

Batch updates multiple deals in the same proposal.

get

Gets a deal given its name.

list

Lists all deals in a proposal.

patch

Updates the given deal at the buyer known revision number.