type Proposal (v201808)

A Proposal represents an agreement between an interactive advertising seller and a buyer that specifies the details of an advertising campaign.


Namespace
https://www.google.com/apis/ads/publisher/v201808

Field

id

xsd:long

The unique ID of the Proposal. This attribute is read-only.

isProgrammatic

xsd:boolean

Flag that specifies whether this Proposal is for programmatic deals. This value is default to false.

dfpOrderId

xsd:long

The unique ID of corresponding Order. This will be null if the Proposal has not been pushed to Ad Manager. This attribute is read-only.

name

xsd:string

The name of the Proposal. This value has a maximum length of 255 characters. This value is copied to Order.name when the proposal turns into an order. This attribute can be configured as editable after the proposal has been submitted. Please check with your network administrator for editable fields configuration.

This attribute is required.

pricingModel

PricingModel

The option to specify whether the Proposal uses the Net or Gross pricing model. This field is optional and defaults to PricingModel.NET.


Enumerations
NET
Indicates using net pricing model to calculate the price.
GROSS
Indicates using gross pricing model to calculate the price.
UNKNOWN
The value returned if the actual value is not exposed by the requested API version.

This attribute is applicable when:
  • not using programmatic, using sales management.

startDateTime

DateTime

The date and time at which the order and line items associated with the Proposal are eligible to begin serving. This attribute is derived from the proposal line item of the proposal which has the earliest ProposalLineItem.startDateTime. This attribute will be null, if this proposal has no related line items, or none of its line items have a start time. This attribute is read-only.

endDateTime

DateTime

The date and time at which the order and line items associated with the Proposal stop being served. This attribute is derived from the proposal line item of the proposal which has the latest ProposalLineItem.endDateTime. This attribute will be null, if this proposal has no related line items, or none of its line items have an end time. This attribute is read-only.

timeZoneId

xsd:string

The time zone ID in tz database format (e.g. "America/Los_Angeles") for this Proposal. The startDateTime and endDateTime will be returned in this time zone. This attribute is optional and defaults to the network's time zone.

This attribute is applicable when:
  • not using programmatic, using sales management.

status

ProposalStatus

The status of the Proposal. This attribute is read-only.


Enumerations
DRAFT
Indicates that the Proposal has just been created or retracted but no approval has been requested yet.
PENDING_APPROVAL
Indicates that a request for approval has been made for the Proposal.
APPROVED
Indicates that the Proposal has been approved and is ready to serve.
REJECTED
Indicates that the Proposal has been rejected in the approval workflow.
UNKNOWN
The value returned if the actual value is not exposed by the requested API version.

isArchived

xsd:boolean

The archival status of the Proposal. This attribute is read-only.

advertiser

ProposalCompanyAssociation

The advertiser, to which this Proposal belongs, and a set of Contact objects associated with the advertiser. The ProposalCompanyAssociation.type of this attribute should be ProposalCompanyAssociationType.ADVERTISER. This attribute is required when the proposal turns into an order, and its ProposalCompanyAssociation.companyId will be copied to Order.advertiserId. This attribute becomes readonly once the Proposal has been pushed.

agencies

ProposalCompanyAssociation[]

List of agencies and the set of Contact objects associated with each agency. This attribute is optional. A Proposal only has at most one Company with ProposalCompanyAssociationType.PRIMARY_AGENCY type, but a Company can appear more than once with different ProposalCompanyAssociationType values. If primary agency exists, its ProposalCompanyAssociation.companyId will be copied to Order.agencyId when the proposal turns into an order.

probabilityOfClose

xsd:long

The probability to close this Proposal. This percentage value is in terms of millipercent, and should be multiples of 10 with the range from 0 to 100000. This attribute will be used to calculate the revenue in reporting.

This attribute is applicable when:
  • using programmatic guaranteed, using sales management.
  • not using programmatic, using sales management.
This attribute is required when:
  • using programmatic guaranteed, using sales management.
  • not using programmatic, using sales management.

billingCap

BillingCap

The billing cap of this Proposal. This attribute is optional and default value is BillingCap.CAPPED_CUMULATIVE. Either this attribute or billingSchedule will be used, according to the billingSource. This attribute can be configured as editable after the proposal has been submitted. Please check with your network administrator for editable fields configuration.


