Creating Product Ads via API

Creating Product-Based Ads with Kevel's API

With a product catalog synced to Kevel, it is possible to create product-based ads (PLAs and other formats) via API or UI. This page describes the process using Kevel's API. There are two ways to create product ads via API:

A fixed list of SKUs
A query specifying product characteristics

Product ads can be created at the same time as the Campaign and Flight(s) they belong to using the Create Campaign v2 endpoint (recommended) or separately associated with existing Flights using Kevel's Jobs API, an asynchronous service that handles longer-running batch operations in the system. In both cases, Kevel facilitates the creation of many product ads in a single request and returns a Job ID. The Job ID is used to poll for the status of the Job and when complete a list of Ad IDs is returned. See the Submit Job API documentation for more details.

Aside from the difference in how the products are specified, there are other key differences between the options:

Option #1 supports providing overrides alongside the list of SKUs allowing you to set product bids, for example, and other Ad-level settings on a per-product basis. This is not supported with Option #2.
Option #1 allows you to manually inactivate and activate products via the UI/API. This is not allowed for Option #2, where the Ads are fully managed by the Kevel system.

Create a Campaign with Product Ads

Below is a complete example request to create a Campaign with one Flight filled with product ads for the brand cashewco. See additional sections that follow for more examples and definitions of all fields included in the Jobs object for use within Flights or in standalone calls to the Jobs API.

cURL Example

curl --request POST \
     --url https://api.kevel.co/v2/campaign \
     --header 'X-Kevel-ApiKey: XXX' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '\
{\
  "AdvertiserId": 11111,\
  "Name": "Product Query Example Campaign",\
  "IsActive": true,\
  "Flights": [\
    {\
      "Name": "Product Ad Flight 1",\
      "StartDateISO": "2025-02-06T00:00:00.000Z",\
      "PriorityId": 22222,\
      "GoalType": 8,\
      "Impressions": 1002,\
      "IsActive": true,\
      "RateType": 3,\
      "EndDateISO": "2025-02-28T00:00:00.000Z",\
      "Price": 2,\
      "Keywords": "",\
      "TimeZone": "UTC",\
      "Jobs": [\
        {\
          "TaskId": "create-ads-from-product-query",\
          "TaskArgs": {\
            "AdTemplateUri": "itemdb://12345/101/0e9321b3-1446-47ec-b1d7-705bfb7b3fb5",\
            "ProductQuery": [["brandId","cashewco"]]  
          }\
        }\
      ]\
    }\
  ]\
}  
'

Product Ad Creation Details

Using a Query

Use the create-ads-from-product-query taskId and a ProductQuery. Here's an example:

cURL Example

curl --request POST \
     --url https://api.kevel.co/v1/job/ \
     --header 'X-Kevel-ApiKey: XXX' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '\
{\
  "TaskId": "create-ads-from-product-query",\
  "TaskArgs": {\
    "FlightId": 456789,\
    "AdTemplateUri": "itemdb://12345/101/0e9321b3-1446-47ec-b1d7-705bfb7b3fb5",\
    "ProductQuery": [\
      [["one-of", "kevel/brand-id"], [12345, 12346]],\
      ["kevel/merchant-id", 12347]  
    ]\
  }\
}  
'

Ad Template URI

In most cases, the Ad Template URI will be constant for all create ads from products requests unless a customer is using multiple ad templates (e.g., for different PLA formats or placements).

Example URI: itemdb://12345/101/0e9321b3-1446-47ec-b1d7-705bfb7b3fb5
Structure: itemdb://{network_id}/{ad_templates_table_id}/{template_uuid}

Product Query

The ProductQuery array contains a list of 2-item arrays (called "clauses"), each describing a match criterion. The first item of each clause is an array of the op and the field. The second item of each clause is the value that should be matched.

Supported op values are =, <, >, <=, >=, not=, one-of, present?, matches, and matches-phrase.

Changing Product Queries

The create-ads-from-product-query task can be called multiple times with the same Flight ID, and each call results in an update of the Ads in the Flight.

Example for a Fixed List of SKUs

Use the create-ads-from-products taskId, a list of ItemDB product URIs, and optionally a set of overrides.

cURL Example

curl --request POST \
     --url https://api.kevel.co/v1/job/ \
     --header 'X-Kevel-ApiKey: XXX' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '\
{\
  "TaskId": "create-ads-from-products",\
  "TaskArgs": {\
    "FlightId": 456789,\
    "AdTemplateUri": "itemdb://12345/101/0e9321b3-1446-47ec-b1d7-705bfb7b3fb5",\
    "ProductUris": [\
      "itemdb://12345/100/01936422964",\
      "itemdb://12345/100/01936422955"\
    ],\
    "Overrides": {\
      "itemdb://12345/100/01936422964": [\
        {\
          "target": [\
            "ad",\
            "price"\
          ],\
          "source": "5",\
          "op": "constant"\
        }\
      ],\
      "itemdb://12345/100/01936422955": [\
        {\
          "target": [\
            "ad",\
            "price"\
          ],\
          "source": "3.5",\
          "op": "constant"\
        }\
      ]\
    }\
  }\
}  
'

Native Product Ads

A Native Product Ad (NPA) is a type of ad that allows you to link a single Ad to multiple Products. In most respects, it behaves like a Product Listing Ad (PLA), but with one important difference: instead of creating one Ad per Product, the system will generate a single Ad that aggregates data from all specified Products.

Example to Create a Native Product Ad via the Jobs API

curl --request POST \
     --url https://api.kevel.co/v1/job/ \
     --header 'X-Kevel-ApiKey: XXX' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '\
{\
  "TaskId": "create-native-product-ad",\
  "TaskArgs": {\
    "FlightId": 456789,\
    "AdTemplateUri": "itemdb://12345/101/f3406d28-7cc9-41e2-abb1-a46b750d3861",\
    "ProductUris": [\
      "itemdb://12345/100/01936422964",\
      "itemdb://12345/100/01936422955"\
    ],\
    "Overrides": {\
      "global": [\
        {\
          "source": "My Native Product Ad",\
          "target": ["creative", "Title"],\
          "op": "constant"\
        },\
        {\
          "source": "https://mycdn.com/productcollage.jpg",\
          "target": ["creative", "TemplateValues", "ctmain_image"],\
          "op": "constant"\
        }\
      ]\
    }\
  }\
}  
'

Note: the Overrides structure matches Overrides for the create-ads-from-products, but only a single key "global" is supported, as opposed to unlimited product-uris.