Skip to main content

​
General

As a general rule:
  • 4xx errors indicate an input or business logic issue. Read the error payload carefully — it will contain field-level detail to help you correct the request before retrying.
  • 500 and 503 errors are typically caused by a temporary network or service issue. Implement an exponential backoff policy: wait 10 seconds before the first retry, 20 seconds before the second, 40 seconds before the third, and so on.
The API accepts up to 2,000 budget objects per call with no defined maximum payload size.
Partial failure is not supported at the request level. However, if a call fails, the error response will include detail records identifying which items caused the failure, so you can correct and resubmit.
Check the suspendedSince and suspensionReasons fields on the seller-campaign:
  • If suspendedSince is null and suspensionReasons is empty, the campaign appears active to the API. If it is still not delivering, check that the template campaign is active and the budget meets the minimum per-seller threshold.
  • If suspensionReasons contains a value, see the table below.

Reason

Meaning

Action

ManuallyStopped

Budget manually suspended

Resume via budgetPATCH

NoBudgetDefined

No active budget exists

Create a valid budget

NoCpcDefined

No CPC set

Set a CPC bid

NoMoreBudget

Budget fully spent

Create a new budget for a future period

RemovedFromCatalog

All products removed

Restore products in the catalog

NotYetStarted

Newly created, not yet processed

Wait for provisioning

NoMoreDailyBudget

Daily spend limit reached

No action needed; resets the next day

Other

Internal error

Contact Criteo Product or R&D

Note that bulk endpoints do not always return HTTP 200. Authorization and validation errors are returned with their appropriate status codes. For example, an invalid seller-campaign mapping returns a 403:
JSON
[
{
"detail": "Seller-campaign mappings are invalid. Invalid seller-campaigns: (campaign: 562108, seller: 1111)",
"status": 403,
"source": {
"body": ""
}
}
]
In the most common scenario, sellers are added automatically from the catalog you have provided to Criteo. You must include the seller identifier in the seller_id field of each product in your catalog feed. The value is case-sensitive.Once the catalog is imported, it typically takes 3–4 hours for sellers to appear in the system.

​
Sellers

Use the sellers endpoint with a name filter:
HTTP
GET /marketplace-performance-outcomes/sellers?sellerName=YourSellerName

​
Campaigns

A campaign (also referred to as an ad set in Commerce Growth) is the top-level configuration managed by Criteo. You do not create or modify it directly via the MPO API.A seller-campaign is automatically created for each seller when the seller is set up. For example, if there are two MPO campaigns (one for web and one for app), two seller-campaigns will be created per seller by default. Seller-campaigns are the entities you manage via the API bids, and run state.
Campaign IDs are assigned and managed by Criteo. You can obtain the campaign ID:
  • Directly from your Criteo point of contact.
  • Via the GET /marketplace-performance-outcomes/campaigns endpoint.
There is no single flag that starts or stops a seller-campaign. A seller-campaign becomes active when it meets a set of conditions — including having a valid budget, a CPC bid, and active products in the catalog. See Managing Campaigns for the full list of conditions. :llmCitationRef[0]To stop a seller-campaign, set the budget to isSuspended: true via:
HTTP
PATCH /marketplace-performance-outcomes/budgets
This can happen when the suspension reason is not yet surfaced by the API. Common causes include:
  • The daily budget has been exhausted (NoMoreDailyBudget).
  • An internal system issue is preventing delivery (Other).
Check the suspendedSince and suspensionReasons fields when retrieving a seller-campaign. If both are null, the campaign appears active. If suspendedSince is set, the campaign is inactive — check suspensionReasons for details. :llmCitationRef[1]

​
Budgets

There is no dedicated endpoint for remaining budget. Calculate it usin
remaining budget = amount − spend
Both amount and spend are available from:
  • GET /marketplace-performance-outcomes/budgets
  • GET /marketplace-performance-outcomes/budgets/{budgetId}
No. For a given (sellerId, campaignId) pair, budget periods must not overlap. If you need to extend a period, update the existing budget. If you need to replace it, create a new one with non-overlapping dates.Important distinction:
  • Past or expired budgets do not block new budgets for the same date range.
  • Suspended budgets are not treated as canceled; they can be reactivated. A suspended budget still occupies its date range and will block a new budget for overlapping dates.
If you need to free up a date range currently held by a suspended budget, you must delete or expire the suspended budget before creating a new one for that period.
Yes. You can create budgets with future startDate values as long as their date ranges do not overlap with any existing active budgets for the same (sellerId, campaignId) pair.

​
Statistics

Yes. While statistics data defaults to UTC, the Stats API supports a timezone parameter so you can retrieve data in your preferred local time zone directly.
Statistics are typically available with a latency of a few hours. Exact latency may vary; refer to the Getting Statistics page for current SLA guidance. :llmCitationRef[2]