Group deals with upfronts

An upfront is an object that serves as a grouping mechanism—defined by an ID and a descriptive name—that you, as the selling party, can use to organize multiple deals under a shared label for consolidated reporting and performance analysis. Upfronts help you aggregate spend, track performance, and analyze transacted inventory.

IMPORTANT: You cannot assign upfronts to deals without media spend goals.

Benefits of upfronts

The following table lists the benefits of assigning upfronts to deals.

Benefits	Description
Retroactive reporting	When a deal has an upfront, all historical spend for that deal's past and present duration is retroactively attributed to the upfront for reporting purposes.
Flexible assignment	During deal creation or deal revision, you can assign one upfront to a deal. Sellers and intermediaries can assign an upfront to deals they have created.
Reporting dimension	Upfronts appear as a reporting dimension, enabling you to aggregate deal performance by grouping upfronts with the name or ID.
Simple structure	Upfronts require only the known agent ID of the seller or intermediary that's creating the upfront, and a descriptive name.

Upfront management

The following table lists tasks you can perform when managing your upfronts.

Task	Description
Create an upfront.	Create an upfront to organize your deal reports.
Assign an upfront to a deal.	Groups deals together using an upfront.
Rename an upfront.	Rename upfront groupings.
Delete an upfront.	Remove upfront from all deals.
List all upfronts for a selling party.	Retrieve all upfronts created by an account.

Create an upfront

To create an upfront, use the upfrontCreate mutation. The following example creates an upfront named "Q4 2025 Premium Video Package," and requires your known agent ID.

IMPORTANT: Each upfront name has a maximum of 256 characters.

mutation {
    upfrontCreate(input: { 
      ownerId: "SELLING_PARTY_KAID_PLACEHOLDER",
      name: "Q4 2025 Premium Video Package" 
    }) {
      data {
        id,
        name,
        owner {
          ... on KnownAgent {
            id
            name
            type
          }
        }
      }
      errors {
        ... on MutationError {
          __typename
          message
          field
        }
      }
    }
}

TIP: After creating an upfront, keep track of the ID to make changes to other deals.

Assign an upfront to a deal

Choose the upfront by either the name or ID, then use the dealCreate mutation for a newly created deal, or use the dealRevise mutation for an existing deal.

mutation {
  dealCreate(
    input: {
      ...
      upfront: {name: "Q4 2025 Premium Video Package"}
      upfront: {id: "UPFRONT_ID_PLACEHOLDER"}
    }
  ) {
    errors {
      ... on MutationError {
        __typename
        message
        field
      }
    }
  }
}

Rename an upfront

To rename an update, use the upfrontUpdate mutation. The following example renames the upfront from "Q4 2025 Premium Video Package" to "Q4 2025 Open Internet Package." This name change retroactively applies to all previously assigned deals.

mutation {
  upfrontUpdate(
    input: {
      id: "UPFRONT_ID_PLACEHOLDER" 
      name: "Q4 2025 Open Internet Package" 
    }
  ) {
    errors {
      ... on MutationError {
        __typename
        message
        field
      }
    }
  }
}

Delete an upfront

To delete an upfront, use the upfrontDelete mutation. The following example deletes an upfront by passing the upfront ID.

NOTE: Deleting an upfront automatically dissociates it from all assigned deals.

mutation {
  upfrontDelete(
    input: {
      id: "UPFRONT_ID_PLACEHOLDER"
    }
  ) {
    errors {
      ... on MutationError {
        __typename
        message
        field
      }
    }
  }
}

List all upfronts for a selling party

The following example upfronts query shows how you can query for a list of all upfronts associated with a selling party known agent, such as an intermediary, publisher, or seller.

query GetSellingPartyUpfrontsExample {
  upfronts(input: {ownerId: "SELLING_PARTY_KAID_PLACEHOLDER"}) {
    nodes {
      id
      name
    }
  }
}

TIP: To view upfronts unassigned to deals, add the where filter for includeUnassociatedUpfronts: true.

The following example upfronts query shows all upfronts, including unassigned upfronts.

query GetAllSellingPartyUpfrontsExample{
  upfronts(
    input: {ownerId: "SELLING_PARTY_KAID_PLACEHOLDER"}
    where: {includeUnassociatedUpfronts: true}
  ) {
    nodes {
      id
      name
    }
  }
}