Discard

Criteo Marketing Solutions API

Migration Guide for MAPI Users

🚧

MAPI has been sunset

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

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.

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.

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.

Endpoints parity

The table below describes the endpoints that can be migrated

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

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.

Conclusion

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.

Updated about 16 hours ago


Migration Guide for MAPI Users


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.