> ## 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.

# Audience Segments Endpoints

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

**Audience Segments** represent groups of users, defined either explicitly through `Contact Lists` provided externally or by `User Events` intent behaviors automatically collected through our retailers integrations.

Multiple Audience Segments can be combined using logical [Algebra Nodes](/retail-media/docs/algebra-nodes) to define the desired target audience for your campaigns.

<Warning>
  The corresponding App should have the "**Audiences Manage**" permission enabled for all endpoints listed on this page.
</Warning>

<Info>
  **About Audience Segments in Preview**

  The Audience Segment endpoints documented here are part of the `2025 Preview version`of the Retail Media API. Only the `create`, `update`, and `delete` endpoints are included because they now support event-based targeting, which is not available in the stable API.\
  Other endpoints (e.g., `search`, `contact-list management`) remain unchanged and are documented in [the stable version of this page](/retail-media/docs/audience-segment-endpoints).
</Info>

<Warning>
  **Note on Audience Computation**

  Audience updates are processed daily at 0h UTC and 12h UTC and can take around 5 hours to reflect on a live campaign. This is important for audiences that are frequently updated as changes should be ready for processing prior to these two times.
</Warning>

<Info>
  **Partial Approvals**

  Bulk operations (`create`, `update`, `delete`) use a **partial approval model**. Even if some items in the request fail, the response will return `200 OK`. Any failed items will be listed in the `error` section of the response with [an error code and details](/retail-media/v2026-preview/docs/audience-segments#errors).

  Examples of possible error codes:

  * `segment-not-found` → Segment is not found.
  * `name-must-be-unique` → Segment name must be unique.
  * `name-must-not-be-empty` → Segment name property must not be empty.

  This list is not exhaustive. Additional warnings may be returned depending on the request context.
</Info>

***

## Endpoints

<table>
  <thead>
    <tr>
      <th>
        <p>
          Verb
        </p>
      </th>

      <th>
        <p>
          Endpoint
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <b>
            POST
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /accounts/\{accountId}/audience-segments/create
          </code>
        </p>
      </td>

      <td>
        <p>
          Create a new Audience Segment
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            PATCH
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /accounts/\{accountId}/audience-segments
          </code>
        </p>
      </td>

      <td>
        <p>
          Update an Audience Segment
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            POST
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /accounts/\{accountId}/audience-segments/delete
          </code>
        </p>
      </td>

      <td>
        <p>
          Delete an Audience Segment
        </p>
      </td>
    </tr>
  </tbody>
</table>

***

## Audience Segment Attributes

<table>
  <thead>
    <tr>
      <th>
        <p>
          Attribute
        </p>
      </th>

      <th>
        <p>
          Data Type
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <code>
            id
          </code>

          /

          <code>
            audienceSegmentId
          </code>
        </p>
      </td>

      <td>
        <p>
          string
        </p>
      </td>

      <td>
        <p>
          Audience Segment ID, generated internally by Criteo
        </p>

        <p>
          Accepted values: string of int64
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            name
          </code>

          <span>\*</span>
        </p>
      </td>

      <td>
        <p>
          string
        </p>
      </td>

      <td>
        <p>
          Audience Segment name
        </p>

        <p>
          Accepted values: string
        </p>

        <p>
          Writeable? Y / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            description
          </code>
        </p>
      </td>

      <td>
        <p>
          string
        </p>
      </td>

      <td>
        <p>
          Description of the Audience Segment
        </p>

        <p>
          Accepted values: string
        </p>

        <p>
          Writeable? Y / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            accountId
          </code>
        </p>
      </td>

      <td>
        <p>
          string
        </p>
      </td>

      <td>
        <p>
          <a href="/retail-media/docs/account">
            Account
          </a>

          ID associated with the Audience Segment, generated internally by Criteo
        </p>

        <p>
          Accepted values: string of int64
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            retailerId
          </code>

          <span>\*</span>
        </p>
      </td>

      <td>
        <p>
          string
        </p>
      </td>

      <td>
        <p>
          <a href="/retail-media/docs/retailers">
            Retailer
          </a>

          ID, associated with the Audience Segment, generated internally by Criteo
        </p>

        <p>
          Accepted values: string of int64
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            type
          </code>
        </p>
      </td>

      <td>
        <p>
          enum
        </p>
      </td>

      <td>
        <p>
          Type of segment
        </p>

        <p>
          Accepted values:
        </p>

        <ul>
          <li>
            <code>
              ContactList
            </code>

            : users segment defined by list of contact identifiers, manageable by the other endpoints
          </li>

          <li>
            <code>
              Events
            </code>

            : users segment defined by a combination of events collected in the retailer's environment
          </li>
        </ul>

        <p>
          Writeable? Y / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            contactList
          </code>
        </p>
      </td>

      <td>
        <p>
          object
        </p>
      </td>

      <td>
        <p>
          Setting to target users with contact list. Note, either one of

          <code>
            contactList
          </code>

          or

          <code>
            events
          </code>

          is required, however both cannot be leveraged at the same time
        </p>

        <p>
          See below for more details
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            events
          </code>
        </p>
      </td>

      <td>
        <p>
          object
        </p>
      </td>

      <td>
        <p>
          Settings to target users based on their events. Note, either one of

          <code>
            contactList
          </code>

          or

          <code>
            events
          </code>

          is required, however both cannot be leveraged at the same time
        </p>

        <p>
          See below for more details
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            createdAt
          </code>
        </p>
      </td>

      <td>
        <p>
          timestamp
        </p>
      </td>

      <td>
        <p>
          Timestamp of Audience Segment creation, in UTC
        </p>

        <p>
          Accepted values:

          <code>
            yyyy-mm-ddThh:mm:ss.msZ
          </code>

          (in

          <a href="https://www.iso.org/iso-8601-date-and-time-format.html">
            ISO-8601
          </a>

          )
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            createdById
          </code>
        </p>
      </td>

      <td>
        <p>
          string
        </p>
      </td>

      <td>
        <p>
          User ID who created the Audience Segment (

          <code>
            null
          </code>

          if created by a service)
        </p>

        <p>
          Accepted values: string
        </p>

        <p>
          Writeable? N / Nullable? Y
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            updatedAt
          </code>
        </p>
      </td>

      <td>
        <p>
          timestamp
        </p>
      </td>

      <td>
        <p>
          Timestamp of last Audience Segment update, in UTC
        </p>

        <p>
          Accepted values:

          <code>
            yyyy-mm-ddThh:mm:ss.msZ
          </code>

          (in

          <a href="https://en.wikipedia.org/wiki/ISO_8601">
            ISO-8601
          </a>

          )
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            channels
          </code>
        </p>
      </td>

      <td>
        <p>
          list\\
        </p>
      </td>

      <td>
        <p>
          Channels associated to the audience
        </p>

        <p>
          Accepted values:

          <code>
            Onsite
          </code>

          ,

          <code>
            Offsite
          </code>
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>
  </tbody>
</table>

*\*Required at the`create` operation*

<Info>
  **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.
</Info>

***

## Contact List Segment Attributes

<table>
  <thead>
    <tr>
      <th>
        <p>
          Attribute
        </p>
      </th>

      <th>
        <p>
          Data Type
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <code>
            isReadOnly
          </code>
        </p>
      </td>

      <td>
        <p>
          boolean
        </p>
      </td>

      <td>
        <p>
          Indicates if the contact list can be edited
        </p>

        <p>
          Accepted values:

          <code>
            true
          </code>

          ,

          <code>
            false
          </code>
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            identifierType
          </code>
        </p>
      </td>

      <td>
        <p>
          enum
        </p>
      </td>

      <td>
        <p>
          User identifier type from Contact list
        </p>

        <p>
          Accepted values:

          <code>
            Email
          </code>

          ,

          <code>
            UserIdentifier
          </code>

          ,

          <code>
            IdentityLink
          </code>

          ,

          <code>
            CustomerId
          </code>

          ,

          <code>
            PhoneNumber
          </code>

          ,

          <code>
            Unknown
          </code>

          ,
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>
  </tbody>
</table>

<Info>
  **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.
</Info>

***

## Events Segment Attributes

<table>
  <thead>
    <tr>
      <th>
        <p>
          Attribute
        </p>
      </th>

      <th>
        <p>
          Data Type
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <code>
            shopperActivity
          </code>

          <span>\*</span>
        </p>
      </td>

      <td>
        <p>
          enum
        </p>
      </td>

      <td>
        <p>
          Activity type performed by the desired target users in the retailer's environment
        </p>

        <p>
          Accepted values:

          <code>
            View
          </code>

          ,

          <code>
            Buy
          </code>

          ,

          <code>
            AddToCart
          </code>

          ,

          <code>
            Unknown
          </code>
        </p>

        <p>
          Writeable? Y / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            lookbackDays
          </code>

          <span>\*</span>
        </p>
      </td>

      <td>
        <p>
          enum
        </p>
      </td>

      <td>
        <p>
          Timeframe of the interaction performed by the desired target users in the retailer's environment
        </p>

        <p>
          Accepted values:

          <code>
            Last7Days
          </code>

          ,

          <code>
            Last14Days
          </code>

          ,

          <code>
            Last30Days
          </code>

          ,

          <code>
            Last45Days
          </code>

          ,

          <code>
            Last60Days
          </code>

          ,

          <code>
            Last90Days
          </code>

          ,

          <code>
            Last120Days
          </code>

          ,

          <code>
            Last150Days
          </code>

          ,

          <code>
            Last180Days
          </code>
        </p>

        <p>
          Writeable? Y / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            categoryIds
          </code>
        </p>
      </td>

      <td>
        <p>
          list\\
        </p>
      </td>

      <td>
        <p>
          Define users interested in specific categories using

          <a href="/retail-media/v2026-preview/docs/category-search">
            Search Category
          </a>

          .
        </p>

        <p>
          Note, either one of

          <code>
            categoryIds
          </code>

          or

          <code>
            brandIds
          </code>

          must be included. Both can be included as well, but the request will fail if neither are included.
        </p>

        <p>
          See the dedicated section right below for more details.
        </p>

        <p>
          Accepted values: array of strings/int64
        </p>

        <p>
          Writeable? Y / Nullable? Y
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            brandIds
          </code>
        </p>
      </td>

      <td>
        <p>
          list\\
        </p>
      </td>

      <td>
        <p>
          Define users who performed the activity type above in specific

          <a href="/retail-media/docs/brands">
            brands
          </a>

          .
        </p>

        <p>
          Note, either one of

          <code>
            categoryIds
          </code>

          or

          <code>
            brandIds
          </code>

          must be included. Both can be included as well, but the request will fail if neither are included.
        </p>

        <p>
          See the dedicated section right below for more details.
        </p>

        <p>
          Accepted values: array of strings/int64
        </p>

        <p>
          Writeable? Y / Nullable? Y
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            minPrice
          </code>
        </p>
      </td>

      <td>
        <p>
          decimal
        </p>
      </td>

      <td>
        <p>
          Define users who interact with products whose prices are greater than

          <code>
            minPrice
          </code>
        </p>

        <p>
          Accepted values:

          <code>
            minPrice
          </code>

          ≥ 0.0 (or

          <code>
            null
          </code>

          )
        </p>

        <p>
          Writeable? Y / Nullable? Y
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            maxPrice
          </code>
        </p>
      </td>

      <td>
        <p>
          decimal
        </p>
      </td>

      <td>
        <p>
          Define users who interact with products whose prices are smaller than

          <code>
            maxPrice
          </code>
        </p>

        <p>
          Accepted values:

          <code>
            maxPrice
          </code>

          ≥ 0.0 (or

          <code>
            null
          </code>

          )
        </p>

        <p>
          Writeable? Y / Nullable? Y
        </p>
      </td>
    </tr>
  </tbody>
</table>

*\*Required at create operation*

<Info>
  **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.
</Info>

***

## Sourcing Category and Brand IDs

To populate the `categoryId` and `brandId` attributes when creating or updating audience segments, use the following endpoints:

### `categoryID`

Use the [Search Categories](/retail-media/v2026-preview/docs/category-search) endpoint to find category IDs relevant to your campaign. This method offers a faster lookup than navigating the full product catalog.

### `brandID`

Two endpoints should be used together to accurately source `brandId`:

* [`/brands/search`](/retail-media/docs/brands) – retrieves all available brands.
* [`/accounts/{accountId}/brands`](/retail-media/docs/brands) – retrieves only the brands mapped to a specific account.

To avoid targeting conflicts, ensure that the `brandId` used is mapped to the account associated with the audience segment. A best practice is to cross-reference both the `brandId` and the intended `retailerId` to verify eligibility for targeting.

***

## Create Audience Segment

This endpoint allows creating Audience Segments, either from Contact List or Users Events type.

<EndpointBadge method="post">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/accounts/{accountId}/audience-segments/create
  ```
</EndpointBadge>

**Sample Request**:

<CodeGroup>
  ```json JSON expandable theme={null}
  curl -L -X POST 'https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audience-segments/create' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
  -d '{
    "data": [
      {
        "type": "AudienceSegment",
        "attributes": {
          "name": "CRM Users 2025",
          "description": "Segment made of CRM user emails",
          "retailerId": "1234",
          "contactList": {
            "identifierType": "Email"
          }
        }
      },
      {
        "type": "AudienceSegment",
        "attributes": {
          "name": "Buyers Last 7D Brand ABC",
          "description": "Segment of buyer users of brand ABC in the last 7 days",
          "retailerId": "1234",
          "events": {
            "shopperActivity": "Buy",
            "lookbackDays": "Last7Days",
            "brandIds": [
              "123456"
            ]
          }
        }
      }
    ]
  }'
  ```

  ```python Python expandable theme={null}
  import http.client
  import json
  conn = http.client.HTTPSConnection("api.criteo.com")
  payload = json.dumps({
    "data": [
      {
        "type": "AudienceSegment",
        "attributes": {
          "name": "CRM Users 2025",
          "description": "Segment made of CRM user emails",
          "retailerId": "1234",
          "contactList": {
            "identifierType": "Email"
          }
        }
      },
      {
        "type": "AudienceSegment",
        "attributes": {
          "name": "Buyers Last 7D Brand ABC",
          "description": "Segment of buyer users of brand ABC in the last 7 days",
          "retailerId": "1234",
          "events": {
            "shopperActivity": "Buy",
            "lookbackDays": "Last7Days",
            "brandIds": [
              "123456"
            ]
          }
        }
      }
    ]
  })
  headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Bearer &lt;TOKEN&gt;'
  }
  conn.request("POST", "/{version}/retail-media/accounts/625702934721171442/audience-segments/create", payload, headers)
  res = conn.getresponse()
  data = res.read()
  print(data.decode("utf-8"))
  ```

  ```java Java theme={null}
  OkHttpClient client = new OkHttpClient().newBuilder()
    .build();
  MediaType mediaType = MediaType.parse("application/json");
  RequestBody body = RequestBody.create(mediaType, '{"data":[{"type":"AudienceSegment","attributes":{"name":"CRM Users 2025","description":"Segment made of CRM user emails","retailerId":"1234","contactList":{"identifierType":"Email"}}},{"type":"AudienceSegment","attributes":{"name":"Buyers Last 7D Brand ABC","description":"Segment of buyer users of brand ABC in the last 7 days","retailerId":"1234","events":{"shopperActivity":"Buy","lookbackDays":"Last7Days","brandIds":["123456"]}}}]}');
  Request request = new Request.Builder()
    .url("https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audience-segments/create")
    .method("POST", body)
    .addHeader("Content-Type", "application/json")
    .addHeader("Accept", "application/json")
    .addHeader("Authorization", "Bearer &lt;TOKEN&gt;")
    .build();
  Response response = client.newCall(request).execute();
  ```

  ```php PHP theme={null}
  <?php
  require_once 'HTTP/Request2.php';
  $request = new HTTP_Request2();
  $request->setUrl('https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audience-segments/create');
  $request->setMethod(HTTP_Request2::METHOD_POST);
  $request->setConfig(array(
    'follow_redirects' => TRUE
  ));
  $request->setHeader(array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer &lt;TOKEN&gt;'
  ));
  $request->setBody('{"data":[{"type":"AudienceSegment","attributes":{"name":"CRMUsers2025","description":"SegmentmadeofCRMuseremails","retailerId":"1234","contactList":{"identifierType":"Email"}}},{"type":"AudienceSegment","attributes":{"name":"BuyersLast7DBrandABC","description":"SegmentofbuyerusersofbrandABCinthelast7days","retailerId":"1234","events":{"shopperActivity":"Buy","lookbackDays":"Last7Days","brandIds":["123456"]}}}]}');
  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();
  }
  ```
</CodeGroup>

**Sample Response**

```json expandable theme={null}
{
    "data": [
        {
            "id": "738406687217913856",
            "type": "RetailMediaAudienceSegment",
            "attributes": {
                "accountId": "625702934721171442",
                "name": "Buyers Last 7D Brand ABC",
                "description": "Segment of buyer users of brand ABC in the last 7 days",
                "retailerId": "1234",
                "type": "Events",
                "createdAt": "2025-07-30T14:44:32.81Z",
                "updatedAt": "2025-07-30T14:44:32.81Z",
                "createdById": "514277",
                "events": {
                    "shopperActivity": "Buy",
                    "lookbackDays": "Last7Days",
                    "categoryIds": [],
                    "brandIds": [
                        "123456"
                    ],
                    "minPrice": null,
                    "maxPrice": null
                },
                "channels": [
                    "Onsite",
                    "Offsite"
                ]
            }
        },
        {
            "id": "738406688413290496",
            "type": "RetailMediaAudienceSegment",
            "attributes": {
                "accountId": "625702934721171442",
                "name": "CRM Users 2025",
                "description": "Segment made of CRM user emails",
                "retailerId": "1234",
                "type": "ContactList",
                "createdAt": "2025-07-30T14:44:32.81Z",
                "updatedAt": "2025-07-30T14:44:32.81Z",
                "createdById": "514277",
                "contactList": {
                    "isReadOnly": false,
                    "identifierType": "Email",
                    "sharingStatus": "NotShared"
                },
                "channels": [
                    "Offsite"
                ]
            }
        }
    ],
    "warnings": [],
    "errors": []
}
```

***

## Update Audience Segment

This endpoint allows updating `Audience Segments`, either from `Contact List` or `Users Events` type.

<Info>
  For `Contact List `segments, it's possible to update their metadata (name and description) but not their identity types. For those cases, please create a new segment with the new desired identifier type.
</Info>

<EndpointBadge method="patch">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/accounts/{accountId}/audience-segments
  ```
