Keywords - Criteo Docs

Introduction

The keywords endpoints allows you to control your Onsite Sponsored Products line item by providing visibility to users on what keyword(s) are applied to line items. This allows to determine which keyword(s) to target positively or negatively.The endpoint can also provide keyword bidding capabilities to optimize line items based on relevant keywords.Visit the Onsite Sponsored Products page for a complete summary of Criteo’s keyword service.

The search endpoint evaluates each query against product eligibility rules configured for the current page or context.

Queries may reference products that are not eligible to be displayed on the page. These products will be excluded from the search results.
Queries may also match products that are eligible to be displayed. These products can be returned in the response.

As a result, the response may not include all products relevant to the query—only those that meet the page’s eligibility criteria.

Endpoints

Verb	Endpoint	Description
GET	`/line-items/{lineItemId}/keywords`	Retrieve a set of positive and negative keywords for a line item
GET	`/line-items/{lineItemId}/keywords/recommended`	Retrieve a collection of recommended keywords for a line item
POST	`/line-items/{lineItemId}/keywords/add-remove`	Add or remove keywords from a line item
POST	`/line-items/{lineItemId}/keywords/set-bid`	Set a bid override at keyword level

Keyword Attributes

Attribute	Data Type	Description
`id`*	string	Line Item ID, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N
`keywords`*	object	Keywords structure, indexed by normalized keyword phrases each of them containing structure of: `matchType` `bid` `inputKeywords` `reviewState` `createdAt` `updatedAt`
`matchType`*	enum	Matching algorithm type to be used when comparing this keyword with shopper search phrases. Accepted values: `PositiveExactMatch`: normalized keyword is an exact match for the normalized search phrase bid `NegativeExactMatch`: normalized keyword is an exact match for the normalized search phrase do not bid `NegativeBroadMatch`: normalized keyword is a substring of the normalized search phrase do not bid Default:`PositiveExactMatch` Writeable? N / Nullable? N
`reviewState`	enum	Status of Keyword review, only applicable for`PositiveExactMatch`match type keywords. Keywords not reviewed by the automatic keyword service will be reviewed and approved by the retailer. Accepted values: `InReview`: keyword has been submitted manually, and the review is still pending `Approved`: keyword was approved manually `AutoApproved`: keyword was approved automatically `Rejected`: keyword was rejected manually `AutoRejected`: keyword was rejected automatically `Recommended`: keyword was recommended by our keyword model Default:`InReview` Writeable? N / Nullable? N
`bid`	decimal	The bid override for the positive keyword. The keyword will use the default line item bid if the value is`null`. The currency of the bid is the default currency for the retailer. The bid can be applied to both manual keywords and recommended keywords. Accepted values: retailer’s`minBid`≤`bid`≤ line-item’s`maxBid`, available in the endpoints detailed inCatalog EndpointsandOnsite Display Line Items, respectively Default:`null` Writeable? Y / Nullable? Y
`isDeleted`	boolean	Control flag to add or remove the keyword from the line-item Accepted values:`true`/`false` Writeable? N / Nullable? N
`inputKeywords`*	object	Keywords structure associated with line-item containing normalized keyword phrases and organized by match type. Parameters: `positiveExact`: list of supplied positive exact phrases `negativeExact`: list of supplied negative exact phrases `negativeBroad`: list of supplied negative broad phrases
`phrase`	string	Raw text of the keyword to be added or removed Accepted values: up to 255-chars string Writeable? Y / Nullable? N
`createdAt`	timestamp	Timestamp when keyword was configured in the line-item (or recommended to line-item) Accepted values:`yyyy-mm-ddThh:mm:ss`(inISO-8601) Writeable? N / Nullable? N
`updatedAt`	timestamp	Timestamp when keyword was last modified in the line-item (or recommended to line-item) Accepted values:`yyyy-mm-ddThh:mm:ss`(inISO-8601) Writeable? N / Nullable? N

*Required

Field Definitions

Writeable (Y/N): Indicates if the field can be modified in requests.
Nullable (Y/N): Indicates if the field can accept null/empty values.
Primary Key: A unique, immutable identifier of the entity, generated internally by Criteo. Primary keys are typically ID fields (e.g., retailerId, campaignId, lineItemId) and are usually required in the URL path.

Get Keywords by Line Item

Sample Request

curl -L -X GET "https://api.criteo.com/{version}/retail-media/line-items/358669652976373760/keywords" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>" \
    -H "Accept: application/json"

