GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelogLog In
These docs are for v2022.07. Click to read the latest docs for v2024.04.

Campaigns Endpoints

View and manage all your campaigns

Suggest Edits

📝

A FEW THINGS TO KNOW

Learn more about campaign management with our API Here!

 

Endpoints

VerbEndpointDescription
POST /accounts/{accountId}/campaignsCreate a Campaign
GET /accounts/{accountId}/campaignsGet All Campaigns
GET /campaigns/{campaignId}Get a Specific Campaign
PUT /campaigns/{campaignId}Update a Specific Campaign

 

📘

Info

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

 

Campaign Attributes

id

    Data Type: string

    Description: Campaign ID

    Accepted Value: int64

    Default Values: None

    Write? No

    Nullable? No


accountId Required

    Data Type: string

    Description: Account ID

    Accepted Value: int64

    Default Value: None

    Write? No

    Nullable? No


name Required

    Data Type: string

    Description: Campaign name; must be unique within an account

    Values: 255 char limit

    Default Value: None

    Write? Yes

    Nullable? No


type Optional

    Data Type: enum

    Description: Campaing type

    Accepted Values: auction,preferred

    Default Value: auction

    Write? None other than the accepted values

    Nullable? No - if attribute is passed in the call, a value must be specified


budget Optional

    Data Type: number

    Description: Campaign lifetime spend cap; uncapped if omitted or set to null.
    - Optional when campaignType = auction
    - Mandatory when campaignType = preferred

    Accepted Values: at least 0

    Default Value: null

    Write? Yes

    Nullable? Yes


budgetSpent Optional

    Data Type: number

    Description: Amount the campaign has already spent

    Accepted Values: at least 0

    Default Value: 0.0

    Write? No

    Nullable? No


budgetRemaining

    Data Type: number

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

    Accepted Values: between 0 and budget Amount

    Default Value: null

    Write? No

    Nullable? Yes


clickAttributionWindow Required

    Data Type: enum

    Description: Post-click attribution window

    Accepted Values: 7D,14D, 30D

    Default Value: 30D

    Write? Yes

    Nullable? No


viewAttributionWindow Required

    Data Type: enum

    Description: Post-click attribution scope

    Accepted Values: samesku, sameskucategory, sameskucategorybrand

    Default Value: sameskucategory

    Write? None other than the accepted values

    Nullable? No


viewAttributionScope

    Data Type: enum

    Description: Post-view attribution scope

    Accepted Values: samesku, sameskucategory, sameskucategorybrand

    Default Value: sameskucategory

    Write? None other than the accepted values

    Nullable? No


promotedBrandIds

    Data Type: string array

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

    Accepted Values: list of brandId

    Default Value: [ ]

    Write? No

    Nullable? No


drawableBalanceIds

    Data Type: string array

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

    Accepted Values: list of balanceId

    Default Value: [ ]

    Write? No

    Nullable? No


status

    Data Type: enum

    Description: Campaign status, derived from the status of line items it holds; active if at least one line item is active. To understand the conditions that will cause a status to change, check out our status page

    Accepted Values: active, inactive

    Default Value: inactive

    Write? No

    Nullable? No


createdAt

    Data Type: timestamp

    Description: Timestamp in UTC of campaign creation

    Accepted Values: -ISO-8601

    Default Value: None

    Write? No

    Nullable? No


createdAt

    Data Type: timestamp

    Description: Timestamp in UTC of last campaign update

    Accepted Values: ISO-8601

    Default Value: None

    Write? No

    Nullable? No

 

Create a Campaign

This endpoint creates a new campaign in the specified account.

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

Sample Request 

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

import requests
import json

url = "https://api.criteo.com/2022-07/retail-media/accounts/4/campaigns"