Enumerations
NO_CAP
There is no cap for each billing month.
CAPPED_CUMULATIVE
Use a billing source of capped actuals with a billing cap of cumulative to bill your advertiser up to a campaign's capped amount, regardless of the number of impressions that are served each month.
CAPPED_PER_BILLING_CYCLE
Use a billing source of capped actuals with a billing cap of the billing cycle to bill your advertiser up to a capped amount for each billing cycle of a campaign, regardless of the number of impressions that are served.
CAPPED_CUMULATIVE_PER_BILLING_CYCLE
Use a billing source of capped actuals with a billing cap of cumulative per billing cycle to bill your advertiser up to a capped amount for each billing cycle of a campaign and carry forward the balance of over- or under-delivered impressions towards the number of impressions delivered in future billing cycles of the campaign.
CAPPED_WITH_ROLLOVER_PER_BILLING_CYCLE
Use a billing source of capped actuals with a billing cap of cumulative per billing cycle to bill your advertiser up to a capped amount for each cycle of a campaign and carry forward the balance of over- or under-delivered impressions towards the number of impressions delivered in future cycles of the campaign.
UNKNOWN
The value returned if the actual value is not exposed by the requested API version.

This attribute is applicable when:
  • not using programmatic, using sales management.

billingSchedule

BillingSchedule

The billing schedule of this Proposal. This attribute is optional and default value is BillingSchedule.PRORATED. Either this attribute or billingCap will be used, according to the billingSource. This attribute can be configured as editable after the proposal has been submitted. Please check with your network administrator for editable fields configuration.


Enumerations
PREPAID
Charged based on the contracted value after the first month of the campaign.
END_OF_THE_CAMPAIGN
Charged based on the contracted value after the last month of the campaign.
STRAIGHTLINE
Use a billing source of contracted with a billing schedule of straightline to bill your advertiser the same amount each month, regardless of the number of days in each month.
PRORATED
Use a billing source of contracted with a billing schedule of prorated to bill your advertiser proportionally based on the amount of days in each month.
UNKNOWN
The value returned if the actual value is not exposed by the requested API version.

This attribute is applicable when:
  • not using programmatic, using sales management.

billingSource

BillingSource

The billing source of this Proposal. This attribute is optional and default value is BillingSource.THIRD_PARTY_VOLUME. If the value is BillingSource.CONTRACTED, the billingSchedule will be used for billing, otherwise the billingCap will be used. This attribute can be configured as editable after the proposal has been submitted. Please check with your network administrator for editable fields configuration.


Enumerations
CONTRACTED
Charge based on the quantity of impressions, clicks, or days booked, regardless of what actually delivered.
DFP_VOLUME
Charge based on what actually delivered, as counted by Ad Manager.
THIRD_PARTY_VOLUME
Charge based on what actually delivered, as counted by the third party ads server.
UNKNOWN
The value returned if the actual value is not exposed by the requested API version.

This attribute is applicable when:
  • not using programmatic, using sales management.

billingBase

BillingBase

The billing base of this Proposal. For example, for a flat fee contracted billingSource, set this to BillingBase.REVENUE. This attribute is optional and defaults to BillingBase.VOLUME. This attribute can be configured as editable after the proposal has been submitted. Please check with your network administrator for editable fields configuration.


Enumerations
VOLUME
Billing calculation (eg. proration) should be based on volume.
REVENUE
Billing calculation (eg. proration) should be based on revenue.
UNKNOWN
The value returned if the actual value is not exposed by the requested API version.

This attribute is applicable when:
  • not using programmatic, using sales management.

poNumber

xsd:string

User defined purchase order number for the Proposal. This attribute is optional and has a maximum length of 63 characters. It is copied to Order.poNumber when the proposal turns into an order. This attribute can be configured as editable after the proposal has been submitted. Please check with your network administrator for editable fields configuration.

This attribute is applicable when:
  • using programmatic guaranteed, using sales management.
  • not using programmatic, using sales management.

internalNotes

xsd:string

Provides any additional notes that may annotate the Proposal. This attribute is optional and has a maximum length of 65,535 characters. This attribute can be configured as editable after the proposal has been submitted. Please check with your network administrator for editable fields configuration.

budget

Money

The total budget allocated for all the proposal line items belonging to the Proposal. It supports precision of 2 decimal places in terms of the fundamental currency unit, so the Money.microAmount must be multiples of 10000. This attribute is optional and default value is 0. The Money.currencyCode is readonly.

This attribute is applicable when:
  • using programmatic guaranteed, using sales management.
  • not using programmatic, using sales management.

primarySalesperson

SalespersonSplit

The primary salesperson who brokered the transaction with the advertiser. This attribute is required when the proposal turns into an order. This attribute can be configured as editable after the proposal has been submitted. Please check with your network administrator for editable fields configuration.

