Product Feed Operations

This article describes DPA Product Feed operations you can use to create, update, check status and get the product feed by feed ID. It also descrives how to download a feed error file.

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.

Create a Product Feed

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

POST traffic/productfeed

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.

Payload:

{
    "accountId": 35220,
    "feedUrl": "http://mb.zenfs.com/yam/ews/PRODUCTION/bulk/import/000000004f40c4eb000000006c0155fe_5f986f5d9b905_1603825501_temp3411924759738859902_prod_feed_2020_10_27_test_3new_items.csv",
    "fileName": "Test Upload 1",
    "userName": "",
    "password": "",
    "feedType": "DPA_RECURRING",
    "scheduleInfo": {
        "feedFrequency": "DAILY",
        "everyXhours": 6,
        "dayOfWeek": null,
        "hourMinute": null
    },
    "verticalType": "RETAIL",
    "feedId": null,
    "feedStatus": null,
    "nextUpdate": null
}

Important

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.

Check Feed Status

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

GET /traffic/productfeed/{feedId}/status?accountId={accountId}

Response:

{
  "response": {
    "status": "COMPLETED",
    "startedTime": "2021-08-27T08:48:33Z",
    "finishedTime": "2021-08-27T08:48:35Z",
   "resultFile":"WWsuBaRHNwlbd0IDNOR228qALEO1BNEpm1Zqh9FJQaQHaWph0mH4uECVtLK_5NDfgiF65qJf92MGYx9iej13rUaStl_8DKlItqAqUK_scFS4ismfrtMMYzNyuAahTUhH",
    "totalCount": "3",
    "addedCount": "0",
    "updatedCount": "3",
    "failedCount": "0"
  },
  "errors": null,
  "timeStamp": "2021-09-03T05:24:00.617Z"
}

Read product feed by feed ID

Method: To get a product feed by feed ID, make a GET call to this endpoint:

GET /traffic/productfeed/{feedId}?accountId={accountId}

Response:

One Time Feed:

{
  "response": {
        "accountId": 35220,
        "feedUrl": "http://mb.zenfs.com/yam/ews/PRODUCTION/bulk/import/000000004f40c4eb000000006c0155fe_5f986f5d9b905_1603825501_temp3411924759738859902_prod_feed_2020_10_27_test_3new_items.csv",
        "fileName": "test123",
        "verticalType": "PRODUCT",
        "feedType": "DPA_ONE_TIME",
        "updatedAt": "2021-08-27T19:30:09.330Z",
        "feedId": 1000121564,
        "feedStatus": "ACTIVE"
  },
  "errors": null,
  "timeStamp": "2021-08-27T19:01:42.523Z"
}

Recurring Feed:

{
  "response": {
        "accountId": 35220,
        "feedUrl": ""http://mb.zenfs.com/yam/ews/PRODUCTION/bulk/import/000000004f40c4eb000000006c0155fe_5f986f5d9b905_1603825501_temp3411924759738859902_prod_feed_2020_10_27_test_3new_items.csv",
        "fileName": "test123",
        "verticalType": "RETAIL",
        "feedType": "DPA_RECURRING",
        "scheduleInfo": {
        "feedFrequency": "WEEKLY",
        "dayOfWeek": "TUESDAY",
        "hourMinute": "00:00"
        },
        "updatedAt": "2021-08-27T19:30:09.330Z",
        "feedId": 1000143772,
        "feedStatus": "ACTIVE"
  },
  "errors": null,
  "timeStamp": "2021-08-27T19:21:44.469Z"
}

Update product feed by feed ID

Method: To update a product feed by feed ID, make a PUT call to this endpoint:

PUT /traffic/productfeed/{feedId}

Payload:

{
    "accountId": 35220,
    "feedUrl": "http://mb.zenfs.com/yam/ews/PRODUCTION/bulk/import/000000004f40c4eb000000006c0155fe_5f986f5d9b905_1603825501_temp3411924759738859902_prod_feed_2020_10_27_test_3new_items.csv",
    "fileName": "test123",
    "userName": "",
    "password": "",
    "verticalType": "RETAIL",
    "feedType": "DPA_ONE_TIME",
    "scheduleInfo": null,
    "feedId": 1000121564,
    "feedStatus": "ACTIVE",
    "nextUpdate": null
}

Download feed error file

Method: To download a feed error file, make a GET call to this endpoint:

GET /traffic/productfeed/errors?accountId={accountId}&token={token}

Response:

{
    "response": {
        "errorData": "SW52YWxpZCBpbWFnZSxUYXJnZXRlZCBQcm9kdWN0LCJzb3VyY2VJZD0yLCBQb3NpdGl2ZSB0ZXN0LCBzaG91bGQgYmUgdGFyZ2V0ZWQsIHBpY2sgdXAgJDEwIixodHRwOi8vd3d3LmFiYy5uZXQuYXUvbmV3c3JhZGlvL3Jlcy9pbWcvYWJjbmV3c3JhZGlvXzEyMDB4NjMwLnBuZywyLGh0dHA6Ly93d3cubGFuZGluZ3VybHBvc2l0aXZlLmNvbSxpbiBzdG9jayxuZXcsMTAsZ3RpbixtcG4sYnJhbmQsaHR0cDovL3d3dy5hZGRpdGlvbmFsLmxpbmssMTgtMjgscmVkLG1hbGUsaXRlbUdyb3VwSWQsY2F0ZWdvcnksbWF0ZXJpYWwscGF0dGVybixwcm9kdWN0VHlwZSwyMDE0LTExLTAxVDE1OjIwOjI1LTA3OjAwLzIwMTUtMTItMDFUMTU6MjA6MjUtMDc6MDAsMjAsc2hpcHBpbmcsc2hpcHBpbmcgd2VpZ2h0LHNoaXBwaW5nIHNpemUsY3VzdG9tIDAsY3VzdG9tIDEsY3VzdG9tIDIsY3VzdG9tIDMsY3VzdG9tIDQNCkludmFsaWQgaW1hZ2UsTm9uLXRhcmdldGVkIFByb2R1Y3QsInNvdXJjZUlkPTMsIE5lZ2F0aXZlIHRlc3QsIHNob3Vkbid0IGJlIHRhcmdldGVkIixodHRwOi8vd3d3LmFiYy5uZXQuYXUvbmV3c3JhZGlvL3Jlcy9pbWcvYWJjbmV3c3JhZGlvXzEyMDB4NjMwLnBuZywzLGh0dHA6Ly93d3cubGFuZGluZ3VybG5lZ2F0aXZlLmNvbSxpbiBzdG9jayxuZXcsMTAsZ3RpbixtcG4sYnJhbmQsaHR0cDovL3d3dy5hZGRpdGlvbmFsLmxpbmssMTgtMjgscmVkLG1hbGUsaXRlbUdyb3VwSWQsY2F0ZWdvcnksbWF0ZXJpYWwscGF0dGVybixwcm9kdWN0VHlwZSwyMDE0LTExLTAxVDE1OjIwOjI1LTA3OjAwLzIwMTQtMTItMDFUMTU6MjA6MjUtMDc6MDAsMjAsc2hpcHBpbmcsc2hpcHBpbmcgd2VpZ2h0LHNoaXBwaW5nIHNpemUsY3VzdG9tIDAsY3VzdG9tIDEsY3VzdG9tIDIsY3VzdG9tIDMsY3VzdG9tIDQNCg=="
    },
    "errors": null,
    "timeStamp": "2021-11-29T21:30:58.149Z"
}

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