Product Overview

Quick Reference

Endpoint Summary

This table provides quick access to the product, variant, and media query services described on this page. Detailed request and response fields are included in the relevant sections.

No	Service	Endpoint
1	Product Query	`POST /api/v2/query/products`
2	Variant Query	`POST /api/v1/query/variants`
3	Product Media List	`POST /api/v1/query/product-media-list`
4	Variant Media List	`POST /api/v1/query/variant-media-list`

General Usage

General Technical Information

Authentication

For the PIM query endpoints on this page, authentication information is sent in the request body. clientId and appKey fields are required.

Header Usage

In requests, Accept and Content-Type header information must be used. Supported values are listed per endpoint on the relevant API Reference screen.

Pagination

pageIndex starts from 0. To move to subsequent pages, the value can be increased and the request can be sent again.

Filtering

Filter fields vary by endpoint. The query scope can be narrowed using fields such as ID, code, name, category, brand, and status.

Response Structure

Records are returned in the result field, while the total record count is returned in the totalCount field.

1. Product Query — `POST /api/v2/query/products`

This endpoint is used to retrieve the product data you see on the Products list page and the Product Detail screen in the PIM UI through the API.

Info

This endpoint is provided in API v2 version. Do not forget to specify the version number as v2 in the URL.

Technical Note

GetProductsis used to query the main catalog record at product level.
The product record may be returned together with related data fields such as category, brand, attributes, options, variants, images, documents, and prices.
For sales-specific sub-breakdowns of the product, it should be evaluated together with the GetVariants endpoint.
In integrations, product matching generally uses the ProductId, Code and IntegrationCode fields.

Endpoint-Specific Query Parameters

API Parameter	Type	PIM UI Equivalent / Meaning	Description
`ProductIds`	`array (integer)`	Product System ID List	Filters by the unique system IDs of the product.
`Names`	`array (string)`	Product Name Filter	Product Name field. This is an exact-match filter and corresponds to the product name column in the UI.
`IncludesNames`	`array (string)`	Product Names Containing	Returns product names that contain the specified texts (include filter).
`ExcludesNames`	`array (string)`	Excluded Product Names	Products containing the specified texts are excluded from the results.
`Codes`	`array (string)`	Product Code Filter	Filters by the Product Code column.
`IncludesCodes`	`array (string)`	Product Codes Containing	Returns products that contain the specified codes.
`ExcludesCodes`	`array (string)`	Excluded Product Codes	Products containing the specified codes are excluded from the results.
`IntegrationCodes`	`array (string)`	Integration Code Filter	Filters by the product detail Integration Code field.
`CategoryIds`	`array (integer)`	Category ID Filter	Filters by the categories in the Category column in the UI.
`ExcludesCategoryIds`	`array (integer)`	Excluded Categories	Excludes products belonging to the specified categories from the results.
`IncludeCategoryNames`	`array (string)`	Include by Category Name	Includes products by category name.
`TrademarkIds`	`array (integer)`	Brand ID Filter	Filters by the Brand field.
`ExcludesTrademarkIds`	`array (integer)`	Excluded Brands	Excludes products belonging to the specified brands from the results.
`IncludeTrademarkNames`	`array (string)`	Include by Brand Name	Includes products by brand name.
`IncludeVariantCode`	`array (string)`	Include by Variant Code	Returns products with the specified variant codes.

API Response Parameters and UI Equivalents

Each Product object in the Result array contains the following fields:

