Create a product campaign
This endpoint creates a new product campaign with the marketing settings and product selections. Set up campaign details like budget, duration, and which products to promote. The campaign will be read
description: "This endpoint creates a new product campaign with the marketing settings and product selections. Set up campaign details like budget, duration, and which products to promote. The campaign will be ready to launch once created. The following fields inside productCampaign are required: name, namespaceId, campaignState, teamId, walletId, placementId, catalogIds (at least one), and strategy (either strategy.auction or strategy.fixedTenancy). For search-targeted placements, targeting.searchTerms is also required, and each entry must include phrase and matchType. The caller's user must have the ROLE_CAMPAIGN_EDITOR permission on the campaign's teamId (or be an admin); otherwise the request will be rejected with PERMISSION_DENIED."
Create a product campaign
This endpoint creates a new product campaign with the marketing settings and product selections. Set up campaign details like budget, duration, and which products to promote. The campaign will be ready to launch once created.
The following fields inside productCampaign are required: name, namespaceId, campaignState, teamId, walletId, placementId, catalogIds (at least one), and strategy (either strategy.auction or strategy.fixedTenancy). For search-targeted placements, targeting.searchTerms is also required, and each entry must include phrase and matchType.
The caller's user must have the ROLE_CAMPAIGN_EDITOR permission on the campaign's teamId (or be an admin); otherwise the request will be rejected with PERMISSION_DENIED.
Authorizations
AuthorizationstringRequired
For accessing the API a valid JWT jwt must be passed in all queries in the 'Authorization' header. The following syntax must be used in the 'Authorization' header. (Bearer xxx.yyy.zzz)
Body
Responses
200
Details of the created campaign.
application/json
400
There was a problem with input.
application/json
401
Login failed or token not valid.
application/json
403
Access denied due to insufficient permissions.
application/json
default
An unexpected error response.
application/json
post/v3/product-campaigns
POST /v3/product-campaigns HTTP/1.1
Host: campaign.<env>.citrusad.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 2163
{
"productCampaign": {
"advertisedProducts": {
"productGroupList": [
"text"
],
"productsByAttributes": {
"priceRange": {
"max": "100",
"min": "10"
},
"tags": [
"tag1",
"tag2",
"tag3"
]
},
"productsByKey": [
{
"catalogId": "catalog_001",
"productCode": "PROD123456",
"sellerId": "seller_78910"
}
]
},
"approval": {
"rejectionReason": "text",
"state": "APPROVAL_STATE_PENDING"
},
"campaignState": "CAMPAIGN_STATE_ACTIVE",
"catalogIds": [
"text"
],
"customFields": [
{
"content": "This is a custom field content.",
"customFieldId": "cfid_12345"
}
],
"customQuestions": [
{
"answers": [
"Answer 1",
"Answer 2",
"Answer 3"
],
"customQuestionId": "cqid_67890"
}
],
"endTime": "2026-01-01T00:00:00.000Z",
"fixedCosts": {
"creativeCost": "$200.00",
"dataCost": "$100.00",
"otherCost": "$50.00"
},
"managerTeamId": "text",
"name": "text",
"namespaceId": "text",
"placementId": "text",
"sellerId": "text",
"startTime": "2026-01-01T00:00:00.000Z",
"strategy": {
"auction": {
"automatedBid": {
"enableAutomatedBid": true,
"objectiveType": "OBJECTIVE_TYPE_UNSPECIFIED",
"targetRoas": "2.5"
},
"maxBid": "$100.00",
"spendLimit": {
"daily": "$50.00",
"total": "$1000.00"
}
},
"fixedTenancy": {
"catalogCosts": [
{
"catalogCostPercentage": 0.25,
"catalogId": "catalog_123456"
}
],
"cost": "$99.99",
"positions": [
1,
2,
3
]
}
},
"targeting": {
"audience": {
"includeSegmentsSets": [
{
"segmentIds": [
"text"
]
}
]
},
"crossSell": {
"targetProductsByAttributes": {
"subclassTags": [
"Electronics",
"Home Appliances"
],
"vendorTags": [
"BrandX",
"BrandY"
]
},
"targetProductsByKey": [
{
"catalogId": "catalog_001",
"productCode": "PROD123456",
"sellerId": "seller_78910"
}
]
},
"excludeFilters": [
{
"catalogId": "catalog_12345",
"filter": "filter_value_abc"
}
],
"includeFilters": [
{
"catalogId": "catalog_12345",
"filter": "filter_value_abc"
}
],
"negativeSearchTerms": [
{
"matchType": "MATCH_TYPE_UNSPECIFIED",
"phrase": "text"
}
],
"searchTerms": [
{
"collectionName": "default_collection",
"matchType": "MATCH_TYPE_UNSPECIFIED",
"maxBid": "100.00",
"phrase": "example search term",
"treatAsCustom": true
}
],
"upsell": {
"targetProductsByAttributes": {
"priceRange": {
"max": "100",
"min": "10"
},
"subclassTags": [
"text"
],
"vendorTags": [
"text"
]
},
"targetProductsByKey": [
{
"catalogId": "catalog_001",
"productCode": "PROD123456",
"sellerId": "seller_78910"
}
]
}
},
"teamId": "text",
"templateId": "text",
"walletId": "text"
}
}{
"productCampaign": {
"advertisedProducts": {
"productGroupList": [
"text"
],
"productsByAttributes": {
"priceRange": {
"max": "100",
"min": "10"
},
"tags": [
"tag1",
"tag2",
"tag3"
]
},
"productsByKey": [
{
"catalogId": "catalog_001",
"productCode": "PROD123456",
"sellerId": "seller_78910"
}
]
},
"approval": {
"rejectionReason": "text",
"state": "APPROVAL_STATE_PENDING"
},
"campaignState": "CAMPAIGN_STATE_ACTIVE",
"catalogIds": [
"text"
],
"customFields": [
{
"content": "This is a custom field content.",
"customFieldId": "cfid_12345"
}
],
"customQuestions": [
{
"answers": [
"Answer 1",
"Answer 2",
"Answer 3"
],
"customQuestionId": "cqid_67890"
}
],
"endTime": "2026-01-01T00:00:00.000Z",
"fixedCosts": {
"creativeCost": "$200.00",
"dataCost": "$100.00",
"otherCost": "$50.00"
},
"id": "text",
"managerTeamId": "text",
"name": "text",
"namespaceId": "text",
"placementId": "text",
"sellerId": "text",
"startTime": "2026-01-01T00:00:00.000Z",
"strategy": {
"auction": {
"automatedBid": {
"enableAutomatedBid": true,
"objectiveType": "OBJECTIVE_TYPE_UNSPECIFIED",
"targetRoas": "2.5"
},
"maxBid": "$100.00",
"spendLimit": {
"daily": "$50.00",
"total": "$1000.00"
}
},
"fixedTenancy": {
"catalogCosts": [
{
"catalogCostPercentage": 0.25,
"catalogId": "catalog_123456"
}
],
"cost": "$99.99",
"positions": [
1,
2,
3
]
}
},
"targeting": {
"audience": {
"includeSegmentsSets": [
{
"segmentIds": [
"text"
]
}
]
},
"crossSell": {
"targetProductsByAttributes": {
"subclassTags": [
"Electronics",
"Home Appliances"
],
"vendorTags": [
"BrandX",
"BrandY"
]
},
"targetProductsByKey": [
{
"catalogId": "catalog_001",
"productCode": "PROD123456",
"sellerId": "seller_78910"
}
]
},
"excludeFilters": [
{
"catalogId": "catalog_12345",
"filter": "filter_value_abc"
}
],
"includeFilters": [
{
"catalogId": "catalog_12345",
"filter": "filter_value_abc"
}
],
"negativeSearchTerms": [
{
"matchType": "MATCH_TYPE_UNSPECIFIED",
"phrase": "text"
}
],
"searchTerms": [
{
"collectionName": "default_collection",
"excludedProducts": [
{
"catalogId": "catalog_001",
"productCode": "PROD123456",
"sellerId": "seller_78910"
}
],
"matchType": "MATCH_TYPE_UNSPECIFIED",
"maxBid": "100.00",
"phrase": "example search term",
"suggested": true,
"treatAsCustom": true
}
],
"upsell": {
"targetProductsByAttributes": {
"priceRange": {
"max": "100",
"min": "10"
},
"subclassTags": [
"text"
],
"vendorTags": [
"text"
]
},
"targetProductsByKey": [
{
"catalogId": "catalog_001",
"productCode": "PROD123456",
"sellerId": "seller_78910"
}
]
}
},
"teamId": "text",
"templateId": "text",
"updateTime": "2026-01-01T00:00:00.000Z",
"walletId": "text"
}
}