Create commitment deals

A commitment deal is an agreement in the platform that specifies a target cost for media investment and a timeframe for its delivery. These deals must provide additional metadata to help The Trade Desk track pacing, such as a media spend goal and bid stream signals. To increase the chances of full delivery, transparency, and quality of commitment deals, The Trade Desk platform lets you set requirements that outline terms for expansion and cancellation of underperforming deals.

Here's what you need to know about commitment deal creation:

• Commitment deals have the following additional requirements:
  • Financial terms: Commitments must include a media spend goal and promises for delivery between the buying and selling parties.
  • Measurement: Commitments count avails and media spend that match the desired deal terms in the inventory composition or bid stream signals sent.
• You must define an underperformance threshold for deal cancellation. It's recommended to also provide a threshold for deal expansion.
• You can add expansion values within the inventory composition terms. These values apply after the deal is expanded by the buying party.
• The biddingTerms field is required for commitment deals. If you want to observe specific signals during requests, include Bidding terms enumeration values, or leave it empty, if not.

The following sections focus on fields used to pace commitment deals. For a list of all core deal terms, see Draft deal terms.

Commitment deal creation workflow

To create a commitment deal, you must set terms for pacing, such as financial terms and optional cancellation terms. In addition, commitments can have optional expansion terms to provide access to more inventory if the deal underpaces.

Workflow diagram

The following commitment deal creation diagram illustrates the required and optional terms that you can add to your terms.

IMPORTANT: The following commitment deal creation workflow diagram doesn't include other required terms. To create a commitment deal, you must complete the steps in Initiate and negotiate deals.

Process overview

The following table outlines the process step by step and provides links to related workflows, while the diagram in the preceding section illustrates the decision-making workflow.

The following sections provide more details on commitment deal terms for pacing.

Commitment pacing

When a commitment deal is being created, both parties need to agree on pacing terms to allow expansion or cancellation of the deal when it starts underperforming.

Here's what you need to know about pacing terms:

• You must have a media spend goal to pace toward.
• Cancellation and expansion are both set up by declaring terms that specify a pacing threshold and period.
• You should set your cancellation threshold to be lower than the expansion threshold.
• You can add conditional inventory access in the expansion terms.
• When the deal underpaces below the expansion terms, the buying party can activate deal expansion.
• After deal expansion is available, the option to activate it remains available to the buying party until the end of the deal.
• Once deal expansion is active, it cannot be undone.
• You can update the expansion terms during the middle of a deal by revising the deal.

IMPORTANT: Deal expansion requires cooperation from both parties: the selling party must have it configured within the deal, and the buying party must decide when to activate it.

The following table outlines how you can set pacing thresholds in a commitment deal.

Commitment financial terms

A commitment deal is an agreement in the platform that specifies a target cost for media investment and a timeframe for its delivery. The Trade Desk platform provides tools to help ensure that the designated investment amount is fulfilled between you and the buying party.

The following table lists all required financial terms for a commitment deal.

IMPORTANT: You must provide a non-zero value when choosing the floor price, media spend, or minimum goals.

The following example dealCreate mutation shows the structure of the financial terms for a commitment deal. For details, see CommitmentFinancialTerms object.

mutation {
  dealCreate(
    input: {
      # DEAL NAME AND PARTICIPANT DETAILS GO HERE!
      terms: {
        commitmentTerms: {
          financialTerms: {
            currencyCode: "USD"
            mediaSpendGoal: 100
            minDailyAvails: 10000
            floorPrice: 1.5
            minWinRate: 0.25
            auctionType: FIRST_PRICE_AUCTION
          }
        }
      }
    }
  )
}

TIP: To auto-fill financial terms at a 90% bid rate when creating non-decisioned deals, set the optional calculateNonDecisionedTerms field to true. This field applies only to fixed-price auction deals.

The following example dealCreate mutation shows shows how to create a commitment deal with system-calculated financial terms that autofill the minDailyAvails and minWinRate field.

