Deal objects

This reference provides all the necessary information to create a deal and defines all elements of the deal. It defines the buying and selling parties, additional parties that can bid on the inventory, and through the terms object specifies the inventory and financial considerations associated with it. For definitions, deal types, and other conceptual details, see Deals.

Here's what you need to know about the deal objects reference:

Use this section to idenity fields you can send in a deal proposal to the buying party.
The proposal must detail who is the buying party, selling party, and relevant contacts using a known agent ID (KAID). For details, see Known Agent object.
You can include these objects in the dealCreate and dealRevise mutations. For details, see Initiate and negotiate deals.
Some fields are for queries and don't apply to mutations. These have a read-only label. For details, see Deal query examples.

Deal I/O objects

Deal I/O objects enable a seller or intermediary to manage a deal on The Trade Desk platform by specifying key parameters such as the involved parties, deal type, included inventory, and financial terms. The following table lists object fields supported in queries and mutations. Fields used only in queries have a Read-only value in the Required? column.

Field	Required?	Data Type	Description
`id`	Optional with exceptions.	String	The unique deal ID used to identify the deal. Here's what you need to know: The ID must be unique within the same seller. Always include this field when making deal revisions. For deals originating from intermediaries, you must send this ID on avails. Omitting this ID indicates The Trade Desk manages the deal. IMPORTANT: Deals created outside of The Trade Desk must provide an ID at creation time.
`accountId`	Required	String	The account ID of the selling party that creates the deal.
`ownerId`	Optional	String	The KAID of the associated owner of the deal.
`name`	Required	String(256)	The shared name of the deal displayed in reporting. NOTE: This name is shared with the buying party when searching or reviewing deals.
`displayName`	Optional	String(256)	The name of the deal displayed in the UI. NOTE: Only you, as the selling party, can see this name. Choose a unique name to distinguish it from your other deals.
`categoryTaxonomy`	Optional	String enum	The IAB Category Taxonomy version to use. NOTE: If the field is empty, this value defaults to `IAB_TECH_LAB_CONTENT_TAXONOMY_1_0`. For details, see Category taxonomy values.
`sellingParty`	Required	Object	The KAID and contact information of the selling party. For field details, see SellingParty object.
`buyingParty`	Required	Object	The KAID and contact information of the buying party. For field details, see BuyingParty object.
`buyingPermissions`	Optional	Object	The permissions for additional deal participants, including advertisers, agencies, and advertiser categories. For details, see Buying permissions objects.
`terms`	Required	Object	The terms define the execution modality and inventory included in the deal. It must be one, and only one of the following objects: CommitmentTerms object or EndeavorTerms object. The object selected determines the type of execution of the deal, and terms for financial, composition, and bidding for the deal.
`upfronts`	Optional	Object	An upfront ID, if applicable. An upfront ID enables both parties to track their upfront spending. For details, see Upfront object
`createdBy`	Required for the `dealCreate` mutation.	Object	The user who creates the deal on the seller's platform and pushes it through to the DSP. NOTE: This is explicitly declared since multiple users can share API keys between each other. For field details, see InventoryContact object.
`updatedBy`	Required for the `dealRevise` mutation.	Object	The user who revises the deal on the seller's platform and pushes it through to the DSP. NOTE: This is explicitly declared since multiple users can share API keys between each other. For field details, see InventoryContact object.
`dealNegotiationStatus`	Read-only	String enum	The status of the deal during negotiation. Every new revision has a pending status. For details, see Deal negotiation status values.
`dealStatus`	Read-only	String enum	The status of the current accepted deal. For details, see Deal status values.

SellingParty object

The SellingParty object represents the selling party which can be an intermediary, seller, or publisher on The Trade Desk. The following table lists the SellingParty object fields.

Field	Required?	Data Type	Description
`id`	Required	String	The KAID of the selling party. NOTE: You cannot revise this field.
`contact`	Required	Object	The primary contact of the selling party who accepts the deal with the buying party, and who to attribute the spend to. For details, see InventoryContact object.

BuyingParty object

The BuyingParty object represents an agency or advertiser on The Trade Desk. The following table lists the BuyingParty object fields.

Field	Required?	Data Type	Description
`id`	Required for the `dealCreate` mutation.	String	The KAID of the buying party.
`contact`	Optional	Object	The primary contact of the buying party who agrees to the deal with the selling party. For details, see InventoryContact object.

InventoryContact object

