> ## Documentation Index > Fetch the complete documentation index at: https://docs.topsort.com/llms.txt > Use this file to discover all available pages before exploring further. # Upsert Products > Upsert products. ## OpenAPI ````yaml /openapi.json put /public/v1/catalog-search-service/catalogs/products openapi: 3.1.0 info: title: Topsort Endpoints v2 API Reference description: > In order for a storefront to be able to run auctions in Topsort and report auction-related events back to Topsort, both the `/v2/auctions` and `/v2/events` endpoints must be integrated. Below are the endpoint and model definitions for each. contact: email: wicha@topsort.com license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html x-logo: url: https://assets.topsort.com/Topsort_logo_icon_dark.svg backgroundColor: '#fff' altText: Topsort version: 2.0.0 servers: - url: https://api.topsort.com description: Base API URL security: [] tags: - name: Auctions description: >- An auction determines which products should be promoted based on the vendors' bids. - name: Events description: >- Events are sent to Topsort as part of the attribution and reporting journey. - name: Toptimize description: > An out-of-the-box solution for prediction, ranking, retrieval, and other elements of ad selection. - name: Toppie API description: Toppie management API. - name: Campaign API description: Full-featured campaign management API for banners and sponsored listings. - name: Catalog API description: Products catalog management API. - name: Billing API description: Marketplace and Vendor Billing management API. - name: Reporting API description: Marketplace, Vendor, Campaign, and product reporting API. - name: Invitation API description: Vendor invitations management API. - name: User API description: User management API. - name: Webhooks API description: Webhooks API that allows event-driven automation. - name: Assets API description: Assets management API. - name: Segments Service description: Segments Service. - name: Forecasting Service description: Toptimize Forecasting Service. - name: Offsite Ads API description: Offsite Ads API that allows to manage offsite ads campaigns. - name: Media API description: Ad configuration API. paths: /public/v1/catalog-search-service/catalogs/products: put: tags: - Catalog API summary: Upsert Products description: Upsert products. operationId: upsert_products 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' security: - Advanced_APIs_HTTPBearer: [] components: schemas: 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_HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/Advanced_APIs_ValidationError' type: array title: Detail type: object title: HTTPValidationError 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. 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' 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_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_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. securitySchemes: Advanced_APIs_HTTPBearer: type: http description: >- A valid API key generated in Topsort's UI. Use the TSE API key if calling auctions or events API, otherwise use the TSC API key. scheme: bearer ````