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

# Line Items 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>;
};

<Note>
  **Getting Started**

  1. A line item holds promoted products to advertise on a single retailer.
  2. Line items include basic settings such as start and end dates, optional budget controls, and the associated retailer where ads are served.
  3. Budgets can also be managed at the campaign level.
  4. Several [reports](/retail-media/v2025.10/docs/demand-side-analytics-get-started) are available to track line item performance.
  5. Campaigns are limited to 10,000 non-archived line items.
  6. Line items are automatically archived 90 days after their end date.
</Note>

<br />

## **Endpoints**

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

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

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

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

      <td>
        <p>
          <code>
            /accounts/\{accountId}/line-items
          </code>
        </p>
      </td>

      <td>
        <p>
          Retrieve all line items associated with a specific account.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            GET
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /line-items/\{lineItemId}
          </code>
        </p>
      </td>

      <td>
        <p>
          Retrieve details of a specific line item.
        </p>
      </td>
    </tr>
  </tbody>
</table>

<br />

## **Line Item 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>
        </p>
      </td>

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

      <td>
        <p>
          Line item 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>
        </p>
      </td>

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

      <td>
        <p>
          Line item name, must be unique within a campaign
        </p>

        <p>
          Accepted values: up to 255-chars string
        </p>

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

    <tr>
      <td>
        <p>
          <code>
            campaignId
          </code>
        </p>
      </td>

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

      <td>
        <p>
          <a href="/retail-media/v2025.10/docs/campaign">
            Campaign
          </a>

          ID, in which the respective line item belongs
        </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>
          <a href="/retail-media/v2025.10/docs/campaign">
            Campaign
          </a>

          type
        </p>

        <p>
          Accepted values:

          <code>
            auction
          </code>

          ,

          <code>
            preferred
          </code>
        </p>

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

    <tr>
      <td>
        <p>
          <code>
            targetRetailerId
          </code>
        </p>
      </td>

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

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

          ID, in which the respective line item serves ad on
        </p>

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

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

    <tr>
      <td>
        <p>
          <code>
            startDate
          </code>
        </p>
      </td>

      <td>
        <p>
          date
        </p>
      </td>

      <td>
        <p>
          Start date of the line item, in the

          <a href="/retail-media/v2025.10/docs/account">
            Account
          </a>

          timezone; used to schedule its activation and start serving ads.
        </p>

        <p>
          To understand the conditions that will cause a status to change, check out

          <a href="/retail-media/v2025.10/docs/campaign-lineitem-status">
            Campaign & Line Item Status
          </a>
        </p>

        <p>
          Accepted values:

          <code>
            yyyy-mm-dd
          </code>
        </p>

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

    <tr>
      <td>
        <p>
          <code>
            endDate
          </code>
        </p>
      </td>

      <td>
        <p>
          date
        </p>
      </td>

      <td>
        <p>
          End date of the line item, in the

          <a href="/retail-media/v2025.10/docs/account">
            Account
          </a>

          timezone; serves ads indefinitely if omitted or set to

          <code>
            null
          </code>

          .
        </p>

        <p>
          A timestamp can be included as well if the line item is desired to end at a certain time of day
        </p>

        <p>
          Accepted values:

          <code>
            yyyy-mm-ddThh:mm:ss±hh:mm
          </code>

          (in

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

          )
        </p>

        <p>
          Default: if

          <code>
            null
          </code>

          or absent, balance will be available indefinitely
        </p>

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

    <tr>
      <td>
        <p>
          <code>
            budget
          </code>
        </p>
      </td>

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

      <td>
        <p>
          Line item lifetime spend cap, uncapped if omitted or set to

          <code>
            null
          </code>
        </p>

        <p>
          Accepted values:

          <code>
            budget
          </code>

          ≥ 0.0
        </p>

        <p>
          Default:

          <code>
            0.0
          </code>
        </p>

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

    <tr>
      <td>
        <p>
          <code>
            budgetSpent
          </code>
        </p>
      </td>

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

      <td>
        <p>
          Budget amount the line item has already spent
        </p>

        <p>
          Accepted values:

          <code>
            budgetSpent
          </code>

          ≥ 0.0
        </p>

        <p>
          Default:

          <code>
            0.0
          </code>
        </p>

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

    <tr>
      <td>
        <p>
          <code>
            budgetRemaining
          </code>
        </p>
      </td>

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

      <td>
        <p>
          Budget amount the line item has remaining until cap is hit;

          <code>
            null
          </code>

          if budget is uncapped
        </p>

        <p>
          Accepted values: 0 ≤

          <code>
            budgetRemaining
          </code>

          ≤

          <code>
            budget
          </code>
        </p>

        <p>
          Default:

          <code>
            0.0
          </code>
        </p>

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

    <tr>
      <td>
        <p>
          <code>
            status
          </code>
        </p>
      </td>

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

      <td>
        <p>
          Line item status; can only be updated by a user to

          <code>
            active
          </code>

          or

          <code>
            paused
          </code>

          ; all other values are applied automatically depending on financials, flight dates, or missing attributes required for line item to serve.
        </p>

        <p>
          To understand the conditions that will cause a status to change, check out

          <a href="/retail-media/v2025.10/docs/campaign-lineitem-status">
            Campaign & Line Item Status
          </a>
        </p>

        <p>
          Accepted values:

          <code>
            active
          </code>

          ,

          <code>
            paused
          </code>

          ,

          <code>
            scheduled
          </code>

          ,

          <code>
            ended
          </code>

          ,

          <code>
            budgetHit
          </code>

          ,

          <code>
            noFunds
          </code>

          ,

          <code>
            draft
          </code>

          ,

          <code>
            archived
          </code>
        </p>

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

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

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

      <td>
        <p>
          Timestamp of line item creation, in UTC
        </p>

        <p>
          Accepted values:

          <code>
            yyyy-mm-ddThh:mm:ss±hh:mm
          </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>
            updatedAt
          </code>
        </p>
      </td>

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

      <td>
        <p>
          Timestamp of last line item update, in UTC
        </p>

        <p>
          Accepted values:

          <code>
            yyyy-mm-ddThh:mm:ss±hh:mm
          </code>

          (in

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

          )
        </p>

        <p>
          Default: same as

          <code>
            createdAt
          </code>
        </p>

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