secondarySalespeople

SalespersonSplit[]

List of secondary salespeople who are responsible for the sales of the Proposal besides primary salesperson. This attribute is optional. A proposal could have 8 secondary salespeople at most, but must also have a primarySalesperson if any secondary salesperson exists. This attribute can be configured as editable after the proposal has been submitted. Please check with your network administrator for editable fields configuration.

This attribute is applicable when:
  • using programmatic guaranteed, using sales management.
  • not using programmatic, using sales management.

salesPlannerIds

xsd:long[]

List of unique IDs of User objects who are the sales planners of the Proposal. This attribute is optional. A proposal could have 8 sales planners at most. This attribute can be configured as editable after the proposal has been submitted. Please check with your network administrator for editable fields configuration.

primaryTraffickerId

xsd:long

The unique ID of the User who is primary trafficker and is responsible for trafficking the Proposal. This attribute is required when the proposal turns into an order, and will be copied to Order.primaryTraffickerId . This attribute can be configured as editable after the proposal has been submitted. Please check with your network administrator for editable fields configuration.

secondaryTraffickerIds

xsd:long[]

List of unique IDs of User objects who are responsible for trafficking the Proposal besides the primary trafficker. This attribute is optional. A proposal could have 8 secondary traffickers at most, but must also have a primary trafficker if any secondary trafficker exists. This attribute can be configured as editable after the proposal has been submitted. Please check with your network administrator for editable fields configuration.

This attribute is applicable when:
  • using programmatic guaranteed, using sales management.
  • not using programmatic, using sales management.

sellerContactIds

xsd:long[]

users who are the seller's contacts.

This attribute is applicable when:
  • using programmatic guaranteed, using sales management.
  • using programmatic guaranteed, not using sales management.
  • using preferred deals, not using sales management.

appliedTeamIds

xsd:long[]

The IDs of all teams that the Proposal is on directly. This attribute is optional. This attribute can be configured as editable after the proposal has been submitted. Please check with your network administrator for editable fields configuration.

customFieldValues

  1. BaseCustomFieldValue[]
    1. CustomFieldValue
    2. DropDownCustomFieldValue

The values of the custom fields associated with the Proposal. This attribute is optional. This attribute can be configured as editable after the proposal has been submitted. Please check with your network administrator for editable fields configuration.

appliedLabels

AppliedLabel[]

The set of labels applied directly to the Proposal. This attribute is optional.

effectiveAppliedLabels

AppliedLabel[]

Contains the set of labels applied directly to the proposal as well as those inherited ones. If a label has been negated, only the negated label is returned. This attribute is read-only.

advertiserDiscount

xsd:long

The discount applied to the Proposal according to the advertiser. The percentage value is stored as millipercents, and must be multiples of 10 with the range from 0 to 99990. This attribute is optional and default value is 0.

This attribute is applicable when:
  • using programmatic guaranteed, using sales management.
  • not using programmatic, using sales management.

proposalDiscount

xsd:long

The proposal discount, which will be applied to all ProposalLineItem objects in the Proposal. The percentage value is stored as millipercents, and must be multiples of 10 with the range from 0 to 99990. This attribute is optional and default value is 0.

This attribute is applicable when:
  • using programmatic guaranteed, using sales management.
  • not using programmatic, using sales management.

currencyCode

xsd:string

The currency code of this Proposal. This attribute is optional and defaults to network's currency code.

exchangeRate

xsd:long

The exchange rate from the currencyCode to the network's currency. The value is stored as the exchange rate times 10,000,000,000 truncated to a long. This attribute is assigned by Google when first created or updated with refreshExchangeRate set to true. This attribute is ignored if the feature is not enabled. This attribute is read-only.

refreshExchangeRate

xsd:boolean

Set this field to true to update the exchangeRate to the latest exchange rate when updating the proposal. This attribute is optional and defaults to false. This attribute is ignored if the feature is not enabled.

agencyCommission

xsd:long

The commission for the primary agency of the Proposal. The percentage value is stored as millipercents, and must be multiples of 10 with the range from 0 to 99990. This attribute is optional and default value is 0.

This attribute is applicable when:
  • not using programmatic, using sales management.

valueAddedTax

xsd:long

The value added tax (VAT) applied on final cost of the Proposal. The percentage value is stored as millipercents, and must be multiples of 10 with the range from 0 to 100000. This attribute is optional and default value is 0.

This attribute is applicable when:
  • not using programmatic, using sales management.

isSold

xsd:boolean

