Targeting

Overview

Availability: Available Targeting defines where and how a line item can serve. Each target has a target type and type-specific details. The Get Targets endpoint retrieves the ManualKeyword, PageType, and Category targets configured for a line item. The Create Targets endpoint creates ManualKeyword, PageType, and Category targets for a line item. The Update Targets and Delete Targets endpoints modify or remove those targets in bulk.

Geography targets are supported by the API but not yet documented here.

Targeting Types

All endpoints use Target resources. A target’s targetType determines the one target details object it contains. A target must contain exactly one details object that matches its targetType. Bid multipliers are supported only on non-negative targets. For ManualKeyword targets, bid multipliers are matched using the retailer’s default language. Create, Update, and Delete requests can contain up to 100 targets, may mix target types, and cannot contain the same target more than once.

Shared Target Attributes

Attribute	Type	Description
`targetType`	enum	Target type: `ManualKeyword`, `PageType`, or `Category`.
`negative`	boolean	Whether the target excludes matching inventory.
`bidMultiplier`	number or null	Bid multiplier for a non-negative target.
`approvalStatus`	enum	Response-only approval status: `Unknown`, `Approved`, `AutoApproved`, `InReview`, `Rejected`, `AutoRejected`, or `Unsubmitted`.

Target Type Details

Target type	Details object	Attributes and options
`ManualKeyword`	`manualKeywordTargetDetails`	`keywordInput` (string): manual keyword used for targeting. `matchType` (enum): `Exact` or `Broad`.
`PageType`	`pageTypeTargetDetails`	`pageType` (enum): `Unknown`, `Search`, `Home`, `Browse`, `Checkout`, `Category`, `ProductDetail`, `Confirmation`, `Merchandising`, `Deals`, `Favorites`, `SearchBar`, `CategoryMenu`, or `AiAssistant`.
`Category`	`categoryTargetDetails`	`categoryId` (string): category used for targeting. `includeChildren` (boolean): whether the target includes child categories.

Target Request Attributes

Create, Update, and Delete use the same request shape:

Attribute	Type	Required	Description
`lineItemId`	string	Yes	Line item ID in the URL path.
`data`	array	No	Target resources to create, update, or delete.
`data[].type`	string	No	Resource type. Set this value to `Target`.
`data[].attributes.targetType`	enum	Yes	Target type: `ManualKeyword`, `PageType`, or `Category`.
`data[].attributes.negative`	boolean	Create: Yes; Update: No; Delete: for `ManualKeyword` and `Category`	Whether the target is negative. It also identifies existing ManualKeyword and Category targets.
`data[].attributes.bidMultiplier`	number or null	No	Optional for Create and Update. Supply it on Update to change or clear the multiplier. Delete does not use it.
`data[].attributes.<details-object>`	object	Yes	Details object matching `targetType`. It identifies the target for Update and Delete. See Target type details.

Partial Success Across Target Types

All target endpoints support partial success by target type. An endpoint can return 200 OK even when one target type fails; inspect both errors and warnings before treating the response as complete.

Identifying Targets for Update and Delete

To update or delete targets, copy the target resources from data in a Get Targets response into the request’s data array. An Update request can change the mutable fields listed below. A Delete request can use the fetched target resources without changes. The response-only approvalStatus field can remain in a copied resource; it does not change approval status.

Target type	Fields that identify the target	Fields that can be updated
`ManualKeyword`	`targetType`, `manualKeywordTargetDetails.keywordInput`, `manualKeywordTargetDetails.matchType`, and `negative`	`bidMultiplier`
`PageType`	`targetType` and `pageTypeTargetDetails.pageType`	`bidMultiplier`
`Category`	`targetType`, `categoryTargetDetails.categoryId`, and `negative`	`categoryTargetDetails.includeChildren` and `bidMultiplier`

The identity fields cannot be changed with Update. To change one, delete the existing target and create a new one.

Endpoints

Method	Endpoint	Description
GET	`/retail-media/line-items/{lineItemId}/targets`	Retrieves targets for a line item
POST	`/retail-media/line-items/{lineItemId}/targets/create`	Creates targets for a line item
POST	`/retail-media/line-items/{lineItemId}/targets/update`	Updates targets for a line item
POST	`/retail-media/line-items/{lineItemId}/targets/delete`	Deletes targets from a line item

