MPO Single Seller Campaigns - Criteo Docs

Overview

A Single-Seller campaign is a marketplace performance configuration where:

This guide is intended for marketplace integrators and technical users who manage MPO campaigns programmatically through the API. The template campaign concept:

When you create a first budget for a given (seller, template) pair via the MPO budgets endpoint, Criteo automatically creates (if needed) and manages the underlying Single-Seller campaign/campaign for that seller.

Single-Seller vs Multi-Seller MPO campaigns

“Single-Seller” campaigns build on top of the “multi-seller” model where multiple sellers share a single campaign.

Aspect Multi-Seller Single-Seller campaigns
Sellers per campaign Many sellers share one campaign One seller per campaign (per-seller campaign)
Configuration One configuration shared by all sellers Shared template configuration + per-seller campaign derived from it
Budget model Shared budgets across multiple sellers One capped total budget per seller per template (no shared budgets)
Cost control Supports CPC-based control only Single-Seller requires budget-based control (template must use budget as cost controller)
Budget types Various (including daily caps) Capped total budget over a date range only; no daily or uncapped budgets
Pacing Daily caps managed explicitly Automatic smoothing: total budget distributed over the period, with daily caps recomputed

When deciding which to use:

Core Entities and Identifiers

This section clarifies the main entities used in Single-Seller setups and where their identifiers come from:

Keep these relationships in mind:

Access and Enablement

1. Feature availability

Single-Seller campaigns may be gated or rolled out progressively. Before using the flows described below:

If you call Single-Seller-specific flows without being enabled, you may receive authorization or validation errors (for example, using a template that is not marked as Single-Seller-compatible).

2. Getting a Single-Seller template

You cannot create Single-Seller templates through MPO. Instead:

  1. Discuss your use case with Criteo
    • Provide the advertiser(s), vertical, and desired optimization goal.
    • Describe whether Single-Seller will coexist with legacy MPO campaigns.
  2. Criteo configures the template
    • Criteo will create a template campaign with:
      • Budget-based cost control (no CPC for Single-Seller).
      • Your desired optimization goal and targeting defaults.
      • Any required marketplace specific constraints.
  3. Criteo shares the following with you
    • Template campaign ID to be used in MPO budgets as campaignId.
    • The minimum allowed daily budget per seller for that template.
  4. You store and manage this configuration
    • Persist the templateCampaignId and minimal budget constraints in your own system.
    • Use them when constructing MPO budget requests for each seller.

3. Prerequisite Data and Permissions

Your integration should already:

Budget Management for Single-Seller Campaigns

Budget objects are the primary control surface for Single-Seller campaigns.

They:

Note Exact JSON envelopes (e.g. JSON:API data wrappers) may differ; the examples below focus on the key attributes and patterns. Always refer to the MPO budgets reference for the canonical schema.

Budget Behavior Overview

Typical Fields in a Budget

At a high level, a budget resource will include fields conceptually similar to:

Refer to the MPO reference for the exact field names and formats for your API version.

Workflow: Create the First Single-Seller Budget (and Campaign)

This section describes the typical flow to onboard a seller on a Single-Seller template.

Preconditions

Step 1 – Construct the Budget Payload

Conceptual example: Sample request

[
  {
    "campaignIds": ["456"],
    "sellerId": "123",
    "startDate": "2026-04-16",
    "endDate": "2026-04-30",
    "budgetType": "Capped",
    "amount": "1200"
  }
]

Key points:

Step 2 – Interpret the Response

A successful response will return:

From the moment this first valid budget is accepted for a (sellerId, templateCampaignId) pair:

Step 3 – Avoid Overlapping Budgets

When planning future periods:

Workflow: Update an Existing Budget

Use budget updates to adjust amount, dates, or suspension status.

Preconditions

Example: Increase Budget Amount mid-flight

Conceptual example using a PATCH-style update:

{
  "budgetId": "789",
  "amount": "2000"
}

Behavior:

Example: Extend The End Date

{
  "budgetId": "789",
  "endDate": "2026-05-31"
}

Guidance:

Workflow: Suspend and Resume a Single-Seller Campaign

You do not pause Single-Seller campaigns directly. Instead, you pause/resume the budget.

Suspend (pause) via Budget

To stop spend:

{
  "budgetId": "789",
  "isSuspended": true
}

Expected behavior:

Resume via budget

To resume spend:

{
  "budgetId": "789",
  "isSuspended": false
}

Guidance:

Canceling a Scheduled Future Budget

To logically cancel a future, not-yet-active budget:

{
  "budgetId": "FUTURE_BUDGET_1011",
  "isSuspended": true
}

After suspension:

Inspecting Budgets and Performance

You can retrieve budgets and monitor performance using existing MPO endpoints.

You can find more details about all MPO endpoints in our API Reference here.

Budgets

Use these endpoints to:

Performance statistics

Single-Seller performance is exposed via the same stats APIs used for MPO, such as:

Use the appropriate combinations of:

productSet for Single-Seller Campaigns

The productSet feature lets you restrict a Single-Seller campaign to a specific list of product IDs from the seller’s catalog.

Overview

For Single-Seller campaigns:

Where productSet is supported

productSet: Supported Structure and Behavior

Read: Inspecting the current productSet

