openapi: 3.1.0 info: title: Product Management Service version: 2026-07-31.2721898287 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" tracking: title: Tracking requirements description: Per-unit tracking requirements enforced during warehouse handling for this product. type: object properties: requires_batch_number: default: false description: Whether a batch number must be recorded for every unit of this product during warehouse handling. type: boolean requires_best_before_date: default: false description: Whether a best-before date must be recorded for every unit of this product during warehouse handling. type: boolean required: - requires_batch_number - requires_best_before_date additionalProperties: false dangerous_goods: anyOf: - type: object properties: adr_class: type: string enum: - "3" - "7" - "8" - "9" - "1.1" - "1.2" - "1.3" - "1.4" - "1.5" - "1.6" - 1.1A - 1.1B - 1.1C - 1.1D - 1.1E - 1.1F - 1.1G - 1.1J - 1.1L - 1.2B - 1.2C - 1.2D - 1.2E - 1.2F - 1.2G - 1.2H - 1.2J - 1.2K - 1.2L - 1.3C - 1.3F - 1.3G - 1.3H - 1.3J - 1.3K - 1.3L - 1.4B - 1.4C - 1.4D - 1.4E - 1.4F - 1.4G - 1.4S - 1.5D - 1.6N - "2.1" - "2.2" - "2.3" - "4.1" - "4.2" - "4.3" - "5.1" - "5.2" - "6.1" - "6.2" title: ADR transport class description: ADR/VAK transport class and division of the product, for example `3` for a flammable liquid or `1.4S` for an explosive article. Class 1 values may be given with or without the compatibility group letter. Only class and division combinations that exist in ADR are accepted. hazard_code: type: string pattern: ^X?\d{2,3}$ title: Hazard identification number description: Hazard identification (Kemler) number shown on the upper half of the orange transport plate, for example `33` or `X423`. Two or three digits, optionally prefixed with `X` when the substance reacts dangerously with water. un_code: type: string pattern: ^\d{4}$ title: UN number description: Four-digit UN number identifying the substance, zero-padded, for example `1203` for petrol. Give the digits only — the `UN` prefix is added where the number is displayed. package_code: type: string pattern: ^[1-7][A-Z]{1,2}\d?$ title: UN packaging code description: UN packaging identification code of the packaging used, for example `1A1` for a steel drum with a non-removable head, `4G` for a fibreboard box. Starts with the packaging category digit, followed by the material letter(s) and an optional closure digit. Uppercase. package_type: type: string minLength: 1 title: Package type description: Type of package the product is shipped in, as required on the dangerous-goods documentation. description: type: string minLength: 1 description: Proper shipping name / description of the dangerous goods as it should appear on the transport document. technical_description: type: string minLength: 1 description: Technical description of the substance, used to supplement the proper shipping name where the classification requires it. required: - adr_class - hazard_code - un_code - package_code - package_type - description - technical_description additionalProperties: false - type: "null" title: Dangerous goods declaration description: ADR/VAK dangerous-goods classification of the product. Omitted for products that are not classified as dangerous goods. When supplied, every field of the declaration is required. Send `null` to remove an existing declaration. not_dangerous_goods_decision: title: Not-dangerous-goods declaration description: The merchant's explicit declaration that this product is not dangerous goods, recorded with who made it and when. Omitted when no such declaration has been made. Mutually exclusive with `dangerous_goods` — a product never carries both at once. type: object properties: reason: type: string title: Reason description: Merchant-supplied note explaining the declaration (max 30 characters). declared_at: description: When the declaration was made, or when its reason was last updated. type: string declared_by: anyOf: - type: string - type: "null" description: Identifier of whoever made the declaration. May be a merchant-panel user or, for machine-to-machine API callers, the calling API client rather than a named person. required: - reason - declared_at - declared_by additionalProperties: false 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" tracking: title: Tracking requirements description: Per-unit tracking requirements enforced during warehouse handling for this product. type: object properties: requires_batch_number: default: false description: Whether a batch number must be recorded for every unit of this product during warehouse handling. type: boolean requires_best_before_date: default: false description: Whether a best-before date must be recorded for every unit of this product during warehouse handling. type: boolean dangerous_goods: anyOf: - type: object properties: adr_class: type: string enum: - "3" - "7" - "8" - "9" - "1.1" - "1.2" - "1.3" - "1.4" - "1.5" - "1.6" - 1.1A - 1.1B - 1.1C - 1.1D - 1.1E - 1.1F - 1.1G - 1.1J - 1.1L - 1.2B - 1.2C - 1.2D - 1.2E - 1.2F - 1.2G - 1.2H - 1.2J - 1.2K - 1.2L - 1.3C - 1.3F - 1.3G - 1.3H - 1.3J - 1.3K - 1.3L - 1.4B - 1.4C - 1.4D - 1.4E - 1.4F - 1.4G - 1.4S - 1.5D - 1.6N - "2.1" - "2.2" - "2.3" - "4.1" - "4.2" - "4.3" - "5.1" - "5.2" - "6.1" - "6.2" title: ADR transport class description: ADR/VAK transport class and division of the product, for example `3` for a flammable liquid or `1.4S` for an explosive article. Class 1 values may be given with or without the compatibility group letter. Only class and division combinations that exist in ADR are accepted. hazard_code: type: string pattern: ^X?\d{2,3}$ title: Hazard identification number description: Hazard identification (Kemler) number shown on the upper half of the orange transport plate, for example `33` or `X423`. Two or three digits, optionally prefixed with `X` when the substance reacts dangerously with water. un_code: type: string pattern: ^\d{4}$ title: UN number description: Four-digit UN number identifying the substance, zero-padded, for example `1203` for petrol. Give the digits only — the `UN` prefix is added where the number is displayed. package_code: type: string pattern: ^[1-7][A-Z]{1,2}\d?$ title: UN packaging code description: UN packaging identification code of the packaging used, for example `1A1` for a steel drum with a non-removable head, `4G` for a fibreboard box. Starts with the packaging category digit, followed by the material letter(s) and an optional closure digit. Uppercase. package_type: type: string minLength: 1 title: Package type description: Type of package the product is shipped in, as required on the dangerous-goods documentation. description: type: string minLength: 1 description: Proper shipping name / description of the dangerous goods as it should appear on the transport document. technical_description: type: string minLength: 1 description: Technical description of the substance, used to supplement the proper shipping name where the classification requires it. required: - adr_class - hazard_code - un_code - package_code - package_type - description - technical_description - type: "null" title: Dangerous goods declaration description: ADR/VAK dangerous-goods classification of the product. Omitted for products that are not classified as dangerous goods. When supplied, every field of the declaration is required. Send `null` to remove an existing declaration. not_dangerous_goods_decision: title: Not-dangerous-goods declaration description: Declare that this product is not dangerous goods, or update the reason on an existing declaration. Send `null` to withdraw an existing declaration. Omit to leave any existing declaration untouched. The declaration timestamp and declaring identity are recorded automatically and cannot be set by the caller. anyOf: - type: object properties: reason: type: string minLength: 1 maxLength: 30 title: Reason description: Short note (max 30 characters) explaining why this product is not dangerous goods. required: - reason additionalProperties: false - 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" tracking: title: Tracking requirements description: Per-unit tracking requirements enforced during warehouse handling for this product. type: object properties: requires_batch_number: default: false description: Whether a batch number must be recorded for every unit of this product during warehouse handling. type: boolean requires_best_before_date: default: false description: Whether a best-before date must be recorded for every unit of this product during warehouse handling. type: boolean required: - requires_batch_number - requires_best_before_date additionalProperties: false dangerous_goods: anyOf: - type: object properties: adr_class: type: string enum: - "3" - "7" - "8" - "9" - "1.1" - "1.2" - "1.3" - "1.4" - "1.5" - "1.6" - 1.1A - 1.1B - 1.1C - 1.1D - 1.1E - 1.1F - 1.1G - 1.1J - 1.1L - 1.2B - 1.2C - 1.2D - 1.2E - 1.2F - 1.2G - 1.2H - 1.2J - 1.2K - 1.2L - 1.3C - 1.3F - 1.3G - 1.3H - 1.3J - 1.3K - 1.3L - 1.4B - 1.4C - 1.4D - 1.4E - 1.4F - 1.4G - 1.4S - 1.5D - 1.6N - "2.1" - "2.2" - "2.3" - "4.1" - "4.2" - "4.3" - "5.1" - "5.2" - "6.1" - "6.2" title: ADR transport class description: ADR/VAK transport class and division of the product, for example `3` for a flammable liquid or `1.4S` for an explosive article. Class 1 values may be given with or without the compatibility group letter. Only class and division combinations that exist in ADR are accepted. hazard_code: type: string pattern: ^X?\d{2,3}$ title: Hazard identification number description: Hazard identification (Kemler) number shown on the upper half of the orange transport plate, for example `33` or `X423`. Two or three digits, optionally prefixed with `X` when the substance reacts dangerously with water. un_code: type: string pattern: ^\d{4}$ title: UN number description: Four-digit UN number identifying the substance, zero-padded, for example `1203` for petrol. Give the digits only — the `UN` prefix is added where the number is displayed. package_code: type: string pattern: ^[1-7][A-Z]{1,2}\d?$ title: UN packaging code description: UN packaging identification code of the packaging used, for example `1A1` for a steel drum with a non-removable head, `4G` for a fibreboard box. Starts with the packaging category digit, followed by the material letter(s) and an optional closure digit. Uppercase. package_type: type: string minLength: 1 title: Package type description: Type of package the product is shipped in, as required on the dangerous-goods documentation. description: type: string minLength: 1 description: Proper shipping name / description of the dangerous goods as it should appear on the transport document. technical_description: type: string minLength: 1 description: Technical description of the substance, used to supplement the proper shipping name where the classification requires it. required: - adr_class - hazard_code - un_code - package_code - package_type - description - technical_description additionalProperties: false - type: "null" title: Dangerous goods declaration description: ADR/VAK dangerous-goods classification of the product. Omitted for products that are not classified as dangerous goods. When supplied, every field of the declaration is required. Send `null` to remove an existing declaration. not_dangerous_goods_decision: title: Not-dangerous-goods declaration description: The merchant's explicit declaration that this product is not dangerous goods, recorded with who made it and when. Omitted when no such declaration has been made. Mutually exclusive with `dangerous_goods` — a product never carries both at once. type: object properties: reason: type: string title: Reason description: Merchant-supplied note explaining the declaration (max 30 characters). declared_at: description: When the declaration was made, or when its reason was last updated. type: string declared_by: anyOf: - type: string - type: "null" description: Identifier of whoever made the declaration. May be a merchant-panel user or, for machine-to-machine API callers, the calling API client rather than a named person. required: - reason - declared_at - declared_by additionalProperties: false 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" tracking: title: Tracking requirements description: Per-unit tracking requirements enforced during warehouse handling for this product. type: object properties: requires_batch_number: default: false description: Whether a batch number must be recorded for every unit of this product during warehouse handling. type: boolean requires_best_before_date: default: false description: Whether a best-before date must be recorded for every unit of this product during warehouse handling. type: boolean required: - requires_batch_number - requires_best_before_date additionalProperties: false dangerous_goods: anyOf: - type: object properties: adr_class: type: string enum: - "3" - "7" - "8" - "9" - "1.1" - "1.2" - "1.3" - "1.4" - "1.5" - "1.6" - 1.1A - 1.1B - 1.1C - 1.1D - 1.1E - 1.1F - 1.1G - 1.1J - 1.1L - 1.2B - 1.2C - 1.2D - 1.2E - 1.2F - 1.2G - 1.2H - 1.2J - 1.2K - 1.2L - 1.3C - 1.3F - 1.3G - 1.3H - 1.3J - 1.3K - 1.3L - 1.4B - 1.4C - 1.4D - 1.4E - 1.4F - 1.4G - 1.4S - 1.5D - 1.6N - "2.1" - "2.2" - "2.3" - "4.1" - "4.2" - "4.3" - "5.1" - "5.2" - "6.1" - "6.2" title: ADR transport class description: ADR/VAK transport class and division of the product, for example `3` for a flammable liquid or `1.4S` for an explosive article. Class 1 values may be given with or without the compatibility group letter. Only class and division combinations that exist in ADR are accepted. hazard_code: type: string pattern: ^X?\d{2,3}$ title: Hazard identification number description: Hazard identification (Kemler) number shown on the upper half of the orange transport plate, for example `33` or `X423`. Two or three digits, optionally prefixed with `X` when the substance reacts dangerously with water. un_code: type: string pattern: ^\d{4}$ title: UN number description: Four-digit UN number identifying the substance, zero-padded, for example `1203` for petrol. Give the digits only — the `UN` prefix is added where the number is displayed. package_code: type: string pattern: ^[1-7][A-Z]{1,2}\d?$ title: UN packaging code description: UN packaging identification code of the packaging used, for example `1A1` for a steel drum with a non-removable head, `4G` for a fibreboard box. Starts with the packaging category digit, followed by the material letter(s) and an optional closure digit. Uppercase. package_type: type: string minLength: 1 title: Package type description: Type of package the product is shipped in, as required on the dangerous-goods documentation. description: type: string minLength: 1 description: Proper shipping name / description of the dangerous goods as it should appear on the transport document. technical_description: type: string minLength: 1 description: Technical description of the substance, used to supplement the proper shipping name where the classification requires it. required: - adr_class - hazard_code - un_code - package_code - package_type - description - technical_description additionalProperties: false - type: "null" title: Dangerous goods declaration description: ADR/VAK dangerous-goods classification of the product. Omitted for products that are not classified as dangerous goods. When supplied, every field of the declaration is required. Send `null` to remove an existing declaration. not_dangerous_goods_decision: title: Not-dangerous-goods declaration description: The merchant's explicit declaration that this product is not dangerous goods, recorded with who made it and when. Omitted when no such declaration has been made. Mutually exclusive with `dangerous_goods` — a product never carries both at once. type: object properties: reason: type: string title: Reason description: Merchant-supplied note explaining the declaration (max 30 characters). declared_at: description: When the declaration was made, or when its reason was last updated. type: string declared_by: anyOf: - type: string - type: "null" description: Identifier of whoever made the declaration. May be a merchant-panel user or, for machine-to-machine API callers, the calling API client rather than a named person. required: - reason - declared_at - declared_by additionalProperties: false 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" tracking: title: Tracking requirements description: Per-unit tracking requirements enforced during warehouse handling for this product. type: object properties: requires_batch_number: default: false description: Whether a batch number must be recorded for every unit of this product during warehouse handling. type: boolean requires_best_before_date: default: false description: Whether a best-before date must be recorded for every unit of this product during warehouse handling. type: boolean dangerous_goods: anyOf: - type: object properties: adr_class: type: string enum: - "3" - "7" - "8" - "9" - "1.1" - "1.2" - "1.3" - "1.4" - "1.5" - "1.6" - 1.1A - 1.1B - 1.1C - 1.1D - 1.1E - 1.1F - 1.1G - 1.1J - 1.1L - 1.2B - 1.2C - 1.2D - 1.2E - 1.2F - 1.2G - 1.2H - 1.2J - 1.2K - 1.2L - 1.3C - 1.3F - 1.3G - 1.3H - 1.3J - 1.3K - 1.3L - 1.4B - 1.4C - 1.4D - 1.4E - 1.4F - 1.4G - 1.4S - 1.5D - 1.6N - "2.1" - "2.2" - "2.3" - "4.1" - "4.2" - "4.3" - "5.1" - "5.2" - "6.1" - "6.2" title: ADR transport class description: ADR/VAK transport class and division of the product, for example `3` for a flammable liquid or `1.4S` for an explosive article. Class 1 values may be given with or without the compatibility group letter. Only class and division combinations that exist in ADR are accepted. hazard_code: type: string pattern: ^X?\d{2,3}$ title: Hazard identification number description: Hazard identification (Kemler) number shown on the upper half of the orange transport plate, for example `33` or `X423`. Two or three digits, optionally prefixed with `X` when the substance reacts dangerously with water. un_code: type: string pattern: ^\d{4}$ title: UN number description: Four-digit UN number identifying the substance, zero-padded, for example `1203` for petrol. Give the digits only — the `UN` prefix is added where the number is displayed. package_code: type: string pattern: ^[1-7][A-Z]{1,2}\d?$ title: UN packaging code description: UN packaging identification code of the packaging used, for example `1A1` for a steel drum with a non-removable head, `4G` for a fibreboard box. Starts with the packaging category digit, followed by the material letter(s) and an optional closure digit. Uppercase. package_type: type: string minLength: 1 title: Package type description: Type of package the product is shipped in, as required on the dangerous-goods documentation. description: type: string minLength: 1 description: Proper shipping name / description of the dangerous goods as it should appear on the transport document. technical_description: type: string minLength: 1 description: Technical description of the substance, used to supplement the proper shipping name where the classification requires it. required: - adr_class - hazard_code - un_code - package_code - package_type - description - technical_description - type: "null" title: Dangerous goods declaration description: ADR/VAK dangerous-goods classification of the product. Omitted for products that are not classified as dangerous goods. When supplied, every field of the declaration is required. Send `null` to remove an existing declaration. not_dangerous_goods_decision: title: Not-dangerous-goods declaration description: Declare that this product is not dangerous goods, or update the reason on an existing declaration. Send `null` to withdraw an existing declaration. Omit to leave any existing declaration untouched. The declaration timestamp and declaring identity are recorded automatically and cannot be set by the caller. anyOf: - type: object properties: reason: type: string minLength: 1 maxLength: 30 title: Reason description: Short note (max 30 characters) explaining why this product is not dangerous goods. required: - reason additionalProperties: false - 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" tracking: title: Tracking requirements description: Per-unit tracking requirements enforced during warehouse handling for this product. type: object properties: requires_batch_number: default: false description: Whether a batch number must be recorded for every unit of this product during warehouse handling. type: boolean requires_best_before_date: default: false description: Whether a best-before date must be recorded for every unit of this product during warehouse handling. type: boolean required: - requires_batch_number - requires_best_before_date additionalProperties: false dangerous_goods: anyOf: - type: object properties: adr_class: type: string enum: - "3" - "7" - "8" - "9" - "1.1" - "1.2" - "1.3" - "1.4" - "1.5" - "1.6" - 1.1A - 1.1B - 1.1C - 1.1D - 1.1E - 1.1F - 1.1G - 1.1J - 1.1L - 1.2B - 1.2C - 1.2D - 1.2E - 1.2F - 1.2G - 1.2H - 1.2J - 1.2K - 1.2L - 1.3C - 1.3F - 1.3G - 1.3H - 1.3J - 1.3K - 1.3L - 1.4B - 1.4C - 1.4D - 1.4E - 1.4F - 1.4G - 1.4S - 1.5D - 1.6N - "2.1" - "2.2" - "2.3" - "4.1" - "4.2" - "4.3" - "5.1" - "5.2" - "6.1" - "6.2" title: ADR transport class description: ADR/VAK transport class and division of the product, for example `3` for a flammable liquid or `1.4S` for an explosive article. Class 1 values may be given with or without the compatibility group letter. Only class and division combinations that exist in ADR are accepted. hazard_code: type: string pattern: ^X?\d{2,3}$ title: Hazard identification number description: Hazard identification (Kemler) number shown on the upper half of the orange transport plate, for example `33` or `X423`. Two or three digits, optionally prefixed with `X` when the substance reacts dangerously with water. un_code: type: string pattern: ^\d{4}$ title: UN number description: Four-digit UN number identifying the substance, zero-padded, for example `1203` for petrol. Give the digits only — the `UN` prefix is added where the number is displayed. package_code: type: string pattern: ^[1-7][A-Z]{1,2}\d?$ title: UN packaging code description: UN packaging identification code of the packaging used, for example `1A1` for a steel drum with a non-removable head, `4G` for a fibreboard box. Starts with the packaging category digit, followed by the material letter(s) and an optional closure digit. Uppercase. package_type: type: string minLength: 1 title: Package type description: Type of package the product is shipped in, as required on the dangerous-goods documentation. description: type: string minLength: 1 description: Proper shipping name / description of the dangerous goods as it should appear on the transport document. technical_description: type: string minLength: 1 description: Technical description of the substance, used to supplement the proper shipping name where the classification requires it. required: - adr_class - hazard_code - un_code - package_code - package_type - description - technical_description additionalProperties: false - type: "null" title: Dangerous goods declaration description: ADR/VAK dangerous-goods classification of the product. Omitted for products that are not classified as dangerous goods. When supplied, every field of the declaration is required. Send `null` to remove an existing declaration. not_dangerous_goods_decision: title: Not-dangerous-goods declaration description: The merchant's explicit declaration that this product is not dangerous goods, recorded with who made it and when. Omitted when no such declaration has been made. Mutually exclusive with `dangerous_goods` — a product never carries both at once. type: object properties: reason: type: string title: Reason description: Merchant-supplied note explaining the declaration (max 30 characters). declared_at: description: When the declaration was made, or when its reason was last updated. type: string declared_by: anyOf: - type: string - type: "null" description: Identifier of whoever made the declaration. May be a merchant-panel user or, for machine-to-machine API callers, the calling API client rather than a named person. required: - reason - declared_at - declared_by additionalProperties: false 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 /v1/products/{productId}/attachments: post: summary: Add Product Attachment description: Links an already-uploaded attachment to the product with a purpose and optional remarks. Returns the updated attachment list. operationId: CreateProductAttachment 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: attachment_id: type: string pattern: ^[a-f0-9]{24}$ description: Internal Attachment ID (24-hex MongoDB ObjectId). example: 5f9b1b9b9b9b9b9b9b9b9b9b purpose: type: string enum: - product_label - product_image - other description: Purpose of the attachment. Closed enum — one of `product_label`, `product_image`, `other`. remarks: description: Optional freeform comment stored alongside the link. example: Label template v2, approved 2025-01 type: string maxLength: 2000 required: - attachment_id - purpose responses: "200": description: Attachment linked; returns the updated attachment list. content: application/json: schema: type: object properties: attachments: type: array items: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Internal Attachment ID (24-hex MongoDB ObjectId). example: 5f9b1b9b9b9b9b9b9b9b9b9b purpose: type: string enum: - product_label - product_image - other description: Purpose of the attachment. Closed enum — one of `product_label`, `product_image`, `other`. remarks: description: Optional freeform comment stored alongside the link. type: string file_name: type: string description: Filename of the attachment. mime: type: string description: MIME type of the attachment. uploaded_at: 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: Timestamp when the attachment was uploaded to the system. is_archived: description: Archived attachments can no longer be downloaded. Attachments are archived after 1 year. type: boolean download_link: description: Download link of the attachment, if available. type: object properties: url: type: string description: Short-lived download URL for the attachment file (use to fetch or display it). valid_until: 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: Validity period of the download URL, after which it stops working (~5 minutes). required: - url - valid_until additionalProperties: false required: - id - purpose - file_name - mime - uploaded_at additionalProperties: false description: Attachment list for the product. required: - attachments 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 get: summary: List Product Attachments description: Returns the attachment list for a product, including short-lived download links. operationId: ListProductAttachments 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: Attachment list for the product. content: application/json: schema: type: object properties: attachments: type: array items: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Internal Attachment ID (24-hex MongoDB ObjectId). example: 5f9b1b9b9b9b9b9b9b9b9b9b purpose: type: string enum: - product_label - product_image - other description: Purpose of the attachment. Closed enum — one of `product_label`, `product_image`, `other`. remarks: description: Optional freeform comment stored alongside the link. type: string file_name: type: string description: Filename of the attachment. mime: type: string description: MIME type of the attachment. uploaded_at: 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: Timestamp when the attachment was uploaded to the system. is_archived: description: Archived attachments can no longer be downloaded. Attachments are archived after 1 year. type: boolean download_link: description: Download link of the attachment, if available. type: object properties: url: type: string description: Short-lived download URL for the attachment file (use to fetch or display it). valid_until: 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: Validity period of the download URL, after which it stops working (~5 minutes). required: - url - valid_until additionalProperties: false required: - id - purpose - file_name - mime - uploaded_at additionalProperties: false description: Attachment list for the product. required: - attachments 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