Sync Items to Catalogs

Sharing Catalog Data with Kevel

Catalog data should be shared in a Newline Delimited JSON (NDJSON) file. Kevel will provide you with details for an Amazon S3 bucket to share your data on a regular cadence. During testing and development (Phase 1 below), Kevel can accommodate receiving catalog data through other channels and in other formats.

Phase 1: Initial Import

To start the Catalog integration process, you'll work with your Kevel account team to send a one-time export of your catalog. The initial import is designed to provide a starting point to validate that Kevel has all the information required to ingest the catalog, and to enable your AdOps team to test the ad creation process to ensure that it meets their requirements.

Phase 2: Continuous Sync

After the initial import has been completed and approved by both organizations, Kevel will work with your engineering team to configure an Amazon S3 bucket owned by Kevel for you to sync the catalog files to on a regular basis. Kevel provisions a single bucket per Kevel Organization with sub "folders" or directories for Networks within that Organization (e.g. you may have dev and prod Kevel Networks). You can configure your integration to send files to the appropriate Network directory based on your preferences.

Kevel will monitor this S3 bucket for new files. Once Kevel determines that a new file has been synced to the bucket, Kevel will trigger an automatic ingestion process which will update the Catalog and any Ads that have been created from the underlying Catalog data.

Syncing Frequency

Kevel supports daily updates of Catalog contents; however, more frequent updates can be considered on a case-by-case basis depending on the use case and the size of the Catalog.

File Naming Conventions and Compression

The recommended name for the source file is <item-type>-<yyyymmdd>.ndjson e.g. products-20230526.ndjson or categories-20230526.ndjson.

To reduce the size of file transfers, Kevel recommends delivering the file gzipped. With this compression, the name could be products-20230526.ndjson.gz.

Catalog Item Structure

Each line in the source file needs to be a JSON object representing a single item. Catalog synchronization is done by providing the full product catalog with each sync, rather than incremental updates—when syncing items to a Catalog you must provide all information about the item whether you are adding it as a new item or updating it.

Structure each item's object with the following properties:

* indicates a required attribute

For each item, if the Catalog already has an item with that ID Key value, it is updated. If the ID Key value does not exist, a new item is created. If an item previously appeared in the source file and is removed in a subsequent sync, the item is removed from the Catalog as well. See Propagating Catalog Item Updates to Ads for more information.

Validation

A unique ID is the only required attribute when syncing items. Kevel does not perform any validation on the items sent to confirm that search keys or aliases present on the Catalog definition are set on the item being processed for ingestion. If a search key's value does not match its pre-defined type, Kevel will save the data, but that attribute will not be indexed.

Source Feed File Example

{"sku":"10855290","title":"Operation Board Game","brand":"Hasbro","image":"https://example.com/image/db42-4884-bdf2-7cf6e89b6976.jpg","categories":["Toys","Games","Board Games"]}
{"sku":"82759006","title":"Best Paper Greetings 1000 Pack Graduation Stickers, Congrats Grad Decal Roll, 8 Designs, Black & Gold, 1.5 in","brand":"Best Paper Greetings","image":"https://example.com/image/f2e748b0-88ff-4778-a008-5dbaafeeb5a4.jpg","categories":["Home","Arts, Crafts & Sewing","Paper & Paper Crafting","Stickers"]}
{"sku":"82744504","title":"Big Dot of Happiness Calling All Units - Police - Cop Birthday Party or Baby Shower Decorations - Beverage Bar Kit - 34 Pieces","brand":"Big Dot of Happiness","image":"https://example.com/image/7c3ce167-fd9c-4962-b6e8-56142f38f96b.jpg","categories":["Home","Arts, Crafts & Sewing","Paper & Paper Crafting","Stickers"]}
{"sku":"82428638","title":"NFL Pittsburgh Steelers Boys' Breakaway Knit Beanie","brand":"NFL","image":"https://example.com/image/2da3-4782-b2a3-39df709776b8.jpg","categories":["Sports & Outdoors","Fan Shop","Fan Shop Clothing","Accessories & Jewelry"]}
{"sku":"81494104","title":"Box Partners Shipping Tags Pre-Strung 13 Pt. 3 1/4\" x 1 5/8\" Fluorescent Red 1000/Case G12022C","brand":"Box Partners","image":"https://example.com/image/f1b52963-fa7e-4fed-940e-4e1a4b97181c.jpg","categories":["School & Office Supplies","Labels & Label Makers","Address Labels"]}
{"sku":"81187730","title":"HABA Kullerbu Dump Truck with Rubble Ball and Tippiing Bed","brand":"HABA","image":"https://example.com/image/9cfc0005-df7f-4788-a7a4-418e5b0f529a.jpg","categories":["Toys","Vehicles & Remote Control","Play Vehicles"]}
{"sku":"81027149","title":"1962 Chevrolet Impala SS 409 Convertible Satin Silver Metallic with Red Interior Limited Edition to 10312 pieces 1/64 Diecast Model Car by Autoworld","brand":"Auto World","image":"https://example.com/image/56b5e649-6b36-45b0-9559-b4bad3896f62.jpg","categories":["Toys","The Collector's Spot","Collectible Model Vehicles"]}
{"sku":"50671790","title":"Marvel Avengers Iron Man Striker 2.4GHz 4.5CH RC Quadcopter","brand":"World Tech Toys","image":"https://example.com/image/0610d9c8-cfc6-4a50-b0aa-209984c9baac.jpg","categories":["Toys","Electronics for Kids"]}