> ## 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 travel auctions > Use the `/auctions/travel` endpoint to create batch auctions for sponsored travel listings. We support two types of sponsored travel listings, hotels and flights. Each batch of auction requests can be a combination of sponsored hotel and flight listing auctions. Each auction type has a unique body schemas. ## OpenAPI ````yaml /openapi.json post /v2/auctions/travel 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/travel: post: tags: - Auctions summary: Create travel auctions description: >- Use the `/auctions/travel` endpoint to create batch auctions for sponsored travel listings. We support two types of sponsored travel listings, hotels and flights. Each batch of auction requests can be a combination of sponsored hotel and flight listing auctions. Each auction type has a unique body schemas. operationId: createTravelAuctions requestBody: description: > The information describing what will be auctioned. Topsort will run an auction for each batched auction request, for which travel products' bids will compete against each other. content: application/json: schema: type: object properties: auctions: type: array items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_TravelAuctionRequest minItems: 1 maxItems: 5 example: - type: hotels slots: 2 travelContext: site: argentina required: - auctions examples: default: value: auctions: - type: hotels slots: 2 products: - id: hotel-1 qualityScore: 0.7 - id: hotel-2 category: singleCategory: id: hotel-boutique travelContext: travelStartDate: '2025-01-01' travelEndDate: '2025-01-15' site: argentina passengers: 2 travelerType: couple - type: flights slots: 2 products: - id: L0_SAO-ORL variationID: '001' price: 1500 qualityScore: 0.7 - id: L0_SAO-ORL variationID: '002' price: 2000 travelContext: site: argentina passengers: 2 route: SAO-ORL flightType: one-way required: true responses: '201': description: > The travel 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: schema: type: object properties: results: type: array items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_TravelAuctionResult minItems: 1 maxItems: 5 required: - results examples: default: value: results: - resultType: hotels winners: - rank: 1 type: product id: hotel-1 resolvedBidId: >- ChAHd-K97Xs8MNRELdY9VCeJFiBCk1_aEYz8eb-WZqyhzL4EFhBCk5Mt_X2_b8Yu_vXJgzPWJhVLBTFRBTGssk9 campaignId: 8b816367-da17-4c65-9a26-391edf01a10d - rank: 2 type: product id: hotel-2 resolvedBidId: >- ChAJe-M23Yr5QPTEFdX7VBgJGhCDm2_wDXy6cb-XZpxjxK6GHhCDm3Ku_W1_c9Zw_wYHfzQYKjTLBVGQBTLttu6 campaignId: 7be0d8c8-243c-41af-bb43-b43ef4935672 error: false - resultType: flights winners: - rank: 1 type: product id: L0_SAO-ORL resolvedBidId: >- ChAKf-N45Vq3LOTEGcW9VDhKHjADk3_zCXx8db-XZsyiwM2HIjADk4Lr_X0_b9Xw_uKHgyRZKhUKCTHQCTHrrh7 campaignId: 8ab7b29e-1934-4ec9-ad87-60c285bc7f38 variationID: '002' - rank: 2 type: product id: L0_SAO-ORL resolvedBidId: >- ChAGg-P56Wu4MRUEHdX8VEfLHkBEk4_aEXz9fb-YZtxjwN3IJkBEk5Ms_W2_c8Yx_vZJhzSXKlVLDUJQDUJssl8 campaignId: cb8ed0a7-0ecf-4ffb-a863-022f862649ec variationID: '001' error: false '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_TravelAuctionRequest: description: Describes the intent of running a single auction. oneOf: - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_HotelsAuctionRequest - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_FlightsAuctionRequest Topsort_Endpoints_v2_API_Reference_TravelAuctionResult: description: The result of a travel-related auction request (hotels or flights). oneOf: - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_SponsoredListingsAuctionResult - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_FlightsAuctionResult - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_EmptyAuctionResult Topsort_Endpoints_v2_API_Reference_HotelsAuctionRequest: title: Hotels type: object description: Describes the intent of running a hotel travel auction. required: - travelContext - slots properties: type: type: string enum: - hotels description: Discriminator for the type of travel auction. slots: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_SlotsCount' description: >- Specifies the maximum number of auction winners that should be returned. If slots > 40, it is capped at 40. products: type: array description: An array of hotels products that should participate in the auction. items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_HotelsTravelProduct category: description: A category for the purpose of running an auction. type: object required: - singleCategory properties: singleCategory: type: object required: - id properties: id: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_CategoryID examples: - c_buenos-aires-hotels travelContext: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_BaseTravelContext Topsort_Endpoints_v2_API_Reference_FlightsAuctionRequest: title: Flights type: object description: Describes the intent of running a flight travel auction. required: - travelContext - slots properties: type: type: string enum: - flights description: Discriminator for the type of travel auction. slots: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_SlotsCount' description: >- Specifies the maximum number of auction winners that should be returned. If slots > 40, it is capped at 40. products: type: array description: An array of flights that should participate in the auction. items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_FlightsTravelProduct travelContext: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_FlightsTravelContext Topsort_Endpoints_v2_API_Reference_SponsoredListingsAuctionResult: title: Sponsored Listings description: >- The result of a sponsored listings auction, containing winning product listings. type: object properties: resultType: type: string winners: type: array items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_SponsoredListingsWinner 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 - resultType Topsort_Endpoints_v2_API_Reference_FlightsAuctionResult: title: Flights description: >- The result of a flights travel auction, containing winning flight products. type: object properties: resultType: type: string winners: type: array items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_FlightsWinner 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 - resultType Topsort_Endpoints_v2_API_Reference_EmptyAuctionResult: title: Empty Auction description: >- An auction result with no winners, typically when no eligible bids are available. type: object properties: resultType: type: string winners: type: array maxItems: 0 error: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_ErrorFlag' required: - winners - error - resultType 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_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_HotelsTravelProduct: description: A hotel product that can participate in a travel auction. type: object required: - id properties: id: type: string description: ID to identify hotel product. examples: - miami-hotel qualityScore: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_QualityScore' Topsort_Endpoints_v2_API_Reference_CategoryID: type: string description: A category ID. minLength: 1 examples: - c_electronics Topsort_Endpoints_v2_API_Reference_BaseTravelContext: description: >- Base context information for travel-related auctions including dates, location, and traveler details. type: object required: - site properties: site: type: string minLength: 1 maxLength: 64 description: Web site requesting the auction examples: - argentina passengers: type: integer description: Number of passengers. Must not exceed 10. examples: - 3 travelStartDate: type: string format: date description: RFC3339 formatted date representing the travel start point. examples: - '2024-06-10' travelEndDate: type: string format: date description: > RFC3339 formatted date representing the travel end point. Must be greater than start date. examples: - '2025-08-10' travelerType: type: string enum: - family - group - solo - couple pageName: type: string description: Page name e.g. "flights", "hotels", "package", ... platform: type: string description: Platform e.g. "app", "mobile", "web", ... Topsort_Endpoints_v2_API_Reference_FlightsTravelProduct: description: A flight that can participate in a travel auction. type: object required: - id properties: id: type: string description: ID to identify a flight. examples: - L0_SAO-ORL variationID: type: string description: ID to identify flights variation. price: type: number description: Flight variation total price in marketplace currency. qualityScore: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_QualityScore' Topsort_Endpoints_v2_API_Reference_FlightsTravelContext: description: >- Context information specific to flight travel auctions including route and flight type. allOf: - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_BaseTravelContext - type: object properties: route: type: string description: Flight route code. flightType: type: string description: Flight type e.g. "round_trip", "one_way", ... Topsort_Endpoints_v2_API_Reference_SponsoredListingsWinner: description: >- A winning bid in a sponsored listings auction with product and campaign details. type: object required: - rank - type - id - resolvedBidId - campaignId properties: rank: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerRank' type: allOf: - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerType - enum: - product - vendor - brand - url id: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerID' examples: - p_Mfk15 resolvedBidId: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_ResolvedBidID campaignId: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_CampaignId' 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_FlightsWinner: description: A winning bid in a flights auction with flights and campaign details. type: object required: - rank - type - id - resolvedBidId - campaignId - variationID properties: rank: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerRank' type: allOf: - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerType - enum: - product id: type: string description: >- The marketplace's ID of the winning flight, depending on the target of the campaign. examples: - p_Mfk15 resolvedBidId: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_ResolvedBidID campaignId: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_CampaignId' variationID: type: string description: The marketplace's ID for the winning flight's variation. Topsort_Endpoints_v2_API_Reference_QualityScore: type: number maximum: 1 exclusiveMinimum: 0 format: double description: | If given, this value will be combined with our internal quality score to provide a score that better represents the relevance of the participating products. If not given it will default to 1. Values must be between 0 and 1. examples: - 0.75 Topsort_Endpoints_v2_API_Reference_WinnerRank: type: integer format: int32 description: >- The rank/position of this winner in the auction results, with 1 being the highest. minimum: 1 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_CampaignId: type: string description: The ID of the campaign that won the auction. examples: - 82588593-85c5-47c0-b125-07e315b7f2b3 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 ````