import http.client

conn = http.client.HTTPSConnection("api.criteo.com")

headers = {
    'Authorization': 'Bearer <MY_ACCESS_TOKEN>',
    'Accept': 'application/json'
}

conn.request("GET", "/{version}/retail-media/line-items/358669652976373760/keywords", headers=headers)

res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

Request request = new Request.Builder()
    .url("https://api.criteo.com/{version}/retail-media/line-items/358669652976373760/keywords")
    .method("GET", null)
    .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
    .addHeader("Accept", "application/json")
    .build();

Response response = client.newCall(request).execute();

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/{version}/retail-media/line-items/358669652976373760/keywords');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
    'follow_redirects' => TRUE
));
$request->setHeader(array(
    'Authorization' => 'Bearer <MY_ACCESS_TOKEN>',
    'Accept' => 'application/json'
));

try {
    $response = $request->send();
    if ($response->getStatus() == 200) {
        echo $response->getBody();
    } else {
        echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase();
    }
} catch(HTTP_Request2_Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

Sample Response

{
    "data": {
        "id": "358669652976373760",
        "type": "RetailMediaKeywordsModel",
        "attributes": {
            "keywords": {
                "vegetable": {
                    "matchType": "NegativeBroadMatch",
                    "bid": null,
                    "inputKeywords": {
                        "negativeBroad": [
                            "vegetable"
                        ],
                        "negativeExact": [],
                        "positiveExact": []
                    },
                    "createdAt": "2025-01-01T00:00:00",
                    "updatedAt": "2025-01-01T00:00:00"
                },
                "tomato": {
                    "matchType": "NegativeExactMatch",
                    "bid": null,
                    "inputKeywords": {
                        "negativeBroad": [],
                        "negativeExact": [
                            "tomatoes"
                        ],
                        "positiveExact": []
                    },
                    "createdAt": "2025-01-01T00:00:00",
                    "updatedAt": "2025-01-01T00:00:00"
                },
                "strawberry": {
                    "matchType": "NegativeExactMatch",
                    "bid": null,
                    "inputKeywords": {
                        "negativeBroad": [],
                        "negativeExact": [
                            "strawberry"
                        ],
                        "positiveExact": []
                    },
                    "createdAt": "2025-01-01T00:00:00",
                    "updatedAt": "2025-01-01T00:00:00"
                },
                "broccoli": {
                    "matchType": "NegativeExactMatch",
                    "bid": null,
                    "inputKeywords": {
                        "negativeBroad": [],
                        "negativeExact": [
                            "broccoli"
                        ],
                        "positiveExact": []
                    },
                    "createdAt": "2025-01-01T00:00:00",
                    "updatedAt": "2025-01-01T00:00:00"
                },
                "banana": {
                    "matchType": "NegativeExactMatch",
                    "bid": null,
                    "inputKeywords": {
                        "negativeBroad": [],
                        "negativeExact": [
                            "banana"
                        ],
                        "positiveExact": []
                    },
                    "createdAt": "2025-01-01T00:00:00",
                    "updatedAt": "2025-01-01T00:00:00"
                },
                "pasta": {
                    "reviewState": "Approved",
                    "matchType": "PositiveExactMatch",
                    "bid": null,
                    "inputKeywords": {
                        "negativeBroad": [],
                        "negativeExact": [],
                        "positiveExact": [
                            "pasta"
                        ]
                    },
                    "createdAt": "2025-01-01T00:00:00",
                    "updatedAt": "2025-01-01T00:00:00"
                },
                "milk": {
                    "reviewState": "Approved",
                    "matchType": "PositiveExactMatch",
                    "bid": 0.50,
                    "inputKeywords": {
                        "negativeBroad": [],
                        "negativeExact": [],
                        "positiveExact": [
                            "milk"
                        ]
                    },
                    "createdAt": "2025-01-01T00:00:00",
                    "updatedAt": "2025-01-01T00:00:00"
                },
                "juice": {
                    "reviewState": "Approved",
                    "matchType": "PositiveExactMatch",
                    "bid": null,
                    "inputKeywords": {
                        "negativeBroad": [],
                        "negativeExact": [],
                        "positiveExact": [
                            "juice"
                        ]
                    },
                    "createdAt": "2025-01-01T00:00:00",
                    "updatedAt": "2025-01-01T00:00:00"
                },
                "egg": {
                    "reviewState": "Approved",
                    "matchType": "PositiveExactMatch",
                    "bid": 0.50,
                    "inputKeywords": {
                        "negativeBroad": [],
                        "negativeExact": [],
                        "positiveExact": [
                            "eggs"
                        ]
                    },
                    "createdAt": "2025-01-01T00:00:00",
                    "updatedAt": "2025-01-01T00:00:00"
                },
                "fruit": {
                    "matchType": "NegativeBroadMatch",
                    "bid": null,
                    "inputKeywords": {
                        "negativeBroad": [
                            "fruits"
                        ],
                        "negativeExact": [],
                        "positiveExact": []
                    },
                    "createdAt": "2025-01-01T00:00:00",
                    "updatedAt": "2025-01-01T00:00:00"
                }
            }
        }
    },
    /* omitted if no errors */
    "errors": [],
    /* omitted if no warnings */
    "warnings": []
}

Get Recommended Keywords by Line Item

This endpoint retrieves a collection of recommended keywords for a line item, created automatically by our keyword models.

Only the top 100 keywords will be returnedAutomatic recommended keywords can change day to day, as are determined based on click volumes by users on Retailer’s environment. Although significant changes are not expected, it is possible that the long tail of the top 100 keywords change slightly

Sample Request

curl -L -X GET "https://api.criteo.com/{version}/retail-media/line-items/358669652976373760/keywords/recommended" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>" \
    -H "Accept: application/json"

import http.client

conn = http.client.HTTPSConnection("api.criteo.com")

headers = {
    'Authorization': 'Bearer <MY_ACCESS_TOKEN>',
    'Accept': 'application/json'
}

conn.request("GET", "/{version}/retail-media/line-items/358669652976373760/keywords/recommended", headers=headers)

res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

Request request = new Request.Builder()
    .url("https://api.criteo.com/{version}/retail-media/line-items/358669652976373760/keywords/recommended")
    .method("GET", null)
    .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
    .addHeader("Accept", "application/json")
    .build();

Response response = client.newCall(request).execute();

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/{version}/retail-media/line-items/358669652976373760/keywords/recommended');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
    'follow_redirects' => TRUE
));
$request->setHeader(array(
    'Authorization' => 'Bearer <MY_ACCESS_TOKEN>',
    'Accept' => 'application/json'
));

