GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelogLog In

Migration Guide for MAPI Users


MAPI has been sunset

This guide focuses on migrating the endpoints under the legacy prefix to the versioned endpoints.


This article is intended to serve as a guide for the account owners and application owners in the process of migrating from the legacy endpoints to Criteo API versioned endpoints. As a rule, the deprecation date of a legacy endpoint is 6 months from the release date of the versioned endpoint.

Please check the latest changelog to be aware of the new features in the latest stable release.

Target audience

  • Account owners: Anyone with administrative ownership rights over a Criteo account.

  • Application owners: The team or organization who owns and maintains the code.

If the account owner and application owner are the same entity, then the organization name in the developer portal should be set the same as the advertiser name.
Please note only the Account Administrator role can approve consent requests for the scope of their accounts, i.e it is not possible for the Business Manager to approve the application consent request. Hence the application owners should generate and send the consent link to the account administrators.


  • Application owners should complete the onboarding in our new Developer Portal as indicated in the onboarding checklist.

  • As per the checklist an application owner should generate the consent URL and share the URL by email, Slack, or any other means with the account owner.

  • Application owners and account owners should get familiar with Versioning Policy. API versioning provides predictability and insight into scheduled changes. This helps you control how you choose to handle feature upgrades and deprecations.

  • Basic understanding of the new Criteo campaigns structure: Campaigns, Ad Sets, and Ads. Bid Strategy and budget became a property of an Ad Set. Targeting controls and bid targets are set at the Ad Set level. Several Ad Sets can be linked to the same Campaign. Ads are the actual media that is used to address the audience of a given Ad Set. There can be many Ads associated with a given Ad Set.


Once the account owner (e.g Account Administrator) receives and clicks on the consent link, they will be redirected to the Criteo Consent Portal where they can grant you the requested authorization levels for the accounts in their portfolio.

Endpoints parity

The table below describes the endpoints that can be migrated

TypeMAPICriteo API - legacyDescriptionVersioning policyCriteo API - versioned

Status: set for deprecation. Category bids can be set only within the context of the ad sets.
Retrieve your campaign(s) and categories for a specific advertiserNN/A

Status: set for deprecation on 2021-12-31. Category bids can be set only within the context of the ad sets.
Retrieve specific categories for a specific advertiserNN/A
GET/v1/budgets/legacy/marketing/v1/budgets/Budget is a property of an Ad Set now and a Campaign.
Please see Update Campaigns
Update Ad Sets
YUpdate Campaigns
Update Ad Sets
More details are given below.

Status: set for deprecation on 2021-12-31.
Retrieve your campaign and categories for a specific campaignYSee Category Bids

Status: set for deprecation on 2021-12-31.
Retrieve specific campaign categories of your portfolioYN/A

Filtering by category hash is not available at the moment. A specific categoryHashCode can be filtered post-retrieval.
GET/PUT/v1/campaigns/bidsPATCH /2021-07/marketing-solutions/ad-sets for updating the bids

GET/PATCH /2021-07/marketing-solutions/ad-sets/search for retrieving the bids
Get or set the new bid values for your Ad Set.
Refer to Search for Ad Sets and Update Ad Sets for more information.
YPATCH /2021-07/marketing-solutions/ad-sets for updating the bids

GET/PATCH /2021-07/marketing-solutions/ad-sets/search for retrieving the bids

Not available in v2021-04, please see the Legacy endpoints guide here. The legacy endpoint will be available until an equivalent versioned endpoint is released.
Retrieve categories for your portfolioN
PATCH/marketing/v1/catalogs/products/legacy/marketing/v1/catalogs/productsManage your product catalog, add, remove or edit your product details. Get status reports on your recent imports.YSee Catalog


In parallel with the API migration, we have migrated the budgets to a new spend management system. On the UI side, these features replaced the budget module within Management Center, and on the API side /v1/budgets endpoint has been replaced by Ad Set and Campaign endpoints.

More specifically, it's now possible to update campaign-level spend limits while updating budgets became a direct component of ad sets. The new system also introduces real-time budget editing.

Your preexisting budget behavior has been replicated through a combination of campaign spend limit and ad set budget settings.

Information about updating and retrieving campaign-level spend limits is available here: Update Campaigns

Information about updating and retrieving Ad Set-level spend strategy is available here: Update Ad Sets

More information about the new spend management system can be checked here.


The document provided you with guidance on completing the steps of legacy migration. The guides section will help to navigate through various usage scenarios of the endpoints and contain more detailed migration instructions for each of the endpoints:

Reference section will provide an up-to-date endpoint specification.
Feel free to reach out to us through your account representative or the Discussion section of the portal if you have any questions.