Criteo REST API for Resellers

Below, you will find the key concepts of the Criteo Reseller Program REST API which allow you to manage campaigns bids and budgets at the sellers level.

API AUTHENTICATION

We use JWT to provide token-based authentication system to our REST API. In order to issue calls to our API, you will need to pass a token on to any of these calls.

To get your token, you will need to issue a POST call to the /oauth2/token endpoint, with client_id and client secret as parameters (see Getting Started section).

RETRIEVING THE AdvertiserID

Retrieve your AdvertiserID by issuing a GET call to the /portfolio/ endpoint.

RETRIEVING THE CampaignID

Retrieve your CampaignID by issuing a GET call to the /sellers/endpoint.

ONBOARDING A SELLER IN THE CRITEO RESELLER PROGRAM

To onboard a new seller, you will need to make sure he is properly flagged in the product catalog you've previously shared with Criteo.
To make sure your seller is properly flagged, you will need to set the seller name column to the seller unique identifier, which is the seller name for each of your seller’s products provided in the catalog.

After the steps above, you will be able to send us your sellers’ budget and bids thanks to the sellers' endpoints described previously, especially:

PUT /v1/sellers/bids to send us the sellers’ CPC
POST /v1/sellers/budgets to send us the seller’s budget

REMOVING A SELLER'S DATA FROM THE CRITEO RESELLER PROGRAM

If you want to remove a seller from the Criteo Reseller Program, you just need to stop this seller inside the campaign (see the section “How do I stop a seller”).

Alternatively, you can also remove the products of the seller from your product catalog. However, this will only take effect once Criteo completes catalog & category ingestion. Furthermore adding it back will also take more time since it will also require a new catalog & category ingestion. Finally, once the seller is removed from the catalog, statistics for this seller won’t be available anymore.

STARTING A CAMPAIGN

To start a Criteo Reseller Program campaign, you must provide us with a dedicated product catalog containing products from all sellers on-boarded in the program. Note that each of these products should have the seller’s unique identifier in the seller field.

Your campaign will be automatically created from the moment your catalog is ingested.
To go live, your campaign needs at least one seller with budget and bid already set. You can send them through PUT /v1/sellers/bids and POST /v1/sellers /budgets endpoints.

STOPPING AN ACTIVE CAMPAIGN

To stop your whole Criteo Reseller Program campaign (for all sellers) please contact your Account Manager.

PAUSING A SPECIFIC SELLER

To stop one or more sellers inside your campaign, you must set their budgets as “Inactive”. Once this is done, the system will stop showing ads for these seller’s products.

To set a budget as “Inactive” you must issue a PUT call to the /sellers/budgets endpoint as described below:

PUT /sellers/budgets with status = Inactive

STOPPING A SELLER WHOSE BUDGET IS ALMOST COMPLETELY CONSUMED

There is nothing to do on your side. We anticipate the budget depletion of all sellers and stop their campaigns whenever they are running out of budget.

SETTING BUDGETS AND CPCs

To set budget and CPC for a specific seller, you need to use the following endpoints:

Bids: for initialization and update: issue a PUT call to the /sellers/bids endpoint
Budgets:
- For initialization: issue a POST call to the /v1/sellers/budgets endpoint
- For budget update: issue a PUT call to the /v1/sellers/budgets endpoint

INCREASING BUDGETS AND CPCs

To increase a budget and CPC for a specific seller, you must issue a PUT call to the /v1/sellers/budgets and /v1/sellers/bids endpoints.

DECREASING CPCs

In case your seller wants to decrease its CPC, you must issue a POST call to the /v1/sellers/bids endpoint.

DECREASING BUDGETS

If your seller wants to decrease its budget, you will need to set the current status to Inactive - this will stop the displays on the current budget on the day (D) you perform the action. After this, you can create a new budget with the decreased value (see “How to create a new Budget section”) This will start(D+1), UTC time

Example:

Day 0, seller A has initially set a budget amount of $1000 on its Criteo Reseller Program campaign.

Day 2, seller A still has $800 of budget BUT decides to reduce its available budget to $500.

Then you must issue the following calls:

PUT call to the /sellers/budgets/ endpoint
- Set status to Inactive
- (No need to precise any budget amount here, status has priority)
POST call to the /sellers/budgets endpoint

Set amount to 500
(No need to provide any status here; if it’s left empty, we assume it will be Active)

CREATING BUDGETS

You can create a new budget if one of two cases :

You don’t have a budget for the current day
You have have an incactive budget for the current day

To create a new Budget for a seller, you will need to issue

POST call to the /sellers/budgets endpoint

The new Budget will take effect either :

Right now if you don’t have any budget for the current day
Tomorrow if you have an inactive budget for the current day

FIXING WRONGLY INPUTTED BUDGETS

First, you will need your seller to provide you with the updated budget.
Then, there are three main scenarios that lead to different actions:

You already have the new budget and it is lower than the initial budget set:
- Apply actions described section How do I decrease a budget/CPC
You already have the new budget and it is greater than the initial budget set:
- Apply the actions described in the section "Increasing a budget/CPC"
You do not have the new/right budget:
- Apply actions explained in the section How can I remove a seller

FIXING WRONGLY INPUTTED CPCs

First, you will need your seller to provide you with the updated CPC. You should then issue a PUT call to the sellers/bids/ endpoint to set the updated bid.

WHAT IF MY SELLER CHANGED THEIR NAME ON MY PLATFORM?

As our API essentially relies on sellerName to manage bids and budgets, any change in seller name will automatically create a new entry in our system, not linked to the previous seller name.
In a nutshell, if a seller changes its name on your platform, you will need to:

Update your product catalog with the new sellerName
Initialize your seller's bid and budget by sending us a PUT /v1/sellers/bids & POST /v1/sellers/budgets instruction.

ANALYZING SELLERS' SPENT BUDGETS

To get a view of the spent budget for a dedicated seller on a Criteo Reseller Program campaign, issue a GET call to the /v1/sellers endpoint. The information will be available as spentAmount.

ANALYZING REMAINING BUDGETS FOR SELLERS

To get a view of the spent budget for a dedicated seller on a Criteo Reseller Program campaign, issue a GET call to the /v1/sellers endpoint. The information will be available as remainingAmount.

REPORTING

You can issue a POST call to the /v1/sellers/stats endpoint. It is only possible to access impressions, clicks and cost at the seller level, available up to a daily granularity.

A maximum of 3 dimensions can be used and must contain the seller dimension.

Available dimensions:

AdvertiserID
CampaignID
Seller – Mandatory
Year
Week
Day

Available metrics:

Displays
Clicks
AdvertiserCost