Managing Campaigns

Overview

In Single-Seller setups, you do not create seller-campaigns directly. Instead, the underlying per-seller campaign is created implicitly by Criteo when you create the first valid budget for a (sellerId, templateCampaignId) pair.

Once created, you can configure and control the campaign through two main surfaces:

• Budget suspension (to pause/resume the campaign).
• productSet configuration (to restrict which products can be advertised).

The Single-Seller campaign entity

A Single-Seller campaign (identified by sellerCampaignId) is the per-seller campaign derived from the template.

Key characteristics:

• Created implicitly when the first valid budget for a (sellerId, templateCampaignId) pair is accepted.
• There may be a short asynchronous provisioning delay before delivery begins after creation.
• Used by MPO stats endpoints when querying performance at the seller-campaign level.
• Can have at most one productSet attached at any given time.

To retrieve seller-campaigns and inspect their current state:

GET /marketplace-performance-outcomes/seller-campaigns

Suspension reasons

When a Single-Seller campaign is not delivering, the API returns a suspensionReasons array explaining why.

Checking campaign status

{
"id": "SELLER_123.TEMPLATE_CAMPAIGN_456",
"sellerId": "SELLER_123",
"campaignId": "TEMPLATE_CAMPAIGN_456",
"suspendedSince": "2026-04-28T10:00:00Z",
"suspensionReasons": ["NoMoreDailyBudget"]
}

• If suspendedSince is null and suspensionReasons is empty → the campaign is active.
• If suspendedSince is set and one or more reasons are present → the campaign is currently suspended.

Suspending and resuming a Single-Seller campaign

You do not pause Single-Seller campaigns directly via a campaign-level endpoint. Instead, you control campaign run state by suspending or resuming the associated budget.

Suspend (pause) a campaign

To stop spend for a seller, set isSuspended: true on the active budget:

POST  https://api.criteo.com/2026-01/marketing-solutions/marketplace-performance-outcomes/budgets/{budgetId}
Content-Type: application/json

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

Expected behavior:

• The budget becomes inactive and the associated Single-Seller campaign stops serving.
• The budget remains present in the API for auditing and historical purposes.

Resume a campaign

To resume spend, set isSuspended: false:

POST  https://api.criteo.com/2026-01/marketing-solutions/marketplace-performance-outcomes/budgets/{budgetId}
Content-Type: application/json

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

Guidance:

• If the endDate is in the past, resuming will not restart delivery; you may need to create a new budget with a future period.
• If there is a future budget scheduled for the same (sellerId, templateCampaignId), the campaign will automatically resume when that future budget’s startDate is reached (assuming that future budget is not itself suspended).

Cancel a scheduled future budget

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

POST  https://api.criteo.com/2026-01/marketing-solutions/marketplace-performance-outcomes/budgets/{budgetId}
Content-Type: application/json

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

After suspension:

• Treat the budget as canceled.
• You can create a new budget covering the same period if needed; suspended budgets do not block new ones for the same dates.

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

A productSet is a whitelist of product IDs:

• Only products whose external item IDs are in the productSet are eligible to be advertised by that Single-Seller campaign.

The productSet:

• Is configured at the seller-campaign level.
• Applies to all ads served by that campaign.
• Is optional; if no productSet is configured, the campaign can use all eligible products from the seller’s catalog (subject to other targeting and policy constraints).
• There is at most one productSet per Single-Seller campaign at any given time.

productSet configuration is only supported for Single-Seller campaigns associated with a Single-Seller template. Do not attempt to use productSet on legacy multi-seller campaigns or other campaign types.

Inspecting the current productSet

When you retrieve a Single-Seller campaign, the response will:

• Return no productSet or productSet: null if no productSet has ever been configured.
• Return a structured rule when a productSet is configured.

Example 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:

• productSet.rules contains an array of rules; in Single-Seller mode, only a single rule is supported.
• Each rule:
  • operator: "IsIn" — inclusion list.
  • field: "ExternalItemId" — field in the seller’s catalog feed.
  • values — list of product IDs (strings).
• If productSet is null or omitted, no additional product-ID filter is applied.

Create / Update: Attaching a productSet

To create or update the productSet for a Single-Seller campaign, call the seller-campaign update endpoint with a productSet object.

PATCH  https://api.criteo.com/2026-01/marketing-solutions/marketplace-performance-outcomes/seller-campaigns
Content-Type: application/json

Example request body:

[
{
"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:

• If the Single-Seller campaign had no productSet before, this creates and attaches a new productSet.
• If a productSet already existed, this replaces the existing rule with the new one (it is not additive).
• After a successful update, subsequent GETs for this campaign will return the new productSet configuration.

Constraints:

• Only:
  • operator = "IsIn" or operator = "IsNotIn", with
  • field = "ExternalItemId"
    is supported for Single-Seller usage.
• A minimum number of product IDs per productSet may be enforced per advertiser (default: 20). Providing fewer IDs than configured will return a 4xx error.

Delete / Unset: Removing the productSet

To remove the productSet and revert to no additional product filter, set productSet.value to null:

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

Expected behavior:

• The Single-Seller campaign stops using a productSet to filter products.
• A subsequent GET for this campaign will show productSet: null (or omit the field, depending on the schema).
• Products are once again selected from the seller’s catalog without additional ID whitelisting, subject to other targeting rules and policies.

Supported productSet patterns

Workflow: Restrict products for a seller

1. Obtain product IDs from your catalog or internal systems for the seller.
2. Attach productSet via:

PATCH /marketplace-performance-outcomes/seller-campaigns

with:

• operator: "IsIn"
• field: "ExternalItemId"
• values: ["SKU_1", "SKU_2", ...]

3. Update or remove later as needed:

   • Update the values list to change the whitelist.
   • Set productSet.value to null to remove the filter entirely.