---
title: "Deal Commitments"
slug: "deal-commitments"
updated: 2025-04-09T13:18:28Z
published: 2025-04-09T13:18:28Z
canonical: "help.yahooinc.com/deal-commitments"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.yahooinc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deal Commitments

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

```plaintext
/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](https://help.yahooinc.com/dsp-api/docs/data-dictionary#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](/dsp-api/docs/deal-commitments#deal-performance-data-map) 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.

```plaintext
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

```plaintext
GET /traffic/dealcommitments/113
```

### Sample Response

```json
{
    "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.

```plaintext
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

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

### Sample Response

```json
{
    "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.

```plaintext
POST traffic/dealcommitments
```

### Parameters

All fields are specified in the request body.

### Sample Request URL

```plaintext
POST /traffic/dealcommitments
```

### Sample Request Body

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

```json
{
  "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

```json
{
    "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.

```plaintext
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

```plaintext
PUT /traffic/dealcommitments/120
```

### Sample Request Body

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

```json
{
  "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

```json
{
    "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.

> [!WARNING]
> 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.

```plaintext
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 |

### Sample Request URL

```plaintext
DELETE traffic/dealcommitments?commitmentIds=116,117
```

### Sample Response

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