Discard
GuidesAPI ReferenceChangelogDiscussions
GuidesAPI ReferenceChangelogDiscussionsLog In

Campaigns

  • A campaign represents a marketing objective and contains line items
  • Campaigns may hold line items across multiple brands and retailers
  • Campaigns have optional budgeting and attribution window controls
  • Budgets may additionally be controlled at the line item level
  • Several reports are available to measure campaign performance
  • Accounts are limited to 100,000 active campaigns
  • Currently, only Open Auction campaigns are supported through the API

Endpoints

  • POST /accounts/{accountId}/campaigns Create a Campaign
  • GET /accounts/{accountId}/campaigns Get All Campaigns
  • GET /campaigns/{campaignId} Get a Specific Campaign
  • PUT /campaigns/{campaignId} Update a Specific Campaign

📘

  • 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

Campaign Attributes

Attribute

Description

Values

Required

Default

Write

Nullable

id string

Campaign ID

int64

accountId string

Account ID

int64

Required

name string

Campaign name; must be unique within an account

255 char limit

R

Write

type enum

Campaign type

auction, preferred

Optional

auction

budget number

Campaign lifetime spend cap; uncapped if omitted or set to null,
Optional when campaignType = auction

Mandatory when campaignType = preferred

at least 0

O

null

W

Yes

budgetSpent number

Amount the campaign has already spent

at least 0

0.0

budgetRemaining number

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

between 0 and budget

null

Yes

clickAttributionWindow enum

Post-click attribution window

7D, 14D, 30D

R

30D

W

viewAttributionWindow enum

Post-view attribution window

none, 1D, 7D, 14D, 30D

R

1D

W

clickAttributionScope enum

Post-click attribution scope

samesku, sameskucategory, sameskucategorybrand

sameskucategory

viewAttributionScope enum

Post-view attribution scope

samesku, sameskucategory, sameskucategorybrand

sameskucategory

promotedBrandIds string array

Set of brands represented in line items of the campaign; note this set is append only

list of brandId

[]

drawableBalanceIds string array

List of balances the campaign is able to draw from; at least one balance is required for a campaign to begin

list of balanceId

[]

status enum

Campaign status, derived from the status of line items it holds; active if at least one line item is active

active, inactive

inactive

createdAt timestamp

Timestamp in UTC of campaign creation

ISO-8601

updatedAt timestamp

Timestamp in UTC of last campaign update

ISO-8601

Create a Campaign

This endpoint creates a new campaign in the specified account.

https://api.criteo.com/2022-04/retail-media/accounts/{accountId}/campaigns

Sample Request

curl -X POST "https://api.criteo.com/2022-04/retail-media/accounts/18446744073709551616/campaigns" \
    -H "Authorization: Bearer myaccesstoken" \
    -H "Content-Type: application/json" \
    -d '{
            "data": {
                "type": "RetailMediaCampaign",
                "attributes": {
                    "name": "My New Campaign"
                }
            }
        }'

Sample Response

{
    "data": {
        "type": "RetailMediaCampaign",
        "id": "3683145960016759663",
        "attributes": {
            "accountId": "18446744073709551616",
            "name": "My New Campaign",
            "type": "auction",
            "promotedBrandIds": [],
            "drawableBalanceIds": [],
            "budget": null,
            "budgetSpent": 0.00,
            "budgetRemaining": null,
            "clickAttributionWindow": "30D",
            "viewAttributionWindow": "1D",
            "clickAttributionScope": "sameSkuCategory",
            "viewAttributionScope": "sameSkuCategory",
            "status": "inactive",
            "createdAt": "2020-06-03T14:17:57+00:00",
            "updatedAt": "2020-06-03T14:17:57+00:00"
        }
    }
}

Get All Campaigns

This endpoint lists all campaigns in the specified account. Results are paginated.

https://api.criteo.com/2022-04/retail-media/accounts/{accountId}/campaigns

Sample Request

curl -X GET "https://api.criteo.com/2022-04/retail-media/accounts/18446744073709551616/campaigns" \
    -H "Authorization: Bearer myaccesstoken"

Sample Response