try {
    $response = $request->send();
    if ($response->getStatus() == 200) {
        echo $response->getBody();
    } else {
        echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase();
    }
} catch(HTTP_Request2_Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

Sample Response

{
    "data": {
        "type": "RecommendedKeywords",
        "attributes": {
            "keywords": {
                "bar sound": {
                    "reviewState": "AutoApproved",
                    "matchType": "PositiveExactMatch",
                    "bid": 1.0,
                    "inputKeywords": {
                        "positiveExact": [
                            "bar sound",
                            "sound bar",
                            "sound-bar",
                            "sound bars",
                            "sounds bar"
                        ]
                    },
                    "createdAt": "2025-01-01T07:00:00",
                    "updatedAt": "2025-01-01T08:00:00"
                },
                "dolby soundbar": {
                    "reviewState": "Recommended",
                    "matchType": "PositiveExactMatch",
                    "bid": null,
                    "inputKeywords": {
                        "positiveExact": [
                            "dolby soundbars",
                            "soundbar dolby"
                        ]
                    },
                    "createdAt": "2025-01-01T07:00:00",
                    "updatedAt": "2025-01-01T08:00:00"
                },
                "atmos": {
                    "matchType": "NegativeBroad",
                    "inputKeywords": {
                        "negativeBroad": [
                            "atmos"
                        ]
                    },
                    "createdAt": "2025-01-01T07:00:00",
                    "updatedAt": "2025-01-01T08:00:00"
                }
            },
            "recommended": [
                "atmos",
                "dolby soundbars",
                "sound bar",
                "sound bars",
                "soundbar dolby"
            ]
        }
    },
    /* omitted if no errors */
    "errors": [],
    /* omitted if no warnings */
    "warnings": []
}

Add or remove Keyword from Line Item

Negative Targeting v1The negative keyword targeting in this API will eventually replace the Negative Keyword Targeting endpoints. You may continue using those endpoints without disrupting your services. We recommend reviewing and testing the new Keyword endpoints to prepare for a future migration to these new endpoints.

Sample Request

curl -L -X POST "https://api.criteo.com/{version}/retail-media/line-items/358669652976373760/keywords/add-remove" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
            "data": {
                "id": "358669652976373760",
                "type": "RetailMediaKeywordAddRemove",
                "attributes": {
                    "keywords": [
                        {
                            "phrase": "cookies and bread",
                            "matchType": "PositiveExactMatch",
                            "isDeleted": "false"
                        },
                        {
                            "phrase": "raspberry",
                            "matchType": "NegativeExactMatch",
                            "isDeleted": "false"
                        },
                        {
                            "phrase": "potatoes",
                            "matchType": "NegativeExactMatch",
                            "isDeleted": "true"
                        }
                    ]
                }
            }
        }'

