> ## Documentation Index
> Fetch the complete documentation index at: https://developers.criteo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Category Bids

export const EndpointBadge = ({method = "GET", children}) => {
  const METHOD_STYLES = {
    GET: {
      bg: "mint-bg-[#2AB673]"
    },
    POST: {
      bg: "mint-bg-[#3064E3]"
    },
    PUT: {
      bg: "mint-bg-[#C28C30]"
    },
    PATCH: {
      bg: "mint-bg-[#DA622B]"
    },
    DELETE: {
      bg: "mint-bg-[#CB3A32]"
    },
    API: {
      bg: "mint-bg-black"
    }
  };
  const key = method.toUpperCase();
  const styles = METHOD_STYLES[key] ?? METHOD_STYLES.API;
  return <div className="relative mt-7">
      <span className={`absolute -top-2 -left-2 z-10 ${styles.bg} text-white px-2.5 py-0.5 rounded-full text-xs font-bold tracking-wide`}>
        {key}
      </span>
      {children}
    </div>;
};

## **Introduction**

In addition to ad-set-level bid targets, Criteo permits bid customization for each product category associated with an ad set.

For example, you may wish to set higher bids for particular brands or product lines.

<Warning>
  **Requirements**

  * Categories used for bidding must be added as the `category 1`, `category 2`, or `category 3` field when configuring the import of your [product catalog](https://help.criteo.com/kb/guide/en/set-up-your-product-catalog-x21HrwcuTy/Steps/775589).
  * Category-level bidding must also be explicitly enabled for **one** of the categories above by your Criteo account team.
  * Ad set must be set with CPC or CPM as cost controller (more details on cost controller [here](/marketing-solutions/v2025.10/docs/ad-set#ad-set-bidding)). If your ad set uses another cost controller, you must refer to the [Display Multipliers](/marketing-solutions/v2025.10/docs/display-multipliers) solution.
</Warning>

 

## **Get Category Bids**

The category bids associated with a specific Ad Set can be retrieved via a `GET` request to the `/ad-sets` endpoint, with the Ad Set ID as a URL parameter and `/category-bids` specified.

 

<EndpointBadge method="get">
  ```http theme={null}
  https://api.criteo.com/2025-10/marketing-solutions/ad-sets/{ad-set-id}/category-bids
  ```
</EndpointBadge>

The API will return an array of categories associated with the ad set:

```json Sample Response theme={null}
{
    "data":[
      {
          "type": "AdSetCategoryBid",
          "id": "1234567|432|1",
          "attributes": {
              "categoryName": "Shoes",
              "bidAmount": 1.3
          }
      },
      {
          "type": "AdSetCategoryBid",
          "id": "1234567|432|2",
          "attributes": {
              "categoryName": "Socks",
              "bidAmount": 1.3
          }
      }
    ],
    "errors": [ ]
}
```

<Info>
  **ID**

  The Id is composite of the Ad Set Id, a Criteo category ID and a Category level (1, 2 or 3). In the above example, the id of the category `shoes` is composed of:

  * **Ad set ID**: `1234567`
  * **Category ID**: `432`
  * **Category Level**: `1`
</Info>

<Info>
  **Default Bid**

  All categories enabled will be shown in the results. If a specific bid is not set for an available category, it will display the bid amount configured at the ad set level.
</Info>

 

## **Update Category Bids**

You can update the bid amount of one or more categories of an Ad Set by making a `PATCH` request to the `/ad-sets` endpoint, with the Ad Set ID as a URL parameter and `/category-bids` specified.

For example, the following call would update the bid values for the category `Shoes` and `Socks` on the previous GET sample:

 

<EndpointBadge method="patch">
  ```http theme={null}
  https://api.criteo.com/2025-10/marketing-solutions/ad-sets/{ad-set-id}/category-bids
  ```
</EndpointBadge>

<CodeGroup>
  ```json Sample Request Body theme={null}
  {
      "data": [
          {
              "type": "AdSetCategoryBid",
              "id": "1234567|432|1",
              "attributes": { 
                  "bidAmount": 2.0
              }
          }, 
          {
              "type": "AdSetCategoryBid",
              "id": "1234567|432|2",
              "attributes": {
                  "bidAmount": 1.1
              }
          }
      ]
  }
  ```
</CodeGroup>

 

The API will return an array of Ad Sets that have been updated successfully in the response `data`. These will contain only two parameters, `type` and `id`.

```json Sample Response - Success theme={null}
{
    "data": [
        {
            "type": "AdSetCategoryBid",
            "id": "1234567|432|1"
        },
        {
            "type": "AdSetCategoryBid",
            "id": "1234567|432|2"
        }
    ],
    "errors": [],
    "warnings": []
}
```

<Info>
  **Reset Category Bid**

  Setting the bid amount of a category to the same bid amount at the ad set level will reset the category bid behavior for that category. Thus, this update will make any subsequent changes on the ad set bid apply to that category bid.
</Info>

<Danger>
  **Updating Multiple Category Bids**

  This endpoint allows you to update several category bids within a single call. Thus it\`s important to understand the [partial success behavior](/marketing-solutions/v2025.10/docs/partial-success-for-bulk-operations).
</Danger>

 

## **Validation Errors**

In addition to [general API errors](/marketing-solutions/v2025.10/docs/api-error-types), you may encounter validation errors when retrieving or updating a category bid.

Below is a list of error codes for category bid validation and a more detailed description of their meaning.

**`campaign--category-bid-get-check--invalid-bidding-config`**\
Category bid is only available on ad set with CPC-based or CPM-based cost controllers. If your ad set uses other cost controller, you must refer to the [Display Multipliers](/marketing-solutions/v2025.10/docs/display-multipliers).

<br />

 

**`campaign--category-bid-update-check--category-not-enabled`**\
The category targeted by the category bid is not enabled.

<br />

 

**`campaign--category-bid-update-check--ad-set-not-enabled`**\
The ad set status is invalid, and the change is not allowed (e.g., the ad set is archived).

<br />

 

**`campaign--category-bid-update-check--invalid-bid-amount`**\
The bid amount provided is not in the range of accepted values.

<br />

 

**`campaign--category-bid-update-check--cannot-update-same-category-bid-amount-multiple-times`**\
It is not possible to update the same category bid amount multiple times in the same request.

<br />

 

## **Upcoming Category Bid functionality**

A special reset endpoint will be introduced in future releases. This endpoint will allow resetting category bids for all the enabled categories associated with an Ad Set. This means that the bid for all categories will be set to the default bid amount of the ad set.

As a reminder, in order to enable category bidding functionality, you may have to issue a request to your account strategist. If the feature is turned off and on during the Ad Set/ Account lifetime the category bids are not reset automatically. Therefore, if you don't plan to use the category bid feature anymore it's a good idea to manually reset category-level bids to those of an ad set, before asking your account strategist to disable the feature.