Discard
GuidesAPI ReferenceChangelogDiscussions
GuidesAPI ReferenceChangelogDiscussionsLog In

Open Auction Line items

  • A line item holds promoted products to advertise on any single retailer
  • Line items have bid settings, start & end dates, and optional budgeting & pacing controls
  • Budgets may additionally be controlled at the campaign level
  • Several reports are available to measure line item performance
  • Campaigns are limited to 10,000 non-archived line items
  • Line items are archived automatically 90 days after their end date

Endpoints

  • GET /campaigns/{campaignId}/auction-line-items Get all Open Auction Line items from a specific Campaign
  • POST /campaigns/{campaignId}/auction-line-items Creates an Open Auction Line item
  • GET /auction-line-items/{lineItemId} Get a specific Open Auction Line item
  • PUT /auction-line-items/{lineItemId} Updates a specific Open Auction Line item

📘

  • Create operations using the POST method expect every Required (R) field; omitting Optional (O) fields will set those fields to Default values
  • Update operations using the PUT method expect every Write (W) field; omitting these fields is equivalent to setting them to null, if possible

Line Item Attributes

Attribute

Description

Values

Required

Default

Write

Nullable

id string

Line item ID

int64

campaignId string

Campaign ID

int64

Required

name string

Line item name; must be unique within a campaign

255 char limit

R

Write

targetRetailerId string

ID of the retailer the line item serves on

int64

R

startDate date

Line item start date in the account timeZone

YYYY-MM-DD

R

W

endDate date

Line item end date in the account timeZone; serves indefinitely if omitted or set to null

YYYY-MM-DD

Optional

null

W

Yes

budget number

Line item lifetime spend cap; uncapped if omitted or set to null

at least 0

O

null

W

Yes

budgetSpent number

Amount the line item has already spent

at least 0

0.0

budgetRemaining number

Amount the line item has remaining until cap is hit; null if budget is uncapped

between 0 and budget

null

Yes

monthlyPacing number

Amount the line item can spend per calendar month in the account timeZone; resets each calendar month; uncapped if omitted or set to null

at least 0

O

null

W

Yes

dailyPacing number

Amount the line item can spend per day in the account timeZone; resets each day; overwritten by a calculation if isAutoDailyPacing is configured; uncapped if omitted or set to null

at least 0

O

null

W

Yes

isAutoDailyPacing boolean

To activate, either line item endDate and budget, or monthlyPace, must be specified; overwrites dailyPacing with a calculation if not set prior

true, false

R

false

W

bidStrategy enum

Bid algorithm optimizing for sales conversions, sales revenue, or clicks

conversion, revenue, clicks

O

conversion

W

targetBid number

If optimizing for conversion or revenue, a target average amount to bid because each bid is modulated up or down by our optimization algorithm; bids stay constant if optimizing for clicks; must meet minBid for line item to serve; minBid depends on selected products and is retrieved through the catalogs; input excludes platform fees

at least the greatest value of minBid across all products on the line item

R

0.3

W

maxBid number

If optimizing for conversion or revenue, the maximum amount allowed to bid for each bid; respected regardless of targetBid; must meet minBid for line item to serve; minBid depends on selected products and is retrieved through the catalogs; bidding is uncapped if omitted or set to null; does not apply if optimizing for clicks; input excludes platform fees

at least 0.01

O

null

W

Yes

status enum

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

active, paused, scheduled, ended, budgetHit, noFunds, draft, archived

W

createdAt timestamp

Timestamp in UTC of line item creation

ISO-8601

updatedAt timestamp

Timestamp in UTC of last line item update

ISO-8601

Create an Open Auction Line Item

This endpoint creates a new open auction line item in the specified campaign.

https://api.criteo.com/2022-04/retail-media/campaigns/{campaignId}/auction-line-items

Sample Request