payload = json.dumps({
  "data": {
    "type": "<string>",
    "attributes": {
      "name": "New API Campaign",
      "type": "auction",
      "clickAttributionWindow": "30D",
      "budget": "2.00",
      "clickAttributionScope": "samesku"
    }
  }
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");

RequestBody body = RequestBody.create(mediaType, "{\n  \"data\": {\n    \"type\": \"<string>\",\n    \"attributes\": {\n      \"name\": \"New API Campaign\",\n      \"type\": \"auction\",\n      \"clickAttributionWindow\": \"30D\",\n            \"budget\": \"2.00\",\n      \"clickAttributionScope\": \"samesku\"\n\n    }\n  }\n}");

Request request = new Request.Builder()
  .url("https://api.criteo.com/2022-07/retail-media/accounts/4/campaigns")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
  .build();

Response response = client.newCall(request).execute();

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/2022-07/retail-media/accounts/4/campaigns');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
));
$request->setBody('{\n  "data": {\n    "type": "<string>",\n    "attributes": {\n      "name": "New API Campaign",\n      "type": "auction",\n      "clickAttributionWindow": "30D",\n            "budget": "2.00",\n      "clickAttributionScope": "samesku"\n\n    }\n  }\n}');
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 

{
    "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-07/retail-media/accounts/{accountId}/campaigns

Sample Request 

curl -X GET "https://api.criteo.com/2022-07/retail-media/accounts/18446744073709551616/campaigns" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>"

import requests

url = "https://api.criteo.com/2022-07/retail-media/accounts/4/campaigns"

payload={}
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

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/2022-07/retail-media/accounts/4/campaigns")
  .method("GET", body)
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
  .build();

Response response = client.newCall(request).execute();

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/2022-07/retail-media/accounts/4/campaigns');
$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 

{
    "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-07/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-07/retail-media/campaigns/{campaignId}

Sample Request 

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

import requests

url = "https://api.criteo.com/2022-07/retail-media/campaigns/1280"

payload={}
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

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/2022-07/retail-media/campaigns/1280")
  .method("GET", body)
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
  .build();

Response response = client.newCall(request).execute();

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/2022-07/retail-media/campaigns/1280');
$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 

{
    "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-07/retail-media/campaigns/{campaignId}

Sample Request 

curl -X PUT "https://api.criteo.com/2022-07/retail-media/campaigns/8343086999167541140" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>" \
    -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"
                }
            }
        }'

import requests
import json

url = "https://api.criteo.com/2022-07/retail-media/campaigns/76216196459831296"

payload = json.dumps({
  "data": {
    "type": "RetailMediaCampaign",
    "id": "76216196459831296",
    "attributes": {
      "name": "api campaign",
      "budget": None,
      "clickAttributionWindow": "30D",
      "viewAttributionWindow": "1D",
      "clickAttributionScope": "sameskucategory",
      "viewAttributionScope": "sameskucategory"
    }
  }
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();

MediaType mediaType = MediaType.parse("application/json");

RequestBody body = RequestBody.create(mediaType, "{\n            \"data\": {\n                \"type\": \"RetailMediaCampaign\",\n                \"id\": \"76216196459831296\",\n                \"attributes\": {\n                    \"name\": \"api campaign\",\n                    \"budget\": null,\n                    \"clickAttributionWindow\": \"30D\",\n                    \"viewAttributionWindow\": \"1D\",\n                    \"clickAttributionScope\": \"sameskucategory\",\n                    \"viewAttributionScope\": \"sameskucategory\"\n                }\n            }\n        }");

Request request = new Request.Builder()
  .url("https://api.criteo.com/2022-07/retail-media/campaigns/76216196459831296")
  .method("PUT", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
  .build();

Response response = client.newCall(request).execute();

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/2022-07/retail-media/campaigns/76216196459831296');
$request->setMethod(HTTP_Request2::METHOD_PUT);
$request->setConfig(array(
  'follow_redirects' => TRUE
));

$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
));

$request->setBody('{\n            "data": {\n                "type": "RetailMediaCampaign",\n                "id": "76216196459831296",\n                "attributes": {\n                    "name": "api campaign",\n                    "budget": null,\n                    "clickAttributionWindow": "30D",\n                    "viewAttributionWindow": "1D",\n                    "clickAttributionScope": "sameskucategory",\n                    "viewAttributionScope": "sameskucategory"\n                }\n            }\n        }');
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 

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

Responses

ResponseDescription
🔵 200Call completed with success
🔵 201Campaign was created successfully
🔴 400Validation Error - one ore more required field was not found. Confirm if all required fields are present in the API call

Updated almost 2 years ago

What’s Next