Create a banner X campaign

Creates a new banner X campaign using the details provided in the request body. This endpoint allows you to define campaign parameters, targeting, strategy, and other configurations to launch a new ca

Epsilon Retail Media's documentation is now centralized with our knowledgebase!

For up to date guides, please view this page in the new Partner APIs space of our documentation.

description: "Creates a new banner X campaign using the details provided in the request body. This endpoint allows you to define campaign parameters, targeting, strategy, and other configurations to launch a new campaign."

Create a banner X campaign

File upload guidelines

BannerX Config Field Validations

contentStandardId

Must be a valid UUID format
Should exist in the shotgun_banner_content_standard_model table
Must belong to the same namespace as the user

slotID

Must be part of the specified contentStandardId

slotType

Must be one of the following enums:
- BANNER_X_SLOT_TYPE_BANNER
- BANNER_X_SLOT_TYPE_SINGLE_TILE
- BANNER_X_SLOT_TYPE_DOUBLE_TILE
Must be present in the contentStandardId details

headingText

Validated against the headingTextConfiguration in the contentStandardId details
Must not exceed the maximum character limit specified
Mandatory if marked as such in the configuration

bannerText

Validated against the bannerTextConfiguration in the contentStandardId details
Must not exceed the maximum character limit specified
Mandatory if marked as such in the configuration

bannerTextColourHex

Must be a valid HEX color
Should match one of the options in fixedBannerTextColourHexOptions if provided in the content standard

ctaFlag

Validated against the callToActionConfiguration in the contentStandardId details
If enabled, all CTA fields (ctaText, ctaTextAccessibility, ctaLink) must be provided

ctaText

Validated against callToActionConfiguration in the content standard
Must not exceed the character limit specified in the configuration
Mandatory if marked as such

ctaTextAccessibility

Maximum length is 200 characters

ctaLink

Must match the linkPrefix and not exceed the linkCharacterLimit specified in the configuration
Default maximum length is 200 characters

backgroundColourHex

Must be a valid HEX color
Should match options in the content standard if provided

backgroundImageId

Must exist in the image bucket
Image dimensions must match those specified in primaryBackgroundImageConfiguration if enabled
Mandatory if marked as such

backgroundImagePosition

Must be one of the following enums, as specified in the configuration:
- BANNER_X_BACKGROUND_IMAGE_POSITION_REPEATING
- BANNER_X_BACKGROUND_IMAGE_POSITION_LEFTALIGNED
- BANNER_X_BACKGROUND_IMAGE_POSITION_RIGHTALIGNED
- BANNER_X_BACKGROUND_IMAGE_POSITION_TOPALIGNED
- BANNER_X_BACKGROUND_IMAGE_POSITION_BOTTOMALIGNED
- BANNER_X_BACKGROUND_IMAGE_POSITION_FILL

secondaryBackgroundImageId

Must exist in the image bucket
Image dimensions must match those specified in secondaryBackgroundImageConfiguration if enabled
Mandatory if marked as such

secondaryBackgroundImagePosition

Must be one of the allowed enums in the configuration
Must be valid for the content standard

heroImageId

Must exist in the image bucket
Image dimensions must match those specified in heroImageConfiguration if enabled
Mandatory if marked as such

heroImageAltText

Maximum length is 200 characters

heroMode

Must be one of the following enums, as specified in the configuration:
- BANNER_X_HERO_IMAGE_MODE_BLOCK
- BANNER_X_HERO_IMAGE_MODE_LANDSCAPE
- BANNER_X_HERO_IMAGE_MODE_PORTRAIT
Must be valid for the content standard

secondaryHeroImageId

Must exist in the image bucket
Image dimensions must match those specified in secondaryHeroImageConfiguration if enabled
Mandatory if marked as such

secondaryHeroImageAltText

Maximum length is 200 characters

secondaryHeroMode

Must be one of the allowed enums in the configuration
Must be valid for the content standard

additionalFields

Validation depends on the field type:

For color fields:

If mandatory is false and enabled is true, must be a valid HEX color
If mandatory is true and enabled is true, must match one of the colorHexOptions

For text fields:

Must not exceed the maxCharacterLimit
May have fixed options or dropdowns as defined in the configuration

trackingTagProvider

No validation required at this time

CTA Fields Special Validations

If CTA is enabled at the content standard level:

Setting ctaFlag=true requires all three fields (ctaText, ctaTextAccessibility, ctaLink) to be provided
If limits are set in the content standard, those apply; otherwise, default limits are:

