---
title: "Purchase Receipt Audiences"
slug: "purchase-receipt"
updated: 2026-03-24T16:49:58Z
published: 2026-03-24T16:49:58Z
canonical: "help.yahooinc.com/purchase-receipt"
---

> ## 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.

# Purchase Receipt Audiences

A purchase receipt audience enables you to target consumers based on sales receipts.

Advertisers can define the parameters of their audience based on purchase confirmation emails in Yahoo users’ inboxes for individual products, airline bookings, hotel reservations and more.

A purchase receipt is defined as an individual, anonymized email that a Yahoo mail user receives indicating that the user completed a purchase or payment.

## Endpoint

```plaintext
/traffic/audiences/mail_event
```

The action taken depends on the HTTP method and the parameters specified.

- Use the `GET `method to read an existing purchase receipt audience.
- Use the `POST` method to create a new purchase receipt audience.
- Use the `PUT` method to update an existing purchase receipt audience.

## Resources

### Purchase Receipt Object

The purchase receipt object contains the following fields:

| **Field** | **Description** | **Type** | **Create** | **Update** |
| --- | --- | --- | --- | --- |
| `id` | Specifies the audience ID. | `integer` | N/A | Required |
| `name` | Specifies the name of the audience. | `string` | Required | Optional |
| `status` | Specifies the current status of the audience. Allowed values: - `ACTIVE`: You can target the audience. - `INACTIVE`: You cannot target the audience. Defaults to `ACTIVE` if you don’t specify a value. | `string` | Optional | Optional |
| `eventType` | Specifies the purchase receipt audience type. Options include: - `FLIGHT` - Consumers who have booked an airline reservation. - `CAR` - Consumers who have booked a car rental. - `HOTEL` - Consumers who have booked a hotel booking or confirmation. - `MOVIE_TICKETS` - Consumers who have purchased a movie ticket. - `LIVE_EVENTS` - Consumers who have purchased a ticket to a live event, like a concert. - `INVOICES` - Consumers who have received statements or bills. - `PRODUCTS` - Consumers who have purchased a particular product. - `SOCIAL_EVENTS` - Consumers who have received emails and invitations from social-planning websites. - `STOCKS_AND_INVESTMENTS` - Consumers who have received trade confirmation emails from investment brokerages. | `string` | Required | Optional |
| `frequency` | Specifies the minimum number of receipts that must be in the consumer’s email for that consumer to be included in the audience. Options include: - `1` (Default Value) - `2` - `3` - `4` - `5` | `integer` | Optional | Optional |
| `accountId` | Specifies the advertiser ID. If specified, the purchase receipt audience is tied to a specific advertiser and can only be used in that advertiser’s campaigns. To learn more, refer to [Advertisers](/dsp-api/docs/advertisers). | `string` | Required | Optional |
| `createdAt` | A read-only field that specifies when the audience was created. | `string` | N/A | N/A |
| `textAttributes` | Specifies an array of Text Attribute objects. To learn more, refer to [Text Attributes Object](/dsp-api/docs/mail-event#text-attributes-object). | `array` | Optional | Optional |
| `timeAttributes` | Specifies an array of Time Attribute objects. To learn more, refer to [Time Attribute Object](/dsp-api/docs/mail-event#time-attribute-object). | `array` | Optional | Optional |
| `countryCodes` | Specifies an array of International Standards Organization ISO3, 3 letter alphabetic country codes representing the target country/region for the audience. Specify single or multiple country codes. Must be selected from the supported country list. | `string` | Required | N/A |

### Text Attributes Object

The `textAttributes` array contains one or more Text Attribute objects. The Text Attribute object contains the following fields:

| **Field** | **Description** | **Type** | **Create** | **Update** |
| --- | --- | --- | --- | --- |
| `key` | Specifies the attribute key. For a complete list, refer to [Supported Purchase Events](/dsp-api/docs/mail-event#supported-purchase-events). | `string` | Required | Required |
| `groupType` | Specifies the group type. Option include: - If `INCLUDE` is specified, the object specifies consumers to *include in* the audience. - If `EXCLUDE` is specified, the object specifies consumers to *exclude from* the audience. | `string` | Required | Required |
| `matchType` | Specifies the match type. Options include: - If `CONTAINS` is specified, the object specifies consumers to *include in* the audience. - If `EQUALS` is specified, the object specifies consumers to *exclude from* the audience. To learn more, refer to [Supported Purchase Events](/dsp-api/docs/mail-event#supported-purchase-events). Required if the value type of the attribute is `String`. | `string` | Required [[1]](https://developer.yahooinc.com/dsp/api/docs/traffic/audience/mail-event-audience.html#id2) | Required [[1]](https://developer.yahooinc.com/dsp/api/docs/traffic/audience/mail-event-audience.html#id2) |
| `operatorType` | Specifies the operator type. Options include: - If `EQUAL_TO` is specified, the object specifies consumers to *include in* the audience. - If `GREATER_THAN` is specified, the object specifies consumers to *exclude from* the audience. - If `LESS_THAN` is specified, the object specifies consumers to *exclude from* the audience. To learn more, refer to [Supported Purchase Events](/dsp-api/docs/mail-event#supported-purchase-events). Required if the value type of the attribute is `Numeric`. | `string` | Required [[2]](https://developer.yahooinc.com/dsp/api/docs/traffic/audience/mail-event-audience.html#id5) | Required [[2]](https://developer.yahooinc.com/dsp/api/docs/traffic/audience/mail-event-audience.html#id5) |
| `values` | Specifies an array of keywords. | `array` | Required | Required |
| `name` | Read-only field showing the event name. | `string` | N/A | N/A |

### Sample Payload

```plaintext
{
  "textAttributes": [
    {
      "key": "cpv",
      "groupType": "INCLUDE",
      "values": [
        "aa.com",
        "advantage.com"
      ]
    }
  ]
}
```

### Time Attribute Object

The `timeAttributes `array contains an array of Time Attribute objects. Time Attribute object are defined by the following fields:

| **Field** | **Description** | **Type** | **Create** | **Update** |
| --- | --- | --- | --- | --- |
| `key` | Specifies the attribute key. For a complete list, refer to [Supported Purchase Events](/dsp-api/docs/mail-event#supported-purchase-events). | `string` | Required | Required |
| `rangeType` | Specifies the method used to select ranage of the data collection. Options include: - If `DATE` is specified, exact dates are used. - If `DAY` is specified, the range is comprised of past or future days. | `string` | Required | Required |
| `fromDate` | Specifies the start of the date range. Required if the `rangeType` is `DATE`. Format: yyyymmdd | `string` | Required [[3]](https://developer.yahooinc.com/dsp/api/docs/traffic/audience/mail-event-audience.html#id8) | Required [[3]](https://developer.yahooinc.com/dsp/api/docs/traffic/audience/mail-event-audience.html#id8) |
| `toDate` | Specifies the end of the date range. Required if the `rangeType` is `DATE`. Format: yyyymmdd | `string` | Required [[4]](https://developer.yahooinc.com/dsp/api/docs/traffic/audience/mail-event-audience.html#id11) | Required [[4]](https://developer.yahooinc.com/dsp/api/docs/traffic/audience/mail-event-audience.html#id11) |
| `numDays` | Specifies the number of days into the past or future. Required if the `rangeType` is `DAY`. | `string` | Required [[5]](https://developer.yahooinc.com/dsp/api/docs/traffic/audience/mail-event-audience.html#id14) | Required [[5]](https://developer.yahooinc.com/dsp/api/docs/traffic/audience/mail-event-audience.html#id14) |
| `name` | Read-only field showing the event name. | `string` | N/A | N/A |

  

### Sample Payload

```plaintext
{
  "timeAttributes": [
    {
      "key": "cbkdt",
      "rangeType": "DATE",
      "fromDate": "20170703",
      "toDate": "20170903"
    },
    {
      "key": "cpickdt",
      "rangeType": "DAY",
      "numDays": "2"
    }
  ]
}
```

### Supported Purchase Events

- `string` data types can only be part of `textAttributes`
- `time `data types can only be included in `timeAttributes`.

| **Attribute** | **Event Key** | **Event Name** | **Data Type** | **Value Type** |
| --- | --- | --- | --- | --- |
| `FLIGHT` | `farcd` | airline | `string` | Search |
| `FLIGHT` | `fpv` | booking service | `string` | Search |
| `FLIGHT` | `fdeap` | travel from | `string` | Search |
| `FLIGHT` | `farap` | travel to | `string` | Search |
| `FLIGHT` | `fbkdt` | booking date | `time` | Timestamp |
| `FLIGHT` | `fdedt` | depart date | `time` | Timestamp |
| `FLIGHT` | `fardt` | arrival date | `time` | Timestamp |
| `CAR` | `cpv` | booked car with | `string` | Search |
| `CAR` | `ccity` | rental city | `string` | String |
| `CAR` | `ccountry` | rental country | `string` | Search |
| `CAR` | `cbkdt` | car booking date | `time` | Timestamp |
| `CAR` | `cpickdt` | pickup date | `time` | Timestamp |
| `HOTEL` | `hhname` | hotel name | `string` | String |
| `HOTEL` | `hpv` | booked hotel with | `string` | Search |
| `HOTEL` | `hbrand` | hotel brand | `string` | Search |
| `HOTEL` | `hcity` | hotel city | `string` | String |
| `HOTEL` | `hcountry` | hotel country | `string` | Search |
| `HOTEL` | `hdedt` | check in date | `time` | Timestamp |
| `HOTEL` | `hbkdt` | hotel booking date | `time` | Timestamp |
| `HOTEL` | `hnody` | length of stay | `string` | Numeric |
| `LIVE_EVENTS` | `lvevtname` | event name | `string` | String |
| `LIVE_EVENTS` | `lvevtvenue` | event venue | `string` | String |
| `LIVE_EVENTS` | `lvevtsender` | event email sender | `string` | Search |
| `LIVE_EVENTS` | `lvevtseason` | event season | `string` | Search |
| `LIVE_EVENTS` | `lvevtdate` | event date | `time` | Timestamp |
| `MOVIE_TICKETS` | `mvtixthtr` | movie theater name | `string` | String |
| `MOVIE_TICKETS` | `mvtixmvname` | movie title | `string` | String |
| `MOVIE_TICKETS` | `mvtixgenre` | movie genre | `string` | Search |
| `MOVIE_TICKETS` | `mvtixsender` | ticket vendor | `string` | Search |
| `MOVIE_TICKETS` | `mvtixrating` | movie rating | `string` | Search |
| `MOVIE_TICKETS` | `mvtixdate` | movie date | `time` | Timestamp |
| `INVOICES` | `iprovidername` | users making payment to | `string` | String |
| `INVOICES` | `ipaymentstatus` | payment status | `string` | Search |
| `INVOICES` | `ipaymentduedate` | payment due date | `time` | Timestamp |
| `PRODUCTS` | `itemname` | product name | `string` | String |
| `PRODUCTS` | `senderdomain` | bought from | `string` | Search |
| `PRODUCTS` | `topcategory` | category | `string` | Search |
| `PRODUCTS` | `subcategory` | subcategory | `string` | Search |
| `PRODUCTS` | `paymenttype` | payment method | `string` | Search |
| `PRODUCTS` | `orderdate` | purchase date | `time` | Timestamp |
| `PRODUCTS` | `itempriceusd` | product price | `string` | Numeric |
| `SOCIAL_EVENTS` | `setopcategory` | social events top category | `string` | Search |
| `SOCIAL_EVENTS` | `sesubcategory` | social events subcategory | `string` | Search |
| `SOCIAL_EVENTS` | `socevtdate` | social events date | `time` | Timestamp |
| `STOCKS_AND_INVESTMENTS` | `investment_bucket` | Average Monthly Trades | `string` | Search |
| `STOCKS_AND_INVESTMENTS` | `provider` | Provider | `string` | Search |
| `STOCKS_AND_INVESTMENTS` | `event_time` | Investment Date | `time` | Timestamp |

## Read Attributes & Allowed Values

Get a list of attributes and allowed values.

```plaintext
GET /traffic/audiences/mail_event/allowedvalues/{eventType}
```

Each event type contains multiple attributes (such as hotel brand or hotel city). Certain attributes allow any value while others are restricted to a specific set of values.

### Parameters

| **Parameter** | **Parameter Type** | **Description** | **Data Type** | **Required** |
| --- | --- | --- | --- | --- |
| `eventType` | path | Specifies the purchase receipt type. - `FLIGHT`: Consumers who have booked an airline reservation. - `CAR`: Consumers who have booked a car rental. - `HOTEL`: Consumers who have booked a hotel booking or confirmation. - `MOVIE_TICKETS`: Consumers who have purchased a movie ticket. - `LIVE_EVENTS`: Consumers who have purchased a ticket to a live event, like a concert. - `INVOICES`: Consumers who have received statements or bills. - `PRODUCTS`: Consumers who have purchased a particular product. - `SOCIAL_EVENTS` - Consumers who have received emails and invitations from social-planning websites. - `STOCKS_AND_INVESTMENTS` - Consumers who have received trade confirmation emails from investment brokerages. |  |  |

### Sample Request URL

```plaintext
GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mail_event/allowedvalues/HOTEL
```

### Sample Response (Partial)

The response contains the following fields:

| Name | Description |
| --- | --- |
| categories | Array containing allowed values for each attribute name. Each item contains the following fields: attributeName: - `Attribute name`. Required when creating the audience. - `allowedValues`: If an attribute allows only specific values, these will be listed here. |

```plaintext
{
  "response": {
    "categories": [
      {
        "attributeName": "hotel booking date",
        "allowedValues": []
      },
      {
        "attributeName": "checkin date",
        "allowedValues": []
      },
      {
        "attributeName": "hotel city",
        "allowedValues": []
      },
      {
        "attributeName": "hotel name",
        "allowedValues": []
      },
      {
        "attributeName": "length of stay",
        "allowedValues": []
      },
      {
        "attributeName": "booked hotel with",
        "allowedValues": [
          "0sg.net",
          "4huffs.com"
        ]
      },
      {
        "attributeName": "hotel brand",
        "allowedValues": [
          "BEST WESTERN HOTELS",
          "CHOICE HOTELS"
        ]
      },
      {
        "attributeName": "hotel country",
        "allowedValues": [
          "AND",
          "ARG"
        ]
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-08-30T04:01:45Z"
}
```

## Read Audience

Read a specific purchase receipt audience.

```plaintext
GET /traffic/audiences/mail_event/{id}?accountId={accountId}
```

### Parameters

| **Parameters** | **Parameter Type** | **Description** | **Data Type** | **Required/Optional** |
| --- | --- | --- | --- | --- |
| `id` | path | Specifies the audience ID. | `integer` | Required |
| `accountId` | query | Specifies the advertiser ID. | `integer` | Required for advertiser-level audiences. Do not use for seat-level audiences. |

### Sample Request URL (Seat-Level)

```plaintext
GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mail_event/50335610
```

### Sample Response (Seat-Level)

```plaintext
{
  "response": {
    "id": 50335610,
    "name": "purtest130",
    "frequency": 1,
    "createdAt": "2017-09-23",
    "status": "ACTIVE",
    "eventType": "CAR",
    "countryCodes": ["USA", "CAN"],
    "textAttributes": [
      {
        "name": "booked car with",
        "key": "cpv",
        "groupType": "INCLUDE",
        "values": [
          "aa.com",
          "advantage.com"
        ]
      },
      {
        "name": "rental city",
        "key": "ccity",
        "groupType": "EXCLUDE",
        "matchType": "CONTAINS",
        "values": [
          "San Francisco",
          "San Jose",
          "Oakland"
        ]
      }
    ],
    "timeAttributes": [
      {
        "name": "pickup date",
        "key": "cpickdt",
        "rangeType": "DAY",
        "numDays": "2"
      },
      {
        "name": "car booking date",
        "key": "cbkdt",
        "rangeType": "DATE",
        "fromDate": "20170703",
        "toDate": "20170903"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-09-23T05:11:03Z"
}
```

### Sample Request URL (Advertiser-Level)

```plaintext
GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mail_event/50335609?accountId=1356341
```

### Sample Response (Advertiser-Level)

```plaintext
{
  "response": {
    "id": 50335609,
    "name": "travel-test",
    "accountId": 1356341,
    "frequency": 1,
    "createdAt": "2017-09-23",
    "status": "ACTIVE",
    "eventType": "FLIGHT",
    "countryCodes": ["USA", "CAN"],
    "textAttributes": [
      {
        "name": "airline",
        "key": "farcd",
        "groupType": "INCLUDE",
        "values": [
          "UA"
        ]
      },
      {
        "name": "travel from",
        "key": "fdeap",
        "groupType": "EXCLUDE",
        "values": [
          "JFK"
        ]
      }
    ],
    "timeAttributes": [
      {
        "name": "booking date",
        "key": "fbkdt",
        "rangeType": "DAY",
        "numDays": "2"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-09-23T05:08:19Z"
}
```

## Create Audience

Create a new purchase receipt audience.

```plaintext
POST /traffic/audiences/mail_event
```

Audiences may be created at the seat-level or the advertiser-level. If no advertiser ID (`accountId`) is specified, the purchase receipt audience is created at the seat level and is available to all advertisers belonging to that seat.

### Sample Request URL (Seat-Level)

```plaintext
POST https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mail_event
```

### Sample Request Body (Seat-Level)

```plaintext
{
  "name": "purtest130",
  "textAttributes": [
    {
      "key": "cpv",
      "groupType": "INCLUDE",
      "values": [
        "aa.com",
        "advantage.com"
      ]
    },
    {
      "key": "ccity",
      "groupType": "EXCLUDE",
      "matchType": "CONTAINS",
      "values": [
        "San Francisco",
        "San Jose",
        "Oakland"
      ]
    }
  ],
  "timeAttributes": [
    {
      "key": "cbkdt",
      "rangeType": "DATE",
      "fromDate": "20170703",
      "toDate": "20170903"
    },
    {
      "key": "cpickdt",
      "rangeType": "DAY",
      "numDays": "2"
    }
  ],
  "eventType": "CAR",
  "accountId": null,
  "status": "ACTIVE",
  "frequency": 1,
  "countryCodes": ["USA", "CAN"],
}
```

### Sample Response (Seat-Level)

```plaintext
{
  "response": {
    "id": 50335610,
    "name": "purtest130",
    "frequency": 1,
    "createdAt": "2017-09-23",
    "status": "ACTIVE",
    "eventType": "CAR",
    "countryCodes": ["USA", "CAN"],
    "textAttributes": [
      {
        "name": "booked car with",
        "key": "cpv",
        "groupType": "INCLUDE",
        "values": [
          "aa.com",
          "advantage.com"
        ]
      },
      {
        "name": "rental city",
        "key": "ccity",
        "groupType": "EXCLUDE",
        "matchType": "CONTAINS",
        "values": [
          "San Francisco",
          "San Jose",
          "Oakland"
        ]
      }
    ],
    "timeAttributes": [
      {
        "name": "pickup date",
        "key": "cpickdt",
        "rangeType": "DAY",
        "numDays": "2"
      },
      {
        "name": "car booking date",
        "key": "cbkdt",
        "rangeType": "DATE",
        "fromDate": "20170703",
        "toDate": "20170903"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-09-23T05:11:03Z"
}
```

### Sample Request Body (Advertiser-Level)

```plaintext
{
  "name": "travel-test",
  "textAttributes": [
    {
      "key": "airline",
      "groupType": "INCLUDE",
      "values": [
        "UA"
      ]
    },
    {
      "key": "travel from",
      "groupType": "EXCLUDE",
      "values": [
        "JFK"
      ]
    }
  ],
  "timeAttributes": [
    {
      "key": "booking date",
      "rangeType": "DAY",
      "numDays": "2"
    }
  ],
  "eventType": "FLIGHT",
  "accountId": 1356341,
  "status": "ACTIVE",
  "frequency": 1,
  "countryCodes": ["USA", "CAN"],
}
```

### Sample Response (Advertiser-Level)

```plaintext
{
  "response": {
    "id": 50335609,
    "name": "travel-test",
    "accountId": 1356341,
    "frequency": 1,
    "createdAt": "2017-09-23",
    "status": "ACTIVE",
    "eventType": "FLIGHT",
    "countryCodes": ["USA", "CAN"],
    "textAttributes": [
      {
        "name": "airline",
        "key": "farcd",
        "groupType": "INCLUDE",
        "values": [
          "UA"
        ]
      },
      {
        "name": "travel from",
        "key": "fdeap",
        "groupType": "EXCLUDE",
        "values": [
          "JFK"
        ]
      }
    ],
    "timeAttributes": [
      {
        "name": "booking date",
        "key": "fbkdt",
        "rangeType": "DAY",
        "numDays": "2"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-09-23T04:56:01Z"
}
```

## Update Audience

Update an existing purchase receipt audience.

```plaintext
PUT /traffic/audiences/mail_event/{id}
```

Partial updates are supported for all fields except `timeAttributes`; values of supported fields which are not in the payload will remain unchanged.

### Sample Request URL (Seat-Level)

```plaintext
PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mail_event/50336118
```

### Sample Request Body (Seat-Level)

```plaintext
{
  "name": "new_name_purchase_event",
  "textAttributes": [
    {
      "key": "cpv",
      "groupType": "INCLUDE",
      "values": [
        "aa.com",
        "advantage.com"
      ]
    }
  ]
}
```

### Sample Response (Seat-Level)

```plaintext
{
  "response": {
    "id": 50336118,
    "name": "new_name_purchase_event",
    "frequency": 1,
    "createdAt": "2017-09-25",
    "status": "INACTIVE",
    "eventType": "CAR",
    "countryCodes": ["USA", "CAN"],
    "textAttributes": [
      {
        "name": "booked car with",
        "key": "cpv",
        "groupType": "INCLUDE",
        "values": [
          "aa.com",
          "advantage.com"
        ]
      }
    ],
    "timeAttributes": []
  },
  "errors": null,
  "timeStamp": "2017-09-25T18:11:47Z"
}
```

### Sample Request URL (Advertiser-Level)

```plaintext
PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mail_event/50336118?accountId=1356341
```

### Sample Request Body (Advertiser-Level)

```plaintext
{
  "name": "new_name_purchase_event_adv",
  "accountId": 1356341,
  "textAttributes": [
    {
      "key": "ccity",
      "groupType": "EXCLUDE",
      "matchType": "CONTAINS",
      "values": [
        "San Francisco",
        "San Jose",
        "Oakland"
      ]
    }
  ]
}
```

### Sample Response (Advertiser-Level)

```plaintext
{
  "response": {
    "id": 50336118,
    "name": "new_name_purchase_event_adv",
    "accountId": 1356341,
    "frequency": 1,
    "createdAt": "2017-09-25",
    "status": "INACTIVE",
    "eventType": "CAR",
    "countryCodes": ["USA"],
    "textAttributes": [
      {
        "name": "rental city",
        "key": "ccity",
        "groupType": "EXCLUDE",
        "matchType": "CONTAINS",
        "values": [
          "San Francisco",
          "San Jose",
          "Oakland"
        ]
      }
    ],
    "timeAttributes": []
  },
  "errors": null,
  "timeStamp": "2017-09-25T18:14:17Z"
}
```

## Read Supported Countries

Get a list of supported countries.

```plaintext
 GET /traffic/audiences/countries
```

### Sample Response

```plaintext
{
  "countries": [
    {
      "isoCode3": "USA",
      "name": "USA"
    },
    {
      "isoCode3": "CAN",
      "name": "Canada"
    },
    {
      "isoCode3": "JPN",
      "name": "Japan"
    },
    {
      "isoCode3": "IND",
      "name": "India"
    },
    …
    {
      "isoCode3": "ECU",
      "name": "Ecuador"
    },
    {
      "isoCode3": "ARG",
      "name": "Argentina"
    },
    {
      "isoCode3": "COL",
      "name": "Colombia"
    }
  ]
}
```

## Delete Audience

The DSP Traffic API does not support deletion of purchase receipt audiences.