</EndpointBadge>

**Sample Request**

<CodeGroup>
  ```json JSON expandable theme={null}
  curl -L -X PATCH 'https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audience-segments' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
  -d '{
    "data": [
      {
        "id": "738406688413290496",
        "type": "AudienceSegment",
        "attributes": {
          "name": "CRM User E-mails 2025 ",
          "description": {
            "value": "Segment made of CRM user e-mails"
          },
          "contactList": {
            "identifierType": "Email"
          }
        }
      },
      {
        "id": "738406687217913856",
        "type": "AudienceSegment",
        "attributes": {
          "name": "Cart Abandoned Last 7D Brand ABC",
          "description": {
            "value": "Segment of cart users with brand ABC in the last 7 days"
          },
          "retailerId": "1234",
          "events": {
            "shopperActivity": "AddToCart",
            "lookbackDays": "Last7Days",
            "brandIds": [
              "123456"
            ]
          }
        }
      }
    ]
  }'
  ```

  ```python Python expandable theme={null}
  import http.client
  import json
  conn = http.client.HTTPSConnection("api.criteo.com")
  payload = json.dumps({
    "data": [
      {
        "id": "738406688413290496",
        "type": "AudienceSegment",
        "attributes": {
          "name": "CRM User E-mails 2025 ",
          "description": "Segment made of CRM user e-mails",
          "retailerId": "1234",
          "contactList": {
            "identifierType": "Email"
          }
        }
      },
      {
        "id": "738406687217913856",
        "type": "AudienceSegment",
        "attributes": {
          "name": "Cart Abandoned Last 7D Brand ABC",
          "description": "Segment of cart users with brand ABC in the last 7 days",
          "retailerId": "1234",
          "events": {
            "shopperActivity": "AddToCart",
            "lookbackDays": "Last7Days",
            "brandIds": [
              "123456"
            ]
          }
        }
      }
    ]
  })
  headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Bearer &lt;TOKEN&gt;'
  }
  conn.request("PATCH", "/{version}/retail-media/accounts/625702934721171442/audience-segments", payload, headers)
  res = conn.getresponse()
  data = res.read()
  print(data.decode("utf-8"))
  ```

  ```java Java theme={null}
  OkHttpClient client = new OkHttpClient().newBuilder()
    .build();
  MediaType mediaType = MediaType.parse("application/json");
  RequestBody body = RequestBody.create(mediaType, '{"data":[{"id":"738406688413290496","type":"AudienceSegment","attributes":{"name":"CRM User E-mails 2025","description":"Segment made of CRM user e-mails","retailerId":"1234","contactList":{"identifierType":"Email"}}},{"id":"738406687217913856","type":"AudienceSegment","attributes":{"name":"Cart Abandoned Last 7D Brand ABC","description":"Segment of cart users with brand ABC in the last 7 days","retailerId":"1234","events":{"shopperActivity":"AddToCart","lookbackDays":"Last7Days","brandIds":["123456"]}}}]}');
  Request request = new Request.Builder()
    .url("https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audience-segments")
    .method("PATCH", body)
    .addHeader("Content-Type", "application/json")
    .addHeader("Accept", "application/json")
    .addHeader("Authorization", "Bearer &lt;TOKEN&gt;")
    .build();
  Response response = client.newCall(request).execute();
  ```

  ```php PHP theme={null}
  <?php
  require_once 'HTTP/Request2.php';
  $request = new HTTP_Request2();
  $request->setUrl('https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audience-segments');
  $request->setMethod(HTTP_Request2::METHOD_PATCH);
  $request->setConfig(array(
    'follow_redirects' => TRUE
  ));
  $request->setHeader(array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer &lt;TOKEN&gt;'
  ));
  $request->setBody('{"data":[{"id":"738406688413290496","type":"AudienceSegment","attributes":{"name":"CRM User E-mails 2025","description":"Segment made of CRM user e-mails","retailerId":"1234","contactList":{"identifierType":"Email"}}},{"id":"738406687217913856","type":"AudienceSegment","attributes":{"name":"Cart Abandoned Last 7D Brand ABC","description":"Segment of cart users with brand ABC in the last 7 days","retailerId":"1234","events":{"shopperActivity":"AddToCart","lookbackDays":"Last7Days","brandIds":["123456"]}}}]}');
  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();
  }
  ```