API Response Field	Type	PIM UI Equivalent / Field Name	Description
`ProductId`	`integer`	Product System ID	Unique product number assigned by the system.
`Name`	`string`	Product Name	Main product name displayed in the product list and detail page.
`Code`	`string`	Product Code	Unique product code displayed on the detail page.
`IntegrationCode`	`string`	Integration Code	Code used for matching with external systems.
`ShortDescription`	`string`	Short Description	Short description field on the product detail page.
`LongDescription`	`string`	Long Description	Detailed description entered in the rich text editor on the product detail page.
`Unit`	`string`	Unit	The product measurement unit (piece, kg, etc.).
`Type`	`integer`	Product Type	Product type classification.
`TaxRate`	`decimal`	Tax Rate	VAT rate applied to the product.
`Link`	`string`	Link / URL	External link for the product.
`ParentId`	`integer?`	Parent Product ID	Reference to the parent product in the variation tree.
`Variants`	`array`	Variants tab	List of all variants linked to the product.
`Pictures`	`array`	Images tab	List of images linked to the product.
`Documents`	`array`	Documents tab	List of documents linked to the product.
`Properties`	`array`	Attributes tab	List of custom fields (properties) defined for the product.
`Tags`	`array`	Tags	List of tags assigned to the product.
`CategoryProducts`	`array`	Categories column	List of categories the product belongs to.
`TrademarkProducts`	`array`	Brands field	List of brands associated with the product.
`Translations`	`array`	Multilingual Values	Translations of the product name and descriptions in different languages.
`Codes`	`array`	Product Codes	Additional codes defined for the product (barcode, EAN, etc.).
`Prices`	`array`	Prices tab	Price information defined for the product.
`Dimensions`	`array`	Dimensions	Product dimension information (width, length, height, etc.).
`Packaging`	`array`	Packaging	Product packaging information.
`Warranties`	`array`	Warranty	Warranty information.
`Status`	`integer`	Status column	`1` = Active, `-1` = Passive. Status label in the UI.
`Created`	`datetime`	Creation Date	Date the product was added to the system.
`Updated`	`datetime?`	Update Date column	Last update date.

Usage Guide on the UI

Product List → API Mapping: The columns of the product table in the UI (Product Name, Category, Variant Count, Code, Tags, Update Date, Status) are fed directly from the response fields above.
Include / Exclude Filters: In the UI filter panel, you can select a category or brand and use "Include / Exclude". The API equivalents are IncludesCategoryIds / ExcludesCategoryIds and IncludesTrademarkIds / ExcludesTrademarkIds parameters.
Multilingual: Translations entered in different languages in the product name tabs in the UI are returned from the API in the Translations array. Each translation has a Culture field that specifies the language code (e.g., tr, en).

2. Variant Query — `POST /api/v1/query/variants`

This endpoint is used to retrieve the variant data listed in the Product Detail → Variants tab in the PIM UI through the API. It also returns images and documents for each variant.

Technical Note

GetVariants is used to query the product variant records that are subject to sale.
The variant level is associated with commercial data such as inventory, price, barcode, option value, media, and sales status.
A product can have more than one variant; the relationship is tracked through the ProductId field.
The return of Pictures and Documents fields in the response makes variant-based media control easier.

Endpoint-Specific Query Parameters

API Parameter	Type	PIM UI Equivalent / Meaning	Description
`ProductIds`	`array (integer)`	Product System ID List	Specifies which products the variants to be retrieved belong to.
`VariantIds`	`array (integer)`	Variant System ID List	Used to filter specific variants by ID.
`Names`	`array (string)`	Variant Name Filter	Exact-match filter by variant name.
`IncludesNames`	`array (string)`	Variant Names Containing	Returns variant names containing the specified texts.
`ExcludesNames`	`array (string)`	Excluded Variant Names	Excludes variants containing the specified texts.
`Codes`	`array (string)`	Variant Code Filter	Filters by the variant detail Variant Code field.
`IncludesCodes`	`array (string)`	Variant Codes Containing	Returns variants containing the specified codes.
`ExcludesCodes`	`array (string)`	Excluded Variant Codes	Excludes variants containing the specified codes.
`CategoryIds`	`array (integer)`	Category ID Filter	Returns variants of products belonging to the specified categories.
`TrademarkIds`	`array (integer)`	Brand ID Filter	Returns variants of products belonging to the specified brands.
`IncludeTrademarkNames`	`array (string)`	Include by Brand Name	Includes variants by brand name.
`IncludeCategoryNames`	`array (string)`	Include by Category Name	Includes variants by category name.

API Response Parameters and UI Equivalents

Each ProductVariantWithMedia object in the Result array contains the following fields:

