Sync Items to Catalogs

Sharing Catalog Data with Kevel

Catalog data should be shared in a Newline Delimited JSON (NDJSON) file. Each line in the source file needs to be a JSON object representing a single item. During testing and development (Phase 1 below), Kevel can accommodate receiving catalog data in other formats and outside of direct integrations.

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, you will configure an integration using Kevel's Create Ingest URL endpoint. The Create Ingest URL endpoint allows you to push source data directly to Kevel storage using the same authentication as other Kevel APIs. When you create a new ingest URL, Kevel will return a signed URL for an Amazon S3 bucket where a file can be uploaded.

Kevel will monitor this S3 bucket for new files. Once Kevel determines that a new file has been uploaded, 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>.ndjson e.g. products.ndjson or categories.ndjson.

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

Kevel's Create Ingest URL endpoint will automatically prepend a datetime string to the provided file name based on the time the ingest URL is created.

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"]}