</CodeGroup>

**Sample Response**

```json expandable theme={null}
{
  "data": [
    {
      "id": "738406688413290496",
      "type": "RetailMediaAudienceSegment",
      "attributes": {
        "accountId": "4",
        "name": "CRM User E-mails 2025",
        "description": {
          "value": "Segment made of CRM user e-mails"
        },
        "retailerId": "1234",
        "type": "ContactList",
        "createdAt": "2025-07-30T14:44:32.81Z",
        "updatedAt": "2025-07-30T15:14:19.3566667Z",
        "createdById": "514277",
        "contactList": {
          "isReadOnly": false,
          "identifierType": "Email",
          "sharingStatus": "NotShared"
        },
        "channels": [
          "Offsite"
        ]
      }
    },
    {
      "id": "738406687217913856",
      "type": "RetailMediaAudienceSegment",
      "attributes": {
        "accountId": "4",
        "name": "Cart Abandoned Last 7D Brand ABC",
        "description": {
          "value": "Segment made of CRM user e-mails"
        },
        "type": "Events",
        "createdAt": "2025-07-30T14:44:32.81Z",
        "updatedAt": "2025-07-30T15:14:19.3566667Z",
        "createdById": "514277",
        "events": {
          "shopperActivity": "AddToCart",
          "lookbackDays": "Last7Days",
          "categoryIds": [],
          "brandIds": [
            "123456"
          ],
          "minPrice": null,
          "maxPrice": null
        },
        "channels": [
          "Onsite",
          "Offsite"
        ]
      }
    }
  ],
  "warnings": [],
  "errors": []
}
```

