Deal Commitments

13 Minutes to read

Deal Commitments

13 Minutes to read

Article summary

Did you find this summary helpful?

Thank you for your feedback!

The dealcommitments endpoint, also known as Commitment Manager, can be used to track Inventory Cost across Deal IDs to bundle for a specific flight. Track Programmatic Guaranteed (PG) Deals and Private Deal IDs targeted by campaigns. A spend commitment is a negotiated commitment made with a publisher to reach a specific inventory cost.

Track Inventory cost spend with the dealcommitments endpoint in order to:

Simplify the process of consolidating and managing spend commitments.
Analyze spend, pacing and performance across all deals.
Track and manage deals efficiently to meet spend targets and maintain publisher relationships.

Endpoint

/traffic/dealcommitments

The following HTTP methods can be used:

Use the GET method to view an existing deal commitment.
Use the GET search method to retrieve multiple deal commitments.
Use the POST method to create a new deal commitment.
Use the PUT method to update an existing deal commitment.
Use the DELETE method to delete an existing deal commitment.

Required and Supported Fields

Deal Commitment

The dealcommitments object contains the following fields.

Parameter	Definition	Data Type	Create	Update
`id`	The ID of the deal commitment.	`integer`	N/A	Required
`name`	The name of the deal commitment.	`string`	Required	Required
`type`	The type of deal commitment: UPFRONT - media buying commitments where advertisers secure premium inventory ahead of time. These deals lock in pricing and availability, ensuring brands get priority access to high-value placements. While historically tied to linear TV, Upfronts have evolved to include digital video, streaming and even display inventory, depending on the publisher and deal structure. OTHER - any scattered buys that do not identify as an upfront.	`string`	Required	Required
`status`	The status of the deal commitment. `ACTIVE` `INACTIVE` The status can only be set to INACTIVE if the current date is outside of the deal commitment `startDate` and `endDate` for a create/update operation. If the current date is within the start and end date, the status can be set to ACTIVE or INACTIVE.	`string`	Required	Required
`publisherName`	The name of the publisher associated with the deal commitment.	`string`	Required	Required
`levelOfTracking`	The granularity of advertiser tracking set for the deal commitment. ALL - track the commitment with all advertisers. INCLUDE - enter specific advertisers to track the commitment with. EXCLUDE - enter specific advertisers to not track the commitment with. The commitment will be tracked under all other advertisers except for the ones entered.	`string`	Required	Required
`startDate`	The start date for the deal commitment. Date must be in ISO format. For example, 2025-01-01T00:00:00.00Z. Note The start date cannot be after the end date. The start date can be in the past, but it is limited at most to 2 years for historical data.	`string`	Required	Required
`endDate`	The end date for the deal commitment. Date must be in the ISO format. For example, 2025-12-31T00:00:00.00Z. Note: The end date can be both in the past and future, but it cannot be set before the start date.	`string`	Required	Required
`currency`	Specifies the currency. This value can only be set creating a deal commitment and must be a valid currency string. To learn more, refer to Currency Types. Some example values: USD, CAD.	`string`	Required	N/A
`totalInventoryCost`	The total inventory cost for the deal commitment. The total inventory cost is the total amount of money to be paid to publishers for media or inventory and must be a positive decimal value, such as 1000.0.	`number`	Required	Required
`createdByUser`	A response-only field that displays the full name of the user who created the deal commitment.	`string`	N/A	N/A
`updatedByUser`	A response-only field that displays the full name of the user who last updated the deal commitment.	`string`	N/A	N/A
`createdAt`	A response-only field that displays the date the deal commitment was created. The date is in ISO format. For example, 2025-12-31T00:00:00.00Z.	`string`	N/A	N/A
`updatedAt`	A response-only field that displays the date the deal commitment was last updated. The date is in ISO format, such as 2025-12-31T00:00:00.00Z.	`string`	N/A	N/A
`seatId`	The seat that the deal commitment is associated with. Note: The seat ID can only be set during creation and cannot be updated.	`integer`	Required	N/A
`dealIds`	The list of IDs for deals that will be associated with the deal commitment. The list cannot be empty and must contain valid, non-deleted deals. Only PRIVATE and/or PGD deal types are allowed.	`array`	Required	Required
`accountIds`	The list of accounts IDs that are included or excluded for the `levelOfTracking` set for the deal commitment. Important If the level of tracking is set to ALL, the list of account IDs should be empty or null. If the level of tracking is set to INCLUDE or EXCLUDE, then the list of account IDs is required and should have at least one valid account ID.	`array`	Required if `levelOfTracking` is set to INCLUDE or EXCLUDE	Required if `levelOfTracking` is set to INCLUDE or EXCLUDE
`pacing`	A response-only field that indicates how the inventory cost is pacing against the commitment timeline, assuming even spend across the period. Shown as a positive decimal percentage. Note: This field is only returned for retrieve/search (GET) calls.	`number`	N/A	N/A
`commitmentHealth`	A response-only field that displays the health of the deal commitment. ON_TRACK - pacing is 95% or higher. Commitments that have not started will have a default health set to ON_TRACK. AT_RISK - pacing is below 95%. Note: This field is only returned for retrieve/search (GET) calls.	`string`	N/A	N/A
`dealPerformanceDataMap`	A response-only field that contains performance information for the deals associated with the commitment. This field is returned as a key-value map, where the keys are the deal IDs and the values are outlined in the dealPerformanceDataMap object. Note: This field is only returned for retrieve/search (GET) calls.	`map`	N/A	N/A
`accountDataMap`	A response-only field that contains information about the accountIds associated with the deal commitment. Returned as a key-value map, where the keys are the account IDs and the values are the names of the advertisers with the associated ID. Note: This field is only returned for retrieve/search (GET) calls.	`map`	N/A	N/A

