Targeting

Overview

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. Clients should inspect the errors array even when the endpoint returns 200 OK. The endpoint supports partial success by target type: if a target type is unavailable, other available target types can still be included in the response. The Create Targets endpoint creates ManualKeyword, PageType, and Category targets for a line item. The Update Targets endpoint updates 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. Create and Update 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.

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

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

The endpoint supports partial success by target type. If one or more target types are available, it 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. A single request can contain targets of more than one supported target type. Prerequisites:

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

Request Attributes

Attribute	Type	Required	Description
`lineItemId`	string	Yes	Line item ID. Provided in the URL path.
`data`	array	No	Target resources to create. A request can contain up to 100 targets.
`data[].type`	string	No	Resource type. Set this value to `Target`.
`data[].attributes.targetType`	enum	Yes	Target type to create: `ManualKeyword`, `PageType`, or `Category`.
`data[].attributes.negative`	boolean	Yes	Whether the target excludes matching inventory.
`data[].attributes.bidMultiplier`	number or null	No	Bid multiplier for a non-negative target.
`data[].attributes.<details-object>`	object	Yes	Details object for the selected target type. See Targeting types.

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.

Partial Success

Create requests can contain up to 100 targets and can include more than one supported target type. They can return 200 OK with created targets in data and errors for target types that did not succeed. Always inspect errors and warnings before treating the response as complete.

Validation errors in partial-success responses

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.

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. A single request can contain targets of more than one supported target type. The request has PATCH-like semantics. The immutable target details identify each target, and the mutable fields supplied in the request are updated. Do not use this endpoint to change a target’s targetType or target details object; identify the existing target with the same targetType and exactly one target details object. Prerequisites:

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

Request Attributes

Attribute	Type	Required	Description
`lineItemId`	string	Yes	Line item ID. Provided in the URL path.
`data`	array	No	Target resources to update.
`data[].type`	string	No	Resource type. Set this value to `Target`.
`data[].attributes.targetType`	enum	Yes	Target type to update: `ManualKeyword`, `PageType`, or `Category`.
`data[].attributes.negative`	boolean	No	Whether the target excludes matching inventory.
`data[].attributes.bidMultiplier`	number or null	No	Bid multiplier for a non-negative target. Supply this field to update it.
`data[].attributes.<details-object>`	object	Yes	Details object that identifies the existing target. See Targeting types.

Fields by target type

To update a target, provide its existing targetType and matching target details. Those fields identify the target and cannot be changed by this endpoint.

Target type	Immutable fields	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`

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.

Partial Success

Update requests can contain up to 100 targets and can include more than one supported target type. They can return 200 OK with updated targets in data and errors for target types that did not succeed. Always inspect errors and warnings before treating the response as complete.

Validation errors in partial-success responses

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.

Introduction

Guides for Retail Media API

Overview

Targeting types

Shared target attributes

Target type details

Endpoints

Get Targets

Request Attributes

Response Attributes

Responses

Partial Success

Create Targets

Request Attributes

Examples

Responses

Partial Success

Validation errors in partial-success responses

Example

Update Targets

Request Attributes

Fields by target type

Example

Responses

Partial Success

Validation errors in partial-success responses

​Overview

​Targeting types

​Shared target attributes

​Target type details

​Endpoints

​Get Targets

​Request Attributes

​Response Attributes

​Responses

​Partial Success

​Create Targets

​Request Attributes

​Examples

​Responses

​Partial Success

​Validation errors in partial-success responses

​Example

​Update Targets

​Request Attributes

​Fields by target type

​Example

​Responses

​Partial Success

​Validation errors in partial-success responses

Overview

Targeting types

Shared target attributes

Target type details

Endpoints

Get Targets

Request Attributes

Response Attributes

Responses

Partial Success

Create Targets

Request Attributes

Examples

Responses

Partial Success

Validation errors in partial-success responses

Example

Update Targets

Request Attributes

Fields by target type

Example

Responses

Partial Success

Validation errors in partial-success responses