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

> [!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](https://developers.criteo.com/retail-media/v2024.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.

## **Endpoints**

| Method | Endpoint | Description |
| - | - | - |
| **GET** | `/accounts/{accountId}/line-items` | Retrieve all line items associated with a specific account. |
| **GET** | `/line-items/{lineItemId}` | Retrieve details of a specific line item by its ID. |

## **Line Item Attributes**

Omitting the status field in line item update calls will result in a **400 error**. Ensure that you include the status when updating line items to avoid validation issues.

**id** *required*

**Data Type:** string

**Accepted Value:** int64

**Write?** No

**Nullable?** No

**Description:** Line Item ID

**type** *required*

**Data Type:** enum

**Accepted Value:** `auction`, `preferred`

**Write?** No

**Nullable?** No

**Description:** Campaign type

**campaignId** *required*

**Data Type:** string

**Accepted Value:** int64

**Write?** No

**Nullable?** No

**Description:** Campaign ID

**name** *required*

**Data Type:** string

**Accepted Value:** 255 char limit

**Write?** Yes

**Nullable?** No

**Description:** Line item name; must be unique within a campaign

**targetRetailerId** *required*

**Data Type:** string

**Accepted Value:** int64

**Write?** No

**Nullable?** No

**Description:** ID of the [retailer](https://developers.criteo.com/retail-media/docs/retailers) the line item serves on

**startDate** *required*

**Data Type:** date

**Accepted Value:** YYYY-MM-DD

**Write?** Yes

**Nullable?** No

**Description:** Line item start date in the [account](https://developers.criteo.com/retail-media/docs/accounts-endpoints.md) `timeZone`

**endDate**

**Data Type:** date

**Accepted Value:** YYYY-MM-DD

**Write?** Yes

**Nullable?** Yes

**Description:** Line item end date in the [account](https://developers.criteo.com/retail-media/docs/accounts-endpoints.md) `timeZone`; serves indefinitely if omitted or set to `null`. A timestamp can be included as well if the line item is desired to end at a certain time of day

**budget**

**Data Type:** number

**Accepted Value:** at least 0

**Write?** No

**Nullable?** Yes

**Description:** Line item lifetime spend cap; uncapped if omitted or set to `null`

**budgetSpent**

**Data Type:** number

**Accepted Value:** at least 0

**Write?** No

**Nullable?** No

**Description:** The amount the line item has already spent

**budgetRemaining**

**Data Type:** number

**Accepted Value:** 0 and `budget`

**Write?** No

**Nullable?** Yes

**Description:** Amount the line item has to remain until cap is hit; null if budget is uncapped

**status**

**Data Type:** enum

**Accepted Value:** `active`, `paused`, `scheduled`, `ended`, `budgetHit`, `noFunds`, `draft`, `archived`

**Write?** Yes

**Nullable?** No

**Description:** Line item status; can only be updated by a user to `active` or `paused`; all other values are applied automatically depending on flight dates, financials, or missing attributes required for line item to serve. To understand the conditions that will cause a status to change, check out our [status page](https://developers.criteo.com/retail-media/docs/campaign-lineitem-status)

**createdAt**

**Data Type:** timestamp

**Accepted Value:** ISO-8601

**Write?** No

**Nullable?** No

**Description:** Timestamp in UTC of last line item update

## **Get All Line Items**

This endpoint lists all line items in the specified campaign. Results are paginated.

GET

```http theme={null}
https://api.criteo.com/{version}/retail-media/accounts/{accountId}/line-items
```

**Sample Request**

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

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

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

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")
  .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');
$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();
}
```

**Sample Response**

```json 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
    }
}
```

## **Get a Specific Line Item**

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

GET

```http theme={null}
https://api.criteo.com/{version}/retail-media/line-items/{lineItemId}
```

**Sample Request**

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

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

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

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/1232")
  .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/1232');
$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();
}
```

**Sample Response**

```json 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"
        }
    }
}
```

## **Responses**

| Response | Description |
| - | - |
| 🟢`200` | Call completed successfully. The specified line item details are returned. |
| 🔴`403` | API user is not authorized to make requests for the account ID. To request authorization, follow the[authorization request](https://developers.criteo.com/retail-media/v2024.10/docs/authorization-requests)steps. |
| 🔴`404` | Line item ID not found. Ensure the`lineItemId`is correct and exists. |