Deal Terms object
The deal terms reflect the type of deal and contains high-level fields used to define composition, permissions, and financial terms. This page focuses on the financial terms and flight information of the deal. For other terms, see the links in the description.
Here's what you need to know about deal terms:
- The selling party must select only one object for terms: either a
commitmentTermsorendeavorTermsobject. Depending on this selection, the deal created would be a commitment deal or an endeavor deal, each with different required fields. For details, see Deal types. - Commitment deals can specify additional terms for expansion and cancellation to ensure the fulfillment of committed spending.
- Commitment deals require strict adherence to financial terms, while endeavors don't require these financial constraints.
- To further improve your ability to meet your media spend goal, you can apply contributing deals to commitment or endeavor deals with a media spend goal. This counts eligible spend from the linked contributing deals toward the spend goal of another deal.
CommitmentTerms object
The CommitmentTerms object represents the terms in a commitment deal, and includes commitment-specific elements such as expansion terms and cancellation terms. The Trade Desk monitors and enforces all terms in a commitment deal.
| Field | Required? | Data Type | Description |
|---|---|---|---|
flight |
Required | Object | The flight information for the deal, including the start and end dates and times. For details, see DealFlight object. |
financialTerms |
Required | Object | The financial terms of a commitment deal, including committed spend, floor prices, minimum avails, and win rates. For details, see CommitmentFinancialTerms object. |
inventoryComposition |
Required | Object | The inventory delivered through the deal, including channel, content, geos, genres, and categories. For details, see InventoryComposition object. |
expansionTerms |
Optional | Object | A list of criteria that a commitment deal must meet for a buying party to apply deal expansion. Leave blank to disable deal expansion. For details, see ExpansionTerms object. |
cancellationTerms |
Optional | Object | A list of criteria that a commitment deal must meet for a buying party to cancel the commitment deal. For details, see CancellationTerms object. |
contributingDeals |
Optional | Object array | A list of contributing deals. These deals can count toward spend for this deal. For details, see ContributingDeal object. |
ExpansionTerms object
The ExpansionTerms object defines the conditions under which a commitment deal can be expanded. If the daily spend of the deal falls below the expansion threshold for longer than the agreed expansion period, the deal becomes eligible for expansion. Deal expansion remains available for the remaining lifetime of the deal.
| Field | Required? | Data Type | Description |
|---|---|---|---|
period |
Required | Integer | The number of consecutive days the daily spend of the deal must remain below the daily spend threshold. The default and minimum value is three days. IMPORTANT: The maximum value is 30 days. |
threshold |
Required | Decimal | The percentage of daily spend that acts as a buffer before a deal can qualify for deal expansion. For example, a value of 0.99 sets a threshold of 99%. |
floorPrice |
Required | Decimal | The adjusted lowest CPM bid allowed for additional inventory delivered through the deal expansion. The floor price for inventory that matches the unexpanded terms remains unchanged. |
CancellationTerms object
The CancellationTerms object defines the conditions under which a deal can be canceled. If the daily spend of the deal falls below the cancellation threshold for the agreed cancellation period, the deal becomes eligible for cancellation. The deal remains eligible for cancellation until its pacing returns to 100%.
The buying party becomes eligible to cancel the deal when daily spend is below the threshold value for the established period value, and the selling party provides a win rate or qualified avails below the minimums declared in the CommitmentFinancialTerms object. Similarly, the selling party may choose to cancel the deal if the daily spend is below the threshold value for the established period value, or the buying party's bid rate drops below the value stated in the deal terms.
| Field | Required? | Data Type | Description |
|---|---|---|---|
period |
Required | Integer | The number of consecutive days the daily spend of the deal must remain below the daily spend threshold. The default and minimum value is three days. IMPORTANT: The maximum value is 30 days. |
threshold |
Required | Decimal | The percentage of daily spend that acts sa a buffer before a deal can qualify for deal cancellation. For example, a value of 0.99 sets a threshold of 99%. |
EndeavorTerms object
The EndeavorTerms object defines the structure of a deal, including its inventory composition, any optional media spend goal, or any special pricing arrangements. These deals represent inventory offered by a selling party (such as a publisher or intermediary) to a buying party (such as an advertiser) for consideration.
| Field | Required? | Data Type | Description |
|---|---|---|---|
flight |
Required | Object | The flight information for the deal, including the start and end dates and times. For details, see DealFlight object. |
financialTerms |
Required | Object | The floor prices, auction type, and other financial terms for an endeavor deal. For details, see EndeavorFinancialTerms object. |
inventoryComposition |
Required | Object | The inventory delivered through the deal, including channel, content, geos, genres, and categories. For details, see InventoryComposition object. |
contributingDeals |
Optional | Object array | A list of contributing deals. These deals can count toward spend for this deal. For details, see ContributingDeal object. |
Financial terms objects
Financial terms specify the pricing structure and monetary requirements for a deal, such as floor prices, spend targets, auction types and performance thresholds. These terms and requirements vary by deal type.
CommitmentFinancialTerms object
The CommitmentFinancialTerms object represents the financial terms for commitment deals, including target spend, floor prices, minimum avails, and win rates. For examples, see Commitment financial terms.
IMPORTANT: The required commitment financial terms must also be non-zero.
| Field | Required? | Data Type | Description |
|---|---|---|---|
currencyCode |
Required | String | The three-letter currency code for the amount as specified in ISO 4217. |
mediaSpendGoal |
Required | Decimal | The amount an advertiser has made a hard commitment to spend. |
floorPrice |
Required | Decimal | The lowest CPM bid allowed for the inventory through this commitment. |
minCpmPerSec |
Optional | Decimal | The lowest price an advertiser can expect to buy inventory at and is calculated as CPM per second. This translates to an actual CPM for an audio or video ad by multiplying the ad duration in seconds by this value. This element applies to CTV channel, video channel, or audio channel. This isn't an absolute floor, but rather an indication of the expected minimum price to clear. |
auctionType |
Required | String enum | The type of auction for the deal. For details, see Auction Type Enumeration Values. |
minDailyAvails |
Optional | Long | The minimum number of avails that the selling party has committed to send each day. |
minWinRate |
Optional | Decimal | The minimum percentage of the buying party's bids that the selling party has promised they will win. If the win rate drops below this amount, the deal may be automatically paused after seven days and the buying party is released from their commitment. NOTE: This value must be greater than 0 and less than or equal to 1, where 1 represents 100%. |
nonDecisionedEligible |
Read-only | Boolean | Determines whether the deal meets the requirements to use non-decisioned features. |
nonDecisionedIneligibilityReasons |
Read-only | String array | A list of reasons why the deal is inelligible for use with non-decisioned features. If the deal is elligible, this returns an empty list. |
calculateNonDecisionedTerms |
Optional | Boolean | When set to true, The Trade Desk performs a bid rate calculation to check if a buying party can use non-decisioned mode. When the minimum number of daily avails or minimum win rate values isn't set, The Trade Desk sets the minimum daily avails and win rate of this deal. This allows for non-decisioned deal eligibility, based on a 90% minimum bid rate requirement. When set to false or is empty, the calculation isn't performed and doesn't change the deal terms. IMPORTANT: Do not set this value if your deal uses variable price as the auction type. |
The following formula shows how these values are used to calculate the minimum bid rate. For details, see FAQs.
EndeavorFinancialTerms object
The EndeavorFinancialTerms object represents the financial terms for endeavor deals. For examples, see Endeavor financial terms.
| Field | Required? | Data Type | Description |
|---|---|---|---|
currencyCode |
Required | String | The three-letter currency code for the amount as specified in ISO 4217. |
floorPrice |
Optional | Decimal | The lowest CPM bid allowed for the inventory in this deal. |
mediaSpendGoal |
Optional | Decimal | The amount an advertiser will endeavor to spend on this deal. IMPORTANT: Once set, this value cannot be removed. |
minCpmPerSec |
Optional | Decimal | The lowest price an advertiser can expect to buy inventory at and is calculated as CPM per second. This translates to an actual CPM for an audio or video ad by multiplying the ad duration in seconds by this value. This element applies to CTV channel, video channel, or audio channel. This isn't an absolute floor, but rather an indication of the expected minimum price to clear. |
auctionType |
Optional | String enum | The type of auction for the deal. For details, see Auction type enumeration values. |
DealFlight object
The DealFlight object represents the start and end time and date for a deal. For examples, see Deal flight duration.
| Field | Required? | Data Type | Description |
|---|---|---|---|
startAt |
Required | DateTime | The start date and time of the deal in UTC. Bids on avails from this deal start only after this date. |
endAt |
Required | DateTime | The end date and time of the deal in UTC. Bids on avails from this deal end after this date. This value must be within two years after the start date. |
timeZone |
Required | String | A representation of the time zone used to show the start and end dates of the deal in the UI. If set to null, the default time zone in the UI is UTC. NOTE: This value does not convert the datetime format, all datetime values must be sent in UTC. |
ContributingDeal object
The ContributingDeal object represents deals that can contribute toward your commitment or endeavor deals with a media spend goal.
| Field | Required? | Data Type | Description |
|---|---|---|---|
id |
Required | String | The ID of an endeavor deal without spend goals, which can contribute spend to this deal. |
ownerId |
Required | String | The known agent ID (KAID) of the seller or intermediary that owns the contributing deal. |
Auction type enumeration values
The following table lists the types of auctions a deal can participate in. This value is included in the financial terms of commitment or endeavor deals.
| Enum Value | Description |
|---|---|
FIRST_PRICE_AUCTION |
The auction winner pays the exact amount of their submitted bid. |
SECOND_PRICE_AUCTION |
The auction winner pays the amount of the second-highest bid. |
FIXED_PRICE_AUCTION |
The auction winner pays a predetermined price agreed upon in advance. |