curl -X POST "https://api.criteo.com/2022-04/retail-media/campaigns/8343086999167541140/auction-line-items" \
    -H "Authorization: Bearer myaccesstoken" \
    -H "Content-Type: application/json" \
    -d '{
            "data": {
                "type": "RetailMediaLineItem",
                "attributes": {
                    "name": "My New Line Item",
                    "targetRetailerId": "18159942378514859684"
                }
            }
        }'

Sample Response

{
    "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,
            "monthlyPacing": null,
            "dailyPacing": null,
            "isAutoDailyPacing": false,
            "bidStrategy": "conversion",
            "targetBid": 0.30,
            "maxBid": null,
            "status": "draft",
            "createdAt": "2020-04-06T06:11:23+00:00",
            "updatedAt": "2020-04-06T06:11:23+00:00"
        }
    }
}

Get All Open Auction Line Items

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

https://api.criteo.com/2022-04/retail-media/campaigns/{campaignId}/auction-line-items

Sample Request

curl -X GET "https://api.criteo.com/2022-04/retail-media/campaigns/8343086999167541140/auction-line-items" \
    -H "Authorization: Bearer myaccesstoken"

Sample Response

{
    "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,
                "monthlyPacing": null,
                "dailyPacing": null,
                "isAutoDailyPacing": false,
                "bidStrategy": "conversion",
                "targetBid": 1.50,
                "maxBid": 2.50,
                "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,
                "monthlyPacing": 1000.00,
                "dailyPacing": 33.33,
                "isAutoDailyPacing": true,
                "bidStrategy": "conversion",
                "targetBid": 0.75,
                "maxBid": 1.25,
                "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/2022-04/retail-media/campaigns/8343086999167541140/line-items?pageIndex=1&pageSize=25",
        "previousPage": null
    }
}

Get a Specific Open Auction Line Item

This endpoint retrieves the specified open auction line item

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

Sample Request

curl -X GET "https://api.criteo.com/2022-04/retail-media/auction-line-items/2465695028166499188" \
    -H "Authorization: Bearer myaccesstoken"

Sample Response

{
    "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,
            "monthlyPacing": null,
            "dailyPacing": null,
            "isAutoDailyPacing": false,
            "bidStrategy": "conversion",
            "targetBid": 0.30,
            "maxBid": null,
            "status": "draft",
            "createdAt": "2020-04-06T06:11:23+00:00",
            "updatedAt": "2020-04-06T06:11:23+00:00"
        }
    }
}

Update a Specific Open Auction Line Item

This endpoint updates the specified open auction line item. In this example, we enable auto daily pacing by setting a monthly pace simultaneously. Note that with auto daily pacing enabled, daily pacing is automatically calculated and overwrites its previous value, if any. Also, note the draft state of the line item because products to be promoted have not yet been added.

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

Sample Request

curl -X PUT "https://api.criteo.com/2022-04/retail-media/auction-line-items/2465695028166499188" \
    -H "Authorization: Bearer myaccesstoken" \
    -H "Content-Type: application/json" \
    -d '{
            "data": {
                "type": "RetailMediaLineItem",
                "id": "2465695028166499188",
                "attributes": {
                    "name": "My New Line Item",
                    "startDate": "2020-04-06",
                    "endDate": null,
                    "budget": null,
                    "monthlyPacing": 3000.00,
                    "dailyPacing": null,
                    "isAutoDailyPacing": true,
                    "bidStrategy": "conversion",
                    "targetBid": 0.30,
                    "maxBid": null,
                    "status": "active"
                }
            }
        }'

Sample Response

{
    "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,
            "monthlyPacing": 3000.00,
            "dailyPacing": 120.00,
            "isAutoDailyPacing": true,
            "bidStrategy": "conversion",
            "targetBid": 0.30,
            "maxBid": null,
            "status": "draft",
            "createdAt": "2020-04-06T06:11:23+00:00",
            "updatedAt": "2020-04-06T06:17:48+00:00"
        }
    }
}

What’s Next
Did this page help you?