Get Targets

Retrieves the ManualKeyword, PageType, and Category targets configured for the specified line item. Use offset and limit to page through the targets retrieved successfully. Prerequisites:

OAuth 2.0 bearer token with the RetailMedia_Campaign_Read scope
Access to the requested line item

Request Attributes

Attribute	Type	Required	Description
`lineItemId`	string	Yes	Line item ID. Provided in the URL path.
`offset`	integer	No	Zero-based offset applied to the targets retrieved successfully. Defaults to `0`.
`limit`	integer	No	Maximum number of targets returned. Defaults to `500`; maximum `50,000`.

Response Attributes

Attribute	Type	Description
`metadata.count`	integer	Total number of targets retrieved successfully before pagination is applied.
`metadata.offset`	integer	Zero-based offset applied to the returned targets.
`metadata.limit`	integer	Maximum number of targets requested for the page.
`data`	array	Paginated target resources.
`errors`	array	Errors encountered while retrieving targets. This array is not paginated.
`warnings`	array	Warnings encountered while retrieving targets. This array is not paginated.

Each resource in data is a Target. See Targeting types for its shared attributes and the details object for each target type. Sample Request

curl -L -X GET \
  'https://api.criteo.com/experimental/retail-media/line-items/1234567890123456789/targets?offset=0&limit=500' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>'

Sample Response — 200 OK

{
  "metadata": {
    "count": 3,
    "offset": 0,
    "limit": 500
  },
  "data": [
    {
      "type": "Target",
      "attributes": {
        "targetType": "ManualKeyword",
        "negative": false,
        "bidMultiplier": 1.25,
        "approvalStatus": "Approved",
        "manualKeywordTargetDetails": {
          "keywordInput": "trail running shoes",
          "matchType": "Exact"
        }
      }
    },
    {
      "type": "Target",
      "attributes": {
        "targetType": "PageType",
        "negative": false,
        "bidMultiplier": null,
        "approvalStatus": "AutoApproved",
        "pageTypeTargetDetails": {
          "pageType": "Search"
        }
      }
    },
    {
      "type": "Target",
      "attributes": {
        "targetType": "Category",
        "negative": false,
        "bidMultiplier": 1.5,
        "approvalStatus": "Approved",
        "categoryTargetDetails": {
          "categoryId": "1001",
          "includeChildren": true
        }
      }
    }
  ],
  "warnings": [],
  "errors": []
}

Responses

Status	Code	Description
`200 OK`		All supported target types were retrieved, or the request partially succeeded for the available target types. Always inspect `errors` and `warnings`; a `200` response can contain only a subset of the supported target types.
`400 Bad Request`	`targets-max-page-size-exceeded`	The requested `limit` is greater than `50,000`. Reduce `limit` to `50,000` or less.
`401 Unauthorized`		The access token is missing, invalid, or expired. Obtain a valid access token and retry the request.
`403 Forbidden`		The caller lacks Campaign Read permission or access to the requested line item. Verify the bearer token includes the `RetailMedia_Campaign_Read` scope and the caller has access to the requested line item.
`500 Internal Server Error`		An unexpected internal error prevented the endpoint from completing the request. Retry the request. If the failure persists, use the response trace ID when contacting support.
`502 Bad Gateway`		Retrieval failed for every supported target type. Retry the request. If the failure persists, use the response trace ID when contacting support.

Partial Success

If one or more target types are available, Get returns 200 OK with those targets in data and describes any unavailable target types in errors. If retrieval fails for every supported target type, it returns a non-200 response with no target data. The metadata.count value is the total number of targets retrieved successfully before pagination. If offset is greater than or equal to metadata.count, data is empty. The errors and warnings arrays apply to the full response and are not affected by pagination. The following example shows a successful response when ManualKeyword targets are unavailable. The response still includes the available PageType and Category targets. Clients should process those targets and inspect errors before treating the response as complete. ManualKeyword targets unavailable — 200 OK