When creating a deal, both the buying and selling parties must provide their contact information, including the name and email of a primary contact. The following table lists the InventoryContact object fields. These fields are optional for deal revision.

Field	Required?	Data Type	Description
`name`	Required	String(128)	The contact's full name.
`email`	Required	String(256)	The contact's email address.

BuyingPermissions object

The BuyingPermissions object provides information on agencies and advertisers allowed to bid on the associated deals. The selling party can adjust permissions in the CategoryPermission and AdvertiserPermission object using a category ID and known agent ID (KAID).

Field	Required?	Data Type	Description
`wseat`	Optional	String array	A list of KAIDs that represent authorized seats that can buy the deal.
`categories`	Optional	Object	A list of included and excluded advertiser categories for the deal. If null, all categories are allowed. For details, see CategoryPermission object.
`advertisers`	Optional	Object	A list of KAIDs that represent included and excluded advertisers for the deal. If null, all advertisers are allowed. For details, see AdvertiserPermission object.

CategoryPermission object

The CategoryPermission object provides information on whether certain advertiser categories bid on inventory. Each category follows the IAB version provided in the categoryTaxonomy field.

IMPORTANT: Only one acat or bcat field can be provided.

Field	Required?	Data Type	Description
`acat`	Optional	String array	The list of advertiser categories that can bid on this deal. If there are no values in the `acat` field, all categories are allowed.
`bcat`	Optional	String array	The list of advertiser categories that aren't allowed to bid on this deal. If there are no values in the `bcat` field, no categories are blocked.

AdvertiserPermission object

The AdvertiserPermission object lists advertiser KAIDs allowed or blocked from bidding on the associated deals.

Field	Required?	Data Type	Description
`aadv`	Optional	String array	The list of KAIDs of advertisers that can bid on this deal. If there are no values in the `aadv` field, all advertisers are allowed.
`badv`	Optional	String array	The list of KAIDs of advertisers that cannot bid on this deal. If there are no values in the `badv` field, no advertisers are blocked.

Upfront object

Upfronts are larger agreements between publishers and advertisers, typically delivered through multiple deals. The Upfront object identifies the deal as part of an upfront, and The Trade Desk utilizes it to help both parties track their spend.

IMPORTANT: Don't include both fields.

Field	Required?	Data Type	Description
`name`	Optional	String(256)	The name of an upfront this deal is part of.
`id`	Optional	String	The ID of an upfront this deal is part of.

Deal enumeration values

The following section contains all deal-related enumeration values sorted by alphabetical order.

Category taxonomy values

The following table lists the accepted category taxonomy values for the categoryTaxonomy field. The categoryTaxonomy field defaults to the IAB_TECH_LAB_CONTENT_TAXONOMY_1_0 value. For taxonomy listings, see IAB content taxonomy mapping: Version 1.0 to 2.2.

TIP: The Trade Desk strongly recommends using the IAB Tech Lab Content Taxonomy 2.2 value.

Enum Value	Description
`IAB_TECH_LAB_CONTENT_TAXONOMY_1_0`	The IAB Content Taxonomy version 1.0.
`IAB_TECH_LAB_CONTENT_TAXONOMY_2_2`	The IAB Content Taxonomy version 2.2.

Deal negotiation status values

The following table lists the supported status values for the dealNegotiationStatus field in alphabetical order. The values reflect the buying party's decision. For details, see Deal phases and statuses.

Enum Value	Description
`ACCEPTED`	Both parties accepted the proposal.
`PROPOSED`	The selling party proposed a deal and is waiting for a response from the buying party.
`REJECTED`	The buying party rejected the current revision of the deal. Previously accepted deal revisions, if there are any, are still live.

Deal status values

The following table lists the supported status values for the dealStatus field in alphabetical order. A deal can only have a single status at a time. For details, see Deal phases and statuses.

Enum Value	Description
`CANCELED`	The deal is canceled by either party before flight completion.
`COMPLETED`	The accepted deal has reached the end of the flight date.
`EXPIRED`	The deal was never accepted and the flight ended.
`LIVE`	The deal has been accepted, is being targeted, and is live in flight.
`LIVE_NOT_SPENDING`	The deal has been accepted by the buying party, but hasn't been targeted in any campaigns.
`NOT_STARTED`	The deal has been accepted by the buying party, but flight dates haven't been reached.
`PAUSED`	The deal has been paused by the selling party.
`PENDING_ACCEPTANCE`	The deal has been proposed by a selling party and is waiting for a response from the buying party.