v1

latestOpenAPI 3.0.02026-07-2466275257.1 KB

productCampaign

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.

post/v3/product-campaigns

Request body

Example request

{
  "productCampaign": {
    "advertisedProducts": {
      "productsByKey": [
        {
          "catalogId": "catalog_001",
          "productCode": "PROD123456",
          "sellerId": "seller_78910"
        }
      ]
    },
    "targeting": {
      "searchTerms": [
        {
          "phrase": "example search term",
          "collectionName": "default_collection",
          "suggested": true,
          "excludedProducts": [
            {
              "catalogId": "catalog_001",
              "productCode": "PROD123456",
              "sellerId": "seller_78910"
            }
          ],
          "maxBid": "100.00",
          "treatAsCustom": true
        }
      ],
      "crossSell": {
        "targetProductsByKey": [
          {
            "catalogId": "catalog_001",
            "productCode": "PROD123456",
            "sellerId": "seller_78910"
          }
        ]
      },
      "upsell": {
        "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"
        }
      ]
    },
    "strategy": {
      "auction": {
        "maxBid": "$100.00",
        "spendLimit": {
          "daily": "$50.00",
          "total": "$1000.00"
        }
      },
      "fixedTenancy": {
        "cost": "$99.99",
        "positions": [
          1,
          2,
          3
        ],
        "catalogCosts": [
          {
            "catalogId": "catalog_123456",
            "catalogCostPercentage": 0.25
          }
        ]
      }
    },
    "fixedCosts": {
      "dataCost": "$100.00",
      "creativeCost": "$200.00",
      "otherCost": "$50.00"
    },
    "customFields": [
      {
        "customFieldId": "cfid_12345",
        "content": "This is a custom field content."
      }
    ],
    "customQuestions": [
      {
        "customQuestionId": "cqid_67890",
        "answers": [
          "Answer 1",
          "Answer 2",
          "Answer 3"
        ]
      }
    ]
  }
}

Response

Details of the created campaign.

Example response

{
  "productCampaign": {
    "advertisedProducts": {
      "productsByKey": [
        {
          "catalogId": "catalog_001",
          "productCode": "PROD123456",
          "sellerId": "seller_78910"
        }
      ]
    },
    "targeting": {
      "searchTerms": [
        {
          "phrase": "example search term",
          "collectionName": "default_collection",
          "suggested": true,
          "excludedProducts": [
            {
              "catalogId": "catalog_001",
              "productCode": "PROD123456",
              "sellerId": "seller_78910"
            }
          ],
          "maxBid": "100.00",
          "treatAsCustom": true
        }
      ],
      "crossSell": {
        "targetProductsByKey": [
          {
            "catalogId": "catalog_001",
            "productCode": "PROD123456",
            "sellerId": "seller_78910"
          }
        ]
      },
      "upsell": {
        "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"
        }
      ]
    },
    "strategy": {
      "auction": {
        "maxBid": "$100.00",
        "spendLimit": {
          "daily": "$50.00",
          "total": "$1000.00"
        }
      },
      "fixedTenancy": {
        "cost": "$99.99",
        "positions": [
          1,
          2,
          3
        ],
        "catalogCosts": [
          {
            "catalogId": "catalog_123456",
            "catalogCostPercentage": 0.25
          }
        ]
      }
    },
    "fixedCosts": {
      "dataCost": "$100.00",
      "creativeCost": "$200.00",
      "otherCost": "$50.00"
    },
    "customFields": [
      {
        "customFieldId": "cfid_12345",
        "content": "This is a custom field content."
      }
    ],
    "customQuestions": [
      {
        "customQuestionId": "cqid_67890",
        "answers": [
          "Answer 1",
          "Answer 2",
          "Answer 3"
        ]
      }
    ]
  }
}