{
    "data": [
        {
            "type": "RetailMediaCampaign",
            "id": "8343086999167541140",
            "attributes": {
                "accountId": "18446744073709551616",
                "name": "Campaign 123",
                "type": "auction",
                "promotedBrandIds": ["7672171780147256541",
                                     "5979998329674492121"],
                "drawableBalanceIds": ["14094543095747588032"],
                "budget": 100000.00,
                "budgetSpent": 6172.33,
                "budgetRemaining": 93827.67,
                "clickAttributionWindow": "30D",
                "viewAttributionWindow": "none",
                "clickAttributionScope": "sameSkuCategory",
                "viewAttributionScope": "sameSkuCategory",
                "status": "active",
                "createdAt": "2020-04-06T13:01:07+00:00",
                "updatedAt": "2020-06-03T11:37:53+00:00"
            }
        },
 
        // ...
 
        {
            "type": "RetailMediaCampaign",
            "id": "16108177282234788969",
            "attributes": {
                "accountId": "18446744073709551616",
                "name": "Campaign 789",
                "type": "auction",
                "promotedBrandIds": ["5979998329674492121"],
                "drawableBalanceIds": [],
                "budget": null,
                "budgetSpent": 0.00,
                "budgetRemaining": null,
                "clickAttributionWindow": "7D",
                "viewAttributionWindow": "1D",
                "clickAttributionScope": "sameSkuCategory",
                "viewAttributionScope": "sameSkuCategory",
                "status": "inactive",
                "createdAt": "2020-04-06T23:47:11+00:00",
                "updatedAt": "2020-04-06T23:47:11+00:00"
            }
        }
    ],
    "metadata": {
        "totalItemsAcrossAllPages": 95,
        "currentPageSize": 25,
        "currentPageIndex": 0,
        "totalPages": 4,
        "nextPage": "https://api.criteo.com/2022-04/retail-media/accounts/18446744073709551616/campaigns?pageIndex=1&pageSize=25",
        "previousPage": null
    }
}

Get a Specific Campaign

This endpoint retrieves the specified campaign.

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

Sample Request

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

Sample Response

{
    "data": {
        "type": "RetailMediaCampaign",
        "id": "8343086999167541140",
        "attributes": {
            "accountId": "18446744073709551616",
            "name": "Campaign 123",
            "type": "auction",
            "promotedBrandIds": ["7672171780147256541",
                                 "5979998329674492121"],
            "drawableBalanceIds": ["14094543095747588032"],
            "budget": 100000.00,
            "budgetSpent": 6172.33,
            "budgetRemaining": 93827.67,
            "clickAttributionWindow": "30D",
            "viewAttributionWindow": "none",
            "clickAttributionScope": "sameSkuCategory",
            "viewAttributionScope": "sameSkuCategory",
            "status": "active",
            "createdAt": "2020-04-06T13:01:07+00:00",
            "updatedAt": "2020-06-03T11:37:53+00:00"
        }
    }
}

Update a Specific Campaign

This endpoint updates the specified campaign. In this example, we switch to an uncapped campaign budget and update the post-view attribution window.

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

Sample Request

curl -X PUT "https://api.criteo.com/2022-04/retail-media/campaigns/8343086999167541140" \
    -H "Authorization: Bearer myaccesstoken" \
    -H "Content-Type: application/json" \
    -d '{
            "data": {
                "type": "RetailMediaCampaign",
                "id": "8343086999167541140",
                "attributes": {
                    "name": "Campaign 123",
                    "budget": null,
                    "clickAttributionWindow": "30D",
                    "viewAttributionWindow": "1D",
                    "clickAttributionScope": "sameskucategory",
                    "viewAttributionScope": "sameskucategory"
                }
            }
        }'

Sample Response

{
    "data": {
        "type": "RetailMediaCampaign",
        "id": "8343086999167541140",
        "attributes": {
            "accountId": "18446744073709551616",
            "name": "Campaign 123",
            "type": "auction",
            "promotedBrandIds": ["7672171780147256541",
                                 "5979998329674492121"],
            "drawableBalanceIds": ["14094543095747588032"],
            "budget": null,
            "budgetSpent": 6172.33,
            "budgetRemaining": null,
            "clickAttributionWindow": "30D",
            "viewAttributionWindow": "1D",
            "clickAttributionScope": "sameSkuCategory",
            "viewAttributionScope": "sameSkuCategory",
            "status": "active",
            "createdAt": "2020-04-06T13:01:07+00:00",
            "updatedAt": "2020-06-03T14:23:28+00:00"
        }
    }
}

What’s Next
Did this page help you?