Deal Performance Data Map

The dealPerformanceDataMap object contains metrics associated with the deal. This is a response-only returned object that is only returned for retrieve/search (GET) calls.

Parameter	Definition	Data Type	Create	Update
`name`	The name of the deal.	`string`	N/A	N/A
`exchangeId`	The ID of the exchange.	`integer`	N/A	N/A
`exchangeDealId`	The deal ID for the exchange.	`string`	N/A	N/A
`bidRequests`	The number of bid requests.	`string`	N/A	N/A
`floorCpm`	The floor CPM.	`string`	N/A	N/A
`dealType`	The deal type. `PGD` `PRIVATE`	`string`	N/A	N/A

Read a Deal Commitment

Get data about a specific deal commitment, identified by its ID.

GET traffic/dealcommitments/{id}

Parameters

Parameter	Parameter Type	Definition	Data Type	Required
`id`	path	The ID of the deal commitment.	`integer`	Y

Sample Request URL

GET /traffic/dealcommitments/113

Sample Response

{
    "response": {
        "id": 113,
        "name": "Deal Commitment Traffic API",
        "type": "OTHER",
        "status": "INACTIVE",
        "publisherName": "AdsWizz",
        "levelOfTracking": "EXCLUDE",
        "dealIds": [
            15381,
            14087
        ],
        "startDate": "2025-01-10T00:00:00Z",
        "endDate": "2026-01-01T00:00:00Z",
        "totalInventoryCost": 15000.0,
        "createdByUser": "John Smith",
        "updatedByUser": "John Smith",
        "createdAt": "2025-02-27T08:58:28Z",
        "updatedAt": "2025-02-27T09:30:29Z",
        "seatId": 19,
        "pacing": 0.0,
        "commitmentHealth": "ON_TRACK",
        "dealPerformanceDataMap": {
            "15381": {
                "name": "Deal Name 1",
                "exchangeId": 4,
                "exchangeDealId": "Exchange Deal ID 1",
                "bidRequests": "4586",
                "floorCpm": "119",
                "dealType": "PGD"
            },
            "14087": {
                "name": "Deal Name 2",
                "exchangeId": 3,
                "exchangeDealId": "Exchange Deal ID 2",
                "bidRequests": "854",
                "floorCpm": "48",
                "dealType": "PRIVATE"
            }
        },
        "accountIds": [
            2211960,
            2900086
        ],
        "accountDataMap": {
            "2211960": "Dark Knight",
            "2900086": "Omniscope"
        },
        "currency": "EUR"
    },
    "errors": null,
    "timeStamp": "2025-02-27T11:27:00.958Z"
}

Search for a list of Deal Commitments

Search for multiple seat deal commitments.

GET traffic/dealcommitments/search?commitmentsSeatId={}&page={}&limit={}&dir={}&sort={}

Parameters