import http.client
import json

conn = http.client.HTTPSConnection("api.criteo.com")
payload = json.dumps({
    "data": {
        "id": "358669652976373760",
        "type": "RetailMediaKeywordAddRemove",
        "attributes": {
            "keywords": [
                {
                    "phrase": "cookies and bread",
                    "matchType": "PositiveExactMatch",
                    "isDeleted": "false"
                },
                {
                    "phrase": "raspberry",
                    "matchType": "NegativeExactMatch",
                    "isDeleted": "false"
                },
                {
                    "phrase": "potatoes",
                    "matchType": "NegativeExactMatch",
                    "isDeleted": "true"
                }
            ]
        }
    }
})

headers = {
    'Authorization': 'Bearer <MY_ACCESS_TOKEN>',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
}

conn.request("POST", "/{version}/retail-media/line-items/358669652976373760/keywords/add-remove", payload, headers)

res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

MediaType mediaType = MediaType.parse("application/json");

RequestBody body = RequestBody.create(mediaType, """
{
    "data": {
        "id": "358669652976373760",
        "type": "RetailMediaKeywordAddRemove",
        "attributes": {
            "keywords": [
                {
                    "phrase": "cookies and bread",
                    "matchType": "PositiveExactMatch",
                    "isDeleted": "false"
                },
                {
                    "phrase": "raspberry",
                    "matchType": "NegativeExactMatch",
                    "isDeleted": "false"
                },
                {
                    "phrase": "potatoes",
                    "matchType": "NegativeExactMatch",
                    "isDeleted": "true"
                }
            ]
        }
    }
}
""");

Request request = new Request.Builder()
    .url("https://api.criteo.com/{version}/retail-media/line-items/358669652976373760/keywords/add-remove")
    .method("POST", body)
    .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
    .addHeader("Content-Type", "application/json")
    .addHeader("Accept", "application/json")
    .build();

Response response = client.newCall(request).execute();

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/{version}/retail-media/line-items/358669652976373760/keywords/add-remove');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
    'follow_redirects' => TRUE
));
$request->setHeader(array(
    'Authorization' => 'Bearer <MY_ACCESS_TOKEN>',
    'Content-Type' => 'application/json',
    'Accept' => 'application/json'
));

$request->setBody(json_encode(array(
    "data" => array(
        "id" => "358669652976373760",
        "type" => "RetailMediaKeywordAddRemove",
        "attributes" => array(
            "keywords" => array(
                array(
                    "phrase" => "cookies and bread",
                    "matchType" => "PositiveExactMatch",
                    "isDeleted" => "false"
                ),
                array(
                    "phrase" => "raspberry",
                    "matchType" => "NegativeExactMatch",
                    "isDeleted" => "false"
                ),
                array(
                    "phrase" => "potatoes",
                    "matchType" => "NegativeExactMatch",
                    "isDeleted" => "true"
                )
            )
        )
    )
), JSON_PRETTY_PRINT));

try {
    $response = $request->send();
    if ($response->getStatus() == 200) {
        echo $response->getBody();
    } else {
        echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase();
    }
} catch(HTTP_Request2_Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

Sample Response
200 successful status will return an empty object array

{}

Set bid on Keyword

Bids can be set on a keyword at any time, even when the keywords are still in theInReview state Sample Request

curl -L -X POST "https://api.criteo.com/{version}/retail-media/line-items/358669652976373760/keywords/set-bid" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
            "data": {
                "type": "RetailMediaKeywordsSetBid",
                "id": "358669652976373760",
                "attributes": {
                    "keywords": [
                        {"phrase": "eggs", "bid": "0.50"},
                        {"phrase": "milk", "bid": "0.50"}
                    ]
                }
            }
        }'

