{ "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,\nboth the `/v2/auctions` and `/v2/events` endpoints must be integrated.\nBelow are the endpoint and model definitions for each.\n", "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" } ], "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.\n" }, { "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": { "post": { "tags": [ "Auctions" ], "summary": "Create auctions", "description": "Use the `/auctions` endpoint to create auctions. Each batch of auction requests can be a combination of sponsored listing auctions and banner auctions. Each auction type has a unique body schemas.\n", "operationId": "createAuctions", "requestBody": { "description": "The information describing what will be auctioned.\nTopsort will run an auction for each batched auction request, for which products' bids will compete against each other.\n", "content": { "application/json": { "examples": { "default": { "summary": "Basic listings auction", "value": { "auctions": [ { "type": "listings", "slots": 2, "products": { "ids": [ "p_PJbnN", "p_ojng4" ] } } ] } }, "externalDemand": { "summary": "Listings auction with external demand (e.g., Criteo)", "value": { "auctions": [ { "type": "listings", "slots": 3, "products": { "ids": [ "p_PJbnN", "p_ojng4", "p_8VKDt" ] }, "demandSources": [ { "source": "criteo", "bids": [ { "chargeType": "CPC", "entity": { "type": "product", "id": "p_PJbnN" }, "bidAmount": 0.5, "metadata": { "clickUrl": "https://example.com/click" } }, { "chargeType": "CPC", "entity": { "type": "product", "id": "p_ojng4" }, "bidAmount": 0.35, "metadata": { "clickUrl": "https://example.com/product/ojng4" } } ] } ] } ] } } }, "schema": { "type": "object", "properties": { "auctions": { "type": "array", "items": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_AuctionRequest" }, "minItems": 1, "maxItems": 5, "example": [ { "type": "listings", "slots": 2, "products": { "ids": [ "p_PJbnN" ] } } ] } } } } }, "required": true }, "responses": { "201": { "description": "The auction results. The list of winners will contain at most `slots` 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.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_AuctionResult" }, "minItems": 1, "maxItems": 5, "example": [ { "resultType": "listings", "winners": [], "error": false } ] } }, "required": [ "results" ] }, "examples": { "listingsAndBanners": { "summary": "Listings and banner auction results", "value": { "results": [ { "resultType": "listings", "winners": [ { "rank": 1, "type": "product", "id": "p_Mfk11", "resolvedBidId": "WyJiX01mazExIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTMyNjYtY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0==", "campaignId": "82588593-85c5-47c0-b125-07e315b7f2b3" } ], "error": false }, { "resultType": "listings", "winners": [ { "rank": 1, "type": "product", "id": "p_Mfk15", "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=", "campaignId": "4bcc6093-f367-4df2-aa1b-7c1674dd6441" }, { "rank": 2, "type": "product", "id": "p_PJbnN", "resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=", "campaignId": "a72e4e43-55b5-4d08-81bb-cbb57df59c72" } ], "error": false }, { "resultType": "banners", "winners": [ { "rank": 1, "type": "product", "id": "p_PJbnN", "resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwiYmFubmVyQWRzIiwiZGVmYXVsdCIsIiJd", "campaignId": "1156ef4e-0109-4190-ac97-4436c82358d2", "asset": [ { "url": "https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-1x.png", "content": { "headingText": "A banner for Topsort with a product image and a shop now button", "bannerText": "Topsort has the best tech!", "bannerTextColour": "48a94c", "heroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574", "heroImageAltText": "Topsort product image" } } ] } ], "error": false } ] } }, "empty": { "summary": "Empty auction (no winners)", "value": { "results": [ { "resultType": "listings", "winners": [], "error": false } ] } }, "externalDemand": { "summary": "External demand (Criteo + Topsort winners)", "value": { "results": [ { "resultType": "external_demand_listings", "winners": [ { "rank": 1, "type": "product", "id": "p_PJbnN", "resolvedBidId": "WyJiX1BKYm5OIiwiY3JpdGVvIiwiQ1BDIiwibGlzdGluZ3MiXQ==", "demandSource": "criteo", "metadata": { "clickUrl": "https://example.com/click" } }, { "rank": 2, "type": "product", "id": "p_Mfk15", "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=", "demandSource": "topsort", "campaignId": "4bcc6093-f367-4df2-aa1b-7c1674dd6441" } ], "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": [] } ] } }, "/v2/auctions/sponsored-brand": { "post": { "tags": [ "Auctions" ], "summary": "Create sponsored brand auctions", "operationId": "createSponsoredBrandAuctions", "requestBody": { "description": "The information describing what will be auctioned.\nTopsort will run an auction for each batched auction request, for which products bids will compete against each other.\n", "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.\n", "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": [] } ] } }, "/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.\nTopsort will run an auction for each batched auction request, for which travel products' bids will compete against each other.\n", "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.\n", "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": [] } ] } }, "/v2/events": { "post": { "tags": [ "Events" ], "summary": "Report events", "description": "Use the `/events` endpoint to report user interactions and activity in on a marketplace:\n- **Impressions** — a user viewed an asset.\n- **Clicks** — a user clicked on an asset.\n- **Purchases** — a user created an order.\n- **Page views** — a user visited a page.\n\nInteractions require either a `resolvedBidId`, for sponsored events coming from the `/v2/auctions` response,\nor an `entity` that describes the entity that was interacted with, in the case of organic or non-sponsored events.\nFor analytics purposes, you can use the `placement` field to differentiate different listings or banners.\nFor example, on a product page with a carousel of products, you can track impressions and clicks related to the carousel\nby including `/carousel` at the end of the `path` field in the `placement` object. This allows you to monitor\nthe performance of carousel products in the [Data Room](https://docs.topsort.com/knowledge-base/analytics/data-room/).\n", "operationId": "reportEvents", "requestBody": { "description": "Event data including impressions, clicks, purchases, and page views.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_EventsRequest" } } }, "required": true }, "responses": { "204": { "description": "All events were reported successfully." }, "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": [] } ] } }, "/v2/events/beta/link-users": { "post": { "tags": [ "Events" ], "summary": "[Beta] Report Link Users", "description": "Use the `/events/beta/link-users` endpoint to report to Topsort linked opaque user IDs.\nThis endpoint allows linking two opaque user IDs for attribution purposes. The `from` field represents the original opaque user ID, and the `to` field represents the target opaque user ID to be linked. The request will fail if the `from` and `to` opaque user IDs are the same.\nContact your sales representative to gain access to this endpoint and start using it.\n", "x-beta": "true", "operationId": "linkUsers", "requestBody": { "description": "Request to link multiple user IDs that represent the same user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "description": "The opaque user ID of the original user account.", "minLength": 1, "maxLength": 64, "examples": [ "user_abc123" ] }, "to": { "type": "string", "description": "The opaque user ID of the target user account to be linked.", "minLength": 1, "maxLength": 64, "examples": [ "user_xyz789" ] } }, "required": [ "from", "to" ] }, "examples": { "default": { "value": { "from": "user123", "to": "user456" } } } } }, "required": true }, "responses": { "204": { "description": "Users account link was reported successfully." }, "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": [] } ] } }, "/toptimize/v1/rank": { "post": { "tags": [ "Toptimize" ], "summary": "[Beta] Rank objects", "operationId": "createRanking", "description": "> ⚠️ **Beta Access Required**\n\n> Contact your sales representative to gain access to this endpoint and start using it.\n\nUse the `/ranking` endpoint to re-rank objects to show on a page. This endpoint can retrieve sponsored\nand non-sonsored objects and rank them together, according to an appropriate context and behavior information.\n", "requestBody": { "description": "The context information to get the ranking, to rank organic and sponsored products.\n", "x-beta": "true", "content": { "application/json": { "schema": { "type": "object", "properties": { "ranking": { "type": "array", "items": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_RankingRequest" }, "minItems": 1, "maxItems": 5, "example": [ { "type": "listings", "slots": 3, "pageSize": 3, "page": { "type": "category", "value": "sneakers", "pageId": "/category/sneakers" }, "opaqueUserId": "u_9ske45" } ] } }, "required": [ "ranking" ] }, "examples": { "default": { "value": { "ranking": [ { "type": "listings", "slots": 3, "pageSize": 3, "page": { "type": "category", "value": "sneakers", "pageId": "/category/sneakers" }, "opaqueUserId": "u_9ske45", "category": { "ids": [ "sneakers", "shoes" ] }, "products": { "ids": [ "p_PJbnN", "p_ojng4" ] } } ] } } } } }, "required": true }, "responses": { "201": { "description": "The ranking results. The list of winners will contain at most `slots` entries per auction. It may contain fewer or no entries at all if there aren't enough products to fill the slots.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_RankingResult" }, "minItems": 1, "maxItems": 5, "example": [ { "resultType": "listings", "results": [], "error": false } ] } }, "required": [ "results" ] }, "examples": { "default": { "value": { "results": [ { "resultType": "listings", "results": [ { "rank": 1, "type": "organic", "id": "p_Mfk11", "resolvedItemId": "WyJiX01mazExIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTMyNjYtY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0==" }, { "rank": 2, "type": "sponsored", "id": "p_Mfk15", "resolvedItemId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=" }, { "rank": 3, "type": "organic", "id": "p_PJbnN", "resolvedItemId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=" } ], "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": [] } ] } }, "/toptimize/v1/predictions": { "post": { "tags": [ "Toptimize" ], "summary": "[Beta] Add Quality Score", "description": "Use the `/predictions` endpoint to get contextual predictions of conversion and relevance metrics, which are personalized by user and context.In order to provide predictions, Topsort requires that events are also sent, as a source of information.\n", "operationId": "getPredictions", "requestBody": { "description": "> ⚠️ **Beta Access Required**\n> Contact your sales representative to gain access to this endpoint and start using it.\nThe context information for the predictions, including which metrics to predict.\n", "x-beta": "true", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_PredictionRequest" } } }, "required": true }, "responses": { "200": { "description": "The prediction results. This will provide a numerical value for each combination of metric/product requested on the API call.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_PredictionResult" } } } }, "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": [] } ] } }, "/toptimize/v1/retrieval": { "post": { "tags": [ "Toptimize" ], "summary": "[Beta] Retrieve objects", "description": "> ⚠️ **Beta Access Required**\n\n> Contact your sales representative to gain access to this endpoint and start using it.\n\nUse the `/retrieval` endpoint to get recommendations of which products are relevant given a\ncertain context. Context is provided by user information, plus seed products. This can be used\nto retrieve object to display on a PDP (single seed product) or in a cart (multiple seed products).\n\nIn order to provide retrieval, Topsort requires that events are also sent, as a source of\ninformation.\n", "operationId": "retrieveObjects", "requestBody": { "description": "The context information for the predictions, including which metrics to predict.\n", "x-beta": "true", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_RetrievalRequest" } } }, "required": true }, "responses": { "200": { "description": "The retrieval results. Each retrieved products is accompanied by their relevancy score.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_RetrievalResults" } } } }, "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": [] } ] } }, "/public/v1/toppie/campaigns": { "get": { "tags": [ "Toppie API" ], "summary": "[BETA] Get Toppie Campaigns", "description": "Retrieve a list of campaigns associated with a specific account.", "operationId": "list_account_campaigns", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "exclusiveMinimum": 0, "description": "Limit of accounts to retrieve.", "default": 100 }, "description": "Limit of accounts to retrieve." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_GetPublicAgencyCampaignsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "x-beta": "true" }, "post": { "tags": [ "Toppie API" ], "summary": "[BETA] Create Toppie Campaign", "description": "Create a new agency campaign with the provided details.", "operationId": "create_agency_campaign", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicAgencyCampaignCreateRequest", "description": "Campaign fields to create a new agency campaign." } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicAgencyCampaign" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "x-beta": "true" } }, "/public/v1/toppie/reporting": { "get": { "tags": [ "Toppie API" ], "summary": "[BETA] Get Agency Account Report.", "description": "Retrieve a general report for an account.", "operationId": "get_agency_account_report", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The start date for which reports will be generated." }, "description": "The start date for which reports will be generated." }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The end date for which reports will be generated." }, "description": "The end date for which reports will be generated." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_KPIs" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "x-beta": "true" } }, "/public/v1/toppie/reporting/campaigns": { "get": { "tags": [ "Toppie API" ], "summary": "[BETA] Get Campaigns Reporting.", "description": "Retrieve a list of campaigns and their reports.", "operationId": "get_agency_account_campaigns", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Token for retrieving the next page.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Token for retrieving the next page." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum number of campaigns to retrieve.", "default": 100 }, "description": "Maximum number of campaigns to retrieve." }, { "name": "order_by", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Advanced_APIs_CampaignsListDimension", "description": "The order dimension for the campaigns to be retrieved.", "default": "name" }, "description": "The order dimension for the campaigns to be retrieved." }, { "name": "direction", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Advanced_APIs_ReportingOrderByDirection", "description": "The order direction for the campaigns to be retrieved.", "default": "asc" }, "description": "The order direction for the campaigns to be retrieved." }, { "name": "start_date", "in": "query", "required": false, "schema": { "description": "Start date for calculating metrics.", "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "description": "Start date for calculating metrics." }, { "name": "end_date", "in": "query", "required": false, "schema": { "description": "End date for calculating metrics.", "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "description": "End date for calculating metrics." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "A search string to filter the names of the campaigns by.", "default": "" }, "description": "A search string to filter the names of the campaigns by." }, { "name": "campaign_status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Advanced_APIs_StatusFilter", "description": "The campaign status to filter the campaigns by. Defaults to all statuses.", "default": "all" }, "description": "The campaign status to filter the campaigns by. Defaults to all statuses." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_AgencyCampaignsWithKPIsResponsePaginated" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "x-beta": "true" } }, "/public/v1/toppie/reporting/account-activity": { "get": { "tags": [ "Toppie API" ], "summary": "[BETA] Account Activity Reports.", "description": "Retrieve account activity reports.", "operationId": "get_agency_account_activity", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The start date for which reports will be generated." }, "description": "The start date for which reports will be generated." }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The end date for which reports will be generated." }, "description": "The end date for which reports will be generated." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 0, "description": "The pagination limit.", "default": 100 }, "description": "The pagination limit." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_AccountActivityResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "x-beta": "true" } }, "/public/v1/toppie/reporting/file-reports/daily-kpis-by-product": { "get": { "tags": [ "Toppie API" ], "summary": "Get Agency Daily Kpis By Product Dump Urls", "description": "Retrieve pre-signed S3 URLs for daily product-wise KPI files.\n\nThis endpoint provides a list of Amazon S3 pre-signed URLs, allowing access to\nproduct-wise daily KPIs for Toppie. The data is provided in Parquet file format.\n\nFiles become available daily after **3 AM UTC** and contain KPI data for the\n**previous day**.", "operationId": "daily_kpis_by_product", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "report_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "Report date (UTC) in YYYY-MM-DD format." }, "description": "Report date (UTC) in YYYY-MM-DD format." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_FileAgencyDailyKPIsByProductResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/toppie/products": { "get": { "tags": [ "Toppie API" ], "summary": "[BETA] List Account Products", "description": "Retrieve a list of products associated with a specific account.", "operationId": "list_account_products", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "next_page", "in": "query", "required": false, "schema": { "description": "A token provided in a previous response. If not empty, it is used to retrieve the page that follows.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "A token provided in a previous response. If not empty, it is used to retrieve the page that follows." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "exclusiveMinimum": 0, "description": "Limit of products to retrieve.", "default": 100 }, "description": "Limit of products to retrieve." }, { "name": "search", "in": "query", "required": false, "schema": { "description": "Search query for product names.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Search query for product names." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_GetPublicAgencyProductsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "x-beta": "true" } }, "/public/v1/campaign-service/restriction-types": { "get": { "tags": [ "Campaign API" ], "summary": "Get Restriction Types", "description": "Endpoint to get all restriction types.", "operationId": "get_restriction_types", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_RestrictionTypesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "security": [ { "Advanced_APIs_HTTPBearer": [] } ] } }, "/public/v1/campaign-service/json-templates": { "post": { "tags": [ "Campaign API" ], "summary": "Create Json Template", "description": "Endpoint to create a new JSON template.", "operationId": "create_json_template", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_JsonTemplateCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_JsonTemplate" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "get": { "tags": [ "Campaign API" ], "summary": "Get Json Templates", "description": "Endpoint to get JSON templates.", "operationId": "get_json_templates", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 0, "description": "The pagination limit.", "default": 100 }, "description": "The pagination limit." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "A token provided in a previous response. If not empty, it is used to retrieve the page that follows.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "A token provided in a previous response. If not empty, it is used to retrieve the page that follows." }, { "name": "search", "in": "query", "required": false, "schema": { "description": "Search query to filter the templates.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Search query to filter the templates." }, { "name": "include_archived", "in": "query", "required": false, "schema": { "description": "Whether to include archived templates.", "default": false, "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "description": "Whether to include archived templates." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_GetJsonTemplatesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/campaign-service/campaigns/sponsored-brand": { "post": { "tags": [ "Campaign API" ], "summary": "Create a sponsored brand campaign.", "description": "Create a regular sponsored brand campaign using external vendor and slot identifiers. Only V2 sponsored brand campaigns are supported.", "operationId": "public_create_sponsored_brand_campaign", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "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_PublicSponsoredBrandCampaignCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicSponsoredBrandCampaignWithBudget" } } } }, "400": { "description": "Invalid wallet or JSON template content." }, "404": { "description": "Vendor, wallet, or slot not found." }, "409": { "description": "Campaign or bid already exists." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/campaign-service/campaigns": { "get": { "tags": [ "Campaign API" ], "summary": "Get Campaigns", "description": "Endpoint to retrieve campaigns. Campaigns can be filtered by Vendor ID and status.\n\nIt is expected to use for getting all campaigns of a marketplace & all campaigns of a vendor in dashboards.\nFiltering by status is expected to use at review page getting campaigns approved, pending tabs.", "operationId": "get_campaigns", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "vendor_id", "in": "query", "required": false, "schema": { "description": "The ID of the vendor. Omit to get campaigns for all vendors.", "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "description": "The ID of the vendor. Omit to get campaigns for all vendors." }, { "name": "status", "in": "query", "required": false, "schema": { "description": "Filter by the approval status of banner campaigns.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_CampaignStatus" }, { "type": "null" } ] }, "description": "Filter by the approval status of banner campaigns." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "The pagination offset.", "default": 0 }, "description": "The pagination offset." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 0, "description": "The pagination limit.", "default": 100 }, "description": "The pagination limit." }, { "name": "is_active", "in": "query", "required": false, "schema": { "description": "Filter by active/inactive campaigns. When start_date or end_date is provided, this reflects the activation flag only, not whether the campaign is currently live.", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "description": "Filter by active/inactive campaigns. When start_date or end_date is provided, this reflects the activation flag only, not whether the campaign is currently live." }, { "name": "external_campaign_id", "in": "query", "required": false, "schema": { "description": "Filter by external campaign ID.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Filter by external campaign ID." }, { "name": "slot_id", "in": "query", "required": false, "schema": { "description": "The ID of the slot. Used to filter banner and sponsored brand campaigns by slot.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "The ID of the slot. Used to filter banner and sponsored brand campaigns by slot." }, { "name": "ad_format", "in": "query", "required": false, "schema": { "description": "Filter by ad format.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_PublicAdFormat" }, { "type": "null" } ] }, "description": "Filter by ad format." }, { "name": "sort_by_date", "in": "query", "required": false, "schema": { "description": "Optional sort by date of campaign creation. Deprecated. Use order_by instead.", "deprecated": true, "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_CampaignOrderByDirection" }, { "type": "null" } ] }, "description": "Optional sort by date of campaign creation. Deprecated. Use order_by instead.", "deprecated": true }, { "name": "order_by", "in": "query", "required": false, "schema": { "description": "A single order by clause, e.g. 'created_at:asc'. Supported dimensions: created_at, start_date, end_date, name, campaign_id.", "oneOf": [ { "type": "string", "pattern": "^[^,]*$" }, { "type": "null" } ] }, "description": "A single order by clause, e.g. 'created_at:asc'. Supported dimensions: created_at, start_date, end_date, name, campaign_id." }, { "name": "start_date", "in": "query", "required": false, "schema": { "description": "Filter campaigns that are active on or after this date (campaigns whose end date is on or after this value).", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "description": "Filter campaigns that are active on or after this date (campaigns whose end date is on or after this value)." }, { "name": "end_date", "in": "query", "required": false, "schema": { "description": "Filter campaigns that are active on or before this date (campaigns whose start date is on or before this value).", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "description": "Filter campaigns that are active on or before this date (campaigns whose start date is on or before this value)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicCampaignsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "post": { "tags": [ "Campaign API" ], "summary": "Create Campaign", "description": "Creates a campaign with its associated budget and bids.\n\nSupports all campaign types except exclusive campaigns.", "operationId": "create_campaign", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "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_PublicCampaignCreateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicCampaign" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/campaign-service/products-in-campaign": { "get": { "tags": [ "Campaign API" ], "summary": "Get Products In Campaign", "description": "This endpoint returns paginated product ids currently in active campaigns. You can filter by vendor_id and ad_format, fetching only from active campaigns and bids.", "operationId": "get_products_in_campaign", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "vendor_id", "in": "query", "required": false, "schema": { "description": "The ID of the vendor to get sponsored products.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "The ID of the vendor to get sponsored products." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "A token provided in a previous response. If not empty, it is used to retrieve the page that follows.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "A token provided in a previous response. If not empty, it is used to retrieve the page that follows." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "exclusiveMinimum": 0, "description": "The pagination limit.", "default": 100 }, "description": "The pagination limit." }, { "name": "look_ahead_hours", "in": "query", "required": false, "schema": { "type": "integer", "description": "Include products whose campaigns are scheduled to start within the N next given hours.", "default": 0 }, "description": "Include products whose campaigns are scheduled to start within the N next given hours." }, { "name": "fetch_active_products", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Whether to fetch only active products. If false, all products will be fetched even if the campaign or the bid are inactive.", "default": false }, "description": "Whether to fetch only active products. If false, all products will be fetched even if the campaign or the bid are inactive." }, { "name": "ad_format", "in": "query", "required": false, "schema": { "description": "Filter by ad format. If not provided, all formats will be included.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_AdFormat" }, { "type": "null" } ] }, "description": "Filter by ad format. If not provided, all formats will be included." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_ProductsInCampaignResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/campaign-service/campaigns/exclusive-listing": { "post": { "tags": [ "Campaign API" ], "summary": "[BETA] Create exclusive listing campaign.", "description": "Endpoint to create exclusive listing campaigns and its respective bids.\n\nExclusive campaigns override auctions and are always shown by a fixed daily price.", "operationId": "create_exclusive_listing_campaign", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "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_PublicExclusiveListingCampaignCreateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicExclusiveListingCampaign" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "x-beta": "true" } }, "/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.\n\nExclusive campaigns override auctions and are always shown by a fixed daily price.", "operationId": "create_exclusive_banner_campaign", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "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" } } } } }, "x-beta": "true" } }, "/public/v1/catalog-search-service/catalogs/categories/count": { "get": { "tags": [ "Catalog API" ], "summary": "Get Categories Count", "description": "Get the number of categories in the catalog.", "operationId": "get_categories_count", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "integer", "title": "Response Get Categories Count" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "security": [ { "Advanced_APIs_HTTPBearer": [] } ] } }, "/public/v1/catalog-search-service/catalogs/products/count": { "get": { "tags": [ "Catalog API" ], "summary": "Get Products Count", "description": "Get the number of products in the catalog.", "operationId": "get_products_count", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "integer", "title": "Response Get Products Count" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "security": [ { "Advanced_APIs_HTTPBearer": [] } ] } }, "/public/v1/catalog-search-service/catalogs/categories": { "get": { "tags": [ "Catalog API" ], "summary": "Get Categories", "description": "Get multiple categories from the catalog.", "operationId": "get_categories", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_CategoriesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "put": { "tags": [ "Catalog API" ], "summary": "Upsert Categories", "description": "Create or replace one or more categories in the catalog.", "operationId": "upsert_categories", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_CategoriesRequest" } } } }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "delete": { "tags": [ "Catalog API" ], "summary": "Delete Categories", "description": "Delete one or more categories from the catalog.", "operationId": "delete_categories", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_CategoriesByIdRequest" } } } }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/catalog-search-service/catalogs/products": { "get": { "tags": [ "Catalog API" ], "summary": "Get Products", "description": "Get multiple products from the catalog.", "operationId": "get_products", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." }, { "name": "ean", "in": "query", "required": false, "schema": { "description": "European Article Number to filter products by. Formatted as a thirteen digit EAN-13 code.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "European Article Number to filter products by. Formatted as a thirteen digit EAN-13 code." }, { "name": "vendor_id", "in": "query", "required": false, "schema": { "description": "Vendor ID to filter products by.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Vendor ID to filter products by." }, { "name": "search", "in": "query", "required": false, "schema": { "description": "Search terms to look for in product names and descriptions.", "default": "", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Search terms to look for in product names and descriptions." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_ProductsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "put": { "tags": [ "Catalog API" ], "summary": "Upsert Products", "description": "Upsert products.", "operationId": "upsert_products", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_ProductsRequest" } } } }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "patch": { "tags": [ "Catalog API" ], "summary": "Update Products", "description": "Update products.", "operationId": "update_products", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_UpdateProductsRequest" } } } }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "delete": { "tags": [ "Catalog API" ], "summary": "Delete Products", "description": "Delete products by ID.", "operationId": "delete_products", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_ProductsByIdRequest" } } } }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/catalog-search-service/catalogs/vendors": { "get": { "tags": [ "Catalog API" ], "summary": "Get Vendors", "description": "Get vendors.", "operationId": "get_vendors", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." }, { "name": "global_id", "in": "query", "required": false, "schema": { "description": "Filter vendors by global vendor ID.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Filter vendors by global vendor ID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_VendorsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "put": { "tags": [ "Catalog API" ], "summary": "Upsert Vendors", "description": "Upsert vendors.", "operationId": "upsert_vendors", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_VendorsRequest" } } } }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "delete": { "tags": [ "Catalog API" ], "summary": "Delete Vendors", "description": "Delete vendors by ID.\n\nThis function won't error out when trying to delete vendors that don't exist.", "operationId": "delete_vendors", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_VendorsByIdRequest" } } } }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/billing-service/billing-contacts": { "get": { "tags": [ "Billing API" ], "summary": "Get Billing Contacts", "description": "Endpoint to get all the billing contacts.", "operationId": "get_billing_contacts", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "external_vendor_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "The External ID of the Vendor to retrieve." }, "description": "The External ID of the Vendor to retrieve." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "The maximum number of items to return per page.", "default": 50 }, "description": "The maximum number of items to return per page." }, { "name": "next_page", "in": "query", "required": false, "schema": { "type": "string", "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicGetBillingContactsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/billing-service/vendor-billing-contact": { "put": { "tags": [ "Billing API" ], "summary": "Upsert Vendor Billing Contact", "description": "Endpoint to assign a billing contact to a vendor.", "operationId": "upsert_vendor_billing_contact", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicUpsertBillingContactVendorRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "security": [ { "Advanced_APIs_HTTPBearer": [] } ] } }, "/public/v1/billing-service/campaign-billing-contact": { "put": { "tags": [ "Billing API" ], "summary": "Upsert Campaign Billing Contact", "description": "Endpoint to upsert a billing contact campaign.", "operationId": "upsert_campaign_bill_contact", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicUpsertBillingContactCampaignRequest" } } } }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "get": { "tags": [ "Billing API" ], "summary": "Get Campaign Billing Contact", "description": "Endpoint to get a billing contact campaign.", "operationId": "get_campaign_billing_contact", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign to get the billing contact for." }, "description": "The ID of the campaign to get the billing contact for." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicBillingContact" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/reporting-service/marketplace": { "get": { "tags": [ "Reporting API" ], "summary": "Get Marketplace Report", "description": "Endpoint to get a marketplace's total behavioral summary report between given dates.", "operationId": "get_marketplace_report_api", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The start date for which reports will be generated." }, "description": "The start date for which reports will be generated." }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The end date for which reports will be generated." }, "description": "The end date for which reports will be generated." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_ReportData" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/reporting-service/marketplace/daily": { "get": { "tags": [ "Reporting API" ], "summary": "Get Marketplace Daily Report", "description": "Endpoint to get a marketplace's daily behavioral summary report between given dates.", "operationId": "get_marketplace_daily_report", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 0, "description": "The pagination limit.", "default": 100 }, "description": "The pagination limit." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." }, { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The start date for which reports will be generated." }, "description": "The start date for which reports will be generated." }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The end date for which reports will be generated." }, "description": "The end date for which reports will be generated." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_DailyReportResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/reporting-service/marketplace/vendors-kpis": { "get": { "tags": [ "Reporting API" ], "summary": "Get Marketplace Vendors Kpis", "description": "Get KPIs for vendors in a marketplace using external vendor IDs.", "operationId": "get_marketplace_vendors_kpis", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 0, "description": "The pagination limit.", "default": 100 }, "description": "The pagination limit." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." }, { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The start date for which reports will be generated." }, "description": "The start date for which reports will be generated." }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The end date for which reports will be generated." }, "description": "The end date for which reports will be generated." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "The search string for a given query." }, "description": "The search string for a given query." }, { "name": "ad_format", "in": "query", "required": false, "schema": { "description": "The ad format for which reports will be generated. If not specified, all ad formats will be included.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_AdFormat" }, { "type": "null" } ] }, "description": "The ad format for which reports will be generated. If not specified, all ad formats will be included." }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Advanced_APIs_ReportingDimension" }, "description": "Order by field.", "default": [ "ad_spend" ] }, "description": "Order by field." }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Advanced_APIs_ReportingOrderByDirection" }, "description": "Order direction. Must be one of: asc, desc.", "default": [ "desc" ] }, "description": "Order direction. Must be one of: asc, desc." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicMarketplaceVendorsKpisResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/reporting-service/marketplace/campaigns-kpis": { "get": { "tags": [ "Reporting API" ], "summary": "Get Marketplace Campaigns Kpis", "description": "Get KPIs for campaigns in a marketplace using external vendor IDs.", "operationId": "get_marketplace_campaigns_kpis", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 0, "description": "The pagination limit.", "default": 100 }, "description": "The pagination limit." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." }, { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The start date for which reports will be generated." }, "description": "The start date for which reports will be generated." }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The end date for which reports will be generated." }, "description": "The end date for which reports will be generated." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "The search string for a given query." }, "description": "The search string for a given query." }, { "name": "ad_format", "in": "query", "required": false, "schema": { "description": "The ad format for which reports will be generated. If not specified, all ad formats will be included.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_AdFormat" }, { "type": "null" } ] }, "description": "The ad format for which reports will be generated. If not specified, all ad formats will be included." }, { "name": "vendor_id", "in": "query", "required": false, "schema": { "description": "External vendor ID.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "External vendor ID." }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Advanced_APIs_ReportingDimension" }, "description": "Order by field.", "default": [ "ad_spend" ] }, "description": "Order by field." }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Advanced_APIs_ReportingOrderByDirection" }, "description": "Order direction. Must be one of: asc, desc.", "default": [ "desc" ] }, "description": "Order direction. Must be one of: asc, desc." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicCampaignsKpisResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/reporting-service/interactions": { "get": { "tags": [ "Reporting API" ], "summary": "Get Marketplace Interactions Report", "description": "Get interactions report for a marketplace grouped by entity type.\n\nThis endpoint returns detailed interaction data (impressions, clicks, purchases, etc.)\naggregated by the specified entity type (vendor, campaign, or product) and time granularity (daily or hourly).\nResults can optionally be filtered to a single vendor or campaign.\nThe response is paginated to handle large datasets.", "operationId": "get_interactions_report", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time", "description": "The start date for which reports will be generated, specified in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6)." }, "description": "The start date for which reports will be generated, specified in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6)." }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time", "description": "The end date for which reports will be generated, specified in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6)." }, "description": "The end date for which reports will be generated, specified in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 0, "description": "The pagination limit.", "default": 1000 }, "description": "The pagination limit." }, { "name": "group_by", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Advanced_APIs_InteractionsGroupBy", "description": "How to group the results (vendor, campaign, or product).", "default": "vendor" }, "description": "How to group the results (vendor, campaign, or product)." }, { "name": "granularity", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Advanced_APIs_InteractionsGranularity", "description": "The time granularity of the report (daily or hourly).", "default": "daily" }, "description": "The time granularity of the report (daily or hourly)." }, { "name": "vendor_id", "in": "query", "required": false, "schema": { "description": "External vendor ID. Filters the report to a single vendor.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "External vendor ID. Filters the report to a single vendor." }, { "name": "campaign_id", "in": "query", "required": false, "schema": { "description": "Campaign ID. Filters the report to a single campaign.", "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "description": "Campaign ID. Filters the report to a single campaign." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_InteractionsReportResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/reporting-service/file-reports/scored-attribution": { "get": { "tags": [ "Reporting API" ], "summary": "Get Scored Attribution Dump Urls", "description": "Get scored attribution files for an specific date.\n\nThis endpoint returns a list of Amazon S3 pre-signed urls containing detailed attribution data in a parquet file format.\nThe files are available after 3am UTC and contains the attribution data for the previous day.", "operationId": "get_scored_attribution_url", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "report_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "Report date (UTC) in YYYY-MM-DD format." }, "description": "Report date (UTC) in YYYY-MM-DD format." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_FileReportScoredAttributionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/reporting-service/file-reports/interactions": { "get": { "tags": [ "Reporting API" ], "summary": "Get Interactions Dump Urls", "description": "Get interaction files for an specific date.\n\nThis endpoint returns a list of Amazon S3 pre-signed urls containing detailed interactions data in a parquet file format.\nThe files are available after 3am UTC and contains the interactions data for the previous day.", "operationId": "get_interactions_urls", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "report_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "Report date (UTC) in YYYY-MM-DD format." }, "description": "Report date (UTC) in YYYY-MM-DD format." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_FileReportInteractionsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/invitation-service/invitations": { "post": { "tags": [ "Invitation API" ], "summary": "[BETA] Invite Vendors", "description": "Invites a collection of Vendors to the Topsort platform.\n\nThe request payload should contain an array of pairs of vendor's ID, and\nemail.", "operationId": "invite_vendors", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_VendorInvitesRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "security": [ { "Advanced_APIs_HTTPBearer": [] } ] } }, "/public/v1/user-service/advertiser-users": { "post": { "tags": [ "User API" ], "summary": "Create User", "description": "Create a user.", "operationId": "create_advertiser_user", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicVendorUserCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicVendorUser" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "put": { "tags": [ "User API" ], "summary": "Update User", "description": "Update a user vendor access. This will substitute accesses, so vendor ids not present in the update will be removed.", "operationId": "update_advertiser_user", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicVendorUserUpdateRequest" } } } }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "get": { "tags": [ "User API" ], "summary": "Get User By Email", "description": "Get a user by email.", "operationId": "get_advertiser_user", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "email", "in": "query", "required": true, "schema": { "type": "string", "description": "The email of the user to get." }, "description": "The email of the user to get." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicVendorUser" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/webhooks/webhooks": { "post": { "tags": [ "Webhooks API" ], "summary": "Create Webhook", "description": "Creates a webhook.", "operationId": "create_webhook", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_WebhookCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_WebhookResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "get": { "tags": [ "Webhooks API" ], "summary": "Get Webhooks", "description": "Returns all webhooks.", "operationId": "get_webhooks", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "The maximum number of items to return per page.", "default": 50 }, "description": "The maximum number of items to return per page." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_WebhooksResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/assets/collection": { "post": { "tags": [ "Assets API" ], "summary": "[BETA] Create Collection", "description": "Creates a collection.", "operationId": "create_collection", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "vendor_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Vendor ID." }, "description": "Vendor ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_CollectionCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_CollectionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "x-beta": "true" } }, "/public/v1/assets/asset": { "post": { "tags": [ "Assets API" ], "summary": "Create Asset", "description": "Creates an asset.", "operationId": "create_asset", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "vendor_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Vendor ID." }, "description": "Vendor ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_AssetCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_AssetCreateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/assets/collections": { "get": { "tags": [ "Assets API" ], "summary": "[BETA] Get Collections", "description": "Retrieves a list of collections.", "operationId": "get_collections", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "vendor_id", "in": "query", "required": false, "schema": { "description": "Vendor ID.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Vendor ID." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "The maximum number of items to return per page.", "default": 50 }, "description": "The maximum number of items to return per page." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_CollectionsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "x-beta": "true" } }, "/public/v1/assets/assets": { "get": { "tags": [ "Assets API" ], "summary": "Get Assets", "description": "Retrieves a list of assets.", "operationId": "get_assets", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "vendor_id", "in": "query", "required": false, "schema": { "description": "Vendor ID.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Vendor ID." }, { "name": "collection_name", "in": "query", "required": false, "schema": { "description": "The collection name that the assets are associated with.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "The collection name that the assets are associated with." }, { "name": "brand", "in": "query", "required": false, "schema": { "description": "The brand that the assets are associated with.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "The brand that the assets are associated with." }, { "name": "mimetype", "in": "query", "required": false, "schema": { "description": "The mimetype of the assets.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_AssetMimetype" }, { "type": "null" } ] }, "description": "The mimetype of the assets." }, { "name": "status", "in": "query", "required": false, "schema": { "description": "The approval status of the assets.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_AssetStatus" }, { "type": "null" } ] }, "description": "The approval status of the assets." }, { "name": "asset_ids", "in": "query", "required": false, "schema": { "description": "The list of asset ids.", "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "description": "The list of asset ids." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "The maximum number of items to return per page.", "default": 50 }, "description": "The maximum number of items to return per page." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_AssetsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/segment-service/segments": { "get": { "tags": [ "Segments Service" ], "summary": "Retrieve a list of segments.", "description": "Retrieve a list of segments.", "operationId": "get_segments", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicSegmentsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "security": [ { "Advanced_APIs_HTTPBearer": [] } ] }, "put": { "tags": [ "Segments Service" ], "summary": "Upsert segments with the provided information.", "description": "Upsert segments with the provided information.", "operationId": "upsert_segments", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicSegmentsUpsertRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicSegmentsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "security": [ { "Advanced_APIs_HTTPBearer": [] } ] } }, "/public/v1/offsite-ads/advertisers": { "post": { "tags": [ "Offsite Ads API" ], "summary": "Create a new advertiser", "description": "Create a new advertiser.", "operationId": "create_offsite_advertiser", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_CreateAdvertiserRequestPublic" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_JobResponseBase" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "security": [ { "Advanced_APIs_HTTPBearer": [] } ] } }, "/public/v1/offsite-ads/campaigns": { "post": { "tags": [ "Offsite Ads API" ], "summary": "Create Campaign", "description": "Create a new offsite campaign.", "operationId": "create_offsite_campaign", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "vendor_id", "in": "query", "required": true, "schema": { "type": "string", "description": "The ID of the vendor to create the campaign for." }, "description": "The ID of the vendor to create the campaign for." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_CreateOffsiteCampaignRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_JobResponseBase" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "get": { "tags": [ "Offsite Ads API" ], "summary": "Get vendor offsite campaigns", "description": "Get vendor offsite campaigns.", "operationId": "get_vendor_offsite_campaigns", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "vendor_id", "in": "query", "required": true, "schema": { "type": "string", "description": "The ID of the vendor to get the campaign for." }, "description": "The ID of the vendor to get the campaign for." }, { "name": "dsps", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicDsp" }, "description": "The DSPs to filter campaigns by. If empty, all DSPs are included.", "examples": [ [ "google_ads", "meta" ] ], "default": [] }, "description": "The DSPs to filter campaigns by. If empty, all DSPs are included." }, { "name": "include_inactive", "in": "query", "required": false, "schema": { "description": "Whether to include inactive campaigns.", "default": false, "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "description": "Whether to include inactive campaigns." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "exclusiveMinimum": 0, "description": "The maximum number of campaigns to return.", "default": 100 }, "description": "The maximum number of campaigns to return." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "The next page token.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "The next page token." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicVendorCampaignsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/offsite-ads/audiences": { "get": { "tags": [ "Offsite Ads API" ], "summary": "List Offsite Audiences", "description": "List offsite audiences.", "operationId": "list_offsite_audiences", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "vendor_id", "in": "query", "required": false, "schema": { "description": "If specified, only shows audiences that specific vendor has access to.", "examples": [ "vendor_123" ], "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "If specified, only shows audiences that specific vendor has access to." }, { "name": "dsp", "in": "query", "required": false, "schema": { "description": "If specified, only shows audiences synced to this DSP.", "examples": [ "google_ads", "meta" ], "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_PublicDsp" }, { "type": "null" } ] }, "description": "If specified, only shows audiences synced to this DSP." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicOffsiteAudiencesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/offsite-ads/audiences/user-list": { "post": { "tags": [ "Offsite Ads API" ], "summary": "Create Offsite Audiences Job", "description": "Create a new offsite audience job.\n\nThis endpoint creates a job to create an offsite audience alongside a presigned url to upload the audience csv file.\nThe presigned url is valid for 1 hour and should be used to upload the audience csv file.\nThe audience creation will begin once the csv file is uploaded.\n\nThe audience CSV should contain one or more of the following columns with hashed and normalized identifiers: hashed_email, hashed_phone, hashed_first_name, hashed_last_name, hashed_mobile_device_id. Strongest identifiers are hashed_email and hashed_phone. Hashing should use the SHA256 method. The audience will be synced to the specified DSPs.", "operationId": "create_offsite_user_list_audience_job", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "vendor_id", "in": "query", "required": false, "schema": { "description": "Limits the audience to a specific vendor when set; otherwise, the audience is available to all vendors.", "examples": [ "vendor_123" ], "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Limits the audience to a specific vendor when set; otherwise, the audience is available to all vendors." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicOffsiteUserListAudienceCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicOffsiteAudienceCreateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/offsite-ads/vendors/active": { "get": { "tags": [ "Offsite Ads API" ], "summary": "Get Active Vendors", "description": "Get vendors that have at least one campaign created for the given DSP.\n\nThis endpoint returns a list of vendors that have at least one campaign created for the given DSP.\nThe list is paginated and the next page token is returned in the response.\nThe next page token can be used to get the next page of vendors.", "operationId": "get_active_vendors", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "dsp", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicDsp", "description": "The DSP to filter vendors by.", "examples": [ "google_ads", "meta" ] }, "description": "The DSP to filter vendors by." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 0, "description": "The pagination limit.", "default": 100 }, "description": "The pagination limit." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_ActiveVendorsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/offsite-ads/vendors/balances": { "get": { "tags": [ "Offsite Ads API" ], "summary": "Get Vendor Balances", "description": "Get vendor balances for the given vendors and DSP.", "operationId": "get_vendor_balances", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "vendor_ids", "in": "query", "required": true, "schema": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 25, "description": "The IDs of the vendors to get the balances for. Maximum of 25 vendors can be queried at once.", "examples": [ [ "vendor_123", "vendor_456" ] ] }, "description": "The IDs of the vendors to get the balances for. Maximum of 25 vendors can be queried at once." }, { "name": "dsp", "in": "query", "required": true, "schema": { "const": "google_ads", "type": "string", "description": "The DSP to get the balances for. Only Google Ads is supported currently.", "examples": [ "google_ads" ] }, "description": "The DSP to get the balances for. Only Google Ads is supported currently." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_VendorBalancesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/toptimize/forecasting/campaign": { "post": { "tags": [ "Forecasting Service" ], "summary": "[BETA] Campaign Performance Forecasts", "description": "Get campaign performance forecasts with confidence intervals.\n\n> ⚠️ **Beta Access Required**\n\n> Contact your sales representative to gain access to this endpoint and\n> start using it.\n\n**Currently Supported:**\n- Listing campaigns (autobidding) only\n\n**Returns total campaign forecasts (not daily) for:**\n- Total impressions with confidence intervals\n- Total clicks with confidence intervals\n- Total purchases with confidence intervals\n- Total sales with confidence intervals\n- Total ad spend with confidence intervals\n\n**Constraints:**\n- Date range cannot exceed 31 days.", "operationId": "get_campaign_forecast", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicListingCampaignForecastRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicCampaignForecastResponse" }, "examples": { "example": { "value": { "forecasts": { "impressions": { "forecastValue": 150000, "forecastIntervalMin": 142000, "forecastIntervalMax": 158000 }, "clicks": { "forecastValue": 12500, "forecastIntervalMin": 11800, "forecastIntervalMax": 13200 }, "purchases": { "forecastValue": 875, "forecastIntervalMin": 820, "forecastIntervalMax": 930 }, "sales": { "forecastValue": 52500, "forecastIntervalMin": 49000, "forecastIntervalMax": 56000 }, "adSpend": { "forecastValue": 10500, "forecastIntervalMin": 10000, "forecastIntervalMax": 11000 } } } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "x-beta": "true" } }, "/public/v1/media-service/slots": { "post": { "tags": [ "Media API" ], "summary": "Create Slot", "description": "Create a new slot.", "operationId": "create_slot", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "Request", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_CategoryOrSearchSlotCreateRequest" }, { "$ref": "#/components/schemas/Advanced_APIs_LandingPageSlotCreateRequestItem" } ] } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_AdConfigSlot" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "get": { "tags": [ "Media API" ], "summary": "Get Slots", "description": "Get slots for a given marketplace.", "operationId": "get_slots", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "position", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Advanced_APIs_PositionType", "description": "The position of the slot." }, "description": "The position of the slot." }, { "name": "page_id", "in": "query", "required": false, "schema": { "description": "The ID of the page. If provided, the slots will be filtered by the page.", "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "description": "The ID of the page. If provided, the slots will be filtered by the page." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Search query to be matched with page url, page name or slot id.", "default": "" }, "description": "Search query to be matched with page url, page name or slot id." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "exclusiveMinimum": 0, "description": "Limits the number of records to be returned. The limit can not surpass 50 and its default is 25.", "default": 25 }, "description": "Limits the number of records to be returned. The limit can not surpass 50 and its default is 25." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_GetSlotsRequest", "description": "Request body containing the orderBy dimensions and directions." } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_AdConfigSlotsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/toppie/campaigns/{campaign-id}": { "get": { "tags": [ "Toppie API" ], "summary": "[BETA] Get Toppie Campaign Details", "description": "Retrieve configuration details for a specific campaign.", "operationId": "get_campaign_configuration", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicAgencyCampaign" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "x-beta": "true" }, "patch": { "tags": [ "Toppie API" ], "summary": "[BETA] Update Toppie Campaign", "description": "Update an agency campaign with the provided details.", "operationId": "update_agency_campaign", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicAgencyCampaignUpdateRequest", "description": "Agency campaign fields to be updated" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicAgencyCampaign" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "x-beta": "true" }, "delete": { "tags": [ "Toppie API" ], "summary": "[BETA] Delete Toppie Campaign", "description": "Delete an agency campaign.", "operationId": "delete_agency_campaign", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "x-beta": "true" } }, "/public/v1/toppie/campaigns/{campaign-id}/bids": { "get": { "tags": [ "Toppie API" ], "summary": "[BETA] Get Toppie Campaign Bids", "description": "Retrieve bidding data for a specific campaign.", "operationId": "get_campaign_bids", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "exclusiveMinimum": 0, "description": "Limit of accounts to retrieve.", "default": 100 }, "description": "Limit of accounts to retrieve." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_GetAgencyCampaignBidsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "x-beta": "true" } }, "/public/v1/toppie/reporting/campaigns/{campaign-id}": { "get": { "tags": [ "Toppie API" ], "summary": "[BETA] Get Campaign Report.", "description": "Retrieve a detailed report for a specific campaign.", "operationId": "get_agency_campaign_report", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." }, { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The start date for which reports will be generated." }, "description": "The start date for which reports will be generated." }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The end date for which reports will be generated." }, "description": "The end date for which reports will be generated." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_KPIs" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "x-beta": "true" } }, "/public/v1/toppie/reporting/campaigns/{campaign-id}/products": { "get": { "tags": [ "Toppie API" ], "summary": "[BETA] Get Campaign Products Report.", "description": "Retrieve a product-level report for a specific campaign.", "operationId": "get_campaign_products_report", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." }, { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The start date for which reports will be generated." }, "description": "The start date for which reports will be generated." }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The end date for which reports will be generated." }, "description": "The end date for which reports will be generated." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "The search string for a given query." }, "description": "The search string for a given query." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Token for retrieving the next page.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Token for retrieving the next page." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum number of products to retrieve.", "default": 100 }, "description": "Maximum number of products to retrieve." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_GlobalCatalogProductKpisResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "x-beta": "true" } }, "/public/v1/campaign-service/campaigns/{campaign-id}/restrictions": { "post": { "tags": [ "Campaign API" ], "summary": "Create Campaign Restriction", "description": "Endpoint to create a campaign restriction.", "operationId": "create_campaign_restriction", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicCampaignRestrictionCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_CampaignRestrictionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "get": { "tags": [ "Campaign API" ], "summary": "Get Campaign Restriction", "description": "Endpoint to get campaign restrictions.", "operationId": "get_campaign_restriction", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_CampaignRestrictionsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/campaign-service/campaigns/{campaign-id}/restrictions/{restriction-id}": { "patch": { "tags": [ "Campaign API" ], "summary": "Update Campaign Restriction", "description": "Endpoint to update a campaign restriction.", "operationId": "update_campaign_restriction", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." }, { "name": "restriction-id", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the restriction." }, "description": "The ID of the restriction." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicCampaignRestrictionUpdate" } } } }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/campaign-service/restriction-types/{restriction-type-id}": { "get": { "tags": [ "Campaign API" ], "summary": "Get Restriction Type", "description": "Endpoint to get a specific restriction type.", "operationId": "get_restriction_type", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "restriction-type-id", "in": "path", "required": true, "schema": { "type": "integer", "description": "Restriction type ID." }, "description": "Restriction type ID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_RestrictionTypeResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/campaign-service/json-templates/{json-template-id}": { "get": { "tags": [ "Campaign API" ], "summary": "Get Json Template", "description": "Endpoint to get a specific JSON template by ID.", "operationId": "get_json_template", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "json-template-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "JSON template ID to retrieve." }, "description": "JSON template ID to retrieve." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_JsonTemplate" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "patch": { "tags": [ "Campaign API" ], "summary": "Update a JSON template", "description": "Partially updates a JSON template by its ID. Returns 404 if the template does not exist, 409 if the new name conflicts with an existing template, or if the template is in use and the JSON schema change is not strictly additive (only new optional top-level properties are allowed while in use).", "operationId": "update_json_template", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "json-template-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "JSON template ID to update." }, "description": "JSON template ID to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_JsonTemplateUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_JsonTemplate" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/campaign-service/campaigns/sponsored-brand/{campaign-id}": { "get": { "tags": [ "Campaign API" ], "summary": "Get a sponsored brand campaign.", "description": "Retrieve a regular sponsored brand campaign by ID. The response uses external vendor and slot identifiers and only exposes V2 sponsored brand campaigns.", "operationId": "public_get_sponsored_brand_campaign", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicSponsoredBrandCampaignWithBudget" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "patch": { "tags": [ "Campaign API" ], "summary": "Update a sponsored brand campaign.", "description": "Partially update a regular sponsored brand campaign. Only V2 sponsored brand campaigns are publicly addressable.", "operationId": "public_update_sponsored_brand_campaign", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." }, { "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_PublicSponsoredBrandCampaignUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicSponsoredBrandCampaignWithBudget" } } } }, "400": { "description": "Invalid wallet or sponsored brand status update." }, "404": { "description": "Campaign, wallet, or slot not found." }, "409": { "description": "Exclusive campaign conflict." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/campaign-service/campaigns/sponsored-brand/{campaign-id}/bids": { "get": { "tags": [ "Campaign API" ], "summary": "List sponsored brand campaign bids.", "description": "Retrieve a cursor-paginated list of bids for a regular sponsored brand campaign. The response uses external slot identifiers and only exposes V2 sponsored brand bids.", "operationId": "public_get_sponsored_brand_bids", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "exclusiveMinimum": 0, "description": "The pagination limit.", "default": 100 }, "description": "The pagination limit." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "A token provided in a previous response. If not empty, it is used to retrieve the page that follows.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "A token provided in a previous response. If not empty, it is used to retrieve the page that follows." }, { "name": "search", "in": "query", "required": false, "schema": { "description": "Search query to filter the bids.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Search query to filter the bids." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicSponsoredBrandBidsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "put": { "tags": [ "Campaign API" ], "summary": "Replace sponsored brand campaign bids.", "description": "Replace all bids for a regular sponsored brand campaign using external slot identifiers. Only V2 sponsored brand campaigns are publicly addressable.", "operationId": "public_recreate_sponsored_brand_bids", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." }, { "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_PublicCreateSponsoredBrandBids" } } } }, "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Invalid JSON template content." }, "404": { "description": "Campaign, vendor, or slot not found." }, "409": { "description": "Bid already exists." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/campaign-service/campaigns/{campaign-id}": { "get": { "tags": [ "Campaign API" ], "summary": "Get Campaign By Id", "description": "Endpoint to retrieve specific campaign by Campaign ID.\n\nIt is expected to use at Campaign Page.", "operationId": "get_campaign", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicCampaign" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "patch": { "tags": [ "Campaign API" ], "summary": "Update Campaign By Id", "description": "Endpoint to update fields for a given campaign.", "operationId": "update_campaign", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicCampaignUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicCampaign" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "delete": { "tags": [ "Campaign API" ], "summary": "Delete Campaign By Id", "description": "Endpoint to delete a specific campaign.", "operationId": "delete_campaign", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/campaign-service/campaigns/{campaign-id}/bids": { "post": { "tags": [ "Campaign API" ], "summary": "Create Campaign Bids", "description": "Endpoint to create a bid for a campaign.", "operationId": "create_bids", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." }, { "name": "skip_existing_bids", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Skip creating bids that already exist. Existing bids will not be updated and will not be returned in the response.", "default": false }, "description": "Skip creating bids that already exist. Existing bids will not be updated and will not be returned in the response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_BidCreateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicBidsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "get": { "tags": [ "Campaign API" ], "summary": "Get Campaign Bids", "description": "Endpoint to retrieve all campaign's bids.", "operationId": "get_bids", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "The pagination offset.", "default": 0 }, "description": "The pagination offset." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 0, "description": "The pagination limit.", "default": 100 }, "description": "The pagination limit." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicBidsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "delete": { "tags": [ "Campaign API" ], "summary": "Delete All Bids From A Campaign", "description": "Endpoint to delete all bids from a campaign.", "operationId": "delete_all_bids_from_a_campaign", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/campaign-service/campaigns/{campaign-id}/bids/{bid-id}": { "patch": { "tags": [ "Campaign API" ], "summary": "Update Campaign Bid By Id", "description": "Endpoint to update a bid.", "operationId": "update_bid", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." }, { "name": "bid-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the bid." }, "description": "The ID of the bid." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_BidUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_Bid" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "delete": { "tags": [ "Campaign API" ], "summary": "Delete Campaign Bid By Id", "description": "Endpoint to delete a bid.", "operationId": "delete_bid", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." }, { "name": "bid-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the bid." }, "description": "The ID of the bid." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/campaign-service/campaigns/{campaign-id}/products": { "get": { "tags": [ "Campaign API" ], "summary": "Get Campaign Products (Banners & Sponsored Brands)", "description": "Returns the products associated with a campaign.\n\nThis endpoint only applies to Banners and Sponsored Brands campaigns.\nIt does not return products for Sponsored Listings campaigns.", "operationId": "get_campaign_products", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." }, { "name": "is_active", "in": "query", "required": false, "schema": { "description": "Filter by active/inactive products.", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "description": "Filter by active/inactive products." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_CampaignProductsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "put": { "tags": [ "Campaign API" ], "summary": "Upsert Campaign Products", "description": "Endpoint to upsert campaign products.", "operationId": "upsert_campaign_products", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_CampaignProductUpsertRequest" } } } }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/campaign-service/campaigns/exclusive-listing/{campaign-id}": { "get": { "tags": [ "Campaign API" ], "summary": "[BETA] Get exclusive listing campaign by ID.", "description": "Endpoint to fetch a specific exclusive listing campaign by Campaign ID.", "operationId": "get_exclusive_listing_campaign_by_id", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign to be fetched." }, "description": "The ID of the campaign to be fetched." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicExclusiveListingCampaign" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "x-beta": "true" }, "patch": { "tags": [ "Campaign API" ], "summary": "[BETA] Update exclusive listing campaign by ID.", "description": "Endpoint to update fields for a given exclusive listing campaign.", "operationId": "update_exclusive_listing_campaign_by_id", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign to be updated." }, "description": "The ID of the campaign to be updated." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicExclusiveListingCampaignUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicExclusiveListingCampaign" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "x-beta": "true" } }, "/public/v1/campaign-service/campaigns/exclusive-banner/{campaign-id}": { "get": { "tags": [ "Campaign API" ], "summary": "[BETA] Get exclusive banner campaign by ID.", "description": "Endpoint to fetch a specific exclusive banner campaign by Campaign ID.", "operationId": "get_exclusive_banner_campaign_by_id", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign to be fetched." }, "description": "The ID of the campaign to be fetched." } ], "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" } } } } }, "x-beta": "true" }, "patch": { "tags": [ "Campaign API" ], "summary": "[BETA] Update exclusive banner campaign by ID.", "description": "Endpoint to update fields for a given exclusive banner campaign.", "operationId": "update_exclusive_banner_campaign_by_id", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign to be updated." }, "description": "The ID of the campaign to be updated." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicExclusiveBannerCampaignUpdateRequest" } } } }, "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" } } } } }, "x-beta": "true" } }, "/public/v1/campaign-service/campaigns/{campaign-id}/timetables": { "put": { "tags": [ "Campaign API" ], "summary": "Create or update campaign timetables (dayparting).", "description": "Create or update dayparting configuration for a campaign.\n\nDayparting allows you to control when your campaign is active during the week.\nYou can specify active hours for each day of the week (1=Monday, 7=Sunday).\n\nHOUR SEMANTICS:\n- start_hour: Campaign starts at this hour (inclusive, 0-23)\n- end_hour: Campaign stops at this hour (exclusive, 1-24)\n- Example: start_hour=9, end_hour=17 runs from 9:00 AM to 5:00 PM\n- For all-day: start_hour=0, end_hour=24\n\nThis endpoint performs an upsert operation - it will create new timetables or\nupdate existing ones based on the day_of_week. Days not in the request remain\nunchanged.", "operationId": "upsert_campaign_timetables", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." }, { "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_PublicUpsertTimeTablesRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicCampaignTimetablesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "get": { "tags": [ "Campaign API" ], "summary": "Retrieve campaign timetables (dayparting).", "description": "Retrieve the dayparting configuration for a campaign.\n\nReturns all configured timetables for the campaign, ordered by day of week.\nIf no timetables are configured, returns an empty list.\n\nHOUR SEMANTICS:\n- start_hour: Campaign starts at this hour (inclusive, 0-23)\n- end_hour: Campaign stops at this hour (exclusive, 1-24)\n- Example: start_hour=9, end_hour=17 means runs from 9:00 AM to 5:00 PM.", "operationId": "get_campaign_timetables", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." }, { "name": "vendor_id", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The ID of the vendor." }, "description": "The ID of the vendor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicCampaignTimetablesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/campaign-service/campaigns/{campaign-id}/timetables/{day-of-week}": { "delete": { "tags": [ "Campaign API" ], "summary": "Delete a campaign timetable for a specific day (dayparting).", "description": "Delete the timetable configuration for a specific day of the week.\n\nThis removes the dayparting rule for the specified day, reverting the campaign\nto be active all day for that day (if the campaign is otherwise active).\n\nAfter deletion, the campaign will run 24 hours on the specified day (no time\nrestrictions).", "operationId": "delete_campaign_timetable", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." }, { "name": "day-of-week", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Advanced_APIs_DayOfWeek", "description": "The day of the week (1=Monday, 7=Sunday)." }, "description": "The day of the week (1=Monday, 7=Sunday)." }, { "name": "vendor_id", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The ID of the vendor." }, "description": "The ID of the vendor." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/catalog-search-service/catalogs/categories/{category-id}": { "get": { "tags": [ "Catalog API" ], "summary": "Get Category", "description": "Get a single category from the catalog.", "operationId": "get_category", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "category-id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "ID of the category." }, "description": "ID of the category." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_Category" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/catalog-search-service/catalogs/products/{product-id}": { "get": { "tags": [ "Catalog API" ], "summary": "Get Product", "description": "Get product by ID.", "operationId": "get_product", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "product-id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The ID of the product to retrieve." }, "description": "The ID of the product to retrieve." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_Product" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/catalog-search-service/catalogs/vendors/{vendor-id}": { "get": { "tags": [ "Catalog API" ], "summary": "Get Vendor", "description": "Get vendor by ID.", "operationId": "get_vendor", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "vendor-id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The ID of the vendor to retrieve." }, "description": "The ID of the vendor to retrieve." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_Vendor" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/billing-service/vendors/{external-vendor-id}/wallets": { "post": { "tags": [ "Billing API" ], "summary": "Create Wallet", "description": "Endpoint to create a wallet for a vendor.\n\nThere is a limit of 3 Wallets per vendor.", "operationId": "create_wallet", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "external-vendor-id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The External ID of the Vendor to retrieve." }, "description": "The External ID of the Vendor to retrieve." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_CreateWalletRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_CreateWalletResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "get": { "tags": [ "Billing API" ], "summary": "Get Vendor Wallets", "description": "Endpoint to list all the wallets of a vendor.", "operationId": "get_vendor_wallets", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "external-vendor-id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The External ID of the Vendor to retrieve." }, "description": "The External ID of the Vendor to retrieve." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_VendorWallets" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/billing-service/vendors/{external-vendor-id}/balance": { "get": { "tags": [ "Billing API" ], "summary": "Get Vendor Balance", "description": "Endpoint to get the balance for a vendor.", "operationId": "get_vendor_balance", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "external-vendor-id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The External ID of the Vendor to retrieve." }, "description": "The External ID of the Vendor to retrieve." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_GetBalanceResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "post": { "tags": [ "Billing API" ], "summary": "Add Vendor Balance", "description": "Endpoint to add some balance for a vendor.\n\nWill truncate the input to its minimum denomination, e.g. USD 1,000.234 is USD 1,000.23 , as there is no fraction of a cent.", "operationId": "add_vendor_balance", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "external-vendor-id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The External ID of the Vendor to retrieve." }, "description": "The External ID of the Vendor to retrieve." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_AddBalanceRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_AddBalanceResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/billing-service/vendors/{external-vendor-id}/balance/burn": { "post": { "tags": [ "Billing API" ], "summary": "Burn Vendor Balance", "description": "Endpoint to burn some amount of balance for a vendor.", "operationId": "burn_vendor_balance", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "external-vendor-id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The External ID of the Vendor to retrieve." }, "description": "The External ID of the Vendor to retrieve." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_BurnVendorBalanceRequest" } } } }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/billing-service/vendors/{external-vendor-id}/wallets/{wallet-id}/adjust": { "post": { "tags": [ "Billing API" ], "summary": "Adjust Wallet Balance", "description": "Endpoint to change the balance for a wallet.\n\nIt will add the amount to the wallet if the amount is positive and burn the amount if it is negative.\nThe amount is ISO 4217 currency code compliant meaning that 100 as an input for USD marketplace will be 1 USD.", "operationId": "adjust_wallet_balance", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "external-vendor-id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The External ID of the Vendor to retrieve." }, "description": "The External ID of the Vendor to retrieve." }, { "name": "wallet-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the wallet to retrieve." }, "description": "The ID of the wallet to retrieve." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_AdjustBalanceRequestPublic" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_AdjustBalanceResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/billing-service/billing-contacts/{billing-contact-id}": { "put": { "tags": [ "Billing API" ], "summary": "Upsert Billing Contact", "description": "Endpoint to upsert a billing contact.", "operationId": "upsert_billing_contact", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "billing-contact-id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The ID of the billing contact." }, "description": "The ID of the billing contact." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicUpsertBillingContactRequest" } } } }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "get": { "tags": [ "Billing API" ], "summary": "Get Billing Contact", "description": "Endpoint to get a billing contact.", "operationId": "get_billing_contact", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "billing-contact-id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The ID of the billing contact." }, "description": "The ID of the billing contact." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicBillingContact" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/billing-service/vendors/{external-vendor-id}/vendor-billing-contact/{billing-contact-id}": { "delete": { "tags": [ "Billing API" ], "summary": "Delete Vendor Billing Contact", "description": "Endpoint to unassign a billing contact from a vendor.", "operationId": "delete_vendor_billing_contact", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "external-vendor-id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The External ID of the Vendor to retrieve." }, "description": "The External ID of the Vendor to retrieve." }, { "name": "billing-contact-id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The ID of the billing contact." }, "description": "The ID of the billing contact." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/reporting-service/vendors/{vendor-id}": { "get": { "tags": [ "Reporting API" ], "summary": "Get Vendor Report", "description": "Endpoint to get a vendor's total behavioral summary report between given dates.", "operationId": "get_vendor_report", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "vendor-id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The ID of the vendor." }, "description": "The ID of the vendor." }, { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The start date for which reports will be generated." }, "description": "The start date for which reports will be generated." }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The end date for which reports will be generated." }, "description": "The end date for which reports will be generated." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_ReportDataWithAuctions" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/reporting-service/vendors/{vendor-id}/daily": { "get": { "tags": [ "Reporting API" ], "summary": "Get Vendor Daily Report", "description": "Endpoint to get a vendor's daily behavioral summary report between given dates.", "operationId": "get_vendor_daily_report", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "vendor-id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The ID of the vendor." }, "description": "The ID of the vendor." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 0, "description": "The pagination limit.", "default": 100 }, "description": "The pagination limit." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." }, { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The start date for which reports will be generated." }, "description": "The start date for which reports will be generated." }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The end date for which reports will be generated." }, "description": "The end date for which reports will be generated." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_DailyReportResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/reporting-service/campaigns/{campaign-id}": { "get": { "tags": [ "Reporting API" ], "summary": "Get Campaign Report", "description": "Endpoint to get a campaign's total behavioral summary report between given dates.", "operationId": "get_campaign_report", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." }, { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The start date for which reports will be generated." }, "description": "The start date for which reports will be generated." }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The end date for which reports will be generated." }, "description": "The end date for which reports will be generated." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_ReportDataWithAuctions" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/reporting-service/campaigns/{campaign-id}/daily": { "get": { "tags": [ "Reporting API" ], "summary": "Get Campaign Daily Report", "description": "Endpoint to get a campaign's daily behavioral summary report between given dates.", "operationId": "get_campaign_daily_report", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 0, "description": "The pagination limit.", "default": 100 }, "description": "The pagination limit." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." }, { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The start date for which reports will be generated." }, "description": "The start date for which reports will be generated." }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The end date for which reports will be generated." }, "description": "The end date for which reports will be generated." }, { "name": "purchase_count_by_product", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Whether to include the purchase count by product inside purchases. Defaults to False.", "default": false }, "description": "Whether to include the purchase count by product inside purchases. Defaults to False." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_DailyReportResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/reporting-service/campaigns/{campaign-id}/products/{product-id}/daily": { "get": { "tags": [ "Reporting API" ], "summary": "Get Product Daily Report", "description": "Endpoint to get a product's daily behavioral summary report between given dates.", "operationId": "get_product_daily_report", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." }, { "name": "product-id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the product." }, "description": "The ID of the product." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 0, "description": "The pagination limit.", "default": 100 }, "description": "The pagination limit." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." }, { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The start date for which reports will be generated." }, "description": "The start date for which reports will be generated." }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The end date for which reports will be generated." }, "description": "The end date for which reports will be generated." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_DailyReportResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/reporting-service/campaigns/{campaign-id}/products": { "get": { "tags": [ "Reporting API" ], "summary": "Get Campaign Report By Product", "description": "Endpoint to get a campaign's total behavioral summary report, divided by products, between given dates.", "operationId": "get_campaign_report_by_product", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 0, "description": "The pagination limit.", "default": 100 }, "description": "The pagination limit." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." }, { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The start date for which reports will be generated." }, "description": "The start date for which reports will be generated." }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The end date for which reports will be generated." }, "description": "The end date for which reports will be generated." }, { "name": "order_by", "in": "query", "required": false, "schema": { "description": "Order by field. Sorts by numeric values (impressions, clicks, etc). Only one dimension allowed.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_CampaignReportByProductOrderByDimension" }, { "type": "null" } ] }, "description": "Order by field. Sorts by numeric values (impressions, clicks, etc). Only one dimension allowed. Allowed values are in the schema (CampaignReportByProductOrderByDimension); other dimensions return 422." }, { "name": "direction", "in": "query", "required": false, "schema": { "description": "Order direction. Must be one of: asc, desc.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_ReportingOrderByDirection" }, { "type": "null" } ] }, "description": "Order direction. Must be one of: asc, desc." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_CampaignKPIsByProduct" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/reporting-service/campaigns/{campaign-id}/products/{product-id}": { "get": { "tags": [ "Reporting API" ], "summary": "Get Product Report", "description": "Endpoint to get a product's total behavioral summary report between given dates.", "operationId": "get_product_report", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign." }, "description": "The ID of the campaign." }, { "name": "product-id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the product." }, "description": "The ID of the product." }, { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The start date for which reports will be generated." }, "description": "The start date for which reports will be generated." }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The end date for which reports will be generated." }, "description": "The end date for which reports will be generated." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_ReportData" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/webhooks/webhooks/{webhook-id}": { "get": { "tags": [ "Webhooks API" ], "summary": "Get Webhook", "description": "Returns the webhook.", "operationId": "get_webhook", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "webhook-id", "in": "path", "required": true, "schema": { "type": "string", "description": "Id of the webhook." }, "description": "Id of the webhook." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_WebhookResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "delete": { "tags": [ "Webhooks API" ], "summary": "Delete Webhook", "description": "Deletes the webhook.", "operationId": "delete_webhook", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "webhook-id", "in": "path", "required": true, "schema": { "type": "string", "description": "Id of the webhook." }, "description": "Id of the webhook." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "patch": { "tags": [ "Webhooks API" ], "summary": "Update Webhook", "description": "Updates a webhook.", "operationId": "update_webhook", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "webhook-id", "in": "path", "required": true, "schema": { "type": "string", "description": "Id of the webhook." }, "description": "Id of the webhook." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_WebhookUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_WebhookResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/assets/collection/{collection-id}": { "delete": { "tags": [ "Assets API" ], "summary": "[BETA] Delete Collection", "description": "Deletes a collection.", "operationId": "delete_collection", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "collection-id", "in": "path", "required": true, "schema": { "type": "string", "description": "Collection ID." }, "description": "Collection ID." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "x-beta": "true" }, "patch": { "tags": [ "Assets API" ], "summary": "[BETA] Update Collection", "description": "Updates a collection.", "operationId": "update_collection", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "collection-id", "in": "path", "required": true, "schema": { "type": "string", "description": "Collection ID." }, "description": "Collection ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_CollectionUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_CollectionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "x-beta": "true" }, "get": { "tags": [ "Assets API" ], "summary": "[BETA] Get Collection", "description": "Retrieves a collection.", "operationId": "get_collection", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "collection-id", "in": "path", "required": true, "schema": { "type": "string", "description": "Collection ID." }, "description": "Collection ID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_CollectionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } }, "x-beta": "true" } }, "/public/v1/assets/asset/{asset-id}": { "get": { "tags": [ "Assets API" ], "summary": "Get Asset", "description": "Retrieves an asset.", "operationId": "get_asset", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "asset-id", "in": "path", "required": true, "schema": { "type": "string", "description": "Asset ID." }, "description": "Asset ID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_AssetResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "patch": { "tags": [ "Assets API" ], "summary": "Update Asset", "description": "Updates an asset.", "operationId": "update_asset", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "asset-id", "in": "path", "required": true, "schema": { "type": "string", "description": "Asset ID." }, "description": "Asset ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_AssetUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_AssetResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "delete": { "tags": [ "Assets API" ], "summary": "Delete Asset", "description": "Deletes an asset.", "operationId": "delete_asset", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "asset-id", "in": "path", "required": true, "schema": { "type": "string", "description": "Asset ID." }, "description": "Asset ID." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/segment-service/segments/{segment-id}": { "get": { "tags": [ "Segments Service" ], "summary": "Retrieve a segment by ID.", "description": "Retrieve a segment by its external ID.", "operationId": "get_segment_by_id", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "segment-id", "in": "path", "required": true, "schema": { "type": "string", "description": "The external ID of the segment." }, "description": "The external ID of the segment." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicSegmentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "delete": { "tags": [ "Segments Service" ], "summary": "Delete a segment.", "description": "Delete a segment.", "operationId": "delete_segment", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "segment-id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the segment." }, "description": "The ID of the segment." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/segment-service/segments/{segment-id}/signed-url": { "get": { "tags": [ "Segments Service" ], "summary": "Get upload users signed url for a segment.", "description": "Retrieve a signed URL for uploading a segment user file.\n\nThis endpoint returns a pre-signed URL that allows you to securely upload a segment user file.\n\nFile requirements:\n- The file must be in plain text format (\".txt\").\n- It should not contain headers.\n- Each line must represent a single opaque user ID.\n- The file must not exceed 50 MiB.\n\nThe signed URL can be used to upload the file directly via an HTTP PUT request.\nFor more information, see the [AWS documentation on uploading objects using presigned URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html).\n\nReturns\n-------\n dict: A dictionary containing the signed URL and any additional metadata required for upload.", "operationId": "get_signed_url", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "segment-id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the segment." }, "description": "The ID of the segment." }, { "name": "action", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Advanced_APIs_SegmentSyncAction", "description": "The action to perform on the segment. Possible values are 'add', 'remove', or 'replace'. The 'replace' action will first remove all existing users from the segment before adding the new ones.", "default": "add" }, "description": "The action to perform on the segment. Possible values are 'add', 'remove', or 'replace'. The 'replace' action will first remove all existing users from the segment before adding the new ones." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_CreatePresignedUrlResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/segment-service/segments/{segment-id}/upload": { "post": { "tags": [ "Segments Service" ], "summary": "Upload users to a segment.", "description": "Uploads a file with segment users.", "operationId": "upload_segment_users", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "segment-id", "in": "path", "required": true, "schema": { "type": "string", "description": "The external ID of the segment." }, "description": "The external ID of the segment." }, { "name": "action", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Advanced_APIs_SegmentSyncAction", "description": "The action to perform on the segment.", "default": "add" }, "description": "The action to perform on the segment." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_Body_upload_segment_users" } } } }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/offsite-ads/jobs/{job-id}": { "get": { "tags": [ "Offsite Ads API" ], "summary": "Get Job Status", "description": "Get job status.", "operationId": "get_offsite_job_status", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "job-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the job to retrieve the status for." }, "description": "The ID of the job to retrieve the status for." }, { "name": "vendor_id", "in": "query", "required": false, "schema": { "description": "The ID of the vendor to retrieve the job status for.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "The ID of the vendor to retrieve the job status for." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_JobDetailsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/offsite-ads/advertisers/{vendor-id}": { "get": { "tags": [ "Offsite Ads API" ], "summary": "Get advertiser onboarding state for a specific DSP", "description": "Get advertiser onboarding state for a specific DSP.", "operationId": "get_offsite_advertiser_onboarding_state", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "vendor-id", "in": "path", "required": true, "schema": { "type": "string", "description": "Vendor ID associated with the advertiser." }, "description": "Vendor ID associated with the advertiser." }, { "name": "dsp", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicDsp", "description": "The DSP to get the advertiser info for." }, "description": "The DSP to get the advertiser info for." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicAdvertiserResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/offsite-ads/campaigns/{campaign-id}": { "get": { "tags": [ "Offsite Ads API" ], "summary": "Get campaign information", "description": "Get campaign.", "operationId": "get_offsite_campaign_info", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign to get." }, "description": "The ID of the campaign to get." }, { "name": "vendor_id", "in": "query", "required": true, "schema": { "type": "string", "description": "The ID of the vendor to get the campaign for." }, "description": "The ID of the vendor to get the campaign for." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_OfsiteCampaign" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "patch": { "tags": [ "Offsite Ads API" ], "summary": "Update Campaign", "description": "Update a campaign.", "operationId": "update_offsite_campaign", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign to update." }, "description": "The ID of the campaign to update." }, { "name": "vendor_id", "in": "query", "required": true, "schema": { "type": "string", "description": "The ID of the vendor to update the campaign for." }, "description": "The ID of the vendor to update the campaign for." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_UpdateOffsiteCampaignRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_JobResponseBase" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/offsite-ads/reporting/campaigns/{campaign-id}/products": { "get": { "tags": [ "Offsite Ads API" ], "summary": "Get Campaign Products Report", "description": "Get campaign products report.\n\nThis endpoint returns a report of products that were advertised in a campaign.\nProduct level report is available for Google Ads campaigns only.\nIf the campaign is not a Google Ads campaign, It returns 404.", "operationId": "get_offsite_campaign_products_report", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign to get ad groups for." }, "description": "The ID of the campaign to get ad groups for." }, { "name": "vendor_id", "in": "query", "required": true, "schema": { "type": "string", "description": "The ID of the vendor to get the campaign products report for." }, "description": "The ID of the vendor to get the campaign products report for." }, { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The start date for which reports will be generated." }, "description": "The start date for which reports will be generated." }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The end date for which reports will be generated." }, "description": "The end date for which reports will be generated." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 0, "description": "The pagination limit.", "default": 100 }, "description": "The pagination limit." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicCampaignProductsReportResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/offsite-ads/reporting/campaigns/{campaign-id}": { "get": { "tags": [ "Offsite Ads API" ], "summary": "Get Campaign Aggregated Report", "description": "Get campaign report.", "operationId": "get_offsite_campaign_aggregated_report", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign to get the report for." }, "description": "The ID of the campaign to get the report for." }, { "name": "vendor_id", "in": "query", "required": true, "schema": { "type": "string", "description": "The ID of the vendor to get the campaign report for." }, "description": "The ID of the vendor to get the campaign report for." }, { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The start date for which reports will be generated." }, "description": "The start date for which reports will be generated." }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The end date for which reports will be generated." }, "description": "The end date for which reports will be generated." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_OffsiteReportData" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/offsite-ads/reporting/campaigns/{campaign-id}/daily": { "get": { "tags": [ "Offsite Ads API" ], "summary": "Get Campaign Daily Report", "description": "Get campaign daily report.", "operationId": "get_offsite_campaign_daily_report", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "campaign-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the campaign to get the daily report for." }, "description": "The ID of the campaign to get the daily report for." }, { "name": "vendor_id", "in": "query", "required": true, "schema": { "type": "string", "description": "The ID of the vendor to get the daily report for." }, "description": "The ID of the vendor to get the daily report for." }, { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The start date for which reports will be generated." }, "description": "The start date for which reports will be generated." }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "The end date for which reports will be generated." }, "description": "The end date for which reports will be generated." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 0, "description": "The pagination limit.", "default": 100 }, "description": "The pagination limit." }, { "name": "next_page", "in": "query", "required": false, "schema": { "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Pagination cursor as provided in an earlier response. If provided will fetch the next page of results." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicCampaignDailyReportResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/offsite-ads/audiences/{audience-id}": { "put": { "tags": [ "Offsite Ads API" ], "summary": "Replace Offsite Audiences Job", "description": "Replace the contents of an existing offsite audience. This endpoint returns a new job id and presigned url for uploading the replacement audience CSV.", "operationId": "replace_offsite_audience_contents", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "audience-id", "in": "path", "required": true, "schema": { "type": "string", "description": "The audience ID to replace." }, "description": "The audience ID to replace." } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Body", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_PublicOffsiteAudienceReplaceRequest" }, { "type": "null" } ] } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PublicOffsiteAudienceCreateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "delete": { "tags": [ "Offsite Ads API" ], "summary": "Delete Offsite Audience", "description": "Delete an existing offsite audience from Topsort as well as synced DSPs.", "operationId": "delete_offsite_audience", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "audience-id", "in": "path", "required": true, "schema": { "type": "string", "description": "The audience ID to delete." }, "description": "The audience ID to delete." } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_JobResponseBase" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/media-service/slots/{slot-id}/fallback": { "delete": { "tags": [ "Media API" ], "summary": "Delete Banner Fallback", "description": "Delete a banner fallback for a given slot.", "operationId": "delete_fallback", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "slot-id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The id of the slot." }, "description": "The id of the slot." }, { "name": "device_type", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Advanced_APIs_MediaDeviceType", "description": "The device type of the fallback." }, "description": "The device type of the fallback." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } }, "/public/v1/media-service/slots/{slot-id}": { "delete": { "tags": [ "Media API" ], "summary": "Delete Slot", "description": "Delete an unused slot.", "operationId": "delete_slot", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "slot-id", "in": "path", "required": true, "schema": { "type": "string", "description": "The id of the slot." }, "description": "The id of the slot." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } }, "patch": { "tags": [ "Media API" ], "summary": "Toggle Slot", "description": "Activate/Deactivate a slot.", "operationId": "toggle_slot", "security": [ { "Advanced_APIs_HTTPBearer": [] } ], "parameters": [ { "name": "slot-id", "in": "path", "required": true, "schema": { "type": "string", "description": "The id of the slot." }, "description": "The id of the slot." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_PatchSlotsRequest", "description": "Request body to activate or deactivate the slot." } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } } }, "webhooks": { "webhooks": { "post": { "summary": "Endpoint to notify events generated in Topsort", "description": "When an event is triggered we'll send you a POST request with this data.\n\nUse the Webhooks API to manage the target url and the accepted events.", "operationId": "webhook_external", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_WebhookEventResponse" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Advanced_APIs_HTTPValidationError" } } } } } } } }, "components": { "responses": { "Topsort_Endpoints_v2_API_Reference_UnauthorizedError": { "description": "Access token is missing or invalid" }, "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" } } } } }, "schemas": { "Topsort_Endpoints_v2_API_Reference_AuctionCategory": { "description": "Represents one or more categories for auction targeting. Can be a single category, multiple categories, or category disjunctions.", "oneOf": [ { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_SingleCategory" }, { "type": "object", "title": "Multiple Categories", "description": "A set of categories for the purpose of running an auction.", "required": [ "ids" ], "properties": { "ids": { "type": "array", "description": "An array containing the category IDs of the bids that will participate in an auction.\nIn order to participate in an auction, a bid product must belong to **all** of the categories provided in the auction request.\n", "items": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_CategoryID" }, "minItems": 1, "examples": [ [ "c_men_clothing", "c_shoes" ] ] } } }, { "type": "object", "title": "Category Disjunctions", "description": "Multiple disjunctions of categories for the purpose of running an auction.", "required": [ "disjunctions" ], "properties": { "disjunctions": { "type": "array", "description": "An array of disjunctions.\n\nIn order to participate in an auction, a bid product must belong to at least one of the categories of the disjunction provided in the auction request.\n", "items": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_CategoryDisjunction" }, "minItems": 1, "maxItems": 5, "examples": [ [ [ "c_red" ], [ "c_blue" ] ] ] } } } ] }, "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_CategoryDisjunction": { "type": "array", "description": "An array of category IDs, describing a category disjunction.\n\nA bid entity must belong to at least one of the categories in the disjunction in order to participate in the auction.\n", "items": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_CategoryID" }, "minItems": 1 }, "Topsort_Endpoints_v2_API_Reference_Device": { "type": "string", "description": "The device for which the ads are meant for.", "enum": [ "desktop", "mobile" ], "default": "desktop" }, "Topsort_Endpoints_v2_API_Reference_DeviceType": { "type": "string", "description": "The device the user is on.", "enum": [ "desktop", "mobile" ], "examples": [ "mobile" ] }, "Topsort_Endpoints_v2_API_Reference_DemandSource": { "type": "object", "description": "External demand source participating in the auction.", "required": [ "source", "bids" ], "properties": { "source": { "type": "string", "enum": [ "criteo" ], "description": "Identifier for the demand source." }, "bids": { "type": "array", "items": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ExternalBid" }, "description": "Array of external bids. Total count across all demand sources must not exceed 100.\n" } } }, "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_AttributesFilter": { "type": "object", "title": "AttributesFilter", "description": "Use product attributes to filter auction bids. This feature requires additional integration and configuration.\n", "properties": { "operator": { "type": "string", "description": "Filter operator type. The value can be `and` (has all) or `or` (has any).", "enum": [ "and", "or" ] }, "attributes": { "type": "array", "description": "Attributes used for filtering in `key:value` format. The attribute name and value are limited to 40 characters each.\n", "maxItems": 5, "items": { "type": "string", "maxLength": 81, "examples": [ "color:red", "material:leather", "size:32" ] } } } }, "Topsort_Endpoints_v2_API_Reference_occurredAt": { "type": "string", "format": "date-time", "description": "A RFC3339 formatted timestamp including UTC offset.", "examples": [ "2009-01-01T12:59:59-05:00" ] }, "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_PlacementId": { "type": "integer", "format": "int32", "description": "The marketplace's ID of the placement where the ad will appear." }, "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_SearchQuery": { "type": "string", "description": "The search string provided by a user." }, "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_ResolvedItemID": { "type": "string", "description": "An opaque Topsort ID to be used when this item is ranked or interacted with.", "examples": [ "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=" ] }, "Topsort_Endpoints_v2_API_Reference_CategoryID": { "type": "string", "description": "A category ID.", "minLength": 1, "examples": [ "c_electronics" ] }, "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_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_ChannelType": { "type": "string", "description": "Optional. The channel where the event occurred.", "enum": [ "onsite", "offsite", "instore" ], "examples": [ "onsite" ] }, "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\nscore to provide a score that better represents the relevance of the\nparticipating products. If not given it will default to 1.\nValues must be between 0 and 1.\n", "examples": [ 0.75 ] }, "Topsort_Endpoints_v2_API_Reference_ExternalCampaignId": { "type": "string", "description": "Marketplace provided ID for a campaign", "examples": [ "awareness-campaign-2025" ] }, "Topsort_Endpoints_v2_API_Reference_ExternalVendorId": { "type": "string", "description": "Marketplace provided ID for a vendor", "examples": [ "my-new-vendor" ] }, "Topsort_Endpoints_v2_API_Reference_ObjectType": { "type": "string", "description": "The type of object that was predicted." }, "Topsort_Endpoints_v2_API_Reference_SponsoredListingsAuction": { "title": "Sponsored Listing", "type": "object", "description": "Describes the intent of running a sponsored listings auction.\n\nExactly **one** of the following fields must be set:\n * `products`\n * `category`\n\nThe optional `demandSources` field enables external demand sources (e.g., Criteo) to\nparticipate in the auction. External demand is restricted to listings auctions only.\n", "properties": { "type": { "type": "string", "const": "listings", "description": "Discriminator for the listings auction." }, "slots": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_SlotsCount" }, "category": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_AuctionCategory" }, "searchQuery": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_SearchQuery" }, "products": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_Products" }, "geoTargeting": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_GeoTargeting" }, "opaqueUserId": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_OpaqueUserID" }, "placementId": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_PlacementId" }, "page": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_Page" }, "filter": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_AttributesFilter" }, "demandSources": { "type": "array", "items": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_DemandSource" }, "description": "External demand sources participating in the auction. Total bids across all demand sources cannot exceed 100. This field is optional and requires additional integration and configuration.\n" } }, "required": [ "type", "slots" ], "examples": [ { "type": "listings", "slots": 2, "products": { "ids": [ "p_PJbnN", "p_ojng4", "p_8VKDt", "p_Mfk15" ] }, "geoTargeting": { "location": "New York" } }, { "type": "listings", "slots": 2, "products": { "ids": [ "p_PJbnN", "p_ojng4" ] }, "demandSources": [ { "source": "criteo", "bids": [ { "chargeType": "CPC", "entity": { "type": "product", "id": "p_PJbnN" }, "bidAmount": 0.5, "metadata": { "clickUrl": "https://example.com/click" } } ] } ] } ] }, "Topsort_Endpoints_v2_API_Reference_BannersAuction": { "title": "Banner Auction", "type": "object", "description": "Describes the intent of running a banner ads auction.\n\n * For **Landing Page** banners, `category` and `searchQuery` must be empty.\n * For **Category** banners, the `category` field must be set.\n * For **Keywords** banners, the `searchQuery` field must be set.\n", "properties": { "type": { "type": "string", "const": "banners", "description": "Discriminator for the banner auction." }, "slots": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_SlotsCount" }, "category": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_AuctionCategory" }, "searchQuery": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_SearchQuery" }, "device": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_Device" }, "geoTargeting": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_GeoTargeting" }, "slotId": { "type": "string", "description": "The ID of the banner placement for which this auction will be run for.", "minLength": 1 }, "products": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_Products" }, "opaqueUserId": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_OpaqueUserID" }, "placementId": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_PlacementId" }, "page": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_Page" } }, "required": [ "type", "slots", "slotId" ], "examples": [ { "type": "banners", "slots": 1, "slotId": "categories-ribbon-banner", "category": { "id": "c_yogurt" } } ] }, "Topsort_Endpoints_v2_API_Reference_AuctionRequest": { "description": "Describes the intent of running a single auction.", "oneOf": [ { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_SponsoredListingsAuction" }, { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_BannersAuction" } ], "discriminator": { "propertyName": "type" } }, "Topsort_Endpoints_v2_API_Reference_RankingRequest": { "type": "object", "description": "Describes the context related to a Ranking request\n", "properties": { "type": { "type": "string", "enum": [ "listings" ], "description": "Type of object to be ranked" }, "slots": { "type": "integer", "format": "int32", "minimum": 1, "description": "Specifies the maximum number of ranked objects that should be returned." }, "pageSize": { "type": "integer", "format": "int32", "minimum": 1, "description": "Specifies the maximum number of ranked objects per page that should be returned." }, "page": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_Page" }, "category": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_AuctionCategory" }, "device": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_Device" }, "geoTargeting": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_GeoTargeting" }, "products": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_Products" }, "opaqueUserId": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_OpaqueUserID" } }, "required": [ "type", "slots", "pageSize", "page", "opaqueUserId" ], "examples": [ { "type": "listings", "slots": 10, "pageSize": 10, "page": { "type": "category", "value": "sneakers", "pageId": "/category/sneakers" }, "opaqueUserId": "u_9ske45", "category": { "ids": [ "sneakers", "shoes" ] }, "products": { "ids": [ "p_PJbnN", "p_ojng4" ] } } ] }, "Topsort_Endpoints_v2_API_Reference_PredictionRequest": { "type": "object", "description": "Request to predict the outcome of an interaction.", "properties": { "metrics": { "type": "object", "description": "Metrics to predict, the response will include all the selected metrics.", "properties": { "ctr": { "type": "boolean", "description": "If `true` a Click Through Rate prediction will be made." }, "cvr": { "type": "boolean", "description": "If `true` a Conversion Rate prediction will be made." } } }, "opaqueUserId": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_OpaqueUserID" }, "page": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_Page" }, "objectType": { "type": "string", "description": "The type of object that is being reported on the interaction.", "enum": [ "listings", "banners" ] }, "deviceType": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_DeviceType" }, "productIds": { "type": "array", "items": { "type": "string", "examples": [ "p_1234", "p_5678" ] } } }, "examples": [ { "metrics": { "ctr": true }, "opaqueUserId": "u_9ske45", "productIds": [ "p_PJbnN", "p_ojng4" ], "objectType": "listings" } ], "required": [ "metrics", "productIds", "objectType", "opaqueUserId" ] }, "Topsort_Endpoints_v2_API_Reference_RetrievalRequest": { "description": "Request to retrieve objects based on context.", "type": "object", "properties": { "slots": { "type": "integer", "description": "How many objects to retrieve.", "examples": [ 10, 50 ], "minimum": 1, "maximum": 100 }, "opaqueUserId": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_OpaqueUserID" }, "page": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_Page" }, "objectType": { "type": "string", "description": "The type of object that needs to be retrieved.", "enum": [ "listings", "banners" ] }, "deviceType": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_DeviceType" }, "seedProductIds": { "type": "array", "items": { "type": "string", "examples": [ "p_1234", "p_5678" ] } }, "mode": { "type": "string", "description": "Retrieval mode, how to interpret the context to get objects.", "enum": [ "all", "complement", "similar" ], "default": "all" } }, "examples": [ { "slots": 5, "opaqueUserId": "u_9ske45", "seedProductIds": [ "p_PJbnN", "p_ojng4" ], "mode": "all", "objectType": "listings", "deviceType": "mobile" } ], "required": [ "slots", "seedProductIds", "opaqueUserId", "objectType" ] }, "Topsort_Endpoints_v2_API_Reference_AuctionResult": { "description": "Base auction result schema supporting different auction types through discriminator.", "discriminator": { "propertyName": "resultType", "mapping": { "listings": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_SponsoredListingsAuctionResult", "banners": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_BannersAuctionResult", "empty": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_EmptyAuctionResult", "external_demand_listings": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ExternalDemandSponsoredListingsAuctionResult" } }, "oneOf": [ { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_SponsoredListingsAuctionResult" }, { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_BannersAuctionResult" }, { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ExternalDemandSponsoredListingsAuctionResult" }, { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_EmptyAuctionResult" } ] }, "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_HotelsAuctionResult" }, { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_FlightsAuctionResult" }, { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_EmptyAuctionResult" } ] }, "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_BannersAuctionResult": { "title": "Banner Auction", "description": "The result of a banner auction, containing winning banner ads.", "type": "object", "properties": { "resultType": { "type": "string" }, "winners": { "type": "array", "items": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_BannersWinner" }, "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.\n" }, "error": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ErrorFlag" } }, "required": [ "winners", "error", "resultType" ] }, "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.\n" }, "error": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ErrorFlag" } }, "required": [ "winners", "error", "resultType" ] }, "Topsort_Endpoints_v2_API_Reference_ExternalDemandSponsoredListingsAuctionResult": { "title": "Sponsored Listings with External Demand", "description": "The result of a sponsored listings auction with external demand, containing winning product listings.", "type": "object", "properties": { "resultType": { "type": "string" }, "winners": { "type": "array", "items": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ExternalDemandSponsoredListingsWinner" }, "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.\n" }, "error": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ErrorFlag" } }, "required": [ "winners", "error", "resultType" ], "examples": [ { "resultType": "listings", "winners": [ { "rank": 1, "type": "product", "id": "p_PJbnN", "resolvedBidId": "WyJiX1BKYm5OIiwiY3JpdGVvIiwiQ1BDIiwibGlzdGluZ3MiXQ==", "demandSource": "criteo", "metadata": { "clickUrl": "https://example.com/click" } }, { "rank": 2, "type": "product", "id": "p_Mfk15", "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=", "demandSource": "topsort", "campaignId": "4bcc6093-f367-4df2-aa1b-7c1674dd6441" } ], "error": false } ] }, "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_ExternalDemandSponsoredListingsWinner": { "type": "object", "required": [ "rank", "type", "id", "resolvedBidId", "demandSource" ], "properties": { "rank": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerRank" }, "type": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerType", "enum": [ "product" ] }, "id": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerID" }, "resolvedBidId": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ResolvedBidID" }, "demandSource": { "type": "string", "enum": [ "criteo", "topsort" ] }, "campaignId": { "type": "string", "description": "The ID of the campaign that won the auction. This is omitted for external winners.", "examples": [ "82588593-85c5-47c0-b125-07e315b7f2b3" ] }, "metadata": { "type": "object", "additionalProperties": true, "description": "Pass-through metadata from the request for external winners (e.g., beacon URL, click URL). This is omitted for internal winners.\n", "examples": [ { "beaconUrl": "https://some.url.com/beacon", "clickUrl": "https://some.url.com/click" } ] } } }, "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.\n", "examples": [ { "headline": "Topsort Rocks", "brandName": "Topsort Brand", "creative": "https://some.url.com/rocks.jpeg" } ] }, "Topsort_Endpoints_v2_API_Reference_BannersWinner": { "description": "A winning bid in a banner auction with asset and campaign details.", "type": "object", "required": [ "rank", "type", "id", "resolvedBidId", "asset" ], "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" }, "asset": { "description": "The list of available sources for a banner.", "type": "array", "items": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_AssetSource" }, "minItems": 1 } } }, "Topsort_Endpoints_v2_API_Reference_HotelsAuctionResult": { "title": "Hotels", "description": "The result of a hotels travel auction.", "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_SponsoredListingsAuctionResult" }, "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.\n" }, "error": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ErrorFlag" } }, "required": [ "winners", "error", "resultType" ] }, "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_RankingResult": { "description": "The result of a ranking request, containing ordered products.", "type": "object", "properties": { "resultType": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_RankingWinner" }, "description": "Array of ranking objects in order from highest to lowest relevancy.\n" }, "error": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ErrorFlag" } }, "required": [ "results", "error", "resultType" ] }, "Topsort_Endpoints_v2_API_Reference_RankingWinner": { "description": "A ranked item from a ranking request with position and type information.", "type": "object", "required": [ "rank", "type", "id", "resolvedItemId" ], "properties": { "rank": { "type": "integer", "format": "int32", "description": "Where is the product ranked in the auction.\n", "minimum": 1 }, "type": { "allOf": [ { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerType" }, { "enum": [ "organic", "sponsored" ] } ] }, "id": { "type": "string", "description": "The marketplace's ID of the ranked entity.", "examples": [ "p_Mfk15" ] }, "resolvedItemId": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ResolvedItemID", "examples": [ "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=" ] } } }, "Topsort_Endpoints_v2_API_Reference_PredictionResult": { "description": "The result of a prediction request, containing CTR and CVR predictions for products.", "type": "object", "properties": { "objectType": { "allOf": [ { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ObjectType" }, { "enum": [ "listings", "banners" ], "examples": [ "listings" ] } ] }, "predictions": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "description": "Product identifier defined on the request." }, "ctr": { "type": "number", "description": "Click-Through Rate prediction." }, "cvr": { "type": "number", "description": "Conversion Rate prediction." } } }, "description": "Predicted objects", "examples": [ [ { "productId": "product-123", "ctr": 0.05, "cvr": 0.101 } ] ] } }, "examples": [ { "objectType": "listings", "predictions": [ { "productId": "p_PJbnN", "ctr": 0.03, "cvr": 0.06 }, { "productId": "p_ojng4", "ctr": 0.056, "cvr": 0.091 } ] } ], "required": [ "objectType", "predictions" ] }, "Topsort_Endpoints_v2_API_Reference_RetrievalResults": { "description": "The result of a retrieval request, containing relevant objects with scores.", "type": "object", "properties": { "objectType": { "allOf": [ { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ObjectType" }, { "enum": [ "listings", "banners" ] } ] }, "objects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Object identifier defined on the request." }, "score": { "type": "number", "description": "Relevance score for the retrieved products." } } }, "description": "Retrieved objects." } }, "examples": [ { "objectType": "listings", "objects": [ { "id": "p_xh90s", "score": 0.978 }, { "id": "p_12lp0", "score": 0.953 }, { "id": "p_ds7ui", "score": 0.877 } ] } ], "required": [ "objectType", "objects" ] }, "Topsort_Endpoints_v2_API_Reference_InteractionObject": { "type": "object", "description": "Information regarding an organic or non-sponsored event.", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The type of object that is being reported on the interaction.", "enum": [ "listing", "banner" ] }, "assetId": { "type": "string", "description": "When type is `banner`, signals the ID of the asset of the banner", "examples": [ "banner_asset_001" ] }, "clickType": { "type": "string", "description": "When type is `listing`, signals the specific interaction flavor with the listing.", "enum": [ "product", "like", "add-to-cart" ] } } }, "Topsort_Endpoints_v2_API_Reference_AssetSource": { "description": "A source available for an asset (banner or video).", "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "A vendor provided asset that the marketplace has to use as a banner. The asset will be served by Topsort's CDN. Note: When the content field is part of the response, the url links to an asset with the same JSON object available on the content object.\n" }, "content": { "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. Note: When the content field is part of the response, the url links to an asset with the same JSON object available on the content object.\n", "examples": [ { "headingText": "A banner for Topsort with a product image and a shop now button", "bannerText": "Topsort has the best tech!", "bannerTextColour": "48a94c", "heroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574", "heroImageAltText": "Topsort product image" } ] } }, "required": [ "url" ] }, "Topsort_Endpoints_v2_API_Reference_Products": { "required": [ "ids" ], "type": "object", "description": "List of products for the purpose of running an auction.\n", "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.\n", "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.\n", "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.\nIf given, these values will be combined with our internal quality scores to provide a score that better represents the relevance of the participating products.\nNote 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.\n", "items": { "type": "number", "maximum": 1, "exclusiveMinimum": 0, "minimum": 0, "examples": [ 0.75 ], "format": "double" }, "minItems": 1, "maxItems": 10000 } } }, "Topsort_Endpoints_v2_API_Reference_SponsoredBrandAuctionRequest": { "type": "object", "description": "Describes the intent of running a sponsored brand auction.\n\nExactly **one** of the following fields must be set:\n * `products`\n * `category`\n * `searchQuery`\n", "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.\n", "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.\n" }, "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_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.\n", "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_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_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_HotelsTravelContext" } } }, "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_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.\n", "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_HotelsTravelContext": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_BaseTravelContext", "description": "Context information specific to hotel travel auctions extending base travel context with hotel-specific fields." }, "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_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_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.\n", "examples": [ "could not find the provided resolved bid id" ] } } }, "Topsort_Endpoints_v2_API_Reference_Placement": { "description": "Information about where an ad or product is placed on a page.", "type": "object", "required": [ "path" ], "additionalProperties": false, "properties": { "path": { "type": "string", "description": "URL path of the page triggering the event. For web apps, this can be obtained in JS using `window.location.pathname`. For mobile apps, use the deep link for the current view, if available. Otherwise, encode the view from which the event occurred in your app as a path-like string (e.g. `/root/categories/:categoryId`).\n", "minLength": 1, "examples": [ "/categories/dairy" ] }, "position": { "type": "integer", "description": "For components with multiple items (i.e. search results, similar products, etc), this should indicate the index of a given item within that list.\n", "minimum": 1 }, "page": { "type": "integer", "description": "For paginated pages, this should indicate which page number triggered the event.\n", "minimum": 1 }, "pageSize": { "type": "integer", "description": "For paginated pages this should indicate how many items are in each result page.\n", "minimum": 1, "examples": [ 15 ] }, "productId": { "type": "string", "description": "The ID of the product associated to the page in which this event occurred, if applicable. This ID must match the ID provided through the catalog service.\n", "minLength": 1 }, "categoryIds": { "type": "array", "items": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_CategoryID" }, "description": "An array of IDs of the categories associated to the page in which this event occurred, if applicable. These IDs must match the IDs provided through the catalog service.\n", "minItems": 1 }, "searchQuery": { "type": "string", "description": "The search string provided by the user in the page where this event occurred, if applicable. This search string must match the searchQuery field that was provided in the auction request (if provided).\n", "minLength": 1, "examples": [ "blue shoes" ] } } }, "Topsort_Endpoints_v2_API_Reference_EventEntity": { "type": "object", "description": "`Entity` is meant for reporting organic events, not sponsored or promoted products. It refers to the object involved in the organic interaction. But, in most cases, you won't need to fill in this object. Be aware that if `resolvedBidId` has any value, `entity` will be disregarded.\n", "required": [ "id", "type" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The marketplace's ID of the entity associated with the interaction.", "minLength": 1, "examples": [ "ean-512385132" ] }, "type": { "type": "string", "description": "The type of entity associated with the interaction.", "enum": [ "product", "vendor" ], "examples": [ "product" ] } } }, "Topsort_Endpoints_v2_API_Reference_ExternalBid": { "type": "object", "description": "A bid from an external demand source participating in the auction.", "required": [ "chargeType", "entity", "bidAmount" ], "properties": { "chargeType": { "type": "string", "enum": [ "CPC" ], "description": "The charging model for this bid." }, "entity": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "product" ], "description": "Entity type. External bids currently only support product." }, "id": { "type": "string", "description": "The marketplace's ID of the entity." } } }, "bidAmount": { "type": "number", "description": "Bid amount in marketplace currency." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional free-form data (e.g., beacon URL, click URL)." } } }, "Topsort_Endpoints_v2_API_Reference_EventsRequest": { "description": "A batch request containing multiple events to be reported to Topsort.", "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "impressions": { "title": "Impressions", "description": "An array of impression events", "type": "array", "minItems": 0, "maxItems": 50, "items": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_Impression" } }, "clicks": { "title": "Clicks", "description": "An array of click events", "type": "array", "minItems": 0, "maxItems": 50, "items": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_Click" } }, "purchases": { "title": "Purchases", "description": "An array of purchase events", "type": "array", "minItems": 0, "maxItems": 50, "items": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_Purchase" } }, "pageviews": { "title": "Page views", "description": "An array of page views", "type": "array", "minItems": 0, "maxItems": 50, "items": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_PageView" } } }, "examples": [ { "impressions": [ { "id": "eb874c98-bf4d-40a9-ae6d-fcf4cecb535c", "occurredAt": "2019-01-01T12:59:59-05:00", "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8", "placement": { "path": "/categories/dairy", "position": 1, "page": 1, "pageSize": 15, "categoryIds": [ "9BLIe" ] }, "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=", "deviceType": "mobile", "channel": "onsite" } ] }, { "clicks": [ { "id": "b39d39ed-ea0e-4059-9d15-4990b39c85a2", "occurredAt": "2019-01-01T13:01:42-05:00", "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8", "placement": { "path": "/categories/dairy", "position": 1, "page": 1, "pageSize": 15, "categoryIds": [ "9BLIe" ] }, "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=", "deviceType": "mobile", "channel": "offsite" } ] }, { "purchases": [ { "id": "0e06c899-b2cd-4e0d-b0de-8aefb4b6d0a0", "items": [ { "productId": "p_SA0238", "unitPrice": 12.95, "quantity": 2, "vendorId": "v_8fj2D" }, { "productId": "p_oajf2D", "unitPrice": 1.49 } ], "occurredAt": "2019-01-01T12:59:59-05:00", "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8", "deviceType": "desktop", "channel": "onsite" }, { "id": "b7147656-504f-4ae7-b335-740829ff64c6", "items": [ { "productId": "p_SA0279", "unitPrice": 119.95, "quantity": 5, "vendorId": "v_8fj2D" } ], "occurredAt": "2019-01-01T13:59:59-05:00", "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8", "channel": "instore" } ] }, { "pageviews": [ { "id": "8f648a8e-830c-4bb4-9d93-6ea80075ca82", "occurredAt": "2019-01-01T12:59:58-05:00", "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8", "page": { "type": "category", "pageId": "/categories/dairy", "value": "dairy" }, "deviceType": "mobile", "channel": "onsite" } ] } ] }, "Topsort_Endpoints_v2_API_Reference_Impression": { "title": "Impression", "type": "object", "description": "An impression means a promotable has become visible to the consumer. For promoted entities, include the `resolvedBidId` field from the `/v2/auctions` response. For unpromoted entities, include the `entity` field to describe what was seen. In case you cannot send an impression when the product becomes visible, send us an impression event when the product was rendered in the HTML or, if that's also not possible, when your API returns the results. It is important to select the most specific event so that your vendors have more accurate CTR metrics, which will allow them to better predict their campaigns.\n", "required": [ "occurredAt", "opaqueUserId", "id" ], "additionalProperties": false, "properties": { "resolvedBidId": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ResolvedBidID", "description": "If the impression is over an ad promotion, this is the `resolvedBidId` field received from the `/auctions` request. In most situations, especially when reporting a sponsored interaction, you'll want to fill in this field.\n" }, "entity": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_EventEntity" }, "placement": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_Placement" }, "occurredAt": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_occurredAt" }, "opaqueUserId": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_OpaqueUserID" }, "id": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_EventIdentifier" }, "additionalAttribution": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_EventEntity" }, "page": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_Page" }, "object": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_InteractionObject" }, "externalCampaignId": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ExternalCampaignId" }, "externalVendorId": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ExternalVendorId" }, "deviceType": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_DeviceType" }, "channel": { "type": "string", "description": "Optional. The channel where the event occurred.", "enum": [ "onsite", "offsite", "instore" ], "examples": [ "onsite" ] } } }, "Topsort_Endpoints_v2_API_Reference_Click": { "title": "Click", "description": "A click is sent to Topsort when the consumer has clicked on a promotable. For promoted entities, include the `resolvedBidId` field from the `/v2/auctions` response. For unpromoted entities, include the `entity` field to describe what was clicked. Topsort charges the vendor and pays the marketplace for clicks on ads in promoted placements on the marketplace app.\n", "type": "object", "required": [ "occurredAt", "opaqueUserId", "id" ], "additionalProperties": false, "properties": { "resolvedBidId": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ResolvedBidID", "description": "If the click is over an ad promotion, this is the `resolvedBidId` field received from the `/auctions` request. In most situations, especially when reporting a sponsored interaction, you'll want to fill in this field." }, "entity": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_EventEntity" }, "placement": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_Placement" }, "occurredAt": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_occurredAt" }, "opaqueUserId": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_OpaqueUserID" }, "id": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_EventIdentifier" }, "additionalAttribution": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_EventEntity" }, "page": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_Page" }, "object": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_InteractionObject" }, "clickType": { "type": "string", "description": "For sponsored events only, signals the specific interaction flavor with the listing.", "enum": [ "product", "like", "add-to-cart" ] }, "externalCampaignId": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ExternalCampaignId" }, "externalVendorId": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ExternalVendorId" }, "deviceType": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_DeviceType" }, "channel": { "type": "string", "description": "Optional. The channel where the event occurred.", "enum": [ "onsite", "offsite", "instore" ], "examples": [ "onsite" ] } } }, "Topsort_Endpoints_v2_API_Reference_Purchase": { "title": "Purchase", "description": "A purchase is sent to Topsort once a marketplace customer places an order. These events are used to measure the effectiveness of an ad campaign.\n", "type": "object", "required": [ "occurredAt", "opaqueUserId", "items", "id" ], "additionalProperties": false, "properties": { "occurredAt": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_occurredAt", "description": "RFC3339 formatted timestamp, including UTC offset, of the instant in which the order was placed. Please note that purchases will NOT be attributed to an auction that happened after." }, "opaqueUserId": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_OpaqueUserID" }, "items": { "type": "array", "description": "Items purchased.", "minItems": 1, "items": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_PurchaseItem" } }, "id": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_EventIdentifier" }, "deviceType": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_DeviceType" }, "channel": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ChannelType" } } }, "Topsort_Endpoints_v2_API_Reference_PurchaseItem": { "description": "An item included in a purchase transaction with product, quantity, and pricing details.", "type": "object", "required": [ "productId", "unitPrice" ], "additionalProperties": false, "properties": { "productId": { "type": "string", "description": "The marketplace ID of the product being purchased.", "minLength": 1, "examples": [ "p_SA0238" ] }, "quantity": { "type": "integer", "minimum": 1, "default": 1, "description": "Amount of products purchased.", "examples": [ 2 ] }, "unitPrice": { "type": "number", "format": "double", "exclusiveMinimum": 0, "description": "The price of a single item in the marketplace currency.", "examples": [ 12.95 ] }, "vendorId": { "type": "string", "description": "The vendor ID of the product being purchased. This field is optional and should be filled in if 1. a product is sold by multiple vendors, or 2. you want to use it for halo attribution\n", "minLength": 1, "examples": [ "v_8fj2D" ] } } }, "Topsort_Endpoints_v2_API_Reference_EventIdentifier": { "type": "string", "description": "A unique identifier for the request. This field ensures the event reporting is idempotent in case there is a network issue and the request is retried. If there is no impression model on the marketplace side, generate a unique string that does not change if the event is resent.\n", "minLength": 1, "examples": [ "eb874c98-bf4d-40a9-ae6d-fcf4cecb535c" ] }, "Topsort_Endpoints_v2_API_Reference_PageView": { "title": "Page View", "type": "object", "description": "A page view represents the navigation of the user throughout the page. They are considered organic events. In contrast to clicks or impressions, which are events within a page, a page view is the interaction with the full page, which can contain multiple objects.\n", "required": [ "occurredAt", "opaqueUserId", "id", "page" ], "additionalProperties": false, "properties": { "page": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_Page" }, "occurredAt": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_occurredAt" }, "opaqueUserId": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_OpaqueUserID" }, "id": { "type": "string", "description": "The marketplace's unique ID for the event. This field ensures the event reporting is idempotent in case there is a network issue and the request is retried. If there is no pageview model on the marketplace side, generate a unique string that does not change if the event is resent.\n", "minLength": 1, "examples": [ "eb874c98-bf4d-40a9-ae6d-fcf4cecb535c" ] }, "deviceType": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_DeviceType" }, "channel": { "$ref": "#/components/schemas/Topsort_Endpoints_v2_API_Reference_ChannelType" } } }, "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_CampaignId": { "type": "string", "description": "The ID of the campaign that won the auction.", "examples": [ "82588593-85c5-47c0-b125-07e315b7f2b3" ] }, "Topsort_Endpoints_v2_API_Reference_ErrorFlag": { "type": "boolean", "description": "A boolean indicating whether this auction was resolved successfully.", "examples": [ false, true ] }, "Advanced_APIs_AccountActivity": { "properties": { "date": { "type": "string", "format": "date", "title": "Date", "description": "The date for this aggregation." }, "transaction": { "$ref": "#/components/schemas/Advanced_APIs_TransactionType", "description": "The transaction type." }, "amount": { "type": "integer", "title": "Amount", "description": "Amount of money made by purchases over a period of time, in minor units of currency according to ISO 4217." } }, "type": "object", "required": [ "date", "transaction", "amount" ], "title": "AccountActivity", "description": "Account activity count." }, "Advanced_APIs_AccountActivityResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "accountActivities": { "items": { "$ref": "#/components/schemas/Advanced_APIs_AccountActivity" }, "type": "array", "title": "Accountactivities", "description": "A list with the account activity count." } }, "type": "object", "required": [ "hasMore", "accountActivities" ], "title": "AccountActivityResponse", "description": "Response for account activity count." }, "Advanced_APIs_ActiveVendorsResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Whether there are more active vendors" }, "nextPage": { "title": "Nextpage", "description": "The next page token", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "vendors": { "items": { "type": "string" }, "type": "array", "title": "Vendors", "description": "The active vendor ids for the DSP" } }, "type": "object", "required": [ "hasMore", "nextPage", "vendors" ], "title": "ActiveVendorsResponse" }, "Advanced_APIs_AdConfigPage": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "The ID of the ad config page." }, "name": { "type": "string", "minLength": 1, "title": "Name", "description": "The name of the landing page.", "examples": [ "Homepage" ] }, "url": { "type": "string", "minLength": 1, "title": "Url", "description": "The url or deep link of the landing page.", "examples": [ "https://app.example.com/main" ] }, "imageUrl": { "title": "Imageurl", "description": "The image url of the ad config page.", "oneOf": [ { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri" }, { "type": "null" } ] }, "marketplaceId": { "type": "string", "format": "uuid", "title": "Marketplaceid", "description": "The ID of the marketplace that the ad config page belongs to." } }, "type": "object", "required": [ "id", "name", "url", "marketplaceId" ], "title": "AdConfigPage", "description": "The ad config page model." }, "Advanced_APIs_AdConfigSlot": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "The ID of the ad config slot." }, "externalId": { "type": "string", "minLength": 1, "title": "Externalid", "description": "The external ID provided by marketplaces." }, "position": { "$ref": "#/components/schemas/Advanced_APIs_PositionType", "description": "The position of the ad config slot." }, "page": { "description": "The page that the ad config slot belongs to. Only 'landing' slots can belong to a page.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_AdConfigPage" }, { "type": "null" } ] }, "marketplaceId": { "type": "string", "format": "uuid", "title": "Marketplaceid", "description": "The ID of the marketplace that the ad config slot belongs to." }, "dimensions": { "additionalProperties": { "$ref": "#/components/schemas/Advanced_APIs_AdConfigSlotDimension" }, "propertyNames": { "$ref": "#/components/schemas/Advanced_APIs_MediaDeviceType" }, "type": "object", "title": "Dimensions", "description": "The slot dimensions. There can be at most one dimension for each device type.", "examples": [ { "desktop": { "height": 20, "width": 20 }, "mobile": { "height": 10, "width": 10 } } ] }, "isActive": { "type": "boolean", "title": "Isactive", "description": "Indicates whether the ad config slot is active. If false, the slot cannot be used in campaigns.", "default": true } }, "type": "object", "required": [ "id", "externalId", "position", "marketplaceId", "dimensions" ], "title": "AdConfigSlot", "description": "The ad config slot model." }, "Advanced_APIs_AdConfigSlotDimension": { "properties": { "width": { "type": "integer", "exclusiveMinimum": 0, "title": "Width", "description": "The width of the dimension." }, "height": { "type": "integer", "exclusiveMinimum": 0, "title": "Height", "description": "The height of the dimension." } }, "type": "object", "required": [ "width", "height" ], "title": "AdConfigSlotDimension", "description": "The ad config dimension model." }, "Advanced_APIs_AdConfigSlotsResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "slots": { "items": { "$ref": "#/components/schemas/Advanced_APIs_AdConfigSlot" }, "type": "array", "title": "Slots" } }, "type": "object", "required": [ "hasMore", "slots" ], "title": "AdConfigSlotsResponse" }, "Advanced_APIs_AdFormat": { "type": "string", "enum": [ "listing", "banner", "sponsored_brand", "exclusive_listing", "exclusive_banner", "travel_listing", "flight_listing" ], "title": "AdFormat", "description": "The type of the auction." }, "Advanced_APIs_AddBalanceRequest": { "properties": { "balance": { "type": "number", "exclusiveMinimum": 0, "title": "Balance", "description": "Amount to add in the marketplace currency" }, "description": { "title": "Description", "description": "Reason given to add the amount", "examples": [ "Free credits added to the account" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "type": "object", "required": [ "balance" ], "title": "AddBalanceRequest", "description": "Basic request Data for Adding Balance." }, "Advanced_APIs_AddBalanceResponse": { "properties": { "result": { "type": "boolean", "title": "Result" } }, "type": "object", "required": [ "result" ], "title": "AddBalanceResponse", "description": "Result of the Balance Adding. Returns True if the operation was executed correctly." }, "Advanced_APIs_AdjustBalanceRequestPublic": { "properties": { "amount": { "type": "integer", "title": "Amount", "description": "Amount to add to the balance. This value must be non-zero. ISO 4217 standard.", "examples": [ 100 ] }, "description": { "type": "string", "minLength": 1, "title": "Description", "description": "Reason given to adjust the amount", "examples": [ "Vendor used the money for other ads" ] } }, "type": "object", "required": [ "amount", "description" ], "title": "AdjustBalanceRequestPublic" }, "Advanced_APIs_AdjustBalanceResponse": { "properties": { "balance": { "type": "integer", "title": "Balance", "description": "Resulting balance of an adjustment. ISO 4217 standard" } }, "type": "object", "required": [ "balance" ], "title": "AdjustBalanceResponse" }, "Advanced_APIs_AgencyCampaignType": { "type": "string", "enum": [ "banner", "listing" ], "title": "AgencyCampaignType" }, "Advanced_APIs_AgencyCampaignWithKPIS": { "properties": { "adSpend": { "type": "integer", "minimum": 0, "title": "Adspend", "description": "Amount spent on ads during the selected period in minor units of currency." }, "cpc": { "type": "number", "title": "Cpc", "description": "Average cost per click during the selected period." }, "cpm": { "type": "number", "title": "Cpm", "description": "Average cost per thousand impressions during the selected period.", "default": 0 }, "ctr": { "type": "number", "title": "Ctr", "description": "The click through rate during the selected period." }, "conversionRate": { "type": "number", "title": "Conversionrate", "description": "The conversion rate during the selected period." }, "impressions": { "type": "integer", "minimum": 0, "title": "Impressions", "description": "Number of impressions during the selected period." }, "chargedImpressions": { "type": "integer", "minimum": 0, "title": "Chargedimpressions", "description": "Amount of charged impressions during the selected period." }, "clicks": { "type": "integer", "minimum": 0, "title": "Clicks", "description": "Number of clicks during the selected period." }, "chargedClicks": { "type": "integer", "minimum": 0, "title": "Chargedclicks", "description": "Amount of charged clicks during the selected period." }, "purchaseCount": { "type": "integer", "minimum": 0, "title": "Purchasecount", "description": "Number of purchases during the selected period." }, "purchaseRevenue": { "type": "integer", "minimum": 0, "title": "Purchaserevenue", "description": "Revenue from promoted sales during the selected period in minor units of currency." }, "roas": { "type": "number", "title": "Roas", "description": "The return on ad spend during the selected period." }, "acos": { "type": "number", "title": "Acos", "description": "Advertising cost of sales (inverse of ROAS) during the selected period.", "default": 0 }, "agencyCampaignId": { "type": "string", "format": "uuid", "title": "Agencycampaignid", "description": "The campaign id for the agency." }, "campaignName": { "type": "string", "title": "Campaignname", "description": "The campaign name." }, "dailyBudget": { "type": "number", "title": "Dailybudget", "description": "The daily budget set for this campaign. In minimum currency units.", "examples": [ 1000 ] }, "isActive": { "type": "boolean", "title": "Isactive", "description": "Whether this campaign is active." }, "startDate": { "type": "string", "format": "date-time", "title": "Startdate", "description": "The starting date of the campaign." }, "endDate": { "title": "Enddate", "description": "The end date of the campaign.", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "adFormat": { "$ref": "#/components/schemas/Advanced_APIs_AgencyCampaignType", "description": "The ad format of the campaign.", "examples": [ "listing", "banner" ] }, "targetRoas": { "type": "number", "title": "Targetroas", "description": "The target roas of the campaign.", "examples": [ 2 ] } }, "type": "object", "required": [ "adSpend", "cpc", "ctr", "conversionRate", "impressions", "chargedImpressions", "clicks", "chargedClicks", "purchaseCount", "purchaseRevenue", "roas", "agencyCampaignId", "campaignName", "dailyBudget", "isActive", "startDate", "endDate", "adFormat", "targetRoas" ], "title": "AgencyCampaignWithKPIS" }, "Advanced_APIs_AgencyCampaignsWithKPIsResponsePaginated": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "campaigns": { "items": { "$ref": "#/components/schemas/Advanced_APIs_AgencyCampaignWithKPIS" }, "type": "array", "title": "Campaigns" } }, "type": "object", "required": [ "hasMore", "campaigns" ], "title": "AgencyCampaignsWithKPIsResponsePaginated" }, "Advanced_APIs_AssetCreateRequest": { "properties": { "name": { "type": "string", "maxLength": 64, "pattern": "^[^<>/\\\\]+$", "title": "Name", "description": "The name of the asset." }, "productIds": { "title": "Productids", "description": "The product ids that the asset is associated with.", "oneOf": [ { "items": { "type": "string", "maxLength": 64 }, "type": "array", "maxItems": 10 }, { "type": "null" } ] }, "brands": { "title": "Brands", "description": "The brands that the asset is associated with.", "oneOf": [ { "items": { "type": "string", "maxLength": 64 }, "type": "array", "maxItems": 10 }, { "type": "null" } ] }, "collectionIds": { "title": "Collectionids", "description": "The collections that the asset is associated with.", "oneOf": [ { "items": { "type": "string", "maxLength": 38 }, "type": "array", "maxItems": 10 }, { "type": "null" } ] }, "mimetype": { "description": "The mimetype of the asset.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_AssetMimetype" }, { "type": "null" } ] }, "metadata": { "title": "Metadata", "description": "The metadata associated with the asset. Max key length is 32 characters and max value length is 64 characters.", "oneOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ] }, "externalUrl": { "title": "Externalurl", "description": "URL of an externally hosted asset. If this value is provided, then the asset will not be hosted by Topsort.", "oneOf": [ { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri" }, { "type": "null" } ] } }, "type": "object", "required": [ "name" ], "title": "AssetCreateRequest" }, "Advanced_APIs_AssetCreateResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "The id of the asset." }, "name": { "type": "string", "title": "Name", "description": "The name of the asset." }, "mimetype": { "title": "Mimetype", "description": "The mimetype of the asset.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/Advanced_APIs_AssetStatus", "description": "Approval status of the asset" }, "url": { "title": "Url", "description": "The url of the asset.", "oneOf": [ { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri" }, { "type": "null" } ] }, "productIds": { "items": { "type": "string" }, "type": "array", "title": "Productids", "description": "The product ids that the asset is associated with." }, "brands": { "items": { "type": "string" }, "type": "array", "title": "Brands", "description": "The brands that the asset is associated with." }, "metadata": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Metadata", "description": "The metadata associated with the asset." }, "isExternal": { "type": "boolean", "title": "Isexternal", "description": "Indicates if the asset is externally hosted." }, "fields": { "title": "Fields", "description": "The fields to send with the pre-signed url. Can be empty if this is an external asset.", "oneOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ] }, "uploadUrl": { "title": "Uploadurl", "description": "The upload url the asset needs to be uploaded to.", "oneOf": [ { "type": "string", "minLength": 1, "format": "uri" }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "name", "status", "productIds", "brands", "metadata", "isExternal" ], "title": "AssetCreateResponse" }, "Advanced_APIs_AssetMimetype": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/gif", "image/webp", "text/html", "video/mp4", "video/quicktime", "application/json", "text/vtt" ], "title": "AssetMimetype" }, "Advanced_APIs_AssetResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "The id of the asset." }, "name": { "type": "string", "title": "Name", "description": "The name of the asset." }, "mimetype": { "title": "Mimetype", "description": "The mimetype of the asset.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/Advanced_APIs_AssetStatus", "description": "Approval status of the asset" }, "url": { "title": "Url", "description": "The url of the asset.", "oneOf": [ { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri" }, { "type": "null" } ] }, "productIds": { "items": { "type": "string" }, "type": "array", "title": "Productids", "description": "The product ids that the asset is associated with." }, "brands": { "items": { "type": "string" }, "type": "array", "title": "Brands", "description": "The brands that the asset is associated with." }, "metadata": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Metadata", "description": "The metadata associated with the asset." }, "isExternal": { "type": "boolean", "title": "Isexternal", "description": "Indicates if the asset is externally hosted." }, "collections": { "items": { "type": "string" }, "type": "array", "title": "Collections", "description": "The collections that the asset is associated with." } }, "type": "object", "required": [ "id", "name", "status", "productIds", "brands", "metadata", "isExternal", "collections" ], "title": "AssetResponse" }, "Advanced_APIs_AssetStatus": { "type": "string", "enum": [ "pending_upload", "pending_approval", "upload_error", "approved", "rejected" ], "title": "AssetStatus" }, "Advanced_APIs_AssetUpdateRequest": { "properties": { "name": { "title": "Name", "description": "The name of the asset.", "oneOf": [ { "type": "string", "maxLength": 64, "pattern": "^[^<>/\\\\]+$" }, { "type": "null" } ] }, "productIds": { "title": "Productids", "description": "The product ids that the asset is associated with.", "oneOf": [ { "items": { "type": "string", "maxLength": 64 }, "type": "array", "maxItems": 10 }, { "type": "null" } ] }, "brands": { "title": "Brands", "description": "The brands that the asset is associated with.", "oneOf": [ { "items": { "type": "string", "maxLength": 64 }, "type": "array", "maxItems": 10 }, { "type": "null" } ] }, "collectionIds": { "title": "Collectionids", "description": "The collections that the asset is associated with.", "oneOf": [ { "items": { "type": "string", "maxLength": 38 }, "type": "array", "maxItems": 10 }, { "type": "null" } ] }, "metadata": { "title": "Metadata", "description": "The metadata associated with the asset.", "oneOf": [ { "additionalProperties": { "type": "string" }, "type": "object", "maxProperties": 10 }, { "type": "null" } ] } }, "type": "object", "title": "AssetUpdateRequest" }, "Advanced_APIs_AssetsResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "assets": { "items": { "$ref": "#/components/schemas/Advanced_APIs_AssetResponse" }, "type": "array", "title": "Assets", "description": "List of assets" } }, "type": "object", "required": [ "hasMore", "assets" ], "title": "AssetsResponse" }, "Advanced_APIs_Auctions": { "properties": { "percentageWon": { "type": "number", "title": "Percentagewon", "description": "Percentage of auctions won for a campaign in a given period of time." }, "won": { "type": "integer", "title": "Won", "description": "Number of auctions won for a campaign in a given period of time." }, "lost": { "type": "integer", "title": "Lost", "description": "Number of auctions lost for a campaign in a given period of time." } }, "type": "object", "required": [ "percentageWon", "won", "lost" ], "title": "Auctions", "description": "Aggregation for auctions." }, "Advanced_APIs_AutobiddingCampaignType": { "type": "string", "enum": [ "autobidding" ], "title": "AutobiddingCampaignType" }, "Advanced_APIs_AutobiddingObjective": { "type": "string", "enum": [ "impressions", "clicks", "conversions", "revenue" ], "title": "AutobiddingObjective" }, "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_BannerAd-Output": { "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_BannerAdRejectionReason": { "properties": { "declineReason": { "type": "string", "title": "Declinereason" }, "reasonDetails": { "title": "Reasondetails", "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "type": "object", "required": [ "declineReason" ], "title": "BannerAdRejectionReason" }, "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_Bid": { "properties": { "bidId": { "type": "string", "format": "uuid", "title": "Bidid", "description": "The ID of the bid" }, "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" } ] }, "target": { "$ref": "#/components/schemas/Advanced_APIs_Entity", "description": "The type of entity this bid will be targeting." }, "isActive": { "type": "boolean", "title": "Isactive", "description": "Whether the bid is active." }, "triggers": { "items": { "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_KeywordTrigger-Output" }, { "$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": "#/components/schemas/Advanced_APIs_CategoriesTrigger", "categories_from_campaign_products": "#/components/schemas/Advanced_APIs_CategoriesFromCampaignProductsTrigger", "category": "#/components/schemas/Advanced_APIs_CategoryTrigger", "keyword": "#/components/schemas/Advanced_APIs_KeywordTrigger-Output", "keywords_from_campaign_products": "#/components/schemas/Advanced_APIs_KeywordsFromCampaignProductsTrigger", "nocontext": "#/components/schemas/Advanced_APIs_NoContextTrigger", "product": "#/components/schemas/Advanced_APIs_ProductTrigger" } } }, "type": "array", "title": "Triggers", "description": "A list of objects that trigger the appearance of this bid on an auction." }, "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" } ] }, "bidsBehaviorData": { "title": "Bidsbehaviordata", "description": "Deprecated. This field is always null. For behavioral data use reporting service.", "deprecated": true, "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "campaignId": { "type": "string", "format": "uuid", "title": "Campaignid", "description": "The ID of the campaign." }, "formatProperties": { "description": "", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_BannerAd-Output" }, { "type": "null" } ] }, "state": { "$ref": "#/components/schemas/Advanced_APIs_BidState", "description": "The activity state of the bid." } }, "type": "object", "required": [ "bidId", "target", "isActive", "triggers", "campaignId", "state" ], "title": "Bid", "description": "Represents an auction bid for a specific entity and a specific maximum amount." }, "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": "#/components/schemas/Advanced_APIs_CategoriesTrigger", "categories_from_campaign_products": "#/components/schemas/Advanced_APIs_CategoriesFromCampaignProductsTrigger", "category": "#/components/schemas/Advanced_APIs_CategoryTrigger", "keyword": "#/components/schemas/Advanced_APIs_KeywordTrigger-Input", "keywords_from_campaign_products": "#/components/schemas/Advanced_APIs_KeywordsFromCampaignProductsTrigger", "nocontext": "#/components/schemas/Advanced_APIs_NoContextTrigger", "product": "#/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_BidCreateRequest": { "properties": { "bids": { "items": { "$ref": "#/components/schemas/Advanced_APIs_BidCreate" }, "type": "array", "maxItems": 500, "minItems": 1, "title": "Bids", "description": "An array of bids to be created." } }, "type": "object", "required": [ "bids" ], "title": "BidCreateRequest" }, "Advanced_APIs_BidState": { "type": "string", "enum": [ "active", "deactivated_manually", "inactive_entity", "deleted_entity", "legacy_inactive", "inactive_schedule" ], "title": "BidState", "description": "The activity state of a bid." }, "Advanced_APIs_BidUpdateRequest": { "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" } ] }, "isActive": { "title": "Isactive", "description": "Whether to activate or deactivate the bid.", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "type": "object", "title": "BidUpdateRequest", "description": "The Bid update request body." }, "Advanced_APIs_Body_upload_segment_users": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_upload_segment_users" }, "Advanced_APIs_Brand": { "properties": { "id": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Id", "description": "The brand ID.", "examples": [ "es5086vyV" ] }, "name": { "type": "string", "minLength": 1, "title": "Name", "description": "The brand name. Truncated to 150 characters.", "examples": [ "Delirium" ] } }, "type": "object", "required": [ "id", "name" ], "title": "Brand", "description": "The brand which a product belongs to." }, "Advanced_APIs_Budget": { "properties": { "amount": { "type": "integer", "exclusiveMaximum": 50000000000, "exclusiveMinimum": 0, "format": "int64", "title": "Amount", "description": "The amount of money in the budget in minor units of currency according to ISO 4217.", "examples": [ 1000 ] }, "amountRemaining": { "type": "integer", "format": "int64", "title": "Amountremaining", "description": "The remaining amount of the budget. This field is deprecated and will be set to 0 once the notice period is over.", "deprecated": true }, "amountCarryover": { "type": "integer", "format": "int64", "title": "Amountcarryover", "description": "The amount carried over from the last period. This field is deprecated and will be set to 0 once the notice period is over.", "deprecated": true }, "amountUsed": { "type": "integer", "format": "int64", "title": "Amountused", "description": "The used amount of the budget. This field is deprecated and will be set to 0 once the notice period is over.", "deprecated": true }, "type": { "$ref": "#/components/schemas/Advanced_APIs_Type", "examples": [ "daily" ] } }, "type": "object", "required": [ "amount", "amountRemaining", "amountCarryover", "amountUsed", "type" ], "title": "Budget", "description": "A campaign budget." }, "Advanced_APIs_BudgetCreate": { "properties": { "amount": { "type": "integer", "exclusiveMaximum": 50000000000, "exclusiveMinimum": 0, "format": "int64", "title": "Amount", "description": "The amount of money in the budget in minor units of currency according to ISO 4217.", "examples": [ 1000 ] }, "type": { "$ref": "#/components/schemas/Advanced_APIs_Type", "examples": [ "daily" ] } }, "type": "object", "required": [ "amount", "type" ], "title": "BudgetCreate", "description": "A budget creation request." }, "Advanced_APIs_BudgetPeriodType": { "type": "string", "enum": [ "daily", "weekly", "monthly", "total" ], "title": "BudgetPeriodType", "description": "The periodicity of the budget." }, "Advanced_APIs_BudgetUpdate": { "properties": { "amount": { "format": "int64", "title": "Amount", "description": "The amount of money in the budget in minor units of currency according to ISO 4217.", "examples": [ 1000 ], "oneOf": [ { "type": "integer", "exclusiveMaximum": 50000000000, "exclusiveMinimum": 0 }, { "type": "null" } ] }, "type": { "description": "The periodicity of the budget.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_Type" }, { "type": "null" } ] } }, "type": "object", "required": [ "amount" ], "title": "BudgetUpdate", "description": "Campaign budget update request model." }, "Advanced_APIs_BurnVendorBalanceRequest": { "properties": { "amount": { "type": "number", "exclusiveMinimum": 0, "title": "Amount", "description": "Amount to Burn. The value must be greater or equal to the minimum currency units. For example, for USD you cannot specify 0.009, as that's less than 1 cent.", "examples": [ 100 ] }, "description": { "type": "string", "minLength": 1, "title": "Description", "description": "Reason given to burn the amount", "examples": [ "Vendor used the money for other ads" ] } }, "type": "object", "required": [ "amount", "description" ], "title": "BurnVendorBalanceRequest", "description": "Basic request payload for Burning Balance." }, "Advanced_APIs_CampaignEntityType": { "type": "string", "enum": [ "product", "brand", "vendor", "url" ], "title": "CampaignEntityType", "description": "The type of the entity to be advertised." }, "Advanced_APIs_CampaignKPIsByProduct": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "reports": { "items": { "$ref": "#/components/schemas/Advanced_APIs_ProductKPIs" }, "type": "array", "title": "Reports", "description": "A list with report data, separated by product" } }, "type": "object", "required": [ "hasMore", "reports" ], "title": "CampaignKPIsByProduct" }, "Advanced_APIs_CampaignOrderByDirection": { "type": "string", "enum": [ "asc", "desc" ], "title": "CampaignOrderByDirection", "description": "The direction to order by." }, "Advanced_APIs_CampaignProduct": { "properties": { "productId": { "type": "string", "title": "Productid" }, "isActive": { "type": "boolean", "title": "Isactive" } }, "type": "object", "required": [ "productId", "isActive" ], "title": "CampaignProduct" }, "Advanced_APIs_CampaignProductUpsertRequest": { "properties": { "products": { "items": { "$ref": "#/components/schemas/Advanced_APIs_CampaignProduct" }, "type": "array", "maxItems": 250, "minItems": 1, "uniqueItems": true, "title": "Products", "description": "The products to upsert." } }, "type": "object", "required": [ "products" ], "title": "CampaignProductUpsertRequest" }, "Advanced_APIs_CampaignProductsResponse": { "properties": { "products": { "items": { "$ref": "#/components/schemas/Advanced_APIs_CampaignProduct" }, "type": "array", "maxItems": 250, "title": "Products", "description": "The products in the campaign." } }, "type": "object", "required": [ "products" ], "title": "CampaignProductsResponse" }, "Advanced_APIs_CampaignRestrictionResponse": { "properties": { "id": { "type": "integer", "title": "Id", "description": "The ID of the restriction." }, "campaignId": { "type": "string", "format": "uuid", "title": "Campaignid", "description": "The ID of the campaign." }, "marketplaceId": { "type": "string", "format": "uuid", "title": "Marketplaceid", "description": "The ID of the marketplace." }, "restrictionType": { "$ref": "#/components/schemas/Advanced_APIs_RestrictionTypeResponse" }, "limit": { "type": "integer", "title": "Limit", "description": "The limit of the restriction." }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat", "description": "The creation date of the restriction." }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat", "description": "The last update date of the restriction." }, "status": { "$ref": "#/components/schemas/Advanced_APIs_CampaignRestrictionStatus", "description": "The status of the restriction." } }, "type": "object", "required": [ "id", "campaignId", "marketplaceId", "restrictionType", "limit", "createdAt", "updatedAt", "status" ], "title": "CampaignRestrictionResponse", "description": "Limit-based restrictions for a campaign." }, "Advanced_APIs_CampaignRestrictionStatus": { "type": "string", "enum": [ "active", "inactive" ], "title": "CampaignRestrictionStatus" }, "Advanced_APIs_CampaignRestrictionsResponse": { "properties": { "restrictions": { "items": { "$ref": "#/components/schemas/Advanced_APIs_CampaignRestrictionResponse" }, "type": "array", "title": "Restrictions" } }, "type": "object", "required": [ "restrictions" ], "title": "CampaignRestrictionsResponse" }, "Advanced_APIs_CampaignStatus": { "type": "string", "enum": [ "approved", "pending", "rejected" ], "title": "CampaignStatus", "description": "Represents the review status of a banner campaign." }, "Advanced_APIs_CampaignType": { "type": "string", "enum": [ "manual", "autobidding", "exclusive" ], "title": "CampaignType", "description": "The bidding method for the campaign." }, "Advanced_APIs_CampaignsListDimension": { "type": "string", "enum": [ "campaign_id", "name", "daily_budget", "impressions", "purchase_revenue", "roas", "cpc", "cpm", "ad_spend", "is_active", "ad_format", "start_date", "end_date", "created_at", "ctr", "conversion_rate", "purchase_count", "charged_clicks", "charged_impressions" ], "title": "CampaignsListDimension", "description": "The dimension to order the list of vendors." }, "Advanced_APIs_CatalogVendor": { "properties": { "id": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Id", "description": "Unique ID of the vendor. Topsort treats IDs as strings, choose any format as long as it is unique within the catalog.", "examples": [ "9SiwYqqL8vdG", "VENDOR-456", "5c30432c-1186-4389-a2f1-577bb8dd5180" ] }, "name": { "type": "string", "minLength": 1, "title": "Name", "description": "Name of the Vendor. Shown in Topsort UI. Truncated to 150 characters.", "examples": [ "Huyghe Brewery", "Sneakers Inc.", "Electronics International" ] }, "imageURL": { "format": "uri", "title": "Imageurl", "description": "URL of the vendor image. This image will be displayed in the Topsort UI along with the name of the vendor. Image dimensions between 250x250 and 600x600 pixels are recommended for the best performance of the Topsort UI.", "examples": [ "https://cdn.example.com/logos/9SiwYqqL8vdG.jpg" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "vendor_role": { "description": "Role of the vendor in the Topsort UI. Defaults to admin. Vendors with the admin role have full control to manage and set up their own campaigns. Vendors with the analytics role have read-only access to campaigns and reporting but require the marketplace admin to manage their campaigns.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_UserServiceVendorRole" }, { "type": "null" } ] }, "merchant_center_id": { "title": "Merchant Center Id", "description": "The Google Merchant Center ID.", "examples": [ 1456723 ], "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "globalId": { "title": "Globalid", "description": "Global identifier for grouping vendors across marketplaces.", "examples": [ "vendor_group_123", "global_brand_abc", "multi_marketplace_xyz" ], "oneOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "name" ], "title": "CatalogVendor", "description": "A vendor is a brand or other entity that promotes products in campaigns." }, "Advanced_APIs_CategoriesByIdRequest": { "properties": { "ids": { "items": { "type": "string", "maxLength": 255, "minLength": 1 }, "type": "array", "maxItems": 500, "minItems": 1, "title": "Ids", "description": "The IDs of the categories to delete.", "examples": [ [ "CAT-434", "CAT-231" ], [ "e5fde3c3-7562-43aa-9388-8376a55f9578" ] ] } }, "type": "object", "required": [ "ids" ], "title": "CategoriesByIdRequest" }, "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_CategoriesRequest": { "properties": { "categories": { "items": { "$ref": "#/components/schemas/Advanced_APIs_Category" }, "type": "array", "maxItems": 500, "minItems": 1, "title": "Categories", "description": "Categories to upsert. New categories will be created, and existing ones will be fully replaced with the provided data." } }, "type": "object", "required": [ "categories" ], "title": "CategoriesRequest" }, "Advanced_APIs_CategoriesResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "response": { "items": { "$ref": "#/components/schemas/Advanced_APIs_Category" }, "type": "array", "title": "Response", "description": "Array of categories. Empty when the catalog contains no categories." } }, "type": "object", "required": [ "hasMore", "response" ], "title": "CategoriesResponse" }, "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.\n\nIdeal for category product listing pages.\nNot allowed for banner ads." }, "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_Category": { "properties": { "id": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Id", "description": "Unique ID of the category. Topsort treats IDs as strings, choose any format as long as it is unique within the catalog.", "examples": [ "ahEDqV5uhjj8", "CAT-343", "52c8c83c-2f4f-4873-87a0-1ccd88273b27" ] }, "name": { "type": "string", "minLength": 1, "title": "Name", "description": "Category name. Shown in Topsort UI. Truncated to 150 characters.", "examples": [ "Beers/Belgian", "Sneakers", "SALE" ] }, "parentId": { "title": "Parentid", "description": "Deprecated. Use `path` instead. ID of the parent category. Each category can have at most one parent category, allowing categories to be organized into hierarchies.", "deprecated": true, "examples": [ "CAT-434", "e5fde3c3-7562-43aa-9388-8376a55f9578" ], "oneOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ] }, "path": { "title": "Path", "description": "A dot-separated string representing this category's location in the hierarchy. A child category's path is formed by appending its own identifier to its parent's path. For example, if 'clothing' has path 'apparel.clothing', its child 'dresses' would have path 'apparel.clothing.dresses'. Each segment may only contain A-Za-z0-9_.", "examples": [ "apparel_and_accessories.clothing.dresses" ], "oneOf": [ { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9_-]+(\\.[A-Za-z0-9_-]+)*$" }, { "type": "null" } ] }, "globalId": { "title": "Globalid", "description": "Global ID of the category. This is an optional field that can be used to link the category to other marketplaces.", "examples": [ "CAT-12345", "CAT-67890" ], "oneOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ] }, "metadata": { "title": "Metadata", "description": "Additional metadata for the category.", "examples": [ { "description": "All drinks available in the marketplace.", "globalName": "Beers", "path": "Driks/Alcoholic/Beers", "showInStore": true } ], "oneOf": [ { "additionalProperties": { "oneOf": [ { "type": "integer" }, { "type": "number" }, { "type": "string" }, { "type": "boolean" }, { "type": "null" } ] }, "type": "object", "maxProperties": 20 }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "name" ], "title": "Category", "description": "Categories provide a way to organize your catalog.\n\nProducts always belong to at least one category, but can belong to more. Categories can be organized into hierarchies." }, "Advanced_APIs_CategoryOrSearchSlotCreateRequest": { "properties": { "slotId": { "type": "string", "minLength": 1, "pattern": "^[\\w!\\\"#$%&'()*+,\\-._/:;<>?@\\[\\]^\\{\\}~=\\\\]*$", "title": "Slotid", "description": "The unique external slot ID that represents the slot.", "examples": [ "sidebar-2" ] }, "dimensions": { "$ref": "#/components/schemas/Advanced_APIs_SlotCreateRequestDimensions", "description": "The dimensions of the slot per device type." }, "position": { "type": "string", "enum": [ "category", "search" ], "title": "Position" } }, "type": "object", "required": [ "slotId", "dimensions", "position" ], "title": "CategoryOrSearchSlotCreateRequest", "description": "Category or search slot create request." }, "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.\n\nIdeal for category product listing pages." }, "Advanced_APIs_CategoryValue": { "properties": { "categoryId": { "type": "string", "title": "Categoryid", "description": "The ID of the category." } }, "type": "object", "required": [ "categoryId" ], "title": "CategoryValue" }, "Advanced_APIs_Channel": { "type": "string", "enum": [ "campaign:create", "campaign:update", "campaign:delete", "catalog:feed:download:finish", "store:availability:download:finish", "catalog:feed:upload:late", "full:availability:upload:late", "delta:availability:upload:late" ], "title": "Channel" }, "Advanced_APIs_ChargeType": { "type": "string", "enum": [ "CPM", "CPC", "CPA" ], "title": "ChargeType", "description": "Campaign charge type.\n\nCPM: cost per mille impressions\nCPC: cost per click\nCPA: cost per action. CPA reflects the total cost to achieve a conversion." }, "Advanced_APIs_CollectionCreateRequest": { "properties": { "name": { "type": "string", "maxLength": 64, "title": "Name", "description": "The name of the collection." }, "description": { "title": "Description", "description": "A description for the collection.", "oneOf": [ { "type": "string", "maxLength": 400 }, { "type": "null" } ] } }, "type": "object", "required": [ "name" ], "title": "CollectionCreateRequest" }, "Advanced_APIs_CollectionResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "The id of the collection." }, "name": { "type": "string", "title": "Name", "description": "The name of the collection." }, "description": { "title": "Description", "description": "A description for the collection.", "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "name" ], "title": "CollectionResponse" }, "Advanced_APIs_CollectionUpdateRequest": { "properties": { "name": { "title": "Name", "description": "The name of the collection.", "oneOf": [ { "type": "string", "maxLength": 64, "pattern": "^[^<>/\\\\]+$" }, { "type": "null" } ] }, "description": { "title": "Description", "description": "A description for the collection.", "oneOf": [ { "type": "string", "maxLength": 400, "pattern": "^[^<>]+$" }, { "type": "null" } ] } }, "type": "object", "title": "CollectionUpdateRequest" }, "Advanced_APIs_CollectionsResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "collections": { "items": { "$ref": "#/components/schemas/Advanced_APIs_CollectionResponse" }, "type": "array", "title": "Collections", "description": "An array of collections." } }, "type": "object", "required": [ "hasMore", "collections" ], "title": "CollectionsResponse" }, "Advanced_APIs_CreateAdvertiserRequestPublic": { "properties": { "vendorId": { "type": "string", "title": "Vendorid", "description": "The vendor ID that is going to be onboarded." }, "dsp": { "$ref": "#/components/schemas/Advanced_APIs_PublicDsp", "description": "The Demand-Side Platform (DSP) associated with the campaign" }, "billingMode": { "description": "The billing mode for the vendor. Will default to the marketplace config if not provided.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_VendorBillingMode" }, { "type": "null" } ] } }, "type": "object", "required": [ "vendorId", "dsp" ], "title": "CreateAdvertiserRequestPublic" }, "Advanced_APIs_CreateExclusiveListingBid": { "properties": { "target": { "$ref": "#/components/schemas/Advanced_APIs_Entity" }, "triggers": { "items": { "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_CategoryTrigger" }, { "$ref": "#/components/schemas/Advanced_APIs_KeywordTrigger-Input" }, { "$ref": "#/components/schemas/Advanced_APIs_ProductTrigger" } ], "description": "When should this bid participate in an auction.", "discriminator": { "propertyName": "type", "mapping": { "category": "#/components/schemas/Advanced_APIs_CategoryTrigger", "keyword": "#/components/schemas/Advanced_APIs_KeywordTrigger-Input", "product": "#/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." } }, "type": "object", "required": [ "target", "triggers" ], "title": "CreateExclusiveListingBid" }, "Advanced_APIs_CreateOffsiteCampaignRequest": { "properties": { "dsps": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicDsp" }, "type": "array", "minItems": 1, "title": "Dsps", "description": "The DSPs to create the campaign for.", "examples": [ [ "google_ads", "meta" ] ] }, "name": { "type": "string", "maxLength": 35, "pattern": "^[^;\"'<>\\#\\|,\\\r\\\n\\\\]*[^;\"'<>\\#\\|,\\\r\\\n\\\\\\s][^;\"'<>\\#\\|,\\\r\\\n\\\\]*$", "title": "Name", "description": "The name of the campaign" }, "startDate": { "type": "string", "format": "date-time", "title": "Startdate", "description": "The start date of the campaign" }, "endDate": { "type": "string", "format": "date-time", "title": "Enddate", "description": "The end date of the campaign" }, "budget": { "type": "integer", "exclusiveMaximum": 2000000000, "exclusiveMinimum": 0, "format": "int64", "title": "Budget", "description": "The daily budget in minor units of currency according to ISO 4217.", "examples": [ 1000 ] }, "targetRoas": { "type": "number", "maximum": 20, "minimum": 1, "title": "Targetroas", "description": "Target ROAS of the campaign. Acceptable values are between 1.0 and 20.0. Topsort maps this value to the closest equivalent bidding configuration supported by each DSP.", "examples": [ 3 ] }, "locationIds": { "items": { "type": "string" }, "type": "array", "minItems": 1, "title": "Locationids", "description": "The DSP-native location IDs to target. Retrieve available IDs via GET /offsite-ads/marketplace/geolocations and use the values from dspLocationIds for the target DSP. Reference: Google Ads geo targets (https://developers.google.com/google-ads/api/data/geotargets), Meta region IDs (https://developers.facebook.com/docs/marketing-api/audiences/reference/targeting-search#regions).", "examples": [ [ "123456" ] ] }, "productIds": { "title": "Productids", "description": "The product ids to target. These are the product ids from the catalog. If not provided, all products will be targeted.", "examples": [ [ "prod1", "prod2", "prod3", "prod4", "prod5" ] ], "oneOf": [ { "items": { "type": "string" }, "type": "array", "minItems": 5 }, { "type": "null" } ] }, "audienceIds": { "title": "Audienceids", "description": "The audience ids to target. These are the audience ids from each DSP platform. Currently, only one audience is supported. If not provided, no audience will be targeted.", "examples": [ [ "123456" ] ], "oneOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 1 }, { "type": "null" } ] } }, "type": "object", "required": [ "dsps", "name", "startDate", "endDate", "budget", "targetRoas", "locationIds" ], "title": "CreateOffsiteCampaignRequest" }, "Advanced_APIs_CreatePresignedUrlResponse": { "properties": { "url": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Url", "description": "The presigned URL." } }, "type": "object", "required": [ "url" ], "title": "CreatePresignedUrlResponse" }, "Advanced_APIs_CreateWalletRequest": { "properties": { "name": { "type": "string", "maxLength": 32, "minLength": 1, "title": "Name", "description": "Name of the wallet" } }, "type": "object", "required": [ "name" ], "title": "CreateWalletRequest" }, "Advanced_APIs_CreateWalletResponse": { "properties": { "walletId": { "type": "string", "format": "uuid", "title": "Walletid" } }, "type": "object", "required": [ "walletId" ], "title": "CreateWalletResponse" }, "Advanced_APIs_DailyKpis": { "properties": { "adSpend": { "type": "integer", "minimum": 0, "title": "Adspend", "description": "Amount spent on ads during the selected period in minor units of currency." }, "cpc": { "type": "number", "title": "Cpc", "description": "Average cost per click during the selected period." }, "cpm": { "type": "number", "title": "Cpm", "description": "Average cost per thousand impressions during the selected period.", "default": 0 }, "ctr": { "type": "number", "title": "Ctr", "description": "The click through rate during the selected period." }, "conversionRate": { "type": "number", "title": "Conversionrate", "description": "The conversion rate during the selected period." }, "impressions": { "type": "integer", "minimum": 0, "title": "Impressions", "description": "Number of impressions during the selected period." }, "chargedImpressions": { "type": "integer", "minimum": 0, "title": "Chargedimpressions", "description": "Amount of charged impressions during the selected period." }, "clicks": { "type": "integer", "minimum": 0, "title": "Clicks", "description": "Number of clicks during the selected period." }, "chargedClicks": { "type": "integer", "minimum": 0, "title": "Chargedclicks", "description": "Amount of charged clicks during the selected period." }, "purchaseCount": { "type": "integer", "minimum": 0, "title": "Purchasecount", "description": "Number of purchases during the selected period." }, "purchaseRevenue": { "type": "integer", "minimum": 0, "title": "Purchaserevenue", "description": "Revenue from promoted sales during the selected period in minor units of currency." }, "roas": { "type": "number", "title": "Roas", "description": "The return on ad spend during the selected period." }, "acos": { "type": "number", "title": "Acos", "description": "Advertising cost of sales (inverse of ROAS) during the selected period.", "default": 0 }, "timegroup": { "type": "string", "format": "date", "title": "Timegroup", "description": "Timegroup for the Kpis." } }, "type": "object", "required": [ "adSpend", "cpc", "ctr", "conversionRate", "impressions", "chargedImpressions", "clicks", "chargedClicks", "purchaseCount", "purchaseRevenue", "roas", "timegroup" ], "title": "DailyKpis", "description": "Response for analytics kpis." }, "Advanced_APIs_DailyReportData": { "properties": { "impressions": { "$ref": "#/components/schemas/Advanced_APIs_Events", "description": "How many impressions are attributed to this report item." }, "clicks": { "$ref": "#/components/schemas/Advanced_APIs_Events", "description": "How many clicks are attributed to this report item." }, "purchases": { "$ref": "#/components/schemas/Advanced_APIs_Purchases", "description": "How many purchases are attributed to this report item." }, "date": { "type": "string", "format": "date", "title": "Date", "description": "The date for this aggregation." } }, "type": "object", "required": [ "impressions", "clicks", "purchases", "date" ], "title": "DailyReportData", "description": "Clicks, impressions and purchases attributed to this report item so far, for a particular date." }, "Advanced_APIs_DailyReportResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "reports": { "items": { "$ref": "#/components/schemas/Advanced_APIs_DailyReportData" }, "type": "array", "title": "Reports", "description": "A list with report data aggregated by day." } }, "type": "object", "required": [ "hasMore", "reports" ], "title": "DailyReportResponse", "description": "Response for daily aggregation reports." }, "Advanced_APIs_DayOfWeek": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7 ], "title": "DayOfWeek", "description": "The day of the week." }, "Advanced_APIs_DeviceType": { "type": "string", "enum": [ "mobile", "desktop" ], "title": "DeviceType", "description": "The device where a banner ad should appear." }, "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." }, "Advanced_APIs_DspOnboardingStatus": { "properties": { "dsp": { "$ref": "#/components/schemas/Advanced_APIs_PublicDsp", "description": "The Demand-Side Platform (DSP) associated with the campaign" }, "status": { "$ref": "#/components/schemas/Advanced_APIs_OnboardingStatus", "description": "The onboarding status for each DSP." }, "lastUpdated": { "type": "string", "format": "date-time", "title": "Lastupdated", "description": "When the status was last updated." } }, "type": "object", "required": [ "dsp", "status", "lastUpdated" ], "title": "DspOnboardingStatus" }, "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_Events": { "properties": { "total": { "type": "integer", "format": "int64", "title": "Total", "description": "Total number of events." }, "charged": { "type": "integer", "format": "int64", "title": "Charged", "description": "Number of charged events." }, "adSpent": { "type": "integer", "format": "int64", "title": "Adspent", "description": "Ad spent over a period of time, in minor units of currency according to ISO 4217." }, "adSpentDecimal": { "title": "Adspentdecimal", "description": "Ad spent over a period of time.", "oneOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ] } }, "type": "object", "required": [ "total", "charged", "adSpent" ], "title": "Events", "description": "Aggregation of events." }, "Advanced_APIs_ExclusiveCampaignChargeType": { "type": "string", "enum": [ "DAILY" ], "title": "ExclusiveCampaignChargeType", "description": "Charge types for exclusive campaigns." }, "Advanced_APIs_FileAgencyDailyKPIsByProductResponse": { "properties": { "files": { "items": { "$ref": "#/components/schemas/Advanced_APIs_FileReportAgencyDailyKPIsByProductUrl" }, "type": "array", "title": "Files" } }, "type": "object", "required": [ "files" ], "title": "FileAgencyDailyKPIsByProductResponse" }, "Advanced_APIs_FileReportAgencyDailyKPIsByProductUrl": { "properties": { "date": { "type": "string", "format": "date", "title": "Date", "description": "The date associated with the agency data dump in ISO format (YYYY-MM-DD)" }, "fileUrl": { "type": "string", "title": "Fileurl", "description": "The signed URL from AWS S3 to download the agency daily kpis by product data dump for the corresponding date" } }, "type": "object", "required": [ "date", "fileUrl" ], "title": "FileReportAgencyDailyKPIsByProductUrl" }, "Advanced_APIs_FileReportInteractionsResponse": { "properties": { "files": { "items": { "$ref": "#/components/schemas/Advanced_APIs_FileReportInteractionsUrl" }, "type": "array", "title": "Files" } }, "type": "object", "required": [ "files" ], "title": "FileReportInteractionsResponse" }, "Advanced_APIs_FileReportInteractionsUrl": { "properties": { "date": { "type": "string", "format": "date", "title": "Date", "description": "The date associated with the interactions data dump in ISO format (YYYY-MM-DD)" }, "fileUrl": { "type": "string", "title": "Fileurl", "description": "The signed URL from AWS S3 to download the interactions data dump for the corresponding date" } }, "type": "object", "required": [ "date", "fileUrl" ], "title": "FileReportInteractionsUrl" }, "Advanced_APIs_FileReportScoredAttributionResponse": { "properties": { "files": { "items": { "$ref": "#/components/schemas/Advanced_APIs_FileReportScoredAttributionUrl" }, "type": "array", "title": "Files" } }, "type": "object", "required": [ "files" ], "title": "FileReportScoredAttributionResponse" }, "Advanced_APIs_FileReportScoredAttributionUrl": { "properties": { "date": { "type": "string", "format": "date", "title": "Date", "description": "The date associated with the scored attribution data dump in ISO format (YYYY-MM-DD)" }, "fileUrl": { "type": "string", "title": "Fileurl", "description": "The signed URL from AWS S3 to download the scored attribution data dump for the corresponding date" } }, "type": "object", "required": [ "date", "fileUrl" ], "title": "FileReportScoredAttributionUrl" }, "Advanced_APIs_FrequencyType": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "title": "FrequencyType" }, "Advanced_APIs_GetAgencyCampaignBidsResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "bids": { "items": { "$ref": "#/components/schemas/Advanced_APIs_TargetWithBid" }, "type": "array", "title": "Bids", "description": "List of targets with bids for the campaign" } }, "type": "object", "required": [ "hasMore", "bids" ], "title": "GetAgencyCampaignBidsResponse" }, "Advanced_APIs_GetBalanceResponse": { "properties": { "currencyCode": { "type": "string", "title": "Currencycode" }, "balance": { "type": "number", "title": "Balance" } }, "type": "object", "required": [ "currencyCode", "balance" ], "title": "GetBalanceResponse", "description": "Response body for the Vendor Balance fetch." }, "Advanced_APIs_GetJsonTemplatesResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "jsonTemplates": { "items": { "$ref": "#/components/schemas/Advanced_APIs_JsonTemplate" }, "type": "array", "title": "Jsontemplates" } }, "type": "object", "required": [ "hasMore", "jsonTemplates" ], "title": "GetJsonTemplatesResponse" }, "Advanced_APIs_GetPublicAgencyCampaignsResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "campaigns": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicAgencyCampaign" }, "type": "array", "title": "Campaigns", "description": "List of campaigns that belong to the agency" } }, "type": "object", "required": [ "hasMore", "campaigns" ], "title": "GetPublicAgencyCampaignsResponse" }, "Advanced_APIs_GetPublicAgencyProductsResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "products": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicAgencyProduct" }, "type": "array", "title": "Products", "description": "List of products that belong to the agency" } }, "type": "object", "required": [ "hasMore", "products" ], "title": "GetPublicAgencyProductsResponse" }, "Advanced_APIs_GetSlotsRequest": { "properties": { "orderBy": { "items": { "$ref": "#/components/schemas/Advanced_APIs_SlotOrderByClause" }, "type": "array", "title": "Orderby", "description": "The fields to sort the results by." } }, "type": "object", "required": [ "orderBy" ], "title": "GetSlotsRequest" }, "Advanced_APIs_GlobalCatalogProductKpi": { "properties": { "adSpend": { "type": "integer", "minimum": 0, "title": "Adspend", "description": "Amount spent on ads during the selected period in minor units of currency." }, "cpc": { "type": "number", "title": "Cpc", "description": "Average cost per click during the selected period." }, "cpm": { "type": "number", "title": "Cpm", "description": "Average cost per thousand impressions during the selected period.", "default": 0 }, "ctr": { "type": "number", "title": "Ctr", "description": "The click through rate during the selected period." }, "conversionRate": { "type": "number", "title": "Conversionrate", "description": "The conversion rate during the selected period." }, "impressions": { "type": "integer", "minimum": 0, "title": "Impressions", "description": "Number of impressions during the selected period." }, "chargedImpressions": { "type": "integer", "minimum": 0, "title": "Chargedimpressions", "description": "Amount of charged impressions during the selected period." }, "clicks": { "type": "integer", "minimum": 0, "title": "Clicks", "description": "Number of clicks during the selected period." }, "chargedClicks": { "type": "integer", "minimum": 0, "title": "Chargedclicks", "description": "Amount of charged clicks during the selected period." }, "purchaseCount": { "type": "integer", "minimum": 0, "title": "Purchasecount", "description": "Number of purchases during the selected period." }, "purchaseRevenue": { "type": "integer", "minimum": 0, "title": "Purchaserevenue", "description": "Revenue from promoted sales during the selected period in minor units of currency." }, "roas": { "type": "number", "title": "Roas", "description": "The return on ad spend during the selected period." }, "acos": { "type": "number", "title": "Acos", "description": "Advertising cost of sales (inverse of ROAS) during the selected period.", "default": 0 }, "ean": { "type": "string", "title": "Ean", "description": "The ean of the product. Global catalog identifier." }, "totalPurchaseQuantity": { "type": "integer", "minimum": 0, "title": "Totalpurchasequantity", "description": "Number of purchases during the selected period." }, "productName": { "type": "string", "title": "Productname", "description": "The name of the product." }, "imageUrl": { "title": "Imageurl", "description": "The url of the product image.", "oneOf": [ { "type": "string", "minLength": 1, "format": "uri" }, { "type": "null" } ] }, "isActive": { "type": "boolean", "title": "Isactive", "description": "Whether this product is active." } }, "type": "object", "required": [ "adSpend", "cpc", "ctr", "conversionRate", "impressions", "chargedImpressions", "clicks", "chargedClicks", "purchaseCount", "purchaseRevenue", "roas", "ean", "totalPurchaseQuantity", "productName", "imageUrl", "isActive" ], "title": "GlobalCatalogProductKpi" }, "Advanced_APIs_GlobalCatalogProductKpisResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "products": { "items": { "$ref": "#/components/schemas/Advanced_APIs_GlobalCatalogProductKpi" }, "type": "array", "title": "Products" } }, "type": "object", "required": [ "hasMore", "products" ], "title": "GlobalCatalogProductKpisResponse" }, "Advanced_APIs_HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/Advanced_APIs_ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "Advanced_APIs_IntRange": { "properties": { "lowerBound": { "title": "Lowerbound", "description": "The lower bound of the size range.", "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "upperBound": { "title": "Upperbound", "description": "The upper bound of the size range.", "oneOf": [ { "type": "integer" }, { "type": "null" } ] } }, "type": "object", "required": [ "lowerBound", "upperBound" ], "title": "IntRange" }, "Advanced_APIs_InteractionReportEntry": { "properties": { "vendorId": { "type": "string", "title": "Vendorid", "description": "The unique identifier of the vendor" }, "campaignId": { "title": "Campaignid", "description": "The unique identifier of the campaign, if applicable", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "title": "Productid", "description": "The unique identifier of the product, if applicable", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "The date and time when these interactions occurred" }, "impressions": { "type": "integer", "title": "Impressions", "description": "Total number of times the ad was displayed" }, "clicks": { "type": "integer", "title": "Clicks", "description": "Total number of times the ad was clicked" }, "chargedClicks": { "type": "integer", "title": "Chargedclicks", "description": "Number of clicks that were charged to the advertiser" }, "adSpentClicks": { "type": "integer", "title": "Adspentclicks", "description": "Number of clicks that contributed to ad spend" }, "chargedImpressions": { "type": "integer", "title": "Chargedimpressions", "description": "Number of impressions that were charged to the advertiser" }, "adSpentImpressions": { "type": "integer", "title": "Adspentimpressions", "description": "Number of impressions that contributed to ad spend" }, "totalPurchaseAmount": { "type": "integer", "title": "Totalpurchaseamount", "description": "Total revenue from purchases in minor units of currency" }, "totalPurchaseQuantity": { "type": "integer", "title": "Totalpurchasequantity", "description": "Total number of items purchased" }, "totalPurchaseCount": { "type": "integer", "title": "Totalpurchasecount", "description": "Total number of purchase transactions" }, "adSpentExclusiveCampaign": { "type": "integer", "title": "Adspentexclusivecampaign", "description": "Amount spent on exclusive campaign interactions" }, "chargedAttributedPurchases": { "type": "integer", "title": "Chargedattributedpurchases", "description": "Number of purchases attributed to charged interactions" }, "adSpentAttributedPurchases": { "type": "integer", "title": "Adspentattributedpurchases", "description": "Number of purchases attributed to ad spend interactions" } }, "type": "object", "required": [ "vendorId", "timestamp", "impressions", "clicks", "chargedClicks", "adSpentClicks", "chargedImpressions", "adSpentImpressions", "totalPurchaseAmount", "totalPurchaseQuantity", "totalPurchaseCount", "adSpentExclusiveCampaign", "chargedAttributedPurchases", "adSpentAttributedPurchases" ], "title": "InteractionReportEntry", "description": "Detailed interaction data for a specific entity (vendor, campaign, or product) at a given timestamp." }, "Advanced_APIs_InteractionType": { "type": "string", "enum": [ "impressions", "clicks", "conversions" ], "title": "InteractionType" }, "Advanced_APIs_InteractionsGranularity": { "type": "string", "enum": [ "daily", "hourly" ], "title": "InteractionsGranularity" }, "Advanced_APIs_InteractionsGroupBy": { "type": "string", "enum": [ "vendor", "campaign", "product" ], "title": "InteractionsGroupBy" }, "Advanced_APIs_InteractionsReportResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "interactions": { "items": { "$ref": "#/components/schemas/Advanced_APIs_InteractionReportEntry" }, "type": "array", "title": "Interactions", "description": "List of interaction report entries, each containing detailed metrics for a specific entity and timestamp." } }, "type": "object", "required": [ "hasMore", "interactions" ], "title": "InteractionsReportResponse", "description": "Unified response model for both daily and hourly interactions reports.\n\nContains a list of interaction entries, each representing detailed metrics for a specific entity\n(vendor, campaign, or product) at a given timestamp. The response is paginated to handle large datasets." }, "Advanced_APIs_JobDetailsResponse": { "properties": { "jobId": { "type": "string", "format": "uuid", "title": "Jobid", "description": "The unique identifier for the queued job." }, "requestType": { "$ref": "#/components/schemas/Advanced_APIs_RequestType", "description": "The type of operation the job represents." }, "status": { "$ref": "#/components/schemas/Advanced_APIs_OffsiteJobStatus", "description": "The current status of the job." }, "dsp": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicAudienceSyncDsp" }, "type": "array", "title": "Dsp", "description": "The DSP(s) associated with the job." }, "result": { "title": "Result", "description": "Optional result data in json format (e.g., {error: 'error message'}).", "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "type": "object", "required": [ "jobId", "requestType", "status", "dsp" ], "title": "JobDetailsResponse" }, "Advanced_APIs_JobResponseBase": { "properties": { "jobId": { "type": "string", "format": "uuid", "title": "Jobid", "description": "The unique identifier for the queued job." } }, "type": "object", "required": [ "jobId" ], "title": "JobResponseBase" }, "Advanced_APIs_JsonTemplate": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "The ID of the JSON template" }, "marketplaceId": { "type": "string", "format": "uuid", "title": "Marketplaceid", "description": "The ID of the marketplace" }, "name": { "type": "string", "title": "Name", "description": "The name of the JSON template" }, "description": { "type": "string", "title": "Description", "description": "The description of the JSON template" }, "isArchived": { "type": "boolean", "title": "Isarchived", "description": "Whether the JSON template is archived", "default": false }, "previewScreenshot": { "title": "Previewscreenshot", "description": "Preview screenshot of the JSON template", "oneOf": [ { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri" }, { "type": "null" } ] }, "previewUrl": { "title": "Previewurl", "description": "Preview URL of the JSON template", "oneOf": [ { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri" }, { "type": "null" } ] }, "jsonSchema": { "additionalProperties": true, "type": "object", "title": "Jsonschema", "description": "The JSON schema of the JSON template" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat", "description": "The creation time of the JSON template" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat", "description": "The update time of the JSON template" }, "adFormat": { "$ref": "#/components/schemas/Advanced_APIs_JsonTemplateAdFormat", "description": "The ad format of the JSON template" } }, "type": "object", "required": [ "id", "marketplaceId", "name", "description", "jsonSchema", "createdAt", "updatedAt", "adFormat" ], "title": "JsonTemplate" }, "Advanced_APIs_JsonTemplateAdFormat": { "type": "string", "enum": [ "banner", "sponsored_brand" ], "title": "JsonTemplateAdFormat", "description": "The type of the ad format of the JSON template." }, "Advanced_APIs_JsonTemplateCreateRequest": { "properties": { "name": { "type": "string", "maxLength": 50, "minLength": 1, "title": "Name", "description": "Unique name of the JSON template" }, "description": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Description", "description": "Description of the JSON template" }, "previewScreenshot": { "title": "Previewscreenshot", "description": "Preview screenshot of the JSON template", "oneOf": [ { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri" }, { "type": "null" } ] }, "adFormat": { "description": "AdFormat this template is for", "default": "banner", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_JsonTemplateAdFormat" }, { "type": "null" } ] }, "previewUrl": { "title": "Previewurl", "description": "Preview URL of the JSON template", "oneOf": [ { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri" }, { "type": "null" } ] }, "jsonSchema": { "additionalProperties": true, "type": "object", "title": "Jsonschema", "description": "A JSON object that defines a schema according to draft-07 of the JSON Schema specification.", "examples": [ { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "title": { "maxLength": 100, "minLength": 1, "type": "string" } }, "required": [ "title" ], "type": "object" } ] } }, "type": "object", "required": [ "name", "description", "jsonSchema" ], "title": "JsonTemplateCreateRequest" }, "Advanced_APIs_JsonTemplateUpdateRequest": { "properties": { "name": { "title": "Name", "description": "Unique name of the JSON template", "oneOf": [ { "type": "string", "maxLength": 50, "minLength": 1 }, { "type": "null" } ] }, "description": { "title": "Description", "description": "Description of the JSON template", "oneOf": [ { "type": "string", "maxLength": 100, "minLength": 1 }, { "type": "null" } ] }, "previewScreenshot": { "title": "Previewscreenshot", "description": "Preview screenshot of the JSON template", "oneOf": [ { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri" }, { "type": "null" } ] }, "previewUrl": { "title": "Previewurl", "description": "Preview URL of the JSON template", "oneOf": [ { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri" }, { "type": "null" } ] }, "jsonSchema": { "title": "Jsonschema", "description": "The JSON schema of the JSON template", "oneOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ] } }, "type": "object", "title": "JsonTemplateUpdateRequest" }, "Advanced_APIs_KPIs": { "properties": { "reports": { "items": { "$ref": "#/components/schemas/Advanced_APIs_DailyKpis" }, "type": "array", "title": "Reports" } }, "type": "object", "required": [ "reports" ], "title": "KPIs" }, "Advanced_APIs_KeywordMatchType": { "type": "string", "enum": [ "exact", "phrase" ], "title": "KeywordMatchType" }, "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.\n\nIdeal for search results pages." }, "Advanced_APIs_KeywordTrigger-Output": { "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.\n\nIdeal for search results pages." }, "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_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_LandingPageSlotCreateRequestItem": { "properties": { "slotId": { "type": "string", "minLength": 1, "pattern": "^[\\w!\\\"#$%&'()*+,\\-._/:;<>?@\\[\\]^\\{\\}~=\\\\]*$", "title": "Slotid", "description": "The unique external slot ID that represents the slot.", "examples": [ "sidebar-2" ] }, "dimensions": { "$ref": "#/components/schemas/Advanced_APIs_SlotCreateRequestDimensions", "description": "The dimensions of the slot per device type." }, "position": { "type": "string", "const": "landing", "title": "Position", "default": "landing" }, "page": { "$ref": "#/components/schemas/Advanced_APIs_SlotCreateRequestPageItem", "description": "The landing page. The page is created if the page with the given name does not exist." } }, "type": "object", "required": [ "slotId", "dimensions", "page" ], "title": "LandingPageSlotCreateRequestItem", "description": "A list item describing the fields of the landing page slot to be created." }, "Advanced_APIs_LanguagePreference": { "type": "string", "enum": [ "en", "fr", "es", "pt", "ru", "ar-AE", "de", "ko" ], "title": "LanguagePreference" }, "Advanced_APIs_MediaDeviceType": { "type": "string", "enum": [ "desktop", "mobile" ], "title": "MediaDeviceType" }, "Advanced_APIs_Next": { "properties": { "offset": { "type": "integer", "format": "int32", "title": "Offset", "description": "How many items to skip from the beginning of the list." }, "limit": { "type": "integer", "format": "int32", "title": "Limit", "description": "How many items to return." } }, "type": "object", "required": [ "offset", "limit" ], "title": "Next" }, "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.\n\nIdeal for Landing pages." }, "Advanced_APIs_OffsiteCampaignStatus": { "type": "string", "enum": [ "ENABLED", "PAUSED" ], "title": "OffsiteCampaignStatus" }, "Advanced_APIs_OffsiteEvents": { "properties": { "total": { "type": "integer", "format": "int64", "title": "Total", "description": "Total number of events." }, "charged": { "type": "integer", "format": "int64", "title": "Charged", "description": "Number of charged events." }, "adSpent": { "type": "integer", "format": "int64", "title": "Adspent", "description": "Ad spent over a period of time, in minor units of currency according to ISO 4217." }, "adSpentDecimal": { "title": "Adspentdecimal", "description": "Ad spent over a period of time.", "oneOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ] } }, "type": "object", "required": [ "total", "charged", "adSpent" ], "title": "OffsiteEvents", "description": "Aggregation of events." }, "Advanced_APIs_OffsiteJobStatus": { "type": "string", "enum": [ "not_started", "in_progress", "completed", "failed", "retrying" ], "title": "OffsiteJobStatus" }, "Advanced_APIs_OffsitePurchases": { "properties": { "amount": { "type": "integer", "format": "int64", "title": "Amount", "description": "Amount of money made by purchases over a period of time, in minor units of currency according to ISO 4217." }, "count": { "type": "integer", "format": "int64", "title": "Count", "description": "Amount of purchase events." }, "quantity": { "type": "integer", "format": "int64", "title": "Quantity", "description": "Amount of items purchased." }, "countByProduct": { "title": "Countbyproduct", "description": "Purchase count by product. Available if `count_by_product` is set to `true`.", "oneOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ] } }, "type": "object", "required": [ "amount", "count", "quantity" ], "title": "OffsitePurchases", "description": "Aggregation of purchase events." }, "Advanced_APIs_OffsiteReportData": { "properties": { "impressions": { "$ref": "#/components/schemas/Advanced_APIs_OffsiteEvents", "description": "How many impressions are attributed to this report item." }, "clicks": { "$ref": "#/components/schemas/Advanced_APIs_OffsiteEvents", "description": "How many clicks are attributed to this report item." }, "purchases": { "$ref": "#/components/schemas/Advanced_APIs_OffsitePurchases", "description": "How many purchases are attributed to this report item." } }, "type": "object", "required": [ "impressions", "clicks", "purchases" ], "title": "OffsiteReportData", "description": "Clicks, impressions and purchases attributed to this report item so far." }, "Advanced_APIs_OfsiteCampaign": { "properties": { "campaignId": { "type": "string", "format": "uuid", "title": "Campaignid", "description": "The unique identifier of the campaign" }, "dsps": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicDsp" }, "type": "array", "minItems": 1, "title": "Dsps", "description": "The Demand-Side Platforms (DSPs) associated with the campaign", "examples": [ [ "google_ads", "meta" ] ] }, "name": { "type": "string", "title": "Name", "description": "The name of the campaign" }, "status": { "$ref": "#/components/schemas/Advanced_APIs_OffsiteCampaignStatus", "description": "The current status of the campaign" }, "startDate": { "type": "string", "format": "date-time", "title": "Startdate", "description": "The start date of the campaign" }, "endDate": { "type": "string", "format": "date-time", "title": "Enddate", "description": "The end date of the campaign" }, "budget": { "type": "integer", "title": "Budget", "description": "The daily budget allocated for the campaign in cents" }, "targetRoas": { "type": "number", "maximum": 20, "minimum": 1, "title": "Targetroas", "description": "Target ROAS of the campaign. Acceptable values are between 1.0 and 20.0. Topsort maps this value to the closest equivalent bidding configuration supported by each DSP.", "examples": [ 3 ] }, "audience": { "description": "The audience targeted by the campaign", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_PublicOffsiteAudience" }, { "type": "null" } ] } }, "type": "object", "required": [ "campaignId", "dsps", "name", "status", "startDate", "endDate", "budget", "targetRoas", "audience" ], "title": "OfsiteCampaign" }, "Advanced_APIs_OnboardingStatus": { "type": "string", "enum": [ "not_started", "in_progress", "completed", "failed" ], "title": "OnboardingStatus" }, "Advanced_APIs_PartialProductUpdate": { "properties": { "id": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Id", "description": "Unique ID of the product. Topsort treats IDs as strings, choose any format as long as it is unique within the catalog.", "examples": [ "eyGqR4YQgBJa", "PROD-548", "52c8c83c-2f4f-4873-87a0-1ccd88273b27" ] }, "name": { "title": "Name", "description": "Name of the product. Shown in Topsort UI. Truncated to 150 characters.", "examples": [ "Delirium Tremens Beer Bottle 330cc x6" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "description": { "title": "Description", "description": "Description of the product. Truncated to 5000 characters.", "examples": [ "Named as \"Best Beer in the World\" in 2008 at the World Beer Championships in Chicago, Illinois." ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "vendors": { "title": "Vendors", "description": "IDs of the vendors that can promote this product in campaigns. Empty or whitespace-only entries are ignored.", "examples": [ [ "9SiwYqqL8vdG", "BRAND-48795" ] ], "oneOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ] }, "brand": { "description": "Brand information of the product.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_Brand" }, { "type": "null" } ] }, "imageURL": { "format": "uri", "title": "Imageurl", "description": "URL of the product image. This image will be displayed in the Topsort UI. Image dimensions between 250x250 and 600x600 pixels are recommended for the best performance of the Topsort UI.", "examples": [ "https://cdn.example.com/products/eyGqR4YQgBJa.jpg" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "link": { "format": "uri", "title": "Link", "description": "The product's landing page. Needed for Google Ads integration.", "examples": [ "http://www.example.com/asp/sp.asp?cat=12&id=1030" ], "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "categories": { "title": "Categories", "description": "IDs of the categories this product belongs to. Empty or whitespace-only entries are ignored.", "examples": [ [ "ahEDqV5uhjj8" ], [ "CAT-343", "CAT-456" ], [ "52c8c83c-2f4f-4873-87a0-1ccd88273b27" ] ], "oneOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ] }, "price": { "title": "Price", "description": "Price of the product in the currency configured in the marketplace.", "examples": [ 18.99, 0.15, 1999.95 ], "oneOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "active": { "title": "Active", "description": "Flag that indicates whether this product is active. Only active products can take part in campaigns and auctions. Set this value to `false` to deactivate a product. When a product is deactivated it will be removed from active campaigns. \n We advise to set this flag to `false` when a product is out of stock.", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "ean": { "title": "Ean", "description": "European Article Number. Formatted as a thirteen digit EAN-13 code. An empty or whitespace-only value is treated as no value (null).", "examples": [ "4003994155486" ], "oneOf": [ { "type": "string", "maxLength": 13, "minLength": 13 }, { "type": "null" } ] }, "quality_score": { "title": "Quality Score", "description": "Marketplace's internal quality score for the product. This in an optional advanced use case, for which we can provide some insights. Examples of metrics include the product's rating, conversion rate, click through rate, combination of other metrics, etc.", "oneOf": [ { "type": "number", "maximum": 1, "exclusiveMinimum": 0 }, { "type": "null" } ] }, "metadata": { "title": "Metadata", "description": "Additional metadata for the product.", "oneOf": [ { "additionalProperties": { "oneOf": [ { "type": "integer" }, { "type": "number" }, { "type": "string" }, { "type": "boolean" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ] }, "globalId": { "title": "Globalid", "description": "Global ID of the product. This is an optional field that can be used to link the product to other marketplaces", "examples": [ "PROD-12345", "PROD-67890" ], "oneOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ] }, "variantIds": { "title": "Variantids", "description": "Alternative IDs of this product.", "examples": [ [ "eyGqR4YQgBJa", "PROD-548", "52c8c83c-2f4f-4873-87a0-1ccd88273b27" ], null ], "oneOf": [ { "items": { "type": "string", "maxLength": 255, "minLength": 1 }, "type": "array", "maxItems": 20 }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "title": "PartialProductUpdate", "description": "A product is the minimum unit that can be sold within a marketplace catalog." }, "Advanced_APIs_PatchSlotsRequest": { "properties": { "isActive": { "type": "boolean", "title": "Isactive", "description": "Set is_active to true to activate the slot, or false to deactivate it." } }, "type": "object", "required": [ "isActive" ], "title": "PatchSlotsRequest" }, "Advanced_APIs_PositionType": { "type": "string", "enum": [ "landing", "category_search", "category", "search" ], "title": "PositionType" }, "Advanced_APIs_Product": { "properties": { "id": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Id", "description": "Unique ID of the product. Topsort treats IDs as strings, choose any format as long as it is unique within the catalog.", "examples": [ "eyGqR4YQgBJa", "PROD-548", "52c8c83c-2f4f-4873-87a0-1ccd88273b27" ] }, "name": { "type": "string", "minLength": 1, "title": "Name", "description": "Name of the product. Shown in Topsort UI. Truncated to 150 characters.", "examples": [ "Delirium Tremens Beer Bottle 330cc x6" ] }, "description": { "title": "Description", "description": "Description of the product. Truncated to 5000 characters.", "examples": [ "Named as \"Best Beer in the World\" in 2008 at the World Beer Championships in Chicago, Illinois." ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "vendors": { "items": { "type": "string", "maxLength": 255, "minLength": 1 }, "type": "array", "title": "Vendors", "description": "IDs of the vendors that can promote this product in campaigns. Empty or whitespace-only entries are ignored.", "examples": [ [ "9SiwYqqL8vdG", "BRAND-48795" ] ] }, "brand": { "description": "Brand information of the product.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_Brand" }, { "type": "null" } ] }, "imageURL": { "format": "uri", "title": "Imageurl", "description": "URL of the product image. This image will be displayed in the Topsort UI. Image dimensions between 250x250 and 600x600 pixels are recommended for the best performance of the Topsort UI.", "examples": [ "https://cdn.example.com/products/eyGqR4YQgBJa.jpg" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "categories": { "items": { "type": "string", "maxLength": 255, "minLength": 1 }, "type": "array", "title": "Categories", "description": "IDs of the categories this product belongs to. Empty or whitespace-only entries are ignored.", "examples": [ [ "ahEDqV5uhjj8" ], [ "CAT-343", "CAT-456" ], [ "52c8c83c-2f4f-4873-87a0-1ccd88273b27" ] ] }, "price": { "title": "Price", "description": "Price of the product in the currency configured in the marketplace.", "examples": [ 18.99, 0.15, 1999.95 ], "oneOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "active": { "type": "boolean", "title": "Active", "description": "Flag that indicates whether this product is active. Only active products can take part in campaigns and auctions. Set this value to `false` to deactivate a product. When a product is deactivated it will be removed from active campaigns. \n We advise to set this flag to `false` when a product is out of stock.", "default": true }, "ean": { "title": "Ean", "description": "European Article Number. Formatted as a thirteen digit EAN-13 code. An empty or whitespace-only value is treated as no value (null).", "examples": [ "4003994155486" ], "oneOf": [ { "type": "string", "maxLength": 13, "minLength": 13 }, { "type": "null" } ] }, "quality_score": { "title": "Quality Score", "description": "Marketplace's internal quality score for the product. This in an optional advanced use case, for which we can provide some insights. Examples of metrics include the product's rating, conversion rate, click through rate, combination of other metrics, etc.", "oneOf": [ { "type": "number", "maximum": 1, "exclusiveMinimum": 0 }, { "type": "null" } ] }, "metadata": { "title": "Metadata", "description": "Additional metadata for the product.", "oneOf": [ { "additionalProperties": { "oneOf": [ { "type": "integer" }, { "type": "number" }, { "type": "string" }, { "type": "boolean" }, { "type": "null" } ] }, "type": "object", "maxProperties": 20 }, { "type": "null" } ] }, "globalId": { "title": "Globalid", "description": "Global ID of the product. This is an optional field that can be used to link the product to other marketplaces", "examples": [ "PROD-12345", "PROD-67890" ], "oneOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ] }, "link": { "format": "uri", "title": "Link", "description": "The product's landing page. Needed for Google Ads integration.", "examples": [ "http://www.example.com/asp/sp.asp?cat=12&id=1030" ], "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "variantIds": { "title": "Variantids", "description": "Alternative IDs of this product.", "examples": [ [ "eyGqR4YQgBJa", "PROD-548", "52c8c83c-2f4f-4873-87a0-1ccd88273b27" ], null ], "oneOf": [ { "items": { "type": "string", "maxLength": 255, "minLength": 1 }, "type": "array", "maxItems": 20 }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "name", "vendors", "categories" ], "title": "Product", "description": "A product is the minimum unit that can be sold within a marketplace catalog." }, "Advanced_APIs_ProductKPIs": { "properties": { "adSpend": { "type": "integer", "minimum": 0, "title": "Adspend", "description": "Amount spent on ads during the selected period in minor units of currency." }, "cpc": { "type": "number", "title": "Cpc", "description": "Average cost per click during the selected period." }, "cpm": { "type": "number", "title": "Cpm", "description": "Average cost per thousand impressions during the selected period.", "default": 0 }, "ctr": { "type": "number", "title": "Ctr", "description": "The click through rate during the selected period." }, "conversionRate": { "type": "number", "title": "Conversionrate", "description": "The conversion rate during the selected period." }, "impressions": { "type": "integer", "minimum": 0, "title": "Impressions", "description": "Number of impressions during the selected period." }, "chargedImpressions": { "type": "integer", "minimum": 0, "title": "Chargedimpressions", "description": "Amount of charged impressions during the selected period." }, "clicks": { "type": "integer", "minimum": 0, "title": "Clicks", "description": "Number of clicks during the selected period." }, "chargedClicks": { "type": "integer", "minimum": 0, "title": "Chargedclicks", "description": "Amount of charged clicks during the selected period." }, "purchaseCount": { "type": "integer", "minimum": 0, "title": "Purchasecount", "description": "Number of purchases during the selected period." }, "purchaseRevenue": { "type": "integer", "minimum": 0, "title": "Purchaserevenue", "description": "Revenue from promoted sales during the selected period in minor units of currency." }, "roas": { "type": "number", "title": "Roas", "description": "The return on ad spend during the selected period." }, "acos": { "type": "number", "title": "Acos", "description": "Advertising cost of sales (inverse of ROAS) during the selected period.", "default": 0 }, "productId": { "type": "string", "title": "Productid", "description": "The id of the product whose report data we want to see" }, "quantity": { "type": "integer", "minimum": 0, "title": "Quantity", "description": "Number of purchased units during the selected period." } }, "type": "object", "required": [ "adSpend", "cpc", "ctr", "conversionRate", "impressions", "chargedImpressions", "clicks", "chargedClicks", "purchaseCount", "purchaseRevenue", "roas", "productId", "quantity" ], "title": "ProductKPIs", "description": "KPI data for a particular product within a specific campaign." }, "Advanced_APIs_ProductReportData": { "properties": { "impressions": { "$ref": "#/components/schemas/Advanced_APIs_OffsiteEvents", "description": "How many impressions are attributed to this report item." }, "clicks": { "$ref": "#/components/schemas/Advanced_APIs_OffsiteEvents", "description": "How many clicks are attributed to this report item." }, "purchases": { "$ref": "#/components/schemas/Advanced_APIs_OffsitePurchases", "description": "How many purchases are attributed to this report item." }, "productId": { "type": "string", "title": "Productid", "description": "The id of the product whose report data we want to see" } }, "type": "object", "required": [ "impressions", "clicks", "purchases", "productId" ], "title": "ProductReportData", "description": "KPI data for a particular product within a specific campaign." }, "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_ProductValue": { "properties": { "productId": { "type": "string", "title": "Productid", "description": "The ID of the product." } }, "type": "object", "required": [ "productId" ], "title": "ProductValue" }, "Advanced_APIs_ProductsByIdRequest": { "properties": { "ids": { "items": { "type": "string", "maxLength": 255, "minLength": 1 }, "type": "array", "maxItems": 500, "minItems": 1, "title": "Ids", "description": "Product IDs to delete. Deleted products will be removed from active campaigns.", "examples": [ [ "9UrUtEsUzLGL", "zhhGqczsuGHx" ] ] } }, "type": "object", "required": [ "ids" ], "title": "ProductsByIdRequest" }, "Advanced_APIs_ProductsInCampaignResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "productsInCampaign": { "items": { "type": "string" }, "type": "array", "title": "Productsincampaign", "description": "List of sponsored product ids." } }, "type": "object", "required": [ "hasMore", "productsInCampaign" ], "title": "ProductsInCampaignResponse", "description": "Scrolled response for products in campaign." }, "Advanced_APIs_ProductsRequest": { "properties": { "products": { "items": { "$ref": "#/components/schemas/Advanced_APIs_Product" }, "type": "array", "maxItems": 500, "minItems": 1, "title": "Products", "description": "The products to create or substitute." } }, "type": "object", "required": [ "products" ], "title": "ProductsRequest" }, "Advanced_APIs_ProductsResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "response": { "items": { "$ref": "#/components/schemas/Advanced_APIs_Product" }, "type": "array", "title": "Response", "description": "Array of products." } }, "type": "object", "required": [ "hasMore", "response" ], "title": "ProductsResponse" }, "Advanced_APIs_PublicAdFormat": { "type": "string", "enum": [ "listing", "banner" ], "title": "PublicAdFormat", "description": "Public campaign ad format filter options." }, "Advanced_APIs_PublicAdvertiserResponse": { "properties": { "vendorId": { "type": "string", "title": "Vendorid", "description": "The vendor ID that is going to be onboarded." }, "dspOnboardingStatus": { "$ref": "#/components/schemas/Advanced_APIs_DspOnboardingStatus", "description": "The onboarding status for each DSP." } }, "type": "object", "required": [ "vendorId", "dspOnboardingStatus" ], "title": "PublicAdvertiserResponse" }, "Advanced_APIs_PublicAgencyCampaign": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Internal identifier for the agency campaign" }, "name": { "type": "string", "title": "Name", "description": "Campaign name" }, "adFormat": { "$ref": "#/components/schemas/Advanced_APIs_AgencyCampaignType", "description": "The ad format for this campaign" }, "chargeType": { "$ref": "#/components/schemas/Advanced_APIs_ChargeType", "description": "The charge type for this campaign" }, "accountId": { "type": "string", "format": "uuid", "title": "Accountid", "description": "Account that owns this campaign" }, "budget": { "type": "integer", "title": "Budget", "description": "Total budget for this campaign" }, "bidCount": { "title": "Bidcount", "description": "Bid count for the campaign (optional)", "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "budgetPeriod": { "$ref": "#/components/schemas/Advanced_APIs_BudgetPeriodType", "description": "The periodicity of the budget" }, "startDate": { "type": "string", "format": "date-time", "title": "Startdate", "description": "Date when the campaign starts, specified in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6). Must include the Timezone definition." }, "endDate": { "type": "string", "format": "date-time", "title": "Enddate", "description": "Date when the campaign ends, specified in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6). Must include the Timezone definition." }, "targetRoas": { "type": "number", "maximum": 20, "minimum": 0.5, "title": "Targetroas", "description": "Target ROAS for the campaign" }, "currencyCode": { "type": "string", "title": "Currencycode", "description": "Currency code this campaign is working with in ISO 4217 format", "examples": [ "USD" ] }, "isActive": { "type": "boolean", "title": "Isactive", "description": "Flag to indicate if the campaign is active or not" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat", "description": "Date and time when the campaign was created" } }, "type": "object", "required": [ "id", "name", "adFormat", "chargeType", "accountId", "budget", "budgetPeriod", "startDate", "endDate", "targetRoas", "currencyCode", "isActive", "createdAt" ], "title": "PublicAgencyCampaign", "description": "Represents a public version of an agency campaign, used in API responses." }, "Advanced_APIs_PublicAgencyCampaignCreateRequest": { "properties": { "name": { "type": "string", "maxLength": 75, "minLength": 1, "title": "Name", "description": "Campaign name, this will be propagated to campaigns in marketplaces" }, "budget": { "type": "integer", "exclusiveMaximum": 20000000000, "exclusiveMinimum": 0, "title": "Budget", "description": "Total budget for this campaign, to be distributed across marketplaces" }, "budgetPeriod": { "$ref": "#/components/schemas/Advanced_APIs_BudgetPeriodType", "description": "The periodicity of the budget", "default": "daily" }, "targets": { "items": { "type": "string" }, "type": "array", "title": "Targets", "description": "List of targets for 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." }, "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" }, "targetRoas": { "type": "number", "maximum": 20, "minimum": 0.5, "title": "Targetroas", "description": "Target ROAS for the campaign" } }, "type": "object", "required": [ "name", "budget", "targets", "targetRoas" ], "title": "PublicAgencyCampaignCreateRequest" }, "Advanced_APIs_PublicAgencyCampaignUpdateRequest": { "properties": { "name": { "title": "Name", "description": "Campaign name, this will be propagated to campaigns in marketplaces", "oneOf": [ { "type": "string", "maxLength": 75, "minLength": 1 }, { "type": "null" } ] }, "budget": { "title": "Budget", "description": "Total budget for this campaign, to be distributed across marketplaces", "oneOf": [ { "type": "integer", "exclusiveMaximum": 20000000000, "exclusiveMinimum": 0 }, { "type": "null" } ] }, "targets": { "description": "Targets to be included or removed from the campaign", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_PublicUpdateTargets" }, { "type": "null" } ] }, "startDate": { "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.", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endDate": { "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. ", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "targetRoas": { "title": "Targetroas", "description": "Target ROAS for the campaign", "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "isActive": { "title": "Isactive", "description": "Flag to indicate if the campaign is active or not", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "type": "object", "title": "PublicAgencyCampaignUpdateRequest" }, "Advanced_APIs_PublicAgencyProduct": { "properties": { "id": { "type": "string", "title": "Id", "description": "Internal identifier for the agency product" }, "name": { "type": "string", "title": "Name", "description": "Product name" }, "description": { "type": "string", "title": "Description", "description": "Product description" }, "categories": { "items": { "type": "string" }, "type": "array", "title": "Categories", "description": "List of categories this product belongs to" }, "brands": { "items": { "type": "string" }, "type": "array", "title": "Brands", "description": "List of brands associated with this product" }, "images": { "items": { "type": "string", "minLength": 1, "format": "uri" }, "type": "array", "title": "Images", "description": "List of image URLs for this product" } }, "type": "object", "required": [ "id", "name", "description", "categories", "brands", "images" ], "title": "PublicAgencyProduct" }, "Advanced_APIs_PublicAudienceSyncDsp": { "type": "string", "enum": [ "google_ads", "meta", "tiktok_ads", "snapchat_ads" ], "title": "PublicAudienceSyncDsp", "description": "DSPs an offsite audience is synced to." }, "Advanced_APIs_PublicBidsResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Whether this is the last page of results or not." }, "next": { "description": "The parameters that should be used to fetch the next page.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_Next" }, { "type": "null" } ] }, "bids": { "items": { "$ref": "#/components/schemas/Advanced_APIs_Bid" }, "type": "array", "maxItems": 500, "title": "Bids", "description": "An array of bids." } }, "type": "object", "required": [ "hasMore", "bids" ], "title": "PublicBidsResponse", "description": "The public response body of the bids endpoints." }, "Advanced_APIs_PublicBillingContact": { "properties": { "id": { "type": "string", "title": "Id", "description": "The ID of the billing contact." }, "brandName": { "type": "string", "title": "Brandname", "description": "The name of the brand this agency is advertising for." }, "invoiceTo": { "type": "string", "title": "Invoiceto", "description": "The name of the company that is responsible for the invoice." }, "advertiserName": { "type": "string", "title": "Advertisername", "description": "The name of the agency/advertiser." } }, "type": "object", "required": [ "id", "brandName", "invoiceTo", "advertiserName" ], "title": "PublicBillingContact" }, "Advanced_APIs_PublicCampaign": { "properties": { "campaignId": { "type": "string", "format": "uuid", "title": "Campaignid", "description": "The ID of the campaign." }, "marketplaceId": { "type": "string", "format": "uuid", "title": "Marketplaceid", "description": "The ID of the marketplace." }, "name": { "type": "string", "minLength": 1, "title": "Name", "description": "The name of the campaign.", "examples": [ "Bola-Bola Ad campaign" ] }, "budget": { "description": "The budget assigned to the campaign.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_Budget" }, { "type": "null" } ] }, "startDate": { "type": "string", "format": "date-time", "title": "Startdate", "description": "The starting date of the campaign." }, "endDate": { "type": "string", "format": "date-time", "title": "Enddate", "description": "The end date of the campaign." }, "isActive": { "type": "boolean", "title": "Isactive", "description": "Whether this campaign is active." }, "isSmart": { "type": "boolean", "title": "Issmart", "description": "Whether this campaign is \"smart\"." }, "campaignType": { "$ref": "#/components/schemas/Advanced_APIs_CampaignType" }, "status": { "$ref": "#/components/schemas/Advanced_APIs_CampaignStatus" }, "statusUpdatedBy": { "title": "Statusupdatedby", "description": "The ID of the user who reviewed the campaign. If it's `null` and the status is not `\"pending\"` then it means this campaign has autoapproval status.", "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "campaignBehaviorData": { "title": "Campaignbehaviordata", "description": "Deprecated. This field is always null. For behavioral data use reporting service.", "deprecated": true, "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "campaignBehaviorDataByDay": { "title": "Campaignbehaviordatabyday", "description": "Deprecated. This field is always null. For behavioral data use reporting service.", "deprecated": true, "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat", "description": "When was this campaign created." }, "chargeType": { "title": "Chargetype", "description": "How campaigns are going to be charged, by click, by per mille impressions, or by action.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_ChargeType" }, { "$ref": "#/components/schemas/Advanced_APIs_ExclusiveCampaignChargeType" } ] }, "exclusivityPrice": { "title": "Exclusivityprice", "description": "Daily price for an exclusive campaign, can only be set if a campaign is exclusive", "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "targetRoas": { "title": "Targetroas", "description": "The target return on ad spend (ROAS) for this campaign. This is only applicable for autobidding listing campaigns.", "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "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" } ] }, "externalVendorId": { "type": "string", "minLength": 1, "title": "Externalvendorid", "description": "The ID of the vendor. Deprecated. Use vendor_id instead.", "deprecated": true }, "adFormat": { "$ref": "#/components/schemas/Advanced_APIs_AdFormat", "description": "The ad format of the campaign. Can be listing or banner.", "examples": [ "listing" ] }, "isAutoTrigger": { "type": "boolean", "title": "Isautotrigger", "description": "Whether the campaign is auto-triggered." }, "autobiddingObjective": { "description": "The autobidding objective for the campaign.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_AutobiddingObjective" }, { "type": "null" } ] }, "vendorId": { "type": "string", "minLength": 1, "title": "Vendorid", "description": "The ID of the vendor." }, "walletId": { "type": "string", "format": "uuid", "title": "Walletid", "description": "The uuid of the wallet to be used with this campaign." }, "fallbackWalletId": { "title": "Fallbackwalletid", "description": "The optional fallback wallet to be used with this campaign.", "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "bidCount": { "type": "integer", "title": "Bidcount", "description": "The amount of active bids associated with this campaign. This field is deprecated and will be set to 0 once the notice period is over.", "deprecated": true } }, "type": "object", "required": [ "campaignId", "marketplaceId", "name", "startDate", "endDate", "isActive", "isSmart", "campaignType", "status", "createdAt", "chargeType", "externalVendorId", "adFormat", "isAutoTrigger", "vendorId", "walletId", "bidCount" ], "title": "PublicCampaign", "description": "The campaign model." }, "Advanced_APIs_PublicCampaignCreateRequest": { "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": "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" }, "targetRoas": { "title": "Targetroas", "description": "Indicates the vendor's goal. For banners, use autobiddingObjective instead. ROAS >12 is rare and depends on product metrics and attribution model.", "oneOf": [ { "type": "number", "maximum": 30, "minimum": 0.5 }, { "type": "null" } ] }, "bids": { "items": { "$ref": "#/components/schemas/Advanced_APIs_BidCreate" }, "type": "array", "minItems": 1, "title": "Bids", "description": "An array of bids for this campaign." }, "campaignType": { "$ref": "#/components/schemas/Advanced_APIs_CampaignType", "description": "The bidding method for the campaign. Note: The value 'exclusive' is deprecated for this endpoint. Use exclusive campaign endpoints instead." }, "status": { "$ref": "#/components/schemas/Advanced_APIs_CampaignStatus", "description": "For a banner campaign, its initial review status.", "default": "approved" }, "adFormat": { "title": "Adformat", "description": "The ad format of the campaign. Can be listing or banner.", "examples": [ "listing" ], "oneOf": [ { "type": "string", "enum": [ "listing", "banner" ] }, { "type": "null" } ] }, "budget": { "description": "The assigned budget for the campaign.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_BudgetCreate" }, { "type": "null" } ] }, "chargeType": { "description": "How campaigns are going to be charged, by click, by per mille impressions, or by action. ListingAd campaigns are charged per click by default. BannerAd campaigns are charged per mille impressions by default.CPA is only allowed for listing campaigns. CPA is supported for manual and autobidding campaigns with any budget type.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_ChargeType" }, { "type": "null" } ] }, "productIds": { "items": { "type": "string" }, "type": "array", "maxItems": 250, "uniqueItems": true, "title": "Productids", "description": "The product IDs to be used in the banner campaign. This is only allowed for banner campaigns. When provided, the assets will be associated to the given product IDs." }, "autobiddingObjective": { "description": "The objective of the campaign, only for autobidding campaigns.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_AutobiddingObjective" }, { "type": "null" } ] }, "targetRoasPreference": { "description": "Target ROAS preset (aggressive, moderate, conservative). When set, the numeric target ROAS is resolved from marketplace bidcalc configuration. When only target_roas is provided without this field, preference is stored as custom.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_TargetRoasPreference" }, { "type": "null" } ] }, "walletId": { "title": "Walletid", "description": "The uuid of the wallet to be used with this campaign.", "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "fallbackWalletId": { "title": "Fallbackwalletid", "description": "The optional fallback wallet to be used with this campaign.", "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "type": "object", "required": [ "name", "bids", "campaignType" ], "title": "PublicCampaignCreateRequest", "description": "The request body of campaign creation." }, "Advanced_APIs_PublicCampaignDailyReportResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "reports": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicDailyReportData" }, "type": "array", "title": "Reports", "description": "The daily report for the campaign" } }, "type": "object", "required": [ "hasMore", "reports" ], "title": "PublicCampaignDailyReportResponse" }, "Advanced_APIs_PublicCampaignForecastMetrics": { "properties": { "impressions": { "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_PublicForecastMetric" }, { "type": "null" } ] }, "clicks": { "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_PublicForecastMetric" }, { "type": "null" } ] }, "purchases": { "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_PublicForecastMetric" }, { "type": "null" } ] }, "sales": { "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_PublicForecastMetric" }, { "type": "null" } ] }, "adSpend": { "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_PublicForecastMetric" }, { "type": "null" } ] } }, "type": "object", "title": "PublicCampaignForecastMetrics" }, "Advanced_APIs_PublicCampaignForecastResponse": { "properties": { "forecasts": { "$ref": "#/components/schemas/Advanced_APIs_PublicCampaignForecastMetrics", "description": "Campaign performance forecasts" } }, "type": "object", "required": [ "forecasts" ], "title": "PublicCampaignForecastResponse" }, "Advanced_APIs_PublicCampaignFormat": { "type": "string", "enum": [ "listing" ], "title": "PublicCampaignFormat" }, "Advanced_APIs_PublicCampaignProductsReportResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "reports": { "items": { "$ref": "#/components/schemas/Advanced_APIs_ProductReportData" }, "type": "array", "title": "Reports", "description": "The products for the campaign" } }, "type": "object", "required": [ "hasMore", "reports" ], "title": "PublicCampaignProductsReportResponse" }, "Advanced_APIs_PublicCampaignRestrictionCreate": { "properties": { "restrictionTypeId": { "type": "integer", "title": "Restrictiontypeid", "description": "The type of restriction." }, "limit": { "type": "integer", "title": "Limit", "description": "The limit of the restriction." } }, "type": "object", "required": [ "restrictionTypeId", "limit" ], "title": "PublicCampaignRestrictionCreate", "description": "Limit-based restrictions for a campaign." }, "Advanced_APIs_PublicCampaignRestrictionUpdate": { "properties": { "limit": { "title": "Limit", "description": "The limit of the restriction.", "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "status": { "description": "The status of the restriction.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_CampaignRestrictionStatus" }, { "type": "null" } ] } }, "type": "object", "title": "PublicCampaignRestrictionUpdate", "description": "Limit-based restrictions for a campaign." }, "Advanced_APIs_PublicCampaignTimeTable": { "properties": { "isActive": { "type": "boolean", "title": "Isactive", "description": "Whether the campaign will be active or not in the given period." }, "startHour": { "type": "integer", "maximum": 23, "minimum": 0, "title": "Starthour", "description": "The start time of the schedule (inclusive). Hour when the campaign starts (0-23). Example: start_hour=9 means campaign starts at 9:00 AM.", "default": 0 }, "endHour": { "type": "integer", "maximum": 24, "minimum": 1, "title": "Endhour", "description": "The end time of the schedule (exclusive). Hour when the campaign stops (1-24). Campaign runs until this hour but NOT during it. Example: end_hour=17 means campaign stops at 17:00 (5 PM). Use end_hour=24 for campaigns running until midnight.", "default": 24 }, "dayOfWeek": { "$ref": "#/components/schemas/Advanced_APIs_PublicDayOfWeek", "description": "The day of the week for the schedule." } }, "type": "object", "required": [ "isActive", "dayOfWeek" ], "title": "PublicCampaignTimeTable", "description": "The schedule for the campaign." }, "Advanced_APIs_PublicCampaignTimeTableResponse": { "properties": { "isActive": { "type": "boolean", "title": "Isactive", "description": "Whether the campaign will be active or not in the given period." }, "startHour": { "type": "integer", "maximum": 23, "minimum": 0, "title": "Starthour", "description": "The start time of the schedule (inclusive). Hour when the campaign starts (0-23). Example: start_hour=9 means campaign starts at 9:00 AM.", "default": 0 }, "endHour": { "type": "integer", "maximum": 24, "minimum": 1, "title": "Endhour", "description": "The end time of the schedule (exclusive). Hour when the campaign stops (1-24). Campaign runs until this hour but NOT during it. Example: end_hour=17 means campaign stops at 17:00 (5 PM). Use end_hour=24 for campaigns running until midnight.", "default": 24 }, "dayOfWeek": { "$ref": "#/components/schemas/Advanced_APIs_PublicDayOfWeek", "description": "The day of the week for the schedule." }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat", "description": "When was this campaign timetable last updated." } }, "type": "object", "required": [ "isActive", "dayOfWeek", "updatedAt" ], "title": "PublicCampaignTimeTableResponse", "description": "The schedule for the campaign." }, "Advanced_APIs_PublicCampaignTimetablesResponse": { "properties": { "campaignId": { "type": "string", "format": "uuid", "title": "Campaignid", "description": "The ID of the campaign." }, "timetables": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicCampaignTimeTableResponse" }, "type": "array", "title": "Timetables", "description": "The schedule for the campaign." } }, "type": "object", "required": [ "campaignId", "timetables" ], "title": "PublicCampaignTimetablesResponse", "description": "The schedule for the campaign." }, "Advanced_APIs_PublicCampaignType": { "type": "string", "enum": [ "autobidding" ], "title": "PublicCampaignType" }, "Advanced_APIs_PublicCampaignUpdateRequest": { "properties": { "name": { "title": "Name", "description": "The name of the campaign.", "examples": [ "Bola-Bola Ad campaign" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "budget": { "description": "The budget of the campaign.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_BudgetUpdate" }, { "type": "null" } ] }, "startDate": { "title": "Startdate", "description": "When should the campaign start. If the start date is in the past, it will be set to the current date.", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endDate": { "title": "Enddate", "description": "When should the campaign stop. Must be greater than start date.", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "isActive": { "title": "Isactive", "description": "Whether the campaign should be active/inactive.", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "isSmart": { "title": "Issmart", "description": "Whether the campaign is `smart`.", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "campaignType": { "description": "The bidding type of the campaign. Can only be updated to `autobidding`.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_AutobiddingCampaignType" }, { "type": "null" } ] }, "status": { "description": "The approval status of the campaign, if it's a banner campaign.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_CampaignStatus" }, { "type": "null" } ] }, "statusUpdatedBy": { "title": "Statusupdatedby", "description": "The ID of the user who approved the banner campaign.", "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "isAutoTrigger": { "title": "Isautotrigger", "description": "Whether the campaign is auto-triggered.", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "targetRoas": { "title": "Targetroas", "description": "Indicates the vendor's goal. For banners, use autobiddingObjective instead. ROAS >12 is rare and depends on product metrics and attribution model.", "oneOf": [ { "type": "number", "maximum": 30, "minimum": 0.5 }, { "type": "null" } ] }, "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" } ] }, "chargeType": { "description": "How campaigns are going to be charged, by click, by per mille impressions, or by action.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_ChargeType" }, { "type": "null" } ] }, "autobiddingObjective": { "description": "The objective of the campaign, only for autobidding campaigns.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_AutobiddingObjective" }, { "type": "null" } ] }, "productIds": { "title": "Productids", "description": "The product IDs to be used in the banner campaign. This is only allowed for banner campaigns. When provided, the assets will be associated to the given product IDs.", "oneOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 250, "minItems": 1, "uniqueItems": true }, { "type": "null" } ] }, "bannerAdRejectionReason": { "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_BannerAdRejectionReason" }, { "type": "null" } ] }, "targetRoasPreference": { "description": "Target ROAS preset (aggressive, moderate, conservative). When set, the numeric target ROAS is resolved from marketplace bidcalc configuration. Cannot be provided together with target_roas.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_TargetRoasPreference" }, { "type": "null" } ] }, "fallbackWalletId": { "title": "Fallbackwalletid", "description": "The optional fallback wallet to be used with this campaign.", "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "type": "object", "title": "PublicCampaignUpdateRequest", "description": "Public Campaign Update Request Body." }, "Advanced_APIs_PublicCampaignsKpis": { "properties": { "adSpend": { "type": "integer", "minimum": 0, "title": "Adspend", "description": "Amount spent on ads during the selected period in minor units of currency." }, "cpc": { "type": "number", "title": "Cpc", "description": "Average cost per click during the selected period." }, "cpm": { "type": "number", "title": "Cpm", "description": "Average cost per thousand impressions during the selected period.", "default": 0 }, "ctr": { "type": "number", "title": "Ctr", "description": "The click through rate during the selected period." }, "conversionRate": { "type": "number", "title": "Conversionrate", "description": "The conversion rate during the selected period." }, "impressions": { "type": "integer", "minimum": 0, "title": "Impressions", "description": "Number of impressions during the selected period." }, "chargedImpressions": { "type": "integer", "minimum": 0, "title": "Chargedimpressions", "description": "Amount of charged impressions during the selected period." }, "clicks": { "type": "integer", "minimum": 0, "title": "Clicks", "description": "Number of clicks during the selected period." }, "chargedClicks": { "type": "integer", "minimum": 0, "title": "Chargedclicks", "description": "Amount of charged clicks during the selected period." }, "purchaseCount": { "type": "integer", "minimum": 0, "title": "Purchasecount", "description": "Number of purchases during the selected period." }, "purchaseRevenue": { "type": "integer", "minimum": 0, "title": "Purchaserevenue", "description": "Revenue from promoted sales during the selected period in minor units of currency." }, "roas": { "type": "number", "title": "Roas", "description": "The return on ad spend during the selected period." }, "acos": { "type": "number", "title": "Acos", "description": "Advertising cost of sales (inverse of ROAS) during the selected period.", "default": 0 }, "vendorId": { "type": "string", "title": "Vendorid", "description": "The external vendor ID used by the marketplace." }, "campaignId": { "type": "string", "format": "uuid", "title": "Campaignid", "description": "The campaign ID." }, "startDate": { "type": "string", "format": "date-time", "title": "Startdate", "description": "The start date of the campaign." }, "endDate": { "type": "string", "format": "date-time", "title": "Enddate", "description": "The end date of the campaign." }, "campaignName": { "title": "Campaignname", "description": "The campaign name.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "type": "integer", "minimum": 0, "title": "Quantity", "description": "Number of items purchased during the selected period." } }, "type": "object", "required": [ "adSpend", "cpc", "ctr", "conversionRate", "impressions", "chargedImpressions", "clicks", "chargedClicks", "purchaseCount", "purchaseRevenue", "roas", "vendorId", "campaignId", "startDate", "endDate", "quantity" ], "title": "PublicCampaignsKpis", "description": "Response for campaign KPIs using external vendor IDs." }, "Advanced_APIs_PublicCampaignsKpisResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "campaignsKpis": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicCampaignsKpis" }, "type": "array", "title": "Campaignskpis", "description": "A list with the marketplace campaign KPIs." } }, "type": "object", "required": [ "hasMore", "campaignsKpis" ], "title": "PublicCampaignsKpisResponse", "description": "Response for marketplace campaign KPIs using external vendor IDs." }, "Advanced_APIs_PublicCampaignsResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Whether this is the last page of results or not." }, "next": { "description": "The parameters that should be used to fetch the next page.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_Next" }, { "type": "null" } ] }, "campaigns": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicCampaign" }, "type": "array", "title": "Campaigns", "description": "An array of campaigns." } }, "type": "object", "required": [ "hasMore", "campaigns" ], "title": "PublicCampaignsResponse", "description": "The campaigns response." }, "Advanced_APIs_PublicCreateSponsoredBrandBid": { "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" } ] }, "target": { "$ref": "#/components/schemas/Advanced_APIs_Entity" }, "triggers": { "items": { "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_CategoriesTrigger" }, { "$ref": "#/components/schemas/Advanced_APIs_CategoriesFromCampaignProductsTrigger" }, { "$ref": "#/components/schemas/Advanced_APIs_CategoryTrigger" }, { "$ref": "#/components/schemas/Advanced_APIs_KeywordTrigger-Input" }, { "$ref": "#/components/schemas/Advanced_APIs_KeywordsFromCampaignProductsTrigger" }, { "$ref": "#/components/schemas/Advanced_APIs_ProductTrigger" } ], "description": "When should this bid participate in an auction.", "discriminator": { "propertyName": "type", "mapping": { "categories": "#/components/schemas/Advanced_APIs_CategoriesTrigger", "categories_from_campaign_products": "#/components/schemas/Advanced_APIs_CategoriesFromCampaignProductsTrigger", "category": "#/components/schemas/Advanced_APIs_CategoryTrigger", "keyword": "#/components/schemas/Advanced_APIs_KeywordTrigger-Input", "keywords_from_campaign_products": "#/components/schemas/Advanced_APIs_KeywordsFromCampaignProductsTrigger", "product": "#/components/schemas/Advanced_APIs_ProductTrigger" } } }, "type": "array", "maxItems": 500, "minItems": 1, "title": "Triggers", "description": "A list of objects that trigger the appearance of this bid on an auction." }, "formatProperties": { "$ref": "#/components/schemas/Advanced_APIs_PublicSponsoredBrandAdCreate", "description": "The public V2 format properties of the bid." }, "location": { "title": "Location", "description": "Optional location associated with this bid.", "examples": [ "Santiago" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "type": "object", "required": [ "target", "triggers", "formatProperties" ], "title": "PublicCreateSponsoredBrandBid", "description": "A sponsored brand bid creation request for the public API." }, "Advanced_APIs_PublicCreateSponsoredBrandBids": { "properties": { "bids": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicCreateSponsoredBrandBid" }, "type": "array", "maxItems": 500, "minItems": 1, "title": "Bids", "description": "An array of bids for this campaign." }, "slotId": { "type": "string", "minLength": 1, "title": "Slotid", "description": "The external slot ID where the sponsored brand campaign will be shown." }, "slotIds": { "title": "Slotids", "description": "Additional external slot IDs. If present, each ID replicates the whole bid set.", "oneOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 10 }, { "type": "null" } ] }, "content": { "additionalProperties": true, "type": "object", "title": "Content", "description": "Dynamic content validated against the slot's JSON template." } }, "type": "object", "required": [ "bids", "slotId", "content" ], "title": "PublicCreateSponsoredBrandBids", "description": "Request body for replacing public sponsored brand bids." }, "Advanced_APIs_PublicDailyReportData": { "properties": { "impressions": { "$ref": "#/components/schemas/Advanced_APIs_OffsiteEvents", "description": "How many impressions are attributed to this report item." }, "clicks": { "$ref": "#/components/schemas/Advanced_APIs_OffsiteEvents", "description": "How many clicks are attributed to this report item." }, "purchases": { "$ref": "#/components/schemas/Advanced_APIs_OffsitePurchases", "description": "How many purchases are attributed to this report item." }, "date": { "type": "string", "format": "date", "title": "Date", "description": "The date for this aggregation." } }, "type": "object", "required": [ "impressions", "clicks", "purchases", "date" ], "title": "PublicDailyReportData", "description": "Clicks, impressions and purchases attributed to this report item so far, for a particular date." }, "Advanced_APIs_PublicDateRange": { "properties": { "startDate": { "type": "string", "format": "date", "title": "Startdate", "description": "Campaign start date (YYYY-MM-DD)" }, "endDate": { "type": "string", "format": "date", "title": "Enddate", "description": "Campaign end date (YYYY-MM-DD). Must be within 31 days of start date." } }, "type": "object", "required": [ "startDate", "endDate" ], "title": "PublicDateRange" }, "Advanced_APIs_PublicDayOfWeek": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7 ], "title": "PublicDayOfWeek", "description": "The day of the week." }, "Advanced_APIs_PublicDsp": { "type": "string", "enum": [ "google_ads", "meta" ], "title": "PublicDsp" }, "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_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_PublicExclusiveBannerCampaignUpdateRequest": { "properties": { "name": { "title": "Name", "description": "The name of the campaign.", "examples": [ "Bola-Bola Ad campaign" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "isActive": { "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.", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "startDate": { "title": "Startdate", "description": "When should the campaign start. If the start date is in the past, it will be set to the current date.", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endDate": { "title": "Enddate", "description": "When should the campaign stop. Must be greater than start date.", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "exclusivityPrice": { "title": "Exclusivityprice", "description": "The price to pay daily for the campaign to run.", "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "position": { "title": "Position", "description": "The rank the ad will have in the auction", "oneOf": [ { "type": "integer", "maximum": 20, "minimum": 1 }, { "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" } ] }, "status": { "description": "The approval status of the campaign.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_CampaignStatus" }, { "type": "null" } ] }, "bannerAdRejectionReason": { "description": "The reason for rejecting the banner ad, if status is declined.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_BannerAdRejectionReason" }, { "type": "null" } ] }, "productIds": { "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.", "oneOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 250, "minItems": 1, "uniqueItems": true }, { "type": "null" } ] } }, "type": "object", "title": "PublicExclusiveBannerCampaignUpdateRequest", "description": "The public request body for updating an exclusive banner campaign." }, "Advanced_APIs_PublicExclusiveListingCampaign": { "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 }, "walletId": { "title": "Walletid", "description": "The uuid of the wallet to be used with this campaign.", "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "adFormat": { "type": "string", "const": "exclusive_listing", "title": "Adformat", "description": "The ad format of the campaign. Can be exclusive_listing.", "examples": [ "exclusive_listing" ] }, "vendorId": { "type": "string", "title": "Vendorid", "description": "The marketplace's ID of the vendor." }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat", "description": "When was this campaign created." }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat", "description": "When was this campaign last updated." } }, "type": "object", "required": [ "name", "marketplaceId", "campaignId", "exclusivityPrice", "chargeType", "adFormat", "vendorId", "createdAt", "updatedAt" ], "title": "PublicExclusiveListingCampaign", "description": "Model that represents an Exclusive Listing Campaign." }, "Advanced_APIs_PublicExclusiveListingCampaignCreateRequest": { "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 }, "bids": { "items": { "$ref": "#/components/schemas/Advanced_APIs_CreateExclusiveListingBid" }, "type": "array", "maxItems": 1, "minItems": 1, "title": "Bids", "description": "An array of bids for this campaign." }, "walletId": { "title": "Walletid", "description": "The uuid of the wallet to be used with this campaign.", "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "type": "object", "required": [ "name", "startDate", "endDate", "exclusivityPrice", "bids" ], "title": "PublicExclusiveListingCampaignCreateRequest", "description": "The request body for creating an exclusive listing campaign." }, "Advanced_APIs_PublicExclusiveListingCampaignUpdateRequest": { "properties": { "name": { "title": "Name", "description": "The name of the campaign.", "examples": [ "Bola-Bola Ad campaign" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "isActive": { "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.", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "startDate": { "title": "Startdate", "description": "When should the campaign start. If the start date is in the past, it will be set to the current date.", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endDate": { "title": "Enddate", "description": "When should the campaign stop. Must be greater than start date.", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "exclusivityPrice": { "title": "Exclusivityprice", "description": "The price to pay daily for the campaign to run.", "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "position": { "title": "Position", "description": "The rank the ad will have in the auction", "oneOf": [ { "type": "integer", "maximum": 20, "minimum": 1 }, { "type": "null" } ] } }, "type": "object", "title": "PublicExclusiveListingCampaignUpdateRequest", "description": "The public request body for updating an exclusive listing campaign." }, "Advanced_APIs_PublicForecastMetric": { "properties": { "forecastValue": { "type": "number", "title": "Forecastvalue", "description": "Predicted value" }, "forecastIntervalMin": { "type": "number", "title": "Forecastintervalmin", "description": "Lower bound of forecast interval" }, "forecastIntervalMax": { "type": "number", "title": "Forecastintervalmax", "description": "Upper bound of forecast interval" } }, "type": "object", "required": [ "forecastValue", "forecastIntervalMin", "forecastIntervalMax" ], "title": "PublicForecastMetric" }, "Advanced_APIs_PublicGetBillingContactsResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "billingContacts": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicBillingContact" }, "type": "array", "title": "Billingcontacts", "description": "List of billing contacts for the vendor." } }, "type": "object", "required": [ "hasMore", "billingContacts" ], "title": "PublicGetBillingContactsResponse" }, "Advanced_APIs_PublicListingCampaignForecastRequest": { "properties": { "campaignFormat": { "$ref": "#/components/schemas/Advanced_APIs_PublicCampaignFormat", "description": "Campaign format type. Currently only 'listing' is supported." }, "dailyBudget": { "type": "number", "exclusiveMinimum": 0, "title": "Dailybudget", "description": "Daily budget for the campaign" }, "dateRange": { "$ref": "#/components/schemas/Advanced_APIs_PublicDateRange", "description": "Campaign date range" }, "targetRoas": { "type": "number", "exclusiveMinimum": 0, "title": "Targetroas", "description": "Target Return on Ad Spend" }, "campaignType": { "$ref": "#/components/schemas/Advanced_APIs_PublicCampaignType", "description": "Campaign type (required)" }, "products": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicProductRequest" }, "type": "array", "minItems": 1, "title": "Products", "description": "List of products in the campaign (required)" }, "triggers": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicTriggerRequest" }, "type": "array", "title": "Triggers", "description": "List of campaign triggers (optional, defaults to empty list)" }, "targets": { "title": "Targets", "description": "Optional list of target variables to forecast. If not provided, all targets will be forecasted.", "oneOf": [ { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicTargetVariable" }, "type": "array" }, { "type": "null" } ] } }, "type": "object", "required": [ "campaignFormat", "dailyBudget", "dateRange", "targetRoas", "campaignType", "products" ], "title": "PublicListingCampaignForecastRequest", "description": "Public API request for a listing campaign performance forecast." }, "Advanced_APIs_PublicMarketplaceVendorsKpisResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "vendorKpis": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicVendorsKpis" }, "type": "array", "title": "Vendorkpis", "description": "A list with the marketplace vendors KPIs." } }, "type": "object", "required": [ "hasMore", "vendorKpis" ], "title": "PublicMarketplaceVendorsKpisResponse", "description": "Response for marketplace vendors KPIs using external IDs." }, "Advanced_APIs_PublicOffsiteAudience": { "properties": { "id": { "type": "string", "title": "Id", "description": "The id of the audience. Use this id to use audiences in campaign creation" }, "name": { "type": "string", "title": "Name", "description": "The name of the audience." }, "description": { "title": "Description", "description": "The description of the audience.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "estimatedSize": { "title": "Estimatedsize", "description": "The estimated size of the audience.", "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "estimatedSizeRange": { "description": "The estimated size range of the audience.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_IntRange" }, { "type": "null" } ] }, "syncedDsps": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicAudienceSyncDsp" }, "type": "array", "title": "Synceddsps", "description": "The DSPs this audience is synced to." } }, "type": "object", "required": [ "id", "name" ], "title": "PublicOffsiteAudience" }, "Advanced_APIs_PublicOffsiteAudienceCreateResponse": { "properties": { "jobId": { "type": "string", "format": "uuid", "title": "Jobid", "description": "The unique identifier for the queued job.", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ] }, "url": { "type": "string", "title": "Url", "description": "The presigned url to upload the audience csv file.\n Presigned url must be used with PUT method and include the header `Content-Type: text/csv`.", "examples": [ "https://offsite-ads-user-list-uploads.s3.us-east-2.amazonaws.com/123e4567-e89b-12d3-a456-426614174000.csv" ] } }, "type": "object", "required": [ "jobId", "url" ], "title": "PublicOffsiteAudienceCreateResponse" }, "Advanced_APIs_PublicOffsiteAudienceReplaceRequest": { "properties": { "name": { "title": "Name", "description": "Optional updated name of the user list audience.", "examples": [ "My user list audience" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "description": { "title": "Description", "description": "Optional updated description of the user list audience.", "examples": [ "This is a user list audience description." ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "type": "object", "title": "PublicOffsiteAudienceReplaceRequest" }, "Advanced_APIs_PublicOffsiteAudiencesResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "audiences": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicOffsiteAudience" }, "type": "array", "title": "Audiences", "description": "The list of audiences." } }, "type": "object", "required": [ "hasMore", "audiences" ], "title": "PublicOffsiteAudiencesResponse" }, "Advanced_APIs_PublicOffsiteUserListAudienceCreateRequest": { "properties": { "name": { "type": "string", "minLength": 1, "title": "Name", "description": "The name of the user list audience.", "examples": [ "My user list audience" ] }, "description": { "title": "Description", "description": "The description of the user list audience.", "examples": [ "This is a user list audience description." ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "dsp": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicAudienceSyncDsp" }, "type": "array", "minItems": 1, "title": "Dsp", "description": "The DSPs to sync the audience to. Include one or more of: google_ads, meta, tiktok_ads, snapchat_ads.", "examples": [ [ "google_ads" ], [ "google_ads", "meta" ] ] } }, "type": "object", "required": [ "name", "dsp" ], "title": "PublicOffsiteUserListAudienceCreateRequest" }, "Advanced_APIs_PublicProductRequest": { "properties": { "id": { "type": "string", "title": "Id", "description": "Product ID" } }, "type": "object", "required": [ "id" ], "title": "PublicProductRequest" }, "Advanced_APIs_PublicSegmentResponse": { "properties": { "name": { "type": "string", "maxLength": 64, "title": "Name", "description": "Name of the segment." }, "description": { "title": "Description", "description": "Description of the segment.", "oneOf": [ { "type": "string", "maxLength": 400 }, { "type": "null" } ] }, "id": { "type": "string", "title": "Id", "description": "ID of the segment." }, "total": { "type": "integer", "title": "Total", "description": "User count of the segment." } }, "type": "object", "required": [ "name", "description", "id", "total" ], "title": "PublicSegmentResponse" }, "Advanced_APIs_PublicSegmentUpsert": { "properties": { "name": { "type": "string", "maxLength": 64, "title": "Name", "description": "Name of the segment." }, "description": { "title": "Description", "description": "Description of the segment.", "oneOf": [ { "type": "string", "maxLength": 400 }, { "type": "null" } ] }, "id": { "type": "string", "minLength": 1, "title": "Id", "description": "ID of the segment." } }, "type": "object", "required": [ "name", "description", "id" ], "title": "PublicSegmentUpsert" }, "Advanced_APIs_PublicSegmentsResponse": { "properties": { "segments": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicSegmentResponse" }, "type": "array", "title": "Segments", "description": "List of segments." } }, "type": "object", "required": [ "segments" ], "title": "PublicSegmentsResponse" }, "Advanced_APIs_PublicSegmentsUpsertRequest": { "properties": { "segments": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicSegmentUpsert" }, "type": "array", "title": "Segments", "description": "List of segments to update." } }, "type": "object", "required": [ "segments" ], "title": "PublicSegmentsUpsertRequest" }, "Advanced_APIs_PublicSponsoredBrandAd": { "properties": { "imageAssets": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicSponsoredBrandAsset" }, "type": "array", "maxItems": 500, "title": "Imageassets", "description": "The image assets for the sponsored brand ad." }, "content": { "additionalProperties": true, "type": "object", "title": "Content", "description": "Dynamic content validated against the slot's JSON template." }, "slotId": { "type": "string", "title": "Slotid", "description": "The external slot ID where the sponsored brand ad is shown." } }, "type": "object", "required": [ "imageAssets", "content", "slotId" ], "title": "PublicSponsoredBrandAd", "description": "The public V2 format properties of a sponsored brand bid." }, "Advanced_APIs_PublicSponsoredBrandAdCreate": { "properties": { "imageAssets": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicSponsoredBrandAsset" }, "type": "array", "maxItems": 500, "title": "Imageassets", "description": "The image assets for the sponsored brand ad." } }, "type": "object", "required": [ "imageAssets" ], "title": "PublicSponsoredBrandAdCreate", "description": "The public format properties for sponsored brand bid creation." }, "Advanced_APIs_PublicSponsoredBrandAsset": { "properties": { "height": { "type": "integer", "title": "Height", "description": "The height of the asset." }, "width": { "type": "integer", "title": "Width", "description": "The width of the asset." }, "contentType": { "type": "string", "title": "Contenttype", "description": "The content type of the asset." }, "contentLength": { "type": "integer", "exclusiveMinimum": 0, "title": "Contentlength", "description": "The content length of the asset." }, "url": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Url", "description": "The URL of the asset." } }, "type": "object", "required": [ "height", "width", "contentType", "contentLength", "url" ], "title": "PublicSponsoredBrandAsset" }, "Advanced_APIs_PublicSponsoredBrandBid": { "properties": { "bidId": { "type": "string", "format": "uuid", "title": "Bidid", "description": "The ID of the bid." }, "state": { "$ref": "#/components/schemas/Advanced_APIs_BidState", "description": "The activity state of the bid." }, "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" } ] }, "target": { "$ref": "#/components/schemas/Advanced_APIs_Entity" }, "triggers": { "items": { "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_CategoriesTrigger" }, { "$ref": "#/components/schemas/Advanced_APIs_CategoriesFromCampaignProductsTrigger" }, { "$ref": "#/components/schemas/Advanced_APIs_CategoryTrigger" }, { "$ref": "#/components/schemas/Advanced_APIs_KeywordTrigger-Output" }, { "$ref": "#/components/schemas/Advanced_APIs_KeywordsFromCampaignProductsTrigger" }, { "$ref": "#/components/schemas/Advanced_APIs_ProductTrigger" } ], "description": "When should this bid participate in an auction.", "discriminator": { "propertyName": "type", "mapping": { "categories": "#/components/schemas/Advanced_APIs_CategoriesTrigger", "categories_from_campaign_products": "#/components/schemas/Advanced_APIs_CategoriesFromCampaignProductsTrigger", "category": "#/components/schemas/Advanced_APIs_CategoryTrigger", "keyword": "#/components/schemas/Advanced_APIs_KeywordTrigger-Output", "keywords_from_campaign_products": "#/components/schemas/Advanced_APIs_KeywordsFromCampaignProductsTrigger", "product": "#/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." }, "formatProperties": { "$ref": "#/components/schemas/Advanced_APIs_PublicSponsoredBrandAd", "description": "The public V2 format properties of the bid." }, "location": { "title": "Location", "description": "Optional location associated with this bid.", "examples": [ "Santiago" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "type": "object", "required": [ "bidId", "state", "target", "triggers", "formatProperties" ], "title": "PublicSponsoredBrandBid", "description": "A sponsored brand bid returned by the public API." }, "Advanced_APIs_PublicSponsoredBrandBidType": { "type": "string", "enum": [ "manual", "autobidding" ], "title": "PublicSponsoredBrandBidType", "description": "The bidding method for the sponsored brand campaign." }, "Advanced_APIs_PublicSponsoredBrandBidsResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "results": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicSponsoredBrandBid" }, "type": "array", "title": "Results", "description": "An array of sponsored brand bids." } }, "type": "object", "required": [ "hasMore", "results" ], "title": "PublicSponsoredBrandBidsResponse", "description": "Paginated list of sponsored brand bids." }, "Advanced_APIs_PublicSponsoredBrandCampaignCreateRequest": { "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.", "default": true }, "status": { "$ref": "#/components/schemas/Advanced_APIs_CampaignStatus", "description": "The initial review status of the sponsored brand campaign.", "default": "approved" }, "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 }, "slotId": { "type": "string", "minLength": 1, "title": "Slotid", "description": "The external slot ID where the sponsored brand campaign will be shown." }, "slotIds": { "title": "Slotids", "description": "Additional external slot IDs. If present, each ID replicates the whole bid set.", "oneOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 10 }, { "type": "null" } ] }, "schedule": { "items": { "$ref": "#/components/schemas/Advanced_APIs_Schedule" }, "type": "array", "maxItems": 1, "minItems": 1, "title": "Schedule", "description": "The schedule for the campaign." }, "content": { "additionalProperties": true, "type": "object", "title": "Content", "description": "Dynamic content validated against the slot's JSON template." }, "walletId": { "title": "Walletid", "description": "The uuid of the wallet used with this campaign.", "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "bids": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicCreateSponsoredBrandBid" }, "type": "array", "maxItems": 500, "minItems": 1, "title": "Bids", "description": "An array of bids for this campaign." }, "targetRoas": { "title": "Targetroas", "description": "Indicates the vendor's target return on ad spend.", "oneOf": [ { "type": "number", "maximum": 30, "minimum": 0.5 }, { "type": "null" } ] }, "bidType": { "$ref": "#/components/schemas/Advanced_APIs_PublicSponsoredBrandBidType", "description": "The bidding type of the campaign." }, "budget": { "$ref": "#/components/schemas/Advanced_APIs_BudgetCreate", "description": "The assigned budget for the campaign." }, "targetRoasPreference": { "description": "Target ROAS preference label.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_TargetRoasPreference" }, { "type": "null" } ] }, "chargeType": { "$ref": "#/components/schemas/Advanced_APIs_ChargeType", "description": "How campaigns are charged.", "default": "CPC" }, "autobiddingObjective": { "$ref": "#/components/schemas/Advanced_APIs_AutobiddingObjective", "description": "The objective of the campaign.", "default": "clicks" } }, "type": "object", "required": [ "name", "slotId", "schedule", "content", "bids", "bidType", "budget" ], "title": "PublicSponsoredBrandCampaignCreateRequest", "description": "Request body for creating a public sponsored brand campaign." }, "Advanced_APIs_PublicSponsoredBrandCampaignUpdateRequest": { "properties": { "name": { "title": "Name", "description": "The name of the campaign.", "examples": [ "Bola-Bola Ad campaign" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "isActive": { "title": "Isactive", "description": "Whether the campaign should be activated.", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "schedule": { "title": "Schedule", "description": "The schedule for the campaign.", "oneOf": [ { "items": { "$ref": "#/components/schemas/Advanced_APIs_Schedule" }, "type": "array", "maxItems": 1 }, { "type": "null" } ] }, "status": { "description": "The approval status of the sponsored brand campaign.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_CampaignStatus" }, { "type": "null" } ] }, "sponsoredBrandRejectionReason": { "description": "The reason for rejecting the sponsored brand campaign.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_PublicSponsoredBrandRejectionReason" }, { "type": "null" } ] }, "targetRoas": { "title": "Targetroas", "description": "Indicates the vendor's target return on ad spend.", "oneOf": [ { "type": "number", "maximum": 30, "minimum": 0.5 }, { "type": "null" } ] }, "bidType": { "description": "The bidding type of the campaign. It can only be set to autobidding.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_AutobiddingCampaignType" }, { "type": "null" } ] }, "targetRoasPreference": { "description": "Target ROAS preference label.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_TargetRoasPreference" }, { "type": "null" } ] }, "budget": { "description": "The assigned budget for the campaign.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_BudgetUpdate" }, { "type": "null" } ] }, "chargeType": { "description": "How campaigns are charged.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_ChargeType" }, { "type": "null" } ] }, "isAutoTrigger": { "title": "Isautotrigger", "description": "Whether the campaign is auto-triggered.", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "autobiddingObjective": { "description": "The objective of the campaign.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_AutobiddingObjective" }, { "type": "null" } ] } }, "type": "object", "title": "PublicSponsoredBrandCampaignUpdateRequest", "description": "Request body for updating a public sponsored brand campaign." }, "Advanced_APIs_PublicSponsoredBrandCampaignWithBudget": { "properties": { "campaignId": { "type": "string", "format": "uuid", "title": "Campaignid", "description": "The ID of the campaign." }, "marketplaceId": { "type": "string", "format": "uuid", "title": "Marketplaceid", "description": "The ID of the marketplace." }, "vendorId": { "type": "string", "title": "Vendorid", "description": "The external vendor ID." }, "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 is active." }, "status": { "$ref": "#/components/schemas/Advanced_APIs_CampaignStatus", "description": "The approval status of the sponsored brand campaign." }, "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." }, "slotId": { "type": "string", "title": "Slotid", "description": "The external slot ID where the sponsored brand campaign is shown." }, "schedule": { "items": { "$ref": "#/components/schemas/Advanced_APIs_Schedule" }, "type": "array", "maxItems": 1, "minItems": 1, "title": "Schedule", "description": "The schedule for the campaign." }, "content": { "additionalProperties": true, "type": "object", "title": "Content", "description": "Dynamic content validated against the slot's JSON template." }, "walletId": { "title": "Walletid", "description": "The uuid of the wallet used with this campaign.", "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat", "description": "When this campaign was created." }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat", "description": "When this campaign was last updated." }, "targetRoas": { "title": "Targetroas", "description": "Indicates the vendor's target return on ad spend.", "oneOf": [ { "type": "number", "maximum": 30, "minimum": 0.5 }, { "type": "null" } ] }, "bidType": { "$ref": "#/components/schemas/Advanced_APIs_PublicSponsoredBrandBidType", "description": "The bidding type of the campaign." }, "isAgency": { "type": "boolean", "title": "Isagency", "description": "Whether this campaign is promoted by an agency." }, "targetRoasPreference": { "description": "Target ROAS preference label.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_TargetRoasPreference" }, { "type": "null" } ] }, "chargeType": { "$ref": "#/components/schemas/Advanced_APIs_ChargeType", "description": "How campaigns are charged." }, "autobiddingObjective": { "description": "The objective of the campaign.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_AutobiddingObjective" }, { "type": "null" } ] }, "budget": { "$ref": "#/components/schemas/Advanced_APIs_Budget", "description": "The assigned budget for the campaign." } }, "type": "object", "required": [ "campaignId", "marketplaceId", "vendorId", "name", "isActive", "status", "isAutoTrigger", "slotId", "schedule", "content", "createdAt", "updatedAt", "bidType", "isAgency", "chargeType", "budget" ], "title": "PublicSponsoredBrandCampaignWithBudget", "description": "A regular sponsored brand campaign returned by the public API." }, "Advanced_APIs_PublicSponsoredBrandRejectionReason": { "properties": { "declineReason": { "type": "string", "title": "Declinereason", "description": "The reason the campaign was rejected." }, "reasonDetails": { "title": "Reasondetails", "description": "Additional details about the rejection reason.", "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "type": "object", "required": [ "declineReason" ], "title": "PublicSponsoredBrandRejectionReason" }, "Advanced_APIs_PublicTargetVariable": { "type": "string", "enum": [ "ad_spend", "clicks", "impressions", "purchases", "sales" ], "title": "PublicTargetVariable" }, "Advanced_APIs_PublicTriggerRequest": { "properties": { "type": { "$ref": "#/components/schemas/Advanced_APIs_PublicTriggerType", "description": "Trigger type" }, "value": { "type": "string", "title": "Value", "description": "Trigger value" } }, "type": "object", "required": [ "type", "value" ], "title": "PublicTriggerRequest" }, "Advanced_APIs_PublicTriggerType": { "type": "string", "enum": [ "search", "category" ], "title": "PublicTriggerType" }, "Advanced_APIs_PublicUpdateTargets": { "properties": { "add": { "title": "Add", "description": "List of targets to add", "oneOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ] }, "remove": { "title": "Remove", "description": "List of targets to remove", "oneOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ] } }, "type": "object", "title": "PublicUpdateTargets" }, "Advanced_APIs_PublicUpsertBillingContactCampaignRequest": { "properties": { "billingContactId": { "type": "string", "title": "Billingcontactid", "description": "The ID of the billing contact." }, "campaignId": { "type": "string", "format": "uuid", "title": "Campaignid", "description": "The ID of the campaign." } }, "type": "object", "required": [ "billingContactId", "campaignId" ], "title": "PublicUpsertBillingContactCampaignRequest" }, "Advanced_APIs_PublicUpsertBillingContactRequest": { "properties": { "brandName": { "type": "string", "title": "Brandname", "description": "The name of the brand this agency is advertising for." }, "invoiceTo": { "type": "string", "title": "Invoiceto", "description": "The name of the company that is responsible for the invoice." }, "advertiserName": { "type": "string", "title": "Advertisername", "description": "The name of the agency/advertiser." } }, "type": "object", "required": [ "brandName", "invoiceTo", "advertiserName" ], "title": "PublicUpsertBillingContactRequest" }, "Advanced_APIs_PublicUpsertBillingContactVendorRequest": { "properties": { "billingContactId": { "type": "string", "title": "Billingcontactid", "description": "The ID of the billing contact." }, "vendorId": { "type": "string", "title": "Vendorid", "description": "The ID of the vendor to associate with the billing contact." } }, "type": "object", "required": [ "billingContactId", "vendorId" ], "title": "PublicUpsertBillingContactVendorRequest" }, "Advanced_APIs_PublicUpsertTimeTablesRequest": { "properties": { "timetables": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PublicCampaignTimeTable" }, "type": "array", "maxItems": 7, "minItems": 1, "title": "Timetables", "description": "The schedule for the campaign." } }, "type": "object", "required": [ "timetables" ], "title": "PublicUpsertTimeTablesRequest" }, "Advanced_APIs_PublicVendorCampaignsResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "campaigns": { "items": { "$ref": "#/components/schemas/Advanced_APIs_OfsiteCampaign" }, "type": "array", "title": "Campaigns", "description": "The campaigns for the vendor" } }, "type": "object", "required": [ "hasMore", "campaigns" ], "title": "PublicVendorCampaignsResponse" }, "Advanced_APIs_PublicVendorUser": { "properties": { "email": { "type": "string", "maxLength": 255, "title": "Email", "description": "The email address of the vendor user" }, "givenName": { "type": "string", "maxLength": 50, "title": "Givenname", "description": "The first name of the vendor user", "default": "" }, "familyName": { "type": "string", "maxLength": 50, "title": "Familyname", "description": "The last name of the vendor user", "default": "" }, "languagePreference": { "$ref": "#/components/schemas/Advanced_APIs_LanguagePreference", "description": "The preferred language of the vendor user", "default": "en" }, "vendorIds": { "items": { "type": "string" }, "type": "array", "maxItems": 1000, "minItems": 1, "title": "Vendorids" }, "userId": { "type": "string", "format": "uuid", "title": "Userid", "description": "The unique identifier for the vendor user" } }, "type": "object", "required": [ "email", "vendorIds", "userId" ], "title": "PublicVendorUser" }, "Advanced_APIs_PublicVendorUserCreateRequest": { "properties": { "email": { "type": "string", "maxLength": 255, "title": "Email", "description": "The email address of the vendor user" }, "givenName": { "type": "string", "maxLength": 50, "title": "Givenname", "description": "The first name of the vendor user", "default": "" }, "familyName": { "type": "string", "maxLength": 50, "title": "Familyname", "description": "The last name of the vendor user", "default": "" }, "languagePreference": { "$ref": "#/components/schemas/Advanced_APIs_LanguagePreference", "description": "The preferred language of the vendor user", "default": "en" }, "vendorIds": { "items": { "type": "string" }, "type": "array", "maxItems": 1000, "minItems": 1, "title": "Vendorids" } }, "type": "object", "required": [ "email", "vendorIds" ], "title": "PublicVendorUserCreateRequest" }, "Advanced_APIs_PublicVendorUserUpdateRequest": { "properties": { "email": { "type": "string", "maxLength": 255, "title": "Email", "description": "The email address of the vendor user" }, "vendorIds": { "items": { "type": "string" }, "type": "array", "maxItems": 1000, "minItems": 1, "title": "Vendorids" } }, "type": "object", "required": [ "email", "vendorIds" ], "title": "PublicVendorUserUpdateRequest" }, "Advanced_APIs_PublicVendorsKpis": { "properties": { "adSpend": { "type": "integer", "minimum": 0, "title": "Adspend", "description": "Amount spent on ads during the selected period in minor units of currency." }, "cpc": { "type": "number", "title": "Cpc", "description": "Average cost per click during the selected period." }, "cpm": { "type": "number", "title": "Cpm", "description": "Average cost per thousand impressions during the selected period.", "default": 0 }, "ctr": { "type": "number", "title": "Ctr", "description": "The click through rate during the selected period." }, "conversionRate": { "type": "number", "title": "Conversionrate", "description": "The conversion rate during the selected period." }, "impressions": { "type": "integer", "minimum": 0, "title": "Impressions", "description": "Number of impressions during the selected period." }, "chargedImpressions": { "type": "integer", "minimum": 0, "title": "Chargedimpressions", "description": "Amount of charged impressions during the selected period." }, "clicks": { "type": "integer", "minimum": 0, "title": "Clicks", "description": "Number of clicks during the selected period." }, "chargedClicks": { "type": "integer", "minimum": 0, "title": "Chargedclicks", "description": "Amount of charged clicks during the selected period." }, "purchaseCount": { "type": "integer", "minimum": 0, "title": "Purchasecount", "description": "Number of purchases during the selected period." }, "purchaseRevenue": { "type": "integer", "minimum": 0, "title": "Purchaserevenue", "description": "Revenue from promoted sales during the selected period in minor units of currency." }, "roas": { "type": "number", "title": "Roas", "description": "The return on ad spend during the selected period." }, "acos": { "type": "number", "title": "Acos", "description": "Advertising cost of sales (inverse of ROAS) during the selected period.", "default": 0 }, "id": { "type": "string", "title": "Id", "description": "The external vendor ID used by the marketplace." }, "vendorName": { "title": "Vendorname", "description": "The vendor name.", "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "type": "object", "required": [ "adSpend", "cpc", "ctr", "conversionRate", "impressions", "chargedImpressions", "clicks", "chargedClicks", "purchaseCount", "purchaseRevenue", "roas", "id" ], "title": "PublicVendorsKpis", "description": "Response for analytics KPIs using external vendor IDs." }, "Advanced_APIs_Purchases": { "properties": { "amount": { "type": "integer", "format": "int64", "title": "Amount", "description": "Amount of money made by purchases over a period of time, in minor units of currency according to ISO 4217." }, "count": { "type": "integer", "format": "int64", "title": "Count", "description": "Amount of purchase events." }, "quantity": { "type": "integer", "format": "int64", "title": "Quantity", "description": "Amount of items purchased." }, "countByProduct": { "title": "Countbyproduct", "description": "Purchase count by product. Available if `count_by_product` is set to `true`.", "oneOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ] } }, "type": "object", "required": [ "amount", "count", "quantity" ], "title": "Purchases", "description": "Aggregation of purchase events." }, "Advanced_APIs_ReportData": { "properties": { "impressions": { "$ref": "#/components/schemas/Advanced_APIs_Events", "description": "How many impressions are attributed to this report item." }, "clicks": { "$ref": "#/components/schemas/Advanced_APIs_Events", "description": "How many clicks are attributed to this report item." }, "purchases": { "$ref": "#/components/schemas/Advanced_APIs_Purchases", "description": "How many purchases are attributed to this report item." } }, "type": "object", "required": [ "impressions", "clicks", "purchases" ], "title": "ReportData", "description": "Clicks, impressions and purchases attributed to this report item so far." }, "Advanced_APIs_ReportDataWithAuctions": { "properties": { "impressions": { "$ref": "#/components/schemas/Advanced_APIs_Events", "description": "How many impressions are attributed to this report item." }, "clicks": { "$ref": "#/components/schemas/Advanced_APIs_Events", "description": "How many clicks are attributed to this report item." }, "purchases": { "$ref": "#/components/schemas/Advanced_APIs_Purchases", "description": "How many purchases are attributed to this report item." }, "auctions": { "$ref": "#/components/schemas/Advanced_APIs_Auctions", "description": "How many auctions are attributed to this report item." } }, "type": "object", "required": [ "impressions", "clicks", "purchases", "auctions" ], "title": "ReportDataWithAuctions", "description": "Auctions information attributed to this report item in addition to normal report data." }, "Advanced_APIs_ReportingDimension": { "type": "string", "enum": [ "impressions", "charged_impressions", "clicks", "charged_clicks", "purchase_count", "purchase_revenue", "ad_spend", "cpc", "cpm", "ctr", "conversion_rate", "roas", "acos", "vendor_id", "vendor_name", "timegroup", "campaign_name", "campaign_id", "status", "ad_format", "active_campaigns", "wallet_name", "days_until_topup", "balance", "quantity" ], "title": "ReportingDimension", "description": "The dimension to order by." }, "Advanced_APIs_ReportingOrderByDirection": { "type": "string", "enum": [ "asc", "desc" ], "title": "ReportingOrderByDirection", "description": "The direction to order by." }, "Advanced_APIs_RequestType": { "type": "string", "enum": [ "advertiser_creation", "campaign_creation", "campaign_update", "user_list_audience_creation" ], "title": "RequestType" }, "Advanced_APIs_RestrictionLevel": { "type": "string", "enum": [ "campaign", "bid" ], "title": "RestrictionLevel" }, "Advanced_APIs_RestrictionTypeResponse": { "properties": { "id": { "type": "integer", "title": "Id", "description": "The ID of the restriction." }, "interactionType": { "$ref": "#/components/schemas/Advanced_APIs_InteractionType", "description": "The interaction type of the restriction." }, "frequencyType": { "$ref": "#/components/schemas/Advanced_APIs_FrequencyType", "description": "The frequency type of the restriction." }, "level": { "$ref": "#/components/schemas/Advanced_APIs_RestrictionLevel", "description": "The level of the restriction." } }, "type": "object", "required": [ "id", "interactionType", "frequencyType", "level" ], "title": "RestrictionTypeResponse", "description": "The type of restriction." }, "Advanced_APIs_RestrictionTypesResponse": { "properties": { "restrictionTypes": { "items": { "$ref": "#/components/schemas/Advanced_APIs_RestrictionTypeResponse" }, "type": "array", "title": "Restrictiontypes" } }, "type": "object", "required": [ "restrictionTypes" ], "title": "RestrictionTypesResponse" }, "Advanced_APIs_Schedule": { "properties": { "startDate": { "type": "string", "format": "date-time", "title": "Startdate", "description": "The start time of the schedule." }, "endDate": { "type": "string", "format": "date-time", "title": "Enddate", "description": "The end time of the schedule." } }, "type": "object", "required": [ "startDate", "endDate" ], "title": "Schedule", "description": "The schedule for the campaign." }, "Advanced_APIs_SegmentSyncAction": { "type": "string", "enum": [ "add", "remove", "replace" ], "title": "SegmentSyncAction" }, "Advanced_APIs_SlotCreateRequestDimensions": { "properties": { "desktop": { "description": "The dimension of the slot for desktop.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_AdConfigSlotDimension" }, { "type": "null" } ] }, "mobile": { "description": "The dimension of the slot for mobile.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_AdConfigSlotDimension" }, { "type": "null" } ] } }, "type": "object", "title": "SlotCreateRequestDimensions", "description": "The dimensions of the slot per device type. At least one of them should be specified." }, "Advanced_APIs_SlotCreateRequestPageItem": { "properties": { "name": { "type": "string", "minLength": 1, "title": "Name", "description": "The name of the landing page.", "examples": [ "Homepage" ] }, "url": { "type": "string", "minLength": 1, "title": "Url", "description": "The url or deep link of the landing page.", "examples": [ "https://app.example.com/main" ] } }, "type": "object", "required": [ "name", "url" ], "title": "SlotCreateRequestPageItem", "description": "An item describing the fields of the landing page to be created." }, "Advanced_APIs_SlotOrderByClause": { "properties": { "dimension": { "$ref": "#/components/schemas/Advanced_APIs_SlotSortDimension" }, "direction": { "$ref": "#/components/schemas/Advanced_APIs_SlotSortDirection" } }, "type": "object", "required": [ "dimension", "direction" ], "title": "SlotOrderByClause", "description": "The order by clause indicates a dimension and a direction to order by the Campaigns response." }, "Advanced_APIs_SlotSortDimension": { "type": "string", "enum": [ "page_url", "page_name", "slot_external_id", "slot_id" ], "title": "SlotSortDimension", "description": "The dimension to order by." }, "Advanced_APIs_SlotSortDirection": { "type": "string", "enum": [ "asc", "desc" ], "title": "SlotSortDirection", "description": "The direction to order by." }, "Advanced_APIs_StatusFilter": { "type": "string", "enum": [ "all", "active", "inactive" ], "title": "StatusFilter", "description": "The status of the vendor." }, "Advanced_APIs_TargetRoasPreference": { "type": "string", "enum": [ "aggressive", "conservative", "moderate", "custom" ], "title": "TargetRoasPreference" }, "Advanced_APIs_TargetWithBid": { "properties": { "target": { "type": "string", "title": "Target", "description": "Target for the campaign" }, "bidAmount": { "title": "Bidamount", "description": "Bid amount for the target", "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "isActive": { "title": "Isactive", "description": "Flag to indicate if the bid is active or not", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "type": "object", "required": [ "target" ], "title": "TargetWithBid" }, "Advanced_APIs_TransactionType": { "type": "string", "enum": [ "Ad spend", "Ad credit" ], "title": "TransactionType", "description": "The type of transaction." }, "Advanced_APIs_Type": { "type": "string", "enum": [ "daily", "weekly", "monthly", "total" ], "title": "Type", "description": "The periodicity of the budget." }, "Advanced_APIs_UpdateOffsiteCampaignRequest": { "properties": { "name": { "title": "Name", "description": "The name of the campaign", "oneOf": [ { "type": "string", "maxLength": 35, "pattern": "^[^;\"'<>\\#\\|,\\\r\\\n\\\\]*[^;\"'<>\\#\\|,\\\r\\\n\\\\\\s][^;\"'<>\\#\\|,\\\r\\\n\\\\]*$" }, { "type": "null" } ] }, "startDate": { "title": "Startdate", "description": "The start date of the campaign", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endDate": { "title": "Enddate", "description": "The end date of the campaign", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "budget": { "title": "Budget", "description": "The budget of the campaign", "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "status": { "description": "The status of the campaign", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_OffsiteCampaignStatus" }, { "type": "null" } ] }, "locationIds": { "title": "Locationids", "description": "The location ids to target. Google ads geo target ids can be found here: https://developers.google.com/google-ads/api/data/geotargets. Facebook region ids can be found here: https://developers.facebook.com/docs/marketing-api/audiences/reference/targeting-search#regions", "oneOf": [ { "items": { "type": "string" }, "type": "array", "minItems": 1 }, { "type": "null" } ] }, "productIds": { "title": "Productids", "description": "The product ids to target. These are the product ids from the catalog. When updating product_ids, you must provide at least 5 products. Use an empty list [] to select all products, or None to keep the current selection.", "oneOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ] }, "audienceIds": { "title": "Audienceids", "description": "The audience ids to target. These are the audience ids from each DSP platform. Currently, only one audience is supported. If not provided, no audience won't be updated. If empty, the audience will be removed.", "examples": [ [ "123456" ] ], "oneOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 1 }, { "type": "null" } ] } }, "type": "object", "title": "UpdateOffsiteCampaignRequest" }, "Advanced_APIs_UpdateProductsRequest": { "properties": { "products": { "items": { "$ref": "#/components/schemas/Advanced_APIs_PartialProductUpdate" }, "type": "array", "maxItems": 500, "minItems": 1, "title": "Products", "description": "The products to update." } }, "type": "object", "required": [ "products" ], "title": "UpdateProductsRequest" }, "Advanced_APIs_UserRole": { "type": "string", "enum": [ "admin", "sales", "marketplace_finance", "marketplace_analyst", "marketplace_developer", "vendor_admin", "vendor_analyst" ], "title": "UserRole" }, "Advanced_APIs_UserServiceVendorRole": { "type": "string", "enum": [ "admin", "analytics" ], "title": "UserServiceVendorRole" }, "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_Vendor": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "imageURL": { "title": "Imageurl", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "vendor_role": { "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_UserServiceVendorRole" }, { "type": "null" } ] }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" }, "merchant_center_id": { "title": "Merchant Center Id", "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "globalId": { "title": "Globalid", "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "name", "imageURL", "vendor_role" ], "title": "Vendor" }, "Advanced_APIs_VendorBalance": { "properties": { "vendorId": { "type": "string", "title": "Vendorid", "description": "The vendor ID." }, "balance": { "type": "integer", "title": "Balance", "description": "The balance for the vendor in minor units of currency according to ISO 4217." } }, "type": "object", "required": [ "vendorId", "balance" ], "title": "VendorBalance" }, "Advanced_APIs_VendorBalancesResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/Advanced_APIs_VendorBalance" }, "type": "array", "title": "Items", "description": "The list of vendor balances." } }, "type": "object", "required": [ "items" ], "title": "VendorBalancesResponse" }, "Advanced_APIs_VendorBillingMode": { "type": "string", "enum": [ "post", "pre" ], "title": "VendorBillingMode" }, "Advanced_APIs_VendorInvite": { "properties": { "vendorId": { "type": "string", "title": "Vendorid", "description": "The ID of the vendor." }, "vendorEmail": { "type": "string", "format": "email", "title": "Vendoremail", "description": "The email of the vendor." }, "targetUserRole": { "$ref": "#/components/schemas/Advanced_APIs_UserRole", "description": "The role to assign to the invited vendor user.", "default": "vendor_analyst" } }, "type": "object", "required": [ "vendorId", "vendorEmail" ], "title": "VendorInvite" }, "Advanced_APIs_VendorInvitesRequest": { "properties": { "invites": { "items": { "$ref": "#/components/schemas/Advanced_APIs_VendorInvite" }, "type": "array", "maxItems": 500, "minItems": 1, "title": "Invites", "description": "A list of vendors to invite to the Topsort platform. The IDs provided must already exist on the catalog." } }, "type": "object", "required": [ "invites" ], "title": "VendorInvitesRequest" }, "Advanced_APIs_VendorWallet": { "properties": { "walletId": { "type": "string", "format": "uuid", "title": "Walletid" }, "name": { "type": "string", "title": "Name" }, "balance": { "type": "number", "title": "Balance" } }, "type": "object", "required": [ "walletId", "name", "balance" ], "title": "VendorWallet" }, "Advanced_APIs_VendorWallets": { "properties": { "wallets": { "items": { "$ref": "#/components/schemas/Advanced_APIs_VendorWallet" }, "type": "array", "title": "Wallets", "description": "List of wallets available for the vendor." } }, "type": "object", "required": [ "wallets" ], "title": "VendorWallets" }, "Advanced_APIs_VendorsByIdRequest": { "properties": { "ids": { "items": { "type": "string", "maxLength": 255, "minLength": 1 }, "type": "array", "minItems": 1, "title": "Ids", "description": "The IDs of the vendors to delete.", "examples": [ [ "XljzxWf8sfqF", "eBbIYS16vZV3" ], [ "VENDOR-456" ], [ "5c30432c-1186-4389-a2f1-577bb8dd5180" ] ] } }, "type": "object", "required": [ "ids" ], "title": "VendorsByIdRequest" }, "Advanced_APIs_VendorsRequest": { "properties": { "vendors": { "items": { "$ref": "#/components/schemas/Advanced_APIs_CatalogVendor" }, "type": "array", "maxItems": 500, "minItems": 1, "title": "Vendors", "description": "Create or replace one or more vendors in the catalog." } }, "type": "object", "required": [ "vendors" ], "title": "VendorsRequest" }, "Advanced_APIs_VendorsResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "response": { "items": { "$ref": "#/components/schemas/Advanced_APIs_CatalogVendor" }, "type": "array", "title": "Response", "description": "Array of vendors. Can be empty when the catalog or requested page contains no vendors." } }, "type": "object", "required": [ "hasMore", "response" ], "title": "VendorsResponse" }, "Advanced_APIs_WebhookCreateRequest": { "properties": { "url": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Url", "description": "The URL to send the webhook event to." }, "channel": { "$ref": "#/components/schemas/Advanced_APIs_Channel", "description": "The channel that triggers this webhook." }, "secret": { "type": "string", "maxLength": 32, "title": "Secret", "description": "Webhook secret to be used in signature generation. If missing, it'll be randomly generated.", "examples": [ "t948Lf__j1WNwcAxZpsz8Q" ] } }, "type": "object", "required": [ "url", "channel" ], "title": "WebhookCreateRequest" }, "Advanced_APIs_WebhookEventResponse": { "properties": { "channel": { "$ref": "#/components/schemas/Advanced_APIs_Channel", "description": "The channel that triggered the webhook" }, "payload": { "additionalProperties": true, "type": "object", "title": "Payload", "description": "Most recent version of the model (e.g. campaign payload)" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "Event time" }, "id": { "type": "string", "title": "Id", "description": "Unique id of the event. This can be used for event de-duplication" } }, "type": "object", "required": [ "channel", "payload", "timestamp", "id" ], "title": "WebhookEventResponse" }, "Advanced_APIs_WebhookResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Id of the webhook." }, "marketplaceId": { "type": "string", "format": "uuid", "title": "Marketplaceid", "description": "The marketplace ID." }, "url": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Url", "description": "The URL to send the webhook event to." }, "channel": { "$ref": "#/components/schemas/Advanced_APIs_Channel", "description": "The channel that triggers this webhook." }, "secret": { "type": "string", "title": "Secret", "description": "Webhook secret to be used in signature generation." }, "disabledAt": { "title": "Disabledat", "description": "When set, the webhook is disabled and will not receive events.", "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "marketplaceId", "url", "channel", "secret" ], "title": "WebhookResponse" }, "Advanced_APIs_WebhookUpdateRequest": { "properties": { "url": { "title": "Url", "description": "The URL to send the webhook event to.", "oneOf": [ { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri" }, { "type": "null" } ] }, "channel": { "description": "The channel that triggers this webhook.", "oneOf": [ { "$ref": "#/components/schemas/Advanced_APIs_Channel" }, { "type": "null" } ] }, "secret": { "title": "Secret", "description": "Webhook secret to be used in signature generation.", "examples": [ "t948Lf__j1WNwcAxZpsz8Q" ], "oneOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] } }, "type": "object", "title": "WebhookUpdateRequest" }, "Advanced_APIs_WebhooksResponse": { "properties": { "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Flag that indicates whether more results are available. `true` indicates there is a next page of results. `false` indicates this response contains the last page of results." }, "nextPage": { "title": "Nextpage", "description": "Pagination cursor. Provide this value as a `next_page` query parameter in a new request to retrieve the next page of results.", "examples": [ "SSBzb2xlbW5seSBzd2VhciB0aGF0IEkgYW0gdXAgdG8gbm8gZ29vZAo=" ], "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "webhooks": { "items": { "$ref": "#/components/schemas/Advanced_APIs_WebhookResponse" }, "type": "array", "title": "Webhooks", "description": "List of webhooks" } }, "type": "object", "required": [ "hasMore", "webhooks" ], "title": "WebhooksResponse" }, "Advanced_APIs_CampaignReportByProductOrderByDimension": { "type": "string", "description": "Dimension to order by for the campaign report by product endpoint. Only these values are accepted; other ReportingDimension values (e.g. vendor_id, campaign_id) return 422.", "enum": [ "impressions", "charged_impressions", "clicks", "charged_clicks", "purchase_count", "purchase_revenue", "ad_spend", "cpc", "ctr", "conversion_rate", "roas" ], "title": "CampaignReportByProductOrderByDimension" } }, "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" }, "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" } } }, "x-mint": { "mcp": { "enabled": true } } }