> ## Documentation Index > Fetch the complete documentation index at: https://docs.topsort.com/llms.txt > Use this file to discover all available pages before exploring further. # [BETA] Create exclusive banner campaign. > Endpoint to create exclusive banner campaigns and its respective bids. Exclusive campaigns override auctions and are always shown by a fixed daily price. ## OpenAPI ````yaml /openapi.json post /public/v1/campaign-service/campaigns/exclusive-banner openapi: 3.1.0 info: title: Topsort Endpoints v2 API Reference description: > In order for a storefront to be able to run auctions in Topsort and report auction-related events back to Topsort, both the `/v2/auctions` and `/v2/events` endpoints must be integrated. Below are the endpoint and model definitions for each. contact: email: wicha@topsort.com license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html x-logo: url: https://assets.topsort.com/Topsort_logo_icon_dark.svg backgroundColor: '#fff' altText: Topsort version: 2.0.0 servers: - url: https://api.topsort.com description: Base API URL security: [] tags: - name: Auctions description: >- An auction determines which products should be promoted based on the vendors' bids. - name: Events description: >- Events are sent to Topsort as part of the attribution and reporting journey. - name: Toptimize description: > An out-of-the-box solution for prediction, ranking, retrieval, and other elements of ad selection. - name: Toppie API description: Toppie management API. - name: Campaign API description: Full-featured campaign management API for banners and sponsored listings. - name: Catalog API description: Products catalog management API. - name: Billing API description: Marketplace and Vendor Billing management API. - name: Reporting API description: Marketplace, Vendor, Campaign, and product reporting API. - name: Invitation API description: Vendor invitations management API. - name: User API description: User management API. - name: Webhooks API description: Webhooks API that allows event-driven automation. - name: Assets API description: Assets management API. - name: Segments Service description: Segments Service. - name: Forecasting Service description: Toptimize Forecasting Service. - name: Offsite Ads API description: Offsite Ads API that allows to manage offsite ads campaigns. - name: Media API description: Ad configuration API. paths: /public/v1/campaign-service/campaigns/exclusive-banner: post: tags: - Campaign API summary: '[BETA] Create exclusive banner campaign.' description: >- Endpoint to create exclusive banner campaigns and its respective bids. Exclusive campaigns override auctions and are always shown by a fixed daily price. operationId: create_exclusive_banner_campaign parameters: - name: vendor_id in: query required: true schema: type: string minLength: 1 description: The ID of the vendor. description: The ID of the vendor. requestBody: required: true content: application/json: schema: $ref: >- #/components/schemas/Advanced_APIs_PublicExclusiveBannerCampaignCreateRequest responses: '200': description: Successful Response content: application/json: schema: $ref: >- #/components/schemas/Advanced_APIs_PublicExclusiveBannerCampaign '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/Advanced_APIs_HTTPValidationError' security: - Advanced_APIs_HTTPBearer: [] components: schemas: Advanced_APIs_PublicExclusiveBannerCampaignCreateRequest: properties: name: type: string minLength: 1 title: Name description: The name of the campaign. examples: - Bola-Bola Ad campaign isActive: type: boolean title: Isactive description: >- Whether the campaign should be activated upon creation.The campaign will start when this is set _and_ the `start_date` has passed. default: true externalCampaignId: title: Externalcampaignid description: >- The external ID of the campaign in the marketplace. Must be unique per marketplace and format combination. oneOf: - type: string - type: 'null' isAutoTrigger: type: boolean title: Isautotrigger description: Whether the campaign is auto-triggered. default: false startDate: type: string format: date-time title: Startdate description: >- When should the campaign start. If the start date is in the past, it will be set to the current date. endDate: type: string format: date-time title: Enddate description: When should the campaign stop. Must be greater than start date. exclusivityPrice: type: integer title: Exclusivityprice description: The price to pay daily for the campaign to run. position: type: integer maximum: 20 minimum: 1 title: Position description: The rank the ad will have in the auction default: 1 walletId: title: Walletid description: The uuid of the wallet to be used with this campaign. oneOf: - type: string format: uuid - type: 'null' impressionsThreshold: title: Impressionsthreshold description: Impressions allowed for the campaign before it is stopped. oneOf: - type: integer - type: 'null' exclusivityPercentage: title: Exclusivitypercentage description: Percentage of auctions the campaign will be exclusive in. oneOf: - type: number - type: 'null' bids: items: $ref: '#/components/schemas/Advanced_APIs_BidCreate' type: array minItems: 1 title: Bids description: An array of bids for this campaign. status: $ref: '#/components/schemas/Advanced_APIs_CampaignStatus' description: For an exclusive banner campaign, its initial review status. default: pending productIds: items: type: string type: array maxItems: 250 uniqueItems: true title: Productids description: >- The product IDs to be associated with the exclusive banner campaign. When provided, replaces the existing set of products on the campaign. type: object required: - name - startDate - endDate - exclusivityPrice - bids title: PublicExclusiveBannerCampaignCreateRequest description: The request body for creating an exclusive banner campaign. Advanced_APIs_PublicExclusiveBannerCampaign: properties: name: type: string minLength: 1 title: Name description: The name of the campaign. examples: - Bola-Bola Ad campaign isActive: type: boolean title: Isactive description: >- Whether the campaign should be activated upon creation.The campaign will start when this is set _and_ the `start_date` has passed. default: true externalCampaignId: title: Externalcampaignid description: The external ID of the campaign in the marketplace. oneOf: - type: string - type: 'null' isAutoTrigger: type: boolean title: Isautotrigger description: Whether the campaign is auto-triggered. default: false marketplaceId: type: string format: uuid title: Marketplaceid description: The ID of the marketplace. campaignId: type: string format: uuid title: Campaignid description: The ID of the campaign. startDate: type: string format: date-time title: Startdate description: >- Date when to start the campaign, specified in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6), if not set that campaign will start immediately after the campaign creation. Must include the Timezone definition.If the start date is in the past, it will be set to the current date. endDate: type: string format: date-time title: Enddate description: >- Date when to stop the campaign, specified in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6), if not set the campaign will never stop. This date must be greater than the start date and must be in the future. Must include the Timezone definition. default: '9999-12-31T22:59:59.999999Z' exclusivityPrice: type: integer title: Exclusivityprice description: The price to pay daily for the campaign to run. bidType: type: string const: exclusive title: Bidtype description: The bidding type of the campaign. default: exclusive createdBy: title: Createdby description: The ID of the user creating the campaign. oneOf: - type: string format: uuid - type: 'null' chargeType: $ref: '#/components/schemas/Advanced_APIs_ExclusiveCampaignChargeType' description: >- How exclusive campaigns are going to be charged, only daily is allowed. position: type: integer maximum: 20 minimum: 1 title: Position description: The rank the ad will have in the auction default: 1 campaignType: $ref: '#/components/schemas/Advanced_APIs_CampaignType' status: $ref: '#/components/schemas/Advanced_APIs_CampaignStatus' description: For an exclusive banner campaign, its initial review status. default: pending adFormat: type: string const: exclusive_banner title: Adformat description: The ad format of the campaign. Can be exclusive_banner. examples: - exclusive_banner vendorId: type: string title: Vendorid description: The marketplace's ID of the vendor. impressionsThreshold: title: Impressionsthreshold description: Impressions allowed for the campaign before it is stopped. oneOf: - type: integer - type: 'null' exclusivityPercentage: title: Exclusivitypercentage description: Percentage of auctions the campaign will be exclusive in. oneOf: - type: number - type: 'null' walletId: type: string format: uuid title: Walletid description: The uuid of the wallet to be used with this campaign. type: object required: - name - marketplaceId - campaignId - exclusivityPrice - chargeType - campaignType - adFormat - vendorId - walletId title: PublicExclusiveBannerCampaign description: Model that represents an Exclusive Banner Campaign. Advanced_APIs_HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/Advanced_APIs_ValidationError' type: array title: Detail type: object title: HTTPValidationError Advanced_APIs_BidCreate: properties: amount: format: int32 title: Amount description: >- Maximum amount of money willing to offer for a sponsored slot in minor units of currency according to ISO 4217. oneOf: - type: integer exclusiveMaximum: 2000000000 exclusiveMinimum: 0 - type: 'null' location: title: Location description: >- By using this option you will be able to target this campaign to a specific group.You must define the same location as a parameter on the auction request. Products on a specific campaign will have specific conversion rates, considering the context of location, so it will not interfere with the conversion rates for the same product in other campaigns. examples: - Santiago oneOf: - type: string minLength: 1 - type: 'null' target: $ref: '#/components/schemas/Advanced_APIs_Entity' triggers: items: oneOf: - $ref: '#/components/schemas/Advanced_APIs_KeywordTrigger-Input' - $ref: '#/components/schemas/Advanced_APIs_CategoryTrigger' - $ref: '#/components/schemas/Advanced_APIs_CategoriesTrigger' - $ref: '#/components/schemas/Advanced_APIs_ProductTrigger' - $ref: '#/components/schemas/Advanced_APIs_NoContextTrigger' - $ref: >- #/components/schemas/Advanced_APIs_KeywordsFromCampaignProductsTrigger - $ref: >- #/components/schemas/Advanced_APIs_CategoriesFromCampaignProductsTrigger description: When should this bid participate in an auction. discriminator: propertyName: type mapping: categories: $ref: '#/components/schemas/Advanced_APIs_CategoriesTrigger' categories_from_campaign_products: $ref: >- #/components/schemas/Advanced_APIs_CategoriesFromCampaignProductsTrigger category: $ref: '#/components/schemas/Advanced_APIs_CategoryTrigger' keyword: $ref: '#/components/schemas/Advanced_APIs_KeywordTrigger-Input' keywords_from_campaign_products: $ref: >- #/components/schemas/Advanced_APIs_KeywordsFromCampaignProductsTrigger nocontext: $ref: '#/components/schemas/Advanced_APIs_NoContextTrigger' product: $ref: '#/components/schemas/Advanced_APIs_ProductTrigger' type: array minItems: 1 title: Triggers description: >- A list of objects that trigger the appearance of this bid on an auction. default: [] formatProperties: description: >- The format properties of the bid. This field is required for banner ads. Should be not set for listing ads. oneOf: - $ref: '#/components/schemas/Advanced_APIs_BannerAd-Input' - type: 'null' type: object required: - target title: BidCreate description: The request model for bid creation. Advanced_APIs_CampaignStatus: type: string enum: - approved - pending - rejected title: CampaignStatus description: Represents the review status of a banner campaign. Advanced_APIs_ExclusiveCampaignChargeType: type: string enum: - DAILY title: ExclusiveCampaignChargeType description: Charge types for exclusive campaigns. Advanced_APIs_CampaignType: type: string enum: - manual - autobidding - exclusive title: CampaignType description: The bidding method for the campaign. Advanced_APIs_ValidationError: properties: loc: items: oneOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError Advanced_APIs_Entity: properties: id: type: string maxLength: 256 minLength: 1 title: Id description: The unique ID of the entity. examples: - p_8983 type: $ref: '#/components/schemas/Advanced_APIs_CampaignEntityType' examples: - product type: object required: - id - type title: Entity description: >- Represents a promotable entity that will be returned upon a winning auction. Advanced_APIs_KeywordTrigger-Input: properties: type: type: string const: keyword title: Type value: $ref: '#/components/schemas/Advanced_APIs_KeywordValue' type: object required: - type - value title: KeywordTrigger description: |- Collection of keywords that match to a product. Ideal for search results pages. Advanced_APIs_CategoryTrigger: properties: type: type: string const: category title: Type value: $ref: '#/components/schemas/Advanced_APIs_CategoryValue' type: object required: - type - value title: CategoryTrigger description: |- Catalog-based category from a product. Ideal for category product listing pages. Advanced_APIs_CategoriesTrigger: properties: type: type: string const: categories title: Type value: $ref: '#/components/schemas/Advanced_APIs_CategoriesValue' type: object required: - type - value title: CategoriesTrigger description: |- Catalog-based categories from a product. Ideal for category product listing pages. Not allowed for banner ads. Advanced_APIs_ProductTrigger: properties: type: type: string const: product title: Type value: $ref: '#/components/schemas/Advanced_APIs_ProductValue' type: object required: - type - value title: ProductTrigger description: The ID of a product. Advanced_APIs_NoContextTrigger: properties: type: type: string const: nocontext title: Type type: object required: - type title: NoContextTrigger description: |- A blank trigger for times when none of the other filters are used. Ideal for Landing pages. Advanced_APIs_KeywordsFromCampaignProductsTrigger: properties: type: type: string const: keywords_from_campaign_products title: Type type: object required: - type title: KeywordsFromCampaignProductsTrigger description: Keywords from campaign products. Advanced_APIs_CategoriesFromCampaignProductsTrigger: properties: type: type: string const: categories_from_campaign_products title: Type type: object required: - type title: CategoriesFromCampaignProductsTrigger description: Categories from campaign products. Advanced_APIs_BannerAd-Input: properties: bannerAssets: items: $ref: '#/components/schemas/Advanced_APIs_BannerAsset' type: array minItems: 1 title: Bannerassets description: The assets for the banner campaign, if `adFormat` is `banner`. slotId: type: string minLength: 1 pattern: ^[\w!\"#$%&'()*+,\-._/:;<>?@\[\]^\{\}~=\\]*$ title: Slotid description: The external slot id provided by the marketplace. deviceType: $ref: '#/components/schemas/Advanced_APIs_DeviceType' description: The targeted device for this campaign, if `adFormat` is `banner`. default: desktop examples: - desktop adFormat: type: string const: banner title: Adformat type: object required: - bannerAssets - slotId - adFormat title: BannerAd Advanced_APIs_CampaignEntityType: type: string enum: - product - brand - vendor - url title: CampaignEntityType description: The type of the entity to be advertised. Advanced_APIs_KeywordValue: properties: words: items: type: string type: array maxItems: 5000 title: Words description: The list of keywords. matchType: $ref: '#/components/schemas/Advanced_APIs_KeywordMatchType' type: object required: - words - matchType title: KeywordValue Advanced_APIs_CategoryValue: properties: categoryId: type: string title: Categoryid description: The ID of the category. type: object required: - categoryId title: CategoryValue Advanced_APIs_CategoriesValue: properties: fromProduct: type: string title: Fromproduct description: The ID of the product to retrieve categories from. type: object required: - fromProduct title: CategoriesValue Advanced_APIs_ProductValue: properties: productId: type: string title: Productid description: The ID of the product. type: object required: - productId title: ProductValue Advanced_APIs_BannerAsset: properties: url: title: Url description: >- The url where the asset is located. If asset_id is provided, this field will be ignored. oneOf: - type: string maxLength: 2083 minLength: 1 format: uri - type: 'null' contentType: title: Contenttype description: >- The mime type of the asset. If asset_id is provided, this field will be ignored. examples: - image/png oneOf: - type: string minLength: 1 - type: 'null' dimensions: $ref: '#/components/schemas/Advanced_APIs_Dimensions' size: title: Size description: >- The file size of the asset, in bytes. If asset_id is provided, this field will be ignored. oneOf: - type: integer - type: 'null' assetId: title: Assetid description: Asset id, if created using the asset API. examples: - asset_01j713j64yfsvtj4bs3ccpy5ca oneOf: - type: string maxLength: 33 - type: 'null' content: title: Content description: >- Custom additional metadata about the banner. If provided, the asset_id and url fields will be ignored. Maximum size is 20KB when serialized. oneOf: - additionalProperties: oneOf: - type: string - items: type: string type: array type: object - type: 'null' jsonTemplateId: title: Jsontemplateid description: >- The id of the json template that was used to create the json content. oneOf: - type: string format: uuid - type: 'null' type: object required: - dimensions title: BannerAsset description: >- Represents the banner resource file, it's location, mimetype, dimensions and size. Advanced_APIs_DeviceType: type: string enum: - mobile - desktop title: DeviceType description: The device where a banner ad should appear. Advanced_APIs_KeywordMatchType: type: string enum: - exact - phrase title: KeywordMatchType Advanced_APIs_Dimensions: properties: width: type: integer exclusiveMinimum: 0 title: Width description: The width of the image. examples: - 1920 height: type: integer exclusiveMinimum: 0 title: Height description: The height of the image. examples: - 1080 type: object required: - width - height title: Dimensions description: The width and height of an asset. securitySchemes: Advanced_APIs_HTTPBearer: type: http description: >- A valid API key generated in Topsort's UI. Use the TSE API key if calling auctions or events API, otherwise use the TSC API key. scheme: bearer ````