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

📘
Line items follow a proposal workflow. A line item must be submitted and approved before it can actively serve.

⚠️
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.

Endpoints Overview

Verb	Endpoint	Description
POST	`/campaigns/{displayCampaignId}/auction-display-line-items`	Create a new Auction Display Line Item
PATCH	`/auction-display-line-items/{lineItemId}`	Update an existing Auction Display Line Item
POST	`/accounts/{accountId}/auction-display-line-items/search`	Search and filter Auction Display Line Items
POST	`/auction-display-line-items/{lineItemId}/submit-proposal`	Submit a line item for review
POST	`/auction-display-line-items/{lineItemId}/recall-proposal`	Recall a submitted line item

Attributes

Attribute	Data Type	Description
`id` / `lineItemId`	string	Line item ID generated by the system. Writeable: No. Nullable: No
`name`*	string	Display name of the line item. Writeable: Yes. Nullable: No
`retailerId`*	string	The retailer ID where ads will serve. Cannot be changed after creation.
`campaignId`*	string	The parent Display Campaign ID. Cannot be changed after creation.
`budget`	number	Lifetime spend cap for the line item. Uncapped if omitted.
`status`*	string	Line item status. Accepted values: `active`, `inactive`.
`isActive`*	boolean	Whether the line item is actively eligible to serve.
`startDate`*	string	When the line item begins serving. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`).
`endDate`	string	When the line item stops serving. Optional; omit for no end date. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`).
`mediaType`*	string	Media type for this line item. Currently supported: `Display`, `Video`.
`pageTypes`*	array of strings	Page types where ads will be eligible to serve. Accepted values: `search`, `category`. At least one must be specified.
`productIds`	array of strings	List of product (SKU) IDs to promote. When provided, overrides dynamic SKU allocation.
`creativeIds`	array of strings	List of creative IDs to associate with this line item.
`pacing.pacingType`*	string	Controls how budget is distributed over time. Accepted values: `even`, `ahead`, `asSoonAsPossible`, `dailyBudgetCap`.
`pacing.pacingAmount`	number	Required when `pacing.pacingType` is `dailyBudgetCap`. Specifies the daily spend limit.
`bidding.bidStrategy`*	string	Bidding strategy to use. Accepted values: `manual`, `automatic`.
`bidding.manualBidding.auctionBids`	array of objects	Required when `bidding.bidStrategy` is `manual`. A bid must be specified for every page type listed in `pageTypes`.
`bidding.manualBidding.auctionBids[].pageType`	string	The page type this bid applies to. Must match a value in `pageTypes`. Accepted values: `search`, `category`.
`bidding.manualBidding.auctionBids[].bid`	number	CPM bid amount in account currency for the specified page type.
`targets`	object	Targeting configuration. Input audience IDs here.
`frequencyCapping`	object	Line item-level frequency cap. Inherits campaign-level settings if `null`.

*Required at create operation

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

Actor Differences

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

Feature	Supply Account User	Demand Brand User
`accountId` in URL	`supplyAccountId`	`demandBrandAccountId`
`companyName` / `onBehalfCompanyName`	Supported on campaigns	Not applicable
Default `frequencyCapping.cappingDurationType`	`day`	`session`
Default `pacing.pacingType`	`dailyBudgetCap`	`asSoonAsPossible`

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.

⚠️
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.

https://api.criteo.com/{version}/retail-media/campaigns/{displayCampaignId}/auction-display-line-items

Sample Request

{
  "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

{
  "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.

https://api.criteo.com/{version}/retail-media/auction-display-line-items/{lineItemId}

📘
Important Only provided fields are updated. Line items in submitted state may require recall before modification.

Sample Request

Updating Bidding Configuration

{
  "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.

{
  "data": {
    "type": "AuctionDisplayLineItem",
    "attributes": {
      "name": "Updated Line Item Name",
      "creativeIds": ["776546501968928768"]
    }
  }
}

Sample Response for the Updating of Basic Fields

{
  "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.

https://api.criteo.com/{version}/retail-media/accounts/{accountId}/auction-display-line-items/search?offset=0&limit=5

Sample Request

{
  "data": {
    "type": "AuctionDisplayLineItemSearchModel",
    "attributes": {
      "campaignId": "824391362922348544",
      "retailerId": "1392",
      "lineItemIds": [],
      "isProposal": true
    }
  }
}

⚠️
The search endpoint supports retrieving a maximum of five (5) line items per request.

Sample Response

{
  "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

Attribute	Type	Description
`campaignId`	string	Filter results to line items belonging to a specific campaign.
`retailerId`	string	Filter results to a specific retailer.
`lineItemIds`	array of strings	Filter to specific line item IDs. Pass an empty array to return all.
`isProposal`	boolean	When true, returns only line items in proposal status (pending review).

Proposal Workflow

Line items follow a lifecycle:

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

📘
Retailers who create line items will not be able to recall them, as they are automatically approved.

Submit Proposal

https://api.criteo.com/{version}/retail-media/auction-display-line-items/{lineItemId}/submit-proposal

Sample Request

{
  "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.

https://api.criteo.com/{version}/retail-media/auction-display-line-items/{lineItemId}/recall-proposal

{
  "data": {
    "type": "ProposalAction",
    "attributes": {
      "comment": "Recalling to update bid amounts."
    }
  }
}

📘
Successful responses return HTTP 204 with no body.

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

Response	Title	Detail	Troubleshooting
🟢 `200`	Success	Request processed successfully	Verify response payload
🟢 `201`	Created	Line item created successfully	N/A
🟢 `204`	No Content	Proposal action succeeded	N/A
🔴 `400`	Invalid Request	Missing or invalid fields	Check bidding, pacing, and `pageTypes`
🔴 `401`	Unauthorized	Invalid or missing token	Verify Bearer token
🔴 `403`	Forbidden	Access denied	Check permissions

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