API Response Field	Type	PIM UI Equivalent / Field Name	Description
`VariantId`	`integer`	Variant System ID	Unique variant number assigned by the system.
`ProductId`	`integer`	Product System ID	ID of the parent product the variant belongs to.
`Code`	`string`	Variant Code	Unique code on the variant detail page.
`IntegrationCode`	`string`	Integration Code	External system matching code.
`Name`	`string`	Variant Name	Name displayed in the variant list and detail.
`ShortDescription`	`string`	Short Description	Short description of the variant.
`LongDescription`	`string`	Long Description	Detailed description of the variant.
`SourceItemId`	`integer`	Source Item ID	Reference to the source of the variant.
`Product`	`object`	Related Product	Information about the parent product the variant belongs to.
`Pictures`	`array`	Images (Media Management)	List of images belonging to the variant (including document details).
`Documents`	`array`	Documents (Media Management)	List of documents belonging to the variant (including document details).
`OptionValues`	`array`	Option Values	Option values assigned to the variant (Color: Red, Size: M, etc.).
`Tags`	`array`	Tags	Tags assigned to the variant.
`Properties`	`array`	Attributes	Custom fields defined for the variant.
`Translations`	`array`	Multilingual Values	Translations of the variant name and descriptions in different languages.
`Codes`	`array`	Variant Codes	Additional codes defined for the variant.
`Prices`	`array`	Prices	Price information defined for the variant.
`Status`	`integer`	Status	`1` = Active, `-1` = Passive.
`Created`	`datetime`	Creation Date	Date the variant was added to the system.
`Updated`	`datetime?`	Update Date	Last update date.

Usage Guide on the UI

Variant Images and Documents: In the UI, the Media Management tab on the variant detail page shows images and documents that are now returned directly as POST /variants response Pictures and Documents arrays.
Option Values: Options such as color/size displayed on variant cards in the UI are returned from the API in the OptionValues array.

3. Product Media List — `POST /api/v1/query/product-media-list`

This endpoint is used to retrieve the images and documents you see in the Product Detail → Media Management tab in the PIM UI for the specified products in bulk.

Technical Note

The product media list is used to retrieve image and document relationships defined at product level in bulk.
Pictures represents product images, while Documents represents product documents.
IsCover field can be used to determine the cover image of the product.
SortOrder field can be used to interpret the display order of images and documents.

Endpoint-Specific Query Parameters

API Parameter	Type	PIM UI Equivalent / Meaning	Description
`ProductIds`	`array (integer)`	Product System ID List	Unique system IDs of the products whose media information you want to retrieve.
`ProductCodes`	`array (string)`	Product Code List	Filters by the Product Codedisplayed on the product detail screen (e.g., `PRD-001`).

API Response Parameters and UI Equivalents

Each ProductMedia object in the Result array contains two sub-arrays:

Images (`Pictures`)

API Response Field	Type	PIM UI Equivalent / Field Name	Description
`PictureId`	`integer`	Image System ID	Unique ID assigned to the image.
`ProductId`	`integer`	Product System ID	ID of the product the image belongs to.
`PictureKey`	`string`	Image Unique Key	Storage key of the image.
`ImageUrl`	`string`	Image Preview URL	Thumbnail link of the image listed in the UI.
`DocumentId`	`string`	DMS Document ID	File ID in the Document Management System.
`Alt`	`string`	Alternative Text (Alt Text)	Image description text used for SEO.
`IsCover`	`boolean`	"Set as cover image" Option	Cover image status selected with a radio button in the UI. `true` means it is the cover image.
`SortOrder`	`integer`	Sort Order Number	Display order determined by drag-and-drop in the UI.
`Code`	`string`	Image Code	Identifier code of the image.
`SourceCode`	`string`	Source Code	Code of the image in the source system.
`DocumentName`	`string`	File Name	Original name of the image file.
`SelectionType`	`string`	Selection Type	Classification of the file as an image or document.
`TypeCode`	`string`	Format	File format extension (e.g., `JPEG`, `PNG`).
`Link`	`string`	Image Download Link	Direct access URL of the image.
`Status`	`integer`	Active / Passive Switch	`1` = Active, `-1` = Passive.
`Created`	`datetime`	Creation Date	Date the image was uploaded.
`Updated`	`datetime?`	Update Date	Last update date.

Documents (`Documents`)