{
  "metadata": {
    "count": 2,
    "offset": 0,
    "limit": 500
  },
  "data": [
    {
      "type": "Target",
      "attributes": {
        "targetType": "PageType",
        "negative": false,
        "bidMultiplier": null,
        "approvalStatus": "AutoApproved",
        "pageTypeTargetDetails": {
          "pageType": "Home"
        }
      }
    },
    {
      "type": "Target",
      "attributes": {
        "targetType": "Category",
        "negative": false,
        "bidMultiplier": 1.2,
        "approvalStatus": "Approved",
        "categoryTargetDetails": {
          "categoryId": "1002",
          "includeChildren": false
        }
      }
    }
  ],
  "warnings": [],
  "errors": [
    {
      "traceId": "example-trace-id",
      "type": "availability",
      "code": "keyword-targets-unavailable",
      "detail": "Failed to fetch keyword targets."
    }
  ]
}

Create Targets

Creates ManualKeyword, PageType, and Category targets for the specified line item. Prerequisites:

OAuth 2.0 bearer token with the RetailMedia_Campaign_Manage scope
Access to the requested line item

See Target request attributes for the request fields.

Examples

Successful Request

curl -L -X POST \
  'https://api.criteo.com/experimental/retail-media/line-items/1234567890123456789/targets/create' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "data": [
      {
        "type": "Target",
        "attributes": {
          "targetType": "PageType",
          "negative": false,
          "bidMultiplier": null,
          "pageTypeTargetDetails": {
            "pageType": "Search"
          }
        }
      }
    ]
  }'

Successful Response — 200 OK

{
  "data": [
    {
      "type": "Target",
      "attributes": {
        "targetType": "PageType",
        "negative": false,
        "bidMultiplier": null,
        "approvalStatus": "AutoApproved",
        "pageTypeTargetDetails": {
          "pageType": "Search"
        }
      }
    }
  ],
  "warnings": [],
  "errors": []
}

Responses

Status	Code	Description
`200 OK`		The request succeeded completely or partially across target types. Process the created targets in `data` and inspect `errors` and `warnings`.
`400 Bad Request`	`targets-max-elements-exceeded`	The request contains more than 100 targets.
`400 Bad Request`	`unknown-target-type`	A target type is not supported.
`401 Unauthorized`		The access token is missing, invalid, or expired.
`403 Forbidden`		The caller lacks Campaign Manage permission or access to the requested line item.
`500 Internal Server Error`		An unexpected internal error prevented the endpoint from completing the request. Retry the request. If the failure persists, contact support.
`502 Bad Gateway`		The endpoint could not complete target creation. Retry the request. If the failure persists, contact support.

Validation Errors

Create responses can include the following application-level validation errors in errors:

Code	Description
`invalid-external-line-item-id`	The line item ID is invalid.
`target-details-mismatch`	A target’s details object does not match its declared target type.
`invalid-category-id`	A Category target’s category ID is not a number.
`unknown-page-type`	A PageType target’s page type is not supported.
`match-type-keywords-count-above-max`	Creating the targets would exceed the limit for a keyword match type.
`manual-positive-keywords-count-above-max`	Creating the targets would exceed the limit for positive ManualKeyword targets.
`non-exact-match-type-for-onsite-display`	A ManualKeyword target uses a match type not supported for an Onsite Display line item.
`duplicate-target-in-request`	The request contains the same target more than once.
`keyword-input-length-above-max`	A ManualKeyword target’s keyword input exceeds the supported length.
`empty-target`	A ManualKeyword target’s keyword input is empty or contains only whitespace.
`bid-multiplier-not-supported-on-negative-target`	A negative target includes a bid multiplier.
`bid-multiplier-out-of-range`	A bid multiplier is outside the supported range.
`unknown-match-type`	A ManualKeyword target uses an unsupported match type.
`another-target-in-request-failed-validation`	Another target of the same type failed validation, so this target was not created.
`page-type-not-available-for-retailer`	A PageType target is not supported by the retailer.
`page-type-not-available-for-buy-type`	A PageType target is not supported for the line item’s buy type.
`unknown-buy-type`	The line item’s buy type cannot be determined for a PageType target.
`negative-category-not-supported`	A Category target cannot be negative on the line item.
`manual-positive-category-not-supported-on-dynamic-match`	A Category target must be negative on a dynamic-match line item.
`category-not-supported-on-line-item-type`	Category targets are not supported for the line item type.
`line-item-has-no-pages`	The line item has no pages to which a Category target can be attached.
`no-category-capable-pages`	No page targeted by the line item supports categories.
`category-not-found-for-retailer`	A Category target does not exist for the retailer.
`category-not-valid-status-for-retailer`	The category exists but does not have a targetable status in the retailer’s catalog.