CTA Text:

BANNER_X_SLOT_TYPE_SINGLE_TILE: 15 characters
BANNER_X_SLOT_TYPE_DOUBLE_TILE: 15 characters
BANNER_X_SLOT_TYPE_BANNER: 10 characters
BANNER_X_SLOT_TYPE_UNSPECIFIED: 1000 characters

CTA Link:

Max 200 characters

CTA TextAccessibility:

Max 200 characters

If ctaFlag=false, all CTA fields must be null; otherwise, a 400 Bad Request is returned

If CTA is disabled at the content standard level:

ctaFlag must be set to false, and all CTA fields must be null
Setting ctaFlag=true or providing CTA field values will result in a 400 Bad Request

Create a banner X campaign

post

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 banner X campaign.

application/json

400

There was a problem with input.

application/json

401

application/json

403

application/json

default

An unexpected error response.

application/json

post/v3/bannerx-campaigns

POST /v3/bannerx-campaigns HTTP/1.1
Host: campaign.<env>.citrusad.com
Authorization: YOUR_API_KEY
Content-Type: application/jsona
Accept: */*
Content-Length: 2755

{
  "bannerXCampaign": {
    "advertisedProducts": {
      "productsByKey": [
        {
          "catalogId": "catalog_001",
          "productCode": "PROD123456",
          "sellerId": "seller_78910"
        }
      ]
    },
    "bannerXConfig": {
      "additionalFields": [
        {
          "id": "12345abcde",
          "value": "abcd-8798uhu"
        }
      ],
      "backgroundColourHex": "#FFFFFF",
      "backgroundImageId": "bg_image_001",
      "backgroundImagePosition": "BANNER_X_BACKGROUND_IMAGE_POSITION_REPEATING",
      "bannerText": "Summer Sale: Up to 50% off!",
      "bannerTextColourHex": "#FF5733",
      "contentStandardId": "content_standard_001",
      "ctaFlag": true,
      "ctaLink": "https://www.example.com",
      "ctaText": "Click Here",
      "ctaTextAccessibility": "Click to learn more",
      "headingText": "Welcome to our store!",
      "heroImageAltText": "This is the hero image.",
      "heroImageId": "hero-image-id-456",
      "heroMode": "BANNER_X_HERO_IMAGE_MODE_BLOCK",
      "secondaryBackgroundImageId": "secondary-image-id-123",
      "secondaryBackgroundImagePosition": "BANNER_X_BACKGROUND_IMAGE_POSITION_REPEATING",
      "secondaryHeroImageAltText": "Secondary hero image description",
      "secondaryHeroImageId": "456defghi",
      "secondaryHeroMode": "BANNER_X_HERO_IMAGE_MODE_BLOCK",
      "slotId": "slot_001",
      "slotType": "BANNER_X_SLOT_TYPE_BANNER",
      "trackingTagProvider": [
        {
          "content": "<script src='tracking.js'></script>",
          "provider": "TRACKING_TAG_PROVIDER_DV"
        }
      ]
    },
    "campaignState": "CAMPAIGN_STATE_ACTIVE",
    "catalogIds": [
      "catalog_001",
      "catalog_002"
    ],
    "customFields": [
      {
        "content": "This is a custom field content.",
        "customFieldId": "cfid_12345"
      }
    ],
    "customQuestions": [
      {
        "answers": [
          "Answer 1",
          "Answer 2",
          "Answer 3"
        ],
        "customQuestionId": "cqid_67890"
      }
    ],
    "endTime": "2024-09-30T23:59:59Z",
    "fixedCosts": {
      "creativeCost": "$200.00",
      "dataCost": "$100.00",
      "otherCost": "$50.00"
    },
    "managerTeamId": "manager_team_67890",
    "name": "Summer Sale Campaign",
    "namespaceId": "namespace_001",
    "placementId": "placement_987654321",
    "sellerId": "seller_12345",
    "startTime": "2024-09-01T12:00:00Z",
    "strategy": {
      "auction": {
        "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": {
      "crossSell": {
        "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_EXACT_MATCH",
          "phrase": "text"
        }
      ],
      "searchTerms": [
        {
          "collectionName": "default_collection",
          "matchType": "MATCH_TYPE_PHRASE_MATCH",
          "maxBid": "100.00",
          "phrase": "example search term",
          "treatAsCustom": true
        }
      ],
      "upsell": {
        "targetProductsByKey": [
          {
            "catalogId": "catalog_001",
            "productCode": "PROD123456",
            "sellerId": "seller_78910"
          }
        ]
      }
    },
    "teamId": "team_12345",
    "templateId": "template_123",
    "walletId": "wallet_123456789"
  }
}

{
  "bannerXCampaign": {
    "advertisedProducts": {
      "productsByKey": [
        {
          "catalogId": "catalog_001",
          "productCode": "PROD123456",
          "sellerId": "seller_78910"
        }
      ]
    },
    "approval": {
      "rejectionReason": "text",
      "state": "APPROVAL_STATE_PENDING"
    },
    "bannerXConfig": {
      "additionalFields": [
        {
          "id": "12345abcde",
          "value": "abcd-8798uhu"
        }
      ],
      "backgroundColourHex": "#FFFFFF",
      "backgroundImageId": "bg_image_001",
      "backgroundImagePosition": "BANNER_X_BACKGROUND_IMAGE_POSITION_REPEATING",
      "bannerText": "Summer Sale: Up to 50% off!",
      "bannerTextColourHex": "#FF5733",
      "contentStandardId": "content_standard_001",
      "ctaFlag": true,
      "ctaLink": "https://www.example.com",
      "ctaText": "Click Here",
      "ctaTextAccessibility": "Click to learn more",
      "headingText": "Welcome to our store!",
      "heroImageAltText": "This is the hero image.",
      "heroImageId": "hero-image-id-456",
      "heroMode": "BANNER_X_HERO_IMAGE_MODE_BLOCK",
      "secondaryBackgroundImageId": "secondary-image-id-123",
      "secondaryBackgroundImagePosition": "BANNER_X_BACKGROUND_IMAGE_POSITION_REPEATING",
      "secondaryHeroImageAltText": "Secondary hero image description",
      "secondaryHeroImageId": "456defghi",
      "secondaryHeroMode": "BANNER_X_HERO_IMAGE_MODE_BLOCK",
      "slotId": "slot_001",
      "slotType": "BANNER_X_SLOT_TYPE_BANNER",
      "trackingTagProvider": [
        {
          "content": "<script src='tracking.js'></script>",
          "provider": "TRACKING_TAG_PROVIDER_DV"
        }
      ]
    },
    "campaignState": "CAMPAIGN_STATE_ACTIVE",
    "catalogIds": [
      "catalog_001",
      "catalog_002"
    ],
    "customFields": [
      {
        "content": "This is a custom field content.",
        "customFieldId": "cfid_12345"
      }
    ],
    "customQuestions": [
      {
        "answers": [
          "Answer 1",
          "Answer 2",
          "Answer 3"
        ],
        "customQuestionId": "cqid_67890"
      }
    ],
    "endTime": "2024-09-30T23:59:59Z",
    "fixedCosts": {
      "creativeCost": "$200.00",
      "dataCost": "$100.00",
      "otherCost": "$50.00"
    },
    "id": "abc123xyz",
    "managerTeamId": "manager_team_67890",
    "name": "Summer Sale Campaign",
    "namespaceId": "namespace_001",
    "placementId": "placement_987654321",
    "sellerId": "seller_12345",
    "settings": {
      "campaignType": "CAMPAIGN_TYPE_BANNERX",
      "fromTime": "2024-09-01T12:34:56Z",
      "isWildcard": true,
      "toTime": "2024-09-01T12:34:56Z"
    },
    "startTime": "2024-09-01T12:00:00Z",
    "strategy": {
      "auction": {
        "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": {
      "crossSell": {
        "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_EXACT_MATCH",
          "phrase": "text"
        }
      ],
      "searchTerms": [
        {
          "collectionName": "default_collection",
          "excludedProducts": [
            {
              "catalogId": "catalog_001",
              "productCode": "PROD123456",
              "sellerId": "seller_78910"
            }
          ],
          "matchType": "MATCH_TYPE_PHRASE_MATCH",
          "maxBid": "100.00",
          "phrase": "example search term",
          "suggested": true,
          "treatAsCustom": true
        }
      ],
      "upsell": {
        "targetProductsByKey": [
          {
            "catalogId": "catalog_001",
            "productCode": "PROD123456",
            "sellerId": "seller_78910"
          }
        ]
      }
    },
    "teamId": "team_12345",
    "templateId": "template_123",
    "updateTime": "2024-09-01T12:34:56Z",
    "walletId": "wallet_123456789"
  }
}

PreviousBanner X campaign

NextGet banner X campaign details