API Response Field	Type	PIM UI Equivalent / Field Name	Description
`ProductDocumentId`	`integer`	Document Relation ID	Unique number for the relationship between the document and the product.
`ProductId`	`integer`	Product System ID	ID of the product the document belongs to.
`DocumentId`	`string`	DMS Document ID	Unique file identity in the Document Management System.
`Code`	`string`	Document Code	Integration or display code assigned to the document.
`Name`	`string`	Document Name	File name displayed in bold in the document row in the UI.
`IntegrationCode`	`string`	Integration Code	External system matching code.
`Path`	`string`	File Path	Location of the file on the server.
`SortOrder`	`integer`	Sort Order Number	Sort value determined by drag-and-drop.
`DocumentName`	`string`	File Name	Original name of the file.
`SelectionType`	`string`	Selection Type	File classification.
`TypeCode`	`string`	Format	In the UI document row, "Format" the file type under the heading (e.g., `PDF`, `XLSX`).
`Tags`	`array`	Document Tags	Tags assigned to the document.
`Status`	`integer`	Active / Passive Switch	`1` = Active, `-1` = Passive.
`Created`	`datetime`	Creation Date	Date the document was uploaded.
`Updated`	`datetime?`	Update Date	Last update date.

Usage Guide on the UI

Cover Image (IsCover): Only one cover image can be selected for a single product on the UI. The image returned from the API as IsCover: true can be positioned as the "Main Image" in your application.
Image Sorting (SortOrder): When you drag and drop image cards in the PIM UI, this field is updated in the background. It is recommended to display images sorted by SortOrder value in ascending order.
Format Information (TypeCode): The file type icons displayed next to documents in the interface (PDF, Excel, etc.) are shown directly based on the TypeCode value.
Bulk Media Retrieval: This endpoint can be called with multiple ProductIds or ProductCodes values to retrieve media information for multiple products in a single request.

4. Variant Media List — `POST /api/v1/query/variant-media-list`

In the PIM UI, Variant Detail → Media Management tab for the specified variants in bulk.

Technical Note

The variant media list is used to query image and document relationships specific to product variants.
Variant-based media enables variants such as different colors, sizes, or capacities under the same product to be managed with different images.
VariantId and VariantCode fields can be used to match media records with the correct variant.
Media records should be evaluated together with cover image, sorting, and active/passive status controls.

Endpoint-Specific Query Parameters

API Parameter	Type	PIM UI Equivalent / Meaning	Description
`VariantIds`	`array (integer)`	Variant System ID List	Unique system IDs of the variants whose media information you want to retrieve.
`VariantCodes`	`array (string)`	Variant Code List	Filters by the Variant Codedisplayed on the variant detail screen.

API Response Parameters and UI Equivalents

The Result array has the same ProductMedia structure as the Product Media List. For field descriptions of the returned Pictures and Documents arrays, see the Section 3 table above.

Usage Guide on the UI

Variant Media vs. Product Media: In the UI, the Media Management tab on the variant detail page displays both variant-specific images and the main product images together. This endpoint returns only the media items belonging to the specified variant(s).
The logic for cover image, sorting, and format information is exactly the same as in the Product Media List.

Error Handling

Common Error Cases

The table below is prepared for the common error cases that may apply to the endpoints on this page. After endpoint-specific error messages are verified by the software team, they should be added to the Error Message column.

HTTP Status	Status	Error Message
`400`	Bad Request
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found
`422`	Unprocessable Entity
`429`	Too Many Requests
`500`	Internal Server Error

Endpoint Summary

General Technical Information

1. Product Query — POST /api/v2/query/products

Endpoint-Specific Query Parameters

API Response Parameters and UI Equivalents

Usage Guide on the UI

2. Variant Query — POST /api/v1/query/variants

Endpoint-Specific Query Parameters

API Response Parameters and UI Equivalents

Usage Guide on the UI

3. Product Media List — POST /api/v1/query/product-media-list

Endpoint-Specific Query Parameters

API Response Parameters and UI Equivalents

Images (Pictures)

Documents (Documents)

Usage Guide on the UI

4. Variant Media List — POST /api/v1/query/variant-media-list

Endpoint-Specific Query Parameters

API Response Parameters and UI Equivalents

Usage Guide on the UI

Common Error Cases

1. Product Query — `POST /api/v2/query/products`

2. Variant Query — `POST /api/v1/query/variants`

3. Product Media List — `POST /api/v1/query/product-media-list`

Images (`Pictures`)

Documents (`Documents`)

4. Variant Media List — `POST /api/v1/query/variant-media-list`