> ## 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. # Create sponsored brand auctions ## OpenAPI ````yaml /openapi.json post /v2/auctions/sponsored-brand 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: /v2/auctions/sponsored-brand: post: tags: - Auctions summary: Create sponsored brand auctions operationId: createSponsoredBrandAuctions requestBody: description: > The information describing what will be auctioned. Topsort will run an auction for each batched auction request, for which products bids will compete against each other. content: application/json: example: auctions: - winners: 2 placementId: some-placement triggers: products: ids: - vanilla_yogurt schema: type: object properties: auctions: type: array items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_SponsoredBrandAuctionRequest minItems: 1 maxItems: 5 example: - winners: 2 placementId: some-placement triggers: products: ids: - vanilla_yogurt required: - auctions required: true responses: '201': description: > The sponsored brand auction results. The list of winners will contain at most `winners` entries per auction. It may contain fewer or no entries at all if there aren't enough products with usable bids, that is, a bid amount greater than the reserve price and belonging to a campaign with enough remaining budget. Bids become unusable if campaign budget is exhausted, the bid is disqualified to preserve spend pacing, etc. content: application/json: example: results: - resultType: brand winners: - rank: 1 type: product id: brand-123 resolvedBidId: >- WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= content: headline: Topsort Rocks brandName: Topsort Brand error: false schema: type: object properties: results: type: array items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_SponsoredBrandAuctionResult minItems: 1 maxItems: 5 example: - resultType: brand winners: [] error: false required: - results '400': $ref: '#/components/responses/Topsort_Endpoints_v2_API_Reference_BadRequest' '401': $ref: >- #/components/responses/Topsort_Endpoints_v2_API_Reference_UnauthorizedError security: - Topsort_Endpoints_v2_API_Reference_HTTPBearer: [] components: schemas: Topsort_Endpoints_v2_API_Reference_SponsoredBrandAuctionRequest: type: object description: | Describes the intent of running a sponsored brand auction. Exactly **one** of the following fields must be set: * `products` * `category` * `searchQuery` required: - winners - placementId - triggers properties: winners: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_SlotsCount' placementId: type: string x-stoplight: id: biqordtdbp58t examples: - some-placement-id triggers: type: object description: > Triggers provide the context for an ad auction. For Sponsored Brands, the trigger must be one of the following: a product category, a set of specific products, or a search query. x-stoplight: id: ne5n2vzri6o92 oneOf: - type: object properties: category: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_SingleCategory required: - category description: A trigger based on a product category. - type: object properties: products: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_Products required: - products description: A trigger based on a set of specific products. - type: object properties: searchQuery: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_SearchQuery required: - searchQuery description: A trigger based on a search query. opaqueUserId: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_OpaqueUserID' geoTargeting: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_GeoTargeting' page: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Page' examples: - winners: 2 placementId: some-placement triggers: products: ids: - vanilla_yogurt - nonfat_vanilla_yogurt geoTargeting: location: New York opaqueUserId: user-123 - winners: 2 placementId: some-placement triggers: category: id: c_yogurt geoTargeting: location: New York opaqueUserId: user-123 - winners: 2 placementId: some-placement triggers: searchQuery: vanilla yogurt geoTargeting: location: New York opaqueUserId: user-123 Topsort_Endpoints_v2_API_Reference_SponsoredBrandAuctionResult: title: Sponsored Brand description: >- The result of a sponsored brand auction, containing winning brand promotions. type: object properties: resultType: type: string winners: type: array items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_SponsoredBrandWinner description: > Array of winner objects in order from highest to lowest bid. It will be empty if there were no qualifying bids or if there was an error. error: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_ErrorFlag' required: - winners - error examples: - resultType: brand winners: - rank: 1 resolvedBidId: >- ChAGc-G66Wt7LKQEOcW8VBdIEhABjz_zDXx7db-ZYpxiwJ3DGhABjr4Lt_J0_a7Xv_uIfyOXIgUKATEQATDrrg8 type: url id: https://some.url.com/myyougurtbrand/page title: Brand Example Promo 1 content: headline: some cool regular yogurt headline brandName: my regular yogurt brand creative1: https://some.url.com/regular_yogurt.jpeg productIds: - vanilla_yogurt - strawberry_yogurt - rank: 2 resolvedBidId: >- ChAGc-G66Wt7LKQEOcW8VBdIEhABk0pue7N5wYmzE04uO_iOGhABjr4Lt_J0_a7Xv_uIfyOXIgUKATgQATDrrg8 type: url id: https://some.url.com/mynonfatyougurtbrand/page title: Brand Example Promo 2 content: headline: some cool nonfat regular yogurt headline brandName: my nonfat yogurt brand creative1: https://some.url.com/nonfat_yogurt.jpeg productIds: - nonfat_vanilla_yogurt - nonfat_strawberry_yogurt error: false Topsort_Endpoints_v2_API_Reference_SlotsCount: type: integer format: int32 description: Specifies the maximum number of auction winners that should be returned. minimum: 1 maximum: 40 Topsort_Endpoints_v2_API_Reference_SingleCategory: type: object title: Single Category description: A category for the purpose of running an auction. required: - id properties: id: type: string description: The category ID of the bids that will participate in an auction. minLength: 1 examples: - c_yogurt Topsort_Endpoints_v2_API_Reference_Products: required: - ids type: object description: | List of products for the purpose of running an auction. properties: ids: type: array description: > An array of product IDs that should participate in the auction. We recommend sending no more than 500 products per auction. items: type: string description: > The marketplace's ID of a product which will participate in the auction. These ID must match those in the catalog integration with Topsort. examples: - p_SA0238 minLength: 1 minItems: 1 maxItems: 10000 qualityScores: type: array description: > An array of marketplace defined quality scores, each corresponding to the product ID with matching array index. If given, these values will be combined with our internal quality scores to provide a score that better represents the relevance of the participating products. Note that the length of this array must be the same as the length of the `ids` array and that the values must be greater than 0 and less than or equal to 1. items: type: number maximum: 1 exclusiveMinimum: 0 minimum: 0 examples: - 0.75 format: double minItems: 1 maxItems: 10000 Topsort_Endpoints_v2_API_Reference_SearchQuery: type: string description: The search string provided by a user. Topsort_Endpoints_v2_API_Reference_OpaqueUserID: type: string description: >- The opaque user ID is an anonymized unique identifier that maps to the original user ID without revealing the original value. This identifier allows Topsort to correlate user activity between auctions and user interactions, independent of the user's logged-in status. For apps or sites where users might interact while logged out, we recommend generating a random identifier (UUIDv7) on the first load, storing it on local storage (cookie, local storage, etc), and letting it live for at least a year. Otherwise, if your users are always logged in for interactions, you may use a hash of your customer ID. Correct purchase attribution requires long-lived opaque user IDs consistent between auction and event requests. examples: - 71303ce0-de89-496d-8270-6434589615e8 Topsort_Endpoints_v2_API_Reference_GeoTargeting: type: object description: >- An object describing geographical information associated with this auction. required: - location properties: location: description: The location this auction is being run for. type: string examples: - New York Topsort_Endpoints_v2_API_Reference_Page: description: Information about the page where an auction or event occurs. type: object title: Page required: - type - pageId properties: type: type: string enum: - home - category - PDP - search - cart - other description: Type of page. examples: - category value: oneOf: - type: string description: Detail of the page, depending on the type examples: - electronics - type: array items: type: string description: Only valid for type cart. Items on the cart examples: - coffee - cookies - apples minItems: 1 pageId: type: string description: Identifies the page examples: - /category/electronics Topsort_Endpoints_v2_API_Reference_SponsoredBrandWinner: description: >- A winning bid in a sponsored brand auction with brand and campaign details. type: object required: - rank - type - id - resolvedBidId - content properties: rank: type: integer format: int32 description: > Where the product's bid ranked in the auction. One-based, so the product with rank 1 won the auction. In an auction response, the winners array is sorted so rank will match the entry's index. minimum: 1 type: allOf: - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerType - enum: - product - url id: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerID' examples: - p_Mfk15 - https://some.url.com/topsort-brand resolvedBidId: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_ResolvedBidID title: type: string description: >- An optional title for the sponsored brand selected when creating the campaign. vendorId: type: string description: The ID of the vendor associated with this sponsored brand winner. examples: - v_8fj2D productIds: description: >- List of product IDs associated with the sponsored brand winning campaign. type: array examples: - - product123 - product456 content: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_SponsoredBrandContent Topsort_Endpoints_v2_API_Reference_ErrorFlag: type: boolean description: A boolean indicating whether this auction was resolved successfully. examples: - false - true Topsort_Endpoints_v2_API_Reference_Error: description: >- Error response object containing error code, message, and documentation URL. type: object required: - errCode properties: errCode: type: string description: A short string uniquely identifying the problem. enum: - bad_request - empty_request - internal_server_error - invalid_api_key - invalid_auction_id - invalid_demand_source - invalid_event_type - invalid_external_bid - invalid_external_demand_ad_type - invalid_promotion_type - invalid_session - missing_auctions - missing_context - missing_placement - missing_product_id - missing_promotion_type - missing_purchased_at - missing_session - missing_slot_id - missing_slots - no_products - no_purchase_items - purchase_item_quantity_less_or_equal_than_zero - resolved_bid_id_not_found - too_few_impressions - too_few_slots - too_many_auctions - too_many_external_bids - unauthorized_external_demand examples: - bad_request - no_products docUrl: type: string format: uri description: >- A link to a documentation page providing more information about the error. examples: - https://api.docs.topsort.com/reference/errors message: type: string description: > Human-readable explanation of or details about the error. The string for a given error may change over time; code should not parse or dispatch based on particular values for this field. examples: - could not find the provided resolved bid id Topsort_Endpoints_v2_API_Reference_WinnerType: type: string description: The target type of the winning bid. Topsort_Endpoints_v2_API_Reference_WinnerID: type: string description: >- The marketplace's ID of the winning entity, depending on the target of the campaign. Topsort_Endpoints_v2_API_Reference_ResolvedBidID: type: string description: An opaque Topsort ID to be used when this item is interacted with. examples: - >- WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= Topsort_Endpoints_v2_API_Reference_SponsoredBrandContent: type: object additionalProperties: true description: > A flexible JSON object with key-value pairs that map to the asset's filled content template. The template can be customized by the marketplace. examples: - headline: Topsort Rocks brandName: Topsort Brand creative: https://some.url.com/rocks.jpeg responses: Topsort_Endpoints_v2_API_Reference_BadRequest: description: HTTP status codes as registered with IANA. content: application/json: schema: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Error' Topsort_Endpoints_v2_API_Reference_UnauthorizedError: description: Access token is missing or invalid securitySchemes: Topsort_Endpoints_v2_API_Reference_HTTPBearer: description: >- A valid API key generated in Topsort's UI. Use a TSE API key for calls to Auctions or Events API. scheme: bearer type: http ````