GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelogLog In

Migration FAQ

Suggest Edits

❗️

Sunset of MAPI

All MAPI endpoints were migrated to Criteo API on July 18, 2022. To learn more about using the Criteo APIs please see our Onboarding checklist.

What are the major changes between your legacy APIs (MAPI and PAPI) and the new Criteo API?

  • A brand new Developer Portal with everything you need to connect, build, and launch your integrations (this is where you are now!)
  • Developer dashboard: A one-stop shop to create and manage apps leveraging different functionalities from Criteo, such as reporting, audiences, and campaigns. You can manage multiple advertisers. Here you'll create a new organization and can invite your teammates to this account
    Our new versioning policy, ensuring each version is stable for a minimum of 12 months
  • A new consent management system, to specify permissions and send authorization requests to users. Each app will now request different permissions, based on its purpose. These can be read or manage permissions. Your end-users will see which permissions your app is requesting
  • For Partners: A Criteo connector for generating consent URLs from your own platform

What are the improvements to the API itself?

  • Along with the overall changes to the Criteo API's functionality, we are also improving specific endpoints' capabilities:
    • Updated Statistics endpoint, with 100+ metrics, including app and store campaigns, so you can build custom reports or connect with your own platforms
    • Updated Transaction ID report, now allowing multiple advertisers and additional time zones
    • Automate campaign management with APIs for budget, ad sets, audiences, and more

How will the new API impact my current integration with Criteo?
If you’ve been using our legacy APIs, PAPI and MAPI, these will be deprecated on June 15th, 2021. You will need to switch over to the Criteo API before then. Most, if not all of the coming endpoints, will indeed contain breaking changes. We will do our best to have this documented for a smooth migration.

What resources are available for the migration?
Learn more about the new Criteo API here, or check out our migration guides:

How long will the migration take my developers?
We've estimated the actual migration will take only a few hours, in total, of engineering dev resources. However, some developers may find it useful to spread this work out over the course of several days.

If I connect to the API through a partner, what do I need to do to migrate?
We are working with many partners to update their integration to the Criteo API. If you previously supplied your credentials to a partner in order to connect, you may receive an authorization request from your partner to reconnect to the API. This is all you need to do to upgrade.

Will the MAPI and PAPI deprecation impact my Shopify or ECP integration?
We do not use the API for our ECP integrations, so it is not impacted by our MAPI and PAPI deprecations.

Why would I want to use the API?
The API can help you get more value out of Criteo by allowing you to build custom solutions. If you have needs around customization, automation, or integration with internal systems beyond what's possible in Commerce Growth, you may be a good fit for the Criteo API. Whether you're an advertiser, agency, or technology partner, you can access the Criteo API to build what you need for your business.

Learn more and see if you're a good fit for the API here.

What do I need to use the API? What resources are needed?
To use the API, you'll need to have your own internal engineering resources to set up and maintain your API integration. The required investment will depend on three factors: Your familiarity with APIs, your necessary use cases, and whether you will access the API through a partner.

  • Familiarity with APIs: The Criteo API system uses industry standards. If you are using similar APIs from your other advertising partners, you will likely already have the required skills in your dev team to use them. In addition, we are evolving our developer program to provide your developers with all the tools that they will need to use our APIs.
  • Use cases: It will require a different level of effort to retrieve a custom report than to programmatically control your entire campaigns. We suggest going step by step, starting with the reporting use case. To do so, your developers can first create a developer account, start testing the API, and then integrate it into an automation flow. The first two steps tend to take our clients an average of two hours and that the last step could take one or two days. These numbers include both large clients and small clients with more limited resources. Starting from there, it will be easier to start using other endpoints for more advanced use cases. Once your dev team is familiar with their first Criteo API call, the marginal cost to use the other endpoints will be lower.
  • Activating through a partner: In some cases, you could indirectly use Criteo APIs through a partner. For example, you could use reporting Criteo APIs to build custom reports within your reporting platform of choice or your agency's in-house reporting tool. Or you could use Criteo APIs to push an audience through your CDP. In those cases, the technical resources needed to integrate Criteo APIs will be absorbed by partners or agencies.

Will I be charged for using the API?
Usage of the Criteo developer portal and developer account is free of charge. API calls are also free of charge. As usual with Criteo, you only pay for the results your ads generate. Please note that some API calls may modify your marketing spend, such as adjusting bids or budgets.

How can I get started?
Our new Developer Portal with everything you need to connect, build, and launch your integrations in just a few steps. Check out the onboarding checklist for more details.

What other functionality will be added to the Criteo API?
To stay ahead of our latest updates, check out our Changelog. If you are interested in providing feedback or requesting a feature, you can join our developers' program by emailing us at [email protected]. By joining our developer program, you will receive early communications about releases and be a part of shaping our API roadmap.

If I am using your legacy APIs (PAPI & MAPI), when do I need to change my integration?
PAPI and MAPI will be deprecated by June 15th, 2021. You can get started on your update now. All previous endpoints (except Statistics, which has been upgraded entirely) are available through the new Criteo API. These require an endpoint URL change to work correctly and using the new authentication system to work correctly. To get your credentials to authenticate, you will need to create a developer account in our Developer Dashboard. Then all you need to do is request consent from your end-users.

Existing MAPI functionality will continue to exist behind the new Criteo API authentication as v2020.07. We will start to decommission Analytics and Campaigns endpoints (except /v1/campaigns/bids and /v1/campaigns/{campaignId}/categories) from July 1st on v2020.07 (Legacy). The remaining v2020.07 endpoints will be decommissioned in the second half of the year, but we will always ensure there is an equivalent in the latest versions. These updates will be communicated in the changelog.

Based on this information, if you're an existing MAPI user, the minimum requirements for migration by June 15th, 2021 are:

If you need more information or would like any additional support on the migration, get in touch with your Criteo contact.

When will v2020.07 be deactivated?
Legacy endpoints (v2020.07) will be deactivated at the end of Q2 quarter except for the endpoints without an equivalent in Criteo API (i.e. categories endpoints):

  • /legacy/marketing/v1/advertiser/{advertiserID}/categories
  • /legacy/marketing /v1/advertiser/{advertiserID}/categories/{categoryHashCode}
  • /legacy/marketing /v1/campaigns/{campaignId}/categories
  • /legacy/marketing /v1/campaigns/{campaignId}/categories/{categoryHashCode}
  • /legacy/marketing /v1/categories
  • /legacy/marketing /v1/campaigns/bids (used for category bidding)

When is category bidding going to be available in the new API?
We are currently anticipating that this feature will be released by the end of Q2. In the meantime, we suggest you use our legacy API here.

How do authorization requests work?
Before an advertiser can start using an app or integration built with the API, the advertiser has to grant it access. This is accomplished through an authorization request. All apps must send an authorization request to advertisers in order to read or manage actions on the advertiser’s behalf.

You can also implement a Criteo connector for generating consent URLs from your own platform by following the guide here.

What is the versioning policy? How often do I need to make changes?
Read our versioning policy here. A new Criteo API version is released every three months at the beginning of each quarter. Each version is supported for 12 months. This means when a new stable version is released and contains changes that affect your integration, you have 12 months to test and migrate to the newest version.

How can users find my app? (For partners)
Currently, you can share a consent URL directly with your clients on a 1:1 basis or (info here about new consent URL generation). In the future, we plan to have discoverable ways for users to explore available integrations right from within Criteo. Please reach out to us If you'd be interested in this feature.

How far back can we pull data through the API?
Data is available for a 2 years period through the analytics endpoint.

Updated about 1 year ago