Guide Change Log
|V1.0||November 2017||First version released.|
|V1.1||March 2018||Impressions level in reporting added to guide.|
|V1.2||September 2018||New filtering options added to guide.|
Preview of API guide V2 so our clients can organize accordingly. Included in this guide are details about the new daily budget feature.
About this document
Here, you’ll discover our main features that allow you – on behalf of your sellers - to:
- Create and update budgets
- Create and update bids (CPC)
- Stop your sellers
- Get statistics for your sellers
To use our REST API, you will need to create a new API User in Management Center. You can access this platform at: https://marketing.criteo.com/
When logged in:
- Click on Setup > Users
- Click on CREATE API USER
- You will then need to enter a contact Email address and select one of the following roles: View only, Business Manager, Financial Manager. To use our API, please pick the Business Manager role. The View only and Financial Manager roles don’t have enough privileges to input and pull data through our API.
- When done, click Add user. You will receive a confirmation message, your Client ID and Client Secret. Store them carefully as you will need them to post requests to our API.
All amounts expressed in the Criteo REST API are expressed in your local currency, including:
- Performance numbers (e.g. COS, Spend, …),
- Budgets and bids
NOTE: You can check your local currency in our Management Center interface. Under “Setup,” select “Users” and select the desired user.
All dates in the Criteo REST API are shown in Coordinated Universal Time (UTC).
Remaining budget and statistics are not real time and can have up to a few hours of delay. Hence a seller can be inactive while their remaining amount is still decreasing. The sellers’ ads are not displayed anymore, but the remaining budget is decreasing as data is catching up.
API usage recommendations
When updating large batches of budgets or bids, you should implement these changes in separated, batched API calls as opposed to many individual calls as this may lead to throttling.
One call should be marked for bids, and another call for budgets. Both calls will contain the correct bids per campaigns and budgets for the given or multiple campaigns.
EXAMPLE: You need to set bids and budgets for 10 different sellers. We recommend you send 1 API call for seller-campaign endpoint and 1 call for budgets endpoint, with both containing respective sellers desired bids and budgets.
All technical components and endpoints are new to this V2 documentation. For comparison purposes, our V1 swagger is available here:
In this Swagger, you’ll find the below endpoints:
- Authentication: allows you to get a token. For security purposes, the token is valid for a duration of 5 minutes.
- Portfolio: allows you to retrieve basic information such as your AdvertiserID & Advertiser Name
- GET /v2/crp/sellers: getting basic sellers information
- POST /v2/crp/statistics: getting basic campaign statistics
- GET /v2/crp/budgets : get status and remaining amount per budget
- POST /v2/crp/budgets: create budget per seller
- PUT /v2/crp/budgets : update budget per seller
- GET/v2/crp/seller-campaign : getting seller information regarding seller bid for the campaign
- PUT /v2/crp/seller-campaigns : provide a bid (CPC) for the seller for the campaign
Please note that both Sellers and Sellers-campaign are automatically created based on catalog import, thus we don’t offer POST calls for them.
EXAMPLE: This swagger links to Criteo production environment. Any test applied there will thus impact real campaigns.
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.
How do I authenticate the API?
Criteo uses 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.
How do I retrieve my Advertiser ID?
Retrieve your AdvertiserID by issuing a GET call to the /portfolio/ endpoint.
How do I retrieve my Catalog ID?
Retrieve your CatalogID by issuing a GET call to the /v2/crp/sellers endpoint.
How do I retrieve my Campaign ID?
Retrieve your CampaignID by issuing a GET call /v2/crp/seller-campaigns endpoint.
How can I onboard a Seller in the Criteo Reseller's program?
Step 1: To onboard a new seller, you will need to make sure they are 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.
From there, sellers will be on-boarded and seller-campaigns will be created for any of your CRP campaigns.
Step 2: You can get the seller ID and seller-campaign ID via GET /v2/crp/seller-campaigns
Step 3: You will be able to send us your sellers’ budget and bids thanks to the sellers endpoints described previously, especially:
- POST /v2/crp/budgets
- PUT /v2/crp/seller-campaigns to provide the seller’s cpc per seller-campaign
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 catalog id (catalogId) as a parameter.
How can I remove a seller's data from Criteo Resellers Program?
If you want to remove a seller from the Criteo Reseller Program, you need to stop the budget of this seller, issuing a PUT /v2/crp/budgets with status = STOPPED.
Alternatively, you can remove the products of the seller from your product feed. However, this will only take effect once Criteo completes feed & sellers ingestion. Furthermore, adding it back will take more time as it will require a new feed & sellers ingestion. We don’t recommend this alternative.
Removing the seller from the feed won’t impact the statistics on this seller.
How do I start a campaign?
Before you can start a Criteo Reseller Program campaign, you must provide us with a 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. 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. However, we don’t recommend starting with such a low level of sellers. CRP campaigns are designated to scale hundreds and thousands of sellers.
TIP: If you already work with Criteo, you have these options:
- Recommended: You can update your current feed by adding sellers' information in the sellers’ field ( if you currently don’t use 3 categories).
- Alternatively, you can duplicate the feed you have already provided us, making sure the sellers’ unique identifier is available in the sellers’ field.
- In this case, please discuss invoicing for your campaign. Ideally it is better if we can integrate this new CRP campaign to your current billing.
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. However, we don’t recommend starting with such a low level of sellers. CRP campaigns are designated to scale hundreds and thousands of sellers.
You can send them through POST /v2/crp/budgets and put /v2/crp/seller-campaigns.
How do I stop a campaign?
To stop your whole Criteo Reseller Program campaign (for all sellers) please contact your Account Manager.
How do I stop a seller?
To stop one or more sellers inside your campaign, you must set their budgets as “STOPPED”.
Once this is done, the system will stop showing ads for these seller’s products.
To set a budget as “STOPPED” you must issue a PUT call to the /sellers/budgets endpoint as PUT /v2/crp/budgets with status = STOPPED.
NOTE: Any seller budget that has a STOPPED status cannot be reactivated. If you want to relaunch a seller whose status has been set to STOPPED, you will need to create a new budget (see section “How to create a new Budget”).
If you stop the budget, you may see a decrease on the budget stops as statistics may take few hours to be updated. For example, if you stop your budget at $10 USD, your ads will stop running but there may be some residual spend. Therefore, you may end up with $9.50 USD.
What should I do for a seller whose budget is almost completely gone?
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.
How do I set budgets and CPCs?
To set budget and CPCs for a specific seller, you need to use the following endpoints:
- For initialization: issue a POST call to the /v2/crp/budget
- For update: issue a PUT call to the /v2/crp/budget endpoint
- For initialization: issue a POST call to the /v2/crp/budget
- CPCs: for initialization and update: issue a PUT call to the /v2/crp/seller-campaign endpoint
How do I increase a budget/CPC?
To increase a budget and CPC for a specific seller, you must issue a PUT call to the /v2/crp/budget and v2/crp/seller-campaign.
How do I decrease a CPC?
In case your seller wants to decrease its CPC, you must issue a POST call to the v2/crp/seller-campaign endpoint.
How do I decrease a budget?
If your seller wants to decrease its budget, you will need to set the current budget’s status to STOPPED - 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 of $1000.
Day 2, seller A still has $800 of budget but decides to reduce their available budget to $500.
Then you must issue the following calls:
- PUT call to the /v2/crp/budgets endpoint
- Set status to STOPPED
- (No need to precise any budget amount here, status has priority)
- POST call to the /v2/crp/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 instantly for the rest of the day for any campaigns they may run.
- Seller will restart the following day 00:00 UTC time with the new budget set for any campaigns they may run
How do I create a new budget?
You can create a new budget if one of two cases is true:
- You don’t have any budget running for the current day for this seller. Our budgets cannot overlap.
- You have a DEPLETED budget for this seller.
To create a new Budget for a seller, you will need to issue:
- POST call to the/v2/crp/budgets endpoint
The new Budget will take effect either:
- Today if budget has not yet been defined for the sellers.
- Tomorrow if budget already exists.
One of my seller's mistakenly set the wrong budget. How do I fix it?
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 in 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 section "How do I increase a budget/CPC?".
- You do not have the new/right budget:
- Apply the actions explained in the section "How can I remove a seller?".
One of my sellers mistakenly set a bid. How can I fix it?
First, you will need your seller to provide you with the updated CPC. You should then issue a PUT call to the /v2/crp/seller-campaigns endpoint to set the updated bid.
What if one of my sellers changed the 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 /v2/crp/seller-campaigns & POST /v2/crp/budgets
NOTE: You will be able to retrieve the statistics of the former sellerName from the statistics endpoint.
How can I see my seller's spent budget?
To get a view of the spent budget for a dedicated seller on a Criteo Reseller Program campaign, issue a GET call to the /v2/crp/budgets. The information will be available as spentAmount.
How can I see the remaining budget for my 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 /v2/crp/budgets.
The information will be available as remainingAmount.
What are the different statuses of my budget?
- Depleted : you run out of budget and we had to stop the seller displaying ads
- Stopped : you manually stopped this seller
- Ended : you provided an end date for this budget – The end date is in the past
- Scheduled : You provided a start date in the future
Can I schedule a budget to start at a later date?
Yes, you can create a budget to run in the future, providing a start date. The budget will start from midnight, GMT time.
Can I define an end date for my budget?
Yes, you can define an end date for your budget. It will end at 23:59 GMT time. The budget status will automatically be set up as DEPLETED the day after.
Can I set a daily budget?
Not yet. However, you will be able to set up a budget type = DAILY and provide an amount in the future. We target this feature to be available in Q1 2019. ETA is not contractual and to be confirmed.
Can I filter my calls regarding seller's budgets?
Yes, below are the available filters:
- For end point sellers – You can filter by status (Available/NotAvailable), seller id
- For end point seller-campaigns – You can filter by campaign id and seller id
- Budget end point – By status
You can issue a POST call to the /v2/crp/statistics endpoint. It is only possible to access impressions, clicks and cost at the seller level, available up to a daily granularity.
One extra dimension can be used on top of seller id and campaign id dimension.
- CampaignID – Mandatory
- Seller ID – Mandatory
Display: As you can have multiple sellers in a banner, we use the seller who had the last product viewed in our system.