Draft deal terms
As a selling party, when drafting a deal, you must specify what you are offering the buying party within the terms of the deal. This can range from exclusive access to premium inventory, a specific type of audience based on device, location, channels and networks, or content that matches certain genres or taxonomies. After identifying the Deal participants, set the deal type—commitment or endeavor—and define the rest of the deal terms.
IMPORTANT: To send a successful request, you must define the deal type by using either the
commitmentTermsorendeavorTermsfield. You cannot change the deal type once it has been accepted—if you need to switch types, you must create a new deal or upgrade the deal. For field details, see Deal Terms object.
Here's what you need to know about deal terms:
- Deal terms for inventory, supply, content categories, and flight details are the same for both commitments and endeavors.
- Your bidding terms must align with the category taxonomy defined during deal creation.
The following sections show which terms are a required to construct a deal. These terms have requirements that change depending on the deal type. To select a deal type, consider the requirements of your deal and what information both parties can provide. For details, see Deal creation differences.
NOTE: All code examples in this section create an endeavor deal for simplicity, but the same fields apply to commitments.
The following table lists the terms shared by commitment and endeavor deals. For more terms specific to commitment deals, see also Create commitment deals.
| Field | Description | Object Reference |
|---|---|---|
financialTerms |
Monetary constraints that can differ from a commitment or endeavor deal type. For details on differences by deal type, see Financial terms. |
|
flight |
The details on the duration of the deal. For details, see Deal flight duration. | DealFlight object |
inventoryComposition |
Allows or blocks supply from sellers and publishers, and has additional filters for web domains, applications, and placements. For details, see Inventory composition terms. | InventoryComposition object |
Financial terms
The financial terms for an endeavor and commitment differ by available fields, optional fields, and how it's used by The Trade Desk to monitor deal performance metrics.
The following table shows the differences between the available financial terms by deal type, listed in alphabetical order.
NOTE: Terms that support the Endeavor or Commitment deal type have a ✅ checkmark icon in their respective column. Terms that don't apply are marked as N/A, and requirements specific to deal type are labeled accordingly.
| Financial Term | Endeavor | Commitment | Description | Required? |
|---|---|---|---|---|
auctionType |
✅ | ✅ | The type of auction specified as an enum value. | Required for commitments. |
currencyCode |
✅ | ✅ | The denomination of the currency. For example, the US dollar is USD. |
Required for both deal types. |
floorPrice |
✅ | ✅ | The lowest CPM bid allowed for the inventory in this deal. | Required for commitments. |
mediaSpendGoal |
✅ | ✅ | The required amount that the buying party commits to media spend. | Required for commitments. |
minCpmPerSec |
✅ | ✅ | 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. |
Optional for both deal types. |
minWinRate |
N/A | ✅ | The minimum win rate for bids that you promise to the buying party. NOTE: This value must be greater than 0 and less than or equal to 1, where 1 represents 100%. |
Required for commitments. |
minDailyAvails |
N/A | ✅ | The minimum number of avails per day that you agree to send to buying party. | Required for commitments. |
For additional details on endeavors, see Endeavor financial terms. For additional details on commitments, see Commitment financial terms.
Deal flight duration
After finalizing the deal terms, set the deal flight duration by selecting a start and end date following datetime format.
Here's what you need to know about flight durations:
- The API limits flights to a maximum duration of two years from the start date.
- All times are stored in UTC, following the Internet Assigned Numbers Authority Time Zone Database (IANA TZDB).
- You can optionally specify a time zone for display purposes using the
timeZonefield. If you are using a UI outside of The Trade Desk, check if they can convert your time zone from UTC.
The following example dealCreate mutation shows the structure of the DealFlight object. For details, see DealFlight object.
mutation {
dealCreate(
input: {
# DEAL NAME AND PARTICIPANT DETAILS GO HERE!
terms: {
endeavorTerms: {
flight: {
endAt: "2025-11-20T04:59:00.000Z"
startAt: "2025-11-05T16:49:30.370Z"
timeZone: "UTC"
}
}
}
}
)
}
Inventory composition terms
Inventory composition terms describe the type of inventory to include or exclude from the deal. If you are creating a commitment deal, additional subterms might be required. For details, see Create commitment deals.
When adding composition terms, you can add the following:
- Bid signal
- Categories
- First-party data
- Keywords
- Mobile apps
- Placement IDs
- Seller IDs
- Sites
The following example dealCreate mutation shows the structure of the inventoryComposition object. For details, see InventoryComposition object. See also Standardized inventory queries.
IMPORTANT: This sample is for demonstration purposes and shows all possible composition values. In actual use, some properties require you to choose either
includedorexcludedfields—not both. See also Inventory Selection object.
mutation {
dealCreate(
input: {
# DEAL NAME AND PARTICIPANT DETAILS GO HERE!
terms: {
endeavorTerms: {
inventoryComposition: {
biddingTerms: ["IMP_EXT_GPID", "SOURCE_TID", "USER_ID", "VIDEO_PODID", "AUDIO_PODID"]
customAttributes: {
base: {
excludedValues: ["abcd123"]
includedValues: ["xyz456"]
key: "key1"
section: IMPRESSION
}
}
# These values are geo segment IDs.
consumerGeos: {
base: {
excluded: ["q5xb319t45"]
included: ["8t9awngqi4"]
}
}
publisherCategories: {
base: {
excluded: ["644", "551"]
included: ["360", "366"]
}
}
publisherKeywords: {
base: {
excluded: ["drugs"]
included: ["summer"]
}
}
apps: {
base: {
excluded: ["com.bundle.com"]
included: ["123456789"]
}
}
placementIds: {
base: {
excluded: ["/1111/homepage#div-rightnav#2"]
included: ["/1111/homepage#div-leftnav"]
}
}
publisherIds: {
base: {
excluded: ["BLOCKED_PUBLISHER_KAID_PLACEHOLDER"]
included: ["ALLOWED_PUBLISHER_KAID_PLACEHOLDER"]
}
}
sellerIds: {
base: {
excluded: ["BLOCKED_SELLER_KAID_PLACEHOLDER"]
included: ["ALLOWED_SELLER_KAID_PLACEHOLDER"]
}
}
sites: {
base: {
excluded: ["finance.example.com"]
included: ["example.com"]
}
}
}
}
}
}
)
}
The following table lists additional terms that are part of inventory composition.
| Field | Required? | Description | Object Reference |
|---|---|---|---|
contentComposition |
Optional | Allows and blocks supply that follows the IAB content specifications. The IAB specification used matches the categoryTaxonomy property of your deal. For details, see Content composition. |
ContentComposition object |
deviceComposition |
Optional | Deal properties that are trackable by device, such as geos, browsers, and operating systems. For details, see Device composition. | DeviceComposition object |
inventoryChannelComposition |
Required | The channel-specific deal settings for one or more of the following inventory channels:
|
Inventory channel objects |
Content composition
Content composition describes search-related content associated with the inventory. Within these compositions, you can include or exclude content based on the values defined in the Content signal taxonomy. Taxonomies can follow either the IAB version 1.0 content taxonomy or the updated IAB version 2.2 content taxonomy. For details, see IAB content taxonomy mapping: Version 1.0 to 2.2.
When adding supply composition terms, you can add the following:
- Content categories
- Content keywords
- Content languages
- Content ratings
- Genres
- Series
- Titles
The following example dealCreate mutation shows the structure of an endeavor deal following the IAB version 2.2 content taxonomy. For details, see ContentComposition object.
IMPORTANT: This sample is for demonstration purposes and shows all possible composition values. In actual use, some properties require you to choose either the
includedorexcludedfields—not both. See also Inventory Selection object.
mutation {
dealCreate(
input: {
# DEAL NAME AND PARTICIPANT DETAILS GO HERE!
categoryTaxonomy: IAB_TECH_LAB_CONTENT_TAXONOMY_2_2
terms: {
endeavorTerms: {
contentComposition: {
contentCategories: {
base: {
excluded: ["644", "551"]
included: ["360", "366"]
}
expansion: {
excluded: ["544"]
included: ["347"]
}
}
genres: {
base: {
excluded: ["Law", "Late Night"]
included: ["Mystery", "Action"]
}
}
contentLanguages: {
base: {
excluded: ["12"]
included: ["11"]
}
}
contentRatings: {
base: {
excluded: ["NC-17", "TV-MA", "X", "R 18+"]
included: ["PG-13", "TV-PG", "R 15+", "FSK-16"]
}
}
series: {
base: {
excluded: ["Generic Horror Show"]
included: ["Generic Music Show"]
}
}
contentKeywords: {
base: {
excluded: ["death", "political", "alcohol"]
included: ["pet", "kids"]
}
}
titles: {
base: {
excluded: ["Generic Horror Title"]
included: ["Generic Music Title"]
}
}
}
}
}
}
)
}
Device composition
Device composition terms enable you to allow or block inventory based on the mappings for the following device information:
- Browser
- Device make
- Geo location
- Language
- Mobile carrier
- Operating system
The following example dealCreate mutation shows defines the structure of the deviceComposition object. For details, see DeviceComposition object.
IMPORTANT: This sample is for demonstration purposes and shows all possible composition values. In actual use, some properties require you to choose either
includedorexcluded—not both. See also Inventory Selection object.
mutation {
dealCreate(
input: {
# DEAL NAME AND PARTICIPANT DETAILS GO HERE!
terms: {
endeavorTerms: {
deviceComposition: {
browsers: {
base: {
excluded: ["13"]
included: ["6"]
}
}
deviceMakes: {
base: {
excluded: ["1"]
included: ["2"]
}
}
mobileCarriers: {
base: {
excluded: ["1"]
included: ["2"]
}
}
operatingSystems: {
base: {
excluded: ["6"]
included: ["5"]
}
}
}
}
}
}
)
}
Inventory channel composition
Use the inventoryChannelComposition object to select from multiple inventory channels, each with its own profile:
- Audio
- CTV
- Digital out-of-home (DOOH)
- Display
- Native display
- Native video
- Video
The following example dealCreate mutation shows the structure of inventory channels in a deal. For details, see Inventory channel objects.
IMPORTANT: This sample is for demonstration purposes and shows all possible values. Some properties require you to choose either
includedorexcluded—not both. See also Inventory Selection object.
mutation {
dealCreate(
input: {
# DEAL NAME AND PARTICIPANT DETAILS GO HERE!
terms: {
commitmentTerms {
inventoryChannelComposition: {
audioChannel: {
adEnvironments: {
base: {
excluded: [WEB]
included: [IN_APP]
}
}
audio: {
liveStream: {
base: true
}
startDelay: {
base: {
excluded: [MID_ROLL]
included: [POST_ROLL,PRE_ROLL]
}
}
podSeq: {
base: {
excluded: [ANY]
included: [FIRST, LAST]
}
}
feed: {
base: {
excluded: [CATCH_UP_RADIO, FM_AM_BROADCAST]
included: [MUSIC_STREAMING_SERVICE, PODCAST]
}
}
slotInPod: {
base: {
excluded: [ANY]
included: [FIRST_OR_LAST]
}
}
}
deviceTypes: {
base: {
excluded: [OTHER, OUT_OF_HOME]
included: [MOBILE, TABLET]
}
}
channels: {
base: {
excluded: ["CHANNEL_NAME_PLACEHOLDER_1"]
included: ["CHANNEL_NAME_PLACEHOLDER_2", "CHANNEL_NAME_PLACEHOLDER_3"]
}
}
networks: {
base: {
excluded: ["NETWORK_NAME_PLACEHOLDER_1"]
included: ["NETWORK_NAME_PLACEHOLDER_2"]
}
}
productionQualities: {
base: {
included: [PROFESSIONAL]
excluded: [USER_GENERATED_CONTENT]
}
}
}
ctvChannel: {
adEnvironments: {
base: {
excluded: [MOBILE_OPTIMIZED_WEB]
included: [IN_APP, WEB]
}
}
ctv: {
liveStream: {
base: true
}
startDelay: {
base: {
excluded: [MID_ROLL]
included: [POST_ROLL,PRE_ROLL]
}
}
podSeq: {
base: {
excluded: [ANY]
included: [FIRST, LAST]
}
}
slotInPod: {
base: {
excluded: [ANY]
included: [FIRST_OR_LAST]
}
}
}
deviceTypes: {
base: {
excluded: [OTHER, OUT_OF_HOME]
included: [MOBILE, TABLET]
}
}
channels: {
base: {
excluded: ["CHANNEL_NAME_PLACEHOLDER_1"]
included: ["CHANNEL_NAME_PLACEHOLDER_2", "CHANNEL_NAME_PLACEHOLDER_3"]
}
}
networks: {
base: {
excluded: ["NETWORK_NAME_PLACEHOLDER_1"]
included: ["NETWORK_NAME_PLACEHOLDER_2"]
}
}
}
doohChannel: {
venueTypes: {
base: {
excluded: ["06"]
included: ["0602"]
}
}
mediaType: {
audio: {
liveStream: {
base: true
}
startDelay: {
base: {
excluded: [MID_ROLL]
included: [POST_ROLL,PRE_ROLL]
}
}
podSeq: {
base: {
excluded: [ANY]
included: [FIRST, LAST]
}
}
feed: {
base: {
excluded: [CATCH_UP_RADIO, FM_AM_BROADCAST]
included: [MUSIC_STREAMING_SERVICE, PODCAST]
}
}
slotInPod: {
base: {
excluded: [ANY]
included: [FIRST_OR_LAST]
}
}
}
display: {
adFormats: {
base: {
included: ["6"]
}
}
}
video: {
liveStream: {
base: true
}
skippability: {
base: false
}
videoDimensions: {
base: {
included: {
height: 1080
width: 1920
}
}
}
startDelay: {
base: {
excluded: [MID_ROLL]
included: [POST_ROLL,PRE_ROLL]
}
}
plcmt: {
base: {
excluded: [ACCOMPANYING_CONTENT]
included: [INSTREAM]
}
}
}
}
}
displayChannel: {
adEnvironments: {
base: {
excluded: [MOBILE_OPTIMIZED_WEB]
included: [IN_APP, WEB]
}
}
display: {
adFormats: {
base: {
included: ["6"]
}
}
}
deviceTypes: {
base: {
excluded: [OTHER, OUT_OF_HOME]
included: [MOBILE, TABLET]
}
}
productionQualities: {
base: {
included: [PROFESSIONAL]
excluded: [USER_GENERATED_CONTENT]
}
}
}
nativeDisplayChannel: {
adEnvironments: {
base: {
excluded: [MOBILE_OPTIMIZED_WEB]
included: [IN_APP, WEB]
}
}
display: {
adFormats: {
base: {
included: ["6"]
}
}
}
deviceTypes: {
base: {
excluded: [OTHER, OUT_OF_HOME]
included: [MOBILE, TABLET]
}
}
productionQualities: {
base: {
included: [PROFESSIONAL]
excluded: [USER_GENERATED_CONTENT]
}
}
}
nativeVideoChannel: {
adEnvironments: {
base: {
excluded: [MOBILE_OPTIMIZED_WEB]
included: [IN_APP, WEB]
}
}
video: {
liveStream: {
base: true
}
skippability: {
base: false
}
videoDimensions: {
base: {
included:
{
height: 1080
width: 1920
}
}
}
startDelay: {
base: {
excluded: [MID_ROLL]
included: [POST_ROLL,PRE_ROLL]
}
}
plcmt: {
base: {
excluded: [ACCOMPANYING_CONTENT]
included: [INSTREAM]
}
}
deviceTypes: {
base: {
excluded: [OTHER, OUT_OF_HOME]
included: [MOBILE, TABLET]
}
}
productionQualities: {
base: {
included: [PROFESSIONAL]
excluded: [USER_GENERATED_CONTENT]
}
}
}
videoChannel: {
video: {
liveStream: {
base: true
}
skippability: {
base: false
}
videoDimensions: {
base: {
included: {
height: 1080
width: 1920
}
}
}
startDelay: {
base: {
excluded: [MID_ROLL]
included: [POST_ROLL,PRE_ROLL]
}
}
plcmt: {
base: {
excluded: [ACCOMPANYING_CONTENT]
included: [INSTREAM]
}
}
}
adEnvironments: {
base: {
excluded: [WEB]
included: [IN_APP]
}
}
deviceTypes: {
base: {
excluded: [OTHER, OUT_OF_HOME]
included: [MOBILE, TABLET]
}
}
productionQualities: {
base: {
included: [PROFESSIONAL]
excluded: [USER_GENERATED_CONTENT]
}
}
}
}
}
}
}
}
)
}
Upgrade a deal
While drafting a deal or if your deal has not been accepted, you are able to add stricter terms through the dealUpgrade mutation. Endeavor deals can be upgraded to either include spend goals, or converted to commitment deals. Upgrade is commonly used if your deal requires decisioning features.
IMPORTANT: Deals originating from the EPA API cannot be upgraded. You must recreate them using the PDP API.
Upgrades result in the following deals:
- Upgrade to an endeavor with spend goals
- Upgrade to a commitment deal
Upgrade to an endeavor with spend goals
To upgrade a deal to an endeavor with spend goals, you must have an endeavor deal without spend goals. This mutation does not work on other deals. The following example dealUpgrade mutation converts an endeavor deal to include terms for the mediaSpendGoal field.
mutation {
dealUpgrade(
input: {
id: "DEAL_ID_PLACEHOLDER"
accountId: "ACCOUNT_ID_PLACEHOLDER"
terms: {
endeavorTerms: {
flight: {
startAt: "2025-11-01T00:00:00.000Z"
endAt: "2025-11-30T04:59:00.000Z"
timeZone: "UTC"
}
financialTerms: {
currencyCode: "USD"
mediaSpendGoal: 25000
}
}
}
sellingParty: {
contact: { name: "Sam Seller", email: "samseller@example.com" }
}
upgradedBy: {
name: "Jane Doe"
email: "janedoe@example.com"
}
}
) {
data { id dealType }
errors {
... on MutationError {
__typename
message
field
}
}
}
}
Upgrade to a commitment deal
To upgrade a deal to an commitment deal, you must have an endeavor deal. The following example dealUpgrade mutation converts an endeavor deal to include required commitment terms such as a mediaSpendGoal, minWinRate, mindDailyAvails cancellationTerms, and biddingTerms fields.
mutation {
dealUpgrade(
input: {
id: "DEAL_ID_PLACEHOLDER"
accountId: "ACCOUNT_ID_PLACEHOLDER"
terms: {
commitmentTerms: {
flight: {
startAt: "2025-11-01T00:00:00.000Z"
endAt: "2025-11-30T04:59:00.000Z"
timeZone: "UTC"
}
financialTerms: {
currencyCode: "USD"
auctionType: FIRST_PRICE_AUCTION
floorPrice: 12.50
mediaSpendGoal: 50000
minWinRate: 0.25
minDailyAvails: 1000000
}
cancellationTerms: { period: 7, threshold: 0.8 }
inventoryComposition: {
biddingTerms: ["IMP_EXT_GPID", "SOURCE_TID", "USER_ID", "AUDIO_PODID", "VIDEO_PODID"]
}
}
}
sellingParty: {
contact: { name: "Sam Seller", email: "samseller@example.com" }
}
upgradedBy: {
name: "Jane Doe"
email: "janedoe@example.com"
}
}
) {
data {
id
dealType
current { terms { __typename } }
}
errors {
... on MutationError {
__typename
message
field
}
}
}
}
Next steps
Depending on the type of deal, you must also complete the steps listed in the following sections:
- For additional requirements specific to commitment deals, see Create commitment deals.
- For additional requirements specific to endeavor deals, see Create endeavor deals.