openapi: 3.1.0 info: title: Product Management Service version: (dev) description: API for managing merchant product catalog data. servers: - url: https://api-1.test.logitrail.com description: Test / Development Server - url: https://api-1.logitrail.com description: Production Server paths: /v1/products/statistics: get: summary: Get Product Statistics description: >- Provides statistics about product master data in the Logitrail's database. operationId: GetProductStatistics security: - idp: - products:read parameters: - in: header name: x-logitrail-merchant-id schema: type: string minLength: 1 description: Logitrail's Merchant ID. required: true description: Logitrail's Merchant ID. responses: '200': description: Product Statistics content: application/json: schema: type: object properties: product_statistics: type: object properties: active_products_count: type: number minimum: 0 title: Count of active products inactive_products_count: type: number minimum: 0 title: Count of inactive/deleted products required: - active_products_count - inactive_products_count additionalProperties: false required: - product_statistics additionalProperties: false '400': description: Validation error, see response body for details. content: application/json: schema: type: object properties: message: type: string description: A brief, human readable error message. error_code: type: string const: VALIDATION_ERROR description: Reason of the error. validation_errors: type: array items: {} description: An array of validation error details. required: - message - error_code - validation_errors additionalProperties: false /v1/products: get: summary: List Products description: >- Returns a paginated list of merchant products. Filters AND-merge; `q` provides unified search across SKU prefix, GTIN prefix, vendor SKU prefix, vendor barcode prefix and (for length ≥ 3) product name substring. operationId: ListProducts security: - idp: - products:read parameters: - in: header name: x-logitrail-merchant-id schema: type: string minLength: 1 description: Logitrail's Merchant ID. required: true description: Logitrail's Merchant ID. - in: query name: q schema: description: >- Unified search phrase (minimum 2 characters). Matches case-insensitive anchored prefix on SKU, GTIN, vendor SKU and vendor barcode; for length ≥ 3 also matches a case-insensitive substring on the product name (incl. translations). At lengths 2–3 the name is intentionally excluded — unanchored regex on `n` would explode the candidate set. type: string minLength: 2 description: >- Unified search phrase (minimum 2 characters). Matches case-insensitive anchored prefix on SKU, GTIN, vendor SKU and vendor barcode; for length ≥ 3 also matches a case-insensitive substring on the product name (incl. translations). At lengths 2–3 the name is intentionally excluded — unanchored regex on `n` would explode the candidate set. - in: query name: sku schema: description: Exact match on the merchant SKU (`m_id`). type: string minLength: 1 description: Exact match on the merchant SKU (`m_id`). - in: query name: gtin schema: description: >- Exact match on GTIN — matches either the primary `gtin` or the secondary `s_gtin`. type: string minLength: 1 description: >- Exact match on GTIN — matches either the primary `gtin` or the secondary `s_gtin`. - in: query name: status schema: description: >- Filter by status. Defaults to `active` so deleted products are hidden by default; pass `deleted` explicitly to retrieve them. type: string enum: - active - deleted description: >- Filter by status. Defaults to `active` so deleted products are hidden by default; pass `deleted` explicitly to retrieve them. - in: query name: on_shelf_minimum_count schema: description: >- Restrict results to products whose on-shelf (`inventory.in_stock`) count is at least the given value. Cross-service post-filter — the page is shrunk after the inventory join, so the returned page may be smaller than `limit`. type: integer minimum: 0 maximum: 9007199254740991 description: >- Restrict results to products whose on-shelf (`inventory.in_stock`) count is at least the given value. Cross-service post-filter — the page is shrunk after the inventory join, so the returned page may be smaller than `limit`. - in: query name: offset schema: default: 0 description: Pagination offset. Defaults to 0. type: integer minimum: 0 maximum: 9007199254740991 description: Pagination offset. Defaults to 0. - in: query name: limit schema: default: 100 description: >- Maximum number of products to return. Defaults to 100, capped at 500. type: integer minimum: 1 maximum: 500 description: >- Maximum number of products to return. Defaults to 100, capped at 500. responses: '200': description: Paginated list of products. content: application/json: schema: type: object properties: products: type: array items: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the product. sku: type: string description: >- Merchant's own SKU. The SKU must be unique within the merchant and active products. gtin: description: >- GTIN (EAN / Barcode) of the product. This value is used to identify the product at the warehouse. type: string name: description: >- Name of the product in merchant's primary language. If you need translations, provide them in `name_translations` field. type: string name_translations: description: Name of the product in different languages. type: object properties: fi: type: string en: type: string sv: type: string ee: type: string additionalProperties: false status: default: active type: string enum: - active - deleted secondary_gtin: anyOf: - type: string - type: 'null' hs_code: anyOf: - type: string - type: 'null' description: HS code (Harmonized System code) of the product. fulfillment_by: default: logitrail title: Fulfillment route description: >- Default fulfillment route for this product. `logitrail` means Logitrail's warehouse picks and ships order lines for the product; `merchant` means the merchant fulfills the line themselves and Logitrail does not pick or ship it. Individual order lines may override this per line; when an order line omits the value, it falls back to this product-level default. Products that pre-date this field default to `logitrail`. type: string enum: - logitrail - merchant origin_country_code: anyOf: - type: string pattern: ^[A-Z]{2}$ - type: 'null' description: >- Country code (ISO 3166-1 alpha-2) of the product's origin. default_purchase_price: anyOf: - type: number - type: 'null' flags: type: array items: type: string weight_g: type: number minimum: 1 dimensions_mm: anyOf: - minItems: 3 maxItems: 3 type: array items: type: number minimum: 0 - type: 'null' description: >- Dimensions (in mm) of the product. Three dimensions are required. If dimensions are not known, use null or [0,0,0]. components: description: Product component definition. anyOf: - type: array items: type: object properties: product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: >- Logitrail's internal technical ID of the product. name: description: >- Name of the sub-product in its merchant's primary language. Embedded for display convenience; omitted if the sub-product cannot be resolved. type: string sku: description: >- SKU of the sub-product. Null when the sub-product has no SKU; omitted if the sub-product cannot be resolved. anyOf: - type: string - type: 'null' required: - id additionalProperties: false description: Reference to the sub-product. amount: type: integer minimum: 1 maximum: 9007199254740991 description: >- Amount of sub-products to be shipped when a main product is ordered. required: - product - amount additionalProperties: false - type: 'null' batch_packages: description: Batch package types of the product. type: array items: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: Internal Technical ID of the batch package. name: type: string description: Name/title of the batch package size: type: number description: How many items the batch package contains? merchant_remarks: type: string description: Remarks regarding the batch package gtin: type: string description: GTIN (Barcode) of the batch package. dimensions_mm: description: >- Dimensions (in mm) of the batch package. Three dimensions are required. minItems: 3 maxItems: 3 type: array items: type: number minimum: 1 weight_g: description: Weight (in grams) of the batch package. type: number minimum: 1 required: - size additionalProperties: false vendor_skus: maxItems: 20 type: array items: type: object properties: vendor: type: object properties: name: type: string minLength: 1 maxLength: 80 description: >- Free-text identifier for the supplier (e.g. 'Supplier Oy'). Trimmed; case-sensitive. Treated as opaque — there is no vendor catalog yet. required: - name additionalProperties: false description: >- Vendor reference. Today only `name` is carried; a future vendor-catalog ticket may add `id` without renaming this field. vendor_sku: type: string minLength: 1 maxLength: 64 description: >- Supplier's own product code as printed on the parcel / supplier order. Trimmed; case-sensitive. vendor_barcode: type: string minLength: 1 maxLength: 64 description: >- Supplier-provided barcode (when distinct from the merchant's own GTIN). Trimmed; case-sensitive. required: - vendor - vendor_sku additionalProperties: false description: >- Supplier-side identifiers for this product. Empty array means no supplier codes are recorded; omit to leave the existing array untouched (on writes) or to inherit from the product profile (on inbound-shipment line items). inventory: description: >- Current inventory snapshot for this product, owned by product-inventory-service. Null when no ProductInventoryDocument exists for the product yet (e.g. brand new product without any incoming articles). Omitted from the response when the listing was retrieved without joining inventory data. anyOf: - type: object properties: inventory: type: object properties: available: type: number minimum: 0 description: >- Units available for new reservations (i.e. on_shelf and not yet reserved). reserved: type: number minimum: 0 description: >- Units already reserved by orders (real or synthetic placeholders). demand: type: number minimum: 0 description: >- Synthetic demand placeholders covering shortage relative to current orders. in_stock: type: number minimum: 0 description: >- Physical units currently on the warehouse shelf. on_hold: type: number minimum: 0 description: >- Units held back from booking (e.g. quality holds or merchant freezes). inbound: type: number minimum: 0 description: >- Units in transit toward the warehouse via inbound shipments. required: - available - reserved - demand - in_stock - on_hold - inbound additionalProperties: false last_movement: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: >- ISO 8601 timestamp of the most recent inventory movement that updated this document. required: - inventory - last_movement additionalProperties: false - type: 'null' required: - id - sku - status - fulfillment_by additionalProperties: false required: - products additionalProperties: false '400': description: Validation error, see response body for details. content: application/json: schema: type: object properties: message: type: string description: A brief, human readable error message. error_code: type: string const: VALIDATION_ERROR description: Reason of the error. validation_errors: type: array items: {} description: An array of validation error details. required: - message - error_code - validation_errors additionalProperties: false post: summary: Create Product description: Creates a new product. operationId: CreateProduct security: - idp: - products:manage parameters: - in: header name: x-logitrail-merchant-id schema: type: string minLength: 1 description: Logitrail's Merchant ID. required: true description: Logitrail's Merchant ID. requestBody: content: application/json: schema: type: object properties: product: type: object properties: sku: type: string description: >- Merchant's own SKU. The SKU must be unique within the merchant and active products. gtin: description: >- GTIN (EAN / Barcode) of the product. This value is used to identify the product at the warehouse. type: string name: description: >- Name of the product in merchant's primary language. If you need translations, provide them in `name_translations` field. type: string name_translations: description: Name of the product in different languages. type: object properties: fi: type: string en: type: string sv: type: string ee: type: string status: default: active type: string enum: - active - deleted secondary_gtin: anyOf: - type: string - type: 'null' hs_code: anyOf: - type: string - type: 'null' description: HS code (Harmonized System code) of the product. fulfillment_by: default: logitrail title: Fulfillment route description: >- Default fulfillment route for this product. `logitrail` means Logitrail's warehouse picks and ships order lines for the product; `merchant` means the merchant fulfills the line themselves and Logitrail does not pick or ship it. Individual order lines may override this per line; when an order line omits the value, it falls back to this product-level default. Products that pre-date this field default to `logitrail`. type: string enum: - logitrail - merchant origin_country_code: anyOf: - type: string pattern: ^[A-Z]{2}$ - type: 'null' description: >- Country code (ISO 3166-1 alpha-2) of the product's origin. default_purchase_price: anyOf: - type: number - type: 'null' flags: type: array items: type: string weight_g: type: number minimum: 1 dimensions_mm: anyOf: - minItems: 3 maxItems: 3 type: array items: type: number minimum: 0 - type: 'null' description: >- Dimensions (in mm) of the product. Three dimensions are required. If dimensions are not known, use null or [0,0,0]. components: description: Product component definition. anyOf: - type: array items: type: object properties: product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: >- Logitrail's internal technical ID of the product. name: description: >- Name of the sub-product in its merchant's primary language. Embedded for display convenience; omitted if the sub-product cannot be resolved. type: string sku: description: >- SKU of the sub-product. Null when the sub-product has no SKU; omitted if the sub-product cannot be resolved. anyOf: - type: string - type: 'null' required: - id description: Reference to the sub-product. amount: type: integer minimum: 1 maximum: 9007199254740991 description: >- Amount of sub-products to be shipped when a main product is ordered. required: - product - amount - type: 'null' batch_packages: description: Batch package types of the product. type: array items: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: Internal Technical ID of the batch package. name: type: string description: Name/title of the batch package size: type: number description: How many items the batch package contains? merchant_remarks: type: string description: Remarks regarding the batch package gtin: type: string description: GTIN (Barcode) of the batch package. dimensions_mm: description: >- Dimensions (in mm) of the batch package. Three dimensions are required. minItems: 3 maxItems: 3 type: array items: type: number minimum: 1 weight_g: description: Weight (in grams) of the batch package. type: number minimum: 1 required: - size vendor_skus: maxItems: 20 type: array items: type: object properties: vendor: type: object properties: name: type: string minLength: 1 maxLength: 80 description: >- Free-text identifier for the supplier (e.g. 'Supplier Oy'). Trimmed; case-sensitive. Treated as opaque — there is no vendor catalog yet. required: - name additionalProperties: false description: >- Vendor reference. Today only `name` is carried; a future vendor-catalog ticket may add `id` without renaming this field. vendor_sku: type: string minLength: 1 maxLength: 64 description: >- Supplier's own product code as printed on the parcel / supplier order. Trimmed; case-sensitive. vendor_barcode: type: string minLength: 1 maxLength: 64 description: >- Supplier-provided barcode (when distinct from the merchant's own GTIN). Trimmed; case-sensitive. required: - vendor - vendor_sku description: >- Supplier-side identifiers for this product. Empty array means no supplier codes are recorded; omit to leave the existing array untouched (on writes) or to inherit from the product profile (on inbound-shipment line items). inventory: description: >- Current inventory snapshot for this product, owned by product-inventory-service. Null when no ProductInventoryDocument exists for the product yet (e.g. brand new product without any incoming articles). Omitted from the response when the listing was retrieved without joining inventory data. anyOf: - type: object properties: inventory: type: object properties: available: type: number minimum: 0 description: >- Units available for new reservations (i.e. on_shelf and not yet reserved). reserved: type: number minimum: 0 description: >- Units already reserved by orders (real or synthetic placeholders). demand: type: number minimum: 0 description: >- Synthetic demand placeholders covering shortage relative to current orders. in_stock: type: number minimum: 0 description: >- Physical units currently on the warehouse shelf. on_hold: type: number minimum: 0 description: >- Units held back from booking (e.g. quality holds or merchant freezes). inbound: type: number minimum: 0 description: >- Units in transit toward the warehouse via inbound shipments. required: - available - reserved - demand - in_stock - on_hold - inbound last_movement: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: >- ISO 8601 timestamp of the most recent inventory movement that updated this document. required: - inventory - last_movement - type: 'null' required: - sku - name required: - product responses: '201': description: Product created successfully. content: application/json: schema: type: object properties: product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the product. sku: type: string description: >- Merchant's own SKU. The SKU must be unique within the merchant and active products. gtin: description: >- GTIN (EAN / Barcode) of the product. This value is used to identify the product at the warehouse. type: string name: description: >- Name of the product in merchant's primary language. If you need translations, provide them in `name_translations` field. type: string name_translations: description: Name of the product in different languages. type: object properties: fi: type: string en: type: string sv: type: string ee: type: string additionalProperties: false status: default: active type: string enum: - active - deleted secondary_gtin: anyOf: - type: string - type: 'null' hs_code: anyOf: - type: string - type: 'null' description: HS code (Harmonized System code) of the product. fulfillment_by: default: logitrail title: Fulfillment route description: >- Default fulfillment route for this product. `logitrail` means Logitrail's warehouse picks and ships order lines for the product; `merchant` means the merchant fulfills the line themselves and Logitrail does not pick or ship it. Individual order lines may override this per line; when an order line omits the value, it falls back to this product-level default. Products that pre-date this field default to `logitrail`. type: string enum: - logitrail - merchant origin_country_code: anyOf: - type: string pattern: ^[A-Z]{2}$ - type: 'null' description: >- Country code (ISO 3166-1 alpha-2) of the product's origin. default_purchase_price: anyOf: - type: number - type: 'null' flags: type: array items: type: string weight_g: type: number minimum: 1 dimensions_mm: anyOf: - minItems: 3 maxItems: 3 type: array items: type: number minimum: 0 - type: 'null' description: >- Dimensions (in mm) of the product. Three dimensions are required. If dimensions are not known, use null or [0,0,0]. components: description: Product component definition. anyOf: - type: array items: type: object properties: product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: >- Logitrail's internal technical ID of the product. name: description: >- Name of the sub-product in its merchant's primary language. Embedded for display convenience; omitted if the sub-product cannot be resolved. type: string sku: description: >- SKU of the sub-product. Null when the sub-product has no SKU; omitted if the sub-product cannot be resolved. anyOf: - type: string - type: 'null' required: - id additionalProperties: false description: Reference to the sub-product. amount: type: integer minimum: 1 maximum: 9007199254740991 description: >- Amount of sub-products to be shipped when a main product is ordered. required: - product - amount additionalProperties: false - type: 'null' batch_packages: description: Batch package types of the product. type: array items: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: Internal Technical ID of the batch package. name: type: string description: Name/title of the batch package size: type: number description: How many items the batch package contains? merchant_remarks: type: string description: Remarks regarding the batch package gtin: type: string description: GTIN (Barcode) of the batch package. dimensions_mm: description: >- Dimensions (in mm) of the batch package. Three dimensions are required. minItems: 3 maxItems: 3 type: array items: type: number minimum: 1 weight_g: description: Weight (in grams) of the batch package. type: number minimum: 1 required: - size additionalProperties: false vendor_skus: maxItems: 20 type: array items: type: object properties: vendor: type: object properties: name: type: string minLength: 1 maxLength: 80 description: >- Free-text identifier for the supplier (e.g. 'Supplier Oy'). Trimmed; case-sensitive. Treated as opaque — there is no vendor catalog yet. required: - name additionalProperties: false description: >- Vendor reference. Today only `name` is carried; a future vendor-catalog ticket may add `id` without renaming this field. vendor_sku: type: string minLength: 1 maxLength: 64 description: >- Supplier's own product code as printed on the parcel / supplier order. Trimmed; case-sensitive. vendor_barcode: type: string minLength: 1 maxLength: 64 description: >- Supplier-provided barcode (when distinct from the merchant's own GTIN). Trimmed; case-sensitive. required: - vendor - vendor_sku additionalProperties: false description: >- Supplier-side identifiers for this product. Empty array means no supplier codes are recorded; omit to leave the existing array untouched (on writes) or to inherit from the product profile (on inbound-shipment line items). inventory: description: >- Current inventory snapshot for this product, owned by product-inventory-service. Null when no ProductInventoryDocument exists for the product yet (e.g. brand new product without any incoming articles). Omitted from the response when the listing was retrieved without joining inventory data. anyOf: - type: object properties: inventory: type: object properties: available: type: number minimum: 0 description: >- Units available for new reservations (i.e. on_shelf and not yet reserved). reserved: type: number minimum: 0 description: >- Units already reserved by orders (real or synthetic placeholders). demand: type: number minimum: 0 description: >- Synthetic demand placeholders covering shortage relative to current orders. in_stock: type: number minimum: 0 description: >- Physical units currently on the warehouse shelf. on_hold: type: number minimum: 0 description: >- Units held back from booking (e.g. quality holds or merchant freezes). inbound: type: number minimum: 0 description: >- Units in transit toward the warehouse via inbound shipments. required: - available - reserved - demand - in_stock - on_hold - inbound additionalProperties: false last_movement: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: >- ISO 8601 timestamp of the most recent inventory movement that updated this document. required: - inventory - last_movement additionalProperties: false - type: 'null' required: - id - sku - status - fulfillment_by additionalProperties: false required: - product additionalProperties: false '400': description: Validation error, see response body for details. content: application/json: schema: type: object properties: message: type: string description: A brief, human readable error message. error_code: type: string const: VALIDATION_ERROR description: Reason of the error. validation_errors: type: array items: {} description: An array of validation error details. required: - message - error_code - validation_errors additionalProperties: false /v1/products/{productId}: get: summary: Get Product description: Returns the product information. operationId: GetProduct security: - idp: - products:read parameters: - in: path name: productId schema: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the product. required: true description: Logitrail's internal technical ID of the product. - in: header name: x-logitrail-merchant-id schema: type: string minLength: 1 description: Logitrail's Merchant ID. required: true description: Logitrail's Merchant ID. responses: '200': description: Return the JSON presentation of the product. content: application/json: schema: type: object properties: product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the product. sku: type: string description: >- Merchant's own SKU. The SKU must be unique within the merchant and active products. gtin: description: >- GTIN (EAN / Barcode) of the product. This value is used to identify the product at the warehouse. type: string name: description: >- Name of the product in merchant's primary language. If you need translations, provide them in `name_translations` field. type: string name_translations: description: Name of the product in different languages. type: object properties: fi: type: string en: type: string sv: type: string ee: type: string additionalProperties: false status: default: active type: string enum: - active - deleted secondary_gtin: anyOf: - type: string - type: 'null' hs_code: anyOf: - type: string - type: 'null' description: HS code (Harmonized System code) of the product. fulfillment_by: default: logitrail title: Fulfillment route description: >- Default fulfillment route for this product. `logitrail` means Logitrail's warehouse picks and ships order lines for the product; `merchant` means the merchant fulfills the line themselves and Logitrail does not pick or ship it. Individual order lines may override this per line; when an order line omits the value, it falls back to this product-level default. Products that pre-date this field default to `logitrail`. type: string enum: - logitrail - merchant origin_country_code: anyOf: - type: string pattern: ^[A-Z]{2}$ - type: 'null' description: >- Country code (ISO 3166-1 alpha-2) of the product's origin. default_purchase_price: anyOf: - type: number - type: 'null' flags: type: array items: type: string weight_g: type: number minimum: 1 dimensions_mm: anyOf: - minItems: 3 maxItems: 3 type: array items: type: number minimum: 0 - type: 'null' description: >- Dimensions (in mm) of the product. Three dimensions are required. If dimensions are not known, use null or [0,0,0]. components: description: Product component definition. anyOf: - type: array items: type: object properties: product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: >- Logitrail's internal technical ID of the product. name: description: >- Name of the sub-product in its merchant's primary language. Embedded for display convenience; omitted if the sub-product cannot be resolved. type: string sku: description: >- SKU of the sub-product. Null when the sub-product has no SKU; omitted if the sub-product cannot be resolved. anyOf: - type: string - type: 'null' required: - id additionalProperties: false description: Reference to the sub-product. amount: type: integer minimum: 1 maximum: 9007199254740991 description: >- Amount of sub-products to be shipped when a main product is ordered. required: - product - amount additionalProperties: false - type: 'null' batch_packages: description: Batch package types of the product. type: array items: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: Internal Technical ID of the batch package. name: type: string description: Name/title of the batch package size: type: number description: How many items the batch package contains? merchant_remarks: type: string description: Remarks regarding the batch package gtin: type: string description: GTIN (Barcode) of the batch package. dimensions_mm: description: >- Dimensions (in mm) of the batch package. Three dimensions are required. minItems: 3 maxItems: 3 type: array items: type: number minimum: 1 weight_g: description: Weight (in grams) of the batch package. type: number minimum: 1 required: - size additionalProperties: false vendor_skus: maxItems: 20 type: array items: type: object properties: vendor: type: object properties: name: type: string minLength: 1 maxLength: 80 description: >- Free-text identifier for the supplier (e.g. 'Supplier Oy'). Trimmed; case-sensitive. Treated as opaque — there is no vendor catalog yet. required: - name additionalProperties: false description: >- Vendor reference. Today only `name` is carried; a future vendor-catalog ticket may add `id` without renaming this field. vendor_sku: type: string minLength: 1 maxLength: 64 description: >- Supplier's own product code as printed on the parcel / supplier order. Trimmed; case-sensitive. vendor_barcode: type: string minLength: 1 maxLength: 64 description: >- Supplier-provided barcode (when distinct from the merchant's own GTIN). Trimmed; case-sensitive. required: - vendor - vendor_sku additionalProperties: false description: >- Supplier-side identifiers for this product. Empty array means no supplier codes are recorded; omit to leave the existing array untouched (on writes) or to inherit from the product profile (on inbound-shipment line items). inventory: description: >- Current inventory snapshot for this product, owned by product-inventory-service. Null when no ProductInventoryDocument exists for the product yet (e.g. brand new product without any incoming articles). Omitted from the response when the listing was retrieved without joining inventory data. anyOf: - type: object properties: inventory: type: object properties: available: type: number minimum: 0 description: >- Units available for new reservations (i.e. on_shelf and not yet reserved). reserved: type: number minimum: 0 description: >- Units already reserved by orders (real or synthetic placeholders). demand: type: number minimum: 0 description: >- Synthetic demand placeholders covering shortage relative to current orders. in_stock: type: number minimum: 0 description: >- Physical units currently on the warehouse shelf. on_hold: type: number minimum: 0 description: >- Units held back from booking (e.g. quality holds or merchant freezes). inbound: type: number minimum: 0 description: >- Units in transit toward the warehouse via inbound shipments. required: - available - reserved - demand - in_stock - on_hold - inbound additionalProperties: false last_movement: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: >- ISO 8601 timestamp of the most recent inventory movement that updated this document. required: - inventory - last_movement additionalProperties: false - type: 'null' required: - id - sku - status - fulfillment_by additionalProperties: false required: - product additionalProperties: false '400': description: Validation error, see response body for details. content: application/json: schema: type: object properties: message: type: string description: A brief, human readable error message. error_code: type: string const: VALIDATION_ERROR description: Reason of the error. validation_errors: type: array items: {} description: An array of validation error details. required: - message - error_code - validation_errors additionalProperties: false '404': description: Product not found. content: application/json: schema: type: object properties: message: type: string description: A brief, human readable error message. error_code: type: string const: PRODUCT_NOT_FOUND required: - message - error_code additionalProperties: false post: summary: Update Product description: Updates an existing product. operationId: UpdateProduct security: - idp: - products:manage parameters: - in: path name: productId schema: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the product. required: true description: Logitrail's internal technical ID of the product. - in: header name: x-logitrail-merchant-id schema: type: string minLength: 1 description: Logitrail's Merchant ID. required: true description: Logitrail's Merchant ID. requestBody: content: application/json: schema: type: object properties: product: type: object properties: sku: type: string description: >- Merchant's own SKU. The SKU must be unique within the merchant and active products. gtin: description: >- GTIN (EAN / Barcode) of the product. This value is used to identify the product at the warehouse. type: string name: description: >- Name of the product in merchant's primary language. If you need translations, provide them in `name_translations` field. type: string name_translations: description: Name of the product in different languages. type: object properties: fi: type: string en: type: string sv: type: string ee: type: string status: default: active type: string enum: - active - deleted secondary_gtin: anyOf: - type: string - type: 'null' hs_code: anyOf: - type: string - type: 'null' description: HS code (Harmonized System code) of the product. fulfillment_by: default: logitrail title: Fulfillment route description: >- Default fulfillment route for this product. `logitrail` means Logitrail's warehouse picks and ships order lines for the product; `merchant` means the merchant fulfills the line themselves and Logitrail does not pick or ship it. Individual order lines may override this per line; when an order line omits the value, it falls back to this product-level default. Products that pre-date this field default to `logitrail`. type: string enum: - logitrail - merchant origin_country_code: anyOf: - type: string pattern: ^[A-Z]{2}$ - type: 'null' description: >- Country code (ISO 3166-1 alpha-2) of the product's origin. default_purchase_price: anyOf: - type: number - type: 'null' flags: type: array items: type: string weight_g: type: number minimum: 1 dimensions_mm: anyOf: - minItems: 3 maxItems: 3 type: array items: type: number minimum: 0 - type: 'null' description: >- Dimensions (in mm) of the product. Three dimensions are required. If dimensions are not known, use null or [0,0,0]. components: description: Product component definition. anyOf: - type: array items: type: object properties: product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: >- Logitrail's internal technical ID of the product. name: description: >- Name of the sub-product in its merchant's primary language. Embedded for display convenience; omitted if the sub-product cannot be resolved. type: string sku: description: >- SKU of the sub-product. Null when the sub-product has no SKU; omitted if the sub-product cannot be resolved. anyOf: - type: string - type: 'null' required: - id description: Reference to the sub-product. amount: type: integer minimum: 1 maximum: 9007199254740991 description: >- Amount of sub-products to be shipped when a main product is ordered. required: - product - amount - type: 'null' batch_packages: description: Batch package types of the product. type: array items: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: Internal Technical ID of the batch package. name: type: string description: Name/title of the batch package size: type: number description: How many items the batch package contains? merchant_remarks: type: string description: Remarks regarding the batch package gtin: type: string description: GTIN (Barcode) of the batch package. dimensions_mm: description: >- Dimensions (in mm) of the batch package. Three dimensions are required. minItems: 3 maxItems: 3 type: array items: type: number minimum: 1 weight_g: description: Weight (in grams) of the batch package. type: number minimum: 1 required: - size vendor_skus: maxItems: 20 type: array items: type: object properties: vendor: type: object properties: name: type: string minLength: 1 maxLength: 80 description: >- Free-text identifier for the supplier (e.g. 'Supplier Oy'). Trimmed; case-sensitive. Treated as opaque — there is no vendor catalog yet. required: - name additionalProperties: false description: >- Vendor reference. Today only `name` is carried; a future vendor-catalog ticket may add `id` without renaming this field. vendor_sku: type: string minLength: 1 maxLength: 64 description: >- Supplier's own product code as printed on the parcel / supplier order. Trimmed; case-sensitive. vendor_barcode: type: string minLength: 1 maxLength: 64 description: >- Supplier-provided barcode (when distinct from the merchant's own GTIN). Trimmed; case-sensitive. required: - vendor - vendor_sku description: >- Supplier-side identifiers for this product. Empty array means no supplier codes are recorded; omit to leave the existing array untouched (on writes) or to inherit from the product profile (on inbound-shipment line items). inventory: description: >- Current inventory snapshot for this product, owned by product-inventory-service. Null when no ProductInventoryDocument exists for the product yet (e.g. brand new product without any incoming articles). Omitted from the response when the listing was retrieved without joining inventory data. anyOf: - type: object properties: inventory: type: object properties: available: type: number minimum: 0 description: >- Units available for new reservations (i.e. on_shelf and not yet reserved). reserved: type: number minimum: 0 description: >- Units already reserved by orders (real or synthetic placeholders). demand: type: number minimum: 0 description: >- Synthetic demand placeholders covering shortage relative to current orders. in_stock: type: number minimum: 0 description: >- Physical units currently on the warehouse shelf. on_hold: type: number minimum: 0 description: >- Units held back from booking (e.g. quality holds or merchant freezes). inbound: type: number minimum: 0 description: >- Units in transit toward the warehouse via inbound shipments. required: - available - reserved - demand - in_stock - on_hold - inbound last_movement: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: >- ISO 8601 timestamp of the most recent inventory movement that updated this document. required: - inventory - last_movement - type: 'null' required: - product responses: '200': description: Product updated successfully. content: application/json: schema: type: object properties: product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the product. sku: type: string description: >- Merchant's own SKU. The SKU must be unique within the merchant and active products. gtin: description: >- GTIN (EAN / Barcode) of the product. This value is used to identify the product at the warehouse. type: string name: description: >- Name of the product in merchant's primary language. If you need translations, provide them in `name_translations` field. type: string name_translations: description: Name of the product in different languages. type: object properties: fi: type: string en: type: string sv: type: string ee: type: string additionalProperties: false status: default: active type: string enum: - active - deleted secondary_gtin: anyOf: - type: string - type: 'null' hs_code: anyOf: - type: string - type: 'null' description: HS code (Harmonized System code) of the product. fulfillment_by: default: logitrail title: Fulfillment route description: >- Default fulfillment route for this product. `logitrail` means Logitrail's warehouse picks and ships order lines for the product; `merchant` means the merchant fulfills the line themselves and Logitrail does not pick or ship it. Individual order lines may override this per line; when an order line omits the value, it falls back to this product-level default. Products that pre-date this field default to `logitrail`. type: string enum: - logitrail - merchant origin_country_code: anyOf: - type: string pattern: ^[A-Z]{2}$ - type: 'null' description: >- Country code (ISO 3166-1 alpha-2) of the product's origin. default_purchase_price: anyOf: - type: number - type: 'null' flags: type: array items: type: string weight_g: type: number minimum: 1 dimensions_mm: anyOf: - minItems: 3 maxItems: 3 type: array items: type: number minimum: 0 - type: 'null' description: >- Dimensions (in mm) of the product. Three dimensions are required. If dimensions are not known, use null or [0,0,0]. components: description: Product component definition. anyOf: - type: array items: type: object properties: product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: >- Logitrail's internal technical ID of the product. name: description: >- Name of the sub-product in its merchant's primary language. Embedded for display convenience; omitted if the sub-product cannot be resolved. type: string sku: description: >- SKU of the sub-product. Null when the sub-product has no SKU; omitted if the sub-product cannot be resolved. anyOf: - type: string - type: 'null' required: - id additionalProperties: false description: Reference to the sub-product. amount: type: integer minimum: 1 maximum: 9007199254740991 description: >- Amount of sub-products to be shipped when a main product is ordered. required: - product - amount additionalProperties: false - type: 'null' batch_packages: description: Batch package types of the product. type: array items: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: Internal Technical ID of the batch package. name: type: string description: Name/title of the batch package size: type: number description: How many items the batch package contains? merchant_remarks: type: string description: Remarks regarding the batch package gtin: type: string description: GTIN (Barcode) of the batch package. dimensions_mm: description: >- Dimensions (in mm) of the batch package. Three dimensions are required. minItems: 3 maxItems: 3 type: array items: type: number minimum: 1 weight_g: description: Weight (in grams) of the batch package. type: number minimum: 1 required: - size additionalProperties: false vendor_skus: maxItems: 20 type: array items: type: object properties: vendor: type: object properties: name: type: string minLength: 1 maxLength: 80 description: >- Free-text identifier for the supplier (e.g. 'Supplier Oy'). Trimmed; case-sensitive. Treated as opaque — there is no vendor catalog yet. required: - name additionalProperties: false description: >- Vendor reference. Today only `name` is carried; a future vendor-catalog ticket may add `id` without renaming this field. vendor_sku: type: string minLength: 1 maxLength: 64 description: >- Supplier's own product code as printed on the parcel / supplier order. Trimmed; case-sensitive. vendor_barcode: type: string minLength: 1 maxLength: 64 description: >- Supplier-provided barcode (when distinct from the merchant's own GTIN). Trimmed; case-sensitive. required: - vendor - vendor_sku additionalProperties: false description: >- Supplier-side identifiers for this product. Empty array means no supplier codes are recorded; omit to leave the existing array untouched (on writes) or to inherit from the product profile (on inbound-shipment line items). inventory: description: >- Current inventory snapshot for this product, owned by product-inventory-service. Null when no ProductInventoryDocument exists for the product yet (e.g. brand new product without any incoming articles). Omitted from the response when the listing was retrieved without joining inventory data. anyOf: - type: object properties: inventory: type: object properties: available: type: number minimum: 0 description: >- Units available for new reservations (i.e. on_shelf and not yet reserved). reserved: type: number minimum: 0 description: >- Units already reserved by orders (real or synthetic placeholders). demand: type: number minimum: 0 description: >- Synthetic demand placeholders covering shortage relative to current orders. in_stock: type: number minimum: 0 description: >- Physical units currently on the warehouse shelf. on_hold: type: number minimum: 0 description: >- Units held back from booking (e.g. quality holds or merchant freezes). inbound: type: number minimum: 0 description: >- Units in transit toward the warehouse via inbound shipments. required: - available - reserved - demand - in_stock - on_hold - inbound additionalProperties: false last_movement: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: >- ISO 8601 timestamp of the most recent inventory movement that updated this document. required: - inventory - last_movement additionalProperties: false - type: 'null' required: - id - sku - status - fulfillment_by additionalProperties: false required: - product additionalProperties: false '400': description: Validation error, see response body for details. content: application/json: schema: type: object properties: message: type: string description: A brief, human readable error message. error_code: type: string const: VALIDATION_ERROR description: Reason of the error. validation_errors: type: array items: {} description: An array of validation error details. required: - message - error_code - validation_errors additionalProperties: false '404': description: Product not found. content: application/json: schema: type: object properties: message: type: string description: A brief, human readable error message. error_code: type: string const: PRODUCT_NOT_FOUND required: - message - error_code additionalProperties: false components: securitySchemes: idp: type: oauth2 flows: clientCredentials: tokenUrl: >- https://idp.logitrail.com/realms/logitrail/protocol/openid-connect/token scopes: products:read: Read product data products:manage: Manage product data