Sync Items to Catalogs

Kevel Catalogs allow you to manage and sync product data used to power your retail media ads. You can share catalog data either through file-based ingestion or via the new Catalog Management API, depending on your integration needs.

Options for Sharing Catalog Data

Kevel now supports two primary methods for syncing catalog data:

1. Flat File Uploads (existing method) — Send a complete NDJSON file of your catalog using the Create Ingest URL endpoint.
2. Catalog Management API (new) — Manage items programmatically through the Catalog and Catalog Item endpoints.
   • List all catalogs in your network and view the items they contain.
   • Create or update product items in batches of 1–1000.
   • Perform partial updates (e.g., frequent in-stock/out-of-stock changes) without re-uploading the full catalog.
   • See the OpenAPI spec for full details.

Phase 1: Initial Import

To begin your Catalog integration, work with your Kevel account team to send a one-time export of your catalog. This initial import ensures Kevel has all the data needed to populate the catalog and allows your AdOps team to test ad creation and product linkages.

You can provide this data via either:

• A flat file upload (recommended for initial imports), or
• The Catalog Management API (for customers who already have API-based product management capabilities).

Phase 2: Continuous Sync

Once your initial import is complete, you can choose how to maintain your Catalog going forward.

Option A: File-Based Sync (Flat File Uploads)

The Create Ingest URL endpoint allows you to push source data to Kevel via a signed Amazon S3 URL. Once a new file is uploaded, Kevel automatically triggers ingestion and updates your Catalog and any Ads linked to those items.

Syncing Frequency

Kevel supports daily catalog updates, though more frequent uploads can be arranged based on catalog size and use case.

File Naming and Compression

Use the format <item-type>.ndjson (e.g., products.ndjson).
Compressed uploads are supported and recommended, e.g. products.ndjson.gz.
Kevel automatically prepends a timestamp when you create an ingest URL.

Option B: API-Based Sync (Catalog Management API)

For real-time or high-frequency updates, use the Catalog Management API.

Available Endpoints

• List Catalogs: Retrieve all catalogs in your network.
• List Items: Get all product items for a specific catalog.
• Create/Update Items: Batch up to 1000 product items per request.
• Partial Updates: Update only the fields that have changed, such as price, availability, or rating, without sending the full item payload.

Example Use Cases

• Hourly stock or price updates
• Rapid onboarding of new products
• Lightweight product data corrections

Example: Create or Update Catalog Items (cURL)

curl -X POST "https://api.kevel.co/catalog/v1/catalogs/{catalogId}/items/batch" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -d '{
    "Items": [
      {
        "sku": "SKU-123",
        "title": "Organic Almond Butter",
        "price": 9.99,
        "inStock": true
      },
      {
        "sku": "SKU-456",
        "title": "Cashew Trail Mix",
				"price": 14.99,
        "inStock": false
      }
    ]
  }'

This request creates or updates two catalog items. Partial payloads (e.g., sending only inStock or price) are supported via the PATCH endpoint.

Catalog Item Structure

Each item must include a unique ID (as defined by the Catalog’s ID Key). All other fields may vary depending on your schema.

*Required field

When syncing via flat file, you must include all attributes for each item.
When syncing via API, you can submit partial payloads containing only updated fields.

Validation

Kevel requires only the unique ID for ingestion. Other attributes are not validated for type or presence; if a search key’s value does not match its defined type, Kevel will store the data but exclude that attribute from indexing.

Example NDJSON Feed (File Upload Method)

{"title": "PROZIS Whey Protein Fusion Vanilla flavour (900g)", "image": "https://static.adzerk.net/Advertisers/vanilla_protein.png", "sku": 1, "brand_name": "Prozis", "brand_id": 2764717, "categories": [1, 3], "main_category_id": 3, "main_category_name": "Protein Powders", "star_rating": 4.7, "price": 52}
{"title": "PROZIS Snack Zero (35g)", "image": "https://static.adzerk.net/Advertisers/12942cbf7cb84e91965c491bbb0abcff.png", "sku": 2, "brand_name": "Prozis", "brand_id": 2764717, "categories": [2, 4], "main_category_id": 4, "main_category_name": "Protein Bars", "star_rating": 4.2, "price": 3}
{"title": "Best snacks with almond pack", "image": "https://static.adzerk.net/Advertisers/almond_pack.png", "sku": 3, "brand_name": "Hazel", "brand_id": 2764718, "categories": [2, 5], "main_category_id": 5, "main_category_name": "Raw Bites", "star_rating": 3.5, "price": 7}

Choosing Between File Uploads and the Catalog Management API