***

## Delete Audience Segment

This endpoint allows deleting Audience Segments, either one by one or multiple of them.

<EndpointBadge method="post">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/accounts/{accountId}/audience-segments/delete
  ```
</EndpointBadge>

**Sample request**

<CodeGroup>
  ```bash cURL theme={null}
  curl -L -X POST 'https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audience-segments/delete' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
  -d '{
    "data": [
      {
        "id": "738406561971802112"
      }
    ]
  }'
  ```

  ```python Python theme={null}
  import http.client
  import json
  conn = http.client.HTTPSConnection("api.criteo.com")
  payload = json.dumps({
    "data": [
      {
        "id": "738406561971802112"
      }
    ]
  })
  headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Bearer &lt;TOKEN&gt;'
  }
  conn.request("POST", "/{version}/retail-media/accounts/625702934721171442/audience-segments/delete", payload, headers)
  res = conn.getresponse()
  data = res.read()
  print(data.decode("utf-8"))
  ```

  ```java Java theme={null}
  OkHttpClient client = new OkHttpClient().newBuilder()
    .build();
  MediaType mediaType = MediaType.parse("application/json");
  RequestBody body = RequestBody.create(mediaType, '{"data":[{"id":"225702933721171456"}]}');
  Request request = new Request.Builder()
    .url("https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audience-segments/delete")
    .method("POST", body)
    .addHeader("Content-Type", "application/json")
    .addHeader("Accept", "application/json")
    .addHeader("Authorization", "Bearer &lt;TOKEN&gt;")
    .build();
  Response response = client.newCall(request).execute();
  ```

  ```php PHP theme={null}
  <?php
  require_once 'HTTP/Request2.php';
  $request = new HTTP_Request2();
  $request->setUrl('https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audience-segments/delete');
  $request->setMethod(HTTP_Request2::METHOD_POST);
  $request->setConfig(array(
    'follow_redirects' => TRUE
  ));
  $request->setHeader(array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer &lt;TOKEN&gt;'
  ));
  $request->setBody('{"data":[{"id":"225702933721171456"}]}');
  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();
  }
  ```
</CodeGroup>

**Sample response**

```json theme={null}
{
    "data": [
        {
            "id": "738406561971802112",
            "type": "RetailMediaAudienceSegment",
            "attributes": {}
        }
    ],
    "warnings": [],
    "errors": []
}
```

### Partial `200 OK` response

<Warning>
  **Audience Segments cannot be deleted once they have served impressions**. Attempts to delete them will return `200 OK` but include a warning indicating the segment must first be removed from all audiences.

  Please note that this is not the only use case that might return a partial `200 OK `response.
</Warning>

```json theme={null}
{
    "data": [],
    "warnings": [],
    "errors": [
        {
            "traceId": "0ab8cdc52e17ecfd1ba9e5d1dacd102a",
            "traceIdentifier": "0ab8cdc52e17ecfd1ba9e5d1dacd102a",
            "type": "validation",
            "code": "segment-must-not-be-used-in-audience",
            "instance": "@data/0",
            "title": "Segment must not be used in an audience",
            "detail": "The segment must be removed from all audiences to be able to delete it"
        }
    ]
}
```

***

## Errors and warnings

Errors and warnings are grouped by category for clarity and usability.

***

### Request Structure Errors

#### `duplicate-id`

**Error**: Segment ID cannot be duplicated\
**Message**: The data object must not have multiple segment objects with the same ID.

***

#### `duplicate-name`

**Error**: Cannot have duplicated segment names\
**Message**: Each segment in the request must have a unique name.

***

#### `empty-attributes-object`

**Error**: Cannot have an empty attributes object\
**Message**: The request must have attributes object provided.

***

#### `empty-data-object`

**Error**: Cannot have an empty data object\
**Message**: The request must have at least one element in the data object.

***

#### `invalid-segment-type`

**Error**: Segment type is invalid\
**Message**: abcdef is not a valid segment type.

***

#### `multiple-segment-types`

**Error**: Cannot have a segment object with multiple types defined\
**Message**: The segment object must have exactly one type defined.

***

#### `non-parsable-id`

**Error**: One or more IDs cannot be parsed\
**Message**: All IDs in the segment object must have a valid numerical ID.

***

#### `undefined-segment-type`

**Error**: Cannot have a segment object without any type defined\
**Message**: The segment object must have exactly one type defined.

***

### Payload & Limits

#### `payload-too-big`

**Error**: Cannot create more than 10 segments at a time\
**Message**: Each request must have at most 10 segment objects.

***

#### `segments-limit-reached`

**Error**: Too many audience segments\
**Message**: Advertiser(s) 30, 40 have reached the number of allowed audience segments.

***

### Pagination Errors

#### `pagination-is-required`

**Error**: Pagination is required\
**Message**: Pagination is required when no entity IDs are provided in the filters.

***

#### `pagination-limit-cannot-be-zero`

**Error**: Pagination limit cannot be zero\
**Message**: Pagination limit must be great than 0 when offset is positive.

***

#### `pagination-limit-invalid`

**Error**: Pagination limit is invalid\
**Message**: Pagination limit must be a positive number lower than 10 (current limit set to 10).

***

#### `pagination-offset-invalid`

**Error**: Pagination offset is invalid\
**Message**: Pagination offset must be a positive number.

***

### Account and Authorization Errors

#### `account-must-be-active`

**Error**: Account must be active\
**Message**: The account used must be active.

***

#### `account-must-be-supply`

**Error**: Account must be supply\
**Message**: The account used must be a supply account.

***

#### `account-must-exist`

**Error**: Account must exist\
**Message**: The account used must exist.

***

#### `retailer-must-be-authorized`

**Error**: Retailer must be authorized\
**Message**: The retailer associated with the account must be authorized.

***

#### `retailer-must-be-live`

**Error**: Retailer must be live\
**Message**: The retailer used must be live.

***

#### `brands-must-be-authorized`

**Error**: Brands must be authorized\
**Message**: You are not authorized to use one or more of the provided brand IDs.

***

#### `add-to-cart-must-be-supported-for-retailer`

**Error**: Add to cart must be supported\
**Message**: The retailer used must support add to cart.

***

### Validation Errors

#### `brand-list-must-be-valid`

**Error**: Brand list must be valid\
**Message**: The provided brands are unknown or cannot be found within the given country: (30, 40).

***

#### `buying-power-must-be-valid`

**Error**: Buying power must be valid\
**Message**: Buying power value is unknown: (Low).

***

#### `categories-must-exist`

**Error**: Categories must exist\
**Message**: One or more of the provided category IDs do not exist.

***

#### `categories-or-brands-must-be-set`

**Error**: Categories or brands must be set\
**Message**: Either category IDs or brand IDs must be set.

***

#### `category-must-be-valid`

**Error**: Category must be valid\
**Message**: The specified category value is invalid.

***

#### `lookback-days-must-be-set`

**Error**: Lookback days must be set\
**Message**: Lookback days must be set.

***

#### `name-must-be-unique`

**Error**: Segment name must be unique\
**Message**: Another Segment exists with the name: abcdef.

***

#### `name-must-not-be-empty`

**Error**: Segment name property must not be empty\
**Message**: Cannot have an empty name in a create Segment entity.

***

#### `name-must-not-be-too-long`

**Error**: Segment name property must not be too long\
**Message**: Segment names must be no longer than 10 characters.

***

#### `price-range-must-be-valid`

**Error**: Price range must be valid\
**Message**: At least one price range must be set or one of the provided value is unknown.

***

#### `segment-must-not-be-used-in-audience`

**Error**: Segment must not be used in an audience\
**Message**: The segment must be removed from all audiences to be able to delete it.

***

#### `segment-not-found`

**Error**: Segment not found\
**Message**: Segment ID abcdef was not found.

***

#### `shopper-activity-must-be-set`

**Error**: Shopper activity must be set\
**Message**: Shopper activity must be set.

***

#### `start-date-must-be-before-end-date`

**Error**: Start date must be before end date\
**Message**: Start date and end date are not chronologically ordered.

***

#### `type-must-be-the-same`

**Error**: Type must be the same\
**Message**: Segment type cannot be changed after creation. The information sent is incompatible with the type of the segment.

***

<br />

## What's next

* [Audiences Size](/retail-media/v2026-preview/docs/audience-size)
* [Audience Segments Size](/retail-media/v2026-preview/docs/audience-segments-size)