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

# Onsite Display Line Items

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

Auction Display Line Items define how Onsite Display campaigns deliver ads across retailer inventory.

They control targeting, creatives, bidding, pacing, and scheduling. Line items operate under a Display Campaign and follow a proposal workflow before activation.

### Business Context

Onsite Display line items enable advertisers to configure auction-based display advertising using CPM bidding. They support automation-first defaults while allowing granular control over bidding, pacing, and targeting when needed.

### Prerequisites

* Valid `accountId` and `displayCampaignId`
* Authenticated request using Bearer token
* Existing Display Campaign

<Info>
  Line items follow a **proposal workflow**. A line item must be submitted and approved before it can actively serve.
</Info>

<Warning>
  Some behaviors and available fields differ depending on whether the request is made by a Retailer (Supply) or an Advertiser (Demand). We document those differences in [this section](/retail-media/v2026-preview/docs/onsite-display-line-items#actor-differences).
</Warning>

***

## Endpoints Overview

<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>
            /campaigns/\{displayCampaignId}/auction-display-line-items
          </code>
        </p>
      </td>

      <td>
        <p>
          Create a new Auction Display Line Item
        </p>
      </td>
    </tr>

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

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

      <td>
        <p>
          Update an existing Auction Display Line Item
        </p>
      </td>
    </tr>

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

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

      <td>
        <p>
          Search and filter Auction Display Line Items
        </p>
      </td>
    </tr>

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

      <td>
        <p>
          <code>
            /auction-display-line-items/\{lineItemId}/submit-proposal
          </code>
        </p>
      </td>

      <td>
        <p>
          Submit a line item for review
        </p>
      </td>
    </tr>

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

      <td>
        <p>
          <code>
            /auction-display-line-items/\{lineItemId}/recall-proposal
          </code>
        </p>
      </td>

      <td>
        <p>
          Recall a submitted line item
        </p>
      </td>
    </tr>
  </tbody>
</table>

***

## 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>
            lineItemId
          </code>
        </p>
      </td>

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

      <td>
        <p>
          Line item ID generated by the system. Writeable: No. Nullable: No
        </p>
      </td>
    </tr>

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

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

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

      <td>
        <p>
          Display name of the line item. Writeable: Yes. Nullable: No
        </p>
      </td>
    </tr>

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

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

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

      <td>
        <p>
          The retailer ID where ads will serve. Cannot be changed after creation.
        </p>
      </td>
    </tr>

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

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

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

      <td>
        <p>
          The parent Display Campaign ID. Cannot be changed after creation.
        </p>
      </td>
    </tr>

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

      <td>
        <p>
          number
        </p>
      </td>

      <td>
        <p>
          Lifetime spend cap for the line item. Uncapped if omitted.
        </p>
      </td>
    </tr>

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

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

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

      <td>
        <p>
          Line item status. Accepted values:

          <code>
            active
          </code>

          ,

          <code>
            inactive
          </code>

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

    <tr>
      <td>
        <p>
          <code>
            isActive
          </code>

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

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

      <td>
        <p>
          Whether the line item is actively eligible to serve.
        </p>
      </td>
    </tr>

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

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

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

      <td>
        <p>
          When the line item begins serving. Format: ISO 8601 (

          <code>
            YYYY-MM-DDTHH:MM:SSZ
          </code>

          ).
        </p>
      </td>
    </tr>

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

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

      <td>
        <p>
          When the line item stops serving. Optional; omit for no end date.
        </p>

        <p>
          Format: ISO 8601 (

          <code>
            YYYY-MM-DDTHH:MM:SSZ
          </code>

          ).
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            mediaType
          </code>

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

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

      <td>
        <p>
          Media type for this line item.
        </p>

        <p>
          Currently supported:

          <code>
            Display
          </code>

          ,

          <code>
            Video
          </code>

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

    <tr>
      <td>
        <p>
          <code>
            pageTypes
          </code>

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

      <td>
        <p>
          array of strings
        </p>
      </td>

      <td>
        <p>
          Page types where ads will be eligible to serve.
        </p>

        <p>
          Accepted values:

          <code>
            search
          </code>

          ,

          <code>
            category
          </code>

          .
        </p>

        <p>
          At least one must be specified.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            productIds
          </code>
        </p>
      </td>

      <td>
        <p>
          array of strings
        </p>
      </td>

      <td>
        <p>
          List of product (SKU) IDs to promote. When provided, overrides dynamic SKU allocation.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            creativeIds
          </code>
        </p>
      </td>

      <td>
        <p>
          array of strings
        </p>
      </td>

      <td>
        <p>
          List of creative IDs to associate with this line item.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            pacing.pacingType
          </code>

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

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

      <td>
        <p>
          Controls how budget is distributed over time. Accepted values:

          <code>
            even
          </code>

          ,

          <code>
            ahead
          </code>

          ,

          <code>
            asSoonAsPossible
          </code>

          ,

          <code>
            dailyBudgetCap
          </code>

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

    <tr>
      <td>
        <p>
          <code>
            pacing.pacingAmount
          </code>
        </p>
      </td>

      <td>
        <p>
          number
        </p>
      </td>

      <td>
        <p>
          Required when

          <code>
            pacing.pacingType
          </code>

          is

          <code>
            dailyBudgetCap
          </code>

          . Specifies the daily spend limit.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            bidding.bidStrategy
          </code>

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

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

      <td>
        <p>
          Bidding strategy to use. Accepted values:

          <code>
            manual
          </code>

          ,

          <code>
            automatic
          </code>

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

    <tr>
      <td>
        <p>
          <code>
            bidding.manualBidding.auctionBids
          </code>
        </p>
      </td>

      <td>
        <p>
          array of objects
        </p>
      </td>

      <td>
        <p>
          Required when

          <code>
            bidding.bidStrategy
          </code>

          is

          <code>
            manual
          </code>

          . A bid must be specified for every page type listed in

          <code>
            pageTypes
          </code>

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

    <tr>
      <td>
        <p>
          <code>
            bidding.manualBidding.auctionBids\[].pageType
          </code>
        </p>
      </td>

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

      <td>
        <p>
          The page type this bid applies to. Must match a value in

          <code>
            pageTypes
          </code>

          . Accepted values:

          <code>
            search
          </code>

          ,

          <code>
            category
          </code>

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

    <tr>
      <td>
        <p>
          <code>
            bidding.manualBidding.auctionBids\[].bid
          </code>
        </p>
      </td>

      <td>
        <p>
          number
        </p>
      </td>

      <td>
        <p>
          CPM bid amount in account currency for the specified page type.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            targets
          </code>
        </p>
      </td>

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

      <td>
        <p>
          Targeting configuration. Input audience IDs here.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            frequencyCapping
          </code>
        </p>
      </td>

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

      <td>
        <p>
          Line item-level frequency cap. Inherits campaign-level settings if

          <code>
            null
          </code>

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

***

## Actor Differences

Some behaviors and available fields differ depending on whether the request is made by a Retailer (Supply) or an Advertiser (Demand).

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

      <th>
        <p>
          Supply Account User
        </p>
      </th>

      <th>
        <p>
          Demand Brand User
        </p>
      </th>
    </tr>
  </thead>

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

          in URL
        </p>
      </td>

      <td>
        <p>
          <code>
            supplyAccountId
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            demandBrandAccountId
          </code>
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            companyName
          </code>

          /

          <code>
            onBehalfCompanyName
          </code>
        </p>
      </td>

      <td>
        <p>
          Supported on campaigns
        </p>
      </td>

      <td>
        <p>
          Not applicable
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          Default

          <code>
            frequencyCapping.cappingDurationType
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            day
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            session
          </code>
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          Default

          <code>
            pacing.pacingType
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            dailyBudgetCap
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            asSoonAsPossible
          </code>
        </p>
      </td>
    </tr>
  </tbody>
</table>

***

## Key Concepts

### Page Types

Display line items can serve on the following page types:

* `search`
* `category`

When using manual bidding, a bid must be provided for each page type configured.

### Bidding

One strategy is supported:

* `manual` — Requires specifying a CPM bid per page type via `auctionBids`

### Pacing

Controls how the budget is spent over time:

* `even` — Distributes spend evenly
* `ahead` — Spends slightly faster than even pacing
* `asSoonAsPossible` — Spends as fast as possible
* `dailyBudgetCap` — Enforces a daily spend limit via `pacingAmount`

***

## Create Auction Display Line Item

Creates a new line item in draft (proposal) state.

<Warning>
  When using manual bidding, `auctionBids` must include one bid entry per page type listed in `pageTypes`. Omitting a bid for any configured page type will result in a validation error.
</Warning>

<EndpointBadge method="post">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/campaigns/{displayCampaignId}/auction-display-line-items
  ```
</EndpointBadge>

**Sample Request**

```json expandable theme={null}
{
  "data": {
    "type": "AuctionDisplayLineItem",
    "attributes": {
      "name": "My Display Line Item",
      "retailerId": "1392",
      "budget": 10000,
      "status": "active",
      "isActive": true,
      "startDate": "2025-02-01T00:00:00Z",
      "endDate": "2026-12-31T23:59:59Z",
      "mediaType": "Display",
      "pageTypes": ["search"],
      "creativeIds": ["776546501968928768"],
      "pacing": {
        "pacingType": "dailyBudgetCap",
        "pacingAmount": 100.0
      },
      "bidding": {
        "bidStrategy": "manual",
        "manualBidding": {
          "auctionBids": [
            {
              "pageType": "search",
              "bid": 2.5
            }
          ]
        }
      }
    }
  }
}
```

**Sample Response**

```json expandable theme={null}
{
  "data": {
    "id": "828005795069235200",
    "type": "AuctionDisplayLineItem",
    "attributes": {
      "status": "draft",
      "isProposal": true,
      "name": "My Display Line Item",
      "retailerId": "1392",
      "budget": 10000.00,
      "pacing": {
        "pacingType": "dailyBudgetCap",
        "pacingAmount": 100.0
      },
      "campaignId": "827998371331510272",
      "startDate": "2025-01-31T19:00:00.000-05:00",
      "endDate": "2026-12-31T18:59:59.000-05:00",
      "mediaType": "display",
      "productIds": [
        "10001",
        "10002",
        "10003"
      ],
      "creativeIds": [
        "776546501968928768"
      ],
      "pageTypes": [
        "search"
      ],
      "frequencyCapping": null,
      "bidding": {
        "bidStrategy": "Manual",
        "manualBidding": {
          "auctionBids": [
            {
              "bid": 2.50000000,
              "pageType": "search"
            }
          ]
        }
      },
      "targets": null
    }
  },
  "warnings": [],
  "errors": []
}
```

***

## Update Auction Display Line Item

Updates an existing line item, and supports partial updates.

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

<Info>
  **Important** Only provided fields are updated. Line items in submitted state may require recall before modification.
</Info>

**Sample Request**

#### Updating Bidding Configuration

```json theme={null}
{
  "data": {
    "type": "AuctionDisplayLineItem",
    "attributes": {
      "bidding": {
        "bidStrategy": "manual",
        "manualBidding": {
          "auctionBids": [
            {
              "pageType": "search",
              "bid": 2.9
            }
          ]
        }
      }
    }
  }
}
```

#### Updating Basic Fields

You can also update fields like `name` and `creativeIds` independently.

```json theme={null}
{
  "data": {
    "type": "AuctionDisplayLineItem",
    "attributes": {
      "name": "Updated Line Item Name",
      "creativeIds": ["776546501968928768"]
    }
  }
}
```

**Sample Response for the Updating of Basic Fields**

```json expandable theme={null}
{
  "data": {
    "id": "828005795069235200",
    "type": "AuctionDisplayLineItem",
    "attributes": {
      "status": "draft",
      "isProposal": true,
      "name": "bdcefcea-56b3-446e-8b73-eef4f07bf217",
      "retailerId": "1392",
      "budget": 10000.00,
      "pacing": {
        "pacingType": "dailyBudgetCap",
        "pacingAmount": 100.0
      },
      "campaignId": "827998371331510272",
      "startDate": "2025-01-31T19:00:00.000-05:00",
      "endDate": "2026-12-31T18:59:59.000-05:00",
      "mediaType": "display",
      "productIds": [
        "10001",
        "10002",
        "10003"
      ],
      "creativeIds": [
        "776546501968928768"
      ],
      "pageTypes": [
        "search"
      ],
      "frequencyCapping": null,
      "bidding": {
        "bidStrategy": "Manual",
        "manualBidding": {
          "auctionBids": [
            {
              "bid": 2.50000000,
              "pageType": "search"
            }
          ]
        }
      },
      "targets": null
    }
  },
  "warnings": [],
  "errors": []
}
```

***

## Search Auction Display Line Items

Retrieves line items using filters. Supports pagination via `offset` and `limit`. Use the optional fields query parameter to restrict which attributes are returned.

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

**Sample Request**

```json theme={null}
{
  "data": {
    "type": "AuctionDisplayLineItemSearchModel",
    "attributes": {
      "campaignId": "824391362922348544",
      "retailerId": "1392",
      "lineItemIds": [],
      "isProposal": true
    }
  }
}
```

<Warning>
  The search endpoint supports retrieving **a maximum of five (5) line items per request.**
</Warning>

**Sample Response**

```json expandable theme={null}
{
  "metadata": {
    "count": 2,
    "offset": 0,
    "limit": 5
  },
  "data": [
    {
      "id": "827999389330837504",
      "type": "AuctionDisplayLineItemSearchResult",
      "attributes": {
        "proposalStatus": null,
        "status": "draft",
        "isProposal": true,
        "name": "a6e12cdc-fddf-45f0-991b-e15765865d3e",
        "retailerId": "1392",
        "budget": 10000.00,
        "pacing": {
          "pacingType": "asSoonAsPossible",
          "pacingAmount": null
        },
        "campaignId": "827998371331510272",
        "startDate": "2024-12-31T19:00:00.000-05:00",
        "endDate": "2026-12-31T18:59:59.000-05:00",
        "mediaType": "display",
        "productIds": [
          "10001",
          "10002",
          "10003",
          "10004",
          "10005",
          "10006",
          "10007",
          "10008"
        ],
        "creativeIds": [
          "776546501968928768"
        ],
        "pageTypes": [
          "search"
        ],
        "frequencyCapping": null,
        "bidding": {
          "bidStrategy": "Manual",
          "manualBidding": {
            "auctionBids": [
              {
                "bid": 2.50000000,
                "pageType": "search"
              }
            ]
          }
        },
        "targets": null
      }
    },
    {
      "id": "828005795069235200",
      "type": "AuctionDisplayLineItemSearchResult",
      "attributes": {
        "proposalStatus": null,
        "status": "draft",
        "isProposal": true,
        "name": "bdcefcea-56b3-446e-8b73-eef4f07bf217",
        "retailerId": "1392",
        "budget": 10000.00,
        "pacing": {
          "pacingType": "dailyBudgetCap",
          "pacingAmount": 2.50
        },
        "campaignId": "827998371331510272",
        "startDate": "2025-01-31T19:00:00.000-05:00",
        "endDate": "2026-12-31T18:59:59.000-05:00",
        "mediaType": "display",
        "productIds": [
          "10001",
          "10002",
          "10003"
        ],
        "creativeIds": [
          "776546501968928768"
        ],
        "pageTypes": [
          "search"
        ],
        "frequencyCapping": null,
        "bidding": {
          "bidStrategy": "Manual",
          "manualBidding": {
            "auctionBids": [
              {
                "bid": 2.50000000,
                "pageType": "search"
              }
            ]
          }
        },
        "targets": null
      }
    }
  ],
  "warnings": [],
  "errors": []
}
```

### Filter Attributes

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

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

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

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

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

      <td>
        <p>
          Filter results to line items belonging to a specific campaign.
        </p>
      </td>
    </tr>

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

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

      <td>
        <p>
          Filter results to a specific retailer.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            lineItemIds
          </code>
        </p>
      </td>

      <td>
        <p>
          array of strings
        </p>
      </td>

      <td>
        <p>
          Filter to specific line item IDs. Pass an empty array to return all.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            isProposal
          </code>
        </p>
      </td>

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

      <td>
        <p>
          When true, returns only line items in proposal status (pending review).
        </p>
      </td>
    </tr>
  </tbody>
</table>

***

## Proposal Workflow

Line items follow a lifecycle:

* Draft → Created but not submitted
* Submitted → Pending review
* Recalled → Returned to draft
* Approved / Rejected → Reviewed by retailer

<Info>
  Retailers who create line items will not be able to recall them, as they are automatically approved.
</Info>

### Submit Proposal

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

**Sample Request**

```json theme={null}
{
  "data": {
    "type": "ProposalAction",
    "attributes": {
      "comment": "Ready for review."
    }
  }
}
```

### Recall Proposal

Use this endpoint to retract a submitted proposal before it is reviewed — for example, to make further edits.

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

<CodeGroup>
  ```json JSON theme={null}
  {
    "data": {
      "type": "ProposalAction",
      "attributes": {
        "comment": "Recalling to update bid amounts."
      }
    }
  }
  ```
</CodeGroup>

<Info>
  Successful responses return `HTTP 204 `with no body.
</Info>

***

### Proposal Constraints

The proposal workflow enforces the following rules:

* A line item must be in `draft` state before it can be submitted
* Submitting an already submitted line item will fail
* A line item must be in `submitted` state to be recalled
* Recalling a line item that was never submitted will fail
* Line items cannot be modified while in submitted (pending review) state
* Once a line item is approved or rejected, it can no longer be recalled

***

# Validations Rules, Responses & Errors

## Validation Rules

Common validation errors include:

* `bidStrategy = manual` but `manualBidding` is missing
* `manualBidding` is provided but does not include a bid for every page type defined in `pageTypes`
* Invalid `pacingType` value
* Missing `pacingAmount` when `pacingType = dailyBudgetCap`
* `endDate` is before `startDate`
* Invalid or unsupported `pageTypes`
* `retailerId` does not match the parent campaign
* `creativeIds` reference non-existent or inaccessible creatives

***

## Responses

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

      <th>
        <p>
          Title
        </p>
      </th>

      <th>
        <p>
          Detail
        </p>
      </th>

      <th>
        <p>
          Troubleshooting
        </p>
      </th>
    </tr>
  </thead>

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

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

      <td>
        <p>
          Success
        </p>
      </td>

      <td>
        <p>
          Request processed successfully
        </p>
      </td>

      <td>
        <p>
          Verify response payload
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🟢

          <code>
            201
          </code>
        </p>
      </td>

      <td>
        <p>
          Created
        </p>
      </td>

      <td>
        <p>
          Line item created successfully
        </p>
      </td>

      <td>
        <p>
          N/A
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🟢

          <code>
            204
          </code>
        </p>
      </td>

      <td>
        <p>
          No Content
        </p>
      </td>

      <td>
        <p>
          Proposal action succeeded
        </p>
      </td>

      <td>
        <p>
          N/A
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🔴

          <code>
            400
          </code>
        </p>
      </td>

      <td>
        <p>
          Invalid Request
        </p>
      </td>

      <td>
        <p>
          Missing or invalid fields
        </p>
      </td>

      <td>
        <p>
          Check bidding, pacing, and

          <code>
            pageTypes
          </code>
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🔴

          <code>
            401
          </code>
        </p>
      </td>

      <td>
        <p>
          Unauthorized
        </p>
      </td>

      <td>
        <p>
          Invalid or missing token
        </p>
      </td>

      <td>
        <p>
          Verify Bearer token
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🔴

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

      <td>
        <p>
          Forbidden
        </p>
      </td>

      <td>
        <p>
          Access denied
        </p>
      </td>

      <td>
        <p>
          Check permissions
        </p>
      </td>
    </tr>
  </tbody>
</table>

***

## Reasons for Errors

**Authentication & Authorization** Missing or expired Bearer tokens will result in a `401` response

**Permissions**\
Having the wrong scope or attempting to call accounts, campaigns, or line items you do not have consent to will result in a `403` response

**Invalid Fields** Having invalid entries for certain attributes can result in a `400` response with an explanation of what to correct

At the **Campaign Level**, this can mean:

* Not including the `buyType`
* Invalid value for the frequency cap duration type
* Attribution scope & windows not within the accepted values
* Inaccessible Balance ID

At the **Line Item Level**, this can mean:

* Unsupported `PageType` is entered
* `PageType` and bid are not aligned for manual bidding
* No max CPM for automated bidding
* `bidStrategy` is manual but `manualBidding` is absent
* When `bidStrategy` is set to manual, the `manualBidding` object with `auctionBids` is required. Omitting it fails
* `bidStrategy` is automatic but `manualBidding` is still included
* Sending `manualBidding` when `bidStrategy` is automatic is likely to cause a conflict error. The automatic strategy requires no bid configuration
* `pacingAmount` missing when `pacingType` is `dailyBudgetCap`
* `pacingType` invalid value.  Accepted values: `even`, `ahead`, `asSoonAsPossible`, `dailyBudgetCap`. Other values fail
* `endDate` before `startDate`. If provided, `endDate` must be after `startDate`
* `retailerId` does not match the campaign's configured retailer
* The `retailerId` on a line item must correspond to a retailer that is valid for the parent campaign. Using a retailer ID the account doesn't have access to will fail.
* `creativeIds` reference non-existent or inaccessible creatives
* If a creative ID doesn't exist or belongs to a different account, the request will fail.

At the **Proposal Stage**:

* Submitting a proposal that is already submitted.  Calling `submit-proposal` on a line item that is already in a submitted/pending state will fail. A line item must be in Draft state to be submitted
* Recalling a proposal that was never submitted.  Calling `recall-proposal` on a line item that is not currently in a submitted/pending state will fail
* Recalling or modifying a line item that has been approved or rejected. Once a proposal has been reviewed (approved or rejected), it can no longer be recalled. Attempting to do so will return an error
* Editing a line item while it is in submitted/pending state. A `PATCH` to a line item that is pending review will likely be rejected until it is recalled first

## What's next

* [Minimum Bid](/retail-media/v2026-preview/docs/minimum-bid)