Product Ads¶

Dynamic Product Ads (DPA) are feed-based ads that can be personalized, depending on each customer’s unique shopping history and buying habits.

Upload a product catalog using the feeds. Each product in the feed is converted to a product ad. This API allows quick manipulation of these product ads.

Note

Any images that you wish to include in your product in the feed must be a minimum of 300x300 pixels.

Endpoint¶

/traffic/productads

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

Use the GET method to retrieve an existing product ad.
Use the POST method to create a new product ad.
Use the PUT method to update an existing product ad.

Resources¶

The product ads object contains the following fields:

Field name	Type & size	Description	Required or optional
`id`	`string`	Specifies the product ad ID	required for update
`sourceId`	`string, Max size: 100`	Unique ID to identify the product. The product sets, user recommendation and dot pixel custom events should use this ID. All products with duplicate IDs will be ignored.	required
`advertiserId`	`long`	The ID of the DSP advertiser associated with the product ad	required
`title`	`string, Max size: 100`	The title of the product. This field will be used in the ad presentation. Title displayed is 20-50 characters.	required
`description`	`string, Max size: 4000`	A short description of the product. This field will be used in the ad presentation. The description displayed is 20-150 characters.	required
`imageLink`	`string`	Link to an image of the product. The image provided will be mapped to these formats for native ads: large 627x627px and HQ 1200x627px.	required
`link`	`string`	Landing page of the merchant when the ad is clicked.	required
`availability`	`string`	Defines product availability. Accepted values are: `IN_STOCK` - product is in stock and can be shipped immediately. `OUT_OF_STOCK` - product is currently unavailable. Out of stock products are not eligible for serving and may be removed from the system after 3 months. `PREORDER` - product will be available in future. `AVAILABLE_FOR_ORDER` - Product can be shipped in 1-2 weeks.	required
`condition`	`string`	The values of the product ad condition: `NEW` `REFURBISHED` `USED`	required
`price`	`string`	The cost of the product and currency. Currency should be specified as the ISO 4217 currency code e.g. 9.99 USD. This field will be used in ad presentation along with title as: title - price. The currency symbol will be used. E.g. Bead-Fringe Suede Ankle Boot - $1200.	required
`globalTradeItemNumber`	`string, Max size: 70`	The Global Trade Item Number (GTINs) can include UPC, EAN, JAN, and ISBN.	one of gtin/mpn/brand is required
`manufacturerProductNumber`	`string, Max size: 70`	The number which uniquely identifies the product to its manufacturer.	one of gtin/mpn/brand is required
`brand`	`string, Max size: 70`	The name of the brand.	one of gtin/mpn/brand is required
`additionalImageLink`	`string, Max size: 2000`	Comma separated multiple (max 10) additional image urls can be provided.	optional
`ageGroup`	`string`	The values of the product ad age group: `NEWBORN` `INFANT` `TODDLER` `KIDS` `ADULT`	optional
`color`	`string, Max size: 100`	The color of the product.	optional
`expirationDateStr`	`ISO‑8601 (YYYY‑MM‑DD)`	The expiration date of the product. An expired product is not eligible for serving.	optional
`gender`	`string`	The values of the product ad gender: `MALE` `FEMALE` `UNISEX`	optional
`itemGroupId`	`string`	Similar products can share same item group ID	optional
`googleProductCategory`	`string, Max size: 250`	Predefined values from Google’s product taxonomy. For example, Apparel & Accessories > Clothing > Dresses.	optional
`material`	`string, Max size: 200`	Material or fabric of the product.	optional
`pattern`	`string, Max size: 100`	The pattern or graphic print featured on a product.	optional
`productType`	`string, Max size: 750`	The retailer-defined category of the product as a string. Examples : TSV format: Home & Garden > Kitchen & Dining > Appliances > Refrigerators	optional
`salePrice`	`string`	The discounted price if the product is on sale. Currency should be specified as the ISO 4217 currency code. Specified as 9.99 USD	optional
`salePriceEffectiveDateStr`	`ISO‑8601 (YYYY‑MM‑DD)`	The start and end date/time of the sale, separated by a slash. e.g., 2014-11-01T12:00-0300/2014-12-01T00:00-0300	optional
`shipping`	`string`	N/A	optional
`shippingWeight`	`string`	N/A	optional
`shippingSize`	`string`	N/A	optional
`customLabel0`	`string, Max size: 100`	Can contain additional information about the item	optional
`customLabel1`	`string, Max size: 100`	Can contain additional information about the item	optional
`customLabel2`	`string, Max size: 100`	Can contain additional information about the item	optional
`customLabel3`	`string, Max size: 100`	Can contain additional information about the item	optional
`customLabel4`	`string, Max size: 100`	Can contain additional information about the item	optional
`status`	`string`	The values of the product ad status: `ACTIVE` `PAUSED` `REJECTED` `DELETED`	optional

Create Product Ad¶

Create a new product ad.

POST /traffic/productads

Parameters¶

All fields are specified in the body of the application/json payload.

Sample Request URL¶

POST https://dspapi.admanagerplus.yahoo.com/traffic/productads

