2. Product Feed Operations

Abstract

Feed operations include creating, updating and deleting the product feed. You can also download a sample product feed spreadsheet in .csv format.

Download Sample Product Feed Spreadsheet

To download a sample feed spreadsheet in .csv format, click Download CSV Spreadsheet.

Sample product feeds can be .csv or .tsv files. For specific format requirements, refer to Bulk Operations.

Feed Formats

Supported feed file formats include:

File Format

Delimited?

Encoding

.csv

Yes

UTF-8, UTF-16 and UTF-32

.tsv

UTF-8, UTF-16 and UTF-32

.txt

Yes

UTF-8, UTF-16 and UTF-32

.xml

UTF-8, UTF-16 and UTF-32

.rss

UTF-8, UTF-16 and UTF-32

Note

gzip (GNU zip) is also a supported file transfer format. The gzip format produces files with a .gz extension. For more information, refer to gzip and GNU Operating System.

Note

You must have a valid ftp server and make your feed available on the server.

Step 1: Create a Product Feed

To create a product feed into Yahoo Native, make a POST call to this endpoint:

https://api.gemini.yahoo.com/v3/rest/feed

The current file formats that are supported include:

File Format

Delimited?

Encoding

.csv

Yes

UTF-8, UTF-16 and UTF-32

.tsv

UTF-8, UTF-16 and UTF-32

.txt

Yes

UTF-8, UTF-16 and UTF-32

.xml

UTF-8, UTF-16 and UTF-32

.rss

UTF-8, UTF-16 and UTF-32

Note

gzip (GNU zip) is also a supported file transfer format. The gzip format produces files with a .gz extension. For more information, refer to gzip and GNU Operating System.

Note

You must have a valid ftp server and make your feed available on the server.

Example

Request:

{
  "advertiserId": 11,
  "status": "ACTIVE",
  "userName": "ftp_username",
  "feedType": "DPA_RECURRING",
  "fileName": "yourfeedfile.csv",
  "password": "password",
  "feedUrl": "ftp://yourftpserver.yourwebsite.com",
  "scheduleInfo": {
    "feedFrequency": "DAILY",
    "dayOfMonth": null,
    "dayOfWeek": null,
    "hourMinute": "12:00"
  }
}

Note

There two feed types: DPA_ONE_TIME and DPA_RECURRING. DPA_ONE_TIME indicates that the feed will be loaded only once, so you do not need to include scheduleInfo in your request. DPA_RECURRING indicates that the feed will be loaded repeatedly at the scheduled time.

Step 2: Check Feed Status

To check the feed status, make a GET call to this endpoint with the feed id, which is the response from creating a feed:

https://api.gemini.yahoo.com/v3/rest/feed/status?feedId=1421

response

{
"errors": null,
"timestamp": "2017-04-12 21:07:36",
"response": {
  "status": "COMPLETED",
  "startedTime": "2017-03-31 00:29:02",
  "finishedTime": "2017-03-31 00:29:02",
  "resultFile": "token",
  "results": {
    "Product_Ad": {
      "totalCount": 9,
      "addedCount": 0,
      "updatedCount": 9,
       "failedCount": 0

      }
    }
  }
}

Note

If the failedCount is greater than zero, you can this API to download the error reporting file:

https://api.gemini.yahoo.com/v3/rest/feed/error?resource=token

Product Feed Fields

The product feed fields are described below.

Field name

Type & size

Description

Required or optional

id

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

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. Description displayed is 20-150 characters.

required

image_link

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

image_link_optional

string

Link to an image of the product with different size than image_link. The image provided will be mapped to these formats for native ads: large 627x627px and HQ 1200x627px.

optional

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.

  • preorder- product will be available in future.

  • available for order - Product can be shipped in 1-2 weeks.

  • out of stock products are not eligible for serving and may be removed from the system after 3 months.

optional (will default to in stock if absent)

condition

string

The condition of the product. Accepted values are new, refurbished, or used.

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

not required

gtin

string, Max size: 70

The Global Trade Item Number (GTINs) can include UPC, EAN, JAN, and ISBN.

not required

mpn

string, Max size: 70

The number which uniquely identifies the product to its manufacturer.

not required

brand

string, Max size: 70

The name of the brand.

not required

additional_image_link

string, Max size: 2000

Comma separated multiple (max 10) additional image urls can be provided.

optional

age_group

string

The age group the product is meant for. Accepted values are newborn, infant, toddler, kids, and adult.

optional

color

string, Max size: 100

The color of the product.

optional

expiration_date

ISO‑8601 (YYYY‑MM‑DD) or YYYY‑MM‑DDTHH:MM or YYYY‑MM‑DDTHH:MM-0000). Dates without a time will default to 00:00 (midnight at the start of the date). Dates with a time but without a time zone will default to UTC.

The expiration date of the product. An expired product is not eligible for serving.

optional

gender

string

Acceptable values are male, female, and unisex

optional

item_group_id

string

Similar products can share same item group id

optional

google_product_category

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

product_type

string, Max size: 750

The retailer-defined category of the product as a string. Examples : TSV format: Home & Garden > Kitchen & Dining > Appliances > Refrigerators

optional

sale_price

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

sale_price_effective_date

ISO‑8601 (YYYY‑MM‑DD) or YYYY‑MM‑DDTHH:MM or YYYY‑MM‑DDTHH:MM or YYYY‑MM‑DDTHH:MM-0000).

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. Dates without a time will default to 00:00 (midnight at the start of the date). Dates with a time but without a time zone will default to UTC.

optional

shipping

string

optional

shipping_weight

string

optional

shipping_size

string

optional

custom_label_0

string, Max size: 100

Can contain additional information about the item

optional

custom_label_1

string, Max size: 100

Can contain additional information about the item

optional

custom_label_2

string, Max size: 100

Can contain additional information about the item

optional

custom_label_3

string, Max size: 100

Can contain additional information about the item

optional

custom_label_4

string, Max size: 100

Can contain additional information about the item

optional

custom_label_5

string, Max size: 100

Can contain additional information about the item

optional

last_changed_date

string, representing epoch time

Represents the time when the change in the catalog was made.

optional