Partial Success Example

Partial-Success Request

curl -L -X POST \
  'https://api.criteo.com/experimental/retail-media/line-items/1234567890123456789/targets/create' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "data": [
      {
        "type": "Target",
        "attributes": {
          "targetType": "ManualKeyword",
          "negative": false,
          "bidMultiplier": null,
          "manualKeywordTargetDetails": {
            "keywordInput": "trail running shoes",
            "matchType": "Broad"
          }
        }
      },
      {
        "type": "Target",
        "attributes": {
          "targetType": "PageType",
          "negative": false,
          "bidMultiplier": null,
          "pageTypeTargetDetails": {
            "pageType": "Search"
          }
        }
      }
    ]
  }'

Partial-Success Response — 200 OK

{
  "data": [
    {
      "type": "Target",
      "attributes": {
        "targetType": "PageType",
        "negative": false,
        "bidMultiplier": null,
        "approvalStatus": "AutoApproved",
        "pageTypeTargetDetails": {
          "pageType": "Search"
        }
      }
    }
  ],
  "warnings": [],
  "errors": [
    {
      "type": "validation",
      "code": "unknown-match-type",
      "detail": "Cannot create target [trail running shoes] because positive broad is not a supported match type.",
      "instance": "@data/0"
    }
  ]
}

The error points to the first requested target, while the valid PageType target was created successfully.

Update Targets

Updates ManualKeyword, PageType, and Category targets for the specified line item. The request has PATCH-like semantics: only mutable fields supplied in the request are updated. See Identifying targets for Update and Delete for the fields that identify each target and the fields that can be updated. Prerequisites:

OAuth 2.0 bearer token with the RetailMedia_Campaign_Manage scope
Access to the requested line item

See Target request attributes for the request fields.

Example

Successful Request

curl -L -X POST \
  'https://api.criteo.com/experimental/retail-media/line-items/1234567890123456789/targets/update' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "data": [
      {
        "type": "Target",
        "attributes": {
          "targetType": "ManualKeyword",
          "negative": false,
          "bidMultiplier": 1.25,
          "manualKeywordTargetDetails": {
            "keywordInput": "trail running shoes",
            "matchType": "Exact"
          }
        }
      }
    ]
  }'

Successful Response — 200 OK

{
  "data": [
    {
      "type": "Target",
      "attributes": {
        "targetType": "ManualKeyword",
        "negative": false,
        "bidMultiplier": 1.25,
        "approvalStatus": "Approved",
        "manualKeywordTargetDetails": {
          "keywordInput": "trail running shoes",
          "matchType": "Exact"
        }
      }
    }
  ],
  "warnings": [],
  "errors": []
}

Responses

Status	Code	Description
`200 OK`		The request succeeded completely or partially across target types. Process the updated targets in `data` and inspect `errors` and `warnings`.
`400 Bad Request`	`targets-max-elements-exceeded`	The request contains more than 100 targets.
`400 Bad Request`	`unknown-target-type`	A target type is not supported.
`401 Unauthorized`		The access token is missing, invalid, or expired.
`403 Forbidden`		The caller lacks Campaign Manage permission or access to the requested line item.
`500 Internal Server Error`		An unexpected internal error prevented the endpoint from completing the request. Retry the request. If the failure persists, contact support.
`502 Bad Gateway`		The endpoint could not complete target updates. Retry the request. If the failure persists, contact support.

Validation Errors

Update responses can include the following application-level validation errors in errors:

Code	Description
`invalid-external-line-item-id`	The line item ID is invalid.
`target-details-mismatch`	A target’s details object does not match its declared target type.
`invalid-category-id`	A Category target’s category ID is not a number.
`unknown-page-type`	A PageType target’s page type is not supported.
`target-not-found`	The target does not exist on the line item.
`duplicate-target-in-request`	The request contains the same target more than once.
`bid-multiplier-not-supported-on-negative-target`	A negative target includes a bid multiplier.
`bid-multiplier-out-of-range`	A bid multiplier is outside the supported range.
`unknown-match-type`	A ManualKeyword target uses an unsupported match type.
`another-target-in-request-failed-validation`	Another target of the same type failed validation, so this target was not updated.
`page-type-not-available-for-retailer`	A PageType target is not supported by the retailer.
`unknown-buy-type`	The line item’s buy type cannot be determined for a PageType target.