Parameter	Parameter Type	Definition	Data Type	Required
`commitmentSeatId`	query	The deal commitment seat ID. This must match the current user seat, for security reasons.	`integer`	Y
`page`	query	Specifies the page number. To apply pagination, both the page and the limit are required at the same time.	`integer`	N
`limit`	query	Specifies the limit to the number of deal commitments that can be returned. To apply pagination, both the page and the limit are required at the same time.	`integer`	N
`dir`	query	Specifies the sort direction. ASC: data is sorted in ascending order. DESC: data is sorted in descending order. If the sort field is passed in and the dir is omitted, the direction will default to ASC.	`string`	N
`sort`	query	Specifies the column to sort by. Allowed values are (case insensitive): COMMITMENT_ID, COMMITMENT_NAME, TYPE, STATUS, PUBLISHER_NAME, START_DATE, END_DATE, COMMITMENT_HEALTH, PACING, CURRENCY, TOTAL_INVENTORY_COST, CREATED_BY_USER, UPDATED_AT	`string`	N

Sample Request URL

GET traffic/dealcommitments/search?commitmentsSeatId=19&page=2&limit=2&dir=asc&sort=START_DATE

Sample Response

{
    "response": [
        {
            "id": 94,
            "name": "Deal Commitment 1",
            "type": "UPFRONT",
            "status": "ACTIVE",
            "publisherName": "AdX",
            "levelOfTracking": "INCLUDE",
            "dealIds": [
                6339,
                6396
            ],
            "startDate": "2023-05-21T00:00:00Z",
            "endDate": "2026-05-21T00:00:00Z",
            "totalInventoryCost": 5000.0,
            "createdByUser": "John Smith",
            "updatedByUser": "John Smith",
            "createdAt": "2025-01-20T10:06:44Z",
            "updatedAt": "2025-01-20T10:21:50Z",
            "seatId": 19,
            "pacing": 0.0,
            "commitmentHealth": "AT_RISK",
            "dealPerformanceDataMap": {
                "6339": {
                    "name": "Deal Name 1",
                    "exchangeId": 5,
                    "exchangeDealId": "Exchange Deal ID 1",
                    "bidRequests": "3204",
                    "floorCpm": "28",
                    "dealType": "PGD"
                },
                "6396": {
                    "name": "Deal Name 2",
                    "exchangeId": 2,
                    "exchangeDealId": "Exchange Deal ID 2",
                    "bidRequests": "8356",
                    "floorCpm": "119",
                    "dealType": "PRIVATE"
                }
            },
            "accountIds": [
                3230292
            ],
            "accountDataMap": {
                "3230292": "Test Advertiser"
            },
            "currency": "USD"
        },
        {
            "id": 96,
            "name": "Deal Commitment 2",
            "type": "UPFRONT",
            "status": "ACTIVE",
            "publisherName": "AdX",
            "levelOfTracking": "INCLUDE",
            "dealIds": [
                6339,
                6396
            ],
            "startDate": "2023-05-22T00:00:00Z",
            "endDate": "2026-05-21T00:00:00Z",
            "totalInventoryCost": 5000.0,
            "createdByUser": "John Smith",
            "updatedByUser": "John Smith",
            "createdAt": "2025-01-20T11:26:42Z",
            "updatedAt": "2025-01-20T11:39:11Z",
            "seatId": 19,
            "pacing": 0.0,
            "commitmentHealth": "AT_RISK",
            "dealPerformanceDataMap": {
                "6339": {
                    "name": "Deal Name 1",
                    "exchangeId": 7,
                    "exchangeDealId": "Exchange Deal ID 1",
                    "bidRequests": "6200",
                    "floorCpm": "37",
                    "dealType": "PGD"
                },
                "6396": {
                    "name": "Deal Name 2",
                    "exchangeId": 3,
                    "exchangeDealId": "Exchange Deal ID 2",
                    "bidRequests": "5284",
                    "floorCpm": "111",
                    "dealType": "PRIVATE"
                }
            },
            "accountIds": [
                3230292
            ],
            "accountDataMap": {
                "3230292": "Test Advertiser"
            },
            "currency": "USD"
        }
    ],
    "errors": null,
    "timeStamp": "2025-02-27T11:38:34.663Z"
}

Create a New Deal Commitment

Create a deal commitment.

POST traffic/dealcommitments

Parameters

All fields are specified in the request body.

Sample Request URL

POST /traffic/dealcommitments

Sample Request Body

The following request creates a new deal commitment, with included advertiser and 2 associated deals.