Sample Request Body¶

{
  "sourceId": "{SOURCE_ID}",
  "accountId": "${ACCOUNT_ID}",
  "status": "ACTIVE",
  "title": "Sample Title",
  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat",
  "link": "https://somewebsite.com/Home123.html",
  "availability": "IN_STOCK",
  "condition": "NEW",
  "price": "7",
  "brand": "advara",
  "imageLink": "https://somewebsite.secure.img.com/Home123.jpg",
  "globalTradeItemNumber": "sample",
  "manufacturerProductNumber": "sample",
  "additionalImageLink": "https://somewebsite.secure.img.com/AdditionalHome123.jpg",
  "ageGroup": "ADULT",
  "color": "RED",
  "gender": "MALE",
  "expirationDateStr": "2024-03-01",
  "itemGroupId": "1",
  "googleProductCategory": "sample",
  "customLabel0": "sample",
  "customLabel1": "sample",
  "customLabel2": "sample",
  "customLabel3": "sample",
  "customLabel4": "sample",
  "material": "sample",
  "pattern": "sample",
  "shippingSize": "12",
  "shippingWeight": "12",
  "shipping": "sample",
  "productType": "sample",
  "salePrice": "2",
  "salePriceEffectiveDateStr": "2014-11-01T12:00-0300/2014-12-01T00:00-0300"
}

Sample Response¶

{
  "id": "{PRODUCT_AD_ID}",
  "sourceId": "{SOURCE_ID}",
  "accountId": "${ACCOUNT_ID}",
  "status": "ACTIVE",
  "title": "Sample Title",
  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat",
  "link": "https://somewebsite.com/Home123.html",
  "availability": "IN_STOCK",
  "condition": "NEW",
  "price": "7",
  "brand": "advara",
  "imageLink": "https://somewebsite.secure.img.com/Home123.jpg",
  "globalTradeItemNumber": "sample",
  "manufacturerProductNumber": "sample",
  "additionalImageLink": "https://somewebsite.secure.img.com/AdditionalHome123.jpg",
  "ageGroup": "ADULT",
  "color": "RED",
  "gender": "MALE",
  "expirationDateStr": "2024-03-01",
  "itemGroupId": "1",
  "googleProductCategory": "sample",
  "customLabel0": "sample",
  "customLabel1": "sample",
  "customLabel2": "sample",
  "customLabel3": "sample",
  "customLabel4": "sample",
  "material": "sample",
  "pattern": "sample",
  "shippingSize": "12",
  "shippingWeight": "12",
  "shipping": "sample",
  "productType": "sample",
  "salePrice": "2",
  "salePriceEffectiveDateStr": "2014-11-01T12:00-0300/2014-12-01T00:00-0300"
}

Update Product Ads¶

Update existing product ads.

PUT /traffic/productads

Parameters¶

All fields are specified in the body of the application/json payload.

Sample Request URL¶

PUT https://dspapi.admanagerplus.yahoo.com/traffic/productads

Sample Request Body¶

[
   {
      "status": "ACTIVE",
      "id": "{PRODUCT_AD_ID_1}"
   },
   {
       "status": "PAUSED",
       "id": "{PRODUCT_AD_ID_2}"
   }

]

Sample Response¶

{
   "response": [
      {
         "id": "{PRODUCT_AD_ID_1}",
         "sourceId": "{SOURCE_ID}",
         "accountId": {ACCOUNT_ID},
         "title": "{SAMPLE_TITLE_1}",
         "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
         "imageLink": "https://somewebsite.secure.img.com/Home123.png",
         "link": "https://somewebsite.com/Home123.html",
         "availability": "IN_STOCK",
         "status": "ACTIVE",
         "condition": "NEW",
         "price": "8",
         "brand": "advara"
      },
      {
         "id": "{PRODUCT_AD_ID_2}",
         "sourceId": "{SOURCE_ID}",
         "accountId": {ACCOUNT_ID},
         "title": "Sample Title 2",
         "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit",
         "imageLink": "https://somewebsite.secure.file.com/Table233.jpg",
         "link": "https://somewebsite.com",
         "availability": "IN_STOCK",
         "status": "PAUSED",
         "condition": "NEW",
         "price": "10",
         "globalTradeItemNumber": "sample",
         "manufacturerProductNumber": "sample",
         "brand": "brand",
         "ageGroup": "ADULT",
         "color": "RED",
         "gender": "MALE",
         "itemGroupId": "{ITEM_GROUP_ID}",
         "googleProductCategory": "category",
         "material": "material",
         "productType": "productType",
         "salePrice": "20",
         "salePriceEffectiveDateStr": "2014-11-01T15:20:25-07:00/2015-12-01T15:20:25-07:00",
         "shippingWeight": "shipping weight",
         "shippingSize": "shipping size",
         "customLabel0": "custom 0",
         "customLabel1": "custom 1",
         "customLabel2": "custom 2",
         "customLabel3": "custom 3",
         "customLabel4": "custom 4"
      }
   ],
   "errors": null,
   "timeStamp": "2023-02-13T16:35:33.947Z"
}