<br />

## **Get all Line Items**

This endpoint lists all line items in the specified campaign.

Results are paginated using `pageIndex` and `pageSize` query parameters; if omitted, defaults to `0` and `25`, respectively. See [API Response](/retail-media/v2025.10/docs/api-response#pagination).

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

**Sample Request**

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.criteo.com/{version}/retail-media/accounts/123456/line-items?pageIndex=0&pageSize=25" \
      -H "Authorization: Bearer <MY_ACCESS_TOKEN>"
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.criteo.com/{version}/retail-media/accounts/4/line-items?pageIndex=0&pageSize=25"

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

  response = requests.request("GET", url, headers=headers, data=payload)

  print(response.text)
  ```

  ```java Java theme={null}
  OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

  MediaType mediaType = MediaType.parse("text/plain");

  RequestBody body = RequestBody.create(mediaType, "");

  Request request = new Request.Builder()
    .url("https://api.criteo.com/{version}/retail-media/accounts/4/line-items?pageIndex=0&pageSize=25")
    .method("GET", body)
    .addHeader("Accept", "application/json")
    .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
    .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/4/line-items?pageIndex=0&pageSize=25');
  $request->setMethod(HTTP_Request2::METHOD_GET);
  $request->setConfig(array(
    'follow_redirects' => TRUE
  ));

  $request->setHeader(array(
    'Accept' => 'application/json',
    'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
  ));

  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": [
        {
            "type": "RetailMediaLineItem",
            "id": "9979917896105882144",
            "attributes": {
                "campaignId": "8343086999167541140",
                "name": "Line Item 123",
                "targetRetailerId": "3239117063738827231",
                "startDate": "2020-04-06",
                "endDate": null,
                "budget": null,
                "budgetSpent": 2383.87,
                "budgetRemaining": null,
                "status": "active",
                "createdAt": "2020-04-06T17:29:11+00:00",
                "updatedAt": "2020-04-06T17:29:11+00:00"
            }
        },
        // ...
        {
            "type": "RetailMediaLineItem",
            "id": "6854840188706902009",
            "attributes": {
                "campaignId": "8343086999167541140",
                "name": "Line Item 789",
                "targetRetailerId": "18159942378514859684",
                "startDate": "2020-04-08",
                "endDate": null,
                "budget": 8000.00,
                "budgetSpent": 1921.23,
                "budgetRemaining": 6078.77,
                "status": "paused",
                "createdAt": "2020-04-06T23:42:47+00:00",
                "updatedAt": "2020-06-03T03:01:52+00:00"       
            }
        }
    ],
    "metadata": {
        "totalItemsAcrossAllPages": 105,
        "currentPageSize": 25,
        "currentPageIndex": 0,
        "totalPages": 5,
        "nextPage": "https://api.criteo.com/{version}/retail-media/accounts/123456/line-items?pageIndex=1&pageSize=25",
        "previousPage": null
    }
}
```

<br />

## **Get a specific Line Item**

This endpoint retrieves details for a specified line item by its ID

<EndpointBadge method="get">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/line-items/{lineItemId}
  ```