Delete Targets

Deletes ManualKeyword, PageType, and Category targets from the specified line item. See Identifying targets for Update and Delete for how to select targets to delete. Prerequisites:

OAuth 2.0 bearer token with the RetailMedia_Campaign_Manage scope
Access to the requested line item

See Target request attributes for the request fields.

Example

Successful Request

curl -L -X POST \
  'https://api.criteo.com/experimental/retail-media/line-items/1234567890123456789/targets/delete' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "data": [
      {
        "type": "Target",
        "attributes": {
          "targetType": "ManualKeyword",
          "negative": false,
          "bidMultiplier": 1.25,
          "approvalStatus": "Approved",
          "manualKeywordTargetDetails": {
            "keywordInput": "trail running shoes",
            "matchType": "Exact"
          }
        }
      },
      {
        "type": "Target",
        "attributes": {
          "targetType": "PageType",
          "negative": false,
          "bidMultiplier": null,
          "approvalStatus": "AutoApproved",
          "pageTypeTargetDetails": {
            "pageType": "Search"
          }
        }
      }
    ]
  }'

Successful Response — 200 OK

{
  "warnings": [],
  "errors": []
}

The response does not contain a data array. Use Get Targets to retrieve the targets remaining on the line item.

Responses

Status	Code	Description
`200 OK`		The request succeeded completely or partially across target types. Inspect `errors` and `warnings` before treating the deletion as complete.
`400 Bad Request`	`targets-max-elements-exceeded`	The request contains more than 100 targets.
`400 Bad Request`	`unknown-target-type`	A target type is not supported.
`401 Unauthorized`		The access token is missing, invalid, or expired.
`403 Forbidden`		The caller lacks Campaign Manage permission or access to the requested line item.
`500 Internal Server Error`		An unexpected internal error prevented the endpoint from completing the request. Retry the request. If the failure persists, contact support.
`502 Bad Gateway`		The endpoint could not complete target deletion. Retry the request. If the failure persists, contact support.

Deleting a PageType target can also remove Category targets associated only with that page type. The response then includes a category-targets-removed-with-page-type warning.

Validation Errors

Delete responses can include the following application-level validation errors in errors:

Code	Description
`invalid-external-line-item-id`	The line item ID is invalid.
`target-details-mismatch`	A target’s details object does not match its declared target type.
`invalid-category-id`	A Category target’s category ID is not a number.
`unknown-page-type`	A PageType target’s page type is not supported.
`duplicate-target-in-request`	The request contains the same target more than once.
`another-target-in-request-failed-validation`	Another target of the same type failed validation, so this target was not deleted.
`category-not-supported-on-line-item-type`	Category targets are not supported for the line item type.

Introduction

Guides for Retail Media API

Overview

Targeting Types

Shared Target Attributes

Target Type Details

Target Request Attributes

Partial Success Across Target Types

Identifying Targets for Update and Delete

Endpoints

Get Targets

Request Attributes

Response Attributes

Responses

Partial Success

Create Targets

Examples

Responses

Validation Errors

Partial Success Example

Update Targets

Example

Responses

Validation Errors

Delete Targets

Example

Responses

Validation Errors

​Overview

​Targeting Types

​Shared Target Attributes

​Target Type Details

​Target Request Attributes

​Partial Success Across Target Types

​Identifying Targets for Update and Delete

​Endpoints

​Get Targets

​Request Attributes

​Response Attributes

​Responses

​Partial Success

​Create Targets

​Examples

​Responses

​Validation Errors

​Partial Success Example

​Update Targets

​Example

​Responses

​Validation Errors

​Delete Targets

​Example

​Responses

​Validation Errors

Overview

Targeting Types

Shared Target Attributes

Target Type Details

Target Request Attributes

Partial Success Across Target Types

Identifying Targets for Update and Delete

Endpoints

Get Targets

Request Attributes

Response Attributes

Responses

Partial Success

Create Targets

Examples

Responses

Validation Errors

Partial Success Example

Update Targets

Example

Responses

Validation Errors

Delete Targets

Example

Responses

Validation Errors