mutation {
  dealCreate(
    input: {
      terms: {
        commitmentTerms: {
          financialTerms: {
            currencyCode: "USD"
            mediaSpendGoal: 100
            floorPrice: 1.5
            auctionType: FIXED_PRICE_AUCTION
            calculateNonDecisionedTerms: true
          }
        }
      }
    }
  )
}

To view the system-chosen values, query for the commitment financial terms. For details, see Retrieve commitment deal terms.

Commitment cancellation terms

When configuring the cancellation terms for a commitment deal, you must specify these parameters based on the following table.

NOTE: The cancellation period starts as soon as the deal crosses the cancellation threshold, independent of expansion.

Recommended expansion terms

Expansion is an optional, but recommended term to help underperforming commitment deals deliver in full. Expansion provides buying parties with access to additional pre-approved inventory. To enable deal expansion, you must configure expansion terms during deal creation, define broader targeting criteria, and set adjusted floor prices for the additional inventory.

When configuring expansion of a commitment deal, specify the following parameters. For details, see ExpansionTerms object.

Commitment terms for pacing

The following example dealCreate mutation shows how to set up both expansion and expanded inventory terms. This example creates a commitment deal with automatic expansion after three days below 85% pacing, reducing the floor price from $15.00 to $10.00 and expanding network targeting to include previously blocked networks. In practice, the threshold for cancellation should be lower than expansion. This ensures the deal has time to recover before moving onto cancellation.

NOTE: The following example omits many other required terms. For a complete example, see Complete deal creation mutation example.

mutation {
   dealCreate(
    input: {
      # OTHER DEAL TERMS GO HERE
      terms: {
        commitmentTerms: {
          expansionTerms: {
            period: 7
            threshold: 0.85
            floorPrice: 10.00
          }
          cancellationTerms: {
            period: 7
            threshold: 0.70
          }
          financialTerms: {
            minDailyAvails: 10000
            floorPrice: 15.00
          }
        }
      }
    }
  ) {
    errors {
      ... on MutationError {
        __typename
        message
        field
      }
    }
  }
}

To create a commitment deal, you must complete the steps in Initiate and negotiate deals.

Complete commitment deal creation example

To create a deal, use the dealCreate mutation to send a request to the buying party. Here's the information you need to create a deal:

• The known agent IDs (KAIDs) of all deal participants.
• The deal type (commitment or endeavor).
• For deals that originate from outside The Trade Desk, their external deal IDs.
• The financial terms and inventory composition of the deal.
• Optional cancellation terms with the thresholds the deal must meet.
• Optional expansion terms to provide access to more inventory when underpacing.

For a complete list of additional properties and descriptions, see Deal objects.

The following example dealCreate mutation shows shows how to create a commitment deal in a single request.