</EndpointBadge>

**Sample Request**

<CodeGroup>
  ```bash cURL theme={null}
  curl -L -X GET "https://api.criteo.com/{version}/retail-media/line-items/2465695028166499188" \
      -H "Authorization: Bearer <MY_ACCESS_TOKEN>"
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.criteo.com/{version}/retail-media/line-items/2465695028166499188"

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

  response = requests.request("GET", url, headers=headers, data=payload)

  print(response.text)
  ```

  ```java Java theme={null}
  OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

  MediaType mediaType = MediaType.parse("text/plain");

  RequestBody body = RequestBody.create(mediaType, "");

  Request request = new Request.Builder()
    .url("https://api.criteo.com/{version}/retail-media/line-items/2465695028166499188")
    .method("GET", body)
    .addHeader("Accept", "application/json")
    .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
    .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/line-items/2465695028166499188');
  $request->setMethod(HTTP_Request2::METHOD_GET);
  $request->setConfig(array(
    'follow_redirects' => TRUE
  ));

  $request->setHeader(array(
    'Accept' => 'application/json',
    'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
  ));

  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": { 
        "type": "RetailMediaLineItem",
        "id": "2465695028166499188",
        "attributes": {
            "campaignId": "8343086999167541140",
            "name": "My New Line Item",
            "targetRetailerId": "18159942378514859684",
            "startDate": "2020-04-06",
            "endDate": null,
            "budget": null,
            "budgetSpent": 0.00,
            "budgetRemaining": null,
            "status": "draft",
            "createdAt": "2020-04-06T06:11:23+00:00",
            "updatedAt": "2020-04-06T06:11:23+00:00"
        }
    }
```

<br />

## **Responses**

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

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

  <tbody>
    <tr>
      <td>
        <p>
          🟢
        </p>

        <p>
          <code>
            200
          </code>
        </p>
      </td>

      <td>
        <p>
          Call completed successfully. The specified line item details are returned.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🔴
        </p>

        <p>
          <code>
            403
          </code>
        </p>
      </td>

      <td>
        <p>
          API user is not authorized to make requests for the account ID. To request authorization, follow the
        </p>

        <p>
          <a href="/retail-media/v2025.10/docs/authorization-requests">
            authorization request
          </a>
        </p>

        <p>
          steps.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🔴
        </p>

        <p>
          <code>
            404
          </code>
        </p>
      </td>

      <td>
        <p>
          Line item ID not found. Ensure the
        </p>

        <p>
          <code>
            lineItemId
          </code>
        </p>

        <p>
          is correct and exists.
        </p>
      </td>
    </tr>
  </tbody>
</table>