GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelogLog In

MAPI and MAPI CRP Users

❗️

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.

Criteo Offsite Ads (former CRP) account owners and application owners need to migrate a connector from the legacy MAPI connector to Criteo API as per the instructions below.

Introduction

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.

If you have received a link to this article on or after 21.01.2022 it means you could be an owner of the Criteo Offsite Ads (COA) account or an owner of the COA application.

Target audience

  • Account owners: Anyone with administrative ownership rights over a Criteo account. Typically this is a team member with "Administrator" role in the Commerce Growth.

  • Application owners: The team or an organization which develops, owns and maintains the connector 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.

Pre-requisites

  • 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.

Authorization

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.

Criteo OffSite Ads require "Campaign" domain permission. (see step 3)

Endpoints parity - Criteo Offsite Ads - COA (former CRP)

The table below describes the new endpoint paths for the COA API. The endpoints’ functionality remains the same – only the paths have changed. Account owners and application developers are expected to complete completion - by the end of Q2 2022.

TypeMAPICriteo API - v2020.07
GET/marketing/v2/crp/advertisers/legacy/offsite-ads/advertisers
GET/marketing/v2/crp/advertisers/{advertiserId}/legacy/offsite-ads/advertisers/{advertiserId}
GET/marketing/v2/crp/advertisers/{advertiserId}/campaigns/legacy/offsite-ads/advertisers/{advertiserId}/campaigns
POST/marketing/v2/crp/advertisers/{advertiserId}/sellers/legacy/offsite-ads/advertisers/{advertiserId}/sellers
GET/marketing//v2/crp/advertisers/{advertiserId}/budgets/legacy/offsite-ads/advertisers/{advertiserId}/budgets
GET/marketing/v2/crp/advertisers/{advertiserId}/seller-campaigns/legacy/offsite-ads/advertisers/{advertiserId}/seller-campaigns
GET/marketing/v2/crp/sellers/{sellerId}/legacy/offsite-ads/sellers/{sellerId}
GET/marketing/v2/crp/sellers/legacy/offsite-ads/sellers
GET/marketing/v2/crp/sellers/{sellerId}/budgets/legacy/offsite-ads/sellers/{sellerId}/budgets
GET | POST/marketing/v2/crp/sellers/{sellerId}/seller-campaigns/legacy/offsite-ads/sellers/{sellerId}/seller-campaigns
GET | PATCH/marketing/v2/crp/seller-campaigns/{sellerCampaignId}/legacy/offsite-ads/seller-campaigns/{sellerCampaignId}
GET | PATCH/marketing/v2/crp/seller-campaigns/legacy/offsite-ads/seller-campaigns
GET/marketing/v2/crp/seller-campaigns/{sellerCampaignId}/budgets/legacy/offsite-ads/seller-campaigns/{sellerCampaignId}/budgets
GET | PATCH/marketing/v2/crp/budgets/{budgetId}/legacy/offsite-ads/budgets/{budgetId}
GET | PATCH | POST/marketing/v2/crp/budgets/legacy/offsite-ads/budgets
GET/marketing/v2/crp/advertisers/{advertiserId}/ad-preview/legacy/offsite-ads/advertisers/{advertiserId}/ad-preview
GET/marketing/v2/crp/advertisers/preview-limit/legacy/offsite-ads/advertisers/preview-limit
GET/marketing/v2/crp/stats/campaigns/legacy/offsite-ads/stats/campaigns
GET/marketing/v2/crp/stats/sellers/legacy/offsite-ads/stats/sellers
GET/marketing/v2/crp/stats/seller-campaigns/legacy/offsite-ads/stats/seller-campaigns

❗️

v2020.07 note

Version 2020.07 is a special version of Criteo API that aggregates the legacy endpoints under the new API framework. Once an endpoint is released under the standard stable version (e.g “2022-10“) you will have 6 months to migrate from v2020.07 to the new version. Please keep an eye on the changelog to be aware of all upcoming changes.

Endpoints parity - Criteo Marketing Solutions (CMS)

The migration has been completed. The table below is provided as historical records only. No action is needed.

Type

MAPI

Criteo API - legacy

Description

Versioning policy

Criteo API - versioned

GET

/v1/advertiser/{advertiserID}/categories

/legacy/marketing/v1/advertiser/{advertiserID}/categories

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 advertiser

N

N/A

GET

/v1/advertiser/{advertiserID}/categories/{categoryHashCode}

/legacy/marketing/v1/advertiser/{advertiserID}/categories/{categoryHashCode}

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 advertiser

N

N/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

Y

Update Campaigns
Update Ad Sets
More details are given below.

GET

/v1/campaigns/{campaignId}/categories

/legacy/marketing/v1/campaigns/{campaignId}/categories

Status: set for deprecation on 2021-12-31.

Retrieve your campaign and categories for a specific campaign

Y

See Category Bids

GET

/v1/campaigns/{campaignId}/categories/{categoryHashCode}

/legacy/marketing/v1/campaigns/{campaignId}/categories/{categoryHashCode}

Status: set for deprecation on 2021-12-31.

Retrieve specific campaign categories of your portfolio

Y

N/A

Filtering by category hash is not available at the moment. A specific categoryHashCode can be filtered post-retrieval.

GET/PUT

/v1/campaigns/bids

PATCH /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.

Y

PATCH /2021-07/marketing-solutions/ad-sets for updating the bids

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

GET

/v1/categories

/legacy/marketing/v1/categories

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 portfolio

N

PATCH

/marketing/v1/catalogs/products

/legacy/marketing/v1/catalogs/products

Manage your product catalog, add, remove or edit your product details. Get status reports on your recent imports.

Y

See Catalog

Budgets - Criteo Marketing Solutions (CMS)

The migration has been completed. The table below is provided as historical records only. No action is needed.

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 Commerce Growth, 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

Summary

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:

Functionality

Status

Criteo Offsite Ads - COA (former CRP)

Migration is on-going

Advertisers and portfolio

Migration has been completed

Statistics

Migration has been completed

Audiences

Migration has been completed

Campaigns and Ad Sets

Migration has been completed

Feel free to reach out to us through your account representative or the Discussion section of the portal if you have any questions.


Did this page help you?