mutation DealCreate {
  dealCreate(
    input: {
      accountId: "ACCOUNT_ID_PLACEHOLDER"
      displayName: "DEAL_UI_PLACEHOLDER"
      name: "DEAL_NAME_PLACEHOLDER"
      sellingParty: {
        id: "SELLING_PARTY_KNOWN_AGENT_ID_PLACEHOLDER"
        contact: {
          name: "Alex Smith"
          email: "alexsmith@example.com"
        }
      }
      buyingParty: {
        id: "BUYING_PARTY_KNOWN_AGENT_ID_PLACEHOLDER"
        contact: {
          name: "John Smith"
          email: "johnsmith@example.com"
        }
      }
      buyingPermissions: {
        advertisers: {
          aadv: ["ALLOWED_ADVERTISER_KAID_PLACEHOLDER_1", "ALLOWED_ADVERTISER_KAID_PLACEHOLDER_2"]
          badv: ["BLOCKED_ADVERTISER_KAID_PLACEHOLDER_1", "BLOCKED_ADVERTISER_KAID_PLACEHOLDER_2"]
        }
        categories: {
          acat: ["IAB9-25", "IAB9-26"]
          bcat: ["IAB9-5", "IAB9-30"]
        }
      }
      terms: {
        commitmentTerms: {
          contributingDeals: {
            id: "CONTRIBUTING_DEAL_ID_PLACEHOLDER", 
            ownerId: "DEAL_OWNER_KNOWN_AGENT_ID_PLACEHOLDER" }
          cancellationTerms: { threshold: 0.5, period: 3 }
          financialTerms: {
            currencyCode: "USD"
            mediaSpendGoal: 100
            minDailyAvails: 10000
            floorPrice: 1.5
            minWinRate: 0.25
            auctionType: FIRST_PRICE_AUCTION
          }
          expansionTerms: { threshold: 0.5, floorPrice: 1.0, period: 5 }
          flight: { endAt: "2025-11-20T04:59:00.000Z", startAt: "2025-11-05T16:49:30.370Z", timeZone: "UTC" }
          inventoryComposition: {
            biddingTerms: ["IMP_EXT_GPID", "SOURCE_TID", "USER_ID", "AUDIO_PODID", "VIDEO_PODID"]
            systemLanguages: {
              base: {
                excluded: ["12"]
                included: ["11"]
              }
            }
            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"]
                }
              }
            }
            customAttributes:{
              base: {
                excludedValues: ["abcd123"]
                includedValues: ["xyz456"]
                key: "key1"
                section: IMPRESSION
              }
              expansion: {
                excludedValues: ["abcd123"]
                includedValues: ["xyz456"]
                key: "key2"
                section: SITE
              }
            }
            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"]
                }
                expansion: {
                  included: ["6"]
                }
              }
            }
            # These values are geo segment IDs.
            consumerGeos: {
              base: {
                excluded: ["q5xb319t45"]
                included: ["8t9awngqi4"]
              }
              expansion: {
                included: ["q5xb319t45"]
              }
            }
            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"]
              }
            }
            inventoryChannelComposition: {
              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"]
                  }
                }              
              }
            }
          }
        }
      }
    createdBy: {
      name: "John Smith"
      email: "johnsmith@example.com"
    }
  } ) {
    data {
      id
      dealStatus
      isPausedBySellingParty
      externallyManaged
      dealType
    }
    errors {
      __typename
      ... on MutationError {
        message
        field
      }
    }
  }
}

TIP: To return errors in a mutation response, include an errors field at the end of your mutation and pass the MutationError object. For details, see Mutation errors in our GraphQL API Resource Hub.

FAQs

The following are commonly asked questions about commitment deal creation.

Which terms are included in deal expansion?

All terms that support the Selection object are expandable. Common expansion strategies may include broader content categories, additional geographic markets, or relaxed device targeting. For a comprehensive list of values, see the description of the corresponding field in the Inventory Selection object.

The following example dealCreate mutation shows shows how to add expansion terms in the expansion object to grant access to inventory that was previously blocked.

mutation {
   dealCreate(
    input: {
      id: "DEAL_ID_PLACEHOLDER"
      terms: {
        # OTHER ADDITIONAL TERMS
        commitmentTerms: {
          inventoryComposition: {
            networks: {
              base: {
                excluded: [
                  name: "BLOCKED_NETWORK_NAME_PLACEHOLDER"
                ]
                included: [
                  name: "ALLOWED_NETWORK_NAME_PLACEHOLDER"
                ]
              }
              expansion: {
                included: "BLOCKED_NETWORK_NAME_PLACEHOLDER"
              }
            }
          }
        }
      }
    }
  ) {
    errors {
      ... on MutationError {
        __typename
        message
        field
      }
    }
  }
}

How is the minimum bid rate calculated?

The minimum bid rate is a calculated variable that shows how likely the buying party bids, it can also represent how reasonable a commitment deal is. This value is calculated by the following equation:

The spend goal times 1000 divided by the product of the minimum avails, flight duration, minimum win rate, and floor price.

NOTE: The calculation uses the exact time difference in milliseconds from the start date to the end date. This can result in decimal values for flight days.

Is there a limit to the bid rate?

The API returns an error and aborts deal creation when the calculated minimum bid rate exceeds 1, or 100%. To fix errors relating to the bid rate, you can decrease the media spend goal, or adjust your conditions by increasing the minimum daily avails, win rates, floor price, or flight duration.

IMPORTANT: To be eligible for targeting by a buying party in a non-decisioned ad group, a fixed-price commitment deal must have a minimum bid rate of at least 90%.