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.
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).
Note: Each token is valid for 5 minutes. Should your token expire, you will receive a 401 HTTP response status code.
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 Feed 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 feed.
Tip: A seller becomes active once you send us available products through the feed & both their bid and budget.
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
Tip: You can retrieve the full list of sellers with their status (active/inactive) by issuing a GET call to the seller’s endpoint, providing your Criteo Reseller Program campaign identifier (CampaignID) as a parameter.
A seller is:
- Active if: it has a budget and a bid and at least one product in the catalog
- Inactive if:
- in its initial status, you’ve declared the sellerName in the Product Feed and not declared yet any budget and/or bid,
- it has no active budget (see later budgetStatus).
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 feed. However, this will only take effect once Criteo completes feed & category ingestion. Furthermore adding it back will also take more time since it will also require a new feed & category ingestion. Finally, once the seller is removed from the feed, 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 feed 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.
Tip: If you already work with Criteo, you can duplicate the feed you have already provided us, making sure the sellers’ unique identifier is available in the sellers’ field.
Your campaign will be automatically created from the moment your feed 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
Note: Any seller budget that has a status = Inactive cannot be reactivated. If you want to relaunch a seller whose status has been set to Inactive, you will need to create a new budget (see the section “Creating a new Budget”).
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
- 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.
In case your seller wants to decrease its CPC, you must issue a POST call to the /v1/sellers/bids endpoint.
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
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)
Important note: Please note that any budget decrease will be taken into account instantly with the following impact:
- Seller will be stopped for the specific seller instantly for the rest of the day,
- Seller will restart the following day 00:00 UTC time with the new budget set.
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 feed with the new sellerName
- Initialize your seller's bid and budget by sending us a PUT /v1/sellers/bids & POST /v1/sellers/budgets instruction.
Note: You will be able to retrieve the statistics of the former sellerName from the statistics endpoint.
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.
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.
- Seller – Mandatory