import http.client
import json

conn = http.client.HTTPSConnection("api.criteo.com")
payload = json.dumps({
    "data": {
        "id": "358669652976373760",
        "type": "RetailMediaKeywordsSetBid",
        "attributes": {
            "keywords": [
                {"phrase": "eggs", "bid": "0.50"},
                {"phrase": "milk", "bid": "0.50"}
            ]
        }
    }
})

headers = {
    'Content-Type': 'application/json',
    'Accept': 'text/plain',
    'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}
conn.request("POST", "/{version}/retail-media/line-items/358669652976373760/keywords/set-bid", payload, headers)

res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

MediaType mediaType = MediaType.parse("application/json");

RequestBody body = RequestBody.create(mediaType, """
{
    "data": {
        "id": "358669652976373760",
        "type": "RetailMediaKeywordsSetBid",
        "attributes": {
            "keywords": [
                {"phrase": "eggs", "bid": "0.50"},
                {"phrase": "milk", "bid": "0.50"}
            ]
        }
    }
}
""");

Request request = new Request.Builder()
    .url("https://api.criteo.com/{version}/retail-media/line-items/358669652976373760/keywords/set-bid")
    .method("POST", body)
    .addHeader("Content-Type", "application/json")
    .addHeader("Accept", "application/json")
    .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
    .build();

Response response = client.newCall(request).execute();
``

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/{version}/retail-media/line-items/358669652976373760/keywords/set-bid');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
    'follow_redirects' => TRUE
));
$request->setHeader(array(
    'Content-Type' => 'application/json',
    'Accept' => 'text/plain',
    'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
));

$request->setBody(json_encode(array(
    "data" => array(
        "id" => "358669652976373760",
        "type" => "RetailMediaKeywordsSetBid",
        "attributes" => array(
            "keywords" => array(
                array("phrase" => "eggs", "bid" => "0.50"),
                array("phrase" => "milk", "bid" => "0.50")
            )
        )
    )
), JSON_PRETTY_PRINT));

try {
    $response = $request->send();
    if ($response->getStatus() == 200) {
        echo $response->getBody();
    } else {
        echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase();
    }
} catch(HTTP_Request2_Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

Sample Response 200 successful status will return an empty object array.

{}

Responses

Response	Description
🔵`200`OK	Call completed with success
🔵`201`OK	The call to add/remove the keyword from the line item was executed successfully The call to set keyword bid to the line item was executed successfully
🔴`400` Bad Request	Setting a bid for a positive keyword that doesn’t exist on the line item. Error Message `“On line item {lineItemId} normalized keyword “{keyword}“/en_US not found”` Setting a keyword bid above the line-item`maxBid`value will result in a 400 bad request error message. In this example, the`maxBid`value is at least 0.40. Error Message `“Invalid bid value, bid greater than maximum of 1.00000000, found for keyword: ”` Setting a keyword bid below the retailer`minBid`value will result in a 400 bad request error message. In this example, the`minBid`value is at least 0.40. Error Message `“Invalid bid value, bid less than minimum of 0.4000, found for keyword: “`

Response

Description

🔵200OK

Call completed with success

🔵201OK

The call to add/remove the keyword from the line item was executed successfully
The call to set keyword bid to the line item was executed successfully

🔴400

Bad Request

Setting a bid for a positive keyword that doesn’t exist on the line item.

Error Message

“On line item {lineItemId} normalized keyword “{keyword}“/en_US not found”

Setting a keyword bid above the line-itemmaxBidvalue will result in a 400 bad request error message. In this example, themaxBidvalue is at least 0.40.

Error Message

“Invalid bid value, bid greater than maximum of 1.00000000, found for keyword: ”

Setting a keyword bid below the retailerminBidvalue will result in a 400 bad request error message. In this example, theminBidvalue is at least 0.40.

Error Message

“Invalid bid value, bid less than minimum of 0.4000, found for keyword: “

What’s next

Keyword Review

​Introduction

​Endpoints

​Keyword Attributes

​Get Keywords by Line Item

​Get Recommended Keywords by Line Item

​Add or remove Keyword from Line Item

​Set bid on Keyword

​Responses

​What’s next

Introduction

Endpoints

Keyword Attributes

Get Keywords by Line Item

Get Recommended Keywords by Line Item

Add or remove Keyword from Line Item

Set bid on Keyword

Responses

What’s next