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-03:00/2014-12-01T00:00-03:00

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

required

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.00",
  "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-01T12:30:30+02:00",
  "itemGroupId": "1",
  "googleProductCategory": "Apparel & Accessories > Clothing > Dresses",
  "customLabel0": "sample",
  "customLabel1": "sample",
  "customLabel2": "sample",
  "customLabel3": "sample",
  "customLabel4": "sample",
  "material": "sample",
  "pattern": "sample",
  "shippingSize": "12",
  "shippingWeight": "12",
  "shipping": "sample",
  "productType": "Home & Garden > Kitchen & Dining > Appliances > Refrigerators",
  "salePrice": "2",
  "salePriceEffectiveDateStr": "2014-11-01T12:00-03:00/2014-12-01T00:00-03:00"
}

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.00",
  "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-01T12:30:30+02:00",
  "itemGroupId": "1",
  "googleProductCategory": "Apparel & Accessories > Clothing > Dresses",
  "customLabel0": "sample",
  "customLabel1": "sample",
  "customLabel2": "sample",
  "customLabel3": "sample",
  "customLabel4": "sample",
  "material": "sample",
  "pattern": "sample",
  "shippingSize": "12",
  "shippingWeight": "12",
  "shipping": "sample",
  "productType": "Home & Garden > Kitchen & Dining > Appliances > Refrigerators",
  "salePrice": "2",
  "salePriceEffectiveDateStr": "2014-11-01T12:00-03:00/2014-12-01T00:00-03:00"
}

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.00",
         "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.00",
         "globalTradeItemNumber": "sample",
         "manufacturerProductNumber": "sample",
         "brand": "brand",
         "ageGroup": "ADULT",
         "color": "RED",
         "gender": "MALE",
         "itemGroupId": "{ITEM_GROUP_ID}",
         "googleProductCategory": "Apparel & Accessories > Clothing > Dresses",
         "material": "sample",
         "productType": "Home & Garden > Kitchen & Dining > Appliances > Refrigerators",
         "salePrice": "20",
         "salePriceEffectiveDateStr": "2014-11-01T15:20:25-07:00/2015-12-01T15:20:25-07:00",
         "shippingWeight": "sample",
         "shippingSize": "sample",
         "customLabel0": "custom 0",
         "customLabel1": "custom 1",
         "customLabel2": "custom 2",
         "customLabel3": "custom 3",
         "customLabel4": "custom 4"
      }
   ],
   "errors": null,
   "timeStamp": "2023-02-13T16:35:33.947Z"
}

Get Product Ads

Retrieve multiple existing product ads.

GET /traffic/productads?accountId={ACCOUNT_ID}&page={PAGE}&limit={LIMIT}

Parameters

Parameter

Parameter Type

Description

Data Type

Required

accountId

query

Specifies the account/advertiser ID.

integer

Y

page

query

Specifies the page number.

integer

N

limit

query

Specifies the total number of items to return. Maximum allowed value is 100.

integer

N

Sample Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/productads?accountId={ACCOUNT_ID}&page=1&limit=1

Sample Response

{
  "response": [
    {
         "id": "{PRODUCT_AD_ID}",
          "sourceId": "{SOURCE_ID}",
          "accountId": "{ACCOUNT_ID}",
          "title": "Sample Title",
          "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
          "imageLink": "https://somewebsite.secure.file.com/Table233.jpg",
          "link": "https://somewebsite.com",
          "availability": "IN_STOCK",
          "condition": "NEW",
          "price": "7.00",
          "brand": "advara",
          "additionalImageLink": "https://somewebsite.secure.img.com/AdditionalHome123.jpg",
          "ageGroup": "ADULT",
          "color": "RED",
          "expirationDateStr": "2024-03-01T12:30:30+02:00",
          "gender": "MALE",
          "itemGroupId": "{ITEM_GROUP_ID}",
          "googleProductCategory": "Apparel & Accessories > Clothing > Dresses",
          "material": "sample",
          "pattern": "sample",
          "productType": "Home & Garden > Kitchen & Dining > Appliances > Refrigerators",
          "salePrice": "2",
          "salePriceEffectiveDateStr": "2014-11-01T12:00-03:00/2014-12-01T00:00-03:00",
          "shipping": "sample",
          "shippingWeight": "12",
          "shippingSize": "12",
          "customLabel0": "sample",
          "customLabel1": "sample",
          "customLabel2": "sample",
          "customLabel3": "sample",
          "customLabel4": "sample",
          "status": "ACTIVE",
          "globalTradeItemNumber": "sample",
          "manufacturerProductNumber": "sample"

    }
  ],
  "errors": null,
  "timeStamp": "2020-06-30T20:05:33.265Z"
}

Get Product Ad by ID

Retrieve existing product ad using the id.

GET /traffic/productads/{PRODUCT_AD_ID}

Parameters

Parameter

Parameter Type

Description

Data Type

Required

id

query

Specifies the Product Ad ID.

string

Y

Sample Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/productads/{PRODUCT_AD_ID}

Sample Response

{
  "response": {
         "id": "{PRODUCT_AD_ID",
          "sourceId": "{SOURCE_ID}",
          "accountId": "{ACCOUNT_ID}",
          "title": "Sample Title",
          "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
          "imageLink": "https://somewebsite.secure.file.com/Table233.jpg",
          "link": "https://somewebsite.com",
          "availability": "IN_STOCK",
          "condition": "NEW",
          "price": "7.00",
          "brand": "advara",
          "additionalImageLink": "https://somewebsite.secure.img.com/AdditionalHome123.jpg",
          "ageGroup": "ADULT",
          "color": "RED",
          "expirationDateStr": "2024-03-01T12:30:30+02:00",
          "gender": "MALE",
          "itemGroupId": "{ITEM_GROUP_ID}",
          "googleProductCategory": "Apparel & Accessories > Clothing > Dresses",
          "material": "sample",
          "pattern": "sample",
          "productType": "Home & Garden > Kitchen & Dining > Appliances > Refrigerators",
          "salePrice": "2",
          "salePriceEffectiveDateStr": "2014-11-01T12:00-03:00/2014-12-01T00:00-03:00",
          "shipping": "sample",
          "shippingWeight": "12",
          "shippingSize": "12",
          "customLabel0": "sample",
          "customLabel1": "sample",
          "customLabel2": "sample",
          "customLabel3": "sample",
          "customLabel4": "sample",
          "status": "ACTIVE",
          "globalTradeItemNumber": "sample",
          "manufacturerProductNumber": "sample"

  },
  "errors": null,
  "timeStamp": "2020-06-30T20:05:33.265Z"
}