Indicates whether the proposal has been sold, i.e., corresponds to whether the status of an Order is OrderStatus.APPROVED or OrderStatus.PAUSED. This attribute is read-only.

approvalStatus

ProposalApprovalStatus

The approval status of the Proposal for the active user or null if the active user has no action needed.


Enumerations
PENDING
Indicates that the Proposal is pending on active user's approval.
NON_PENDING
Indicates that active user is the approver, and the related approval action(s) of the Proposal has been performed or not activated yet, or the proposal is retracted.
UNKNOWN
The value returned if the actual value is not exposed by the requested API version.

This attribute is applicable when:
  • using programmatic guaranteed, using sales management.
  • not using programmatic, using sales management.
This attribute is read-only when:
  • using programmatic guaranteed, using sales management.
  • not using programmatic, using sales management.

workflowProgress

WorkflowProgress

The progress report for the workflow applied on the Proposal.

This attribute is applicable when:
  • using programmatic guaranteed, using sales management.
  • not using programmatic, using sales management.
This attribute is read-only when:
  • using programmatic guaranteed, using sales management.
  • not using programmatic, using sales management.

lastModifiedDateTime

DateTime

The date and time this Proposal was last modified. This attribute is read-only.

resources

ProposalLink[]

The list of resources on this Proposal. This attribute is optional. This attribute can be configured as editable after the proposal has been submitted. Please check with your network administrator for editable fields configuration.

This attribute is applicable when:
  • not using programmatic, using sales management.

actualExpiryTime

DateTime

The actual date and time at which the inventory reserved by the Proposal will expire.

This attribute is applicable when:
  • using programmatic guaranteed, using sales management.
  • not using programmatic, using sales management.
This attribute is read-only when:
  • using programmatic guaranteed, using sales management.
  • not using programmatic, using sales management.

expectedExpiryTime

DateTime

The expected date and time at which the inventory reserved by the Proposal will expire.

This attribute is applicable when:
  • using programmatic guaranteed, using sales management.
  • not using programmatic, using sales management.
This attribute is read-only when:
  • using programmatic guaranteed, using sales management.
  • not using programmatic, using sales management.

thirdPartyAdServerId

xsd:int

A predefined third party ad server, which will be used to fill in reconciliation. All predefined third party ad servers can be found in the Third_Party_Company PQL table. If actual third party ad server is not in the predefined list, this field is set to 0, and actual third party ad server name is set in customThirdPartyAdServerName. Third party ad server is optional. By default, this field is 0, and customThirdPartyAdServerName is null which means no third party ad server is specified.

This attribute is applicable when:
  • not using programmatic, using sales management.

customThirdPartyAdServerName

xsd:string

When actual third party ad server is not in the predefined list, thirdPartyAdServerId is set to 0, and actual third party ad server name is set here. When thirdPartyAdServerId is not 0, this field is ignored.

This attribute is applicable when:
  • not using programmatic, using sales management.

termsAndConditions

ProposalTermsAndConditions[]

A list of terms and conditions for this Proposal. This field is optional.

This attribute is applicable when:
  • not using programmatic, using sales management.

lastRetractionDetails

RetractionDetails

Details describing the most recent proposal retraction.

This attribute is applicable when:
  • using programmatic guaranteed, using sales management.
  • not using programmatic, using sales management.
This attribute is read-only when:
  • using programmatic guaranteed, using sales management.
  • not using programmatic, using sales management.

marketplaceInfo

ProposalMarketplaceInfo

The marketplace info of this proposal if it has a corresponding order in Marketplace.

This attribute is applicable when:
  • using programmatic guaranteed, using sales management.
  • using programmatic guaranteed, not using sales management.

offlineErrors

OfflineError[]

Errors that occurred during offline processes. If any errors occur during an offline process, such as reserving inventory, this field will be populated with those errors, otherwise this field will be null. This attribute is read-only.

hasOfflineErrors

xsd:boolean

Whether errors occured during offline processes. This attribute is read-only.

buyerRfp

BuyerRfp

The buyer RFP associated with this Proposal, which is optional. This field will be null if the proposal is not initiated from RFP.

This attribute is applicable when:
  • using programmatic guaranteed, not using sales management.
  • using preferred deals, not using sales management.

hasBuyerRfp

xsd:boolean

Whether a Proposal contains a BuyerRfp field. If this field is true, it indicates that the Proposal in question orignated from a buyer.

This attribute is applicable when:
  • using programmatic guaranteed, not using sales management.
  • using preferred deals, not using sales management.

Send feedback about...

Ad Manager API
Ad Manager API
Need help? Visit our support page.