{
  "name": "Deal Commitment Traffic API Create",
  "type": "UPFRONT",
  "status": "ACTIVE",
  "publisherName": "AdX",
  "levelOfTracking": "INCLUDE",
  "dealIds": [6339, 6396],
  "startDate": "2025-01-01T00:00:00.00Z",
  "endDate": "2025-12-31T00:00:00.00Z",
  "currency": "USD",
  "totalInventoryCost": 5000.0,
  "seatId": 19,
  "accountIds": [3230292]
}

Sample Response

{
    "response": {
        "id": 120,
        "name": "Deal Commitment Traffic API Create",
        "type": "UPFRONT",
        "status": "ACTIVE",
        "publisherName": "AdX",
        "levelOfTracking": "INCLUDE",
        "dealIds": [
            6339,
            6396
        ],
        "startDate": "2025-01-01T00:00:00Z",
        "endDate": "2025-12-31T00:00:00Z",
        "totalInventoryCost": 5000.0,
        "createdByUser": "John Smith",
        "updatedByUser": "John Smith",
        "createdAt": "2025-02-27T08:58:28Z",
        "updatedAt": "2025-02-27T08:58:29Z",
        "seatId": 19,
        "accountIds": [
            3230292
        ],
        "accountDataMap": {
            "3230292": "Alex Cornetto Test Advertiser"
        },
        "currency": "USD"
    },
    "errors": null,
    "timeStamp": "2025-02-27T08:58:29.325Z"
}

Update an existing Deal Commitment

Update an existing deal commitment.

PUT traffic/dealcommitments/{id}

Parameters

Parameter	Parameter Type	Definition	Data Type	Required
`id`	path	The ID of the deal commitment.	`integer`	Y

Sample Request URL

PUT /traffic/dealcommitments/120

Sample Request Body

The following request updates all editable fields for a deal commitment.

{
  "name": "Deal Commitment Traffic API Update",
  "type": "OTHER",
  "status": "INACTIVE",
  "publisherName": "AdsWizz",
  "levelOfTracking": "EXCLUDE",
  "dealIds": [15381, 14087],
  "startDate": "2025-01-10T00:00:00.00Z",
  "endDate": "2026-01-01T00:00:00.00Z",
  "totalInventoryCost": 15000.0,
  "accountIds": [2900086, 2211960]
}

Sample Response

{
    "response": {
        "id": 222,
        "name": "Deal Commitment Traffic API Update",
        "type": "OTHER",
        "status": "INACTIVE",
        "publisherName": "AdsWizz",
        "levelOfTracking": "EXCLUDE",
        "startDate": "2025-01-10T00:00:00Z",
        "endDate": "2026-01-01T00:00:00Z",
        "totalInventoryCost": 15000.0,
        "createdByUser": "John Smith",
        "updatedByUser": "John Smith",
        "createdAt": "2025-04-09T07:17:21Z",
        "updatedAt": "2025-04-09T07:18:21Z",
        "seatId": 19,
        "dealIds": [
            15381,
            14087
        ],
        "accountIds": [
            2211960,
            2900086
        ],
        "accountDataMap": {
            "2211960": "Dark Knight",
            "2900086": "Omniscope IP"
        },
        "currency": "USD"
    },
    "errors": null,
    "timeStamp": "2025-04-09T07:18:23.885Z"
}

Delete one or more deal commitments

Delete one or more deal commitments that belong to a given seat.

Important
In order to delete a commitment, ensure that the commitment ID associated with the commitment has the following constraints.
Belongs to the current user seat.
Needs to be valid commitmentIds.

If all the IDs are in a valid format and exist in the database, but some do not belong to the current user's seat, only those for which the user has access will be deleted.

DELETE traffic/dealcommitments?commitmentIds={}

Parameters

Parameter	Parameter Type	Definition	Data Type	Required
`commitmentIds`	query	A comma separated list of deal commitment IDs to be deleted. The commitments must belong to the current user seat.	`string`	Y

Parameter

Parameter Type

Definition

Data Type

Required

commitmentIds

query

A comma separated list of deal commitment IDs to be deleted.

The commitments must belong to the current user seat.

string

Sample Request URL

DELETE traffic/dealcommitments?commitmentIds=116,117

Sample Response

{
    "response": "All valid entities matching the current user seat have been deleted",
    "errors": null,
    "timeStamp": "2025-02-27T09:43:46.703Z"
}

Was this article helpful?

What's Next

Digital Out Of Home

Contents

Endpoint
Required and Supported Fields
Read a Deal Commitment
Search for a list of Deal Commitments
Create a New Deal Commitment
Update an existing Deal Commitment
Delete one or more deal commitments