When you retrieve a Single-Seller campaign (for example: GET /marketplace-performance-outcomes/seller-campaigns), the response will:

Schematic response fragment:

{
  "data": [
    {
      "id": "SELLER_123.TEMPLATE_CAMPAIGN_456",
      "sellerId": "SELLER_123",
      "campaignId": "TEMPLATE_CAMPAIGN_456",
      "productSet": {
          "rules": [
              {
                  "operator": "IsIn",
                  "field": "ExternalItemId",
                  "values": [
                        "SKU_1",
                        "SKU_2",
                        "SKU_3"
                    ]
                }
            ],
            "productSetStatus": "Valid",
            "productSetNumberOfProducts": 3
        }
    }
  ]
}

Interpretation:

If productSet is null or omitted, there is no additional product-ID filter applied.

Create / Update: Attaching a productSet

To create or update the productSet for a Single-Seller campaign, call the seller-campaign update endpoint (for example: PATCH /marketplace-performance-outcomes/seller-campaigns) with a productSet object. Schematic request body (batch of one item):

[
  {
    "id": "SELLER_123.TEMPLATE_CAMPAIGN_456",
    "productSet": {
      "value": [{
                          "operator": "IsIn",
                          "field": "ExternalItemId",
                          "values": ["SKU_001", "SKU_002", "SKU_003", "SKU_004", "SKU_005", "SKU_006", "SKU_007", "SKU_008", "SKU_009", "SKU_010", "SKU_011"]
                        }]
                    }
  }
]

Behavior:

Constraints:

Delete / Unset: Removing the productSet

To remove the productSet (and revert to “no extra product filter”), set the productSet.value to null in an update call. Schematic request:

[
  {
    "id": "SELLER_123.TEMPLATE_CAMPAIGN_456",
    "productSet": {
      "value": null
    }
  }
]

Expected behavior:

productSet: Usage Patterns and Edge Cases

Supported patterns

Common errors and how to avoid them

  1. Using productSet with a non-Single-Seller campaign If you attempt to configure a productSet on a campaign that is not associated with a Single-Seller template, the API may:

    • Reject the request with a 4xx error (for example, indicating an unsupported campaign type).
    • Or explicitly state that productSet is only supported on Single-Seller campaigns.

    To avoid this:

    • Only send a productSet for campaigns that your Criteo contact has confirmed as Single-Seller.
    • If you manage both Single-Seller and multi-seller campaigns, track this distinction in your own data model.

  2. Too few product IDs If the advertiser-specific minimum number of product IDs is, for example, 10, the following may fail:

   "values": ["SKU_001", "SKU_002", "SKU_003"]

When this constraint is violated, the API should respond with:

Your agent or integration should:

  1. Non-matching or invalid product IDs If some IDs in values do not exist in the seller’s catalog or are not eligible (for example, inactive or disapproved products):

    • The request may still be accepted as long as the payload is syntactically valid.
    • At serving time, only existing, eligible products will be used; others are effectively ignored.

    For best results:

    • Use your own catalog or feeds to validate IDs where possible.
    • Monitor performance and impression volume; a productSet with many invalid IDs may lead to under-delivery or blank banner.

Putting It All Together: Typical Automated Flow

This section summarizes a typical end-to-end workflow an agent or automation could follow to set up and manage Single-Seller campaigns.

A. Onboard a new seller to a Single-Seller template

  1. Fetch seller list Call GET /marketplace-performance-outcomes/sellers to obtain sellerId values.
  2. Check local configuration Confirm you have:
    • templateCampaignId for Single-Seller.
    • Minimum allowed budget per seller.
  3. Create first budget for the new seller Call POST /marketplace-performance-outcomes/budgets with:
    • sellerId = the new seller.
    • campaignIds = [templateCampaignId].
    • budgetType = Capped.
    • Valid amount, startDate, endDate.
  4. Wait for provisioning and start monitoring After the budget becomes active, the Single-Seller campaign is created and starts delivering. Use stats endpoints to monitor performance.

B. Adjust spend mid-flight

  1. Retrieve the current budgetGET /marketplace-performance-outcomes/budgets?sellerId=...&campaignId=templateCampaignId
  2. Decide new amount or dates Incorporate minimum/maximum constraints and business logic.
  3. PATCH the budgetPATCH /marketplace-performance-outcomes/budgets with the updated fields.
  4. Confirm the updated state Optionally re-GET the budget or check campaign performance to ensure changes took effect.

C. Pause / resume seller activity

  1. PausePATCH /marketplace-performance-outcomes/budgets with "isSuspended": true.
  2. ResumePATCH /marketplace-performance-outcomes/budgets with "isSuspended": false (if the end date is still in the future).
  3. Cancel scheduled future budgets For future budgets, set isSuspended: true and treat them as canceled.

D. Restrict products for a seller

  1. Obtain product IDs From your catalog or internal systems, list product external IDs for the seller.
  2. Attach productSetPATCH /marketplace-performance-outcomes/seller-campaigns with a productSet containing:
    • operator: "IsIn"
    • field: "ExternalItemId"
    • values: [SKU_1, SKU_2, ...]
  3. Update or remove later as needed
    • Update the list of values to change the whitelist.
    • Set productSet.value to null to remove the filter entirely.

Error Handling and Best Practices

To build robust, agent-friendly integrations: